@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5685

package/dist/core/agent-profiles.js

@@ -0,0 +1,105 @@
+import { join } from 'node:path';
+/**
+ * Pure native account-home mappings. Keep file-catalog knowledge separate from account
+ * relocation. Workspace code resolves saved accounts; runners, auth and terminal handoff consume
+ * this mapping.
+ */
+/**
+ * Account relocation variables used by cezar. null means named accounts are unsupported. omp
+ * takes a profile name; other supported mappings take a folder. Host values define the default;
+ * named overrides apply last. Refuse a named omp folder outside the current profile root.
+ */
+export const PROFILE_ENV_VAR = {
+    claude: 'CLAUDE_CONFIG_DIR',
+    codex: 'CODEX_HOME',
+    opencode: null,
+    pi: 'PI_CODING_AGENT_DIR',
+    // CURSOR_CONFIG_DIR relocates configuration, not a verified whole account home.
+    cursor: null,
+    omp: 'OMP_PROFILE',
+};
+/** Providers that can carry more than one account — what the UI offers "Add account" for. */
+export const PROFILE_CAPABLE_PROVIDERS = Object.keys(PROFILE_ENV_VAR).filter((provider) => PROFILE_ENV_VAR[provider] !== null);
+export function supportsProfiles(provider) {
+    return PROFILE_ENV_VAR[provider] !== null;
+}
+/**
+ * Build a provider-specific account override, or an empty object for the discovered default. omp
+ * takes a profile name parsed from its folder. Never emit another provider’s variable.
+ */
+export function profileEnv(provider, configDir) {
+    const name = PROFILE_ENV_VAR[provider];
+    const dir = configDir?.trim();
+    if (name === null || !dir)
+        return {};
+    if (provider === 'omp') {
+        const profile = ompProfileName(dir);
+        return profile === null ? {} : { [name]: profile };
+    }
+    return { [name]: dir };
+}
+/** omp's own profile-name rule (omp 18.8.0, `packages/utils/src/dirs.ts`). */
+const OMP_PROFILE_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+/** Windows device names omp refuses as a profile, with or without an extension. */
+const OMP_RESERVED_NAME_RE = /^(?:CON|PRN|AUX|NUL|COM[0-9]|LPT[0-9])(?:\..*)?$/i;
+/**
+ * The omp profile a folder names, or `null` when it names none.
+ *
+ * A folder names a profile when its parent is called `profiles` and its own name passes every rule
+ * omp applies, so cezar never hands omp a profile it would refuse at startup. `default` is refused
+ * too: omp reads it as "no profile", so a named account under that name would be the default.
+ *
+ * Shape only — whether `profiles/` is the one under omp's CURRENT root needs the environment, and
+ * `ompProfileDirError` (workspace) checks that. Both separators are accepted so a Windows folder
+ * parses on any host.
+ */
+export function ompProfileName(dir) {
+    const segments = dir.split(/[\\/]+/).filter((segment) => segment !== '');
+    if (segments.length < 2 || segments[segments.length - 2] !== 'profiles')
+        return null;
+    const name = segments[segments.length - 1];
+    return isOmpProfileName(name) ? name : null;
+}
+/** Whether omp accepts `name` as a profile of its own; `default` is omp's "no profile". */
+export function isOmpProfileName(name) {
+    return OMP_PROFILE_NAME_RE.test(name) && !name.endsWith('.') && name !== 'default'
+        && !OMP_RESERVED_NAME_RE.test(name);
+}
+/**
+ * Where the agent keeps its config inside an account folder: the folder itself, except omp, whose
+ * profile folder keeps it in `agent/`. The discovered omp default is ALREADY an agent dir
+ * (`agentHomePaths().omp`), so callers apply this to named accounts only.
+ */
+export function profileAgentDir(provider, dir) {
+    return provider === 'omp' ? join(dir, 'agent') : dir;
+}
+/**
+ * Does `entries` look like a config dir this provider actually wrote?
+ *
+ * ADVISORY, never a gate. The honest first-run flow for a second account is *add the profile →
+ * Connect → the CLI creates the dir on login*, so refusing an unrecognized directory would break
+ * the very case the feature exists for. The answer drives a warning line in the UI, nothing more.
+ *
+ * Takes the directory listing rather than a path so it stays pure; the caller reads the dir.
+ */
+export function looksLikeProfileDir(provider, entries) {
+    const present = new Set(entries);
+    const markers = PROFILE_DIR_MARKERS[provider];
+    return markers.some((marker) => present.has(marker));
+}
+/** What each agent drops into its home on first login. Any one is enough. */
+const PROFILE_DIR_MARKERS = {
+    // `.claude.json` sits INSIDE the dir once it is overridden (see `claudeStateFilePath`), which
+    // is exactly the case being probed here.
+    claude: ['.claude.json', 'settings.json', 'projects', 'sessions'],
+    codex: ['auth.json', 'config.toml'],
+    // OpenCode cannot carry profiles (`PROFILE_ENV_VAR.opencode === null`); the discovered config
+    // dir is probed, but nothing it holds marks a login.
+    opencode: [],
+    pi: ['auth.json', 'settings.json', 'models.json', 'sessions'],
+    cursor: [],
+    // A named account is a profile folder (`agent/`, `logs/`, `run/`, `cache/`); the discovered
+    // default is an agent dir (`agent.db`, `config.yml`, `sessions/`). Either listing answers.
+    omp: ['agent', 'agent.db', 'config.yml', 'sessions'],
+};
+//# sourceMappingURL=agent-profiles.js.map

