> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pingdotgg/t3code/llms.txt
> Use this file to discover all available pages before exploring further.

# Orchestration Schemas

> Effect schemas for orchestration events, commands, and domain models

## Overview

The orchestration schemas define the core domain model for T3 Code's event-sourced architecture. These schemas handle projects, threads, messages, turns, and provider sessions using Effect Schema for validation and type safety.

## Core Domain Models

### OrchestrationProject

Represents a workspace project with configuration and scripts.

<ResponseField name="id" type="ProjectId" required>
  Unique project identifier
</ResponseField>

<ResponseField name="title" type="string" required>
  Project display name
</ResponseField>

<ResponseField name="workspaceRoot" type="string" required>
  Absolute path to the workspace root directory
</ResponseField>

<ResponseField name="defaultModel" type="string | null" required>
  Default AI model for new threads in this project
</ResponseField>

<ResponseField name="scripts" type="ProjectScript[]" required>
  Configured project scripts (build, test, lint, etc.)
</ResponseField>

<ResponseField name="createdAt" type="IsoDateTime" required>
  Project creation timestamp
</ResponseField>

<ResponseField name="updatedAt" type="IsoDateTime" required>
  Last update timestamp
</ResponseField>

<ResponseField name="deletedAt" type="IsoDateTime | null" required>
  Soft deletion timestamp
</ResponseField>

### ProjectScript

Configurable script that can be run in the project context.

<ResponseField name="id" type="string" required>
  Script identifier
</ResponseField>

<ResponseField name="name" type="string" required>
  Display name
</ResponseField>

<ResponseField name="command" type="string" required>
  Shell command to execute
</ResponseField>

<ResponseField name="icon" type="ProjectScriptIcon" required>
  Icon identifier: `"play"` | `"test"` | `"lint"` | `"configure"` | `"build"` | `"debug"`
</ResponseField>

<ResponseField name="runOnWorktreeCreate" type="boolean" required>
  Whether to automatically run when creating a new worktree
</ResponseField>

### OrchestrationThread

A conversation thread with an AI provider.

<ResponseField name="id" type="ThreadId" required>
  Unique thread identifier
</ResponseField>

<ResponseField name="projectId" type="ProjectId" required>
  Parent project ID
</ResponseField>

<ResponseField name="title" type="string" required>
  Thread title
</ResponseField>

<ResponseField name="model" type="string" required>
  AI model slug for this thread
</ResponseField>

<ResponseField name="runtimeMode" type="RuntimeMode" required>
  Runtime mode: `"approval-required"` | `"full-access"`
</ResponseField>

<ResponseField name="interactionMode" type="ProviderInteractionMode" required>
  Interaction mode: `"default"` | `"plan"`
</ResponseField>

<ResponseField name="branch" type="string | null" required>
  Git branch associated with this thread
</ResponseField>

<ResponseField name="worktreePath" type="string | null" required>
  Git worktree path if using worktrees
</ResponseField>

<ResponseField name="latestTurn" type="OrchestrationLatestTurn | null" required>
  Current or most recent turn state
</ResponseField>

<ResponseField name="messages" type="OrchestrationMessage[]" required>
  All messages in the thread
</ResponseField>

<ResponseField name="proposedPlans" type="OrchestrationProposedPlan[]" required>
  Plans proposed by the assistant (when in plan mode)
</ResponseField>

<ResponseField name="activities" type="OrchestrationThreadActivity[]" required>
  Activity log (tool calls, approvals, errors)
</ResponseField>

<ResponseField name="checkpoints" type="OrchestrationCheckpointSummary[]" required>
  Git checkpoints for rollback
</ResponseField>

<ResponseField name="session" type="OrchestrationSession | null" required>
  Active provider session
</ResponseField>

<ResponseField name="createdAt" type="IsoDateTime" required>
  Thread creation timestamp
</ResponseField>

<ResponseField name="updatedAt" type="IsoDateTime" required>
  Last update timestamp
</ResponseField>

<ResponseField name="deletedAt" type="IsoDateTime | null" required>
  Soft deletion timestamp
</ResponseField>

### OrchestrationMessage

