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.

22.7 KB
Raw Blame
import type { AgentJournalCursor, AgentJournalItemIdentity } from './agent-session-journal-identity'
export type {
  AgentJournalCursor,
  AgentJournalItemIdentity,
  AgentSessionJournalIdentity,
  AgentSessionJournalProviderHandle
} from './agent-session-journal-identity'
import type { AgentJournalTurnScope } from './agent-session-journal-turn-scope'
export type { AgentJournalTurnScope } from './agent-session-journal-turn-scope'
import type { AgentSessionProviderContextBoundary } from './agent-session-provider-context'
// Persist/republish plain JSON only. Append-only rows are upcast on read, never rewritten;
// unreadable versions/kinds must refuse writes rather than be skipped or compacted away.

import type { UnreadAgentSessionFailureFact } from './agent-session-failure'
import type { AgentSessionFailureRowWords } from './agent-session-failure-words'
import type { AgentType } from './agent-status-types'
import type { AgentSessionQuestionAnswer } from './agent-session-question-answer'
import type { AgentJournalTurnOutcome } from './agent-turn-outcome'
import type { NativeChatToolMetadata } from './native-chat/tools/native-chat-tool-identity'
import type { AgentSessionContextUsage } from './agent-session-context-usage'
import type { NativeChatBlock, NativeChatRole } from './native-chat-types'
import type {
  AgentMessageSender,
  AgentMessageSource
} from './agent-session/agent-session-message-source'
import type { AgentSessionExecutionOptions } from './agent-session-execution-options'

export { type AgentType }

/** Bump only alongside a read-time upcaster in `journal-row-schema.ts`. */
/** v3 introduced turn items; other rows stay v2. The first v3 row stops older hosts writing (read-only on released builds, failed load here) rather than allowing truncation. */
export const AGENT_SESSION_JOURNAL_SCHEMA_VERSION = 4
export const AGENT_SESSION_JOURNAL_TURN_ITEM_SCHEMA_VERSION = 3
/** v4 queue rows make older builds keep the chat read-only; other rows retain their own version. */
export const AGENT_SESSION_JOURNAL_QUEUE_SCHEMA_VERSION = 4
const AGENT_SESSION_JOURNAL_PRE_TURN_SCHEMA_VERSION = 2

export function journalRowSchemaVersion(bodies: readonly { kind: string }[]): number {
  return bodies.some((body) => body.kind === 'turn')
    ? AGENT_SESSION_JOURNAL_TURN_ITEM_SCHEMA_VERSION
    : AGENT_SESSION_JOURNAL_PRE_TURN_SCHEMA_VERSION
}

// ─── Bounded payloads ───────────────────────────────────────────────────────

/** A tool output or diff body. A row keeps the whole value (`truncated: false`). `truncated: true`
 *  marks a head: the copy sent to a client (fetch the whole item with `agentSession.item`), a
 *  call still running, or a row an older build saved, whose remainder is gone. */
export type AgentJournalBoundedPayload = {
  head: string
  /** Byte length of the ORIGINAL payload, not of `head`. */
  byteLength: number
  /** sha256 of the original payload, for identification only. */
  digest: string
  truncated: boolean
}

// ─── Render-model items ─────────────────────────────────────────────────────

/** How a user message reached the provider when it was not an ordinary turn
 *  input. Persisted and open for growth: a reader that cannot place a value
 *  renders an ordinary message. */
export const AGENT_JOURNAL_MESSAGE_SEND_MODES = ['goal'] as const
export type AgentJournalMessageSendMode = (typeof AGENT_JOURNAL_MESSAGE_SEND_MODES)[number]

/** Unknown persisted message states read as completed. */
export const AGENT_JOURNAL_MESSAGE_STATES = ['running', 'completed'] as const
export type AgentJournalMessageState = (typeof AGENT_JOURNAL_MESSAGE_STATES)[number]

export type AgentJournalSkillRef = { name: string; path: string }

export type AgentJournalMessageItem = {
  kind: 'message'
  role: NativeChatRole
  blocks: NativeChatBlock[]
  /** Absent ⇒ an ordinary turn input. `goal` ⇒ the text was set as the thread
   *  goal's objective, and the provider pursues it without a turn of its own. */
  sentAs?: AgentJournalMessageSendMode
  /** Present on a conversation command the user sent, such as `/compact`. The text is what the
   *  user typed; this names the command so no reader parses it. Open like `sentAs`. */
  command?: { name: string }
  /** The skills the user picked from the menu for this message, by the file the agent selects
   *  each by. The text still carries each `$name`; agents that select by name ignore this. */
  skills?: AgentJournalSkillRef[]
  /** Present on a message another agent sent through Orca; absent, the person's. Host-written,
   *  outside every fingerprint, never sent to the provider. */
  from?: AgentMessageSource
  /** Reasoning rows only: absence means unknown, never live. observedAt marks the start. */
  state?: AgentJournalMessageState
  /** Host-observed message/turn/stream end; absent for history or crash recovery without a live end, so no duration is claimed. */
  completedAt?: number
}