package/dist/core/agent-profiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-profiles.js","sourceRoot":"","sources":["../../src/core/agent-profiles.ts"],"names":[],"mappings":"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"}

package/dist/core/agent-runner.d.ts

@@ -0,0 +1,425 @@
+/**
+ * Backend-neutral logical sessions for task execution, follow-ups, waiting, interrupt and
+ * resume. Adapters own native process lifetimes and emit normalized events behind this seam.
+ */
+import type { UiEvent } from './ui-events.ts';
+import type { SessionTransport } from '../contract/index.js';
+import type { RunnerFacts } from './runner-facts.ts';
+/**
+ * Canonical user-selectable runner tuple in display order. Derive runtime enumerations and
+ * schemas from this set; keep legacy backend ids separate for persisted records.
+ */
+export declare const RUNNER_IDS: readonly ['claude', 'codex', 'opencode', 'pi', 'cursor', 'omp'];
+/** The user-selectable runners (what config/GUI expose). */
+export type RunnerId = (typeof RUNNER_IDS)[number];
+/** `claude-cli` is the legacy id kept so old run records still parse. */
+export type AgentBackend = RunnerId | 'claude-cli';
+/** Narrow an arbitrary string (a config value, a check name) to a runner id. */
+export declare function isRunnerId(value: string): value is RunnerId;
+export interface AgentRunSpec {
+    /** Appended to the CLI's default system prompt (`--append-system-prompt`). */
+    systemPrompt?: string;
+    /** Private bundled tool server; capability values belong only in env. */
+    cezarTools?: {
+        name: string;
+        command: string;
+        args: string[];
+    };
+    userPrompt: string;
+    /** Image blocks delivered with the first user message — screenshots pasted
+     *  into the new-task form (spec 002's paste path, at task start). */
+    images?: ContentBlock[] | undefined;
+    /** The directory the agent runs in — also the only writable root. */
+    cwd: string;
+    /** The tool list and how it reached the runner. The zero-config default
+     *  (`DEFAULT_ALLOWED_TOOLS`) includes `Bash` unrestricted unless the grant
+     *  carries a `bashAllowlist`, so treat it as full shell access in `cwd`, not
+     *  a sandboxed allowlist (#430). */
+    toolGrant: ToolGrant;
+    /** A governed session (every root and worker session the delegation listener provisions): turn off native tools that reach another
+     * session where a runner keeps them separate from subagent messaging, for this
+     * invocation only. Native subagents stay. Adapters map this intent; absent preserves
+     * ordinary harness settings. Custom tools and unrestricted shell are not
+     * hard-isolated. See AGENT_PROTOCOL.md's D1 (hearsay-tools/cezarion#2279). */
+    restrictCrossSessionMessaging?: boolean;
+    /** Extra directories the agent may read/write besides `cwd`. */
+    additionalDirectories?: string[];
+    /** Extra env vars for the agent process (merged over `process.env`) —
+     *  e.g. CEZ_HANDOFF_FILE / CEZ_ARTIFACTS_DIR / CEZ_TASK_ID (spec 007). */
+    env?: Record<string, string>;
+    model?: string | undefined;
+    /** Reasoning-effort pin (#45). Canonical `low`/`medium`/`high`/`xhigh`/`max`;
+     *  absent means each harness keeps its own default. Same class of override as
+     *  `model`, so `modelsLocked` suppresses it too. */
+    effort?: string | undefined;
+    /** Wall-clock kill switch for the run (ms). */
+    timeoutMs?: number | undefined;
+    /**
+     * Stable session id (UUID) so the user can take over interactively later:
+     * `cd <repo> && claude --resume <sessionId>`.
+     */
+    sessionId?: string | undefined;
+    /**
+     * Spawn `claude --resume <sessionId>` instead of starting a fresh session —
+     * picks up the on-disk conversation (used by "Continue" after a run ends).
+     */
+    resume?: boolean;
+    /**
+     * Full system prompt (skill + extra + handoff) used only when an in-thread
+     * resume cannot reopen the stored session and the runner falls back to a
+     * fresh one. Continue omits the skill from `systemPrompt` on in-thread
+     * resumes; this carries it for that fallback. Absent on resent runners.
+     */
+    resumeFallbackSystemPrompt?: string;
+}
+export type AgentRunSpecField = keyof AgentRunSpec;
+export declare const AGENT_RUN_SPEC_FIELDS: readonly AgentRunSpecField[];
+/** A tool list a runner receives, with the command prefixes `Bash` is limited to. */
+type ToolList = {
+    readonly tools: readonly string[];
+    readonly bashAllowlist?: readonly string[] | undefined;
+};
+/**
+ * A step's tool list as the runner receives it, resolved once before the runner
+ * (hearsay-tools/cezarion#1810). The kind says where the list came from, so a
+ * runner can tell no list from the step default, a worker's inherited grant and
+ * a list someone wrote out. Each runner maps every kind in an exhaustive switch
+ * that ends in `unknownToolGrant`, so a new kind fails to compile in each one.
+ */
+export type ToolGrant = 
+/** No list: the harness keeps its own tool set. */
+{
+    readonly kind: 'unset';
+    readonly bashAllowlist?: readonly string[] | undefined;
+}
+/** The step sets no `allowedTools`: `allowedToolsForStep`'s default for this runner. */
+ | ({
+    readonly kind: 'step-default';
+} & ToolList)
+/** An owned worker's grant, pinned at spawn from its parent's. The identity keeps
+ *  only the list, so the parent's default and its written list look the same. */
+ | ({
+    readonly kind: 'inherited';
+} & ToolList)
+/** A list a workflow step or a cezar caller wrote out, an empty one included. */
+ | ({
+    readonly kind: 'explicit';
+} & ToolList);
+export type ToolGrantKind = ToolGrant['kind'];
+export declare const TOOL_GRANT_KINDS: readonly ToolGrantKind[];
+/** The `default` of a runner's switch over `ToolGrant['kind']`: only a kind it does not map reaches here. */
+export declare function unknownToolGrant(grant: never): never;
+/**
+ * What one runner does with one `AgentRunSpec` field. `honored` means setting
+ * the field changes what reaches the backend, and `via` names the flag, request
+ * field or process option it becomes. Not honored means the runner drops it,
+ * and `reason` says why the wire cannot carry it or which product decision left
+ * it unmapped — never "not implemented yet".
+ */
+export type SpecFieldSupport = {
+    readonly honored: true;
+    readonly via: string;
+} | {
+    readonly honored: false;
+    readonly reason: string;
+};
+/**
+ * A runner's declaration, one entry per `AgentRunSpec` field. The harness
+ * parity matrix drives each runner against its offline mock and fails any
+ * declaration the recorded boundary contradicts, in either direction
+ * (`harness-parity.test.ts`, #284) — so a caller reading `specSupport` reads
+ * what the backend actually receives, not what the adapter meant to send.
+ */
+export type AgentRunSpecSupport = Readonly<Record<AgentRunSpecField, SpecFieldSupport>>;
+/**
+ * Backends without a dedicated system-prompt channel (codex app-server,
+ * opencode serve) deliver `spec.systemPrompt` as a leading block of the
+ * opening user message — the documented per-backend mapping (spec §protocol
+ * v2: claude = `--append-system-prompt`, codex/opencode = prepended here).
+ */
+export declare function prependSystemPrompt(systemPrompt: string | undefined, userPrompt: string): string;
+/**
+ * True for the `128 + signal` exit codes an agent CLI reports when it handles
+ * a stop signal itself instead of dying from it (SIGINT/SIGKILL/SIGTERM).
+ *
+ * Every runner arms a SIGTERM→SIGKILL watchdog on `end()` and signals on
+ * `interrupt()` (#703): the CLIs install their own handlers, so a session the
+ * runner tore down on purpose comes back as a NON-ZERO exit. Paired with a
+ * "we sent the signal" flag, this predicate keeps that teardown out of the
+ * error path — an exit cezar caused is never an agent failure.
+ */
+export declare function isSignalTerminationExit(exitCode: number | null): boolean;
+/** The slice of `ChildProcess` a termination tracker needs — keeps the helper
+ *  usable from the transport layer and from test fakes alike. */
+export interface TrackableChild {
+    exitCode: number | null;
+    signalCode: NodeJS.Signals | null;
+    once(event: 'exit', listener: () => void): unknown;
+}
+/**
+ * Returns a predicate that answers "has this child actually terminated?".
+ *
+ * `ChildProcess.killed` answers a different question — it flips as soon as a
+ * signal is *delivered*, whether or not the child dies from it. Every agent CLI
+ * installs its own SIGTERM handler, so gating a SIGTERM→SIGKILL watchdog on
+ * `!child.killed` disables the escalation for exactly the child it exists for:
+ * `killed` is true, `exitCode` stays null, and the process outlives the whole
+ * grace window (#844, same defect fixed for the discovery probe in #841).
+ *
+ * Seeded from `exitCode`/`signalCode` so a child that died before the watchdog
+ * was armed is recognized without waiting for an event that already fired.
+ */
+export declare function trackChildExit(child: TrackableChild): () => boolean;
+/** One content block of a user message — mirrors the Anthropic wire format
+ *  so it can be written to the claude CLI's stdin verbatim. */
+export type ContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    source: {
+        type: 'base64';
+        media_type: string;
+        data: string;
+    };
+};
+/** Normalized event stream — the GUI renders these, the store persists them. */
+export type AgentEvent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool-call';
+    id: string;
+    tool: string;
+    input: unknown;
+} | {
+    type: 'tool-result';
+    toolCallId: string;
+    result: string;
+    isError: boolean;
+}
+/** An image inside a tool result (screenshot tools, Read on a PNG…) —
+ *  raw base64 here; the run manager persists it and re-emits a URL. */
+ | {
+    type: 'image';
+    mediaType: string;
+    data: string;
+} | {
+    type: 'token-usage';
+    tokensUsed: number;
+} | {
+    type: 'cost';
+    usd: number;
+}
+/** The backend's real session id, once known — codex threads and opencode
+ *  sessions mint their own id, so the run manager persists this to enable
+ *  resume ("Continue") and "open in CLI". Claude's equals `spec.sessionId`. */
+ | {
+    type: 'session';
+    sessionId: string;
+    sessionTransport?: SessionTransport;
+}
+/** `unconsumedInputIds`: agent input accepted in this turn that the model never
+ *  read before the turn ended idle (#505). */
+ | {
+    type: 'turn-end';
+    unconsumedInputIds?: readonly string[];
+}
+/** Accepted agent input the harness will not read without a new prompt, reported
+ *  outside a turn (an OpenCode lost wake) (#505). */
+ | {
+    type: 'input-unconsumed';
+    inputIds: readonly string[];
+} | {
+    type: 'note';
+    message: string;
+} | {
+    type: 'done';
+} | {
+    type: 'error';
+    message: string;
+};
+export interface AgentToolCallRecord {
+    id: string;
+    name: string;
+    input: unknown;
+}
+export interface AgentRunResult {
+    /** Concatenated assistant text across the run, trimmed. */
+    text: string;
+    toolCalls: AgentToolCallRecord[];
+    /** Cost-weighted token usage; 0 when the backend surfaced no telemetry. */
+    tokensUsed: number;
+    sessionId?: string | undefined;
+}
+export interface SessionOptions {
+    /** Native stdout/SSE activity, including progress and heartbeat frames that
+     * do not map to presentation events. Used by managed open-turn liveness. */
+    onActivity?: () => void;
+    /** Close the session shortly after the first turn ends (single-turn
+     *  behavior, used for non-interactive workflow steps). Interactive
+     *  sessions omit this and control `end()` themselves. */
+    autoEndAfterFirstTurn?: boolean | undefined;
+    /** Internal synchronous veto, checked when the auto-end timer fires. A held
+     * turn stays open; a later turn may auto-end normally. Explicit end/interrupt
+     * and provider failure still close the session. */
+    shouldAutoEnd?: () => boolean;
+    /** Protocol-v2 channel: receives the normalized `UiEvent` stream emitted
+     *  ALONGSIDE the v1 `AgentEvent`s (additive — v1 keeps flowing unchanged).
+     *  RunManager consumption lands in R2 step 2.1. */
+    onUiEvent?: (event: UiEvent) => void;
+    /** Readiness hint only, not an acknowledgement or a turn completion. The
+     * caller rechecks session identity, ask state and queue before retrying. */
+    onAgentInputReady?: (() => void) | undefined;
+    /** The model received these inputs (replay echo, userMessage item, …). Fires at most
+     * once per ID and never from a transport acknowledgement (#505). */
+    onAgentInputConsumed?: (inputIds: readonly string[]) => void;
+    /** The session's backend process was replaced after `startSession` returned (OMP's R13
+     *  respawn, OpenCode's retried `opencode serve` start — #872); `AgentSession.pid` already
+     *  names the new one. Callers that registered the
+     *  first pid for telemetry or cleanup register this one instead. */
+    onPidChange?: (pid: number) => void;
+}
+/**
+ * A live logical agent session. Most backends retain one process and read
+ * follow-ups from it. Cursor print replaces its process after each completed
+ * turn and resumes the same native session ID for follow-ups.
+ */
+export interface AgentSession {
+    /** Resolves when the backend process exits — the session is fully over. */
+    result: Promise<AgentRunResult>;
+    /** OS pid of the spawned backend process — the root of the run's process
+     *  tree (agents spawn Bash children under it). Absent when the spawn
+     *  failed before a pid existed. Feeds live resource telemetry (#348). */
+    readonly pid?: number | undefined;
+    /** Write a user message into the live session. False when it is closed. */
+    sendMessage(content: ContentBlock[]): boolean;
+    /** Resolve a native approval using opaque runner-owned request/option ids. */
+    respondPermission?(requestId: string, optionId: string): boolean;
+    /** Synchronous non-human reservation: false refuses without writing; a Promise
+     * confirms the HARNESS ACCEPTED the input — mid-turn on a `steer` runner — not that
+     * the model consumed it (#505). Reject retains caller ownership for replay.
+     * `inputIds` correlate `onAgentInputConsumed` and `turn-end.unconsumedInputIds`.
+     * Never fall back to the human-answer seam. */
+    sendAgentMessage(content: ContentBlock[], inputIds?: readonly string[]): false | Promise<void>;
+    /**
+     * Drop follow-ups queued while a turn was still in flight. A turn end that
+     * surfaces a question (a `cezar_ask` card or the human gate) calls this so a
+     * mid-turn `sendMessage` cannot start a new turn after the question. Backends
+     * that never queue (they write or steer immediately) no-op.
+     */
+    discardQueuedMessages(): void;
+    /** True while this session still holds a human follow-up from `sendMessage`
+     *  that the model has not consumed and that the runner will still deliver (#486).
+     *  A held input releases only when (a) the normalized `turn.started` of the turn
+     *  that carries it has been emitted, (b) it is read inside an open normalized turn,
+     *  or (c) a rejection or a close means it can never start, or a
+     *  `discardQueuedMessages` drops it. A discard cannot retract an input the wire
+     *  already wrote or spawned: the runner then either drops only the hold, and the
+     *  input can still run, or keeps the hold because its discard is a no-op (the H2
+     *  entries of `PARITY_EXEMPTIONS`). Close needs no runner code: run.ts reads
+     *  the hold only while the session is `open`. A native ack, a native run-start
+     *  frame, a spawn or a queue shift is not a release on its own; it releases only
+     *  when one of those exits already holds. run.ts parks a boundary whose hold reads
+     *  false (hearsay-tools/cezarion#1112). A held follow-up that
+     *  drains at an idle boundary without opening a new turn must call
+     *  `onAgentInputReady` so run.ts can re-settle that boundary; the 250 ms recheck is
+     *  the backstop. Each runner's hold comment lists its exit frames. */
+    holdsHumanInput(): boolean;
+    /** Count of human follow-ups still held behind `holdsHumanInput`. Every built-in
+     *  runner reports it from the same state `holdsHumanInput` reads
+     *  (`holdsHumanInput() === count > 0`). Optional only on wrappers and test fakes. */
+    heldHumanInputCount?(): number;
+    /** Graceful close: end input, then a SIGTERM→SIGKILL watchdog. */
+    end(): void;
+    /** Hard stop (used by cancel). */
+    interrupt(): void;
+    /** True while the session still accepts messages. */
+    readonly open: boolean;
+}
+/**
+ * How a runner admits input while a turn runs (hearsay-tools/cezarion#505). The fields shared by both modes; a
+ * runner declares one of the `InputDelivery` variants.
+ */
+interface InputDeliveryFacts {
+    /** Whether the wire tells us when the model actually received the input. */
+    readonly consumption: 'observable' | 'unobservable';
+    /**
+     * What resolves `sendAgentMessage`'s Promise (hearsay-tools/cezarion#2991). `write`: the local
+     * pipe write, so the provider can neither delay nor reject it (Claude's stdin). `response`: a
+     * native response to the submission, apart from the turn's frames (an RPC result, an HTTP
+     * acknowledgement, a prompt response id). `model-work`: the first model-work frame of the
+     * turn the input opens, so no turn can end before its input is acknowledged (Cursor print).
+     */
+    readonly acknowledgement: 'write' | 'response' | 'model-work';
+    /** The native mechanism. Documentation only: no code branches on it. */
+    readonly via: string;
+}
+/**
+ * `steer`: non-human input is accepted mid-turn and consumed inside the running turn.
+ * `boundary`: it is refused while busy.
+ *
+ * `humanInputAtTurnEnd` says whether a human `sendMessage` written while a turn runs can still
+ * be held, unread, when that turn ends (hearsay-tools/cezarion#2991); turn-end code then keeps
+ * the session for the turn it opens. `never-held`: the harness always reads it inside the
+ * running turn. `held-when-late`: it reads it in the running turn, unless it arrives after the
+ * turn's last model call; then the harness holds it and it opens the next turn.
+ * `always-held`: the harness queues it until the running turn ends, and it opens the next turn.
+ * A boundary runner has no mid-turn input channel, so the type fixes it to `always-held`. A
+ * message written after the harness already ended the turn natively is not mid-turn input.
+ */
+export type InputDelivery = InputDeliveryFacts & ({
+    readonly mode: 'steer';
+    readonly humanInputAtTurnEnd: 'never-held' | 'held-when-late' | 'always-held';
+} | {
+    readonly mode: 'boundary';
+    readonly humanInputAtTurnEnd: 'always-held';
+});
+export declare const BOUNDARY_INPUT_DELIVERY: InputDelivery;
+/** Absent means the pre-#505 behavior every runner had. */
+export declare function inputDeliveryOf(runner: Pick<AgentRunner, 'inputDelivery'>): InputDelivery;
+/**
+ * How this runner delivers `spec.systemPrompt` across session/process boundaries (#790).
+ *
+ * - `resent`: every session/process receives `spec.systemPrompt` again. Claude
+ *   `--resume` keeps the launch `--append-system-prompt` and ignores new flags
+ *   (resending is harmless; changed extra/delegation/artifact/handoff
+ *   instructions never reach a resumed session). Pi `--session` *replaces*
+ *   stored prompt sections with the new flags, so resend is required — a
+ *   resumed skill task lacks the playbook unless the caller sends it. OMP was
+ *   not live-verified (not installed here) and is declared `resent` as the
+ *   safe value.
+ * - `in-thread`: the system prompt was prepended into the opening turn and is
+ *   part of the resumed thread's history (OpenCode, Codex, Cursor). Re-sending
+ *   the skill on the same session duplicates it; a fresh-session continuation
+ *   (no `sessionId`, or OpenCode's lost-session fallback) still needs it.
+ *
+ * The flag is the caller's dedupe policy for the skill prefix, not a statement
+ * that in-thread runners ignore `systemPrompt` on resume. Codex, Cursor and
+ * OpenCode still re-prepend the whole `spec.systemPrompt` (extra prompt + handoff)
+ * on every resumed opening turn; Continue omits only the skill prefix on a
+ * same-session in-thread resume.
+ */
+export type SystemPromptOnResume = 'resent' | 'in-thread';
+/** Builds the runner for a backend id. The engine depends on this type only; the entry points
+ *  pass `createRunner` from `runner-factory.ts`, which knows every adapter, and a test passes a
+ *  factory for the one runner it drives (hearsay-tools/cezarion#2939). */
+export type RunnerFactory = (backend: AgentBackend | RunnerId | undefined, options?: {
+    sessionTransport?: SessionTransport;
+}) => AgentRunner;
+export interface AgentRunner {
+    readonly backend: AgentBackend;
+    /** Which `AgentRunSpec` fields this runner honors, and how — see `AgentRunSpecSupport`. */
+    readonly specSupport: AgentRunSpecSupport;
+    /** How this runner carries `spec.systemPrompt` onto a resumed session (#790). Required. */
+    readonly systemPromptOnResume: SystemPromptOnResume;
+    /** How non-human input is admitted while a turn runs; absent means `boundary` (#505). */
+    readonly inputDelivery?: InputDelivery;
+    /** This runner's row of `RUNNER_FACTS` (hearsay-tools/cezarion#2991). Every built-in runner
+     *  declares it; optional only on wrappers and test fakes. Shared code reads the table by id. */
+    readonly facts?: RunnerFacts;
+    run(spec: AgentRunSpec, onEvent?: (event: AgentEvent) => void): Promise<AgentRunResult>;
+    startSession(spec: AgentRunSpec, onEvent?: (event: AgentEvent) => void, opts?: SessionOptions): AgentSession;
+    interrupt(): Promise<void>;
+}
+export {};