A single message in a thread conversation.

<ResponseField name="id" type="MessageId" required>
  Unique message identifier
</ResponseField>

<ResponseField name="role" type="OrchestrationMessageRole" required>
  Message role: `"user"` | `"assistant"` | `"system"`
</ResponseField>

<ResponseField name="text" type="string" required>
  Message content
</ResponseField>

<ResponseField name="attachments" type="ChatAttachment[]" optional>
  Attached images or files
</ResponseField>

<ResponseField name="turnId" type="TurnId | null" required>
  Associated turn ID
</ResponseField>

<ResponseField name="streaming" type="boolean" required>
  Whether the message is currently streaming
</ResponseField>

<ResponseField name="createdAt" type="IsoDateTime" required>
  Message creation timestamp
</ResponseField>

<ResponseField name="updatedAt" type="IsoDateTime" required>
  Last update timestamp
</ResponseField>

### OrchestrationSession

Active provider session state.

<ResponseField name="threadId" type="ThreadId" required>
  Associated thread ID
</ResponseField>

<ResponseField name="status" type="OrchestrationSessionStatus" required>
  Session status: `"idle"` | `"starting"` | `"running"` | `"ready"` | `"interrupted"` | `"stopped"` | `"error"`
</ResponseField>

<ResponseField name="providerName" type="string | null" required>
  Provider name (e.g., "codex")
</ResponseField>

<ResponseField name="runtimeMode" type="RuntimeMode" required>
  Current runtime mode
</ResponseField>

<ResponseField name="activeTurnId" type="TurnId | null" required>
  Currently active turn ID
</ResponseField>

<ResponseField name="lastError" type="string | null" required>
  Last error message if status is "error"
</ResponseField>

<ResponseField name="updatedAt" type="IsoDateTime" required>
  Last update timestamp
</ResponseField>

## Commands

### Thread Commands

Commands for managing threads and turns.

#### ThreadTurnStartCommand

Starts a new turn in a thread.

```typescript theme={null}
export const ThreadTurnStartCommand = 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(ChatAttachment),
  }),
  provider: Schema.optional(ProviderKind),
  model: Schema.optional(TrimmedNonEmptyString),
  serviceTier: Schema.optional(Schema.NullOr(ProviderServiceTier)),
  modelOptions: Schema.optional(ProviderModelOptions),
  assistantDeliveryMode: Schema.optional(AssistantDeliveryMode),
  runtimeMode: RuntimeMode,
  interactionMode: ProviderInteractionMode,
  createdAt: IsoDateTime,
});
```

<ParamField path="type" type="'thread.turn.start'" required>
  Command type discriminator
</ParamField>

<ParamField path="commandId" type="CommandId" required>
  Unique command identifier
</ParamField>

<ParamField path="threadId" type="ThreadId" required>
  Target thread ID
</ParamField>

<ParamField path="message.messageId" type="MessageId" required>
  ID for the user message
</ParamField>

<ParamField path="message.text" type="string" required>
  User input text (max 120,000 characters)
</ParamField>

<ParamField path="message.attachments" type="ChatAttachment[]" required>
  Attached images (max 8 attachments)
</ParamField>

<ParamField path="model" type="string" optional>
  Override model for this turn
</ParamField>

<ParamField path="serviceTier" type="'fast' | 'flex' | null" optional>
  Service tier for the turn
</ParamField>

<ParamField path="modelOptions" type="ProviderModelOptions" optional>
  Model-specific options
</ParamField>

<ParamField path="assistantDeliveryMode" type="'buffered' | 'streaming'" optional>
  How to deliver assistant responses
</ParamField>

<ParamField path="runtimeMode" type="RuntimeMode" required>
  Runtime mode for this turn
</ParamField>

<ParamField path="interactionMode" type="ProviderInteractionMode" required>
  Interaction mode for this turn
</ParamField>

#### ThreadTurnInterruptCommand

Interrupts an active turn.

```typescript theme={null}
const ThreadTurnInterruptCommand = Schema.Struct({
  type: Schema.Literal("thread.turn.interrupt"),
  commandId: CommandId,
  threadId: ThreadId,
  turnId: Schema.optional(TurnId),
  createdAt: IsoDateTime,
});
```

