Repository Public
1/** Public API types of the kernel (CONTRACT §2). */2import type { DelegationContract, EffectClass, EventKind, ResultEnvelope, Trust, Usage } from '@aos/shared';34export type ReconcileOutcome<Res> = { done: true; result: Res } | { done: false } | { unknown: true };56export interface StepSpec<Req, Res> {7 /** 'model_call' | 'tool_call' | 'wait' | 'now' | 'uuid' | … */8 kind: string;9 name: string;10 effect: EffectClass;11 /** JSON-serialisable; hashed (canonical JSON) → request_hash. */12 request: Req;13 /** Optional probe for non_idempotent steps found 'started' after a crash: has the effect happened? */14 reconcile?: (req: Req, idemKey: string) => Promise<ReconcileOutcome<Res>>;15 /**16 * ADDITION to the contract (optional). Result to record when the owner answers "it ran — continue"17 * to a reconcile question (the real output was lost in the crash). Default:18 * `{ ok: true, output: 'Owner confirmed …', reconciled: 'assumed_done' }`.19 */20 assumedResult?: (req: Req, idemKey: string) => Res;21}2223export type StepExec<Res> = (idemKey: string, signal: AbortSignal) => Promise<{ result: Res; usage?: Partial<Usage> }>;2425export interface RunContext {26 readonly runId: string;27 readonly missionId: string;28 readonly parentRunId: string | null;29 readonly contract: DelegationContract;30 readonly workspaceAbs: string;31 /** Aborted on cancel, lost lease and worker shutdown. */32 readonly signal: AbortSignal;33 step<Req, Res>(spec: StepSpec<Req, Res>, exec: StepExec<Res>): Promise<Res>;34 wait<T = unknown>(kind: 'approval' | 'question', payload: Record<string, unknown>, opts?: { timeoutSec?: number }): Promise<T | { expired: true }>;35 sleep(ms: number): Promise<void>;36 now(): Promise<Date>;37 uuid(): Promise<string>;38 emit(kind: EventKind, payload: Record<string, unknown>, trust?: Trust): Promise<void>;39 emitTransient(kind: 'model.delta', payload: Record<string, unknown>): void;40 ownerMessages(): Promise<{ id: number; text: string }[]>;41 readonly replaying: boolean;42 usage(): Usage;43 budgetLeft(): { usd: number; turns: number; wallSec: number };44}4546export type RunLogic = (ctx: RunContext) => Promise<ResultEnvelope>;4748export type StepBoundary = 'before_intent' | 'after_intent' | 'after_exec' | 'after_commit';49/** Test instrumentation (chaos suite): called at each boundary of the step protocol. */50export interface KernelHooks {51 boundary?: (info: { runId: string; seq: number; kind: string; name: string; boundary: StepBoundary }) => void | Promise<void>;52}5354/** Daily cap in USD: a number, null (no cap), or a function re-evaluated before each model_call. */55export type DailyBudget = number | null | (() => number | null | Promise<number | null>);5657/** The three answers offered by a reconcile question (CONTRACT §2 step protocol 4). */58export const RECONCILE_OPTIONS = ['it ran — continue', 'it did not run — run it', 'abort'] as const;59