Start hereRequest trace
Start heresource checked

One request, every boundary

Step through a user turn from a client command to an ordered SQL commit, provider-native execution, canonical event ingestion, checkpoint diff, and streamed UI state.

What this chapter resolves
  • Build a causal mental model before studying individual modules.
  • Distinguish the synchronous command acknowledgement from asynchronous provider work.
  • Locate durability, side effects, streaming, and checkpoint settlement.

The easiest way to understand T3 Code is to separate accepting intent from performing work. This first trace deliberately follows a turn on an existing thread with no new attachments or worktree bootstrap. That keeps one transactional write path visible; the multi-step bootstrap branch appears immediately afterwards.

Interactive trace

End-to-end request trace

Move through the ordered stages or play the trace once.

1 / 11

Step 1 of 11: Compose

Compose

The client builds a typed command

The local, hosted, or Electron web renderer—or mobile—creates a thread.turn.start command for an existing thread.

packages/contracts/src/orchestration.ts:847–864
  1. Compose · The client builds a typed command

    The local, hosted, or Electron web renderer—or mobile—creates a thread.turn.start command for an existing thread.

    packages/contracts/src/orchestration.ts:847–864
  2. Authorize · The WebSocket method checks scope

    The connection is authenticated, but each RPC method still has its own required OAuth scope. The socket is a transport, not blanket authority.

    apps/server/src/auth/RpcAuthorization.ts:18–139
  3. Normalize · The server canonicalizes external input

    Before dispatch, the RPC path normalizes timestamps, workspace roots, and attachments. Attachment bytes—when present—are written before the orchestration transaction.

    apps/server/src/orchestration/Normalizer.ts:46–178
  4. Queue · Dispatch enters one ordered queue

    OrchestrationEngine offers a CommandEnvelope to one queue. A single worker processes envelopes, which makes command decisions totally ordered.

    apps/server/src/orchestration/Layers/OrchestrationEngine.ts:331–368
  5. Decide · The I/O-free decision layer plans facts

    Before the SQL transaction, the decider checks invariants and returns one or more events. It performs no persistence, filesystem, or provider I/O, but it does read the clock and create UUIDs through Effect dependencies.

    apps/server/src/orchestration/decider.ts:18–173
  6. Commit · Event, projection, and receipt commit together

    Inside one SQL transaction the engine appends events, updates durable projections, and records the accepted idempotency receipt.

    apps/server/src/orchestration/Layers/OrchestrationEngine.ts:197–259
  7. React · A reactor performs the provider side effect

    ProviderCommandReactor observes committed turn intent, resolves the provider instance, starts or resumes a session, and sends the turn.

    apps/server/src/orchestration/Layers/ProviderCommandReactor.ts:1060–1174
  8. Adapt · The harness speaks its native protocol

    Codex app-server, Claude Agent SDK, ACP, or OpenCode produces native notifications. Its adapter maps them into the canonical runtime union.

    packages/contracts/src/providerRuntime.ts:1139–1193
  9. Ingest · Runtime facts become internal commands

    ProviderRuntimeIngestion turns content, activities, approvals, plans, usage, and lifecycle facts back into orchestration commands.

    apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts:1490–1874
  10. Sync · Committed state reaches clients

    An initial HTTP snapshot establishes authoritative state; the WebSocket subscription resumes after its sequence cursor and carries committed thread events.

    packages/client-runtime/src/state/threads.ts:534–645
  11. Checkpoint · An eligible Git workspace is captured in parallel

    CheckpointReactor independently sees turn.completed, attempts hidden-ref capture, then dispatches thread.turn.diff.complete. Only the engine persists that result.

    apps/server/src/orchestration/Layers/CheckpointReactor.ts:270–316

The command is deliberately rich

packages/contracts/src/orchestration.ts:847–864 ↗verbatim · typescript · 2a356b9b
const ClientThreadTurnStartCommand = Schema.Struct({
  type: Schema.Literal("thread.turn.start"),
  commandId: CommandId,
  threadId: ThreadId,
  message: Schema.Struct({
    messageId: MessageId,
    role: Schema.Literal("user"),
    text: Schema.String,
    attachments: Schema.Array(UploadChatAttachment),
  }),
  modelSelection: Schema.optional(ModelSelection),
  titleSeed: Schema.optional(TrimmedNonEmptyString),
  runtimeMode: RuntimeMode,
  interactionMode: ProviderInteractionMode,
  bootstrap: Schema.optional(ThreadTurnStartBootstrap),
  sourceProposedPlan: Schema.optional(SourceProposedPlanReference),
  createdAt: IsoDateTime,
});
Read this as: The boundary validates what every client must agree on. Provider-native options stay behind ModelSelection and the provider registry; lifecycle intent stays canonical.