export type AgentJournalToolCallState = 'running' | 'completed' | 'failed'

/** How a call that did not finish on its own ended, finer than its `failed` state. Persisted and
 *  open for growth: a reader that cannot place a value reads `state`. `unverifiable` is a call its
 *  session's end closed when nothing proved that end, so a later proof naming its owner finds it
 *  and revises it to `interrupted`, as it does the turn. */
export const AGENT_JOURNAL_TOOL_CALL_ENDINGS = ['interrupted', 'unverifiable'] as const
export type AgentJournalToolCallEnding = (typeof AGENT_JOURNAL_TOOL_CALL_ENDINGS)[number]

export type AgentJournalToolCallItem = NativeChatToolMetadata & {
  kind: 'tool-call'
  name: string
  input: unknown
  /** Provider-supplied identity within this item stream; optional for mixed-version peers. */
  callId?: string
  state: AgentJournalToolCallState
  /** Only beside `state: 'failed'`, which builds that predate it read as they always did. Read
   *  both through `agentJournalToolCallLifecycle`. */
  endedAs?: AgentJournalToolCallEnding
  output?: AgentJournalBoundedPayload
}

export type AgentJournalDiffItem = {
  kind: 'diff'
  path: string
  patch: AgentJournalBoundedPayload
}

export const AGENT_JOURNAL_RESOLUTION_STATES = ['pending', 'resolved', 'cancelled'] as const
export type AgentJournalResolutionState = (typeof AGENT_JOURNAL_RESOLUTION_STATES)[number]

/** Durable resolution uses compare-and-set so competing clients cannot invoke the provider callback twice. */
export type AgentJournalResolution = {
  state: AgentJournalResolutionState
  /** Option id the winner picked; null while pending or cancelled. For a question, the answer in the
   *  packed form older clients read; `answers` is the same answer structured. */
  selectedOptionId: string | null
  /** Question answers. Absent on approvals and on rows written before hosts recorded it. */
  answers?: AgentSessionQuestionAnswer[]
  /** Opaque client identity of the resolver, for "answered on <device>". */
  resolvedBy: string | null
  resolvedAt: number | null
}

export type AgentJournalPromptOption = {
  id: string
  label: string
  description?: string
}

export type AgentJournalFreeTextInput = {
  allowEmpty?: boolean
  multiline?: boolean
  initialValue?: string
  placeholder?: string
}

export type AgentJournalQuestion = {
  id: string
  question: string
  header?: string
  multiSelect: boolean
  options: AgentJournalPromptOption[]
  /** Present when the provider accepts an answer outside the offered options. */
  freeTextQuestionId?: string
  freeTextInput?: AgentJournalFreeTextInput
}

export type AgentJournalApprovalMatchedAskRule = {
  source: string
  toolName: string
  ruleContent?: string
}

export type AgentJournalPlanApprovalSubject = {
  kind: 'plan'
  text: string
  filePath?: string
}

declare const agentJournalUnknownKind: unique symbol
/** A kind tag this build does not know. Branded, so it never stands in for a known tag. */
export type AgentJournalUnknownKind = string & { readonly [agentJournalUnknownKind]: true }

/** A subject of a kind a newer Orca wrote: carried as it was, with whatever fields it holds, and
 *  never drawn or approved here. */
export type AgentJournalUnknownApprovalSubject = { readonly kind: AgentJournalUnknownKind }

/** Open, as the journal schema reads it: narrow with `isPlanApprovalSubject` before reading it. */
export type AgentJournalApprovalSubject =
  | AgentJournalPlanApprovalSubject
  | AgentJournalUnknownApprovalSubject

export type AgentJournalApprovalItem = {
  kind: 'approval'
  title: string
  displayName?: string
  description?: string
  decisionReason?: string
  blockedPath?: string
  matchedAskRule?: AgentJournalApprovalMatchedAskRule
  subject?: AgentJournalApprovalSubject
  detail: string | null
  options: AgentJournalPromptOption[]
  resolution: AgentJournalResolution
}

