The ProviderAdapter contract

ProviderAdapter is not T3 Code’s domain model and it is not a transport protocol. It is the server-side boundary that gives five very different native runtimes one callable shape and one event vocabulary.

That placement explains both its power and its limits:

• orchestration decides and durably records product intent;
• ProviderService resolves a configured instance and owns durable session bindings, recovery policy, MCP preparation, logging, and event fan-in;
• one ProviderAdapter owns native process/session behavior;
• ProviderRuntimeIngestion translates the adapter’s hot canonical events back into internal orchestration commands.

The adapter therefore normalizes how to talk to a harness. It does not make the harness itself durable, and it does not prove every provider supports every event in the canonical union.

The contract is deliberately smaller than the product

export interface ProviderAdapterShape<TError> {
  /**
   * Provider kind implemented by this adapter.
   */
  readonly provider: ProviderDriverKind;
  readonly capabilities: ProviderAdapterCapabilities;
 
  /**
   * Start a provider-backed session.
   */
  readonly startSession: (
    input: ProviderSessionStartInput,
  ) => Effect.Effect<ProviderSession, TError>;
 
  /**
   * Send a turn to an active provider session.
   */
  readonly sendTurn: (
    input: ProviderSendTurnInput,
  ) => Effect.Effect<ProviderTurnStartResult, TError>;
 
  /**
   * Interrupt an active turn.
   */
  readonly interruptTurn: (threadId: ThreadId, turnId?: TurnId) => Effect.Effect<void, TError>;

  /**
   * Respond to an interactive approval request.
   */
  readonly respondToRequest: (
    threadId: ThreadId,
    requestId: ApprovalRequestId,
    decision: ProviderApprovalDecision,
  ) => Effect.Effect<void, TError>;
 
  /**
   * Respond to a structured user-input request.
   */
  readonly respondToUserInput: (
    threadId: ThreadId,
    requestId: ApprovalRequestId,
    answers: ProviderUserInputAnswers,
  ) => Effect.Effect<void, TError>;
 
  /**
   * Stop one provider session.
   */
  readonly stopSession: (threadId: ThreadId) => Effect.Effect<void, TError>;

The complete shape has fourteen required members and one optional operation. Reading them by responsibility is more useful than reading them in file order.

sendTurn returns ProviderTurnStartResult: a T3 threadId, a turnId, and an optional opaque resume cursor. It does not return generated text. Text, tool activity, plan changes, requests, usage, completion, and failures arrive later on streamEvents.

A session uses T3 identity and opaque native continuation

The public ProviderSession is centered on threadId. It also carries the driver and, during the ongoing migration, an optional configured instance id, plus status, runtime mode, working directory, model, active turn, timestamps, last error, and an opaque resumeCursor. Runtime routing promotes legacy persisted bindings before it requires that instance identity.

The opaque cursor is an important design choice. Codex can store app-server resume material, Claude can store SDK/transcript position, ACP adapters can store an ACP session id, and OpenCode can store a versioned ses_… token without forcing their native identities into one false universal schema. ProviderService can persist the envelope while the owning adapter remains responsible for decoding it.

Capability negotiation is only one field today

The declared capability object contains one property: sessionModelSwitch: "in-session" | "unsupported". It tells the provider reactor whether a model change may stay within an existing native session or requires a restart.

That is the entire SPI capability surface at this revision. Approvals, structured input, plans, tasks, skills, usage telemetry, rollback, steering, and native modes must not be inferred from this one object. They are concrete adapter behaviors, sometimes expressed through typed failure, sometimes absent, and sometimes implemented through provider-specific extensions.

Canonical events are a grammar, not a checklist

  /**
   * Stop all sessions owned by this adapter.
   */
  readonly stopAll: () => Effect.Effect<void, TError>;
 
  /**
   * Canonical runtime event stream emitted by this adapter.
   */
  readonly streamEvents: Stream.Stream<ProviderRuntimeEvent>;

Every runtime event shares an id, driver kind, T3 thread, timestamp, optional instance/turn/item/request ids, provider references, and optional raw provenance. The union then supplies typed payloads for session, thread, turn, content, item, approval, structured input, task, hook, tool, authentication, account, MCP, model, configuration, file, warning, and error events.

That breadth provides a stable target vocabulary for adapters and consumers. It is not proof of feature parity. For example, the schema can represent token usage for any provider, while Chapter 20 verifies that only Codex and Claude emit that event at this revision.

flowchart LR
  I[(durable turn intent)] -->|hot domain event| R[ProviderCommandReactor]
  R --> S[ProviderService]
  S -->|thread → instance| A[ProviderAdapter]
  A --> N[native runtime]
  N -.native messages.-> A
  A -.ProviderRuntimeEvent.-> S
  S -.correlate + log + PubSub.-> G[Runtime ingestion]
  G -->|internal command| E[orchestration engine]
  E --> D[(durable events + projections)]
  A -->|start result only| S
  S -->|start result only| R

ProviderService owns the cross-provider policy

The adapter’s contract intentionally omits several product concerns that ProviderService supplies:

• decode and validate public inputs;
• resolve threadId → persisted binding → providerInstanceId → live adapter;
• prepare and revoke the T3 MCP credential for the session;
• adopt an already-live adapter session or resume from the stored cursor;
• persist the latest provider binding, runtime mode, model selection, cwd, status, and resume data;
• stop stale sessions for the same thread on other live instances;
• correlate every runtime event with the adapter instance that emitted it;
• fan all instance streams into one provider-runtime PubSub;
• collect metrics and analytics around the operation.

This is why an adapter should not perform cross-provider orchestration. It knows how its native runtime behaves. The service knows how that runtime participates in the product.

The error taxonomy crosses three boundaries

One naming wrinkle matters: the live adapter facade currently reports a missing or unavailable instance as ProviderUnsupportedError, even though a separate ProviderInstanceNotFoundError type exists. The book follows executed paths, not just exported class names.

Walk the contract boundary

Choose an operation and advance its round trip. The moving token stops at the immediate return boundary before continuing along the independent runtime-event lane. Try sending while a turn is already running: the lab deliberately refuses to label that generic call “steer,” because only each concrete adapter can settle that meaning.

What the tests establish—and do not

The canonical runtime schema has decoder tests. ProviderService tests route sessions, recover persisted bindings, validate instance identity, and merge runtime events in order. Every concrete adapter has behavior tests for its own transport and normalization.

There is no repository-wide executable conformance suite that feeds the same full feature script to all five adapters and proves semantic equivalence. That absence is appropriate to surface: one interface gives the product a stable integration point, while Chapters 16–19 retain provider differences instead of hiding them.