operon-agents 0.1.0-alpha.0

package/dist/harness.d.ts

@@ -0,0 +1,746 @@
+/**
+ * Mode 2 — batteries-included, in-process Harness facade.
+ *
+ * Wraps the `operon-agents-core` engine into the kind of ergonomic interface a CLI
+ * backend wants: `createHarness()` manages sessions, and each session exposes
+ * `prompt()/steer()/followUp()/cancel()/onEvent()/setApprovalHandler()` plus the full
+ * control plane (goals, plan mode, compaction, skills, plugins, …) delegated to
+ * the core `Session`.
+ *
+ * It is a pure composition of core primitives — no new engine behavior. For the
+ * low-level "assemble it yourself / stateless server" path, import from
+ * `operon-agents/core` instead.
+ */
+import { type AgentEvent, type EventPublicationMode, type AgentEventListener, type AgentInput, SessionProjection, type SessionSnapshot, type SnapshotOptions, type DirectoryEntry, type ProjectionObservation, type ProjectionListener, type ApprovalRequest, type ApprovalResponse, type Capability, type InterruptAnswer, type ChatModel, ListenerSink, type PermissionManagerOptions, type PermissionMode, type PendingRunInterrupt, type QuestionRequest, type QuestionResult, type Responder, type RunHandle, type RunResult, type SessionStore, type SessionHandle, type SessionSummary, type ListSessionsFilter, type OpenSessionOptions, type DeleteSessionOptions, type ThinkingLevel, type Tool, type Logger, type ExternalOriginMetadataValue, type SteerChannel, type SteerOrigin, Agent, Runner, Session, McpOAuthService, type HookDef, type McpServerConfig, type PluginManager, type ApprovalRequestOptions, type Machine, type MachineFactory, type SessionRepository, type ResolvedAgentProfile, type SubagentProvider, type ModelRuntime } from "operon-agents-core";
+import { HarnessExtensionManager, ServiceRegistry, type ExtensionDefinition, type ServiceOptions } from "./extensions/index.ts";
+import { type CommandResult } from "operon-agents-core";
+export type ApprovalHandler = (request: ApprovalRequest, options?: ApprovalRequestOptions) => Promise<ApprovalResponse> | ApprovalResponse;
+export type QuestionHandler = (request: QuestionRequest, options?: {
+    readonly signal?: AbortSignal;
+}) => Promise<QuestionResult> | QuestionResult;
+export type HarnessSessionState = "idle" | "running" | "interrupted" | "closed";
+export type DeliveryMode = "auto" | "steer" | "follow_up";
+export interface DeliveryOptions {
+    readonly source: string;
+    readonly actor?: string;
+    readonly metadata?: Readonly<Record<string, ExternalOriginMetadataValue>>;
+    /** auto: steer a running turn, or start an idle one. */
+    readonly mode?: DeliveryMode;
+}
+export interface DeliveryReceipt {
+    readonly deliveryId: string;
+    readonly sessionId: string;
+    readonly acceptedAt: number;
+    readonly status: "started" | "queued";
+    readonly channel: "turn" | SteerChannel;
+    readonly steerId?: string;
+    /** Present when delivery started an idle session. */
+    readonly completion?: Promise<RunResult>;
+}
+export interface HarnessSessionStatus {
+    readonly state: HarnessSessionState;
+    readonly activeTurnId: string | null;
+    readonly hasQueuedMessages: boolean;
+}
+export interface DefaultCapabilitiesOptions {
+    /** Context window budget used to size compaction. Defaults to 200_000. */
+    readonly maxContextTokens?: number;
+    /** Workspace MCP servers. When set (or with `pluginManager`), an MCP capability is included. */
+    readonly mcpServers?: Record<string, McpServerConfig>;
+    /**
+     * Installed-plugin manager. When set, the framework self-drives the plugin's contributions into
+     * this capability set: its skills (merged into the skills capability), its MCP servers (merged
+     * into the MCP capability), its shell hooks (merged into user-hooks), and its session-start skill
+     * (rendered via a shared skill registry). Build capabilities fresh per session (a harness
+     * capability factory) and load the manager first, so each session reflects the current plugin set
+     * — read here at construction.
+     */
+    readonly pluginManager?: PluginManager;
+    /**
+     * Session shell hooks from config (`config.hooks`). Merged with plugin hooks when a
+     * `pluginManager` is present (config first, then plugins). Wired as `userHooksCapability`.
+     */
+    readonly hooks?: readonly HookDef[];
+    /**
+     * OAuth service backing MCP servers that need it. Its credential store is the injection point:
+     * a `JsonFileStore` locally, a `MemoryMcpCredentialStore` (hydrated from external storage) on a
+     * server. Only consulted when an MCP capability is built.
+     */
+    readonly oauthService?: McpOAuthService;
+}
+/**
+ * The standard coding-agent capability bundle (goal / plan / todo / skills /
+ * cron / background / compaction). Filesystem access is NOT here — it is a tool
+ * on the agent (`filesystemTools()`), not a capability; so is AskUserQuestion
+ * (`askUserQuestionTool`, wired through ToolRunContext.responder).
+ *
+ * With `mcpServers` and/or `pluginManager`, an MCP capability is added; with `pluginManager`, the
+ * plugin's skills/MCP/session-start are wired in too. Intended to be called fresh per session (via
+ * a harness capability factory) so per-session state (goal/plan/todo/…) and the plugin set are
+ * isolated per session, mirroring a fresh-Session-per-create model.
+ */
+export declare function defaultCapabilities(options?: DefaultCapabilitiesOptions): Capability[];
+export interface HarnessOptions<TContext = unknown> {
+    /** Model for the default agent. Either a constructed `ChatModel` or an id resolved via `resolveModel`. */
+    readonly model: string | ChatModel;
+    /** Resolve string model ids (needed only if `model`/agent models are strings). */
+    readonly resolveModel?: (modelId: string) => ChatModel | Promise<ChatModel>;
+    /**
+     * The model registry backing `resolveModel`. Only needed to let extensions register or override
+     * providers at runtime (`ctx.actions.registerProvider`). Harness-global by nature: one runtime
+     * serves every session, so a registration is visible to all of them. Without it those two
+     * actions throw and everything else works unchanged.
+     */
+    readonly modelRuntime?: ModelRuntime;
+    /** Default working directory for new sessions. Defaults to `process.cwd()`. */
+    readonly workDir?: string;
+    /**
+     * Cap on subagents running concurrently from one session's root frame. Defaults to the same
+     * bound the `Workflow` tool uses, so a batch of `Agent` spawns cannot fan out further than a
+     * workflow would. Nested spawns are exempt by design (they would deadlock a shared pool).
+     */
+    readonly maxConcurrentSubagents?: number;
+    /**
+     * Session repository (the fleet's store + index) — the harness's only storage knob. Injecting one
+     * is how a deployment plugs in storage: `DiskSessionRepository(homeDir)` for local disk, Pg/Redis
+     * on a server. Omit for in-memory sessions (`MemorySessionRepository`).
+     */
+    readonly repository?: SessionRepository;
+    /** Event durability policy. Defaults to `immediate` for low-latency local applications.
+     *  Managed servers override each opened session to `committed`. */
+    readonly eventPublication?: EventPublicationMode;
+    /**
+     * Extra subagent profiles merged into the builtin `coder`/`explore`/`plan` fleet. The SOURCE is
+     * the composition root's concern — disk (`loadAgentProfiles`) locally, external on a server —
+     * but the merge/tool-wiring is identical. Ignored when `subagentProvider` is given.
+     */
+    readonly extraSubagentProfiles?: Record<string, ResolvedAgentProfile>;
+    /**
+     * The agent for new sessions. Provide a complete `Agent`, or omit it to run the builtin default
+     * profile (`DEFAULT_AGENT_PROFILES.agent`) rendered as an agent — there is no piecemeal middle
+     * ground. Per-session overrides go through `createSession({ agent })`.
+     */
+    readonly agent?: Agent<TContext>;
+    /**
+     * Default host application context for sessions. It is runtime-only: never serialized into
+     * the log or SessionStore. Override per session with `createSession({ context })` or provide it
+     * again when reopening a process with `resumeSession(id, { context })`.
+     */
+    readonly context?: TContext;
+    /**
+     * Process-level shared services, registered into the harness's `ServiceRegistry` at
+     * construction. An extension consumes one by naming it in `uses` and receiving it as
+     * `ctx.services[name]` -- a stable handle that resolves the current provider on every call,
+     * which is what makes a host-side
+     * `harness.services.replace()` land without touching any session. A plain value registers
+     * as-is (not replaceable); wrap it as `{ instance, replaceable, dispose }` to opt into hot
+     * swapping. Design: docs/architecture.md §5.5.
+     */
+    readonly services?: Record<string, unknown | ({
+        readonly instance: unknown;
+    } & ServiceOptions)>;
+    /**
+     * Opt-in to FILE extensions, both tiers, from this directory (one folder per extension).
+     * The single explicit switch: without it no file-extension machinery exists ("default
+     * closed"); with it, `harness.extensions` loads/reloads/unloads them — each load being the
+     * manual approval. Extensions with a `create` half publish process-level services and may
+     * embed a session half; see docs/architecture.md §5.4-5.5. (Unrelated to
+     * `pluginManager`, the Codex-compatible skill/MCP plugin system.)
+     */
+    readonly extensionDir?: string;
+    /**
+     * Root of the per-extension data folders handed to `create` halves as `host.dataDir`
+     * (`<root>/<id>`). Defaults to `<extensionDir>/.data` when `extensionDir` is set; by value
+     * only, set it to give `create` halves a place for their files (absent ⇒ `dataDir` is
+     * `undefined`). Kept outside the code folders so an update never touches state.
+     */
+    readonly extensionDataDir?: string;
+    /**
+     * Concrete tool palette the default profile's tool NAMES resolve against (and the subagent palette).
+     * Defaults to `filesystemTools()` plus `askUserQuestionTool`; capability tools (goal/plan/todo/…) are
+     * injected at runtime, so they need not appear here. Ignored when `agent` is given — a complete agent
+     * carries its own tools.
+     */
+    readonly tools?: readonly Tool[];
+    /**
+     * Extra guidance appended to the default agent's system prompt (the profile's `roleAdditional` slot,
+     * rendered after its own prompt). This LAYERS on the default profile — it does not replace it; for a
+     * wholly different prompt, pass a complete `agent`. Ignored when `agent` is given.
+     */
+    readonly appendSystemPrompt?: string;
+    /**
+     * Subagent fleet the `Agent` / `Workflow` tools spawn by type. Defaults to the builtin
+     * `coder` / `explore` / `plan` profiles (each inherits the session model; their tools resolve
+     * against the default agent's toolset), so orchestration works out of the box. Pass your own
+     * provider to override, or `null` to disable subagents entirely — which also hides the
+     * Agent/Workflow tools, since there is nothing for them to spawn.
+     */
+    readonly subagentProvider?: SubagentProvider<TContext> | null;
+    /**
+     * Expose the builtin `Workflow` tool (default true).
+     *
+     * The narrow version of the switch above: use it when the host has its own
+     * workflow orchestration and two overlapping tools would leave the model
+     * guessing. Subagents and the `Agent` tool are unaffected — unlike
+     * `subagentProvider: null`, which necessarily takes both tools with it.
+     */
+    readonly workflowTool?: boolean;
+    /**
+     * Machine for sessions — one shared `Machine` (the sandbox case), or a
+     * {@link MachineFactory} for a per-session one. Defaults to a `LocalMachine`
+     * rooted at each session's own `workDir`.
+     */
+    readonly machine?: Machine | MachineFactory;
+    /**
+     * Capabilities for sessions. Defaults to `defaultCapabilities()`. Pass a factory (sync or async)
+     * to build a FRESH capability set per session — so per-session state (goal/plan/todo/background/
+     * skills/mcp) is isolated and re-reads sources like a plugin manager each session. A plain array
+     * is shared across the harness's sessions (fine only when state needn't be isolated).
+     *
+     * The factory receives the session it is being built for, so capabilities can be
+     * scoped to it — see {@link SessionCapabilityContext}. Existing zero-argument
+     * factories keep working unchanged.
+     */
+    readonly capabilities?: readonly Capability[] | ((ctx: SessionCapabilityContext) => readonly Capability[] | Promise<readonly Capability[]>);
+    /**
+     * Programmatic runtime extensions, registered once here — the by-value twin of `extensionDir`.
+     * Every definition's `setup` runs in every session; a session varies that with
+     * `createSession({ params })` (a value configures, `false` skips). A definition with a
+     * `create` half has it run here, once, and the result registered as a service under its `id`
+     * before any session opens; `harness.close()` unregisters (and disposes) those services.
+     * Each definition's `uses` is checked at this point, in order — a consumer comes after its
+     * provider (or after `services`). Synchronous `create`s finish before `createHarness`
+     * returns; an async one makes sessions wait for it, so `create` must not open a session of
+     * its own. Intentionally independent from Codex-compatible plugins (`pluginManager`): those
+     * are skills/MCP/hooks metadata, extensions are trusted host code.
+     */
+    readonly extensions?: readonly ExtensionDefinition[];
+    /** Permission config. Defaults to `{ mode: "yolo" }`. */
+    readonly permission?: PermissionManagerOptions;
+    /**
+     * Logger for loop diagnostics (LLM request/response, tool I/O, compaction). Defaults to the
+     * `AGENTS_LOG` env var (`AGENTS_LOG=debug` builds a console logger); omit both to stay silent.
+     */
+    readonly logger?: Logger;
+    /** Context budget for the default compaction capability. */
+    readonly maxContextTokens?: number;
+    readonly maxTurns?: number;
+    readonly maxStepsPerTurn?: number;
+}
+/**
+ * What a capability factory is told about the session it is building for.
+ *
+ * Exists so conversation-scoped resources don't force conversation-scoped harnesses.
+ * MCP is the motivating case: a host that gives each conversation its own server
+ * (a REPL kernel keyed by conversation id, say) used to need a whole separate
+ * harness per conversation, duplicating the workspace's agent profile, tool palette,
+ * plugins and skills along with it. Session-scoped servers keep the harness at
+ * workspace scope, where it belongs — `mcpServers` here is the session-level
+ * counterpart of the harness-level `DefaultCapabilitiesOptions.mcpServers`.
+ */
+export interface SessionCapabilityContext {
+    readonly sessionId: string;
+    readonly workDir: string;
+    /** Session-scoped MCP servers, as given to createSession / resumeSession / forkSession. */
+    readonly mcpServers?: Record<string, McpServerConfig>;
+}
+/**
+ * Options common to every way of opening a session.
+ *
+ * Beyond `agent` / `context`, these are per-session overrides of harness-level
+ * defaults. They exist so one harness can serve sessions that differ in workspace,
+ * persona or permission policy, instead of the host having to stand up a whole
+ * harness per combination — which duplicates the agent profile, tool palette,
+ * plugins, skills and MCP connections that have nothing to do with the difference.
+ * Each one is already a session-level input inside the engine; the harness was
+ * simply passing its own value straight through.
+ */
+interface OpenSessionOptionsBase<TContext = unknown> {
+    /** Override the agent for this session only. */
+    readonly agent?: Agent<TContext>;
+    /** Override the execution machine for this session only. Lifecycle remains host-owned. */
+    readonly machine?: Machine | MachineFactory;
+    /** Runtime-only application context for this session. Overrides `HarnessOptions.context`. */
+    readonly context?: TContext;
+    /**
+     * MCP servers scoped to this session, surfaced to the capability factory via
+     * {@link SessionCapabilityContext}. Merge policy is the factory's call — the
+     * harness only carries them across.
+     */
+    readonly mcpServers?: Record<string, McpServerConfig>;
+    /**
+     * Per-session argument for each registered extension, by extension id — handed to that
+     * extension's `setup(api, ctx)` as `ctx.params`. A value of `false` skips the extension for
+     * this session entirely (its `setup` never runs). Persisted with the session, so a
+     * `resumeSession` or a reload re-applies the same params without the caller repeating them.
+     * This is the per-session knob: definitions themselves are registered once, on the harness.
+     */
+    readonly params?: Record<string, unknown>;
+    /** Permission config for this session. Overrides `HarnessOptions.permission`. */
+    readonly permission?: PermissionManagerOptions;
+    /** Override this session's event durability policy. */
+    readonly eventPublication?: EventPublicationMode;
+    /**
+     * Extra system-prompt text for this session's default agent. Overrides
+     * `HarnessOptions.appendSystemPrompt`. Ignored when `agent` is given, since that
+     * replaces the default agent outright.
+     */
+    readonly appendSystemPrompt?: string;
+    /** Turn cap for this session's runs. Overrides `HarnessOptions.maxTurns`. */
+    readonly maxTurns?: number;
+    /**
+     * Step-per-turn cap for this session. Overrides `HarnessOptions.maxStepsPerTurn`.
+     * Carried on the session's default agent (the Runner reads the agent's value
+     * first), so it is ignored when `agent` is given.
+     */
+    readonly maxStepsPerTurn?: number;
+}
+export interface CreateSessionOptions<TContext = unknown> extends OpenSessionOptionsBase<TContext> {
+    readonly id?: string;
+    readonly workDir?: string;
+    /** Partition this session under an owner — see {@link CreateSessionInput.ownerKey}. */
+    readonly ownerKey?: string;
+    readonly title?: string;
+}
+export interface ResumeSessionOptions<TContext = unknown> extends OpenSessionOptionsBase<TContext> {
+}
+export interface ForkSessionOptions<TContext = unknown> extends ResumeSessionOptions<TContext> {
+    readonly id?: string;
+    /** Defaults to the source session's key. */
+    readonly ownerKey?: string;
+    readonly title?: string;
+}
+/** A `Responder` whose approval/question handlers can be swapped at runtime (last-wins). */
+declare class MutableResponder implements Responder {
+    approvalHandler: ApprovalHandler | undefined;
+    questionHandler: QuestionHandler | undefined;
+    /** No handler ⇒ not a live approver ⇒ the run interrupts durably (resume later via
+     *  `HarnessSession.resume`) instead of auto-rejecting the tool. */
+    isLiveApprover(): boolean;
+    requestApproval(request: ApprovalRequest, options?: ApprovalRequestOptions): Promise<ApprovalResponse>;
+    requestQuestion(request: QuestionRequest, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<QuestionResult>;
+}
+/**
+ * Ergonomic per-session facade. Run-driving methods (`prompt`/`steer`/`followUp`/`cancel`/
+ * `onEvent`/approval handlers) live here; everything else delegates to the core
+ * `Session` (reachable via `.core` for anything not surfaced).
+ */
+export declare class HarnessSession<TContext = unknown> {
+    readonly id: string;
+    readonly workDir: string;
+    /** The underlying core session — escape hatch for the full control plane. */
+    readonly core: Session;
+    /**
+     * The session's event stream folded into state. The consumer split: `onEvent` serves
+     * events-as-events (tracing, telemetry); the projection serves state — a late-joining
+     * consumer calls `observeProjection()` and gets an exact history/live seam (no loss,
+     * no duplicates, no dedup).
+     * Attached before the session's first run — see docs/architecture.md §2.3.
+     */
+    readonly projection: SessionProjection;
+    private readonly agent;
+    private readonly runner;
+    private readonly events;
+    private readonly responder;
+    private readonly onClosed;
+    private runContext;
+    private currentRun;
+    /** Barrier gate (docs/architecture.md §5.5): while set, no NEW run starts on this
+     *  session — prompt/resume park at it, promptStream starts lazily behind it. The in-flight
+     *  run is never touched. */
+    private runGate;
+    /** Resolves when the latest run settles — the "arrived at the boundary" signal a barrier
+     *  coordinator awaits. Undefined while idle. */
+    private runSettled;
+    private readonly runSettles;
+    private lastRunInterrupted;
+    private closed;
+    private deliveryCounter;
+    /** A wake is already scheduled on the microtask queue; more enqueues fold into it. */
+    private wakeScheduled;
+    /** Per-session turn cap; the Runner's own config is the fallback. */
+    private readonly maxTurns;
+    constructor(args: {
+        core: Session;
+        agent: Agent<TContext>;
+        runner: Runner<TContext>;
+        events: ListenerSink;
+        responder: MutableResponder;
+        projection: SessionProjection;
+        workDir: string;
+        context?: TContext;
+        maxTurns?: number;
+        interrupted?: boolean;
+        onClosed: (id: string) => void;
+    });
+    /**
+     * Start a turn to consume queued follow-ups, once the current synchronous work is done.
+     *
+     * Deferred to a microtask for two reasons: several enqueues in one stack fold into a single
+     * wake, and a settle that lands in a finishing run's own stack sees `currentRun` already
+     * cleared. Re-checked at fire time because either can change in between — and re-checked
+     * again after every run, since the queue may have filled during one whose drain had passed.
+     */
+    private scheduleIdleWake;
+    /** Run options every run on this session carries — currently the session's turn cap. */
+    private get runOverrides();
+    /** Current runtime-only application context supplied to Agent callbacks. */
+    get context(): TContext | undefined;
+    get status(): HarnessSessionStatus;
+    /** Durable approvals / tool inputs awaiting answers, including after a reopen where the
+     *  historical `turn.paused` event itself is no longer live in Projection. */
+    pendingInterruptions(): Promise<readonly PendingRunInterrupt[]>;
+    /** Replace the runtime-only context used by subsequent prompt/resume calls. */
+    setContext(context: TContext | undefined): void;
+    private beginRun;
+    private endRun;
+    /**
+     * Barrier support (docs/architecture.md §5.5): refuse NEW runs until released and
+     * report when this session reaches its run boundary. Installing the gate is synchronous — a
+     * coordinator gates every affected session FIRST, then awaits quiescence, so the set of
+     * running sessions only shrinks. The in-flight run (if any) is never signaled or aborted;
+     * `quiescent` settles when it finishes on its own. `release` is idempotent and always safe —
+     * a coordinator calls it in a finally so a failed barrier leaves nothing held.
+     */
+    holdAtBoundary(): {
+        readonly quiescent: Promise<void>;
+        release(): void;
+    };
+    /** Run a turn to completion. Serialized with other runs on this session. */
+    prompt(input: AgentInput): Promise<RunResult>;
+    private runPrompt;
+    /**
+     * Hand a message to the frame running at `address` in this session (`main` for the root agent,
+     * `main/<agentId>` for a subagent); `false` when nobody is there. The seam an out-of-process
+     * coordinator uses to address a specific subagent.
+     */
+    steerTo(address: string, content: string, origin: SteerOrigin): boolean;
+    /**
+     * Deliver an externally-originated message. A running session receives it through the
+     * requested SteerBus channel; an idle session starts a new turn immediately.
+     *
+     * ACCEPTANCE IS DURABLE BEFORE THIS RESOLVES. The input is journaled as `inbox.received`
+     * and that write is awaited before a receipt exists, so the receipt means "this survives a
+     * crash", not merely "this reached a process". Previously the message lived only in memory
+     * (SteerBus, or an argument to `runPrompt`) until the run that consumed it journaled it —
+     * a crash in that window lost a delivery the caller had already been told was accepted.
+     *
+     * The provenance of what the model ultimately sees is still persisted on the eventual
+     * `message.appended` record: acceptance and processing are journaled separately because
+     * they can legitimately differ (capability rewrite, guardrail rejection, or a capability
+     * answering the prompt outright).
+     */
+    deliver(input: string, options: DeliveryOptions): Promise<DeliveryReceipt>;
+    /**
+     * Dispatch an input whose acceptance is ALREADY journaled.
+     *
+     * A worker draining a session's inbox calls this directly: the `inbox.received` record exists,
+     * so going back through `deliver` would write a second one and count the delivery twice. The
+     * split is the whole reason acceptance and dispatch are separable — accepting is a durable
+     * write that must happen before a receipt exists, dispatching is what someone holding the
+     * session's lease does with it afterwards, possibly on another machine, possibly much later.
+     *
+     * Run state is read HERE, not at acceptance: by now a turn may have started or ended, so
+     * whether this steers work in flight or starts a fresh turn can only be decided now.
+     */
+    dispatchAccepted(input: string, origin: SteerOrigin & {
+        readonly kind: "external";
+    }, acceptedAt?: number): DeliveryReceipt;
+    /**
+     * Resume a durably-interrupted run. When a `prompt` returns `status:"interrupted"` — which
+     * happens when no live approval handler is registered (`no live responder ⇒ durable`) — the run's
+     * interruption control tree was persisted to the session store. This loads it, applies the
+     * caller's `answers` (prefer `approvalId`; a unique `toolCallId` is also accepted), and continues the
+     * run to its next stop. Works across processes as long as the reopened session shares the same
+     * durable store. Same guardrail-facade contract as `prompt` (a tripwire resolves as a terminal
+     * `RunResult`, not a throw).
+     *
+     * An answer is either a bare `ApprovalResponse` (shorthand for the common approval case) or a
+     * discriminated `InterruptAnswer` — pass `{ kind: "input", data }` to answer a durable input
+     * suspension (`ctx.suspend`), which the approval-only shorthand cannot express.
+     *
+     * Recovery: if a previous resume threw mid-flight, the persisted state is left at
+     * `phase: "recovery_required"` with its revision bumped. Calling this again handles it —
+     * the state is re-read from the store here, so it is never stale — and continues from the
+     * last durable pause. Only callers driving `Runner.resume` directly with a kept-around
+     * copy see a "stale interruption state" error; re-fetching the persisted state clears it.
+     */
+    resume(answers: Record<string, ApprovalResponse | InterruptAnswer>): Promise<RunResult>;
+    /** Streaming variant: iterate events, await `.completed` for the result. */
+    promptStream(input: AgentInput): RunHandle<RunResult>;
+    /** Synthesize the terminal RunResult for a guardrail tripwire (facade contract). */
+    private guardrailBlocked;
+    /**
+     * Inject a user message into the in-flight (or next) turn. Returns the steer's correlation
+     * id: a `steer.queued` event carries it now, and the consuming `message.appended` event's
+     * `origin.steerId` matches it when the model actually sees the message.
+     */
+    steer(input: string): string;
+    /**
+     * Queue a user message for a new turn after the current run's active turn finishes.
+     * Returns the steer's correlation id (see `steer`), or null when the session has no
+     * active run — use `prompt` instead in that case.
+     */
+    followUp(input: string): string | null;
+    /** Abort the current run. */
+    cancel(): void;
+    /** Subscribe to this session's event stream. Returns an unsubscribe fn. */
+    onEvent(listener: AgentEventListener): () => void;
+    /** Current folded state. Consumers that also need subsequent events should use
+     *  `observeProjection()` for an atomic history/live seam. */
+    snapshot(options?: SnapshotOptions): SessionSnapshot;
+    /** Post-apply event feed: every delivered event's effect is already in `snapshot()`.
+     *  Listeners must be synchronous — backpressure belongs to the transport. */
+    subscribeProjection(listener: ProjectionListener): () => void;
+    /** Atomically subscribe to post-fold AgentEvents and capture the authoritative state at
+     *  that boundary. Prefer this over coordinating `snapshot()` and `subscribeProjection()`
+     *  manually in transports and UIs. */
+    observeProjection(listener: ProjectionListener, options?: SnapshotOptions): ProjectionObservation;
+    /** Lightweight per-address summary (which agents exist, who is live/running). */
+    directory(): DirectoryEntry[];
+    setApprovalHandler(handler: ApprovalHandler | undefined): void;
+    setQuestionHandler(handler: QuestionHandler | undefined): void;
+    setModel(model: string | ChatModel): void;
+    setThinking(level: ThinkingLevel): void;
+    /** In-memory switch is immediate; await the returned promise to confirm it was journaled. */
+    setPermissionMode(mode: PermissionMode): Promise<void>;
+    createGoal(...args: Parameters<Session["createGoal"]>): ReturnType<Session["createGoal"]>;
+    getGoal(): ReturnType<Session["getGoal"]>;
+    setPlanMode(...args: Parameters<Session["setPlanMode"]>): ReturnType<Session["setPlanMode"]>;
+    getPlan(): ReturnType<Session["getPlan"]>;
+    compact(...args: Parameters<Session["compact"]>): ReturnType<Session["compact"]>;
+    listSkills(): ReturnType<Session["listSkills"]>;
+    activateSkill(...args: Parameters<Session["activateSkill"]>): ReturnType<Session["activateSkill"]>;
+    listPlugins(): ReturnType<Session["listPlugins"]>;
+    installPlugin(...args: Parameters<Session["installPlugin"]>): ReturnType<Session["installPlugin"]>;
+    listBackgroundTasks(...args: Parameters<Session["listBackgroundTasks"]>): ReturnType<Session["listBackgroundTasks"]>;
+    getRecords(...args: Parameters<Session["getRecords"]>): ReturnType<Session["getRecords"]>;
+    listSubagents(...args: Parameters<Session["listSubagents"]>): ReturnType<Session["listSubagents"]>;
+    reconcileSubagents(...args: Parameters<Session["reconcileSubagents"]>): ReturnType<Session["reconcileSubagents"]>;
+    getContextBreakdown(): ReturnType<Session["getContextBreakdown"]>;
+    /**
+     * Add an extension mid-session. Applied at the next quiet point: immediately when idle,
+     * at the run's stop boundary when one is in flight — its tools appear at the next run's
+     * assembly. The change is journaled; it does NOT survive `resumeSession` (re-attach, or
+     * register it in `createHarness({ extensions })`, which every open re-evaluates). A definition
+     * with a `create` half is accepted only once registered — its service must already exist.
+     */
+    attachExtension(definition: ExtensionDefinition): Promise<void>;
+    /** Remove an extension mid-session: `session.end("detach")` fires, then its scope unwinds. */
+    detachExtension(extensionId: string): Promise<void>;
+    /** Ids of currently attached extensions; empty when the session has no extensions capability. */
+    attachedExtensionIds(): readonly string[];
+    /** Currently attached extensions with what each `uses`; empty without an extensions capability. */
+    attachedExtensions(): readonly {
+        readonly id: string;
+        readonly uses: readonly string[];
+    }[];
+    /** Run a slash command against this session: the static registry plus capability-contributed
+     *  dynamic commands (extensions' `registerCommand`). Commands are the SERIALIZABLE control
+     *  surface — what an out-of-process host (app-server RPC) uses where an in-process host
+     *  reaches `extensionHandle()`. */
+    runCommand(input: string): Promise<CommandResult>;
+    /** The control surface an extension published via `api.expose`; undefined when the extension
+     *  is absent, detached, or exposed nothing. The generic replacement for per-feature session
+     *  facade methods (e.g. cron's — see `cronExtension`). */
+    extensionHandle<T = unknown>(extensionId: string): T | undefined;
+    private extensionRuntime;
+    pauseGoal(...args: Parameters<Session["pauseGoal"]>): ReturnType<Session["pauseGoal"]>;
+    resumeGoal(...args: Parameters<Session["resumeGoal"]>): ReturnType<Session["resumeGoal"]>;
+    cancelGoal(...args: Parameters<Session["cancelGoal"]>): ReturnType<Session["cancelGoal"]>;
+    setGoalBudget(...args: Parameters<Session["setGoalBudget"]>): ReturnType<Session["setGoalBudget"]>;
+    clearPlan(...args: Parameters<Session["clearPlan"]>): ReturnType<Session["clearPlan"]>;
+    pendingCompaction(...args: Parameters<Session["pendingCompaction"]>): ReturnType<Session["pendingCompaction"]>;
+    cancelCompaction(...args: Parameters<Session["cancelCompaction"]>): ReturnType<Session["cancelCompaction"]>;
+    readBackgroundTaskOutput(...args: Parameters<Session["readBackgroundTaskOutput"]>): ReturnType<Session["readBackgroundTaskOutput"]>;
+    readBackgroundTaskOutputDelta(...args: Parameters<Session["readBackgroundTaskOutputDelta"]>): ReturnType<Session["readBackgroundTaskOutputDelta"]>;
+    stopBackgroundTask(...args: Parameters<Session["stopBackgroundTask"]>): ReturnType<Session["stopBackgroundTask"]>;
+    /** Move a running detachable tool call (bash/subagent/workflow) into a background task. */
+    detachTool(...args: Parameters<Session["detachTool"]>): ReturnType<Session["detachTool"]>;
+    getPluginInfo(...args: Parameters<Session["getPluginInfo"]>): ReturnType<Session["getPluginInfo"]>;
+    setPluginEnabled(...args: Parameters<Session["setPluginEnabled"]>): ReturnType<Session["setPluginEnabled"]>;
+    setPluginMcpServerEnabled(...args: Parameters<Session["setPluginMcpServerEnabled"]>): ReturnType<Session["setPluginMcpServerEnabled"]>;
+    removePlugin(...args: Parameters<Session["removePlugin"]>): ReturnType<Session["removePlugin"]>;
+    reloadPlugins(...args: Parameters<Session["reloadPlugins"]>): ReturnType<Session["reloadPlugins"]>;
+    listMcpServers(...args: Parameters<Session["listMcpServers"]>): ReturnType<Session["listMcpServers"]>;
+    reconnectMcpServer(...args: Parameters<Session["reconnectMcpServer"]>): ReturnType<Session["reconnectMcpServer"]>;
+    /** Close the session and release its resources. */
+    close(): Promise<void>;
+}
+/** Manages a fleet of in-process sessions over a shared engine config. */
+export declare class Harness<TContext = unknown> {
+    private readonly options;
+    private readonly runner;
+    private readonly repo;
+    /** Concrete tools the default profile's tool NAMES resolve against (keyed by schema name). */
+    private readonly toolPalette;
+    private readonly activeSessions;
+    /** Process-level shared services. The host replaces providers here (`services.replace`);
+     *  sessions only ever see handles (`ctx.shared`, `ctx.services`). */
+    readonly services: ServiceRegistry;
+    /** The one in-flight reshape barrier (mutex: a second barrier operation rejects). Sessions
+     *  appearing while it holds are gated at birth — see the tail of `openFromStore`. */
+    private activeBarrier;
+    /** File-extension manager (both tiers) — present only when the host opted in with
+     *  `extensionDir`. NOT the Codex-compatible skill/MCP plugin system (`pluginManager`). */
+    readonly extensions: HarnessExtensionManager | undefined;
+    /** Service ids published by by-value `create` halves, in creation order — unregistered (and
+     *  disposed) by `close()`, newest first. */
+    private readonly createdServices;
+    /** The by-value definitions this harness currently mounts into newborn sessions, in
+     *  registration order. Seeded from `createHarness({ extensions })` and rewritten in place by
+     *  `replaceExtension`, so a swap reaches sessions born after it — reading `options.extensions`
+     *  directly would hand new sessions the OLD code, which is exactly the skew the barrier exists
+     *  to prevent. */
+    private readonly valueDefs;
+    /** Root of extensions' data folders (`host.dataDir` = `<root>/<id>`); absent ⇒ none handed out. */
+    private readonly dataRoot;
+    /** Settles once every by-value `create` half has published its service; sessions open after it. */
+    private readonly sharedReady;
+    /** The extension whose `create` is running right now — its `createSession` must refuse. */
+    private runningCreate;
+    constructor(options: HarnessOptions<TContext>);
+    /**
+     * Run one by-value definition's `create` half against a staging host: the service is COLLECTED,
+     * not registered, so a throwing `create` publishes nothing. Stays synchronous when `create` is
+     * — what lets a synchronous extension's service exist the moment `createHarness` returns.
+     * Shared by construction and `replaceExtension`.
+     */
+    private stageValue;
+    /**
+     * Register the by-value definitions, in order: check each one's `uses` against the registry
+     * (a consumer must come after its provider), then run its `create` half if it has one and
+     * register the result as a service under the extension's `id`. Stays synchronous as long as
+     * every `create` is — so `createHarness` returns with a synchronous extension's service
+     * already registered; the first async `create` turns the rest of the sequence into a promise
+     * chain that `openFromStore` awaits. Staging (`stageDefinition`) collects before registering,
+     * so a throwing `create` publishes nothing.
+     */
+    private registerDefinitions;
+    /**
+     * The default agent for sessions with no explicit `agent`: the builtin `agent` profile rendered as
+     * an Agent — its tool names resolved against {@link toolPalette}, its model forced to `options.model`
+     * (the profile declares none). Capability tools (goal/plan/todo/…) still join at runtime via the
+     * session's capabilities.
+     *
+     * Built fresh per session. Runtime-specific prompt data is not captured here: `instructions`
+     * resolves the current frame's machine + cwd through the Session cache, so root/subagent/worktree
+     * prompts stay isolated without coupling Agent lifetime to machine lifetime.
+     */
+    private buildDefaultAgent;
+    get sessions(): ReadonlyMap<string, HarnessSession<TContext>>;
+    createSession(opts?: CreateSessionOptions<TContext>): Promise<HarnessSession<TContext>>;
+    resumeSession(id: string, opts?: ResumeSessionOptions<TContext>): Promise<HarnessSession<TContext>>;
+    /** Fork an existing session into a new one (copies its log + state) and open it. */
+    forkSession(sourceId: string, opts?: ForkSessionOptions<TContext>): Promise<HarnessSession<TContext>>;
+    /** The currently-open session with this id, or undefined (does not reopen — use resumeSession). */
+    getSession(id: string): HarnessSession<TContext> | undefined;
+    /** Read a session's durable handle without constructing a Session, opening capabilities,
+     *  reconciling background tasks, or subscribing Projection. Intended for read-only servers.
+     *  Soft-deleted sessions resolve only with `{ includeDeleted: true }` — audit/purge tooling. */
+    inspectSession(id: string, options?: OpenSessionOptions): Promise<SessionHandle | undefined>;
+    /** Read one catalog row without the O(N) `listSessions()` scan. */
+    getSessionSummary(id: string): Promise<SessionSummary | undefined>;
+    /** Close one open session by id (no-op if it isn't open). */
+    closeSession(id: string): Promise<void>;
+    /**
+     * Delete a session after releasing any open in-process handle. Soft by default — the durable
+     * record is retained and `resumeSession` stops resolving it. `{ purge: true }` destroys it.
+     */
+    deleteSession(id: string, options?: DeleteSessionOptions): Promise<void>;
+    /** Undo a soft delete. No-op when the session is absent or was never deleted. */
+    restoreSession(id: string): Promise<void>;
+    listSessions(filter?: ListSessionsFilter): Promise<readonly SessionSummary[]>;
+    close(): Promise<void>;
+    /**
+     * Replace by-value extensions with new versions, as one coordinated act — the by-value twin of
+     * `harness.extensions.reload()` (docs/architecture.md §5.5). Every session holding
+     * one of them rendezvous at its run boundary (in-flight runs finish untouched — nothing is
+     * aborted); in that global quiet moment the old halves detach, each `create` half re-runs and
+     * its service is swapped, and the new halves attach; then everyone resumes. Sessions born from
+     * the quiet moment on are born with the new definitions. On rendezvous timeout NOTHING changes:
+     * the barrier lifts, `BarrierTimeout` names the stuck sessions, and the caller retries later
+     * (or closes the straggler).
+     *
+     * Pass EVERY definition a shape change affects in ONE call — the provider and the consumers
+     * written against it — so they cross the barrier together; a consumer left out resumes against
+     * the new shape running old code, which is the skew this whole mechanism exists to prevent.
+     *
+     * `services` swaps HOST-registered services (`createHarness({ services })`) in the same quiet
+     * moment, for when the shape that changed is the host's rather than an extension's. Those obey
+     * their `replaceable` flag; an extension's own `create` service swaps unconditionally, since
+     * its owner is being replaced along with it.
+     *
+     * Implementation-only swaps need none of this — `harness.services.replace` (layer 1) lands on
+     * the next call and touches no session at all.
+     */
+    replaceExtension(next: ExtensionDefinition | readonly ExtensionDefinition[], options?: {
+        /** Host-registered services to swap in the same quiet moment, by name. */
+        readonly services?: Readonly<Record<string, unknown>>;
+        /** Rendezvous budget; on expiry the replace fails and nothing changed. Default 30s. */
+        readonly timeoutMs?: number;
+        readonly drainTimeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * The service half of one replaced extension: publish what its `create` staged. `replace`
+     * rather than unregister + register, so consumers this barrier never gated — other extensions
+     * holding a `uses` handle — see no gap; `force` because the owner is being replaced along with
+     * it (see `ServiceRegistry.replace`).
+     */
+    private publishValueService;
+    /** Dispose a `create` result that was staged but never published (default rule: its `close()`). */
+    private disposeStaged;
+    /**
+     * The barrier itself (docs/architecture.md §5.5), shared by `replaceExtension` and
+     * the plugin manager: gate every session holding one of `extensionIds` (synchronously, FIRST
+     * — the set of running sessions only shrinks from there), rendezvous bounded by `timeoutMs`
+     * (a straggler throws BarrierTimeout and nothing ran), then run `fn` in the globally quiet
+     * moment. `held()` reads live, so sessions born gated during the barrier are included.
+     * Whatever happens, every gate is released.
+     */
+    private withBarrier;
+    /** Resolve the capability set for one session — calling the factory fresh when one was given. */
+    private resolveCapabilities;
+    /**
+     * The harness-tier reach handed to a session's extensions: other sessions, and the model
+     * provider registry. Bound to `sessionId` so `fork()` forks THAT session, not whichever one
+     * happens to be active.
+     *
+     * `isIdle`/`waitForIdle` resolve the HarnessSession lazily — at capability-build time the
+     * session object does not exist yet (this runs while it is being constructed).
+     */
+    private extensionHost;
+    private openFromStore;
+    private contextFor;
+}
+/**
+ * A cold open proves that no in-process run still owns lifecycle frames left open in the
+ * previous journal. Close those frames durably so historical event consumers and Projection
+ * agree with HarnessSession.status. A durable interruption is excluded by the caller: its
+ * open turn is intentional continuation state, not a crash remnant.
+ */
+/**
+ * Close the turns a dead process left open, without opening the session.
+ *
+ * A worker that dies mid-turn journals no `turn.ended`; to every reader the turn is still
+ * running. Opening the session repairs that (the same recovery runs inside `resumeSession`),
+ * but opening boots capabilities and a machine just to write two records. This does only the
+ * repair: fold the log, and for every frame still inside a turn append `turn.ended` with
+ * `reason: "failed"` (and `agent.ended` for a live sub-agent). Returns the events those records
+ * project to, so a host that has live subscribers can hand them on — a record appended here
+ * reaches the log, not any broadcast channel.
+ *
+ * A session paused for an answer is left alone: its open turn is waiting, not dead.
+ */
+export declare function closeOrphanedTurns(sessionId: string, store: SessionStore): Promise<readonly AgentEvent[]>;
+/** A reshape rendezvous that did not converge in time. Nothing was changed; the sessions that
+ *  never reached their run boundary are named so the caller can act on them and retry. */
+export declare class BarrierTimeout extends Error {
+    readonly stuckSessionIds: readonly string[];
+    constructor(stuckSessionIds: readonly string[]);
+}
+export declare function createHarness<TContext = unknown>(options: HarnessOptions<TContext>): Harness<TContext>;
+export {};
+//# sourceMappingURL=harness.d.ts.map