Skip to content

armgit / orca

Public Imported from GitHub
0

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.

8.2 KB
Raw Blame
// Share terminal-state and group summary rules with producers/desktop/mobile.
// Frozen fallback text must retain only write-time facts valid after the writer exits; live claims belong to revisable blocks.

import {
  isSubagentGroupBlock,
  type NativeChatBlock,
  type NativeChatSubagentEntry,
  type NativeChatSubagentGroupBlock,
  type NativeChatSubagentState
} from '../../native-chat-types'

/** Only working is in flight; producers collapse started/interacted/pending/running/paused before writing the roster. */
const TERMINAL_SUBAGENT_STATES: ReadonlySet<string> = new Set([
  'idle',
  'completed',
  'failed',
  'stopped',
  'unverifiable'
])

/** Settled-state precedence for the group's one-line verdict: the worst
 *  outcome wins, and `completed` only shows when nothing else is left. */
const SETTLED_PRECEDENCE = ['failed', 'stopped', 'unverifiable', 'idle', 'completed'] as const

/** Report adverse outcomes before all siblings settle so failures remain visible during fan-out. */
const ADVERSE_PRECEDENCE = ['failed', 'stopped', 'unverifiable'] as const

/** A state this build does not know reads as `unverifiable`, never as working:
 *  a roster written by a newer build must not leave the row spinning forever. */
export function normalizeSubagentState(state: string): NativeChatSubagentState {
  if (state === 'working') {
    return 'working'
  }
  return TERMINAL_SUBAGENT_STATES.has(state) ? (state as NativeChatSubagentState) : 'unverifiable'
}

/** Shared durable/read bound for id, label and groupId; larger writes waste replay bytes every consumer clips anyway. */
export const MAX_SUBAGENT_FIELD_CHARS = 512

export function isTerminalSubagentState(state: string): boolean {
  return normalizeSubagentState(state) !== 'working'
}

/** Latch the child’s verdict, not lost visibility: later authoritative outcomes may replace unverifiable. */
const LATCHED_SUBAGENT_STATES: ReadonlySet<string> = new Set([
  'idle',
  'completed',
  'failed',
  'stopped'
])

/** Preserve reported outcomes. Allow unverifiable to settle when contact returns, but never return settled/lost children to working from stale progress ticks. */
export function canReplaceSubagentState(current: string, next: string): boolean {
  const from = normalizeSubagentState(current)
  if (from === 'working') {
    return true
  }
  if (LATCHED_SUBAGENT_STATES.has(from)) {
    return false
  }
  // `from` is `unverifiable`: only a real verdict may land.
  return LATCHED_SUBAGENT_STATES.has(normalizeSubagentState(next))
}

export type NativeChatSubagentSummary = {
  total: number
  working: number
  /** The group's verdict once nothing is in flight; null while any child works. */
  settledState: NativeChatSubagentState | null
  /** How many children hold `settledState`. */
  settledCount: number
  /** Worst adverse outcome already recorded, reported even while siblings still
   *  work. Null when nothing has gone wrong. */
  adverseState: NativeChatSubagentState | null
  /** How many children hold `adverseState`. */
  adverseCount: number
  /** Sum latest child totals only; child counters are disjoint from the deliberately excluded parent usage. */
  tokens: number | null
  /** Synthetic elapsed-clock anchor covering latest runs: count overlaps once and omit idle gaps. Null if no run is measurable. */
  clockStartedAt: number | null
  /** Latest terminal timestamp, once the group has settled. */
  settledAt: number | null
}

export function summarizeSubagentGroup(
  agents: readonly NativeChatSubagentEntry[]
): NativeChatSubagentSummary {
  const counts = new Map<NativeChatSubagentState, number>()
  let working = 0
  let tokens: number | null = null
  let settledAt: number | null = null
  for (const agent of agents) {
    const state = normalizeSubagentState(agent.state)
    if (state === 'working') {
      working += 1
    } else {
      counts.set(state, (counts.get(state) ?? 0) + 1)
    }
    if (typeof agent.tokens === 'number' && Number.isFinite(agent.tokens)) {
      tokens = (tokens ?? 0) + agent.tokens
    }
    if (typeof agent.settledAt === 'number') {
      settledAt = settledAt === null ? agent.settledAt : Math.max(settledAt, agent.settledAt)
    }
  }
  const settledState =
    working > 0 ? null : (SETTLED_PRECEDENCE.find((state) => counts.has(state)) ?? null)
  const adverseState = ADVERSE_PRECEDENCE.find((state) => counts.has(state)) ?? null
  return {
    total: agents.length,
    working,
    settledState,
    settledCount: settledState === null ? 0 : (counts.get(settledState) ?? 0),
    adverseState,
    adverseCount: adverseState === null ? 0 : (counts.get(adverseState) ?? 0),
    tokens,
    clockStartedAt: subagentClockStart(agents, working > 0 ? null : settledAt),
    settledAt: working > 0 ? null : settledAt
  }
}