package/dist/core/agent-runner.js

@@ -0,0 +1,98 @@
+/**
+ * Backend-neutral logical sessions for task execution, follow-ups, waiting, interrupt and
+ * resume. Adapters own native process lifetimes and emit normalized events behind this seam.
+ */
+/**
+ * Canonical user-selectable runner tuple in display order. Derive runtime enumerations and
+ * schemas from this set; keep legacy backend ids separate for persisted records.
+ */
+export const RUNNER_IDS = ['claude', 'codex', 'opencode', 'pi', 'cursor', 'omp'];
+/** Narrow an arbitrary string (a config value, a check name) to a runner id. */
+export function isRunnerId(value) {
+    return RUNNER_IDS.includes(value);
+}
+/**
+ * Every `AgentRunSpec` field, as a runtime list. Typed as a full `Record` over
+ * `keyof AgentRunSpec`, so the interface gaining or losing a field is a compile
+ * error here — and, through `AgentRunSpecSupport`, in every runner (#284).
+ */
+const AGENT_RUN_SPEC_FIELD_SET = {
+    systemPrompt: true,
+    cezarTools: true,
+    userPrompt: true,
+    images: true,
+    cwd: true,
+    toolGrant: true,
+    restrictCrossSessionMessaging: true,
+    additionalDirectories: true,
+    env: true,
+    model: true,
+    effort: true,
+    timeoutMs: true,
+    sessionId: true,
+    resume: true,
+    resumeFallbackSystemPrompt: true,
+};
+export const AGENT_RUN_SPEC_FIELDS = Object.keys(AGENT_RUN_SPEC_FIELD_SET);
+/** Every `ToolGrant` kind, as a runtime list; a `Record`, so a new kind is a compile error here. */
+const TOOL_GRANT_KIND_SET = {
+    unset: true,
+    'step-default': true,
+    inherited: true,
+    explicit: true,
+};
+export const TOOL_GRANT_KINDS = Object.keys(TOOL_GRANT_KIND_SET);
+/** The `default` of a runner's switch over `ToolGrant['kind']`: only a kind it does not map reaches here. */
+export function unknownToolGrant(grant) {
+    throw new Error(`Unknown tool grant kind: ${String(grant.kind)}`);
+}
+/**
+ * Backends without a dedicated system-prompt channel (codex app-server,
+ * opencode serve) deliver `spec.systemPrompt` as a leading block of the
+ * opening user message — the documented per-backend mapping (spec §protocol
+ * v2: claude = `--append-system-prompt`, codex/opencode = prepended here).
+ */
+export function prependSystemPrompt(systemPrompt, userPrompt) {
+    return systemPrompt ? `${systemPrompt}\n\n---\n\n${userPrompt}` : userPrompt;
+}
+/**
+ * True for the `128 + signal` exit codes an agent CLI reports when it handles
+ * a stop signal itself instead of dying from it (SIGINT/SIGKILL/SIGTERM).
+ *
+ * Every runner arms a SIGTERM→SIGKILL watchdog on `end()` and signals on
+ * `interrupt()` (#703): the CLIs install their own handlers, so a session the
+ * runner tore down on purpose comes back as a NON-ZERO exit. Paired with a
+ * "we sent the signal" flag, this predicate keeps that teardown out of the
+ * error path — an exit cezar caused is never an agent failure.
+ */
+export function isSignalTerminationExit(exitCode) {
+    return exitCode === 130 || exitCode === 137 || exitCode === 143;
+}
+/**
+ * Returns a predicate that answers "has this child actually terminated?".
+ *
+ * `ChildProcess.killed` answers a different question — it flips as soon as a
+ * signal is *delivered*, whether or not the child dies from it. Every agent CLI
+ * installs its own SIGTERM handler, so gating a SIGTERM→SIGKILL watchdog on
+ * `!child.killed` disables the escalation for exactly the child it exists for:
+ * `killed` is true, `exitCode` stays null, and the process outlives the whole
+ * grace window (#844, same defect fixed for the discovery probe in #841).
+ *
+ * Seeded from `exitCode`/`signalCode` so a child that died before the watchdog
+ * was armed is recognized without waiting for an event that already fired.
+ */
+export function trackChildExit(child) {
+    let exited = child.exitCode != null || child.signalCode != null;
+    child.once('exit', () => {
+        exited = true;
+    });
+    return () => exited;
+}
+export const BOUNDARY_INPUT_DELIVERY = {
+    mode: 'boundary', consumption: 'unobservable', acknowledgement: 'response', humanInputAtTurnEnd: 'always-held', via: 'next idle turn',
+};
+/** Absent means the pre-#505 behavior every runner had. */
+export function inputDeliveryOf(runner) {
+    return runner.inputDelivery ?? BOUNDARY_INPUT_DELIVERY;
+}
+//# sourceMappingURL=agent-runner.js.map

package/dist/core/agent-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runner.js","sourceRoot":"","sources":["../../src/core/agent-runner.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAU,CAAC;AAQ1F,gFAAgF;AAChF,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAQ,UAAgC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC3D,CAAC;AAuDD;;;;GAIG;AACH,MAAM,wBAAwB,GAA+C;IAC3E,YAAY,EAAE,IAAI;IAClB,UAAU,EAAE,IAAI;IAChB,UAAU,EAAE,IAAI;IAChB,MAAM,EAAE,IAAI;IACZ,GAAG,EAAE,IAAI;IACT,SAAS,EAAE,IAAI;IACf,6BAA6B,EAAE,IAAI;IACnC,qBAAqB,EAAE,IAAI;IAC3B,GAAG,EAAE,IAAI;IACT,KAAK,EAAE,IAAI;IACX,MAAM,EAAE,IAAI;IACZ,SAAS,EAAE,IAAI;IACf,SAAS,EAAE,IAAI;IACf,MAAM,EAAE,IAAI;IACZ,0BAA0B,EAAE,IAAI;CACjC,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC,IAAI,CAAC,wBAAwB,CAAiC,CAAC;AAwB3G,oGAAoG;AACpG,MAAM,mBAAmB,GAA0C;IACjE,KAAK,EAAE,IAAI;IACX,cAAc,EAAE,IAAI;IACpB,SAAS,EAAE,IAAI;IACf,QAAQ,EAAE,IAAI;CACf,CAAC;AACF,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,IAAI,CAAC,mBAAmB,CAA6B,CAAC;AAE7F,6GAA6G;AAC7G,MAAM,UAAU,gBAAgB,CAAC,KAAY;IAC3C,MAAM,IAAI,KAAK,CAAC,4BAA4B,MAAM,CAAE,KAA4B,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC5F,CAAC;AAsBD;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,YAAgC,EAAE,UAAkB;IACtF,OAAO,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,cAAc,UAAU,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC;AAC/E,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAuB;IAC7D,OAAO,QAAQ,KAAK,GAAG,IAAI,QAAQ,KAAK,GAAG,IAAI,QAAQ,KAAK,GAAG,CAAC;AAClE,CAAC;AAUD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAAC,KAAqB;IAClD,IAAI,MAAM,GAAG,KAAK,CAAC,QAAQ,IAAI,IAAI,IAAI,KAAK,CAAC,UAAU,IAAI,IAAI,CAAC;IAChE,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE;QACtB,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC;AACtB,CAAC;AAyKD,MAAM,CAAC,MAAM,uBAAuB,GAAkB;IACpD,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe,EAAE,UAAU,EAAE,mBAAmB,EAAE,aAAa,EAAE,GAAG,EAAE,gBAAgB;CACtI,CAAC;AACF,2DAA2D;AAC3D,MAAM,UAAU,eAAe,CAAC,MAA0C;IACxE,OAAO,MAAM,CAAC,aAAa,IAAI,uBAAuB,CAAC;AACzD,CAAC"}

package/dist/core/ask.d.ts

@@ -0,0 +1,26 @@
+import type { UiAskQuestion } from './ui-events.ts';
+/**
+ * AskUser payload — the structured multiple-choice question an agent asks the
+ * user, so the cockpit can render clickable option chips instead of the prose
+ * fallback ("AskUserQuestion isn't available…"). See the spec
+ * `.ai/specs/2026-07-18-askuser-across-runners.md`.
+ *
+ * An agent raises it with the `cezar_ask` lifecycle tool; Codex and OpenCode
+ * native questions map onto the same shape (`parseAskRequest`). The shape is
+ * modeled 1:1 on Claude Code's built-in `AskUserQuestion` (1–4 questions, 2–4
+ * options each, `header` ≤12 chars, unique question texts and unique option
+ * labels). A free-text "Other" is always available via the composer, so it is
+ * never an explicit option. The retired `CEZ:ASK` text marker is plain text
+ * (hearsay-tools/cezarion#2397).
+ */
+import { type AskRequest } from '../contract/index.js';
+export { askOptionSchema, askQuestionSchema, askRequestSchema, type AskOption, type AskQuestion, type AskRequest } from '../contract/index.js';
+/**
+ * Parse a value into a validated `AskRequest`, or `null` when it does not match
+ * (bad counts, over-length header, non-unique labels/questions, extra keys).
+ * Callers degrade to plain text on `null` — the feature never makes the prose
+ * fallback worse.
+ */
+export declare function parseAskRequest(value: unknown): AskRequest | null;
+/** Project validated asks to the SSE shape with absent optional fields. */
+export declare function uiAskQuestions(questions: AskRequest['questions']): UiAskQuestion[];