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.

11.5 KB
Raw Blame
// Validate replayed JSON deeply before unguarded reducers/renderers read it; malformed rows fail load without deletion.
// Extend with keys, open-union tags or a new row v; never tighten existing types/bounds/closed sets.
// Unknown keys and string vocabularies survive; unknown bodies/blocks/goals/subjects remain undrawn and writable.
// Unreadable context usage alone is dropped (journal-row-unusable-annotations.ts).
// Older rewind replaces unknown turn/tool/resolution states with placeholders and blocks with raw-JSON text, retaining unknown bodies.
// History pages lack row v: extensions must also remain safe for older clients (journal-closed-sets.test.ts).

import { z } from 'zod'
import { AgentSessionContextUsageSchema } from './agent-session-context-usage-schema'
import { AgentJournalThreadGoalStateSchema } from './agent-session-journal-thread-goal-schema'
import { AgentSessionFailureFactSchema } from './agent-session-failure-fact-schema'
import { knownTags, openDiscriminatedUnion } from './agent-session-journal-open-union'
import type {
  AgentJournalItemBody,
  AgentJournalMessageItem,
  AgentJournalResolution,
  AgentJournalRenderItem
} from './agent-session-journal-types'

const BoundedPayload = z.object({
  head: z.string(),
  byteLength: z.number(),
  digest: z.string(),
  truncated: z.boolean()
})

const ProviderFrame = z.object({
  provider: z.string(),
  kind: z.string(),
  payload: BoundedPayload
})

const ToolMetadata = {
  mcpIdentity: z.object({ server: z.string(), tool: z.string() }).optional(),
  exitCode: z.number().int().optional(),
  durationMs: z.number().nonnegative().optional(),
  webSearchResults: z.array(z.object({ title: z.string(), url: z.string() })).optional()
}

/** Provider IDs are opaque; reject all-whitespace values without rewriting valid IDs. */
const ProviderCallId = z
  .string()
  .refine((value) => value.trim().length > 0, 'callId must contain a non-whitespace character')

/** Keep lifecycle strings open so newer states do not make persisted rows malformed. */
const SubagentEntry = z.object({
  id: z.string(),
  label: z.string(),
  state: z.string().min(1),
  tokens: z.number().optional(),
  startedAt: z.number().optional(),
  settledAt: z.number().optional()
})

/** Skip unknown block types, but reject malformed payloads of known types. */
const Block = openDiscriminatedUnion(
  z.discriminatedUnion('type', [
    z.object({
      type: z.literal('text'),
      text: z.string(),
      presentation: z.string().optional(),
      tone: z.string().optional(),
      providerFrame: ProviderFrame.optional()
    }),
    // JSON.stringify drops input: undefined, so persisted canonical calls may omit it.
    z.object({
      type: z.literal('tool-call'),
      name: z.string(),
      input: z.unknown().optional(),
      callId: ProviderCallId.optional(),
      ...ToolMetadata
    }),
    z.object({
      type: z.literal('tool-result'),
      output: z.string(),
      isError: z.boolean().optional()
    }),
    z.object({
      type: z.literal('image-ref'),
      path: z.string().optional(),
      url: z.string().optional(),
      alt: z.string().optional()
    }),
    z.object({
      type: z.literal('subagent-group'),
      groupId: z.string(),
      agents: z.array(SubagentEntry)
    }),
    // `outcomeBasis` and `background` stay open for the same reason `state` does.
    SubagentEntry.extend({
      type: z.literal('subagent'),
      groupId: z.string(),
      parentId: z.string().optional(),
      run: z.string().optional(),
      outcomeBasis: z.string().optional(),
      background: z.boolean().optional()
    }),
    // Keep kind/state open for newer vocabularies; renderers fall back on unknown values.
    z.object({
      type: z.literal('background-task'),
      taskId: z.string().min(1),
      kind: z.string().min(1),
      label: z.string(),
      state: z.string().min(1),
      parentToolUseId: z.string().optional(),
      summary: z.string().optional(),
      error: z.string().optional(),
      outputFile: z.string().optional(),
      tokens: z.number().optional(),
      startedAt: z.number().optional(),
      settledAt: z.number().optional()
    })
  ])
)

