@yul-labs/agent-relay 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,1698 @@
+import { z } from 'zod';
+
+/**
+ * Deciders answer the approval / choice / input prompts that a coding agent
+ * raises during an INTERACTIVE run. This is the heart of the project's core
+ * feature: instead of suppressing prompts (the old non-interactive approach),
+ * agent-relay lets the agent ask, detects the question, and a Decider — a rule
+ * policy, an LLM (via a CLI like `claude -p` / `codex exec`), or any plugged-in
+ * function/API — produces the answer that is fed back into the session.
+ *
+ * Deciders are pluggable and vendor-agnostic; the interactive adapters call
+ * `decide()` and translate the result into keystrokes / protocol responses.
+ */
+type InteractionKind = "approval" | "choice" | "input";
+/** A prompt the agent is waiting on, surfaced to the Decider. */
+interface InteractionRequest {
+    kind: InteractionKind;
+    /** The cleaned prompt text the agent is showing. */
+    prompt: string;
+    /** The original task/goal the agent is working on — lets a decider judge
+     *  whether a risky action is ON-task (allow) or OFF-task (redirect). */
+    task?: string;
+    /** For `choice`: the visible options/menu items, in display order. */
+    options?: string[];
+    /** For a MULTI-select choice: true, and `checked` carries each option's
+     *  current state. The decider returns the DESIRED set in `optionIndexes`. */
+    multiSelect?: boolean;
+    /** For a multi-select: current checked state per option (aligned to `options`). */
+    checked?: boolean[];
+    /** Recent transcript / surrounding context to inform the decision. */
+    context?: string;
+    /** Working directory of the run. */
+    cwd?: string;
+    /** Which agent is asking (`claude` / `codex` / ...). */
+    agent?: string;
+}
+type DecisionAction = "approve" | "deny" | "select" | "answer" | "abort";
+/** The Decider's answer to an {@link InteractionRequest}. */
+interface InteractionDecision {
+    action: DecisionAction;
+    /** For `select`: index into `request.options`. */
+    optionIndex?: number;
+    /** For a MULTI-select `select`: the DESIRED set of checked indices. The keymap
+     *  toggles only the options whose current `checked` state differs, then submits. */
+    optionIndexes?: number[];
+    /** For `answer`: free-text response. */
+    text?: string;
+    /** Why this decision was made (for logging/observability). */
+    reason?: string;
+    /** Which decider produced this. */
+    by?: string;
+}
+/** The pluggable contract every decider implements. */
+interface Decider {
+    readonly name: string;
+    decide(req: InteractionRequest): Promise<InteractionDecision>;
+}
+interface RuleDeciderOptions {
+    /** If the prompt/command matches any, deny (or pick a negative choice). */
+    denyPatterns?: RegExp[];
+    /** Default stance for approvals that match no deny pattern. */
+    defaultApproval?: "approve" | "deny";
+    /** Recognizes an affirmative option ("Yes", "Proceed", "Allow", ...). */
+    affirmativePattern?: RegExp;
+    /** Recognizes a negative option ("No", "Cancel", "Reject", ...). */
+    negativePattern?: RegExp;
+    /** Default free-text answer for `input` prompts. */
+    defaultAnswer?: string;
+    name?: string;
+}
+/** Conservative default patterns for genuinely dangerous actions. */
+declare const DEFAULT_DENY_PATTERNS: RegExp[];
+declare class RuleDecider implements Decider {
+    readonly name: string;
+    private readonly opts;
+    constructor(options?: RuleDeciderOptions);
+    private isDangerous;
+    decide(req: InteractionRequest): Promise<InteractionDecision>;
+}
+/** Approve everything (mirror of the old AutoApprovalGate, as a Decider). */
+declare class AlwaysApproveDecider implements Decider {
+    readonly name = "always-approve";
+    decide(req: InteractionRequest): Promise<InteractionDecision>;
+}
+declare class FunctionDecider implements Decider {
+    private readonly fn;
+    readonly name: string;
+    constructor(fn: (req: InteractionRequest) => InteractionDecision | Promise<InteractionDecision>, name?: string);
+    decide(req: InteractionRequest): Promise<InteractionDecision>;
+}
+interface CommandDeciderOptions {
+    /** The decider model command, e.g. "claude" or "codex". */
+    command: string;
+    /** Args, e.g. ["-p","--output-format","json"] for claude print mode. */
+    args?: string[];
+    env?: Record<string, string>;
+    /** Build the model prompt from a request. */
+    renderPrompt?: (req: InteractionRequest) => string;
+    timeoutMs?: number;
+    /** Decision used if the model errors / times out / is unparseable. */
+    fallback?: InteractionDecision;
+    name?: string;
+}
+/**
+ * Default rendering. The policy biases STRONGLY toward letting the agent work:
+ * approve by default so the task progresses, and only deny when an action is
+ * both dangerous AND unrelated to the task — in which case the model supplies a
+ * short redirect comment. (This judgment needs the task, which is why it cannot
+ * be a regex rule.)
+ */
+declare function renderDecisionPrompt(req: InteractionRequest): string;
+/** Lenient parse of a model's textual reply into an InteractionDecision. */
+declare function parseDecisionReply(reply: string): InteractionDecision | undefined;
+declare class CommandDecider implements Decider {
+    readonly name: string;
+    private readonly opts;
+    constructor(options: CommandDeciderOptions);
+    decide(req: InteractionRequest): Promise<InteractionDecision>;
+}
+interface ApiDeciderOptions {
+    /** Full chat-completions URL, e.g. http://localhost:9090/v1/chat/completions */
+    url: string;
+    model?: string;
+    apiKey?: string;
+    /**
+     * Cap on tokens the model may generate per decision (NOT a target — the model
+     * stops at its stop token, so a normal decision still costs only what it needs).
+     * Default 2048. Reasoning models emit a long chain-of-thought before the JSON
+     * answer, so a too-small cap (e.g. a few hundred) truncates them mid-thought,
+     * leaving an empty `content` and an unparseable reply → safe-deny. Raise it
+     * (not lower) for verbose reasoning models.
+     */
+    maxTokens?: number;
+    temperature?: number;
+    timeoutMs?: number;
+    renderPrompt?: (req: InteractionRequest) => string;
+    fallback?: InteractionDecision;
+    name?: string;
+}
+declare class ApiDecider implements Decider {
+    private readonly opts;
+    readonly name: string;
+    constructor(opts: ApiDeciderOptions);
+    decide(req: InteractionRequest): Promise<InteractionDecision>;
+}
+type DeciderType = "rule" | "always-approve" | "command" | "api";
+/** Plain config object describing which decider to use (mirrors the zod schema). */
+interface DeciderConfig {
+    type: DeciderType;
+    /** rule: regex strings that trigger a deny / negative choice. */
+    denyPatterns?: string[];
+    /** rule: stance for non-dangerous approvals. */
+    defaultApproval?: "approve" | "deny";
+    /** rule: default text for `input` prompts. */
+    defaultAnswer?: string;
+    /** command: the model CLI to invoke and its args. */
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    /** api: OpenAI-compatible chat-completions endpoint + model. */
+    url?: string;
+    model?: string;
+    apiKey?: string;
+    maxTokens?: number;
+}
+/** Build a {@link Decider} from config. Defaults to a {@link RuleDecider}. */
+declare function createDecider(config?: DeciderConfig): Decider;
+
+/**
+ * Core type contracts for agent-relay.
+ *
+ * IMPORTANT: This module is the seam that keeps the core vendor-agnostic.
+ * Nothing in `core/` may import Claude/Codex-specific code; everything talks
+ * to the {@link AgentAdapter} interface defined here. Concrete adapters live
+ * under `src/adapters/` and depend on these types, never the other way around.
+ */
+/**
+ * How an adapter talks to its underlying agent.
+ *
+ * - `pty`  : drive the agent's real interactive TUI through a pseudo-terminal.
+ *            This is the primary mode for Claude/Codex.
+ * - `test` : in-process deterministic adapter used for tests / dry runs.
+ */
+type AdapterMode = "pty" | "test";
+/**
+ * How much autonomy the underlying agent is granted for a run.
+ *
+ * - `auto`     : the agent acts without asking — the orchestrator auto-approves
+ *                every action (the default for "run while I sleep" automation).
+ * - `gated`    : risky actions are deferred to an {@link ApprovalGate} handler;
+ *                without one they pause the run (status `waiting_approval`).
+ * - `readonly` : the agent may inspect but not mutate (plan / read-only sandbox).
+ */
+type ApprovalMode = "auto" | "gated" | "readonly";
+/** Sandbox strength for process-spawning agents (maps to vendor flags). */
+type SandboxLevel = "read-only" | "workspace-write" | "danger-full-access";
+/**
+ * The normalized event types every adapter emits, regardless of vendor.
+ * Adapters translate their native event streams into these.
+ */
+type AgentEventType = "start" | "stdout" | "stderr" | "json" | "assistant_message" | "tool_call" | "tool_result" | "status" | "error" | "complete";
+/** A single normalized event in an agent run. */
+interface AgentEvent {
+    type: AgentEventType;
+    /** ISO-8601 timestamp of when the event was observed. */
+    timestamp: string;
+    /** Human-readable text payload, when applicable (assistant text, log line). */
+    text?: string;
+    /** Structured payload (parsed JSON, tool input/output, usage, etc). */
+    data?: unknown;
+    /** The raw, unparsed source line, preserved for debugging/logging. */
+    raw?: string;
+}
+/**
+ * A pointer to an underlying agent session so it can later be resumed.
+ * `nativeSessionId` is the vendor's own id (Codex thread id, Claude session id).
+ */
+interface AgentSessionRef {
+    adapter: string;
+    nativeSessionId?: string;
+    resumable: boolean;
+}
+/** Everything an adapter needs to perform a single run. */
+interface AgentRunInput {
+    /** The task prompt to hand to the agent. */
+    prompt: string;
+    /** Working directory the agent should operate in. */
+    cwd: string;
+    /** Safety cap on the number of assistant turns. */
+    maxTurns: number;
+    /** Hard wall-clock timeout in milliseconds. */
+    timeoutMs: number;
+    /** Idle timeout: abort if no event is observed for this long. */
+    idleTimeoutMs: number;
+    /** When true, no real process is spawned; only a command preview is produced. */
+    dryRun?: boolean;
+    /** When resuming, the native session reference to continue from. */
+    resume?: AgentSessionRef;
+    /** Extra args appended to the underlying command (escape hatch). */
+    extraArgs?: string[];
+    /** Autonomy level: how the agent's risky actions are approved. */
+    approvalMode?: ApprovalMode;
+    /** Sandbox strength for process-spawning agents. */
+    sandbox?: SandboxLevel;
+    /**
+     * Interactive (PTY) only: how long the agent must produce no output and show
+     * no prompt before the session decides the task is complete and quits the
+     * TUI. Lower = faster termination but more risk of quitting mid-think.
+     */
+    completionIdleMs?: number;
+    /**
+     * Claude only: get the full "ultracode" preset (xhigh effort + dynamic workflow
+     * orchestration) on an UNATTENDED run. The adapter uses an xhigh-capable model
+     * (`--model opus`, required) and drives `/effort ultracode` in the TUI before
+     * the task. (Plain `--effort xhigh` is the default and needs no model change.)
+     */
+    ultracode?: boolean;
+    /** Arbitrary extra options interpreted by specific adapters (e.g. fake). */
+    options?: Record<string, unknown>;
+}
+/** The terminal result an adapter returns from {@link AgentAdapter.run}. */
+interface AgentRunResult {
+    /** Whether the adapter believes the run finished successfully. */
+    success: boolean;
+    /** Process exit code, or null for non-process adapters / aborted runs. */
+    exitCode: number | null;
+    /** Native session reference for resume, if the adapter produced one. */
+    sessionRef?: AgentSessionRef;
+    /** The agent's final assistant message, if captured. */
+    finalMessage?: string;
+    /** True if the run was aborted via the provided AbortSignal. */
+    aborted?: boolean;
+    /** Structured error info when the run failed (friendly, not a raw stack). */
+    error?: AgentErrorInfo;
+    /** Free-form metadata (token usage, cost, turn counts, ...). */
+    meta?: Record<string, unknown>;
+}
+/** Friendly, structured error info surfaced by adapters (never a raw throw). */
+interface AgentErrorInfo {
+    message: string;
+    /** Stable code, e.g. `COMMAND_NOT_FOUND`, `SPAWN_FAILED`, `NON_ZERO_EXIT`. */
+    code?: string;
+    /** Optional remediation hint shown to the user. */
+    hint?: string;
+}
+/** Result of an adapter availability probe. */
+interface AdapterAvailability {
+    ok: boolean;
+    /** Why the adapter is unavailable (friendly message). */
+    reason?: string;
+    /** Detected version string, when discoverable. */
+    version?: string;
+    /** Remediation hint, e.g. install instructions. */
+    hint?: string;
+}
+/** A human-facing preview of the command an adapter would execute. */
+interface CommandPreview {
+    mode: AdapterMode;
+    command: string;
+    args: string[];
+    /** Whether the prompt is delivered over stdin rather than as an arg. */
+    promptViaStdin?: boolean;
+    /** Display string, e.g. `codex exec --json "<prompt>"`. */
+    display: string;
+}
+/**
+ * The runtime context the runner passes to an adapter. The adapter pushes
+ * normalized events via {@link onEvent} and must honor {@link signal} for
+ * cancellation (timeout / idle / Ctrl-C). Keeping this callback-based (rather
+ * than returning an async iterator) makes the control flow easy to test and to
+ * race against timers in the runner.
+ */
+interface AdapterRunContext {
+    /** Aborts when the runner decides to stop (timeout, idle, signal, maxTurns). */
+    signal: AbortSignal;
+    /** Push a normalized event to the runner. */
+    onEvent: (event: AgentEvent) => void;
+    /** Working directory (mirror of input.cwd, provided for convenience). */
+    cwd: string;
+    /**
+     * Answers the approval / choice / input prompts an INTERACTIVE agent raises.
+     * Interactive (PTY) adapters consult this for every detected prompt — it is
+     * the runtime hook that actually handles user-approval situations.
+     */
+    decider?: Decider;
+}
+/** Static description of an adapter, used by the registry and `adapters` cmd. */
+interface AgentAdapterDefinition {
+    /** Registry key / adapter name as used on the CLI (`claude`, `codex`, ...). */
+    name: string;
+    /** Adapter family/type (from config; usually equals `name`). */
+    type: string;
+    /** Execution mode. */
+    mode: AdapterMode;
+    /** One-line human description. */
+    description: string;
+    /** Whether this adapter can resume previous sessions. */
+    supportsResume: boolean;
+}
+/**
+ * The single interface every agent integration must implement. The core only
+ * ever depends on this; vendor specifics stay inside implementations.
+ */
+interface AgentAdapter {
+    readonly definition: AgentAdapterDefinition;
+    /** Probe whether the adapter can actually run (command present, key set...). */
+    isAvailable(): Promise<AdapterAvailability>;
+    /** Describe (but do not execute) the command for a given input. */
+    describeCommand(input: AgentRunInput): CommandPreview;
+    /** Execute a run, emitting events via ctx.onEvent and resolving a result. */
+    run(input: AgentRunInput, ctx: AdapterRunContext): Promise<AgentRunResult>;
+    /**
+     * Resume a previous session with a follow-up prompt. Optional: adapters that
+     * cannot resume omit this. Implementations should honor the same context
+     * contract as {@link run}.
+     */
+    resume?(ref: AgentSessionRef, input: AgentRunInput, ctx: AdapterRunContext): Promise<AgentRunResult>;
+}
+/** Lifecycle status of a relay session. */
+type SessionStatus = "created" | "running" | "completed" | "failed" | "timeout" | "cancelled" | "waiting_approval";
+/** Persisted metadata for a single session. */
+interface SessionMetadata {
+    sessionId: string;
+    prompt: string;
+    adapter: string;
+    mode: AdapterMode;
+    status: SessionStatus;
+    cwd: string;
+    dryRun: boolean;
+    startedAt: string;
+    endedAt?: string;
+    logFile: string;
+    exitCode?: number | null;
+    error?: AgentErrorInfo;
+    /** Native session reference enabling resume. */
+    sessionRef?: AgentSessionRef;
+    /** Free-form metadata captured from the adapter result. */
+    meta?: Record<string, unknown>;
+}
+/** Reason the runner aborted a run before the adapter finished naturally. */
+type AbortReason = "timeout" | "idle" | "cancel" | "maxTurns";
+
+/** Config schema (zod), defaults, and load/save helpers. */
+
+/** The canonical config file name created by `agent-relay init`. */
+declare const CONFIG_FILENAME = "agent-relay.config.json";
+declare const approvalPolicySchema: z.ZodEnum<["auto", "gated", "readonly"]>;
+declare const sandboxSchema: z.ZodEnum<["read-only", "workspace-write", "danger-full-access"]>;
+/**
+ * Per-adapter configuration. `command`/`args` are only meaningful for adapters
+ * that spawn a process; the in-process `fake`/`test` adapter omits them.
+ */
+declare const adapterConfigSchema: z.ZodObject<{
+    type: z.ZodString;
+    mode: z.ZodEnum<["pty", "test"]>;
+    command: z.ZodOptional<z.ZodString>;
+    args: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Extra env vars to inject when spawning. */
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    /** Per-adapter approval override (falls back to defaults). */
+    approvalPolicy: z.ZodOptional<z.ZodEnum<["auto", "gated", "readonly"]>>;
+    /** Per-adapter sandbox override (falls back to defaults). */
+    sandbox: z.ZodOptional<z.ZodEnum<["read-only", "workspace-write", "danger-full-access"]>>;
+}, "strict", z.ZodTypeAny, {
+    type: string;
+    mode: "pty" | "test";
+    args: string[];
+    approvalPolicy?: "auto" | "gated" | "readonly" | undefined;
+    sandbox?: "read-only" | "workspace-write" | "danger-full-access" | undefined;
+    command?: string | undefined;
+    env?: Record<string, string> | undefined;
+}, {
+    type: string;
+    mode: "pty" | "test";
+    approvalPolicy?: "auto" | "gated" | "readonly" | undefined;
+    sandbox?: "read-only" | "workspace-write" | "danger-full-access" | undefined;
+    command?: string | undefined;
+    args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+}>;
+type AdapterConfig = z.infer<typeof adapterConfigSchema>;
+declare const defaultsSchema: z.ZodObject<{
+    maxTurns: z.ZodDefault<z.ZodNumber>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    idleTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Default autonomy level. `auto` (the default) makes runs fully
+     * unattended — the orchestrator auto-approves and the agent CLIs are
+     * launched with their non-interactive "don't ask" flags.
+     */
+    approvalPolicy: z.ZodOptional<z.ZodEnum<["auto", "gated", "readonly"]>>;
+    /** Default sandbox strength for process-spawning agents. */
+    sandbox: z.ZodOptional<z.ZodEnum<["read-only", "workspace-write", "danger-full-access"]>>;
+    /** Interactive: idle window before a finished agent's TUI is quit (ms). */
+    completionIdleMs: z.ZodOptional<z.ZodNumber>;
+    /**
+     * Legacy flag. When `approvalPolicy` is unset, `true` -> `gated` and
+     * `false` -> `auto`. Kept for back-compat; prefer `approvalPolicy`.
+     */
+    requireApprovalOnRiskyActions: z.ZodDefault<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    maxTurns: number;
+    timeoutMs: number;
+    idleTimeoutMs: number;
+    requireApprovalOnRiskyActions: boolean;
+    approvalPolicy?: "auto" | "gated" | "readonly" | undefined;
+    sandbox?: "read-only" | "workspace-write" | "danger-full-access" | undefined;
+    completionIdleMs?: number | undefined;
+}, {
+    maxTurns?: number | undefined;
+    timeoutMs?: number | undefined;
+    idleTimeoutMs?: number | undefined;
+    approvalPolicy?: "auto" | "gated" | "readonly" | undefined;
+    sandbox?: "read-only" | "workspace-write" | "danger-full-access" | undefined;
+    completionIdleMs?: number | undefined;
+    requireApprovalOnRiskyActions?: boolean | undefined;
+}>;
+type RelayDefaults = z.infer<typeof defaultsSchema>;
+/** Resolve the effective approval mode (adapter override > defaults > legacy). */
+declare function resolveApprovalMode(defaults: RelayDefaults, adapter?: AdapterConfig): ApprovalMode;
+/** Resolve the effective sandbox level (adapter override > defaults > default). */
+declare function resolveSandbox(defaults: RelayDefaults, adapter?: AdapterConfig): SandboxLevel;
+declare const hooksSchema: z.ZodObject<{
+    /** Shell command run just before the agent starts. */
+    onStart: z.ZodOptional<z.ZodString>;
+    /** Shell command run after the run reaches a terminal status. */
+    onComplete: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    onStart?: string | undefined;
+    onComplete?: string | undefined;
+}, {
+    onStart?: string | undefined;
+    onComplete?: string | undefined;
+}>;
+type HooksConfig = z.infer<typeof hooksSchema>;
+/** Which decider answers interactive approval/choice prompts. */
+declare const deciderSchema: z.ZodObject<{
+    type: z.ZodDefault<z.ZodEnum<["rule", "always-approve", "command", "api"]>>;
+    /** rule: regex strings that trigger deny / a negative choice. */
+    denyPatterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** rule: stance for non-dangerous approvals. */
+    defaultApproval: z.ZodOptional<z.ZodEnum<["approve", "deny"]>>;
+    /** rule: default answer for free-text input prompts. */
+    defaultAnswer: z.ZodOptional<z.ZodString>;
+    /** command: the decider model CLI + args (e.g. claude -p / codex exec). */
+    command: z.ZodOptional<z.ZodString>;
+    args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    /** api: OpenAI-compatible chat-completions endpoint + model. */
+    url: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    type: "command" | "rule" | "always-approve" | "api";
+    timeoutMs?: number | undefined;
+    command?: string | undefined;
+    args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+    denyPatterns?: string[] | undefined;
+    defaultApproval?: "approve" | "deny" | undefined;
+    defaultAnswer?: string | undefined;
+    url?: string | undefined;
+    model?: string | undefined;
+    apiKey?: string | undefined;
+    maxTokens?: number | undefined;
+}, {
+    timeoutMs?: number | undefined;
+    type?: "command" | "rule" | "always-approve" | "api" | undefined;
+    command?: string | undefined;
+    args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+    denyPatterns?: string[] | undefined;
+    defaultApproval?: "approve" | "deny" | undefined;
+    defaultAnswer?: string | undefined;
+    url?: string | undefined;
+    model?: string | undefined;
+    apiKey?: string | undefined;
+    maxTokens?: number | undefined;
+}>;
+type DeciderConfigSchema = z.infer<typeof deciderSchema>;
+declare const configSchema: z.ZodEffects<z.ZodObject<{
+    defaultAdapter: z.ZodString;
+    sessionsDir: z.ZodDefault<z.ZodString>;
+    logsDir: z.ZodDefault<z.ZodString>;
+    defaults: z.ZodDefault<z.ZodObject<{
+        maxTurns: z.ZodDefault<z.ZodNumber>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        idleTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        /**
+         * Default autonomy level. `auto` (the default) makes runs fully
+         * unattended — the orchestrator auto-approves and the agent CLIs are
+         * launched with their non-interactive "don't ask" flags.
+         */
+        approvalPolicy: z.ZodOptional<z.ZodEnum<["auto", "gated", "readonly"]>>;
+        /** Default sandbox strength for process-spawning agents. */
+        sandbox: z.ZodOptional<z.ZodEnum<["read-only", "workspace-write", "danger-full-access"]>>;
+        /** Interactive: idle window before a finished agent's TUI is quit (ms). */
+        completionIdleMs: z.ZodOptional<z.ZodNumber>;
+        /**
+         * Legacy flag. When `approvalPolicy` is unset, `true` -> `gated` and
+         * `false` -> `auto`. Kept for back-compat; prefer `approvalPolicy`.
+         */
+        requireApprovalOnRiskyActions: z.ZodDefault<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        maxTurns: number;
+        timeoutMs: number;
+        idleTimeoutMs: number;
+        requireApprovalOnRiskyActions: boolean;
+        approvalPolicy?: "auto" | "gated" | "readonly" | undefined;
+        sandbox?: "read-only" | "workspace-write" | "danger-full-access" | undefined;
+        completionIdleMs?: number | undefined;
+    }, {
+        maxTurns?: number | undefined;
+        timeoutMs?: number | undefined;
+        idleTimeoutMs?: number | undefined;
+        approvalPolicy?: "auto" | "gated" | "readonly" | undefined;
+        sandbox?: "read-only" | "workspace-write" | "danger-full-access" | undefined;
+        completionIdleMs?: number | undefined;
+        requireApprovalOnRiskyActions?: boolean | undefined;
+    }>>;
+    adapters: z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodString;
+        mode: z.ZodEnum<["pty", "test"]>;
+        command: z.ZodOptional<z.ZodString>;
+        args: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /** Extra env vars to inject when spawning. */
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        /** Per-adapter approval override (falls back to defaults). */
+        approvalPolicy: z.ZodOptional<z.ZodEnum<["auto", "gated", "readonly"]>>;
+        /** Per-adapter sandbox override (falls back to defaults). */
+        sandbox: z.ZodOptional<z.ZodEnum<["read-only", "workspace-write", "danger-full-access"]>>;
+    }, "strict", z.ZodTypeAny, {
+        type: string;
+        mode: "pty" | "test";
+        args: string[];
+        approvalPolicy?: "auto" | "gated" | "readonly" | undefined;
+        sandbox?: "read-only" | "workspace-write" | "danger-full-access" | undefined;
+        command?: string | undefined;
+        env?: Record<string, string> | undefined;
+    }, {
+        type: string;
+        mode: "pty" | "test";
+        approvalPolicy?: "auto" | "gated" | "readonly" | undefined;
+        sandbox?: "read-only" | "workspace-write" | "danger-full-access" | undefined;
+        command?: string | undefined;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+    }>>;
+    /** Which decider answers interactive prompts. */
+    decider: z.ZodOptional<z.ZodObject<{
+        type: z.ZodDefault<z.ZodEnum<["rule", "always-approve", "command", "api"]>>;
+        /** rule: regex strings that trigger deny / a negative choice. */
+        denyPatterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** rule: stance for non-dangerous approvals. */
+        defaultApproval: z.ZodOptional<z.ZodEnum<["approve", "deny"]>>;
+        /** rule: default answer for free-text input prompts. */
+        defaultAnswer: z.ZodOptional<z.ZodString>;
+        /** command: the decider model CLI + args (e.g. claude -p / codex exec). */
+        command: z.ZodOptional<z.ZodString>;
+        args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+        /** api: OpenAI-compatible chat-completions endpoint + model. */
+        url: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        apiKey: z.ZodOptional<z.ZodString>;
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        type: "command" | "rule" | "always-approve" | "api";
+        timeoutMs?: number | undefined;
+        command?: string | undefined;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+        denyPatterns?: string[] | undefined;
+        defaultApproval?: "approve" | "deny" | undefined;
+        defaultAnswer?: string | undefined;
+        url?: string | undefined;
+        model?: string | undefined;
+        apiKey?: string | undefined;
+        maxTokens?: number | undefined;
+    }, {
+        timeoutMs?: number | undefined;
+        type?: "command" | "rule" | "always-approve" | "api" | undefined;
+        command?: string | undefined;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+        denyPatterns?: string[] | undefined;
+        defaultApproval?: "approve" | "deny" | undefined;
+        defaultAnswer?: string | undefined;
+        url?: string | undefined;
+        model?: string | undefined;
+        apiKey?: string | undefined;
+        maxTokens?: number | undefined;
+    }>>;
+    /** Optional shell-command lifecycle hooks. */
+    hooks: z.ZodOptional<z.ZodObject<{
+        /** Shell command run just before the agent starts. */
+        onStart: z.ZodOptional<z.ZodString>;
+        /** Shell command run after the run reaches a terminal status. */
+        onComplete: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        onStart?: string | undefined;
+        onComplete?: string | undefined;
+    }, {
+        onStart?: string | undefined;
+        onComplete?: string | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    adapters: Record<string, {
+        type: string;
+        mode: "pty" | "test";
+        args: string[];
+        approvalPolicy?: "auto" | "gated" | "readonly" | undefined;
+        sandbox?: "read-only" | "workspace-write" | "danger-full-access" | undefined;
+        command?: string | undefined;
+        env?: Record<string, string> | undefined;
+    }>;
+    defaultAdapter: string;
+    sessionsDir: string;
+    logsDir: string;
+    defaults: {
+        maxTurns: number;
+        timeoutMs: number;
+        idleTimeoutMs: number;
+        requireApprovalOnRiskyActions: boolean;
+        approvalPolicy?: "auto" | "gated" | "readonly" | undefined;
+        sandbox?: "read-only" | "workspace-write" | "danger-full-access" | undefined;
+        completionIdleMs?: number | undefined;
+    };
+    decider?: {
+        type: "command" | "rule" | "always-approve" | "api";
+        timeoutMs?: number | undefined;
+        command?: string | undefined;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+        denyPatterns?: string[] | undefined;
+        defaultApproval?: "approve" | "deny" | undefined;
+        defaultAnswer?: string | undefined;
+        url?: string | undefined;
+        model?: string | undefined;
+        apiKey?: string | undefined;
+        maxTokens?: number | undefined;
+    } | undefined;
+    hooks?: {
+        onStart?: string | undefined;
+        onComplete?: string | undefined;
+    } | undefined;
+}, {
+    adapters: Record<string, {
+        type: string;
+        mode: "pty" | "test";
+        approvalPolicy?: "auto" | "gated" | "readonly" | undefined;
+        sandbox?: "read-only" | "workspace-write" | "danger-full-access" | undefined;
+        command?: string | undefined;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+    }>;
+    defaultAdapter: string;
+    sessionsDir?: string | undefined;
+    logsDir?: string | undefined;
+    defaults?: {
+        maxTurns?: number | undefined;
+        timeoutMs?: number | undefined;
+        idleTimeoutMs?: number | undefined;
+        approvalPolicy?: "auto" | "gated" | "readonly" | undefined;
+        sandbox?: "read-only" | "workspace-write" | "danger-full-access" | undefined;
+        completionIdleMs?: number | undefined;
+        requireApprovalOnRiskyActions?: boolean | undefined;
+    } | undefined;
+    decider?: {
+        timeoutMs?: number | undefined;
+        type?: "command" | "rule" | "always-approve" | "api" | undefined;
+        command?: string | undefined;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+        denyPatterns?: string[] | undefined;
+        defaultApproval?: "approve" | "deny" | undefined;
+        defaultAnswer?: string | undefined;
+        url?: string | undefined;
+        model?: string | undefined;
+        apiKey?: string | undefined;
+        maxTokens?: number | undefined;
+    } | undefined;
+    hooks?: {
+        onStart?: string | undefined;
+        onComplete?: string | undefined;
+    } | undefined;
+}>, {
+    adapters: Record<string, {
+        type: string;
+        mode: "pty" | "test";
+        args: string[];
+        approvalPolicy?: "auto" | "gated" | "readonly" | undefined;
+        sandbox?: "read-only" | "workspace-write" | "danger-full-access" | undefined;
+        command?: string | undefined;
+        env?: Record<string, string> | undefined;
+    }>;
+    defaultAdapter: string;
+    sessionsDir: string;
+    logsDir: string;
+    defaults: {
+        maxTurns: number;
+        timeoutMs: number;
+        idleTimeoutMs: number;
+        requireApprovalOnRiskyActions: boolean;
+        approvalPolicy?: "auto" | "gated" | "readonly" | undefined;
+        sandbox?: "read-only" | "workspace-write" | "danger-full-access" | undefined;
+        completionIdleMs?: number | undefined;
+    };
+    decider?: {
+        type: "command" | "rule" | "always-approve" | "api";
+        timeoutMs?: number | undefined;
+        command?: string | undefined;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+        denyPatterns?: string[] | undefined;
+        defaultApproval?: "approve" | "deny" | undefined;
+        defaultAnswer?: string | undefined;
+        url?: string | undefined;
+        model?: string | undefined;
+        apiKey?: string | undefined;
+        maxTokens?: number | undefined;
+    } | undefined;
+    hooks?: {
+        onStart?: string | undefined;
+        onComplete?: string | undefined;
+    } | undefined;
+}, {
+    adapters: Record<string, {
+        type: string;
+        mode: "pty" | "test";
+        approvalPolicy?: "auto" | "gated" | "readonly" | undefined;
+        sandbox?: "read-only" | "workspace-write" | "danger-full-access" | undefined;
+        command?: string | undefined;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+    }>;
+    defaultAdapter: string;
+    sessionsDir?: string | undefined;
+    logsDir?: string | undefined;
+    defaults?: {
+        maxTurns?: number | undefined;
+        timeoutMs?: number | undefined;
+        idleTimeoutMs?: number | undefined;
+        approvalPolicy?: "auto" | "gated" | "readonly" | undefined;
+        sandbox?: "read-only" | "workspace-write" | "danger-full-access" | undefined;
+        completionIdleMs?: number | undefined;
+        requireApprovalOnRiskyActions?: boolean | undefined;
+    } | undefined;
+    decider?: {
+        timeoutMs?: number | undefined;
+        type?: "command" | "rule" | "always-approve" | "api" | undefined;
+        command?: string | undefined;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+        denyPatterns?: string[] | undefined;
+        defaultApproval?: "approve" | "deny" | undefined;
+        defaultAnswer?: string | undefined;
+        url?: string | undefined;
+        model?: string | undefined;
+        apiKey?: string | undefined;
+        maxTokens?: number | undefined;
+    } | undefined;
+    hooks?: {
+        onStart?: string | undefined;
+        onComplete?: string | undefined;
+    } | undefined;
+}>;
+type RelayConfig = z.infer<typeof configSchema>;
+/** The default config object written by `init`. */
+declare function createDefaultConfig(): RelayConfig;
+/** Validate an unknown value as a RelayConfig, throwing a friendly error. */
+declare function parseConfig(value: unknown): RelayConfig;
+/** Resolve the absolute path to the config file for a given root dir. */
+declare function configPath(rootDir: string): string;
+/** Load and validate the config from disk. */
+declare function loadConfig(rootDir: string): Promise<RelayConfig>;
+/**
+ * Load the config, or fall back to the built-in defaults when **no config file
+ * exists** — so the CLI works zero-config (e.g. `npx agent-relay run --adapter
+ * claude -p "..."`) without requiring `agent-relay init` first. The session/log
+ * directories are created lazily on the first run, so nothing else is needed.
+ *
+ * A config file that IS present but malformed (bad JSON or failing validation)
+ * still throws — we never silently ignore a config the user actually wrote.
+ * `onDefault` fires only when the fallback is used, letting callers surface a
+ * one-line "using built-in defaults" hint.
+ */
+declare function loadConfigOrDefault(rootDir: string, onDefault?: () => void): Promise<RelayConfig>;
+/** Serialize a config to pretty JSON (stable key order via schema parse). */
+declare function stringifyConfig(config: RelayConfig): string;
+/** Write a config to disk, creating parent dirs as needed. */
+declare function saveConfig(rootDir: string, config: RelayConfig): Promise<string>;
+
+/** Typed errors used across agent-relay so callers can branch on `code`. */
+declare class AgentRelayError extends Error {
+    readonly code: string;
+    readonly hint?: string;
+    constructor(message: string, code: string, hint?: string);
+}
+/** Raised when a config file is missing or invalid. */
+declare class ConfigError extends AgentRelayError {
+    constructor(message: string, hint?: string);
+}
+/** Raised when an adapter name is not registered / not in config. */
+declare class UnknownAdapterError extends AgentRelayError {
+    constructor(name: string, available: string[]);
+}
+/** Raised when a session cannot be found on disk. */
+declare class SessionNotFoundError extends AgentRelayError {
+    constructor(sessionId: string);
+}
+
+/** Session metadata persistence: create, save, load, list. */
+
+interface CreateSessionInput {
+    prompt: string;
+    adapter: string;
+    mode: AdapterMode;
+    cwd: string;
+    logFile: string;
+    dryRun?: boolean;
+    /** Override the generated id (used by tests / explicit session ids). */
+    sessionId?: string;
+    /** Override the creation timestamp (used by tests for determinism). */
+    startedAt?: string;
+}
+/**
+ * Manages session metadata files under `sessionsDir`. The manager is given an
+ * already-resolved absolute directory; the runner/commands compute that from
+ * config + root dir.
+ */
+declare class SessionManager {
+    private readonly sessionsDir;
+    constructor(sessionsDir: string);
+    /** Absolute path to a session's JSON metadata file. */
+    filePath(sessionId: string): string;
+    /** Build a fresh session record in the `created` state (not yet persisted). */
+    create(input: CreateSessionInput): SessionMetadata;
+    /** Persist (create or overwrite) a session's metadata. */
+    save(meta: SessionMetadata): Promise<string>;
+    /** Load a session's metadata, throwing {@link SessionNotFoundError}. */
+    load(sessionId: string): Promise<SessionMetadata>;
+    /** Apply a partial update and persist; returns the updated record. */
+    update(sessionId: string, patch: Partial<SessionMetadata>): Promise<SessionMetadata>;
+    /** Convenience helper to set status (and optionally endedAt). */
+    setStatus(sessionId: string, status: SessionStatus, extra?: Partial<SessionMetadata>): Promise<SessionMetadata>;
+    /** List all sessions, newest first. Returns [] if the dir does not exist. */
+    list(): Promise<SessionMetadata[]>;
+}
+
+/**
+ * Append-only run logger. Writes a human-readable header, one line per event,
+ * and a footer with the final status. Uses synchronous appends so the log is
+ * always flushed even if the process is killed mid-run.
+ */
+
+interface RunLoggerHeader {
+    sessionId: string;
+    adapter: string;
+    mode: string;
+    prompt: string;
+    cwd: string;
+    command?: CommandPreview;
+    startedAt: string;
+}
+interface RunLoggerOptions {
+    /**
+     * When false (the default), raw `stdout`/`stderr` events are NOT written to the
+     * log — only the meaningful ones (start, prompt/status, decision, complete,
+     * error). Interactive TUIs redraw constantly, so the raw stream is ~98% noise
+     * and bloats logs; keep it only when debugging via `verbose: true`.
+     */
+    verbose?: boolean;
+    /** Optional cap on log bytes; appends stop (with a one-time notice) past it. */
+    maxBytes?: number;
+}
+declare class RunLogger {
+    private readonly logFile;
+    private readonly opts;
+    private bytes;
+    private suppressed;
+    private truncated;
+    constructor(logFile: string, opts?: RunLoggerOptions);
+    private append;
+    /** Ensure the log directory exists and write the run header. */
+    start(header: RunLoggerHeader): void;
+    /** Record a single normalized event. */
+    event(event: AgentEvent): void;
+    /** Write the run footer with terminal status and optional error. */
+    finish(status: SessionStatus, endedAt: string, error?: AgentErrorInfo): void;
+}
+
+/**
+ * Completion detection: maps a finished (or aborted) run to a terminal
+ * {@link SessionStatus}. Designed to be extensible — today the default detector
+ * uses adapter success / exit code / abort reason, but new detectors can layer
+ * in test-result parsing, output-pattern matching, or changed-file analysis.
+ */
+
+/** Everything a detector needs to render a verdict. */
+interface CompletionContext {
+    /** Adapter result (may be partial when aborted). */
+    result?: AgentRunResult;
+    /** All normalized events observed during the run. */
+    events: AgentEvent[];
+    /** Why the runner aborted, if it did. */
+    abortReason?: AbortReason;
+    /** An error thrown by the adapter's run(), if any. */
+    error?: Error;
+}
+/** A pluggable completion strategy. */
+interface CompletionDetector {
+    readonly name: string;
+    /**
+     * Return a terminal status, or `undefined` to defer to the next detector in
+     * a chain (lets specialized detectors only handle cases they understand).
+     */
+    detect(ctx: CompletionContext): SessionStatus | undefined;
+}
+/**
+ * Default detector. Order of precedence:
+ *  1. abort reasons (timeout / idle -> timeout, cancel -> cancelled,
+ *     maxTurns -> failed),
+ *  2. thrown error -> failed,
+ *  3. adapter success or exit code 0 -> completed,
+ *  4. otherwise -> failed.
+ */
+declare class DefaultCompletionDetector implements CompletionDetector {
+    readonly name = "default";
+    detect(ctx: CompletionContext): SessionStatus;
+}
+/**
+ * Runs detectors in order, returning the first defined verdict, and falling
+ * back to {@link DefaultCompletionDetector}. This is the extension seam: append
+ * a `TestsPassedDetector`, `OutputPatternDetector`, or `ChangedFilesDetector`
+ * before the default to refine the verdict without touching the runner.
+ */
+declare class CompositeCompletionDetector implements CompletionDetector {
+    readonly name = "composite";
+    private readonly detectors;
+    private readonly fallback;
+    constructor(detectors?: CompletionDetector[]);
+    detect(ctx: CompletionContext): SessionStatus;
+}
+/**
+ * --- Future extension hooks (intentionally not wired into the runner yet) ---
+ *
+ * These illustrate how richer signals plug into the same interface. They are
+ * exported so they can be unit-tested and adopted incrementally.
+ */
+/** Detect "tests passed" from a configurable success/failure regex. */
+interface PatternDetectorOptions {
+    /** If this matches any assistant/stdout text, the run is `completed`. */
+    successPattern?: RegExp;
+    /** If this matches, the run is `failed`. Evaluated before successPattern. */
+    failurePattern?: RegExp;
+}
+declare class OutputPatternDetector implements CompletionDetector {
+    private readonly options;
+    readonly name = "output-pattern";
+    constructor(options: PatternDetectorOptions);
+    detect(ctx: CompletionContext): SessionStatus | undefined;
+}
+
+/**
+ * Run orchestration. Owns the lifecycle of a single agent run:
+ * config -> adapter selection -> session create/save -> prompt dispatch ->
+ * event collection -> timeout/idle/maxTurns enforcement -> logging ->
+ * signal-based cleanup -> completion detection -> final status persistence.
+ *
+ * The runner depends ONLY on the {@link AgentAdapter} interface, resolved
+ * through an injected {@link AdapterFactory}. It never imports a concrete
+ * vendor adapter, which keeps `core/` decoupled from Claude/Codex.
+ */
+
+/** Builds an {@link AgentAdapter} from its name + the active config. */
+type AdapterFactory = (name: string, config: RelayConfig) => AgentAdapter;
+interface RunnerOptions {
+    config: RelayConfig;
+    /** Base directory used to resolve sessionsDir/logsDir and default cwd. */
+    rootDir: string;
+    /** Adapter to use; defaults to `config.defaultAdapter`. */
+    adapterName?: string;
+    prompt: string;
+    /** Working directory for the agent; defaults to `rootDir`. */
+    cwd?: string;
+    maxTurns?: number;
+    timeoutMs?: number;
+    idleTimeoutMs?: number;
+    dryRun?: boolean;
+    extraArgs?: string[];
+    /** Override the resolved approval mode for this run. */
+    approvalMode?: ApprovalMode;
+    /** Override the resolved sandbox level for this run. */
+    sandbox?: SandboxLevel;
+    /** Interactive: idle window before a finished agent's TUI is quit (ms). */
+    completionIdleMs?: number;
+    /** Claude: drive `/effort ultracode` (+ Opus) in the TUI before the task. */
+    ultracode?: boolean;
+    /** Decider that answers interactive prompts (overrides config/hooks). */
+    decider?: Decider;
+    /** Programmatic lifecycle hooks. */
+    hooks?: RunHooks;
+    /** Resume target (native session ref) for resume runs. */
+    resume?: AgentSessionRef;
+    /** Force a specific session id (otherwise generated). */
+    sessionId?: string;
+    /** DI seam: resolves an adapter instance. */
+    resolveAdapter: AdapterFactory;
+    /** Optional completion detector; defaults to the composite/default chain. */
+    detector?: CompletionDetector;
+    /** Observe normalized events live (in addition to logging). */
+    onEvent?: (event: AgentEvent) => void;
+    /** Log the raw stdout/stderr stream too (default false → small logs). */
+    verbose?: boolean;
+    /** Optional cap on log file bytes. */
+    maxLogBytes?: number;
+    /** Install SIGINT/SIGTERM handlers (default true; tests pass false). */
+    installSignalHandlers?: boolean;
+    /**
+     * External cancellation signal. Aborting it cancels the run (mapped to the
+     * `cancel` reason -> `cancelled` status), independent of OS signals. Enables
+     * programmatic cancellation and deterministic cancel tests.
+     */
+    signal?: AbortSignal;
+    /** Injectable clock for deterministic timestamps in tests. */
+    now?: () => Date;
+}
+interface RunOutcome {
+    session: SessionMetadata;
+    status: SessionStatus;
+    result?: AgentRunResult;
+    events: AgentEvent[];
+    abortReason?: AbortReason;
+    logFile: string;
+}
+declare function runAgent(options: RunnerOptions): Promise<RunOutcome>;
+
+/**
+ * Run lifecycle hooks — agent-relay's extensibility harness.
+ *
+ * Two flavors:
+ *  - **Programmatic** {@link RunHooks}: callbacks for embedders (onSessionStart,
+ *    onEvent, onComplete, onApprovalRequest).
+ *  - **Shell** {@link ShellHooks}: shell commands defined in the config file,
+ *    run with `AGENT_RELAY_*` env vars (think git hooks, but for agent runs) —
+ *    e.g. run the test suite or send a notification when a run completes.
+ */
+
+/** Programmatic lifecycle callbacks supplied by an embedder. */
+interface RunHooks {
+    onSessionStart?: (session: SessionMetadata) => void | Promise<void>;
+    onEvent?: (event: AgentEvent, session: SessionMetadata) => void | Promise<void>;
+    onComplete?: (outcome: RunOutcome) => void | Promise<void>;
+    /**
+     * Act as the Decider for interactive prompts: given the agent's prompt,
+     * return the decision. When provided, this takes precedence over the
+     * configured decider — a programmatic human-in-the-loop / policy hook.
+     */
+    onApprovalRequest?: (req: InteractionRequest) => InteractionDecision | Promise<InteractionDecision>;
+}
+/** Shell-command hooks defined in the config file. */
+interface ShellHooks {
+    /** Runs just before the agent starts (status: running). */
+    onStart?: string;
+    /** Runs after the run reaches a terminal status. */
+    onComplete?: string;
+}
+interface ShellHookContext {
+    sessionId: string;
+    adapter: string;
+    status: string;
+    cwd: string;
+    logFile: string;
+    exitCode?: number | null;
+}
+/**
+ * Run a shell-command hook. Failures never throw (they must not break a run);
+ * the command runs in a shell with `AGENT_RELAY_*` env vars describing the run.
+ */
+declare function runShellHook(command: string, ctx: ShellHookContext): Promise<{
+    ok: boolean;
+    exitCode: number | null;
+}>;
+
+type FakeScenario = "success" | "failure" | "timeout" | "auto";
+interface FakeAdapterOptions {
+    scenario?: FakeScenario;
+    /** Assistant messages to emit (one `assistant_message` event each). */
+    assistantMessages?: string[];
+    /** Emit a tool_call / tool_result pair before finishing. */
+    emitTool?: boolean;
+    /** Delay (ms) before the run resolves in success/failure scenarios. */
+    delayMs?: number;
+    /** Exit code reported on failure. */
+    failureExitCode?: number;
+    /** Safety cap (ms) so a `timeout` scenario can never truly hang forever. */
+    hangSafetyMs?: number;
+    /** Injectable clock for deterministic timestamps. */
+    now?: () => Date;
+}
+declare class FakeAgentAdapter implements AgentAdapter {
+    readonly definition: AgentAdapterDefinition;
+    private readonly options;
+    constructor(options?: FakeAdapterOptions);
+    isAvailable(): Promise<AdapterAvailability>;
+    describeCommand(input: AgentRunInput): {
+        mode: AdapterMode;
+        command: string;
+        args: never[];
+        display: string;
+    };
+    private resolveScenario;
+    private emit;
+    run(input: AgentRunInput, ctx: AdapterRunContext): Promise<AgentRunResult>;
+    resume(ref: {
+        adapter: string;
+        nativeSessionId?: string;
+        resumable: boolean;
+    }, input: AgentRunInput, ctx: AdapterRunContext): Promise<AgentRunResult>;
+    private hangUntilAborted;
+    private sleep;
+}
+
+/**
+ * Heuristic detector for "the agent is now waiting on a prompt" in interactive
+ * (PTY) terminal output. Detection is necessarily heuristic — TUIs redraw,
+ * paginate, and vary — so patterns are configurable per adapter, and the PTY
+ * session only runs detection once output has gone idle (settled).
+ *
+ * Two robust shapes are recognized out of the box:
+ *   - approval  : a yes/no style confirmation (e.g. "... [y/n]", "Proceed?")
+ *   - choice    : a numbered menu ("1. Continue", "2. Stop", optionally "> 1.")
+ * Adapters can supply their own patterns for vendor-specific TUIs.
+ */
+
+interface DetectedPrompt {
+    kind: InteractionKind;
+    /** Cleaned prompt text shown to the decider. */
+    prompt: string;
+    /** For `choice`: option labels in display order (checkbox marker stripped). */
+    options?: string[];
+    /** For `choice`: the display number for each option (for keystroke mapping). */
+    optionNumbers?: number[];
+    /** True for a MULTI-select menu (each option has a `[ ]`/`[x]`/`◯`/`◉` box). */
+    multiSelect?: boolean;
+    /** For a multi-select: current checked state per option (aligned to `options`). */
+    checked?: boolean[];
+    /** For a multi-select: index of the row the cursor (`>`/`❯`) is on (default 0). */
+    cursorIndex?: number;
+    /** Stable signature of the settled prompt, for de-duplication. */
+    signature: string;
+}
+/** Recognize a leading checkbox marker on an option label; returns its state +
+ *  the remaining label, or null when the label has no checkbox. */
+declare function parseCheckbox(label: string): {
+    checked: boolean;
+    label: string;
+} | null;
+interface PromptDetectorOptions {
+    /** Recognizes a yes/no approval prompt. */
+    approvalPattern?: RegExp;
+    /** Matches a single numbered menu option; groups: 1=number, 2=label. */
+    optionLine?: RegExp;
+    /** Recognizes a free-text input prompt (optional; off by default). */
+    inputPattern?: RegExp;
+    /** Minimum option lines to treat the tail as a choice menu. */
+    minOptions?: number;
+    /** How many trailing lines to inspect. */
+    tailLines?: number;
+}
+declare class PromptDetector {
+    private readonly opts;
+    constructor(options?: PromptDetectorOptions);
+    /** Detect a settled prompt from raw terminal output, or null. */
+    detect(rawOutput: string): DetectedPrompt | null;
+}
+
+/**
+ * The interactive PTY session driver — agent-relay's core run loop.
+ *
+ * It spawns a coding agent in a real pseudo-terminal, watches the output, and
+ * once the terminal SETTLES (no new bytes for `idleMs`) it checks whether the
+ * agent is:
+ *   - waiting on a prompt  -> ask the {@link Decider}, translate the decision to
+ *                             keystrokes, and write them back into the PTY, or
+ *   - done with the task   -> (a `completionPattern` settled) send the quit keys
+ *                             and let the process exit.
+ *
+ * This is what lets agent-relay run agents *interactively* while an LLM/policy
+ * answers the approvals and choices that come up — instead of suppressing them.
+ */
+
+/** Maps a decision + detected prompt to the bytes to write into the PTY. */
+interface PtyKeymap {
+    keysFor(decision: InteractionDecision, prompt: DetectedPrompt): string | null;
+}
+/** Sensible default keystrokes for yes/no prompts and numbered menus. */
+declare class DefaultKeymap implements PtyKeymap {
+    private readonly multiSelectSubmit;
+    constructor(multiSelectSubmit?: string);
+    keysFor(decision: InteractionDecision, prompt: DetectedPrompt): string | null;
+}
+/**
+ * A pre-task step run once the agent is idle (e.g. set a session option via a
+ * slash command) BEFORE the task prompt is typed. `send` is typed (Enter
+ * appended), then we wait `waitMs` for any animated widget it opens to finish and
+ * the screen to revert (e.g. claude `/effort ultracode`), before the next step /
+ * the task prompt. Time-based because such widgets redraw continuously and never
+ * "settle" for detection.
+ */
+interface SetupStep {
+    send: string;
+    waitMs?: number;
+}
+interface PtySessionOptions {
+    command: string;
+    args: string[];
+    cwd: string;
+    env?: Record<string, string>;
+    decider: Decider;
+    detector: PromptDetector;
+    keymap?: PtyKeymap;
+    /** No-output settle window before running detection (ms). */
+    idleMs?: number;
+    cols?: number;
+    rows?: number;
+    agent?: string;
+    /** The original task/goal, passed to the decider for relevance judgment. */
+    task?: string;
+    /** Cap on prompts handled before aborting (maps from maxTurns). */
+    maxInteractions?: number;
+    /** When this matches the settled tail, the task is considered complete. */
+    completionPattern?: RegExp;
+    /**
+     * If the agent produces no output and shows no prompt for this long, treat
+     * the task as complete and quit the TUI (so the run ends `completed` rather
+     * than waiting for the overall idle timeout). Disabled when unset.
+     */
+    completionIdleMs?: number;
+    /**
+     * If the visible screen matches this, the agent is still WORKING (e.g. a
+     * "Thinking… esc to interrupt" indicator) — the completion-idle countdown is
+     * suppressed no matter how long the agent stays silent, so a long
+     * think/build is never mistaken for "done".
+     */
+    workingPattern?: RegExp;
+    /** Keys to send to exit the TUI on completion (e.g. double Ctrl-C). */
+    quitKeys?: string;
+    /** Optional text to type once the UI is ready (for TUIs needing typed input). */
+    initialInput?: string;
+    /** Delay before sending initialInput (ms). */
+    initialDelayMs?: number;
+    /**
+     * Pre-task setup steps (slash-commands + menu choices) to run once the agent
+     * is idle, before the task. With this set, the prompt is NOT a launch arg — it
+     * is typed via `promptAfterSetup` after the steps complete.
+     */
+    setup?: SetupStep[];
+    /** Task prompt to TYPE after `setup` completes. */
+    promptAfterSetup?: string;
+    /** Grace period to wait for exit after sending quit keys (ms). */
+    exitGraceMs?: number;
+    now?: () => Date;
+    /** Friendly install hint for a missing command. */
+    installHint?: string;
+}
+declare function runPtySession(opts: PtySessionOptions, ctx: AdapterRunContext): Promise<AgentRunResult>;
+
+/**
+ * Base adapter for driving a coding agent INTERACTIVELY through a PTY. Concrete
+ * adapters (Claude / Codex) supply the command, the pre-prompt args (sandbox /
+ * approval flags that make the agent *ask*), the prompt-detection patterns, the
+ * keystroke map, and how to detect completion. The detect -> decide -> respond
+ * loop lives in {@link runPtySession}; the {@link Decider} comes from the run
+ * context so the same adapter works with any decision backend.
+ */
+
+interface InteractiveAdapterConfig {
+    definition: AgentAdapterDefinition;
+    command: string;
+    installHint: string;
+    /** Args placed BEFORE the prompt (sandbox / approval flags, model, ...). */
+    preArgs: (input: AgentRunInput) => string[];
+    /**
+     * Args that make the agent RESUME a prior conversation (before the follow-up
+     * prompt). When set, the adapter advertises `supportsResume` and `resume()`
+     * spawns with these instead of `preArgs` — e.g. claude `--continue`, codex
+     * `resume --last`. The native session id is rarely captured in PTY mode, so
+     * these usually resume the agent's MOST RECENT session in the cwd.
+     */
+    resumeArgs?: (input: AgentRunInput, ref: AgentSessionRef) => string[];
+    /**
+     * On resume, TYPE the follow-up prompt once the agent is idle instead of
+     * passing it as a launch arg. May be a predicate so the adapter can decide
+     * per-resume: codex types the prompt ONLY on the `resume --last` fallback
+     * (where `codex resume --last "<prompt>"` misparses the prompt as the optional
+     * `[SESSION_ID]` positional), but passes it as an arg when a native SESSION_ID
+     * is present (`codex resume <id> "<prompt>"` parses cleanly).
+     */
+    resumeTypesPrompt?: boolean | ((input: AgentRunInput, ref: AgentSessionRef) => boolean);
+    /** With `resumeTypesPrompt`, warm up this many ms after the agent first goes
+     *  idle before typing the prompt (lets a slow startup, e.g. codex loading MCP
+     *  servers, finish so the prompt isn't typed into a not-ready input). */
+    resumeWarmupMs?: number;
+    /**
+     * Pre-task setup steps to run before the prompt (e.g. claude `/effort` →
+     * "ultracode"). When this returns steps, the agent is launched WITHOUT the
+     * prompt as an arg; the steps run once it is idle, then the prompt is typed.
+     */
+    setup?: (input: AgentRunInput) => SetupStep[] | undefined;
+    detector?: PromptDetectorOptions;
+    keymap?: PtyKeymap;
+    completionPattern?: RegExp;
+    completionIdleMs?: number;
+    /** "Agent is working" indicator that suppresses completion (see PtySession). */
+    workingPattern?: RegExp;
+    quitKeys?: string;
+    env?: Record<string, string>;
+    /** Deliver the prompt as a CLI arg (default) or typed into the TUI. */
+    promptMode?: "arg" | "type";
+    idleMs?: number;
+    now?: () => Date;
+}
+declare class InteractivePtyAdapter implements AgentAdapter {
+    readonly definition: AgentAdapterDefinition;
+    protected readonly cfg: InteractiveAdapterConfig;
+    private readonly detector;
+    constructor(cfg: InteractiveAdapterConfig);
+    isAvailable(): Promise<AdapterAvailability>;
+    protected buildArgs(input: AgentRunInput): {
+        args: string[];
+        initialInput?: string;
+    };
+    describeCommand(input: AgentRunInput): CommandPreview;
+    run(input: AgentRunInput, ctx: AdapterRunContext): Promise<AgentRunResult>;
+    resume(ref: AgentSessionRef, input: AgentRunInput, ctx: AdapterRunContext): Promise<AgentRunResult>;
+    private spawn;
+}
+
+/**
+ * Claude Code driven interactively in a PTY. The project's concept is PURE
+ * AUTONOMY: by default Claude runs with `--dangerously-skip-permissions` so it
+ * acts without per-action prompts. The {@link Decider} still handles the prompts
+ * that appear anyway (the directory-trust menu, etc.). `approvalPolicy: "gated"`
+ * uses `--permission-mode acceptEdits` so Claude asks more and the decider sees
+ * those; `"readonly"` uses `--permission-mode plan`. The prompt is a positional
+ * arg so the session starts immediately.
+ */
+
+interface ClaudeInteractiveOptions {
+    command?: string;
+    env?: Record<string, string>;
+    now?: () => Date;
+}
+declare class ClaudeInteractiveAdapter extends InteractivePtyAdapter {
+    constructor(opts?: ClaudeInteractiveOptions);
+    static fromConfig(config: AdapterConfig): ClaudeInteractiveAdapter;
+}
+
+/**
+ * Codex driven interactively in a PTY. The project's concept is PURE AUTONOMY:
+ * by default Codex runs with `-a never` (never ask) within the chosen sandbox,
+ * so it just works. The {@link Decider} still handles the prompts that appear
+ * anyway (the directory-trust dialog, etc.). `approvalPolicy: "gated"` switches
+ * Codex to `-a on-request` so the decider sees each action; `"readonly"` runs it
+ * read-only. The prompt is a positional arg so the TUI starts immediately.
+ */
+
+interface CodexInteractiveOptions {
+    command?: string;
+    env?: Record<string, string>;
+    now?: () => Date;
+    /** Override Codex's sessions root (~/.codex/sessions) — for tests. */
+    sessionsDir?: string;
+}
+declare class CodexInteractiveAdapter extends InteractivePtyAdapter {
+    private readonly clock;
+    /** Override the sessions root (~/.codex/sessions) for tests. */
+    private readonly sessionsDir?;
+    constructor(opts?: CodexInteractiveOptions);
+    /**
+     * Run Codex, then capture its NATIVE session id (the rollout UUID) for this
+     * cwd and attach it to the result's `sessionRef` so the runner persists it and
+     * a later resume can use `codex resume <id> "<prompt>"`. Capture is best-effort:
+     * if no rollout matches (or any I/O fails) the result is returned unchanged, so
+     * the run still resumes via the `--last` fallback.
+     */
+    run(input: AgentRunInput, ctx: AdapterRunContext): Promise<AgentRunResult>;
+    static fromConfig(config: AdapterConfig): CodexInteractiveAdapter;
+}
+
+/**
+ * Adapter registry. Maps an adapter config entry (by `type`) to a concrete
+ * {@link AgentAdapter} instance. This is the only place that knows about all
+ * vendor adapters; `core/` depends solely on the interface and receives a
+ * factory from here.
+ *
+ * The built-in agents (claude, codex) are driven INTERACTIVELY through a PTY.
+ */
+
+/** A builder that turns a config entry into an adapter instance. */
+type AdapterBuilder = (config: AdapterConfig) => AgentAdapter;
+/** Static descriptions of the built-in adapters (for `agent-relay adapters`). */
+declare const BUILTIN_ADAPTER_DEFINITIONS: AgentAdapterDefinition[];
+/** A registry mapping adapter `type` -> builder. */
+declare class AdapterRegistry {
+    private readonly builders;
+    constructor();
+    register(type: string, builder: AdapterBuilder): void;
+    has(type: string): boolean;
+    /** List the adapter types this registry can build. */
+    types(): string[];
+    /** Build an adapter from a config entry, by its `type`. */
+    build(config: AdapterConfig): AgentAdapter;
+    /** Resolve an adapter by its config name within a {@link RelayConfig}. */
+    resolveByName(name: string, config: RelayConfig): AgentAdapter;
+}
+/** Shared default registry instance. */
+declare const defaultRegistry: AdapterRegistry;
+/**
+ * The {@link AdapterFactory} the runner expects. Wires the default registry so
+ * commands can simply pass `createAdapterFactory()`.
+ */
+declare function createAdapterFactory(registry?: AdapterRegistry): (name: string, config: RelayConfig) => AgentAdapter;
+
+/** `agent-relay init`: create config + session/log directories. */
+
+interface InitOptions {
+    rootDir: string;
+    /** Overwrite an existing config file. */
+    force?: boolean;
+}
+interface InitResult {
+    configPath: string;
+    /** True if a fresh config file was written. */
+    configCreated: boolean;
+    sessionsDir: string;
+    logsDir: string;
+    /** Directories that were created (absolute paths). */
+    createdDirs: string[];
+}
+declare function runInit(options: InitOptions): Promise<InitResult>;
+
+/** `agent-relay adapters`: list registered/built-in adapters. */
+
+interface AdapterListItem {
+    /** The name used on the CLI (`--adapter <name>`). */
+    name: string;
+    type: string;
+    mode: string;
+    description: string;
+    supportsResume: boolean;
+    /** True when present in the active config. */
+    configured: boolean;
+    /** The configured command, if any. */
+    command?: string;
+}
+/**
+ * Produce the adapter list. When `config` is provided, entries reflect the
+ * configured adapters (name = config key) augmented with built-in descriptions;
+ * built-ins not present in config are appended as `configured: false`.
+ */
+declare function listAdapters(config?: RelayConfig): AdapterListItem[];
+
+/**
+ * `agent-relay doctor`: environment diagnostics. Missing agent CLIs are
+ * reported as warnings (not errors) so this never fails CI just because Claude
+ * or Codex isn't installed.
+ */
+type CheckLevel = "ok" | "warn" | "error";
+interface DoctorCheck {
+    name: string;
+    level: CheckLevel;
+    detail: string;
+    hint?: string;
+}
+interface DoctorReport {
+    checks: DoctorCheck[];
+    /** True when there are no `error`-level checks. */
+    ok: boolean;
+}
+interface DoctorOptions {
+    rootDir: string;
+}
+declare function runDoctor(options: DoctorOptions): Promise<DoctorReport>;
+
+/** `agent-relay run`: resolve prompt + config and orchestrate a run. */
+
+/** Raw decider flags (as collected by the CLI) to build a decider override. */
+interface DeciderFlags {
+    /** rule | always-approve | command | api */
+    decider?: string;
+    /** command decider: full command line, whitespace-split (e.g. "codex exec -s read-only"). */
+    deciderCommand?: string;
+    /** api decider: OpenAI-compatible chat-completions URL. */
+    deciderUrl?: string;
+    deciderModel?: string;
+    deciderKey?: string;
+    deciderMaxTokens?: number;
+    deciderTimeoutMs?: number;
+}
+/**
+ * Build a validated decider override from CLI flags, or `undefined` when no
+ * decider flag was given (so the configured/default decider is kept). Lets users
+ * pick a decider without writing a config file — e.g.
+ *   --decider api --decider-url http://localhost:9090/v1/chat/completions --decider-model default
+ *   --decider command --decider-command "codex exec --skip-git-repo-check -s read-only"
+ */
+declare function deciderConfigFromFlags(flags: DeciderFlags): DeciderConfig | undefined;
+interface RunCommandOptions {
+    rootDir: string;
+    adapter?: string;
+    prompt?: string;
+    promptFile?: string;
+    maxTurns?: number;
+    timeoutMs?: number;
+    idleTimeoutMs?: number;
+    completionIdleMs?: number;
+    /** Approval mode: auto (autonomy) | gated (agent asks more) | readonly (sandbox). */
+    approvalMode?: ApprovalMode;
+    /** Claude: drive `/effort ultracode` (+ Opus) in the TUI before the task. */
+    ultracode?: boolean;
+    dryRun?: boolean;
+    cwd?: string;
+    extraArgs?: string[];
+    /** Pre-loaded config (skips disk read; used by tests). */
+    config?: RelayConfig;
+    /** Called when no config file is found and built-in defaults are used. */
+    onDefaultConfig?: () => void;
+    /** Decider override (e.g. from --decider* flags); replaces config.decider. */
+    deciderConfig?: DeciderConfig;
+    /** Log the raw stdout/stderr stream too (default false → small logs). */
+    verbose?: boolean;
+    /** Optional cap on log file bytes. */
+    maxLogBytes?: number;
+    /** Override adapter resolution (used by tests / custom registries). */
+    resolveAdapter?: AdapterFactory;
+    onEvent?: (event: AgentEvent) => void;
+    installSignalHandlers?: boolean;
+    now?: () => Date;
+}
+/** Resolve the prompt text from `prompt` or `promptFile`. */
+declare function resolvePrompt(options: Pick<RunCommandOptions, "prompt" | "promptFile" | "rootDir">): Promise<string>;
+declare function runCommand(options: RunCommandOptions): Promise<RunOutcome>;
+
+/**
+ * `agent-relay resume`: look up a prior session's metadata and, if a follow-up
+ * prompt is given and the adapter supports resume, dispatch a resume run.
+ *
+ * In this initial version the focus is structural: load + surface metadata, and
+ * thread a follow-up prompt through the adapter's resume path when possible.
+ */
+
+interface ResumeCommandOptions {
+    rootDir: string;
+    sessionId: string;
+    /** Optional follow-up prompt; without it, only metadata is returned. */
+    prompt?: string;
+    /** Run-tuning (parity with `run`); fall back to config defaults when unset. */
+    maxTurns?: number;
+    timeoutMs?: number;
+    idleTimeoutMs?: number;
+    completionIdleMs?: number;
+    config?: RelayConfig;
+    /** Called when no config file is found and built-in defaults are used. */
+    onDefaultConfig?: () => void;
+    /** Decider override (e.g. from --decider* flags); replaces config.decider. */
+    deciderConfig?: DeciderConfig;
+    /** Log the raw stdout/stderr stream too (default false → small logs). */
+    verbose?: boolean;
+    /** Optional cap on log file bytes. */
+    maxLogBytes?: number;
+    resolveAdapter?: AdapterFactory;
+    onEvent?: (event: AgentEvent) => void;
+    installSignalHandlers?: boolean;
+    now?: () => Date;
+}
+interface ResumeCommandResult {
+    /** The previously stored session metadata. */
+    session: SessionMetadata;
+    /** Whether the adapter is able to resume this session. */
+    resumable: boolean;
+    /** True when a resume run was actually dispatched. */
+    resumed: boolean;
+    /** Reason a resume was not attempted, when applicable. */
+    reason?: string;
+    /** Outcome of the resume run, when one was dispatched. */
+    outcome?: RunOutcome;
+}
+declare function resumeCommand(options: ResumeCommandOptions): Promise<ResumeCommandResult>;
+
+/**
+ * `agent-relay sessions`: list recorded sessions (with log sizes) and prune old
+ * ones + their logs. Sessions/logs accumulate forever otherwise — this is the
+ * retention/cleanup surface.
+ */
+
+interface SessionsBaseOptions {
+    rootDir: string;
+    /** Called when no config file is found and built-in defaults are used. */
+    onDefaultConfig?: () => void;
+}
+interface SessionListItem extends SessionMetadata {
+    /** Size of the session's log file in bytes (0 if missing). */
+    logBytes: number;
+}
+/** List sessions (newest first) with each log's size and the grand total. */
+declare function listSessions(opts: SessionsBaseOptions): Promise<{
+    items: SessionListItem[];
+    totalLogBytes: number;
+}>;
+interface PruneOptions extends SessionsBaseOptions {
+    /** Keep the N newest sessions; delete the rest. */
+    keep?: number;
+    /** Delete sessions older than this many days (by endedAt, else startedAt). */
+    olderThanDays?: number;
+    /** Delete ALL sessions. */
+    all?: boolean;
+    now?: () => Date;
+}
+interface PruneResult {
+    deleted: number;
+    freedBytes: number;
+    kept: number;
+}
+/**
+ * Delete sessions (JSON + log) matching the filter. `keep` and `olderThanDays`
+ * combine as OR (a session goes if EITHER rule selects it). At least one of
+ * `keep` / `olderThanDays` / `all` must be set.
+ */
+declare function pruneSessions(opts: PruneOptions): Promise<PruneResult>;
+
+/**
+ * Terminal output cleanup helpers for parsing interactive TUI output.
+ * Strips ANSI escape sequences (colors, cursor moves, OSC) and normalizes
+ * whitespace so prompt detection works on readable text.
+ */
+/** Remove ANSI escape sequences from a string. */
+declare function stripAnsi(input: string): string;
+/**
+ * Clean terminal output for prompt detection: strip ANSI, turn carriage
+ * returns into line breaks, and drop other C0 control chars (keeping tab).
+ *
+ * Full-screen TUIs (e.g. Claude Code) position the cursor with escape
+ * sequences and use `\r` to redraw, so collapsing each line to "the text after
+ * the last CR" would wipe real content. Converting `\r` to `\n` preserves every
+ * rendered fragment as its own line; prompt detection then works on the tail.
+ */
+declare function cleanTerminalText(input: string): string;
+/** Return the last `n` non-empty lines of cleaned text. */
+declare function tailLines(text: string, n: number): string[];
+
+export { type AbortReason, type AdapterAvailability, type AdapterConfig, type AdapterFactory, type AdapterListItem, type AdapterMode, AdapterRegistry, type AdapterRunContext, type AgentAdapter, type AgentAdapterDefinition, type AgentErrorInfo, type AgentEvent, type AgentEventType, AgentRelayError, type AgentRunInput, type AgentRunResult, type AgentSessionRef, AlwaysApproveDecider, ApiDecider, type ApprovalMode, BUILTIN_ADAPTER_DEFINITIONS, CONFIG_FILENAME, ClaudeInteractiveAdapter, CodexInteractiveAdapter, CommandDecider, type CommandPreview, type CompletionContext, type CompletionDetector, CompositeCompletionDetector, ConfigError, type CreateSessionInput, DEFAULT_DENY_PATTERNS, type Decider, type DeciderConfig, type DeciderConfigSchema, type DeciderFlags, type DecisionAction, DefaultCompletionDetector, DefaultKeymap, type DetectedPrompt, type DoctorReport, type FakeAdapterOptions, FakeAgentAdapter, FunctionDecider, type HooksConfig, type InitResult, type InteractionDecision, type InteractionKind, type InteractionRequest, type InteractiveAdapterConfig, InteractivePtyAdapter, OutputPatternDetector, PromptDetector, type PromptDetectorOptions, type PruneOptions, type PruneResult, type PtyKeymap, type PtySessionOptions, type RelayConfig, type RelayDefaults, type ResumeCommandResult, RuleDecider, type RunHooks, RunLogger, type RunLoggerOptions, type RunOutcome, type RunnerOptions, type SandboxLevel, type SessionListItem, SessionManager, type SessionMetadata, SessionNotFoundError, type SessionStatus, type ShellHookContext, type ShellHooks, UnknownAdapterError, adapterConfigSchema, approvalPolicySchema, cleanTerminalText, configPath, configSchema, createAdapterFactory, createDecider, createDefaultConfig, deciderConfigFromFlags, deciderSchema, defaultRegistry, defaultsSchema, hooksSchema, listAdapters, listSessions, loadConfig, loadConfigOrDefault, parseCheckbox, parseConfig, parseDecisionReply, pruneSessions, renderDecisionPrompt, resolveApprovalMode, resolvePrompt, resolveSandbox, resumeCommand, runAgent, runCommand, runDoctor, runInit, runPtySession, runShellHook, sandboxSchema, saveConfig, stringifyConfig, stripAnsi, tailLines };