The acknowledgement is not the answer

apps/server/src/orchestration/Layers/OrchestrationEngine.ts:331–368 ↗verbatim · typescript · 85e20350
  yield* projectionPipeline.bootstrap;
  commandReadModel = yield* projectionSnapshotQuery.getCommandReadModel();
 
  const worker = Effect.forever(Queue.take(commandQueue).pipe(Effect.flatMap(processEnvelope)));
  yield* Effect.forkScoped(worker);
  yield* Effect.logDebug("orchestration engine started").pipe(
    Effect.annotateLogs({ sequence: commandReadModel.snapshotSequence }),
  );
 
  const readEvents: OrchestrationEngineShape["readEvents"] = (fromSequenceExclusive, limit) =>
    eventStore.readFromSequence(fromSequenceExclusive, limit);
 
  const dispatch: OrchestrationEngineShape["dispatch"] = (command, options) =>
    Effect.gen(function* () {
      const result = yield* Deferred.make<{ sequence: number }, OrchestrationDispatchError>();
      yield* Queue.offer(commandQueue, {
        command,
        origin: options?.origin,
        result,
        startedAtMs: yield* Clock.currentTimeMillis,
      });
      return yield* Deferred.await(result);
    });
 
  return {
    readEvents,
    dispatch,
    // Each access creates a fresh PubSub subscription so that multiple
    // consumers (wsServer, ProviderRuntimeIngestion, CheckpointReactor, etc.)
    // each independently receive all domain events.
    get streamDomainEvents(): OrchestrationEngineShape["streamDomainEvents"] {
      return Stream.fromPubSub(eventPubSub);
    },
    // The command read model's snapshotSequence tracks the latest committed
    // event sequence (updated on the worker fiber). A plain property read is a
    // consistent, committed value — reassignment of `commandReadModel` is
    // atomic on the single-threaded event loop.
    latestSequence: Effect.sync(() => commandReadModel.snapshotSequence),
Read this as: Dispatch waits for the ordered command worker and the committed receipt. It does not wait for the coding agent's turn to finish. Multiple downstream consumers each receive their own event subscription.
packages/contracts/src/orchestration.ts:1580–1583 ↗verbatim · typescript · 151b83cd
export const DispatchResult = Schema.Struct({
  sequence: NonNegativeInt,
});
export type DispatchResult = typeof DispatchResult.Type;
Read this as: The client receives a successful DispatchResult containing the committed sequence—not the internal SQLite receipt row.

The turn reaches another milestone when its projected provider session is no longer running. Checkpoint state can arrive independently, and capture may be missing, skipped, or erroneous. A single “complete” boolean cannot faithfully represent all three phases.

The bootstrap fork is not one transaction

The richer client command can create a thread, create or select a worktree, run setup, and start the first turn. Those are several operations with compensating tombstone cleanup on failure. Only the two-to-four-event batch for an already existing thread—optional lifecycle resets, then message and turn-start—is decided and committed atomically.

The full causal loop

Figure 0.3 · Existing-thread turn sequencedashed arrows cross hot streams or parallel consumers
End-to-end T3 Code turn sequenceDiagram loading

Zoom with the controls, +/, or Ctrl/ + trackpad scroll. Enable Pan to drag, use two-finger scrolling, or use the arrow keys. 0 fits the diagram; Esc leaves Pan or expanded view.

End-to-end T3 Code turn sequence
Text equivalent

An existing-thread command is authorized, normalized, serialized, decided, and atomically stored with its accepted receipt. The client receives only the committed sequence. A hot post-commit event starts provider work through ProviderService and an adapter. Canonical provider events independently feed runtime ingestion and optional checkpoint capture. Both return durable results by sending internal commands to the same engine. HTTP snapshots and WebSocket live events synchronize the client.

Figure 0.3. This scoped trace omits attachment writes and multi-step bootstrap. Runtime ingestion and checkpoint capture independently subscribe to provider events; neither writes durable domain state except by dispatching back through the engine.

The diagram intentionally keeps the checkpoint worker in the reactor lane, but its last write does not bypass the domain kernel. Git capture is a side effect; the result becomes durable only after a new internal command passes through the engine.

T3
Source-locked editionRead against fa219001d · 23 Aug 2026
Book search

Find a concept, module, or source path

Type two or more characters.