const PromptOption = z.object({
  id: z.string(),
  label: z.string(),
  description: z.string().optional()
})

const FreeTextInput = z.object({
  allowEmpty: z.boolean().optional(),
  multiline: z.boolean().optional(),
  initialValue: z.string().optional(),
  placeholder: z.string().optional()
})

const Question = z.object({
  id: z.string(),
  question: z.string(),
  header: z.string().optional(),
  multiSelect: z.boolean(),
  options: z.array(PromptOption),
  freeTextQuestionId: z.string().optional(),
  freeTextInput: FreeTextInput.optional()
})

const Resolution = z.object({
  state: z.string().min(1),
  selectedOptionId: z.string().nullable(),
  answers: z
    .array(
      z.object({
        questionId: z.string(),
        optionIds: z.array(z.string()),
        other: z.string().optional()
      })
    )
    .optional(),
  resolvedBy: z.string().nullable(),
  resolvedAt: z.number().nullable()
})

const ApprovalMatchedAskRule = z.object({
  source: z.string(),
  toolName: z.string(),
  ruleContent: z.string().optional()
})

const KnownApprovalSubject = z.discriminatedUnion('kind', [
  z.object({ kind: z.literal('plan'), text: z.string().min(1), filePath: z.string().optional() })
])
export const AGENT_JOURNAL_APPROVAL_SUBJECT_KINDS = knownTags(KnownApprovalSubject)
/** Open like blocks; a subject this build cannot draw is never approvable here
 *  (agent-session-approval-subject.ts). */
const ApprovalSubject = openDiscriminatedUnion(KnownApprovalSubject)

const MessageBody = z.object({
  kind: z.literal('message'),
  role: z.string().min(1),
  blocks: z.array(Block),
  // Open like roles: a send mode a newer build writes must not turn the row malformed.
  sentAs: z.string().min(1).optional(),
  command: z.object({ name: z.string().min(1) }).optional(),
  skills: z.array(z.object({ name: z.string().min(1), path: z.string().min(1) })).optional(),
  // Open like `sentAs`: a state a newer host writes reads as completed, never malformed.
  state: z.string().min(1).optional(),
  completedAt: z.number().finite().optional()
})

/** A turn's lifecycle, as the turn item and the legacy status row both carry it. */
const TurnLifecycleFields = {
  turnId: z.string(),
  state: z.string().min(1),
  // Keep newer verdicts readable; readAgentJournalTurnOutcome maps unplaceable ones to unknown.
  outcome: z.string().min(1).optional(),
  userItemId: z.string().min(1).optional(),
  startedAt: z.number().finite().positive().optional(),
  requestedAt: z.number().finite().positive().optional(),
  completedAt: z.number().finite().positive().optional(),
  durationMs: z.number().finite().nonnegative().optional()
}