export type AgentJournalQuestionItem = {
  kind: 'question'
  question: string
  options: AgentJournalPromptOption[]
  questions?: AgentJournalQuestion[]
  /** Present when the provider accepts an answer outside the offered options. */
  freeTextQuestionId?: string
  freeTextInput?: AgentJournalFreeTextInput
  resolution: AgentJournalResolution
}

export const AGENT_JOURNAL_TURN_LIFECYCLE_STATES = [
  'running',
  'completed',
  'interrupted',
  'unverifiable'
] as const
export type AgentJournalTurnLifecycleState = (typeof AGENT_JOURNAL_TURN_LIFECYCLE_STATES)[number]

// The turn verdict vocabulary lives in agent-turn-outcome.ts so the agent-status
// row can share it without importing the journal; re-exported to keep one import site.
export { AGENT_JOURNAL_TURN_OUTCOMES, type AgentJournalTurnOutcome } from './agent-turn-outcome'

export type AgentJournalTurnLifecycle = {
  turnId: string
  state: AgentJournalTurnLifecycleState
  /** Absent/unrecognized verdict means unknown, never success. completed alone proves nothing: provider API errors also finish turns. */
  outcome?: AgentJournalTurnOutcome
  /** Journal key of the user item that opened the turn. A lifecycle row may key
   *  itself when provider output opened a turn with no user item; absent means
   *  an older host. */
  userItemId?: string
  startedAt?: number
  /** Host clock at the send that opened this turn, when one is known. `startedAt`
   *  remains the provider turn-open instant and is never rewritten. */
  requestedAt?: number
  completedAt?: number
  /** The provider's own measured turn duration, preferred over the host interval. */
  durationMs?: number
  /** What the provider said about its context window during or after this turn.
   *  Usually written by a later revision, since the provider answers after the end. */
  contextUsage?: AgentSessionContextUsage
  /** On a turn a conversation command opened: the provider turn that carried out the command,
   *  once the provider opened one. Nothing else re-derives it after the command settles. */
  providerTurnId?: string
}

/** Provider thread-goal lifecycle. Open like other persisted vocabularies: a
 *  status a newer provider reports must not turn a row malformed. */
export const AGENT_JOURNAL_THREAD_GOAL_STATUSES = [
  'active',
  'paused',
  'blocked',
  'usageLimited',
  'budgetLimited',
  'complete'
] as const
export type AgentJournalThreadGoalStatus = (typeof AGENT_JOURNAL_THREAD_GOAL_STATUSES)[number]

/** The provider's goal as last journaled. Timestamps are epoch ms on the
 *  provider's clock; counters are as of `updatedAt`. */
export type AgentJournalThreadGoal = {
  objective: string
  status: AgentJournalThreadGoalStatus
  tokenBudget: number | null
  tokensUsed: number
  timeUsedSeconds: number
  createdAt: number
  updatedAt: number
}

/** A goal transition in typed form, so readers never parse a bounded frame head. */
export type AgentJournalThreadGoalState =
  | { state: 'set'; goal: AgentJournalThreadGoal }
  | { state: 'cleared' }

type AgentJournalStatusItemFields = {
  kind: 'status'
  /** Optional display hints; unknown values retain the ordinary text fallback. */
  presentation?: string
  contextClear?: AgentSessionProviderContextBoundary
  tone?: string
  /** Legacy carrier of a turn record: written by hosts before v3, and published
   *  to clients that predate the `turn` item. New code reads turns through
   *  `readAgentJournalTurn`, never this field. */
  turnLifecycle?: AgentJournalTurnLifecycle
  /** Additive fallback for provider traffic this host cannot model yet. Older
   *  clients still render `text`; newer clients expose the bounded frame. */
  providerFrame?: {
    provider: string
    kind: string
    payload: AgentJournalBoundedPayload
  }
  /** Present on thread-goal transitions; absent on rows from older hosts. */
  threadGoal?: AgentJournalThreadGoalState
  /** On the row about a reply Orca's own stop cut off: why Orca stopped. Its cause is open (a newer
   *  host may name one this build does not know), so read it with `readAgentSessionOrcaStop`. */
  orcaStop?: { cause: string }
}

/** A status row that reports no failure; its text is its writer's own. */
export type AgentJournalPlainStatusItem = AgentJournalStatusItemFields & {
  text: string
  failure?: undefined
}

export type AgentJournalStatusItem =
  | AgentJournalPlainStatusItem
  | (AgentJournalStatusItemFields &
      /** A row that reports a failure: what failed, typed, beside the sentence older clients print,
       *  both from `agentSessionFailureWords`. Absent on rows from older hosts. */
      AgentSessionFailureRowWords)

