@themoltnet/pi-runtime 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,1348 @@
+import { Agent } from '@themoltnet/sdk';
+import { AgentSession } from '@earendil-works/pi-coding-agent';
+import { Api } from '@earendil-works/pi-ai';
+import { BashOperations } from '@earendil-works/pi-coding-agent';
+import { ClaimedTask } from '@themoltnet/agent-runtime';
+import { CommandAnalysis } from '@themoltnet/shell-command-analyzer';
+import { connect } from '@themoltnet/sdk';
+import { ContextRef } from '@themoltnet/agent-runtime';
+import { EditOperations } from '@earendil-works/pi-coding-agent';
+import { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { FindOperations } from '@earendil-works/pi-coding-agent';
+import { GrepToolDetails } from '@earendil-works/pi-coding-agent';
+import { GrepToolInput } from '@earendil-works/pi-coding-agent';
+import { LoadSkillsResult } from '@earendil-works/pi-coding-agent';
+import { LsOperations } from '@earendil-works/pi-coding-agent';
+import { Model } from '@earendil-works/pi-ai';
+import { Readable } from 'node:stream';
+import { ReadOperations } from '@earendil-works/pi-coding-agent';
+import { ShellCommandAnalyzer } from '@themoltnet/shell-command-analyzer';
+import { Skill } from '@earendil-works/pi-coding-agent';
+import { Static } from 'typebox';
+import { SubagentContractRegistry } from '@themoltnet/agent-runtime';
+import { TaskOutput } from '@themoltnet/agent-runtime';
+import { TaskReporter } from '@themoltnet/agent-runtime';
+import { TObject } from 'typebox';
+import { ToolCallEvent } from '@earendil-works/pi-coding-agent';
+import { ToolDefinition } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import { VM } from '@earendil-works/gondolin';
+import { WriteOperations } from '@earendil-works/pi-coding-agent';
+
+/**
+ * Apply agent env vars to the host process, mirroring `moltnet start`.
+ * Resolves relative paths (e.g. GIT_CONFIG_GLOBAL) against the repo root.
+ */
+export declare function activateAgentEnv(agentEnv: Record<string, string | undefined>, repoRoot: string): void;
+
+/** Minimal shape of the SDK method the resolver needs (keeps deps testable). */
+export declare interface AllowedToolsClient {
+    runtimeProfiles: {
+        allowedTools: (profileId: string, options: {
+            teamId: string;
+        }) => Promise<{
+            enforcement: ToolEnforcement;
+            allowedTools: string[];
+        }>;
+    };
+}
+
+/**
+ * Construct an `AgentSession`. By default it is in-memory; callers may opt
+ * parent sessions into daemon-owned file persistence via `sessionPersistence`.
+ * The caller is responsible for eventually invoking `session.prompt(...)` and
+ * for tearing down — the helper does no lifecycle management beyond
+ * construction.
+ */
+export declare function buildAgentSession(args: BuildAgentSessionArgs): Promise<AgentSession>;
+
+declare interface BuildAgentSessionArgs {
+    /** Host directory mounted into the VM. */
+    mountPath: string;
+    /** Host working directory where the agent session should start. */
+    cwdPath: string;
+    /** pi auth directory (resolved from `PI_CODING_AGENT_DIR` or `~/.pi/agent`). */
+    piAuthDir: string;
+    /** Resolved pi model handle (provider + model id). */
+    modelHandle: Model<Api>;
+    /** Optional runtime-profile thinking/reasoning level applied at session start. */
+    thinkingLevel?: PiThinkingLevel | null;
+    /** Optional runtime-profile sampling temperature applied to provider requests. */
+    temperature?: number | null;
+    /** Optional runtime-profile nucleus sampling probability mass. */
+    topP?: number | null;
+    /** Optional runtime-profile top-k sampling cutoff. */
+    topK?: number | null;
+    /** Optional runtime-profile generated output token cap. */
+    maxOutputTokens?: number | null;
+    /** Pre-built customTools array. Caller composes Gondolin + MoltNet + submit tools. */
+    customTools: ToolDefinition[];
+    /**
+     * Exact model-visible tool allowlist. Omit for Pi's default behavior.
+     * Enforce-mode runtimes pass this so denied built-ins are not reconstructed
+     * behind the custom-tool overrides.
+     */
+    tools?: string[];
+    /** System-prompt fragments appended after pi's defaults. Parent passes the
+     *  runtime instructor; subagents pass their narrower variant. */
+    appendSystemPrompt: string[];
+    /** Skills to advertise in `<available_skills>`. Default: empty list. */
+    skillsOverride?: () => LoadSkillsResult;
+    /** Span attributes merged onto every OTel span the session emits. */
+    otelSpanAttrs: Record<string, string | number | boolean>;
+    /** Agent name for `gen_ai.agent.name` on the root span. */
+    agentName: string;
+    /**
+     * Extra pi extension factories appended after the always-on telemetry (and
+     * model-options) extensions — e.g. the tool-policy `tool_call` gate. Each is a
+     * plain `(pi) => void` registrar, same shape as the OTel extension.
+     */
+    extraExtensionFactories?: ((pi: ExtensionAPI) => void)[];
+    /**
+     * Parent sessions may persist their conversation history in a daemon-owned
+     * directory. Subagents should leave this unset and stay in-memory.
+     */
+    sessionPersistence?: {
+        sessionDir: string;
+        forkFromSessionPath?: string | null;
+    };
+}
+
+export declare function buildPiExecutorManifest(input: {
+    runtime: PiRuntimeDefinition;
+    profile: {
+        id: string;
+        definitionCid: string;
+    };
+    template: ResolvedGondolinTemplate;
+    builtInTools?: readonly PiToolDescriptor[];
+    builtInToolNames?: readonly string[];
+}): Promise<PiExecutorManifest>;
+
+/**
+ * Build the minimal immutable system-prompt kernel. Runtime-profile context
+ * carries operator-selected workflow guidance; this kernel stays last in the
+ * system-prompt sequence so the daemon, not injected context, owns these
+ * rules.
+ */
+export declare function buildRuntimeKernel(ctx: RuntimeInstructorContext): string;
+
+export declare function buildWorkspaceMountInstructions(guestWorkspace: string): string;
+
+export declare function createGondolinBashOps(vm: VM, localCwd: string, guestWorkspace: string): BashOperations;
+
+export declare function createGondolinEditOps(vm: VM, localCwd: string, guestWorkspace: string): EditOperations;
+
+export declare function createGondolinFindOps(vm: VM, localCwd: string, guestWorkspace: string): FindOperations;
+
+export declare function createGondolinLsOps(vm: VM, localCwd: string, guestWorkspace: string): LsOperations;
+
+export declare function createGondolinReadOps(vm: VM, localCwd: string, guestWorkspace: string): ReadOperations;
+
+export declare function createGondolinToolDefinitions(config: {
+    vm: VM;
+    cwdPath: string;
+    guestWorkspace: string;
+}): ToolDefinition[];
+
+export declare function createGondolinWriteOps(vm: VM, localCwd: string, guestWorkspace: string): WriteOperations;
+
+/**
+ * Create all MoltNet tool definitions, ready to pass to `pi.registerTool()`.
+ */
+export declare function createMoltNetTools(config: MoltNetToolsConfig): ToolDefinition<any, any>[];
+
+export declare function createPiOtelExtension(options?: PiOtelOptions): (pi: ExtensionAPI) => void;
+
+export declare function createPiRetryTriage(options: {
+    model: Model<Api>;
+    thinkingLevel?: PiRetryTriageThinkingLevel | null;
+    piAgentDir: string;
+    timeoutMs?: number;
+    cwd?: string;
+}): PiRetryTriage;
+
+/**
+ * Factory that builds a pi-specific `executeTask` function suitable for
+ * injection into `AgentRuntime`. The returned function caches the resolved
+ * checkpoint across tasks so the second task hits the snapshot cache.
+ */
+export declare function createPiTaskExecutor(opts: ExecutePiTaskOptions): (claimedTask: ClaimedTask, reporter: TaskReporter) => Promise<TaskOutput>;
+
+/**
+ * Build the subagent custom tool for a parent session. The handle
+ * exposes the call counter so executors can emit summary telemetry
+ * when the parent terminates.
+ */
+export declare function createSubagentTool(args: CreateSubagentToolArgs): SubagentToolHandle;
+
+export declare interface CreateSubagentToolArgs {
+    /** Host directory mounted into the VM. */
+    mountPath: string;
+    /** Host working directory the subagent should start in. Defaults to mountPath. */
+    cwdPath?: string;
+    /** pi auth directory the parent resolved. */
+    piAuthDir: string;
+    /** Resolved pi model handle — subagents share it. */
+    modelHandle: Model<Api>;
+    /** Runtime-profile thinking/reasoning level — subagents inherit it. */
+    thinkingLevel?: PiThinkingLevel | null;
+    /** Runtime-profile sampling temperature — subagents inherit it. */
+    temperature?: number | null;
+    /** Runtime-profile nucleus sampling probability mass — subagents inherit it. */
+    topP?: number | null;
+    /** Runtime-profile top-k sampling cutoff — subagents inherit it. */
+    topK?: number | null;
+    /** Runtime-profile generated output token cap — subagents inherit it. */
+    maxOutputTokens?: number | null;
+    /** Agent name for telemetry. */
+    agentName: string;
+    /**
+     * Custom tools every subagent inherits (Gondolin-routed
+     * built-ins + moltnet_* tools, etc). MUST NOT include
+     * the parent's submit-output tool, the parent's `subagent` tool,
+     * or any other parent-only artefact — the caller is responsible
+     * for filtering. The subagent appends its own submit tool.
+     */
+    inheritedCustomTools: ToolDefinition[];
+    /** Exact enforce-mode tool allowlist inherited from the parent session. */
+    tools?: string[];
+    /**
+     * The parent runtime instructor verbatim. Subagents prepend it to
+     * their own short "you are a subagent" preamble so the same
+     * invariants (gh auth, diary discipline, accountable commits)
+     * apply if the subagent takes those actions. The parent's task
+     * description dictates whether they should.
+     */
+    parentRuntimeInstructor: string;
+    parentTaskId: string;
+    parentTaskType: string;
+    parentAttemptN: number;
+    /**
+     * Parent task's cancel signal. When the daemon cancels the parent
+     * task (operator cancel or task-level `runningTimeoutSec` expiry),
+     * each in-flight subagent's inner `session.abort()` is invoked so
+     * it tears down promptly instead of running until its own LLM
+     * call resolves. Mirrors the existing `wireSessionAbort` pattern
+     * the parent session uses.
+     *
+     * Optional only because the test seam can omit it; production
+     * callers (executePiTask) pass `reporter.cancelSignal`.
+     */
+    parentCancelSignal?: AbortSignal;
+    /**
+     * Per-call fallback timeout. Defends against an inner session that
+     * ignores `abort()` for any reason (LLM provider stuck, tool call
+     * hanging on I/O, etc.). When the timeout fires, `session.abort()`
+     * is invoked and the tool returns `isError: true` with a
+     * `subagent_timed_out` reason the parent LLM can recover from.
+     *
+     * Default: 5 minutes. Set to `0` to disable (relying purely on
+     * parentCancelSignal). Negative values are treated as the default.
+     */
+    timeoutMs?: number;
+    /**
+     * Test seam. Production callers leave this undefined and get
+     * `buildAgentSession` from the factory module. Tests inject a mock
+     * that returns a stub session implementing only `prompt()` to
+     * exercise the tool's logic without booting a VM.
+     */
+    buildAgentSession?: (args: BuildAgentSessionArgs) => Promise<AgentSession>;
+    /**
+     * Contract registry for resolving output_schema names to TypeBox
+     * schemas at call time. The subagent tool reads ONLY via `.get()`
+     * and `.list()` — the registry is immutable after construction.
+     *
+     * Production callers (executePiTask) create the registry with
+     * built-in contracts at session-setup; tests inject a registry
+     * with whatever stubs they need.
+     */
+    contractRegistry: SubagentContractRegistry;
+    /**
+     * Extra pi extension factories every subagent session registers — chiefly the
+     * tool-policy `tool_call` gate. A subagent runs in its own `AgentSession`, so
+     * without re-registering the gate here it would execute tools un-checked,
+     * escaping the parent's enforcement (#1348 B2). Empty/undefined when tool
+     * enforcement is `off`, so subagents then match the parent's un-gated
+     * behaviour. The factories are read-only closures, safe to share across the
+     * parent and every subagent session.
+     */
+    extraExtensionFactories?: ((pi: ExtensionAPI) => void)[];
+}
+
+/**
+ * A pi extension factory that gates every `tool_call` against the resolved
+ * policy. Blocks in `enforce`, audits (and allows) in `watch`, and is a no-op in
+ * `off`. Register it in a session's `extensionFactories`.
+ */
+export declare function createToolPolicyExtension(deps: ToolPolicyExtensionDeps): (pi: ExtensionAPI) => void;
+
+/**
+ * Map a pi `tool_call` event to a gate decision, extracting the shell command
+ * for `bash` and delegating to {@link decideToolCall}.
+ */
+export declare function decideForEvent(event: ToolCallEvent, policy: SessionToolPolicy, analyze: ShellCommandAnalyzer['analyze']): GateDecision;
+
+/**
+ * Decide whether a tool call is permitted by the resolved policy.
+ *
+ * Fail-closed in `enforce` (audited-but-allowed in `watch`, no-op in `off`) for:
+ *
+ * 1. **Unresolvable commands** — a `bash` command whose executables cannot be
+ *    statically resolved (command substitution, `eval`, non-literal command
+ *    names, unparseable input).
+ * 2. **Arbitrary-code interpreters** — a `bash` command that invokes a shell or
+ *    language interpreter (`bash -c`, `python`, `node`, `perl`, …; the
+ *    analyzer's `arbitrary-code` risk tier). Being name-listed is NOT enough:
+ *    we cannot statically see the code such an interpreter runs, so the policy's
+ *    allow-set can't bound it. This is the interim conservative stance for
+ *    issue #1348 — an operator who lists `bash` still cannot smuggle
+ *    `bash -c "curl … | sh"` past `enforce`.
+ * 3. **Unlisted executables** — any resolved executable not in `allowedTools`.
+ *
+ * KNOWN LIMITATION (follow-up): the `escapable` risk tier (GTFOBins binaries
+ * like `find`, `tar`, `awk` that document shell-spawn / file-write techniques)
+ * is NOT blocked on the tier alone. The analyzer already re-analyzes the
+ * sub-commands it can see through documented escape flags (`find -exec`,
+ * `tar --to-command`, …), but techniques it cannot parse statically could still
+ * escape a name-based allow-set. Tightening `escapable` (e.g. an LLM judge or a
+ * capability-aware allow-set) is tracked as future work.
+ */
+export declare function decideToolCall(input: GateInput): GateDecision;
+
+export declare function defineGondolinTemplate(options: DefineGondolinTemplateOptions): GondolinTemplateDefinition;
+
+export declare interface DefineGondolinTemplateOptions {
+    id: string;
+    version: string;
+    snapshot?: SnapshotConfig;
+    checkpointPath?: string;
+    resolveCheckpoint?(context: GondolinTemplateResolveContext): Promise<string>;
+    fingerprint?: string;
+    executables?: readonly string[];
+    resumeCommands?: readonly ResumeCommand[];
+}
+
+export declare function definePiExtension(options: PiExtensionOptions): PiExtensionContribution;
+
+export declare function definePiRuntime(options: DefinePiRuntimeOptions): PiRuntimeDefinition;
+
+export declare interface DefinePiRuntimeOptions {
+    id: string;
+    version: string;
+    runtimeKind?: string;
+    vm: GondolinTemplateDefinition;
+    tools?: readonly PiToolContribution[];
+    extensions?: readonly PiExtensionContribution[];
+}
+
+export declare function definePiTool(tool: ToolDefinition, options?: {
+    scope?: PiToolScope;
+}): PiToolContribution;
+
+export declare function definePiTool(options: PiToolFactoryOptions): PiToolContribution;
+
+export declare function enabledPiToolNames(input: {
+    tools: readonly ToolDefinition[];
+    extensions?: readonly PiExtensionContribution[];
+    policy?: {
+        enforcement: ToolEnforcement;
+        allowedTools: ReadonlySet<string>;
+    };
+}): string[] | undefined;
+
+/**
+ * Ensure a cached snapshot exists, building one if needed.
+ * Returns the absolute path to the qcow2 checkpoint file.
+ */
+export declare function ensureSnapshot(options?: EnsureSnapshotOptions): Promise<string>;
+
+export declare interface EnsureSnapshotOptions {
+    config?: SnapshotConfig;
+    onProgress?: (message: string) => void;
+    /** Max number of old snapshots to keep (default 1). */
+    maxCached?: number;
+}
+
+export declare function executeGondolinGrep(vm: VM, localCwd: string, guestWorkspace: string, params: GrepToolInput, signal?: AbortSignal): Promise<TextToolResult<GrepToolDetails>>;
+
+/**
+ * Run one attempt of `task` in a freshly-resumed Gondolin VM. Owns the full
+ * lifecycle: resume VM → wire tools → pi session → close VM. Always returns
+ * a `TaskOutput` (failures surface as `status: 'failed'`); throws only on
+ * unrecoverable setup errors.
+ */
+export declare function executePiTask(claimedTask: ClaimedTask, reporter: TaskReporter, opts: ExecutePiTaskOptions): Promise<TaskOutput>;
+
+export declare interface ExecutePiTaskOptions {
+    /** MoltNet agent whose credentials the VM boots with. */
+    agentName: string;
+    /**
+     * Host root that owns `.moltnet/<agentName>/`.
+     *
+     * Defaults to `mountPath`, but callers that mount scratch workspaces should
+     * pass the stable sandbox root.
+     */
+    agentRootDir?: string;
+    /** Host cwd that the VM mounts into the guest (defaults to `process.cwd()`). */
+    mountPath?: string;
+    /** LLM selection. */
+    provider: string;
+    model: string;
+    /**
+     * Runtime-profile reasoning/thinking level. Null/undefined means use Pi's
+     * configured default; explicit `off` disables provider thinking where
+     * supported.
+     */
+    thinkingLevel?: PiThinkingLevel | null;
+    /** Optional sampling temperature. Null/undefined means provider default. */
+    temperature?: number | null;
+    /** Optional nucleus-sampling probability mass. Null/undefined means provider default. */
+    topP?: number | null;
+    /** Optional top-k sampling cutoff. Null/undefined means provider default. */
+    topK?: number | null;
+    /** Optional cap on generated output tokens. Null/undefined means provider/model default. */
+    maxOutputTokens?: number | null;
+    /** Extra hosts to allow in the sandbox egress policy. */
+    extraAllowedHosts?: string[];
+    /** Sandbox overrides (env, VFS shadows, resources). */
+    sandboxConfig?: SandboxConfig;
+    /** Host environment variable names to forward into the Pi VM. */
+    forwardEnv?: string[];
+    /**
+     * Runtime profile context defaults. Merged with task.input.context at
+     * execution time because the selected runtime profile is known only after
+     * claim. Task entries override profile entries with the same slug.
+     */
+    runtimeProfileContext?: readonly ContextRef[];
+    /**
+     * Runtime profile id, used to resolve the tool-policy allow-set at session
+     * start. Required together with a non-`off` `toolEnforcement` for the
+     * `tool_call` gate to run.
+     */
+    runtimeProfileId?: string;
+    /** Tool-policy enforcement mode for the selected runtime profile. */
+    toolEnforcement?: ToolEnforcement;
+    /**
+     * Forwarded to `buildTaskUserPrompt` for per-type builders. Static
+     * across tasks. Today no built-in builder needs per-task `extras` —
+     * judges fetch their own dependent data via MoltNet tools
+     * (`moltnet_get_task`, `moltnet_list_task_attempts`, etc.) at run
+     * time, which keeps this layer task-type-agnostic. Field is kept
+     * for forward compat with custom prompt builders that might want it.
+     */
+    promptExtras?: Record<string, unknown>;
+    /** Snapshot progress callback; defaults to stderr logging. */
+    onSnapshotProgress?: (message: string) => void;
+    /**
+     * Optional pre-resolved checkpoint path. If omitted, `ensureSnapshot` is
+     * invoked. Useful for batch execution where the caller wants to cache
+     * across tasks.
+     */
+    checkpointPath?: string;
+    /**
+     * Lazy checkpoint resolver used by `createPiTaskExecutor` so snapshot
+     * creation can happen after the reporter has been opened and can surface
+     * setup failures as task messages.
+     */
+    resolveCheckpointPath?: () => Promise<string>;
+    /**
+     * Set when the caller already opened the reporter before handing control
+     * to `executePiTask`.
+     */
+    reporterAlreadyOpened?: boolean;
+    /**
+     * Optional callback invoked alongside every `reporter.record()` so
+     * the daemon can mirror task messages into its local logger.
+     * Bound at executor-construction time — use when one task runs per
+     * process (e.g. `once.ts`) and per-task context is known before
+     * the executor is built. For poll mode, prefer `makeOnTurnEvent`
+     * below. If both are set, `makeOnTurnEvent` wins.
+     * See `TurnEventHandler` for payload shape. Defaults to a no-op.
+     */
+    onTurnEvent?: TurnEventHandler;
+    /**
+     * Per-task factory variant for `onTurnEvent`. Invoked once per
+     * task with the claimed task before any emit, so the returned
+     * handler can bind taskId / attemptN into a pino child.
+     * Use in poll mode where N tasks run sequentially in the same
+     * process. See #1078.
+     */
+    makeOnTurnEvent?: TurnEventHandlerFactory;
+    /**
+     * Cap the number of tool-use turns per attempt. When the limit is
+     * reached, the pi session is aborted and the attempt finalizes with
+     * `error.code: max_turns_exceeded`. A tool-use turn = any `turn_end`
+     * whose `stopReason !== 'end_turn'` (matches the Anthropic SDK
+     * `max_turns` semantics: the model's final text-only response doesn't
+     * count). Default `0` = disabled. Recommended `30` for `fulfill_brief`.
+     * Closes part of #1094.
+     */
+    maxTurns?: number;
+    /**
+     * Cap the number of `bash` tool timeouts per attempt. A timeout is a
+     * `tool_execution_end` for `bash` whose result text contains
+     * "Command timed out after" (pi's stable error wrapper from
+     * `@earendil-works/pi-coding-agent`'s bash tool). When the limit is
+     * reached, the pi session is aborted and the attempt finalizes with
+     * `error.code: max_bash_timeouts_exceeded`. Catches the death-spiral
+     * pattern from task `a3762f44` where the model kept retrying
+     * long-blocking shell commands until the host job timeout fired.
+     * Default `3`. Set to `0` to disable. Closes part of #1094.
+     */
+    maxBashTimeouts?: number;
+    /**
+     * Number of correction turns allowed after the first invalid submit-output
+     * tool call. A value of 2 permits three invalid submit calls total before
+     * the attempt fails with output_validation_failed.
+     */
+    maxSubmitValidationRetries?: number;
+    /**
+     * Number of same-session re-prompts when the model ends its turn WITHOUT
+     * calling the submit-output tool at all (no captured payload and no
+     * exhausted validation budget). Distinct from
+     * `maxSubmitValidationRetries`, which recovers *invalid-args* submit calls.
+     * Each re-prompt names the submit tool and forbids a prose reply. When the
+     * budget is spent the attempt still fails with `submit_output_missing`.
+     * Only applies to task types that register a submit tool. Default `3`. Set
+     * to `0` to disable. See #1528.
+     */
+    maxSubmitMissingReprompts?: number;
+    /**
+     * Continuation prompt sent when a turn ends without a submit call. Defaults
+     * to `buildSubmitMissingPrompt(<tool name>)`.
+     */
+    submitMissingPrompt?: string;
+    /**
+     * Cap provider-error retries inside the same Pi session. A retry is attempted
+     * only after a Pi assistant turn ends with `stopReason: "error"` and the
+     * provider diagnostic is not a known credential/model/config failure. This is
+     * distinct from daemon attempt retry: the active session keeps its context and
+     * receives a short continuation prompt.
+     *
+     * Default `4`. Set to `0` to disable.
+     */
+    maxProviderErrorRetries?: number;
+    /** Base delay for same-session provider-error retries. Default `2000`. */
+    providerErrorRetryBaseDelayMs?: number;
+    /** Maximum delay for same-session provider-error retries. Default `30000`. */
+    providerErrorRetryMaxDelayMs?: number;
+    /** Continuation prompt sent after a retryable provider error. Default `Go on`. */
+    providerErrorRetryPrompt?: string;
+    /**
+     * Optional UI adapter for interactive pi/TUI callers. The daemon normally
+     * leaves this unset and consumes the structured `provider_error_retry` task
+     * message instead.
+     */
+    providerErrorRetryUi?: ProviderErrorRetryUi;
+    /**
+     * Skip per-call UI approval for matching `moltnet_host_exec` commands.
+     * Keep false/undefined for interactive consumers. `true` skips every dialog
+     * after HOST_EXEC_ALLOWED; an array limits auto-approval to matching rules.
+     */
+    hostExecAutoApprove?: HostExecAutoApproveConfig;
+    /**
+     * Optional daemon-supplied execution plan. Keeps task semantics out of
+     * `pi-extension` while still letting callers opt into stable worktrees and
+     * file-backed Pi sessions for selected task classes.
+     */
+    makeExecutionPlan?: PiTaskExecutionPlanFactory;
+    /**
+     * Immutable subagent contract registry used to resolve `output_schema`
+     * names at subagent tool call time. Constructed by the daemon (or
+     * tests) from static built-in schemas — `execute-pi-task` never hardcodes
+     * contracts. See #1106.
+     */
+    subagentContractRegistry?: SubagentContractRegistry;
+    /**
+     * Structured logger for tool-policy resolution/gate events. The daemon passes
+     * its task-bound pino child so these lines carry taskId/attemptN and join the
+     * run's NDJSON stream. When omitted, tool-policy events fall back to raw
+     * NDJSON on stderr (single-process / test callers). See #1348.
+     */
+    toolPolicyLogger?: ToolPolicyLogger;
+    /** Trusted, statically imported operator runtime contributions. */
+    runtimeDefinition?: PiRuntimeDefinition;
+    /**
+     * Pre-resolved local VM template. Daemons resolve this before polling so
+     * profile requirements and executor attestation can be checked before claim.
+     */
+    resolvedVmTemplate?: ResolvedGondolinTemplate;
+    /** Internal/lower-level lazy template resolver used by executor factories. */
+    resolveVmTemplate?: () => Promise<ResolvedGondolinTemplate>;
+}
+
+export declare function filterModelVisibleTools(tools: readonly ToolDefinition[], policy?: {
+    enforcement: ToolEnforcement;
+    allowedTools: ReadonlySet<string>;
+}): ToolDefinition[];
+
+/**
+ * Resolve the main worktree root (where .moltnet/ lives — it's untracked,
+ * only exists in the main worktree, not in git worktrees).
+ */
+export declare function findMainWorktree(startPath?: string): string;
+
+/**
+ * The gate's verdict:
+ * - `{ allow: true }` — let the tool run.
+ * - `{ allow: false, reason }` — block it (enforce mode).
+ * - `{ audit, ... }` — would-block, but proceed and record it (watch mode).
+ */
+export declare type GateDecision = {
+    allow: true;
+} | {
+    allow: false;
+    reason: string;
+} | {
+    audit: string;
+    missing?: string[];
+};
+
+export declare interface GateInput {
+    /** Pi tool name (e.g. 'bash', 'read', 'write', or a custom tool id). */
+    toolName: string;
+    /** The shell command, when `toolName === 'bash'`. */
+    command?: string;
+    enforcement: ToolEnforcement;
+    /** Names the policy allows (structured tool names + shell executable names). */
+    allowedTools: ReadonlySet<string>;
+    /**
+     * Synchronous shell analyzer (`ShellCommandAnalyzer.analyze`). Injected so the
+     * decision stays pure and testable; the analyzer's async WASM init happens
+     * once at session start.
+     */
+    analyze: (command: string) => CommandAnalysis;
+}
+
+export declare const GONDOLIN_TOOL_NAMES: readonly ["read", "write", "edit", "bash", "ls", "find", "grep"];
+
+export declare interface GondolinTemplateDefinition {
+    readonly kind: 'gondolin';
+    readonly id: string;
+    readonly version: string;
+    readonly executables: readonly string[];
+    readonly resumeCommands: readonly ResumeCommand[];
+    resolve(context?: GondolinTemplateResolveContext): Promise<ResolvedGondolinTemplate>;
+}
+
+export declare interface GondolinTemplateResolveContext {
+    onProgress?: (message: string) => void;
+}
+
+/**
+ * Baseline env keys forwarded to host-exec child processes.
+ * Callers can extend this set at sandbox startup via `MoltNetToolsConfig.hostExecBaseEnv`.
+ */
+export declare const HOST_EXEC_DEFAULT_BASE_ENV: ReadonlySet<string>;
+
+declare type HostExecAutoApproveConfig = boolean | readonly HostExecAutoApproveRule[];
+
+declare interface HostExecAutoApproveRule {
+    /** Exact executable name. Must still pass HOST_EXEC_ALLOWED. */
+    executable: string;
+    /** Optional ordered argument prefix; flags after the prefix are allowed. */
+    argsPrefix?: readonly string[];
+    /** Optional unordered argument tokens that must appear somewhere. */
+    argsContains?: readonly string[];
+    /** Optional argument tokens that prevent auto-approval when present. */
+    argsExcludes?: readonly string[];
+}
+
+export declare interface InjectedTaskContext {
+    /** Refs that were delivered, in declared order, for audit. */
+    injected: ContextRef[];
+    /** Synthetic Skill objects to splice into pi's skillsOverride. */
+    skills: Skill[];
+    /** Prepend this to `appendSystemPrompt`. Empty when nothing
+     *  contributed (omit the array entry rather than pass an empty
+     *  string to keep pi's prompt assembly tidy). */
+    systemPromptPrefix: string;
+    /** Append this to the task user prompt BEFORE `session.prompt()`. */
+    userInlineSuffix: string;
+}
+
+/**
+ * Resolve effective runtime context and inject the side effects Pi
+ * needs. Safe to call with an empty array — returns an inert result.
+ */
+export declare function injectTaskContext(args: InjectTaskContextArgs): Promise<InjectedTaskContext>;
+
+export declare interface InjectTaskContextArgs {
+    /** Empty array (the default for any non-eval task) is a no-op. */
+    context: readonly ContextRef[];
+    /** Guest filesystem handle. In production this is `managed.vm.fs`. */
+    fs: VmFsForContext;
+    /** Guest path where the active host workspace is mounted. */
+    guestWorkspace: string;
+}
+
+export declare function isKernelTool(name: string): boolean;
+
+export declare function isToolVisible(name: string, policy?: {
+    enforcement: ToolEnforcement;
+    allowedTools: ReadonlySet<string>;
+}): boolean;
+
+export declare function loadCredentials(agentDir: string): VmCredentials;
+
+export declare interface ManagedVm {
+    vm: VM;
+    credentials: VmCredentials;
+    mountPath: string;
+    guestWorkspace: string;
+    agentDir: string;
+}
+
+export declare function materializePiExtensions(input: {
+    runtime: PiRuntimeDefinition;
+    context: PiToolContext;
+    target: 'parent' | 'subagent';
+    policy?: {
+        enforcement: ToolEnforcement;
+        allowedTools: ReadonlySet<string>;
+    };
+}): Promise<PiExtensionFactory[]>;
+
+export declare function materializePiTools(input: {
+    runtime: PiRuntimeDefinition;
+    context: PiToolContext;
+    target: 'parent' | 'subagent';
+    policy?: {
+        enforcement: ToolEnforcement;
+        allowedTools: ReadonlySet<string>;
+    };
+}): Promise<ToolDefinition[]>;
+
+export declare const MOLTNET_TOOL_NAMES: readonly ["moltnet_pack_get", "moltnet_pack_create", "moltnet_pack_provenance", "moltnet_pack_render", "moltnet_rendered_pack_list", "moltnet_rendered_pack_get", "moltnet_diary_tags", "moltnet_list_entries", "moltnet_get_entry", "moltnet_search_entries", "moltnet_create_entry", "moltnet_get_task", "moltnet_list_task_attempts", "moltnet_list_task_messages", "moltnet_upload_task_artifact", "moltnet_list_task_artifacts", "moltnet_download_task_artifact", "moltnet_review_session_errors", "moltnet_host_exec"];
+
+declare type MoltNetAgent = Awaited<ReturnType<typeof connect>>;
+
+/**
+ * Active-task context. When present, `moltnet_create_entry` is forced to
+ * land entries in `diaryId` (the task diary), regardless of the env-derived
+ * diary, and auto-injects provenance tags under the `task:*` namespace
+ * (`task:id:<id>`, `task:type:<type>`, `task:attempt:<n>`, and
+ * `task:correlation:<id>` when the task carries one). See issue #979 +
+ * the #986 follow-up that introduced the namespace.
+ */
+declare interface MoltNetTaskContext {
+    taskId: string;
+    taskType: string;
+    attemptN: number;
+    diaryId: string;
+    /**
+     * Optional correlation id. When set, propagated as a
+     * `task:correlation:<id>` provenance tag so all entries from a
+     * multi-task workflow can be grouped without enumerating individual
+     * task ids.
+     */
+    correlationId: string | null;
+}
+
+export declare interface MoltNetToolsConfig {
+    getAgent(): MoltNetAgent | null;
+    getDiaryId(): string | null;
+    getTeamId(): string | null;
+    getSessionErrors(): readonly TrackedError[];
+    clearSessionErrors(): void;
+    /** Host working directory for host-exec commands (worktree path or cwd). */
+    getHostCwd?(): string;
+    /**
+     * Optional workspace-file reader. Daemon/Gondolin callers provide this so
+     * artifact uploads see guest overlay writes that may not exist on the host
+     * mount path yet.
+     */
+    openWorkspaceFileForRead?(filePath: string): Promise<{
+        stream: Readable;
+        isFile: boolean;
+        sizeBytes?: number;
+        displayPath?: string;
+    }>;
+    /**
+     * Set of process.env keys that are safe to forward to host-exec child
+     * processes. Configured at sandbox startup so the caller can include
+     * agent-specific vars (e.g. MOLTNET_AGENT_NAME) alongside the defaults.
+     * Defaults to HOST_EXEC_DEFAULT_BASE_ENV when omitted.
+     */
+    hostExecBaseEnv?: ReadonlySet<string>;
+    /**
+     * When true, `moltnet_host_exec` skips the per-call UI approval dialog.
+     * Intended for non-interactive daemon automation only; interactive
+     * consumers should keep the default false behavior.
+     */
+    autoApproveHostExec?: boolean;
+    /**
+     * Host-exec auto-approval policy. `true` skips all dialogs after the
+     * executable allowlist check. An array skips only commands matching one of
+     * the supplied executable/argument rules. Omitted/false preserves the
+     * interactive approval flow.
+     */
+    hostExecAutoApprove?: HostExecAutoApproveConfig;
+    /**
+     * Active-task context, populated by the agent-daemon path. When set,
+     * `moltnet_create_entry` enforces `diaryId === taskContext.diaryId` and
+     * injects provenance tags. When absent (interactive pi-extension / TUI),
+     * entry creation behaves as before (env-derived diary, no auto-tags).
+     */
+    getTaskContext?(): MoltNetTaskContext | null;
+}
+
+export declare function normalizeRetryTriageResult(value: unknown): PiRetryTriageResult;
+
+export declare const PI_EXECUTOR_MANIFEST_VERSION: "moltnet:executor-manifest:v1";
+
+export declare const PI_RUNTIME_DEFINITION_VERSION = "moltnet:pi-runtime:v1";
+
+export declare interface PiExecutorManifest {
+    schemaVersion: typeof PI_EXECUTOR_MANIFEST_VERSION;
+    runtime: {
+        kind: string;
+        engine: 'pi';
+        sandbox: 'gondolin';
+        id: string;
+        version: string;
+    };
+    profile: {
+        id: string;
+        definitionCid: string;
+    };
+    vm: {
+        templateId: string;
+        templateVersion: string;
+        templateFingerprint: string;
+        guestAssetBuildId: string;
+    };
+    tools: {
+        name: string;
+        descriptorCid: string | null;
+        scope: PiToolScope;
+    }[];
+    extensions: {
+        id: string;
+        declaredTools: readonly string[];
+        scope: PiToolScope;
+    }[];
+    executables: readonly string[];
+}
+
+export declare interface PiExtensionContribution {
+    readonly kind: 'extension';
+    readonly id: string;
+    readonly declaredTools: readonly string[];
+    readonly scope: PiToolScope;
+    create: (context: PiToolContext) => PiExtensionFactory | Promise<PiExtensionFactory>;
+}
+
+export declare type PiExtensionFactory = (pi: ExtensionAPI) => void;
+
+export declare interface PiExtensionOptions {
+    id: string;
+    declaredTools?: readonly string[];
+    scope?: PiToolScope;
+    factory?: PiExtensionFactory;
+    create?: (context: PiToolContext) => PiExtensionFactory | Promise<PiExtensionFactory>;
+}
+
+export declare interface PiOtelOptions {
+    /** Agent name for `gen_ai.agent.name` on the root span. */
+    agentName?: string;
+    /**
+     * Extra attributes merged onto every span. Use MoltNet-specific keys
+     * like `moltnet.task.id` — any `gen_ai.*` keys here are filtered out
+     * since the extension is authoritative for those.
+     */
+    spanAttributes?: Record<string, string | number | boolean>;
+}
+
+export declare type PiRetryTriage = (input: PiRetryTriageInput) => Promise<PiRetryTriageResult>;
+
+export declare type PiRetryTriageConfidence = RetryTriageConfidence;
+
+export declare type PiRetryTriageDecision = RetryTriageDecision;
+
+export declare interface PiRetryTriageInput {
+    task: {
+        id: string;
+        taskType: string;
+        teamId: string;
+        input: unknown;
+    };
+    attemptN: number;
+    maxAttempts?: number | null;
+    remainingAttempts?: number | null;
+    error: unknown;
+    recentMessages?: {
+        timestamp: string;
+        kind: string;
+        payload: unknown;
+    }[];
+}
+
+export declare interface PiRetryTriageResult {
+    decision: RetryTriageDecision;
+    confidence: RetryTriageConfidence;
+    reason: string;
+}
+
+export declare type PiRetryTriageThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+
+export declare interface PiRuntimeDefinition {
+    readonly schemaVersion: typeof PI_RUNTIME_DEFINITION_VERSION;
+    readonly id: string;
+    readonly version: string;
+    readonly runtimeKind: string;
+    readonly vm: GondolinTemplateDefinition;
+    readonly tools: readonly PiToolContribution[];
+    readonly extensions: readonly PiExtensionContribution[];
+}
+
+export declare interface PiSessionPersistencePlan {
+    sessionDir: string;
+    forkFromSessionPath?: string | null;
+}
+
+export declare interface PiTaskExecutionPlan {
+    /**
+     * Effective workspace mode for this task instance.
+     * `scratch_mount` means mount an empty scratch directory rather than the
+     * daemon checkout.
+     */
+    workspaceMode: 'shared_mount' | 'dedicated_worktree' | 'scratch_mount';
+    /**
+     * Daemon-local reuse key. When set alongside `workspaceScope: 'session'`,
+     * dedicated worktrees may be retained and reopened across related tasks.
+     */
+    sessionKey: string | null;
+    /**
+     * Workspace identity selected by the daemon. `null` means the task should
+     * run against the shared mount path.
+     */
+    workspaceId: string | null;
+    /**
+     * Branch to create or reopen for the workspace. `null` means no dedicated
+     * worktree is required.
+     */
+    worktreeBranch: string | null;
+    /**
+     * Base ref a NEW `worktreeBranch` is cut from. Used by `fork` continuations
+     * to branch from the parent's tip instead of the default (main/HEAD). Ignored
+     * when `worktreeBranch` already exists.
+     */
+    worktreeBaseRef?: string | null;
+    /**
+     * Lifetime of the task workspace from the daemon's point of view.
+     * `attempt` = disposable; `session` = keep stable for the reuse key.
+     */
+    workspaceScope: 'attempt' | 'session';
+    /**
+     * Optional existing workspace root to attach instead of creating a fresh
+     * shared/worktree/scratch workspace. Used for read-only-ish producer
+     * inspection by applying VFS shadowing on top of the mounted path.
+     */
+    workspaceAttachment?: PiWorkspaceAttachmentPlan | null;
+    /**
+     * Optional seed content for a freshly created scratch workspace.
+     */
+    workspaceSeed?: PiWorkspaceSeedPlan | null;
+    /**
+     * Optional location for file-backed Pi session history. When omitted,
+     * the executor keeps the conversation in memory for this attempt only.
+     */
+    sessionPersistence?: PiSessionPersistencePlan | null;
+}
+
+export declare type PiTaskExecutionPlanFactory = (claimedTask: ClaimedTask) => Promise<PiTaskExecutionPlan | null> | PiTaskExecutionPlan | null;
+
+declare type PiThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+
+export declare interface PiToolContext {
+    agent: Agent;
+    claimedTask: ClaimedTask;
+    reporter: TaskReporter;
+    vm: VM;
+    cwdPath: string;
+    guestWorkspace: string;
+}
+
+export declare interface PiToolContribution {
+    readonly kind: 'tool';
+    readonly descriptor: PiToolDescriptor;
+    readonly scope: PiToolScope;
+    create: (context: PiToolContext) => ToolDefinition | Promise<ToolDefinition>;
+}
+
+export declare type PiToolDescriptor = Pick<ToolDefinition, 'name' | 'label' | 'description' | 'parameters'>;
+
+export declare interface PiToolFactoryOptions {
+    descriptor: PiToolDescriptor;
+    scope?: PiToolScope;
+    create: (context: PiToolContext) => ToolDefinition | Promise<ToolDefinition>;
+}
+
+export declare type PiToolScope = 'parent' | 'parent_and_subagents';
+
+declare interface PiWorkspaceAttachmentPlan {
+    mountPath: string;
+    cwdPath: string;
+    shadowWrites?: 'deny' | 'tmpfs';
+}
+
+declare interface PiWorkspaceSeedPlan {
+    copyFromPath: string;
+    source: 'producer';
+}
+
+export declare interface ProviderErrorRetryEvent extends Record<string, unknown> {
+    event: 'provider_error_retry';
+    retry: number;
+    maxRetries: number;
+    delayMs: number;
+    reason: string;
+}
+
+export declare type ProviderErrorRetryLevel = 'info' | 'warning' | 'error';
+
+export declare interface ProviderErrorRetryUi {
+    /**
+     * Mirrors pi's `ctx.hasUI`. Undefined means "UI adapter is present"; false
+     * lets callers pass a stable adapter from both TUI and headless contexts.
+     */
+    hasUI?: boolean;
+    setStatus?: (key: string, message: string) => void | Promise<void>;
+    notify?: (message: string, level: ProviderErrorRetryLevel) => void | Promise<void>;
+}
+
+export declare function redactRetryTriageSecrets(value: string): string;
+
+export declare interface ResolvedGondolinTemplate {
+    id: string;
+    version: string;
+    checkpointPath: string;
+    fingerprint: string;
+    guestAssetBuildId: string;
+    executables: readonly string[];
+    resumeCommands: readonly ResumeCommand[];
+}
+
+/**
+ * Resolve the session's tool policy at start-up.
+ *
+ * `off` short-circuits without a network call. Otherwise the allowed-tool set
+ * is fetched from the API. If that fetch fails, the mode decides the fallback:
+ * `enforce` **fails closed** (empty allow-set → every non-`off` tool is
+ * blocked); `watch` fails open (empty allow-set → every tool is audited but
+ * allowed).
+ *
+ * The result is a **session-start snapshot**: it is resolved once and cached for
+ * the session's lifetime. Policy edits made while a task is running do not take
+ * effect until the next session — a deliberate trade-off (one resolution per
+ * session, stable enforcement for the run) accepted over re-fetching per call.
+ */
+export declare function resolveSessionToolPolicy(input: ResolveSessionToolPolicyInput): Promise<SessionToolPolicy>;
+
+declare interface ResolveSessionToolPolicyInput {
+    agent: AllowedToolsClient;
+    profileId: string;
+    teamId: string;
+    /**
+     * The profile's enforcement mode, already known to the daemon from the
+     * resolved runtime profile. Used to decide fail-open vs fail-closed when the
+     * allowed-tools fetch fails.
+     */
+    enforcement: ToolEnforcement;
+    logger: ToolPolicyLogger;
+    /**
+     * Deadline for the allowed-tools fetch. A hung API call must not stall session
+     * start-up indefinitely, so on timeout we abort and fall back to the
+     * mode-appropriate degraded policy. Defaults to
+     * {@link DEFAULT_RESOLVE_TIMEOUT_MS}; `0`/negative disables the deadline.
+     */
+    timeoutMs?: number;
+}
+
+export declare function resolveTaskWorktreePath(mainRepo: string, workspaceId: string): string;
+
+export declare interface ResumeCommand {
+    /** Shell command, same semantics as the string form. */
+    run: string;
+    /** Optional generic runtime predicate for whether this step should run. */
+    when?: ResumeCommandWhen;
+    /** Additional attempts on non-zero exit. Default 0. */
+    retries?: number;
+    /** Linear backoff between attempts in ms. Delay before attempt N+1 is
+     *  `(N + 1) * retryBackoffMs` (so 2s, 4s, … with the default). */
+    retryBackoffMs?: number;
+}
+
+/** Structured form of a resume command with optional retry policy. */
+declare interface ResumeCommandWhen {
+    /**
+     * Effective workspace mode(s) that should run this command.
+     * Evaluated by the runtime from the mounted workspace shape rather than
+     * from task type semantics.
+     */
+    workspaceMode?: ('shared_mount' | 'dedicated_worktree' | 'scratch_mount')[];
+}
+
+/**
+ * Resume a VM from a checkpoint, inject credentials, configure egress +
+ * TLS. Returns the managed VM handle.
+ */
+export declare function resumeVm(config: VmConfig): Promise<ManagedVm>;
+
+export declare type RetryTriageConfidence = 'low' | 'medium' | 'high';
+
+export declare type RetryTriageDecision = 'retry' | 'do_not_retry';
+
+declare interface RuntimeInstructorContext {
+    taskId: string;
+    taskType: string;
+    attemptN: number;
+    diaryId: string;
+    agentName: string;
+    guestWorkspace: string;
+    /** Optional correlation id grouping this task with others. */
+    correlationId: string | null;
+}
+
+export declare interface SandboxConfig {
+    /**
+     * Operator-owned snapshot build settings. Runtime profiles must never
+     * populate this field.
+     */
+    snapshot?: {
+        /** Shell commands to run after the base setup. */
+        setupCommands?: string[];
+        /** Additional hosts to allow network access during build. */
+        allowedHosts?: string[];
+        /** Overlay disk size (default '3G'). */
+        overlaySize?: string;
+    };
+    /** Runtime network egress policy. Separate from snapshot build access. */
+    network?: {
+        /** Additional host patterns allowed while the VM is running.
+         * Internal and private address resolution remains blocked. */
+        allowedHosts?: string[];
+        /** Host patterns explicitly allowed to resolve to internal/private IPs. */
+        allowedInternalHosts?: string[];
+    };
+    /** Operator-owned shell commands to run every VM resume, after platform setup
+     *  (TLS, DNS, git safe.directory, tmpfs node_modules) and before
+     *  the agent session starts. Use for per-session bootstrap that
+     *  doesn't belong baked into the snapshot.
+     *
+     *  Not included in the snapshot cache key — changes here apply on
+     *  every resume without triggering a snapshot rebuild. Each command
+     *  runs in a fresh shell with `set -eu` and `set -o pipefail`; a
+     *  non-zero exit (including from any segment of a pipeline) aborts
+     *  resume with the failing command's stderr/stdout tail.
+     *
+     *  Each entry is either a raw string (no retries) or an object
+     *  `{ run, when?, retries?, retryBackoffMs? }`. `when` gates the
+     *  command on generic runtime properties such as effective
+     *  `workspaceMode`; this keeps sandbox policy decoupled from task
+     *  types. `retries` is the number of ADDITIONAL attempts after the
+     *  first failure (default 0 = no retry). Use for steps that hit the
+     *  network and may legitimately race DHCP/registry availability on a
+     *  fresh resume (e.g. `pnpm install`). The wrapped command must be
+     *  idempotent. */
+    resumeCommands?: (string | ResumeCommand)[];
+    /** VFS shadow settings — hide host paths from the guest. */
+    vfs?: {
+        /** Paths (relative to workspace root) to shadow from the host mount. */
+        shadow?: string[];
+        /** What to do with writes to shadowed paths: 'deny' or 'tmpfs' (default 'tmpfs'). */
+        shadowMode?: 'deny' | 'tmpfs';
+    };
+    /** Environment variable overrides for the guest VM (applied on top of defaults). */
+    env?: Record<string, string>;
+    /** Host-side escape hatch policy. Applies only to `moltnet_host_exec`. */
+    hostExec?: {
+        /**
+         * `true` auto-approves every allowed executable. An array auto-approves
+         * only commands matching one of the executable/argument rules.
+         */
+        autoApprove?: boolean | {
+            executable: string;
+            argsPrefix?: string[];
+            argsContains?: string[];
+            argsExcludes?: string[];
+        }[];
+    };
+    /** VM resource allocation. */
+    resources?: {
+        /** Memory size in qemu syntax (default '1G'). */
+        memory?: string;
+        /** CPU count (default 2). */
+        cpus?: number;
+    };
+}
+
+/** The resolved allow-set + enforcement mode for a runtime session. */
+export declare interface SessionToolPolicy {
+    enforcement: ToolEnforcement;
+    allowedTools: ReadonlySet<string>;
+    /**
+     * `true` when the allow-set is a **degraded fallback** — the allowed-tools
+     * fetch failed or timed out and this policy is the fail-closed/fail-open
+     * default, NOT the operator's actual configuration. An intentional
+     * empty-but-resolved policy (e.g. a profile with no bound tools) has
+     * `degraded: false`. Surfaced in every audit/block log so an operator can tell
+     * "blocked because the policy is empty" from "blocked because we couldn't read
+     * the policy". `off` and successful resolutions are never degraded.
+     */
+    degraded: boolean;
+}
+
+/** Extract snapshot-specific config for backwards compat with ensureSnapshot. */
+export declare type SnapshotConfig = NonNullable<SandboxConfig['snapshot']>;
+
+export declare interface SubagentToolHandle {
+    /** ToolDefinition to register via `customTools` on the parent session. */
+    readonly tool: ToolDefinition;
+    /** How many times the parent LLM has called this tool. */
+    getCallCount: () => number;
+}
+
+/**
+ * Parameters shape the parent LLM sees when calling the subagent tool.
+ *
+ *   - `task`         — natural-language instructions for the subagent.
+ *                      The parent authors this per call. Must be
+ *                      non-empty.
+ *   - `output_schema` — name of a registered SubagentOutputContract.
+ *                      Resolved at call time; unknown names error.
+ */
+export declare const SubagentToolParameters: TObject<{
+    task: Type.TString;
+    output_schema: Type.TString;
+}>;
+
+export declare type SubagentToolParameters = Static<typeof SubagentToolParameters>;
+
+declare type TextToolResult<TDetails> = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    details: TDetails | undefined;
+};
+
+/**
+ * Map a host-side absolute path to a guest-side workspace path.
+ * Throws if the path escapes the workspace.
+ */
+export declare function toGuestPath(localCwd: string, localPath: string, guestWorkspace: string): string;
+
+export declare type ToolEnforcement = Static<typeof ToolEnforcementSchema>;
+
+declare const ToolEnforcementSchema = Type.Union(toolEnforcementLiterals, {
+    description:
+    'Runtime tool-policy enforcement mode: off (inert), watch (audit only), enforce (block disallowed tools, fail-closed).',
+});
+
+export declare interface ToolPolicyExtensionDeps {
+    policy: SessionToolPolicy;
+    analyzer: ShellCommandAnalyzer;
+    logger: ToolPolicyLogger;
+}
+
+/**
+ * Structured logger the resolver and gate emit to. Deliberately the pino
+ * `(obj, msg)` shape so the daemon can pass a task-bound pino child directly —
+ * every tool-policy line then carries the daemon's taskId/attemptN context and
+ * lands in the same NDJSON stream as the rest of the run.
+ */
+declare interface ToolPolicyLogger {
+    debug: (obj: Record<string, unknown>, msg: string) => void;
+    info: (obj: Record<string, unknown>, msg: string) => void;
+    warn: (obj: Record<string, unknown>, msg: string) => void;
+}
+
+export declare interface TrackedError {
+    toolName: string;
+    toolCallId: string;
+    input: Record<string, unknown>;
+    error: string;
+    timestamp: number;
+}
+
+export declare interface TurnEventHandler {
+    (event: TurnEventKind, summary: Record<string, unknown>): void;
+}
+
+export declare type TurnEventHandlerFactory = (claimedTask: ClaimedTask) => TurnEventHandler;
+
+export declare type TurnEventKind = Parameters<TaskReporter['record']>[0]['kind'];
+
+export declare interface VmConfig {
+    /** Absolute path to the qcow2 checkpoint. */
+    checkpointPath: string;
+    /** MoltNet agent name (used to resolve credentials). */
+    agentName: string;
+    /**
+     * Host root that owns `.moltnet/<agentName>/`.
+     *
+     * Defaults to the main git worktree for backwards compatibility. Daemon
+     * callers pass the sandbox root so non-git scratch/shared tasks can boot.
+     */
+    agentRootDir?: string;
+    /** Host directory to mount into the VM. */
+    mountPath: string;
+    /** Effective workspace shape selected by the caller. */
+    workspaceMode?: 'shared_mount' | 'dedicated_worktree' | 'scratch_mount';
+    /** Additional hosts to allow in egress policy. */
+    extraAllowedHosts?: string[];
+    /** Full sandbox config (vfs shadows, env overrides). */
+    sandboxConfig?: SandboxConfig;
+    /**
+     * Host environment variable names to copy into the VM process.
+     *
+     * Runtime profiles use this for provider API keys: `requiredEnv` proves the
+     * daemon host has the secret, and this allowlist forwards only those names
+     * into the guest without storing secret values in the profile.
+     */
+    forwardEnv?: string[];
+    /** Abort resume/setup work, closing any live VM owned by resumeVm. */
+    signal?: AbortSignal;
+}
+
+export declare interface VmCredentials {
+    moltnetJson: string;
+    agentEnvRaw: string;
+    /**
+     * Pi OAuth/API-key auth blob. Null when neither `~/.pi/agent/auth.json`
+     * (resolved via `PI_CODING_AGENT_DIR` when set) is present — in that
+     * case the daemon relies on Pi's env-var providers (`ANTHROPIC_API_KEY`,
+     * etc.) carried via `agentEnv` and the host environment instead. CI uses
+     * this path.
+     */
+    piAuthJson: string | null;
+    agentEnv: Record<string, string | undefined>;
+    gitconfig: string | null;
+    sshPrivateKey: string | null;
+    sshPublicKey: string | null;
+    allowedSigners: string | null;
+    /** Raw PEM content of the GitHub App private key, or null if not configured. */
+    githubAppPem: string | null;
+    /** VM-local filename for the GitHub App PEM (basename of host path), or null. */
+    githubAppPemFilename: string | null;
+}
+
+/**
+ * Subset of `@earendil-works/gondolin`'s `VmFs` we actually use. We
+ * narrow the dependency surface so unit tests can hand in a
+ * vitest-mocked object without instantiating a real VM. We use `any`
+ * for the options parameter to make this interface bivariantly
+ * compatible with `VmFs` (whose options types differ between
+ * `mkdir` and `writeFile`); the orchestrator only ever calls these
+ * methods with the documented option shape, so the looseness is
+ * confined to this seam.
+ */
+export declare interface VmFsForContext {
+    mkdir: (dirPath: string, options?: any) => Promise<void>;
+    writeFile: (filePath: string, data: string | Uint8Array, options?: any) => Promise<void>;
+}
+
+export { }