#### ThreadApprovalRespondCommand

Responds to an approval request from the provider.

```typescript theme={null}
const ThreadApprovalRespondCommand = Schema.Struct({
  type: Schema.Literal("thread.approval.respond"),
  commandId: CommandId,
  threadId: ThreadId,
  requestId: ApprovalRequestId,
  decision: ProviderApprovalDecision,
  createdAt: IsoDateTime,
});
```

<ParamField path="decision" type="ProviderApprovalDecision" required>
  Approval decision: `"accept"` | `"acceptForSession"` | `"decline"` | `"cancel"`
</ParamField>

### Project Commands

#### ProjectCreateCommand

Creates a new project.

```typescript theme={null}
export const ProjectCreateCommand = Schema.Struct({
  type: Schema.Literal("project.create"),
  commandId: CommandId,
  projectId: ProjectId,
  title: TrimmedNonEmptyString,
  workspaceRoot: TrimmedNonEmptyString,
  defaultModel: Schema.optional(TrimmedNonEmptyString),
  createdAt: IsoDateTime,
});
```

## Events

### Event Types

All orchestration events:

```typescript theme={null}
export const OrchestrationEventType = Schema.Literals([
  "project.created",
  "project.meta-updated",
  "project.deleted",
  "thread.created",
  "thread.deleted",
  "thread.meta-updated",
  "thread.runtime-mode-set",
  "thread.interaction-mode-set",
  "thread.message-sent",
  "thread.turn-start-requested",
  "thread.turn-interrupt-requested",
  "thread.approval-response-requested",
  "thread.user-input-response-requested",
  "thread.checkpoint-revert-requested",
  "thread.reverted",
  "thread.session-stop-requested",
  "thread.session-set",
  "thread.proposed-plan-upserted",
  "thread.turn-diff-completed",
  "thread.activity-appended",
]);
```

### Event Structure

All events share these base fields:

<ResponseField name="sequence" type="number" required>
  Global event sequence number
</ResponseField>

<ResponseField name="eventId" type="EventId" required>
  Unique event identifier
</ResponseField>

<ResponseField name="aggregateKind" type="'project' | 'thread'" required>
  Type of aggregate this event belongs to
</ResponseField>

<ResponseField name="aggregateId" type="ProjectId | ThreadId" required>
  Aggregate root ID
</ResponseField>

<ResponseField name="occurredAt" type="IsoDateTime" required>
  Event occurrence timestamp
</ResponseField>

<ResponseField name="commandId" type="CommandId | null" required>
  Command that caused this event
</ResponseField>

<ResponseField name="causationEventId" type="EventId | null" required>
  Event that caused this event
</ResponseField>

<ResponseField name="correlationId" type="CommandId | null" required>
  Correlation ID for event chain (equals commandId)
</ResponseField>

<ResponseField name="metadata" type="OrchestrationEventMetadata" required>
  Additional metadata (provider turn ID, adapter key, etc.)
</ResponseField>

### Event Payloads

#### ThreadCreatedPayload

```typescript theme={null}
export const ThreadCreatedPayload = Schema.Struct({
  threadId: ThreadId,
  projectId: ProjectId,
  title: TrimmedNonEmptyString,
  model: TrimmedNonEmptyString,
  runtimeMode: RuntimeMode,
  interactionMode: ProviderInteractionMode,
  branch: Schema.NullOr(TrimmedNonEmptyString),
  worktreePath: Schema.NullOr(TrimmedNonEmptyString),
  createdAt: IsoDateTime,
  updatedAt: IsoDateTime,
});
```

#### ThreadMessageSentPayload

```typescript theme={null}
export const ThreadMessageSentPayload = Schema.Struct({
  threadId: ThreadId,
  messageId: MessageId,
  role: OrchestrationMessageRole,
  text: Schema.String,
  attachments: Schema.optional(Schema.Array(ChatAttachment)),
  turnId: Schema.NullOr(TurnId),
  streaming: Schema.Boolean,
  createdAt: IsoDateTime,
  updatedAt: IsoDateTime,
});
```