/** The durable record of one root turn. `running` exposes cancellation while
 *  the provider can still accept it; the item is revised to a terminal state,
 *  never tombstoned, so the endpoints survive. Timestamps are the execution
 *  host's clock at provider-event receipt; `durationMs` is the provider's own
 *  measurement. `unverifiable` carries no end: the host lost the child without
 *  observing its exit. `outcome` is the provider's separate verdict and is
 *  absent whenever nothing told the host one. */
export type AgentJournalTurnItem = { kind: 'turn' } & AgentJournalTurnLifecycle

/** Display-only creation fact; survives removal of the orchestration Task and Dispatch. */
export type AgentJournalAgentStartItem = {
  kind: 'agent-start'
  dispatchId: string
  worker: AgentMessageSender
  task: string
}

export type AgentJournalItemBody =
  | AgentJournalAgentStartItem
  | AgentJournalMessageItem
  | AgentJournalToolCallItem
  | AgentJournalDiffItem
  | AgentJournalApprovalItem
  | AgentJournalQuestionItem
  | AgentJournalStatusItem
  | AgentJournalTurnItem

/** Agent work, versus a backgrounded shell or command task. Classified once by
 *  the producer, which holds the provider vocabulary, so no reader re-derives it. */
export type AgentJournalProducerKind = 'agent' | 'background'

/** Repeat producer identity on every row so backwards scans stopping at the turn need no start-row lookup. Absence positively identifies the session root, never unknown; subagents share its journal. */
export type AgentJournalProducerLinkage = {
  /** The producing subagent's canonical id. Absent ⇒ the session's own agent. */
  agentId?: string
  /** The producing agent's own parent. Absent ⇒ its parent is the session root. */
  parentAgentId?: string
  /** Provider tool-call parent reference, not agent identity: resumes announce a new call. Provenance only; producers read it to recover earlier resolved IDs, readers never join on it. */
  providerParentRef?: string
  producerKind?: AgentJournalProducerKind
  /** Which run of the agent, when past the first. Identity answers "which agent";
   *  this answers "which run of it", and is deliberately not part of the identity. */
  attempt?: number
}

export const AGENT_JOURNAL_THREAD_SCOPE: AgentJournalTurnScope = { kind: 'thread' }

/** Who produced a row and which turn it belongs to: what every item write states. */
export type AgentJournalRowAttribution = AgentJournalProducerLinkage & {
  turnScope: AgentJournalTurnScope
}

export type AgentJournalPosition = {
  sequence: number
  index: number
}

/** Order by sequence; provider observedAt can precede earlier sequences after crash recovery. */
export type AgentJournalRenderItem = AgentJournalProducerLinkage & {
  itemId: string
  revision: number
  body: AgentJournalItemBody
  sequence: number
  /** Place among the writes of the row at `sequence`, which one lifecycle batch
   *  shares across every item it creates. Absent ⇒ 0, and on a host that predates it. */
  sequenceIndex?: number
  observedAt: number
  /** Set when the row was appended by crash reconciliation rather than live. */
  recovered?: true
  /** When crash reconciliation wrote this revision; present exactly when `recovered` is. */
  recoveredAt?: number
  /** Absent only from a host that predates it. */
  turnScope?: AgentJournalTurnScope
  /** Set on the copy sent to a client when text in it was shortened to fit; never saved. The whole
   *  item comes from `agentSession.item`. A cut tool output or diff also says so in `truncated`. */
  shortened?: true
}

// ─── Submissions ────────────────────────────────────────────────────────────

/** The turn a send was answered into: its record's item id, and how the send joined it. `start`:
 *  the provider answered the send's start request with that turn; `steer`: Orca steered it into
 *  that running turn. Known limit: a start the provider silently folds into a running turn reads
 *  as `start`, including into a turn no user entry opened. A newer host may name another way,
 *  which a reader leaves unclaimed. */
export type AgentJournalAnsweredTurn = { turnItemId: string; via: AgentJournalTurnJoin }
export type AgentJournalTurnJoin = 'start' | 'steer'
/** The same, as a writer names it: the turn record's identity, keyed when the row is written. */
export type AgentJournalAnsweredTurnIdentity = {
  turn: AgentJournalItemIdentity
  via: AgentJournalTurnJoin
}

