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
import type { AgentSessionProviderContextBoundary } from './agent-session-provider-context'
// IPC-serializable conversation contract: plain JSON only, no classes/Maps/Dates. Sources prefer transcripts, then hooks,
// then degraded scrollback; docs/plans/2026-06-17-001-feat-native-chat-view-plan.md (KTD2).
import type {
AgentSessionBackgroundTask,
AgentSessionBackgroundTaskRunState
} from './agent-session-background-task-wire'
import type { AgentSessionTokenUsage } from './agent-session-context-usage'
import type { AgentSessionOrcaStop } from './agent-session-orca-stop'
import type { AgentSessionFailureFact } from './agent-session-failure'
import type {
AgentJournalMessageSendMode,
AgentJournalMessageState,
AgentJournalPosition,
AgentJournalProducerLinkage,
AgentJournalToolCallEnding,
AgentJournalToolCallState
} from './agent-session-journal-types'
import type { AgentType } from './agent-status-types'
import type { NativeChatToolMetadata } from './native-chat/tools/native-chat-tool-identity'
import type { AgentMessageSource } from './agent-session/agent-session-message-source'
export type { AgentType }
export const NATIVE_CHAT_SOURCES = ['transcript', 'hook', 'scrape'] as const
export type NativeChatSource = (typeof NATIVE_CHAT_SOURCES)[number]
/** Higher source authority wins deduplication of the same turn. */
export const NATIVE_CHAT_SOURCE_PRIORITY: Record<NativeChatSource, number> = {
transcript: 3,
hook: 2,
scrape: 1
}
export const NATIVE_CHAT_ROLES = ['user', 'assistant', 'tool', 'reasoning', 'system'] as const
export type NativeChatRole = (typeof NATIVE_CHAT_ROLES)[number]
export type NativeChatTextBlock = {
type: 'text'
text: string
/** Optional journal display hints; readers narrow only the values they know. */
presentation?: string
contextClear?: AgentSessionProviderContextBoundary
tone?: string
/** Optional structured detail for an otherwise ordinary fallback line. */
providerFrame?: {
provider: string
kind: string
payload: {
head: string
byteLength: number
digest: string
truncated: boolean
}
}
/** On a status line that reports a failure: what failed, typed. */
failure?: AgentSessionFailureFact
/** On the line about a reply Orca's own stop cut off: why, and the turn it cut. */
orcaStop?: AgentSessionOrcaStop & { turnItemId?: string }
/** On a usage-limit line: the turn the limit ended, which its Continue picks up. */
usageLimitTurnItemId?: string
}
/** Tool arguments remain unknown because provider shapes differ; renderers preview the serialized payload. */
export type NativeChatToolCallBlock = NativeChatToolMetadata & {
type: 'tool-call'
name: string
input: unknown
/** Provider-supplied identity within this item stream; absent on legacy transcripts and peers. */
callId?: string
/** Provider lifecycle when the structured app-server path can supply it. */
state?: AgentJournalToolCallState
/** See the journal tool-call item: read with `state` through `agentJournalToolCallLifecycle`. */
endedAs?: AgentJournalToolCallEnding
}
/** One resolved hunk from a provider's edit result, carrying true file ranges. */
export type NativeChatEditPatchHunk = {
oldStart: number
oldLines: number
newStart: number
newLines: number
/** Signed unified rows, as the provider emitted them. */
lines: string[]
}
/** Provider-resolved file hunks: Claude attaches them to results; Codex resolves ranges in its patch before sending. */
export type NativeChatEditPatch = {
filePath?: string
hunks: NativeChatEditPatchHunk[]
}
/** The result returned to the agent for a prior tool call. */
export type NativeChatToolResultBlock = {
type: 'tool-result'
output: string
isError?: boolean
/** The call this result answers, when the producer knows it; otherwise pairing is positional. */
callId?: string
/** Present only for edit tools whose result reported resolved hunks. */
editPatch?: NativeChatEditPatch
/** The journal item to fetch when `output` is only a head of what the tool returned. */
fullOutputItemId?: string
}
/** Local path or remote URL, exactly one populated; optional alt text. */
export type NativeChatImageRefBlock = {
type: 'image-ref'
path?: string
url?: string
alt?: string
}
/** Collapse in-flight provider states to working. idle means existing but inactive; unverifiable means contact lost without proof of exit
* (docs/reference/ssh-execution-boundary.md). */
export const NATIVE_CHAT_SUBAGENT_STATES = [
'working',
'idle',
'completed',
'failed',
'stopped',
'unverifiable'
] as const
export type NativeChatSubagentState = (typeof NATIVE_CHAT_SUBAGENT_STATES)[number]
/** One child agent in a spawn group. */
export type NativeChatSubagentEntry = {
/** Provider's child id (Codex: the child thread id). The roster key. */
id: string
/** Row label — the provider's task name, disambiguated by ordinal on collision. */
label: string
state: NativeChatSubagentState
/** Latest total tokens the provider reported FOR THIS CHILD, never a running sum. */
tokens?: number
/** Epoch ms the child's latest run started; a resumed child restarts it. */
startedAt?: number
/** Epoch ms the entry latched terminal. */
settledAt?: number
}
/** Provider-neutral roster revised in place by Claude/Codex activity. */
export type NativeChatSubagentGroupBlock = {
type: 'subagent-group'
/** Stable group key — the parent turn that spawned these children. */
groupId: string
agents: NativeChatSubagentEntry[]
}
/** Individual subagent row revised at its spawn position. Readers derive sibling groups from groupId/parentId; no row lists them together. */
export type NativeChatSubagentBlock = NativeChatSubagentEntry & {
type: 'subagent'
/** The turn that spawned it: siblings with the same key draw together. */
groupId: string
/** The subagent that spawned it. Absent ⇒ the session's own agent did. */
parentId?: string
/** The provider's id for the run `state` describes. Absent when the provider names none. */
run?: string
/** `stop-acknowledged`: stopped because the agent accepted a Stop, not because the child
* reported its own end; that run's own ending may still replace it. */
outcomeBasis?: 'stop-acknowledged'
/** Told to outlive the turn that spawned it. */
background?: true
}
/** Durable provider task row, revised in place from lifecycle frames. Shell/workflow/monitor tasks are distinct from subagent rosters.
* Failures change state on the same row rather than becoming separate red error rows. */
export type NativeChatBackgroundTaskBlock = {
type: 'background-task'
/** Provider task id — the row key, stable across a resume. */
taskId: string
kind: AgentSessionBackgroundTask['kind']
/** Display name: the provider's description, else the identity it reported. */
label: string
/** Run state, in the vocabulary the background-tasks strip already renders. */
state: AgentSessionBackgroundTaskRunState
/** Structural link used to co-locate the task with its spawning call; transcript rows have no separate parent relationship. */
parentToolUseId?: string
/** The provider's own sentence about the outcome, when it sent one. */
summary?: string
/** The provider's error text, when it reported one apart from the summary. */
error?: string
/** Where the provider wrote the task's output. */
outputFile?: string
/** Latest total tokens the provider reported FOR THIS TASK. */
tokens?: number
startedAt?: number
/** Epoch ms the row latched terminal. */
settledAt?: number
}
export type NativeChatBlock =
| NativeChatTextBlock
| NativeChatToolCallBlock
| NativeChatToolResultBlock
| NativeChatImageRefBlock
| NativeChatSubagentGroupBlock
| NativeChatSubagentBlock
| NativeChatBackgroundTaskBlock
/** Structured rows preserve journal producer linkage; terminal-backed rows omit it. */
export type NativeChatMessage = AgentJournalProducerLinkage & {
/** Stable dedup/list identity across re-reads and appends. */
id: string
role: NativeChatRole
blocks: NativeChatBlock[]
/** Epoch ms; null when unavailable (e.g. scrape). */
timestamp: number | null
source: NativeChatSource
/** Optional provider row cursor; split projections share it for whole-row paging. */
transcriptOffset?: number
/** Canonical display position: JSONL record byte start or database provider sequence, independent of clocks/cursors. */
transcriptOrder?: number
/** Model id that produced an assistant response, as the provider API names it. */
model?: string
/** The agent's provider that served `model`, where the agent records one. */
provider?: string
/** On assistant responses whose accounting reflects the prompt the model read. */
usage?: AgentSessionTokenUsage
/** Explicit turn key overrides differing ids for turn deduplication. */
turnId?: string
/** Provider conversation-tree predecessor id; older hosts omit it. */
parentId?: string
/** How a user message was delivered when it was not an ordinary prompt. */
sentAs?: AgentJournalMessageSendMode
/** Its text was shortened to fit the copy sent to this client; the host keeps it whole. */
shortened?: true
/** The journal row's own lifecycle; absent means unknown, never live. */
state?: AgentJournalMessageState
/** Host clock when the row's message was seen to end; absent when no end was seen live. */
completedAt?: number
/** On a conversation command the user sent, such as `/compact`: the command it names. */
command?: { name: string }
/** On a user-role message another agent sent through Orca: who, as the journal recorded it. */
from?: AgentMessageSource
/** Projected creation fact, never a user turn or provider input. */
agentStart?: true
/** Accepted but not yet handed to the agent: drawn after everything the agent has done. */
queued?: true
/** Unsent rows belong to no turn. Draw at journal position, or after the conversation when unplaced. */
unsent?: true
/** This client's send, made while the chat read Stopping, that the host has not recorded yet. */
sentWhileStopping?: true
/** Unrecorded client send awaiting explicit Retry; host holds nothing, so it cannot wait behind a turn. */
awaitsRetry?: true
/** Withdrawn sends have no rail tick because the host conversation outline excludes them. */
stoppedBeforeStart?: true
/** Structured journal ordering outranks timestamps; terminal transcripts omit it and worker reads strip it. */
journalPosition?: AgentJournalPosition
/** Newest absorbed tool row’s position; the folded row still sorts by its own position. */
foldedJournalPosition?: AgentJournalPosition
/** Private presentation row; raw host messages never publish this fold-only marker. */
unpairedToolResults?: true
}
/** Split reasoning and its answer share the provider's row identity. */
export function nativeChatSemanticRowId(message: NativeChatMessage): string {
return message.role === 'reasoning' && message.id.endsWith(':reasoning')
? message.id.slice(0, -':reasoning'.length)
: message.id
}
/** New hosts expose the cursor; older messages retain their reasoning/answer id convention. */
export function nativeChatMessagesShareTranscriptRow(
first: NativeChatMessage,
second: NativeChatMessage
): boolean {
if (typeof first.transcriptOffset === 'number' && typeof second.transcriptOffset === 'number') {
return first.transcriptOffset === second.transcriptOffset
}
return (
first.role === 'reasoning' &&
second.role === 'assistant' &&
nativeChatSemanticRowId(first) === second.id
)
}
export const NATIVE_CHAT_TURN_LIFECYCLE_STATES = ['working', 'completed', 'interrupted'] as const
export type NativeChatTurnLifecycleState = (typeof NATIVE_CHAT_TURN_LIFECYCLE_STATES)[number]
export const NATIVE_CHAT_INTERRUPTED_STATUS_TEXT = 'Conversation interrupted'
/** Replay-safe provider completion/interruption evidence recovered from transcripts, unlike assistant prose. */
export type NativeChatTurnLifecycle = {
state: NativeChatTurnLifecycleState
/** Stable provider id when available, otherwise the JSONL record position. */
turnId: string
/** Provider timestamp; null only when the transcript omitted one. */
timestamp: number | null
}
export const NATIVE_CHAT_SESSION_STATUSES = [
'loading',
'ready',
'working',
'empty',
'error'
] as const
export type NativeChatSessionStatus = (typeof NATIVE_CHAT_SESSION_STATUSES)[number]
export type NativeChatSession = {
messages: NativeChatMessage[]
status: NativeChatSessionStatus
/** Provider conversation id; null until reported while the view shows live hooks and later backfills. */
sessionId: string | null
agent: AgentType
/** Human-readable error when `status === 'error'`. */
error?: string
}
export function isTextBlock(block: NativeChatBlock): block is NativeChatTextBlock {
return block.type === 'text'
}
export function isToolCallBlock(block: NativeChatBlock): block is NativeChatToolCallBlock {
return block.type === 'tool-call'
}
export function isToolResultBlock(block: NativeChatBlock): block is NativeChatToolResultBlock {
return block.type === 'tool-result'
}
/** Provider-authored Claude interruptedMessageId/Codex turn_aborted rows abandon in-flight tool calls without results. */
export function isInterruptedStatusMessage(message: NativeChatMessage): boolean {
return (
message.role === 'system' &&
message.blocks.some(
(block) => block.type === 'text' && block.text === NATIVE_CHAT_INTERRUPTED_STATUS_TEXT
)
)
}
export function isImageRefBlock(block: NativeChatBlock): block is NativeChatImageRefBlock {
return block.type === 'image-ref'
}
export function isSubagentGroupBlock(
block: NativeChatBlock
): block is NativeChatSubagentGroupBlock {
return block.type === 'subagent-group'
}
export function isSubagentBlock(block: NativeChatBlock): block is NativeChatSubagentBlock {
return block.type === 'subagent'
}
export function isBackgroundTaskBlock(
block: NativeChatBlock
): block is NativeChatBackgroundTaskBlock {
return block.type === 'background-task'
}