/** Every working run ends at now, so together they cover one span from the
 *  earliest of them; only settled time before that span adds to it. */
function subagentClockStart(
  agents: readonly NativeChatSubagentEntry[],
  settledAt: number | null
): number | null {
  const runs: [number, number][] = []
  let liveFrom: number | null = null
  for (const agent of agents) {
    if (typeof agent.startedAt !== 'number') {
      continue
    }
    if (normalizeSubagentState(agent.state) === 'working') {
      liveFrom = liveFrom === null ? agent.startedAt : Math.min(liveFrom, agent.startedAt)
    } else if (typeof agent.settledAt === 'number') {
      runs.push([agent.startedAt, Math.max(agent.startedAt, agent.settledAt)])
    }
  }
  const cutoff = liveFrom ?? Infinity
  let covered = 0
  let reach = -Infinity
  for (const [start, end] of runs.sort((a, b) => a[0] - b[0])) {
    covered += Math.max(0, Math.min(end, cutoff) - Math.max(start, reach))
    reach = Math.max(reach, end)
  }
  if (liveFrom !== null) {
    return liveFrom - covered
  }
  return settledAt === null || runs.length === 0 ? null : settledAt - covered
}

/** Empty rosters draw no row despite schema acceptance; counting them as renderable reserves a blank transcript gap. */
export function isRenderableSubagentGroup(block: NativeChatSubagentGroupBlock): boolean {
  return block.agents.length > 0
}

/** The spawn groups in `blocks` that will actually draw a row. */
export function subagentGroupBlocks(
  blocks: readonly NativeChatBlock[]
): NativeChatSubagentGroupBlock[] {
  return blocks.filter(
    (block): block is NativeChatSubagentGroupBlock =>
      isSubagentGroupBlock(block) && isRenderableSubagentGroup(block)
  )
}

/** Only rendered rosters replace their frozen twin; preserve genuine adjacent prose. */
export function isReplacedSubagentGroupTwin(block: NativeChatBlock, drawsGroup: boolean): boolean {
  return drawsGroup && block.type === 'text' && isSubagentGroupFallbackText(block.text)
}

/** The row's blocks less any roster twin a drawn group replaces. */
export function withoutSubagentGroupTwins(blocks: readonly NativeChatBlock[]): NativeChatBlock[] {
  const drawsGroup = subagentGroupBlocks(blocks).length > 0
  return blocks.filter((block) => !isReplacedSubagentGroupTwin(block, drawsGroup))
}

/** Frozen fallback for clients without roster blocks: claim spawn/recorded outcomes only, never current live counts
 * (docs/reference/ssh-execution-boundary.md). Kicked off versus Ran states whether an outcome existed at write time;
 * Ran while in flight would falsely claim exit. Keep adverse counts so plain-text readers still see failures. Hosts revise structured blocks for liveness. */
export function subagentGroupFallbackText(agents: readonly NativeChatSubagentEntry[]): string {
  const { total, working, adverseState, adverseCount } = summarizeSubagentGroup(agents)
  const noun = total === 1 ? 'subagent' : 'subagents'
  const adverse = adverseState === null ? '' : ` (${adverseCount} ${adverseState})`
  return `${working > 0 ? 'Kicked off' : 'Ran'} ${total} ${noun}${adverse}`
}

/** Match frozen twin shape, not recomputed bytes: newer states normalize differently and would duplicate the roster.
 * Keep legacy — N working clauses for unreleased dev journals that replay forever; no extra false-positive surface. Sync with subagentGroupFallbackText. */
const SUBAGENT_GROUP_FALLBACK_PATTERN =
  /^(?:Kicked off \d+ subagents?(?: \u2014 \d+ working)?|Ran \d+ subagents?)(?: \(\d+ [a-z][a-z-]*\))?$/

export function isSubagentGroupFallbackText(text: string): boolean {
  return SUBAGENT_GROUP_FALLBACK_PATTERN.test(text)
}