Orchestration API

Command and query interface for managing projects, threads, and AI sessions

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

Show Project structure

id · string

Unique project identifier

title · string

Project display name

workspaceRoot · string

Absolute path to project directory

defaultModel · string | null

Default AI model (e.g., “gpt-5-codex”)

scripts · array

Project scripts (build, test, lint, etc.)

createdAt · string

ISO 8601 timestamp

updatedAt · string

ISO 8601 timestamp

deletedAt · string | null

ISO 8601 timestamp (null if not deleted)

threads · array · required

Array of thread entities with messages, activities, and checkpoints

Show Thread structure

id · string

Unique thread identifier

projectId · string

Parent project ID

title · string

Thread display name

model · string

AI model in use

runtimeMode · 'approval-required' | 'full-access'

Permission level for the provider

interactionMode · 'default' | 'plan'

Provider interaction style

messages · array

Conversation messages (user/assistant/system)

activities · array

Thread activity log (tool calls, approvals, errors)

checkpoints · array

Git checkpoint summaries for each turn

session · object | null

Active provider session state

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