export const AGENT_JOURNAL_DISPATCH_STATES = ['pending', 'accepted', 'rejected', 'unknown'] as const
export type AgentJournalDispatchState = (typeof AGENT_JOURNAL_DISPATCH_STATES)[number]

/** The write-ahead submission row, projected. `unknown` is a displayed state:
 *  the turn reads as delivery unconfirmed, never as sent and never as failed. */
export type AgentJournalSubmission = {
  clientMessageId: string
  /** Execution fence of the latest dispatch attempt or recovery. */
  fence: number
  payloadFingerprint: string
  dispatchState: AgentJournalDispatchState
  /** Provider item identity adopted on accept; null otherwise. */
  providerItemId: string | null
  /** Terminal reason on `rejected`: a sentence a person can read, or one of the legacy markers
   *  older clients already recognise. On `unknown`, the doubt marker. */
  reason: string | null
  /** On `rejected`, why, typed; absent on rows from older hosts. */
  rejection?: UnreadAgentSessionFailureFact
  submittedAt: number
  resolvedAt: number | null
  /** Where the journal wrote this submission's row: its sequence, recomputed on every fold and
   *  never stored. Needed because a rejected send's own row moves to its rejection, which erases
   *  where it was sent. Absent from hosts that predate it. */
  submittedSequence?: number
  /** On `rejected`: the turn a Codex send was answered into, when that turn ended without taking
   *  it. null: the host recorded that it was answered into no turn, as every other rejection is
   *  (Claude, a queued message taken back before handover, restart recovery). Absent: written
   *  before this field existed, or not rejected. A stored value this build cannot read is null. */
  answeredInTurn?: AgentJournalAnsweredTurn | null
  /** Set when crash reconciliation resolved the dispatch, not the provider. A live
   *  `unknown` is a send still outstanding; a recovered one outlived its writer. */
  recovered?: true
  /** The host accepted this send to hand over later; absent on sends dispatched as they were
   *  recorded (older hosts). With no `handedOverAt` yet, a pending one is still queued. */
  handoverRecorded?: true
  /** When the host handed it to the provider (its `dispatch{pending}` row). */
  handedOverAt?: number
  /** Host-only: the submission row's sequence, which tells which host process accepted it. Set
   *  only on a send accepted for later handover. The snapshot still carries it, but the submission
   *  schema omits it; no released client reads it, and clients read `submittedSequence` instead. */
  acceptedSequence?: number
  /** The queued draft this submission hands off; absent for a direct send. Read this, never
   *  a draft id compared with `clientMessageId`. */
  queuedMessageId?: string
  /** Host-only: who asked for this turn — a person over the client send RPC, or Orca itself.
   *  A restart or a close keeps only a person's Send cut short as a card. The snapshot still
   *  carries it; no released client reads it. */
  origin?: 'client' | 'host'
  /** Who it is from: the kind of its `AgentSessionMessageSource` ('user' or 'agent'), so a restart
   *  or a close keeps only a person's unsent send as a card. Only the kind: the senders stay on the
   *  card, host-only, and publishing them here would need a strip. A newer build's kind is kept as
   *  written, never read as absent. Absent when its sender named none (a dispatch preamble, a restart continuation). */
  source?: { kind: string }
  /** On a rejected send the host kept as a card: that card's message id. The text lives on the
   *  card, so no surface draws this send, before or after the card is sent, edited or deleted.
   *  Recorded in the rejection's own transaction (`journal-unsent-send-hold.ts`). */
  keptAsQueuedMessageId?: string
  /** Immutable choices captured on acceptance and applied when the agent is handed the message;
   *  absent on older submissions. The host's alone: clients ignore it. */
  options?: AgentSessionExecutionOptions
}

/** Durable answer to "did my send land?", keyed by client message id. Only an
 *  `accepted` dispatch mints one, and it outlives the journal tail. */
export type AgentJournalAcceptanceReceipt = {
  clientMessageId: string
  providerItemId: string
  cursor: AgentJournalCursor
  acceptedAt: number
}

// ─── Snapshots and cursor resume ────────────────────────────────────────────

export type AgentJournalSnapshot = {
  sessionId: string
  cursor: AgentJournalCursor
  items: AgentJournalRenderItem[]
  submissions: AgentJournalSubmission[]
}

/** Every cursor-resume failure forces a clean client snapshot reload. */
export const AGENT_JOURNAL_RESET_REASONS = [
  'epoch_changed',
  'cursor_ahead',
  'cursor_compacted',
  'journal_gap',
  'schema_unreadable'
] as const
export type AgentJournalResetReason = (typeof AGENT_JOURNAL_RESET_REASONS)[number]