## Read Model

### OrchestrationReadModel

The current state projection of all projects and threads.

```typescript theme={null}
export const OrchestrationReadModel = Schema.Struct({
  snapshotSequence: NonNegativeInt,
  projects: Schema.Array(OrchestrationProject),
  threads: Schema.Array(OrchestrationThread),
  updatedAt: IsoDateTime,
});
export type OrchestrationReadModel = typeof OrchestrationReadModel.Type;
```

## RPC Schemas

### WebSocket Methods

```typescript theme={null}
export const ORCHESTRATION_WS_METHODS = {
  getSnapshot: "orchestration.getSnapshot",
  dispatchCommand: "orchestration.dispatchCommand",
  getTurnDiff: "orchestration.getTurnDiff",
  getFullThreadDiff: "orchestration.getFullThreadDiff",
  replayEvents: "orchestration.replayEvents",
} as const;
```

### Method Schemas

```typescript theme={null}
export const OrchestrationRpcSchemas = {
  getSnapshot: {
    input: OrchestrationGetSnapshotInput,
    output: OrchestrationGetSnapshotResult,
  },
  dispatchCommand: {
    input: ClientOrchestrationCommand,
    output: DispatchResult,
  },
  getTurnDiff: {
    input: OrchestrationGetTurnDiffInput,
    output: OrchestrationGetTurnDiffResult,
  },
  getFullThreadDiff: {
    input: OrchestrationGetFullThreadDiffInput,
    output: OrchestrationGetFullThreadDiffResult,
  },
  replayEvents: {
    input: OrchestrationReplayEventsInput,
    output: OrchestrationReplayEventsResult,
  },
} as const;
```

## Usage Examples

### Dispatching a Command

```typescript theme={null}
import { ThreadTurnStartCommand } from "@t3tools/contracts";
import { nanoid } from "nanoid";

const command: typeof ThreadTurnStartCommand.Type = {
  type: "thread.turn.start",
  commandId: nanoid(),
  threadId: "thread_abc123",
  message: {
    messageId: nanoid(),
    role: "user",
    text: "Help me implement a new feature",
    attachments: [],
  },
  runtimeMode: "full-access",
  interactionMode: "default",
  createdAt: new Date().toISOString(),
};

// Validate with Effect Schema
import { Schema } from "effect";
const validated = Schema.decodeUnknownSync(ThreadTurnStartCommand)(command);
```

### Reading the Snapshot

```typescript theme={null}
import { OrchestrationReadModel } from "@t3tools/contracts";

const snapshot: typeof OrchestrationReadModel.Type = await rpc.call(
  "orchestration.getSnapshot",
  {}
);

const activeThreads = snapshot.threads.filter(
  (t) => t.session?.status === "running"
);
```

### Handling Events

```typescript theme={null}
import { OrchestrationEvent } from "@t3tools/contracts";

function handleEvent(event: typeof OrchestrationEvent.Type) {
  switch (event.type) {
    case "thread.message-sent":
      console.log(`Message: ${event.payload.text}`);
      break;
    case "thread.activity-appended":
      console.log(`Activity: ${event.payload.activity.summary}`);
      break;
  }
}
```

## Constants

### Validation Limits

```typescript theme={null}
export const PROVIDER_SEND_TURN_MAX_INPUT_CHARS = 120_000;
export const PROVIDER_SEND_TURN_MAX_ATTACHMENTS = 8;
export const PROVIDER_SEND_TURN_MAX_IMAGE_BYTES = 10 * 1024 * 1024; // 10MB
```

### Default Values

```typescript theme={null}
export const DEFAULT_PROVIDER_KIND: ProviderKind = "codex";
export const DEFAULT_RUNTIME_MODE: RuntimeMode = "full-access";
export const DEFAULT_PROVIDER_INTERACTION_MODE: ProviderInteractionMode = "default";
```

## Related Types

See also:

* [Base Schemas](/api/contracts/types#base-schemas) - Primitive type definitions
* [Model Contracts](/api/contracts/models) - Model configuration types
* [Provider Types](/api/contracts/types#provider-types) - Provider session types