Thread state and helpers

Members

threadId: The thread runs go to. A new task with no thread starts a new thread per run. On an existing task, null or omitted keeps a stored one-thread mode and its thread; set threadMode: "new_thread" to leave it.

Constants

THREAD_SEARCH_MAX_LIMIT: The server's default and maximum orchestration.searchThreads limit.
threadId: Brand a trusted string without validation. Use for ids this process generated or already decoded.
OrchestrationV2ThreadBoundedSnapshot: A bounded cold open: full control-plane arrays with a recent window of timeline rows.
OrchestrationV2ThreadHistoryPage: An older timeline page for progressive history. Rows are chronological.
OrchestrationV2ThreadTranscript: The thread's visible timeline in one read, for handing a conversation to another reader.
OrchestrationV2PendingBackgroundTask: Provider-owned background work that can outlive the root turn. A kind this build does not know, or none, loads as background_task, as upstream does.
OrchestrationV2ProviderTurnTokenUsage: Live context usage reported by the provider mid-turn.
OrchestrationV2RuntimeRequest: An approval, question, or other request the provider raised and how it was answered.
TurnTokenUsage: Normalized main-agent usage for one turn. complete means the provider supplied full input and output totals; partial means every included count is valid but the full total is not known.
OrchestrationV2TurnItem: A turn item of any type, including a type this build does not know.
OrchestrationV2OlderSettledThreads: Snapshots that leave out older settled threads name the cut and count them per project. asOfSequence is the snapshot's own sequence: the counts are exact until a later change.
OrchestrationV2ThreadFamily: The active threads that share the requested thread's lineage.rootThreadId, in any run state. An unknown thread has an empty family; a deleted one still names its root.
OrchestrationV2OlderSettledCursor: Where a page of older settled threads starts: below this settle time, then after this id.
OrchestrationV2OlderSettledThreadsPage: Older settled threads below the cursor, newest settle first. A limit: 0 read fills counts instead, per project. A cursor without an id is strict.
ModelSelection: The historical { provider, model } shape still decodes; instanceId is the routing key.
ProviderUserInputAnswer: One question's answer: any JSON value, as the contracts allow. The provider adapters act on a single choice (a string), several choices (a string array), or Codex's { answers: string[] }.

Functions

The highest turn count the server can diff to: the largest app run ordinal of a ready checkpoint whose run completed. 0 when there is none.

export function latestDiffTurnCount(
  projection: Pick<OrchestrationV2ThreadProjection, "runs" | "checkpoints">,
): number;

applyThreadEvent()

Applies one event to the projection. Events for other threads and unknown events leave it unchanged.

export function applyThreadEvent(
  projection: Projection,
  event: OrchestrationV2DomainEvent,
): Projection;

pendingRequests()

Requests the provider raised that nobody has answered, oldest first.

export function pendingRequests(
  projection: Pick<OrchestrationV2ThreadProjection, "runtimeRequests" | "turnItems">,
): PendingRequest[];

runOutcome()

The outcome of a settled run; undefined while the run is not terminal.

export function runOutcome(
  projection: OrchestrationV2ThreadProjection,
  run: OrchestrationV2Run,
): TurnOutcome | undefined;

assistantMessageForRun()

The last assistant message of a run; a finished message is preferred over a streaming one.

export function assistantMessageForRun(
  projection: Pick<OrchestrationV2ThreadProjection, "messages">,
  runId: RunId,
): OrchestrationV2ConversationMessage | undefined;

activeRun()

The run an interrupt targets: the highest-ordinal run that is preparing, starting, running, or waiting. A queued run has not started, so it is not the active run.

export function activeRun(
  projection: Pick<OrchestrationV2ThreadProjection, "runs">,
): OrchestrationV2Run | undefined;

threadPhase()

Pure classification of a shell thread.

export function threadPhase(shell: OrchestrationV2ThreadShell): ThreadPhase;

watchThread()

Watch a thread with replay, reconnection and derived run events.

export function watchThread(
  rpc: ThreadWatchRpc,
  threadId: ThreadId,
  options: ThreadWatchOptions = {},
): AsyncIterable<ThreadWatchItem>;

isRunTerminalStatus()

Narrow a run status to a terminal status.

export function isRunTerminalStatus(status: string): status is OrchestrationV2RunTerminalStatus;

isRunActiveStatus()

Queued runs wait their turn; preparing, starting, running, and waiting runs hold the thread.

export function isRunActiveStatus(status: string): boolean;

isTurnItemOfType()

Narrow a known timeline item to the requested item type.

export function isTurnItemOfType<const T extends OrchestrationV2TurnItemType>(
  item: OrchestrationV2TurnItem,
  type: T,
): item is OrchestrationV2TurnItemOfType<T>;

threadId

The thread runs go to. A new task with no thread starts a new thread per run. On an existing task, null or omitted keeps a stored one-thread mode and its thread; set threadMode: "new_thread" to leave it.

Kind: global variable

THREAD_SEARCH_MAX_LIMIT

The server’s default and maximum orchestration.searchThreads limit.

Kind: global constant

threadId

Brand a trusted string without validation. Use for ids this process generated or already decoded.

Kind: global constant

OrchestrationV2ThreadBoundedSnapshot

A bounded cold open: full control-plane arrays with a recent window of timeline rows.

Kind: global constant

OrchestrationV2ThreadHistoryPage

An older timeline page for progressive history. Rows are chronological.

Kind: global constant

OrchestrationV2ThreadTranscript

The thread’s visible timeline in one read, for handing a conversation to another reader.

Kind: global constant

OrchestrationV2PendingBackgroundTask

Provider-owned background work that can outlive the root turn. A kind this build does not know, or none, loads as background_task, as upstream does.

Kind: global constant

OrchestrationV2ProviderTurnTokenUsage

Live context usage reported by the provider mid-turn.

Kind: global constant

OrchestrationV2RuntimeRequest

An approval, question, or other request the provider raised and how it was answered.

Kind: global constant

TurnTokenUsage

Normalized main-agent usage for one turn. complete means the provider supplied full input and output totals; partial means every included count is valid but the full total is not known.

Kind: global constant

OrchestrationV2TurnItem

A turn item of any type, including a type this build does not know.

Kind: global constant

OrchestrationV2OlderSettledThreads

Snapshots that leave out older settled threads name the cut and count them per project. asOfSequence is the snapshot’s own sequence: the counts are exact until a later change.

Kind: global constant

OrchestrationV2ThreadFamily

The active threads that share the requested thread’s lineage.rootThreadId, in any run state. An unknown thread has an empty family; a deleted one still names its root.

Kind: global constant

OrchestrationV2OlderSettledCursor

Where a page of older settled threads starts: below this settle time, then after this id.

Kind: global constant

OrchestrationV2OlderSettledThreadsPage

Older settled threads below the cursor, newest settle first. A limit: 0 read fills counts instead, per project. A cursor without an id is strict.

Kind: global constant

ModelSelection

The historical { provider, model } shape still decodes; instanceId is the routing key.

Kind: global constant

ProviderUserInputAnswer

One question’s answer: any JSON value, as the contracts allow. The provider adapters act on a single choice (a string), several choices (a string array), or Codex’s { answers: string[] }.

Kind: global constant

latestDiffTurnCount()

The highest turn count the server can diff to: the largest app run ordinal of a ready checkpoint whose run completed. 0 when there is none.

export function latestDiffTurnCount(
  projection: Pick<OrchestrationV2ThreadProjection, "runs" | "checkpoints">,
): number;

Kind: global function

applyThreadEvent()

Applies one event to the projection. Events for other threads and unknown events leave it unchanged.

export function applyThreadEvent(
  projection: Projection,
  event: OrchestrationV2DomainEvent,
): Projection;

Kind: global function

pendingRequests()

Requests the provider raised that nobody has answered, oldest first.

export function pendingRequests(
  projection: Pick<OrchestrationV2ThreadProjection, "runtimeRequests" | "turnItems">,
): PendingRequest[];

Kind: global function

runOutcome()

The outcome of a settled run; undefined while the run is not terminal.

export function runOutcome(
  projection: OrchestrationV2ThreadProjection,
  run: OrchestrationV2Run,
): TurnOutcome | undefined;

Kind: global function

assistantMessageForRun()

The last assistant message of a run; a finished message is preferred over a streaming one.

export function assistantMessageForRun(
  projection: Pick<OrchestrationV2ThreadProjection, "messages">,
  runId: RunId,
): OrchestrationV2ConversationMessage | undefined;

Kind: global function

activeRun()

The run an interrupt targets: the highest-ordinal run that is preparing, starting, running, or waiting. A queued run has not started, so it is not the active run.

export function activeRun(
  projection: Pick<OrchestrationV2ThreadProjection, "runs">,
): OrchestrationV2Run | undefined;

Kind: global function

threadPhase()

Pure classification of a shell thread.

export function threadPhase(shell: OrchestrationV2ThreadShell): ThreadPhase;

Kind: global function

watchThread()

Watch a thread with replay, reconnection and derived run events.

export function watchThread(
  rpc: ThreadWatchRpc,
  threadId: ThreadId,
  options: ThreadWatchOptions = {},
): AsyncIterable<ThreadWatchItem>;

Kind: global function

isRunTerminalStatus()

Narrow a run status to a terminal status.

export function isRunTerminalStatus(status: string): status is OrchestrationV2RunTerminalStatus;

Kind: global function

isRunActiveStatus()

Queued runs wait their turn; preparing, starting, running, and waiting runs hold the thread.

export function isRunActiveStatus(status: string): boolean;

Kind: global function

isTurnItemOfType()

Narrow a known timeline item to the requested item type.

export function isTurnItemOfType<const T extends OrchestrationV2TurnItemType>(
  item: OrchestrationV2TurnItem,
  type: T,
): item is OrchestrationV2TurnItemOfType<T>;

Kind: global function