Skip to main content

​
Overview

The Orchestration API provides the core command/event architecture for T3 Code. It follows event sourcing principles where commands are dispatched, domain events are persisted, and read models are projected from the event stream.

​
Architecture

​
Available Methods

All orchestration methods use the orchestration.* namespace:
​
orchestration.getSnapshot
method
Retrieve the current read model snapshot
​
orchestration.dispatchCommand
method
Execute a command (create/update/delete operations)
​
orchestration.getTurnDiff
method
Get git diff for a specific turn range
​
orchestration.getFullThreadDiff
method
Get complete diff for all turns in a thread
​
orchestration.replayEvents
method
Replay events from a specific sequence number

​
getSnapshot

Retrieve the complete current state of all projects, threads, and sessions.

​
Request

{
  "id": "req-1",
  "body": {
    "_tag": "orchestration.getSnapshot"
  }
}

​
Response

​
snapshotSequence
number
required
Current event sequence number
​
projects
array
required
Array of project entities
​
threads
array
required
Array of thread entities with messages, activities, and checkpoints
​
updatedAt
string
required
Last snapshot update timestamp (ISO 8601)

​
Example Response

{
  "id": "req-1",
  "result": {
    "snapshotSequence": 42,
    "projects": [
      {
        "id": "proj-123",
        "title": "my-app",
        "workspaceRoot": "/home/user/projects/my-app",
        "defaultModel": "gpt-5-codex",
        "scripts": [],
        "createdAt": "2026-03-07T10:00:00.000Z",
        "updatedAt": "2026-03-07T10:00:00.000Z",
        "deletedAt": null
      }
    ],
    "threads": [
      {
        "id": "thread-456",
        "projectId": "proj-123",
        "title": "New thread",
        "model": "gpt-5-codex",
        "runtimeMode": "full-access",
        "interactionMode": "default",
        "messages": [],
        "activities": [],
        "checkpoints": [],
        "session": null,
        "createdAt": "2026-03-07T10:05:00.000Z",
        "updatedAt": "2026-03-07T10:05:00.000Z",
        "deletedAt": null
      }
    ],
    "updatedAt": "2026-03-07T12:00:00.000Z"
  }
}

​
dispatchCommand

Execute a command to modify system state. Commands are validated, processed, and result in domain events.

​
Request

​
command
ClientOrchestrationCommand
required
Command object with type discriminator
{
  "id": "req-2",
  "body": {
    "_tag": "orchestration.dispatchCommand",
    "command": {
      "type": "project.create",
      "commandId": "cmd-789",
      "projectId": "proj-new",
      "title": "New Project",
      "workspaceRoot": "/home/user/new-project",
      "defaultModel": "gpt-5-codex",
      "createdAt": "2026-03-07T12:00:00.000Z"
    }
  }
}

​
Response

​
sequence
number
required
Event sequence number after command processing
{
  "id": "req-2",
  "result": {
    "sequence": 43
  }
}

​
Available Commands

See Commands for the complete list of command types.

​
getTurnDiff

Retrieve the git diff for a specific range of turns within a thread.

​
Request

​
threadId
string
required
Thread identifier
​
fromTurnCount
number
required
Starting turn number (inclusive)
​
toTurnCount
number
required
Ending turn number (inclusive). Must be ≥ fromTurnCount.
{
  "id": "req-3",
  "body": {
    "_tag": "orchestration.getTurnDiff",
    "threadId": "thread-456",
    "fromTurnCount": 0,
    "toTurnCount": 2
  }
}

​
Response

​
threadId
string
required
Thread identifier
​
fromTurnCount
number
required
Starting turn number
​
toTurnCount
number
required
Ending turn number
​
diff
string
required
Unified diff format showing file changes
{
  "id": "req-3",
  "result": {
    "threadId": "thread-456",
    "fromTurnCount": 0,
    "toTurnCount": 2,
    "diff": "diff --git a/src/index.ts b/src/index.ts\nindex 1234567..abcdefg 100644\n--- a/src/index.ts\n+++ b/src/index.ts\n@@ -1,3 +1,4 @@\n+import express from 'express';\n console.log('Hello');\n"
  }
}

​
getFullThreadDiff

Retrieve the complete diff for all turns in a thread from turn 0 to the specified turn.

​
Request

​
threadId
string
required
Thread identifier
​
toTurnCount
number
required
Final turn number (inclusive)
{
  "id": "req-4",
  "body": {
    "_tag": "orchestration.getFullThreadDiff",
    "threadId": "thread-456",
    "toTurnCount": 5
  }
}

​
Response

Same structure as getTurnDiff, with fromTurnCount always set to 0.

​
replayEvents

Replay all events after a specific sequence number. Useful for rebuilding read models or catching up after reconnection.

​
Request

​
fromSequenceExclusive
number
required
Start replaying after this sequence number (exclusive)
{
  "id": "req-5",
  "body": {
    "_tag": "orchestration.replayEvents",
    "fromSequenceExclusive": 42
  }
}

​
Response

​
result
array
required
Array of OrchestrationEvent objects in sequence order
{
  "id": "req-5",
  "result": [
    {
      "sequence": 43,
      "eventId": "evt-123",
      "aggregateKind": "thread",
      "aggregateId": "thread-456",
      "type": "thread.created",
      "occurredAt": "2026-03-07T12:00:00.000Z",
      "commandId": "cmd-789",
      "causationEventId": null,
      "correlationId": "cmd-789",
      "metadata": {},
      "payload": {
        "threadId": "thread-456",
        "projectId": "proj-123",
        "title": "New thread",
        "model": "gpt-5-codex",
        "runtimeMode": "full-access",
        "interactionMode": "default",
        "createdAt": "2026-03-07T12:00:00.000Z",
        "updatedAt": "2026-03-07T12:00:00.000Z"
      }
    }
  ]
}

​
Source Code References

Orchestration implementation:
  • Schemas: packages/contracts/src/orchestration.ts
  • Engine: apps/server/src/orchestration/Services/OrchestrationEngine.ts
  • Read Model: apps/server/src/orchestration/Services/ProjectionSnapshotQuery.ts
  • Reactor: apps/server/src/orchestration/Services/OrchestrationReactor.ts
  • WebSocket Router: apps/server/src/wsServer.ts:684-714

​
Domain Model

The orchestration domain is split into two aggregate roots:

Project Aggregate

Manages project metadata, workspace root, default model, and scripts

Thread Aggregate

Manages conversation threads, messages, activities, checkpoints, and provider sessions

​
Event Sourcing Flow

  1. Client dispatches command via dispatchCommand
  2. Server validates command against schema
  3. Command handler processes business logic
  4. Domain events are persisted to event store
  5. Read model is updated via projection
  6. Events are broadcast to all connected clients via push
  7. Client updates UI based on events

​
Next Steps

Commands

Explore all available command types

Events

Learn about domain event types

WebSocket Protocol

Understand the transport layer

Build docs developers (and LLMs) love

Get started for freeTalk to us