Skip to content

feat(contract): add Driver Contract v2 and refresh all dependencies#43

Draft
Yevanchen wants to merge 2 commits into
mainfrom
feat/contract-v2-dep-update
Draft

feat(contract): add Driver Contract v2 and refresh all dependencies#43
Yevanchen wants to merge 2 commits into
mainfrom
feat/contract-v2-dep-update

Conversation

@Yevanchen

Copy link
Copy Markdown
Collaborator

Summary

Two-part change, delivered as a draft while the kernel/backends/host migration is planned:

1. Dependency refresh (all deps to latest)

package from to
typescript 6.0.3 7.0.2
@types/node 25.8 26.1.1
vite-plus 0.1.24 0.2.4
@anthropic-ai/sdk 0.100.1 0.111.0
@anthropic-ai/claude-agent-sdk 0.3.205 0.3.207
@modelcontextprotocol/client 2.0.0-beta.2 2.0.0-beta.3
@orpc/client 1.14.6 1.14.7

Migration fallout was minimal: two type assertions dropped for the stricter no-unnecessary-type-assertion lint. bun@1.3.14 remains the latest stable. Full CI flow (frozen-lockfile install → lint → tc → test → build → artifact) verified on a clean standalone checkout.

2. Driver Contract v2 (agent-driver/contract, spec in docs/contract.md)

A clean, deliberately incompatible redesign of the agent-session event/data contract, synthesized from the latest Codex app-server protocol (thread/turn/item model) and ACP v2 (protocolVersion: 2), cross-checked against Claude Agent SDK, AG-UI, Vercel AI SDK streams, and A2A. The old 2026-05-26 runtime-event generation stays wired until the kernel, the three backends, and the host migrate onto v2 via protocol adapters (follow-ups).

Highlights over the old contract:

  • 17 typed event kinds + open x_* extension rule replace 107 declared / ~20 emitted untyped kinds; zod v4 schemas are the single source of truth (previously hand-rolled validators duplicated driver/host).
  • One item lifecycle for everythingitem.started/delta/updated/completed with authoritative completed snapshots (Codex semantics), covering message, reasoning (indexed summary/raw parts), plan, command, file_change, tool_call, and extension items. Ends the parallel message.*-family vs item.* split and the tool.call.updated field-sniffing mega-event.
  • MCP/ACP-aligned content blocks end to end (text/image/audio/resource_link/resource) — no more "[image: …]" string flattening; multimodal turn.start/turn.steer input.
  • Interaction plane: option-based permission requests with typed command/file-change/tool subjects (unknown outcome ≠ approval), plus input.requested/resolved for Codex request_user_input / MCP elicitation.
  • Transport performance is contract-level: emitter-assigned per-session seq, delta-only best_effort classification, normative adjacent-coalescing rules (coalesceSessionEvents) and a reference buffer (createSessionEventBuffer) so any boundary can batch/merge high-frequency deltas safely.
  • Granularity conformance suite maps representative native Codex v2 / ACP v2 payloads onto the contract with zero field loss (tests/contract-granularity.test.ts).

Testing

  • bun run lint / bun run tc / bun test tests (256 pass) / bun run build — all green, including on a clean git archive checkout with bun install --frozen-lockfile (the CI flow).
  • New contract suite: 63 tests across events/items/commands/buffer/granularity.

Follow-ups (out of scope here)

  • Migrate kernel + ACP/Claude/OpenAI backends to emit Contract v2; adapt the oRPC wire and hello capability negotiation.
  • Host-side (mosoo repo pkgs/runtime-events) migration off the parallel schema copy.
  • Retire src/runtime-events / src/runtime-command once both edges are on v2.

Bump TypeScript to 7.0.2, @types/node to 26, vite-plus to 0.2.4,
@anthropic-ai/sdk to 0.111.0, Claude Agent SDK to 0.3.207, MCP client
to 2.0.0-beta.3, and @orpc/client to 1.14.7. Drop two type assertions
that the stricter no-unnecessary-type-assertion lint now rejects.
…coalescing

Design and implement the v2 agent-session contract per docs/contract.md,
synthesized from the Codex app-server thread/turn/item protocol and Agent
Client Protocol v2: one item lifecycle (started/delta/updated/completed
with authoritative snapshots), MCP-aligned content blocks, an option-based
permission and user-input interaction plane, multimodal turn commands, an
emitter-assigned per-session seq, and contract-level adjacent coalescing
plus a reference buffer for high-frequency delta transport. Ships as the
new agent-driver/contract subpath with zod schemas as the single source of
truth and a granularity conformance suite; the 2026-05-26 runtime-event
generation stays wired until kernel, backends, and host migrate.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant