Orca is the place for working with a fleet of agents (e.g. Grok Bot, Claude Code). Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.
TypeScript adeagent-ideai-agentsautomationbotclaude-codecodexghosttygrok-bothermes-agentmobile-appmuseopenclawopencodeorchestrationpiruntimeterminalworktreesyc-backed
// Normalize explicit hook/OSC status; a guarded interrupt fallback supplies done when the cancellation hook is missing.
import type { ProgramStatusFacet } from './program-status/facet'
import type { AgentProviderSessionMetadata } from './agent-session-resume'
import type { AgentMainAgentStatus } from './main-agent-status'
import type { AgentStateHistoryEntry } from './agent-state-history'
import { isAgentTurnOutcome } from './agent-turn-outcome'
import type { OrchestrationFleetAttention } from './orchestration-fleet-attention'
import type { AgentStatusRowFacets } from './agent-status-observation'
import type { AgentChildWorkView } from './agent-status-child-work-view'
import type { TerminalAgent } from './terminal-agent'
import {
AGENT_MODEL_MAX_LENGTH,
AGENT_STATUS_TOOL_INPUT_MAX_LENGTH,
AGENT_TYPE_MAX_LENGTH,
normalizeInteractivePromptField,
normalizeOptionalField,
normalizeOptionalMultilineField,
normalizePromptField,
normalizeTurnCompletedAtField
} from './agent-status-field-normalization'
import { assertJsonTextStructureWithinLimits } from './json-text-structure-limit'
import {
normalizeAgentSubagentsField,
type AgentSubagentSnapshot
} from './agent-status-subagent-snapshot'
export {
AGENT_MODEL_MAX_LENGTH,
AGENT_STATUS_MAX_FIELD_LENGTH,
AGENT_STATUS_TOOL_INPUT_MAX_LENGTH,
AGENT_TYPE_MAX_LENGTH
} from './agent-status-field-normalization'
export {
agentSubagentsEqual,
type AgentSubagentSnapshot,
type AgentSubagentState
} from './agent-status-subagent-snapshot'
export type {
AgentStatusCacheIdentity,
AgentStatusClearIpcPayload,
AgentStatusIpcPayload,
MigrationUnsupportedPtyEntry,
RefusedPaneResume
} from './agent-status-ipc-payload'
export { mainAgentStatusEqual, type AgentMainAgentStatus } from './main-agent-status'
export { AGENT_STATE_HISTORY_MAX, type AgentStateHistoryEntry } from './agent-state-history'
export const AGENT_STATUS_STATES = ['working', 'blocked', 'waiting', 'done'] as const
export type AgentStatusState = (typeof AGENT_STATUS_STATES)[number]
export type AgentWorkingMode = 'monitoring'
// Accept custom nonempty agent names; the well-known TerminalAgent/unknown union is only a pattern-matching convenience.
export type WellKnownAgentType = TerminalAgent | 'unknown'
export type AgentType = WellKnownAgentType | (string & {})
export type AgentStatusOrchestrationContext = {
taskId: string
dispatchId: string
/** Runtime-authoritative lifecycle state. Hook-only contexts may omit it. */
dispatchStatus?: 'pending' | 'dispatched' | 'completed' | 'failed' | 'circuit_broken'
taskTitle?: string
displayName?: string
parentTerminalHandle?: string
parentPaneKey?: string
coordinatorHandle?: string
orchestrationRunId?: string
/** Durable orchestration categories combined with the current push-fed status observation. */
attention?: OrchestrationFleetAttention
}
export type AgentStatusEntry = {
/** Renderer-local status-feed confirmation for children; absent on hook rows. */
subagentObservation?: 'live' | 'unverifiable'
state: AgentStatusState
/** Ongoing work that does not require foreground agent execution. Only valid while working. */
workingMode?: AgentWorkingMode
/** Cache the latest prompt across tool events until a new prompt/reset; empty means unknown. */
prompt: string
/** Timestamp (ms) of the last status update. */
updatedAt: number
/** Original evidence clock; delivery updatedAt restamps reconnect replays. Local/older-host rows omit this and use updatedAt for freshness. */
evidenceObservedAt?: number
/** True only while a host-held structured session is represented by its live status feed. */
structuredHostOwned?: true
/** State entry time stays fixed while tool/prompt pings advance updatedAt. */
stateStartedAt: number
/** `updatedAt` of the write that switched into `state`; see AgentStateHistoryEntry.observedAt. */
stateObservedAt?: number
/** Host-stamped lead turn opening; older hosts/writers without turn clocks fall back to stateStartedAt. */
turnStartedAt?: number
/** The host's turn-end stamp; see `AgentStatusIpcPayload.turnEndedAt`. */
turnEndedAt?: number
/** How the host identified that end; see `TurnEndDisposition`. */
turnEndDisposition?: TurnEndDisposition
agentType?: AgentType
/** Provider model currently used by this session. */
model?: string
/** Command installed by the running OMP extension; absent on older hosts. */
modelSwitchCommand?: 'orca-model'
/** Composite key: `${tabId}:${leafId}` where leafId is a stable UUID layout leaf. */
paneKey: string
/** Runtime terminal handle for matching retained parent rows when the parent
* pane key cannot be re-derived after terminal teardown. */
terminalHandle?: string
/** Retain host workspace attribution for orchestration workers reporting before their renderer tab exists. */
worktreeId?: string
/** Accepted transport authority for this live row; null means local. */
connectionId?: string | null
/** Tab attribution from the hook IPC payload, when available. */
tabId?: string
terminalTitle?: string
/** Rolling log of previous states, capped at AGENT_STATE_HISTORY_MAX. */
stateHistory: AgentStateHistoryEntry[]
/** Observed session origin for row ordering; recent history can evict its first state. */
firstStateStartedAt?: number
/** Name of the tool the agent is currently using (e.g. "Edit", "Bash"). */
toolName?: string
/** Short preview of the tool input (e.g. file path, command). */
toolInput?: string
/** Keep full AskUserQuestion JSON for cards, not toolInput previews; clear when the agent moves on. */
interactivePrompt?: string
/** Most recent assistant message preview, when the hook carried one. */
lastAssistantMessage?: string
/** Dashboard may show tool output, but native-chat streaming must not present tool stdout as assistant prose. */
lastAssistantMessageIsToolOutput?: boolean
/** Retain the last completed non-boundary output across working: batched done→working publication may already clear lastAssistantMessage. */
lastCompletedAssistantMessage?: string
/** True when this `done` was reached via interrupt, not normal completion
* (agent-reported or Orca's guarded fallback). Undefined otherwise. */
interrupted?: boolean
/** True when this `done` is a session boundary, not a completed turn. See AgentStatusPayload. */
sessionBoundary?: boolean
/** Dispatch hierarchy belongs to panes, not worktrees: workers can share the coordinator's worktree. */
orchestration?: AgentStatusOrchestrationContext
/** Live in-process subagents/teammates of this pane's session. Absent when
* none are tracked; the sidebar derives indented child rows from it. */
subagents?: AgentSubagentSnapshot[]
/** The main agent's own state; absent from old hosts and from writers that carry no main agent fact
* (OSC, launch seeds), where readers fall back to `state`. */
mainAgent?: AgentMainAgentStatus
/** The host's child-work views for this session, when it publishes them; child rows then read
* these instead of `subagents`. Absent from older hosts. */
children?: AgentChildWorkView[]
/** Provider-owned conversation/session id captured from hook payloads.
* Used only for exact CLI resume; Orca terminal ids are not agent-session ids. */
providerSession?: AgentProviderSessionMetadata
/** False when the status belongs to a non-terminal owner that restores itself. */
terminalResumeEligible?: false
/** Live-only Command Code turn boundary key; not persisted to last-status.json. */
promptInteractionKey?: string
/** Live OSC 7501 facet never decides state; read through resolveProgramStatusPresentation beside the state owner. */
programStatus?: ProgramStatusFacet
/** Hydrated nonterminal rows are immediately stale; accepted live events clear this flag.
* Hosts also use it for pre-process evidence: preserve identity without claiming current status. */
restoredUnconfirmed?: boolean
} & AgentStatusRowFacets
// ─── Agent status payload shape (what hook receivers send via IPC) ──────────
// Hook integrations provide only normalized state fields; the renderer fills the rest (updatedAt, paneKey, …) on IPC receipt.
export type AgentStatusPayload = {
state: AgentStatusState
/** Ongoing work that does not require foreground agent execution. Only valid while working. */
workingMode?: AgentWorkingMode
prompt?: string
agentType?: AgentType
model?: string
modelSwitchCommand?: 'orca-model'
toolName?: string
toolInput?: string
/** JSON string of the AskUserQuestion tool input, captured live. See the
* AgentStatusEntry field for semantics. Not truncated like toolInput. */
interactivePrompt?: string
lastAssistantMessage?: string
/** See the AgentStatusEntry field for semantics. */
lastAssistantMessageIsToolOutput?: boolean
interrupted?: boolean
/** done session boundaries (connect/resume/clear) are not turn completions; notifications/automations/badges/end clocks must ignore them (STA-3386). */
sessionBoundary?: boolean
/** Wall-clock ms when the lead turn ended while Claude background inventory kept the pane `working`.
* `stateStartedAt` stays pinned for that whole working run, so this is the per-turn identity.
* Present on the gated `working` row and that turn's later all-clear `done`. Event-only — not stored on AgentStatusEntry. */
turnCompletedAt?: number
/** Live in-process children of the reporting session. See AgentStatusEntry. */
subagents?: AgentSubagentSnapshot[]
/** The main agent's own state and last-turn verdict. See AgentMainAgentStatus. Producers publish it
* beside the combined `state`; a reader that predates it keeps reading `state`. */
mainAgent?: AgentMainAgentStatus
/** The execution host awaits a launched Claude task’s wake-up or its finishing turn. */
claudeTaskWakeupPending?: 'notification' | 'finishing-turn'
}
/** Parsing always supplies prompt (empty if omitted); optional tool/assistant fields distinguish no update from explicit clearing. */
export type ParsedAgentStatusPayload = Omit<AgentStatusPayload, 'prompt'> & { prompt: string }
/** Explicitly select status fields from flattened IPC; spreading would leak launchToken, connectionId, promptInteractionKey and providerSessionOnly to paired clients. */
export function pickParsedAgentStatusPayload(
row: ParsedAgentStatusPayload
): ParsedAgentStatusPayload {
return {
state: row.state,
...(row.workingMode !== undefined ? { workingMode: row.workingMode } : {}),
prompt: row.prompt,
...(row.agentType !== undefined ? { agentType: row.agentType } : {}),
...(row.model !== undefined ? { model: row.model } : {}),
...(row.modelSwitchCommand ? { modelSwitchCommand: row.modelSwitchCommand } : {}),
...(row.toolName !== undefined ? { toolName: row.toolName } : {}),
...(row.toolInput !== undefined ? { toolInput: row.toolInput } : {}),
...(row.interactivePrompt !== undefined ? { interactivePrompt: row.interactivePrompt } : {}),
...(row.lastAssistantMessage !== undefined
? { lastAssistantMessage: row.lastAssistantMessage }
: {}),
...(row.lastAssistantMessageIsToolOutput !== undefined
? { lastAssistantMessageIsToolOutput: row.lastAssistantMessageIsToolOutput }
: {}),
...(row.interrupted !== undefined ? { interrupted: row.interrupted } : {}),
...(row.sessionBoundary !== undefined ? { sessionBoundary: row.sessionBoundary } : {}),
...(row.turnCompletedAt !== undefined ? { turnCompletedAt: row.turnCompletedAt } : {}),
...(row.subagents !== undefined ? { subagents: row.subagents } : {}),
...(row.mainAgent !== undefined ? { mainAgent: row.mainAgent } : {}),
...(row.claudeTaskWakeupPending !== undefined
? { claudeTaskWakeupPending: row.claudeTaskWakeupPending }
: {})
}
}
/** Hook set/snapshot IPC shares one shape so renderers use one setAgentStatus path. */
/** Maximum character length for the toolName field. */
export const AGENT_STATUS_TOOL_NAME_MAX_LENGTH = 60
/** 8KB preserves paragraph summaries while bounding per-pane cache growth. */
export const AGENT_STATUS_ASSISTANT_MESSAGE_MAX_LENGTH = 8000
/** Keep full question JSON/options, with a cap to bound cache; preview cuts would corrupt it. */
export const AGENT_STATUS_INTERACTIVE_PROMPT_MAX_LENGTH = 16000
// Re-exported here because every consumer reaches for the entry type and its freshness gate
// together; the clock rules themselves live in agent-status-freshness.ts.
export {
AGENT_STATUS_HYDRATE_MAX_AGE_MS,
AGENT_STATUS_STALE_AFTER_MS,
agentStatusAuthorityObservedAt,
agentStatusEvidenceObservedAt,
isFreshNonDoneAgentStatus
} from './agent-status-freshness'
// Why: ReadonlySet<string> so .has() accepts any string without a cast here; the narrowing cast stays on the return line where it's proven safe.
const VALID_STATES: ReadonlySet<string> = new Set<string>(AGENT_STATUS_STATES)
/** identified proves a new/continued/repeated turn; ambiguous cannot distinguish repeats from missed openings. Absence is legacy (older hosts, replays, unclassified agents). */
export type TurnEndDisposition = 'identified' | 'ambiguous'
export type HostTurnEndFacts = { turnEndedAt?: number; turnEndDisposition?: TurnEndDisposition }
export function isTurnEndDisposition(value: unknown): value is TurnEndDisposition {
return value === 'identified' || value === 'ambiguous'
}
/** The host's turn-end facts of a row, for the copies that carry them. */
export function pickHostTurnEnd(row: HostTurnEndFacts): HostTurnEndFacts {
return {
...(row.turnEndedAt !== undefined ? { turnEndedAt: row.turnEndedAt } : {}),
...(row.turnEndDisposition !== undefined ? { turnEndDisposition: row.turnEndDisposition } : {})
}
}
export function isAgentStatusState(value: unknown): value is AgentStatusState {
return typeof value === 'string' && VALID_STATES.has(value)
}
export const AGENT_STATUS_JSON_STRUCTURE_LIMITS = {
structuralTokens: 4096,
nestingDepth: 16
} as const
/** Drop malformed mainAgent alone; combined state remains valid, matching the older-host fallback. */
export function normalizeMainAgentStatusField(value: unknown): AgentMainAgentStatus | undefined {
if (typeof value !== 'object' || value === null) {
return undefined
}
const obj = value as Record<string, unknown>
const state = obj.state
if (!isAgentStatusState(state)) {
return undefined
}
if (typeof obj.stateStartedAt !== 'number' || !Number.isFinite(obj.stateStartedAt)) {
return undefined
}
return {
state,
// Why: a verdict belongs to a finished turn; anything riding on a live state is stale.
...(state === 'done' && isAgentTurnOutcome(obj.outcome) ? { outcome: obj.outcome } : {}),
...(state === 'working' && obj.stopping === true ? { stopping: true as const } : {}),
stateStartedAt: obj.stateStartedAt
}
}
/** Apply identical validation to JSON/object entrypoints; return null for malformed payloads or invalid states. */
function normalizeAgentStatusObject(parsed: unknown): ParsedAgentStatusPayload | null {
if (typeof parsed !== 'object' || parsed === null) {
return null
}
const obj = parsed as Record<string, unknown>
// Why: explicit typeof guard rejects non-string values instead of leaning on Set.has to return false for mismatched types.
if (typeof obj.state !== 'string') {
return null
}
const state = obj.state
if (!VALID_STATES.has(state)) {
return null
}
return {
state: state as AgentStatusState,
workingMode: state === 'working' && obj.workingMode === 'monitoring' ? 'monitoring' : undefined,
prompt: normalizePromptField(obj.prompt),
// Why: normalize like the other single-line fields so embedded newlines (e.g. `agentType: "claude\nrogue"`) can't break single-line UI and equality checks.
agentType: normalizeOptionalField(obj.agentType, AGENT_TYPE_MAX_LENGTH),
model: normalizeOptionalField(obj.model, AGENT_MODEL_MAX_LENGTH),
...(obj.modelSwitchCommand === 'orca-model'
? { modelSwitchCommand: 'orca-model' as const }
: {}),
toolName: normalizeOptionalField(obj.toolName, AGENT_STATUS_TOOL_NAME_MAX_LENGTH),
toolInput: normalizeOptionalField(obj.toolInput, AGENT_STATUS_TOOL_INPUT_MAX_LENGTH),
interactivePrompt: normalizeInteractivePromptField(
obj.interactivePrompt,
AGENT_STATUS_INTERACTIVE_PROMPT_MAX_LENGTH
),
lastAssistantMessage: normalizeOptionalMultilineField(
obj.lastAssistantMessage,
AGENT_STATUS_ASSISTANT_MESSAGE_MAX_LENGTH
),
// Only explicit true means known tool output; absent/false retain older-host behavior without suppressing prose.
lastAssistantMessageIsToolOutput:
obj.lastAssistantMessageIsToolOutput === true ? true : undefined,
// Why: only meaningful on `done`; coerce to undefined elsewhere so it can't leak stale truth across transitions.
interrupted: obj.interrupted === true && state === 'done' ? true : undefined,
sessionBoundary: obj.sessionBoundary === true && state === 'done' ? true : undefined,
turnCompletedAt: normalizeTurnCompletedAtField(obj.turnCompletedAt, state),
subagents: normalizeAgentSubagentsField(obj.subagents),
mainAgent: normalizeMainAgentStatusField(obj.mainAgent),
...(obj.agentType === 'claude' &&
state !== 'done' &&
(obj.claudeTaskWakeupPending === 'notification' ||
obj.claudeTaskWakeupPending === 'finishing-turn')
? { claudeTaskWakeupPending: obj.claudeTaskWakeupPending }
: {})
}
}
/** Normalize deserialized IPC directly to avoid JSON round trips on frequent tool events. */
export function normalizeAgentStatusPayload(payload: unknown): ParsedAgentStatusPayload | null {
return normalizeAgentStatusObject(payload)
}
/** Reject malformed hook/OSC 9999 JSON or invalid states as null. */
export function parseAgentStatusPayload(json: string): ParsedAgentStatusPayload | null {
try {
assertJsonTextStructureWithinLimits(json, AGENT_STATUS_JSON_STRUCTURE_LIMITS)
return normalizeAgentStatusObject(JSON.parse(json))
} catch {
return null
}
}