const KnownItemBody = z.discriminatedUnion('kind', [
  MessageBody,
  z.object({
    kind: z.literal('agent-start'),
    dispatchId: z.string().min(1),
    task: z.string()
  }),
  z.object({
    kind: z.literal('tool-call'),
    ...ToolMetadata,
    name: z.string(),
    // See the tool-call block: the key itself is lost when `input` is undefined.
    input: z.unknown().optional(),
    callId: ProviderCallId.optional(),
    state: z.string().min(1),
    // Open like `state`: an ending a newer build writes reads as the `state` beside it.
    endedAs: z.string().min(1).optional(),
    output: BoundedPayload.optional()
  }),
  z.object({ kind: z.literal('diff'), path: z.string(), patch: BoundedPayload }),
  z.object({
    kind: z.literal('approval'),
    title: z.string(),
    displayName: z.string().optional(),
    description: z.string().optional(),
    decisionReason: z.string().optional(),
    blockedPath: z.string().optional(),
    matchedAskRule: ApprovalMatchedAskRule.optional(),
    subject: ApprovalSubject.optional(),
    detail: z.string().nullable(),
    options: z.array(PromptOption),
    resolution: Resolution
  }),
  z.object({
    kind: z.literal('question'),
    question: z.string(),
    options: z.array(PromptOption),
    questions: z.array(Question).optional(),
    freeTextQuestionId: z.string().optional(),
    freeTextInput: FreeTextInput.optional(),
    resolution: Resolution
  }),
  z.object({
    kind: z.literal('status'),
    text: z.string(),
    presentation: z.string().optional(),
    contextClear: z
      .object({
        operationId: z.string().min(1).max(512),
        afterFence: z.number().int().nonnegative(),
        clearedAt: z.number().int().nonnegative()
      })
      .optional(),
    tone: z.string().optional(),
    turnLifecycle: z.object(TurnLifecycleFields).optional(),
    providerFrame: ProviderFrame.optional(),
    threadGoal: AgentJournalThreadGoalStateSchema.optional(),
    failure: AgentSessionFailureFactSchema.optional(),
    orcaStop: z.object({ cause: z.string().min(1) }).optional()
  }),
  z.object({
    kind: z.literal('turn'),
    ...TurnLifecycleFields,
    contextUsage: AgentSessionContextUsageSchema.optional(),
    providerTurnId: z.string().min(1).optional()
  })
])

/** Every body kind this build knows; a body of another kind is kept as-is and drawn by nobody. */
export const AGENT_JOURNAL_ITEM_BODY_KINDS = knownTags(KnownItemBody)
export const AgentJournalItemBodySchema = openDiscriminatedUnion(KnownItemBody)

/** Keep producerKind open so newer producer types remain readable across the wire. */
export const AgentJournalProducerLinkageFields = {
  // Empty IDs count as present and would permanently hide a parent's own row from parent-scoped readers.
  agentId: z.string().min(1).optional(),
  parentAgentId: z.string().min(1).optional(),
  providerParentRef: z.string().min(1).optional(),
  producerKind: z.string().min(1).optional(),
  attempt: z.number().int().optional()
} as const

/** Preserve unknown scope kinds from newer hosts without claiming a turn boundary or rejecting their content. */
export const AgentJournalTurnScopeSchema = z.object({
  kind: z.string().min(1),
  turnItemId: z.string().min(1).optional()
})

export const AgentJournalRenderItemSchema = z.object({
  itemId: z.string().min(1),
  revision: z.number().int(),
  body: AgentJournalItemBodySchema,
  sequence: z.number().int(),
  sequenceIndex: z.number().int().nonnegative().optional(),
  observedAt: z.number(),
  recovered: z.literal(true).optional(),
  recoveredAt: z.number().optional(),
  turnScope: AgentJournalTurnScopeSchema.optional(),
  shortened: z.literal(true).optional(),
  ...AgentJournalProducerLinkageFields
})

export function isAgentJournalResolution(value: unknown): value is AgentJournalResolution {
  return Resolution.safeParse(value).success
}

export function isAdmissibleAgentJournalItemBody(value: unknown): value is AgentJournalItemBody {
  return AgentJournalItemBodySchema.safeParse(value).success
}

/** Submission rows may only carry a user-authored message body. */
export function isAdmissibleAgentJournalMessageBody(
  value: unknown
): value is AgentJournalMessageItem {
  return MessageBody.safeParse(value).success
}

export function isAdmissibleAgentJournalRenderItem(
  value: unknown
): value is AgentJournalRenderItem {
  return AgentJournalRenderItemSchema.safeParse(value).success
}

/** Prove canonical writes are admissible on replay; open-string schemas are deliberately wider, so the converse need not hold. */
type Admits<T extends true> = T
export type CanonicalJournalTypesAreAdmissible = [
  Admits<AgentJournalItemBody extends z.input<typeof AgentJournalItemBodySchema> ? true : false>,
  Admits<AgentJournalMessageItem extends z.input<typeof MessageBody> ? true : false>,
  Admits<AgentJournalRenderItem extends z.input<typeof AgentJournalRenderItemSchema> ? true : false>
]