Orchestration WebSocket methods reference

The orchestration methods are the central API for managing projects, threads, and AI agent sessions in DP Code. They use the orchestration.* method namespace. All methods follow the WebSocket protocol described in the overview.

orchestration.dispatchCommand

Dispatch a client orchestration command. This is the primary write path for all state-changing operations — creating projects and threads, starting turns, responding to approvals, reverting checkpoints, and more. The method name in the _tag field is orchestration.dispatchCommand. Returns: { sequence: number } — the event sequence number assigned to the resulting domain event.

Parameters

command

object

required

A tagged union. Set type to one of the command types listed below.

Show command types

project.create — Create a new project.

type

"project.create"

required

commandId

string

required

Unique command identifier.

projectId

string

required

ID to assign to the new project.

title

string

required

Display name for the project.

workspaceRoot

string

required

Absolute path to the project workspace directory.

kind

string

default:"\"project\""

Project kind. Defaults to "project".

defaultModelSelection

object | null

Default model selection for new threads in this project.

createWorkspaceRootIfMissing

boolean

default:"false"

Create the workspace root directory if it does not exist.

createdAt

string

required

ISO 8601 timestamp.

project.meta.update — Update project metadata.

type

"project.meta.update"

required

commandId

string

required

projectId

string

required

title

string

New display name.

workspaceRoot

string

New workspace root path.

defaultModelSelection

object | null

Updated model selection.

scripts

object[]

Updated project scripts list.

project.delete — Delete a project.

type

"project.delete"

required

commandId

string

required

projectId

string

required

thread.create — Create a new thread.

type

"thread.create"

required

commandId

string

required

threadId

string

required

projectId

string

required

title

string

required

modelSelection

object

required

Provider and model to use. See ModelSelection below.

runtimeMode

"approval-required" | "full-access"

required

interactionMode

"default" | "plan"

default:"\"default\""

envMode

"local" | "worktree"

default:"\"local\""

branch

string | null

required

worktreePath

string | null

required

createdAt

string

required

thread.turn.start — Send a user message and start a provider turn.

type

"thread.turn.start"

required

commandId

string

required

threadId

string

required

message

object

required

Show message fields

messageId

string

required

role

"user"

required

text

string

required

Message text. Max 120,000 characters.

attachments

object[]

Up to 8 image or assistant-selection attachments.

skills

object[]

Provider skill references.

mentions

object[]

Provider mention references.

runtimeMode

"approval-required" | "full-access"

required

interactionMode

"default" | "plan"

required

modelSelection

object

Override model for this turn.

dispatchMode

"queue" | "steer"

default:"\"queue\""

Use "steer" to urgently redirect a running turn.

assistantDeliveryMode

"buffered" | "streaming"

Override streaming behavior.

createdAt

string

required

thread.turn.interrupt — Interrupt a running turn.

type

"thread.turn.interrupt"

required

commandId

string

required

threadId

string

required

turnId

string

Specific turn to interrupt. Omit to interrupt the active turn.

createdAt

string

required

thread.approval.respond — Respond to a provider approval request.

type

"thread.approval.respond"

required

commandId

string

required

threadId

string

required

requestId

string

required

decision

"accept" | "acceptForSession" | "decline" | "cancel"

required

createdAt

string

required

thread.user-input.respond — Answer a provider user-input request.

type

"thread.user-input.respond"

required

commandId

string

required

threadId

string

required

requestId

string

required

answers

object

required

Map of question keys to string or string-array answers (or null).

createdAt

string

required

thread.checkpoint.revert — Revert the thread to a previous checkpoint.

type

"thread.checkpoint.revert"

required

commandId

string

required

threadId

string

required

turnCount

number

required

Number of turns to revert to.

createdAt

string

required

thread.session.stop — Stop the active provider session for a thread.

type

"thread.session.stop"

required

commandId

string

required

threadId

string

required

createdAt

string

required

thread.delete — Delete a thread.thread.archive / thread.unarchive — Archive or unarchive a thread.thread.meta.update — Update thread metadata (title, model selection, branch, worktree path, etc.).thread.runtime-mode.set — Set the runtime mode for a thread.thread.interaction-mode.set — Set the interaction mode (default or plan) for a thread.thread.message.edit-and-resend — Edit a user message and resend it as a new turn.thread.activity.append — Append a custom activity entry to the thread timeline.thread.handoff.create / thread.fork.create — Create a handoff or fork thread from an existing thread.

Response

sequence

number

required

The event sequence number produced by this command.

Example

Request
Response

