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
/** Share child labels/details across sidebar and chat. Prefer host children views; retain subagents/task-roster builders until no supported publisher/paired host requires each legacy shape. Delete each legacy builder when its last publisher is gone. */
import type { AgentSessionBackgroundTask } from './agent-session-background-task-wire'
import type { AgentChildWorkKind } from './agent-status-child-work'
import { resolveAgentChildWorkFreshness } from './agent-status-child-work-freshness'
import {
agentChildWorkOwnedLiveness,
deriveAgentChildDisplayState,
type AgentChildDisplayState
} from './agent-status-child-work-display'
import { agentChildWorkViewOffersStop } from './agent-child-work-stop-targets'
import type { AgentChildWorkView } from './agent-status-child-work-view'
import {
agentStatusAuthorityObservedAt,
agentStatusEvidenceObservedAt
} from './agent-status-freshness'
import type { AgentStatusEntry, AgentSubagentSnapshot } from './agent-status-types'
/** What a child row says beside its name. Surfaces format it; they never decide it. */
export type AgentChildRowDetail =
/** The tool the child is running now, as `tool: input` — the line a CLI agent row shows. */
| { kind: 'operation'; toolName: string; input?: string }
/** Its own work is over and only work it owns still runs; the tool line is stale. */
| { kind: 'monitoring' }
| { kind: 'message'; text: string }
/** Settled, and the lane cannot say how. */
| { kind: 'ended' }
/** How long since the last evidence for this child (see `recencyAt`). */
| { kind: 'no-update' }
/** The child's role, when nothing more specific is known. */
| { kind: 'role'; agentType: string }
/** A host that publishes only a run state: that state's reason word. */
| { kind: 'reason'; state: 'waiting' | 'blocked' | 'unverifiable' }
/** One child row, for every surface that lists child work (sidebar and chat strip). */
export type AgentChildRowModel = {
/** Row identity: the host's child id, or the provider id an old host names it by. */
id: string
/** The id a targeted stop names; absent when the host holds none. */
providerId?: string
kind: AgentChildWorkKind
displayState: AgentChildDisplayState
/** '' when the child reported no label; a surface then names the row by its state. */
name: string
agentType?: string
model?: string
detail: AgentChildRowDetail | null
/** When the child was first seen: the elapsed anchor. */
firstObservedAt: number
/** Last evidence for THIS child. Absent from a host that reports none. */
observedAt?: number
/** Reader-clock anchor for no-update age: child evidence, otherwise parent evidence. */
recencyAt: number
settledAt?: number
totalTokens?: number
canStop: boolean
settled: boolean
/** Work this child owns (a nested agent, a shell it launched), in host order. */
owned: AgentChildRowModel[]
}
export type AgentChildRowContext = {
/** A stale parent makes every live claim beneath it unverifiable. */
parentEvidenceFresh: boolean
transportObservation: 'live' | 'unverifiable'
/** Parent evidence on the reader clock; fallback recency when the child has no clock. */
parentObservedAt: number
/** Reader minus host clock, or zero locally; convert child stamps before computing age. */
hostClockOffsetMs: number
}
/** Derive every surface's child context from the same parent evidence. */
export function agentChildRowContextForParent(
parent: Pick<
AgentStatusEntry,
'updatedAt' | 'evidenceObservedAt' | 'mirroredEvidenceReceivedAt' | 'subagentObservation'
>,
parentEvidenceFresh: boolean
): AgentChildRowContext {
// The parent row decays on this same clock, so a child's silence reads the same as its parent's.
const parentObservedAt = agentStatusEvidenceObservedAt(parent)
return {
parentEvidenceFresh,
transportObservation: parent.subagentObservation ?? 'live',
parentObservedAt,
hostClockOffsetMs: parentObservedAt - agentStatusAuthorityObservedAt(parent)
}
}
/** Provider strings that carry no identity; the next label wins. */
const PLACEHOLDER_LABELS = new Set(['unknown', 'untitled', 'task', 'subagent'])
/** A provider label that names the child, or undefined for an empty or placeholder one. */
export function usableAgentChildLabel(value: string | undefined): string | undefined {
const trimmed = value?.trim()
return trimmed && !PLACEHOLDER_LABELS.has(trimmed.toLowerCase()) ? trimmed : undefined
}
// A live claim beneath a parent Orca no longer hears from asserts nothing; settled history stands.
function withFreshness(
displayState: AgentChildDisplayState,
context: AgentChildRowContext
): AgentChildDisplayState {
if (
displayState === 'done' ||
displayState === 'failed' ||
displayState === 'interrupted' ||
displayState === 'idle'
) {
return displayState
}
return resolveAgentChildWorkFreshness({
state: displayState,
membership: 'live',
parentEvidenceFresh: context.parentEvidenceFresh,
transportObservation: context.transportObservation
})
}
type AgentChildRowDetailSource = {
/** `run-state`: the host reported only the child's run state (the legacy task roster). */
evidence: 'child' | 'run-state'
kind: AgentChildWorkKind
name: string
agentType?: string
operation?: { toolName: string; input?: string }
lastMessage?: string
settled: boolean
}
// A default role or one that restates the name adds nothing.
function roleDetail(source: AgentChildRowDetailSource): AgentChildRowDetail | null {
if (source.kind !== 'agent') {
return null
}
const agentType = source.agentType ?? 'unknown'
return agentType.trim() === 'default' || source.name.trim() === agentType.trim()
? null
: { kind: 'role', agentType }
}
function messageOrRole(source: AgentChildRowDetailSource): AgentChildRowDetail | null {
const text = source.lastMessage?.trim()
return text ? { kind: 'message', text } : roleDetail(source)
}
/** The one rule for what a child row says, in the order a CLI agent row decides it. */
function agentChildRowDetail(
source: AgentChildRowDetailSource,
displayState: AgentChildDisplayState
): AgentChildRowDetail | null {
if (source.evidence === 'run-state') {
return displayState === 'waiting' ||
displayState === 'blocked' ||
displayState === 'unverifiable'
? { kind: 'reason', state: displayState }
: null
}
switch (displayState) {
case 'unverifiable':
return { kind: 'no-update' }
case 'monitoring':
// A shell or monitor names itself; only an agent's own tool line goes stale.
return source.kind === 'agent' ? { kind: 'monitoring' } : null
case 'working':
case 'waiting':
return source.operation
? {
kind: 'operation',
toolName: source.operation.toolName,
...(source.operation.input !== undefined ? { input: source.operation.input } : {})
}
: messageOrRole(source)
case 'blocked':
case 'done':
case 'failed':
return messageOrRole(source)
case 'interrupted':
return roleDetail(source)
case 'idle':
return source.settled ? { kind: 'ended' } : roleDetail(source)
}
}
function viewName(view: AgentChildWorkView): string {
return (
usableAgentChildLabel(view.description) ??
usableAgentChildLabel(view.name) ??
usableAgentChildLabel(view.agentType) ??
''
)
}
function rowFromView(
view: AgentChildWorkView,
views: readonly AgentChildWorkView[],
ownedByOwner: ReadonlyMap<string, AgentChildWorkView[]>,
context: AgentChildRowContext,
path: ReadonlySet<string>
): AgentChildRowModel {
const displayState = withFreshness(
deriveAgentChildDisplayState(view, agentChildWorkOwnedLiveness(views, view.id)),
context
)
const settled = view.membership === 'settled'
const name = viewName(view)
const nextPath = new Set(path).add(view.id)
return {
id: view.id,
...(view.providerId !== undefined ? { providerId: view.providerId } : {}),
kind: view.kind,
displayState,
name,
...(view.agentType !== undefined ? { agentType: view.agentType } : {}),
...(view.model !== undefined ? { model: view.model } : {}),
detail: agentChildRowDetail(
{
evidence: 'child',
kind: view.kind,
name,
agentType: view.agentType,
operation: view.operation,
lastMessage: view.lastMessage,
settled
},
displayState
),
firstObservedAt: view.firstObservedAt,
observedAt: view.observedAt,
recencyAt: view.observedAt + context.hostClockOffsetMs,
...(view.settledAt !== undefined ? { settledAt: view.settledAt } : {}),
...(view.totalTokens !== undefined ? { totalTokens: view.totalTokens } : {}),
canStop: agentChildWorkViewOffersStop(view),
settled,
owned: (ownedByOwner.get(view.id) ?? [])
.filter((owned) => !nextPath.has(owned.id))
.map((owned) => rowFromView(owned, views, ownedByOwner, context, nextPath))
}
}
/** Nest host views by ownership; the shared fold keeps finished agents monitoring their live work. */
export function buildAgentChildRowModels(
views: readonly AgentChildWorkView[],
context: AgentChildRowContext
): AgentChildRowModel[] {
const ownedByOwner = new Map<string, AgentChildWorkView[]>()
for (const view of views) {
if (view.parentChildWorkId !== undefined) {
ownedByOwner.set(view.parentChildWorkId, [
...(ownedByOwner.get(view.parentChildWorkId) ?? []),
view
])
}
}
return views
.filter((view) => view.parentChildWorkId === undefined)
.map((view) => rowFromView(view, views, ownedByOwner, context, new Set()))
}
/** Legacy subagents from older hosts/CLI panes have lifecycle/spawn times but no child evidence clock. */
export function buildLegacyAgentChildRowModels(
subagents: readonly AgentSubagentSnapshot[],
context: AgentChildRowContext
): AgentChildRowModel[] {
return subagents.map((subagent) => {
const displayState = withFreshness(
deriveAgentChildDisplayState({ state: subagent.state, membership: 'live' }, null),
context
)
const name =
usableAgentChildLabel(subagent.description) ?? usableAgentChildLabel(subagent.agentType) ?? ''
return {
id: subagent.id,
providerId: subagent.id,
kind: 'agent',
displayState,
name,
...(subagent.agentType !== undefined ? { agentType: subagent.agentType } : {}),
...(subagent.model !== undefined ? { model: subagent.model } : {}),
detail: agentChildRowDetail(
{ evidence: 'child', kind: 'agent', name, agentType: subagent.agentType, settled: false },
displayState
),
firstObservedAt: subagent.startedAt,
recencyAt: context.parentObservedAt,
canStop: false,
settled: false,
owned: []
}
})
}
function legacyTaskDisplayState(
task: AgentSessionBackgroundTask,
settled: boolean
): AgentChildDisplayState {
if (task.state) {
return task.state
}
if (settled) {
return 'done'
}
return task.kind === 'monitor' ? 'monitoring' : 'working'
}
// The host decided each row's state; the row keeps it.
function legacyTaskRow(task: AgentSessionBackgroundTask, settled: boolean): AgentChildRowModel {
const displayState = legacyTaskDisplayState(task, settled)
const name = usableAgentChildLabel(task.description) ?? usableAgentChildLabel(task.name) ?? ''
const startedAt = task.startedAt ?? 0
return {
id: task.id,
providerId: task.id,
kind: task.kind,
displayState,
name,
detail: agentChildRowDetail(
{ evidence: 'run-state', kind: task.kind, name, settled },
displayState
),
firstObservedAt: startedAt,
recencyAt: startedAt,
...(task.totalTokens !== undefined ? { totalTokens: task.totalTokens } : {}),
// Absent means stoppable: a host predating the field published only rows its stop could act on.
canStop: task.stoppable !== false,
settled,
owned: []
}
}
/** Legacy session task rosters are flat, retain host-decided state and have only start times. */
export function buildLegacyTaskRowModels(
tasks: readonly AgentSessionBackgroundTask[],
settledTasks: readonly AgentSessionBackgroundTask[]
): AgentChildRowModel[] {
// Older hosts can retain a previous turn beside its resumed live task; the live row wins.
const rows = new Map<string, AgentChildRowModel>()
for (const [roster, settled] of [
[settledTasks, true],
[tasks, false]
] as const) {
for (const task of roster) {
rows.set(task.id, legacyTaskRow(task, settled))
}
}
return [...rows.values()]
}
/** Every row of a tree, owners before what they own. */
export function flattenAgentChildRowModels(
rows: readonly AgentChildRowModel[]
): AgentChildRowModel[] {
return rows.flatMap((row) => [row, ...flattenAgentChildRowModels(row.owned)])
}