{
  "id": "req-001",
  "body": {
    "_tag": "orchestration.dispatchCommand",
    "type": "thread.turn.start",
    "commandId": "cmd-abc123",
    "threadId": "thread-xyz",
    "message": {
      "messageId": "msg-001",
      "role": "user",
      "text": "Refactor the authentication module to use JWT.",
      "attachments": []
    },
    "runtimeMode": "full-access",
    "interactionMode": "default",
    "createdAt": "2025-05-01T12:00:00.000Z"
  }
}

{
  "id": "req-001",
  "result": {
    "sequence": 1042
  }
}

orchestration.getSnapshot

Return the full orchestration read model: all projects and all threads with complete message, activity, checkpoint, and session data. No parameters required.

Response

snapshotSequence

number

required

The event sequence number this snapshot was built from.

projects

object[]

required

Array of all projects.

Show project fields

string

required

title

string

required

workspaceRoot

string

required

kind

string

required

Either "project" or a custom kind.

defaultModelSelection

object | null

required

scripts

object[]

required

createdAt

string

required

updatedAt

string

required

deletedAt

string | null

required

threads

object[]

required

Array of all threads, each with full message and activity history.

updatedAt

string

required

ISO 8601 timestamp of the last update.

orchestration.getShellSnapshot

Return a lightweight snapshot containing only project and thread shell data (no messages, no activities, no checkpoints). Prefer this over getSnapshot when you only need to render the sidebar list.

Response

snapshotSequence

number

required

projects

object[]

required

Array of OrchestrationProjectShell objects (same fields as full project, minus deletedAt).

threads

object[]

required

Array of OrchestrationThreadShell objects — thread metadata plus latest turn and session status, no messages.

updatedAt

string

required

orchestration.subscribeShell

Streaming. Subscribe to incremental shell updates. The server emits a snapshot item first, then streams project-upserted, project-removed, thread-upserted, and thread-removed events as state changes. No parameters required.

Stream items

kind

string

required

One of: "snapshot", "project-upserted", "project-removed", "thread-upserted", "thread-removed".

sequence

number

Present on event items. Monotonically increasing sequence number.

snapshot

object

Present when kind is "snapshot". Contains the full OrchestrationShellSnapshot.

project

object

Present when kind is "project-upserted". Contains OrchestrationProjectShell.

projectId

string

Present when kind is "project-removed".

thread

object

Present when kind is "thread-upserted". Contains OrchestrationThreadShell.

threadId

string

Present when kind is "thread-removed".

orchestration.subscribeThread

Streaming. Subscribe to detailed events for a specific thread. The server emits a snapshot item first, then streams OrchestrationEvent items as they occur.

Parameters

threadId

string

required

ID of the thread to subscribe to.

Stream items

kind

"snapshot" | "event"

required

snapshot

object

Present when kind is "snapshot". Contains OrchestrationThreadDetailSnapshot with snapshotSequence and the full OrchestrationThread.

event

object

Present when kind is "event". Contains an OrchestrationEvent (see event types below).

OrchestrationEvent structure

Every event shares these base fields:

sequence

number

required

Monotonic sequence number.

eventId

string

required

type

string

required

Event type string (see list below).

aggregateKind

"project" | "thread"

required

aggregateId

string

required

Project or thread ID.

occurredAt

string

required

ISO 8601 timestamp.

commandId

string | null

required

correlationId

string | null

required

payload

object

required

Event-specific payload (varies by type).

Event types:

Type	Payload
`project.created`	Project creation fields
`project.meta-updated`	Changed project metadata fields
`project.deleted`	`{ projectId, deletedAt }`
`thread.created`	Thread creation fields
`thread.deleted`	`{ threadId, deletedAt }`
`thread.archived` / `thread.unarchived`	`{ threadId, archivedAt/unarchivedAt }`
`thread.meta-updated`	Changed thread metadata fields
`thread.runtime-mode-set`	`{ threadId, runtimeMode, updatedAt }`
`thread.interaction-mode-set`	`{ threadId, interactionMode, updatedAt }`
`thread.message-sent`	Full message fields
`thread.turn-queued` / `thread.turn-start-requested`	Turn request fields
`thread.turn-interrupt-requested`	`{ threadId, turnId?, createdAt }`
`thread.approval-response-requested`	`{ threadId, requestId, decision, createdAt }`
`thread.user-input-response-requested`	`{ threadId, requestId, answers, createdAt }`
`thread.checkpoint-revert-requested`	`{ threadId, turnCount, createdAt }`
`thread.reverted`	`{ threadId, turnCount }`
`thread.conversation-rollback-requested`	`{ threadId, messageId, numTurns, createdAt }`
`thread.conversation-rolled-back`	`{ threadId, messageId, numTurns, removedTurnIds? }`
`thread.session-set`	`{ threadId, session }`
`thread.proposed-plan-upserted`	`{ threadId, proposedPlan }`
`thread.turn-diff-completed`	Checkpoint summary fields
`thread.activity-appended`	`{ threadId, activity }`

orchestration.getTurnDiff

Retrieve the git diff for a range of turns in a thread.

Parameters

threadId

string

required

ID of the thread.

fromTurnCount

number

required

Start of the turn count range (inclusive). Must be less than or equal to toTurnCount.

toTurnCount

number

required

End of the turn count range (inclusive).

Response

threadId

string

required

fromTurnCount

number

required

toTurnCount

number

required

diff

string

required

Unified diff string.

orchestration.getFullThreadDiff

Retrieve the cumulative git diff for an entire thread up to a specified turn count.

Parameters

threadId

string

required

toTurnCount

number

required

The turn count ceiling for the diff.

Response

Same structure as getTurnDiff: { threadId, fromTurnCount, toTurnCount, diff }.

orchestration.importThread

Import a thread from an external source by mapping it to an existing internal thread.

Parameters

threadId

string

required

Internal thread ID to map to.

externalId

string

required

External identifier to import from.

Response

threadId

string

required

The internal thread ID that was created or updated.

orchestration.repairState

Repair inconsistent orchestration state by re-projecting from stored events. No parameters required. Returns the repaired full OrchestrationReadModel.

orchestration.replayEvents

Replay orchestration domain events from a given sequence number. Useful after a reconnect to catch up on events missed while offline.

Parameters

fromSequenceExclusive

number

required

Replay all events with a sequence number greater than this value.

Response

An array of OrchestrationEvent objects in sequence order.

Example

Request
Response

{
  "id": "req-005",
  "body": {
    "_tag": "orchestration.replayEvents",
    "fromSequenceExclusive": 980
  }
}

{
  "id": "req-005",
  "result": [
    {
      "sequence": 981,
      "eventId": "evt-aaa",
      "type": "thread.message-sent",
      "aggregateKind": "thread",
      "aggregateId": "thread-xyz",
      "occurredAt": "2025-05-01T12:01:00.000Z",
      "commandId": "cmd-abc123",
      "correlationId": "cmd-abc123",
      "metadata": {},
      "payload": { ... }
    }
  ]
}

ModelSelection

The ModelSelection object identifies the provider and model for a session. The provider field is a discriminant:

Provider	`provider` value	Options type
OpenAI Codex	`"codex"`	`CodexModelOptions`
Claude Code	`"claudeAgent"`	`ClaudeModelOptions`
Cursor	`"cursor"`	`CursorModelOptions`
Gemini	`"gemini"`	`GeminiModelOptions`
Grok	`"grok"`	`GrokModelOptions`
Kilo	`"kilo"`	`OpenCodeModelOptions`
OpenCode	`"opencode"`	`OpenCodeModelOptions`
Pi	`"pi"`	`PiModelOptions`

{
  "provider": "claudeAgent",
  "model": "claude-opus-4-5",
  "options": {}
}

WebSocket API

Providers

Self-Hosting

Orchestration WebSocket methods reference

orchestration.dispatchCommand

Parameters

Response

Example

orchestration.getSnapshot

Response

orchestration.getShellSnapshot

Response

orchestration.subscribeShell

Stream items

orchestration.subscribeThread

Parameters

Stream items

OrchestrationEvent structure

orchestration.getTurnDiff

Parameters

Response

orchestration.getFullThreadDiff

Parameters

Response

orchestration.importThread

Parameters

Response

orchestration.repairState

orchestration.replayEvents

Parameters

Response

Example

ModelSelection

Build docs developers (and LLMs) love

WebSocket API

Providers

Self-Hosting

Documentation Index

​orchestration.dispatchCommand

​Parameters

​Response

​Example

​orchestration.getSnapshot

​Response

​orchestration.getShellSnapshot

​Response

​orchestration.subscribeShell

​Stream items

​orchestration.subscribeThread

​Parameters

​Stream items

​OrchestrationEvent structure

​orchestration.getTurnDiff

​Parameters

​Response

​orchestration.getFullThreadDiff

​Parameters

​Response

​orchestration.importThread

​Parameters

​Response

​orchestration.repairState

​orchestration.replayEvents

​Parameters

​Response

​Example

​ModelSelection

Build docs developers (and LLMs) love

orchestration.dispatchCommand

Parameters

Response

Example

orchestration.getSnapshot

Response

orchestration.getShellSnapshot

Response

orchestration.subscribeShell

Stream items

orchestration.subscribeThread

Parameters

Stream items

OrchestrationEvent structure

orchestration.getTurnDiff

Parameters

Response

orchestration.getFullThreadDiff

Parameters

Response

orchestration.importThread

Parameters

Response

orchestration.repairState

orchestration.replayEvents

Parameters

Response

Example

ModelSelection