@cleocode/core 2026.6.12 → 2026.6.14

package/dist/llm/pi/pi-tool-bridge.js

@@ -0,0 +1,117 @@
+/**
+ * Pi ↔ dispatch-engine bridge (T1740 · AC6 · epic T11456).
+ *
+ * Closes the agent tool-call loop for the in-process Pi runner. Pi's agent loop
+ * executes a tool the model emits by calling the `execute(toolCallId, params,
+ * signal)` method of the matching `AgentTool` it finds on `AgentContext.tools`.
+ * Before T1740 the Pi adapter advertised the registry's tool SCHEMAS to the
+ * model (`pi-stream-fn.ts` → `SendOptions.tools`) but supplied NO executables —
+ * so a model tool-call had nothing to run and the loop could only stream text.
+ *
+ * {@link buildPiAgentTools} projects the {@link AgentToolRegistry} into the
+ * `AgentTool[]` the loop needs, binding each tool's `execute` body to the T1740
+ * {@link ToolDispatchEngine}. When the model emits a tool call, Pi invokes the
+ * bound `execute`, which runs the call THROUGH the dispatch engine — lookup +
+ * Zod-validate + availability + budget + guarded execution + LLM-safe
+ * formatting — and returns the classified result as an `AgentToolResult` Pi
+ * feeds back to the model as a `tool_result`. That is the closed loop:
+ *
+ *   model tool-call → Pi AgentTool.execute → ToolDispatchEngine.dispatch →
+ *   GuardedToolSurface side effect → formatted result → back to the model.
+ *
+ * ## Boundary cleanliness
+ *
+ * - **Gate-11** — this module defines NO atomic tool primitive; it CONSUMES the
+ *   frozen registry (`toOpenAITools`-shaped schemas) and the dispatch engine.
+ * - **Gate-13** — no LLM resolution / transport / client construction here; the
+ *   only LLM route stays in {@link createPiStreamFn}. Tool execution is pure
+ *   side-effect dispatch through the guard.
+ * - **Gate-10** — the Pi `AgentTool.parameters` is a TypeBox `TSchema`; the
+ *   registry carries Zod. We convert via the shared {@link zodSchemaToOpenAITool}
+ *   generator (Zod v4 native `z.toJSONSchema`) and pass the resulting JSON-Schema
+ *   object through as the (structurally-compatible) `parameters` WITHOUT a
+ *   typebox value-import, matching `pi-stream-fn.ts`'s quarantine.
+ *
+ * @task T1740
+ * @epic T11456
+ * @see ../../tools/dispatch.js — the dispatch engine this binds the loop to
+ * @see ./pi-stream-fn.js — the sibling that advertises the same tools' schemas
+ */
+import { getLogger } from '../../logger.js';
+import { zodSchemaToOpenAITool } from '../../tools/schema-gen.js';
+const logger = getLogger('pi-tool-bridge');
+/**
+ * Project an {@link AgentToolRegistry} into the `AgentTool[]` the Pi loop
+ * executes, binding every tool's `execute` to the shared {@link
+ * ToolDispatchEngine} (AC6).
+ *
+ * One {@link ToolDispatchEngine} instance is shared across all returned tools so
+ * the run-scoped budget (call count / time ceilings) is enforced ACROSS the
+ * whole turn, not per tool. Each `execute`:
+ *   1. wraps Pi's `(toolCallId, params)` into a {@link ToolCall};
+ *   2. dispatches it through the engine (validate → availability → budget →
+ *      guarded execution → format);
+ *   3. returns the formatted content as an `AgentToolResult` Pi feeds back.
+ *
+ * @param engine - The dispatch engine (carries registry + guard + budget).
+ * @returns The `AgentTool[]` to assign to `AgentContext.tools`.
+ */
+export function buildPiAgentTools(engine, registry) {
+    return registry.list().map((descriptor) => {
+        // Reuse the SINGLE shared schema generator so the bridge's advertised schema
+        // is byte-identical to what `pi-stream-fn.ts` puts on the wire (DRY, Gate-10
+        // — Zod → JSON-Schema, no typebox value-import).
+        const { inputSchema } = zodSchemaToOpenAITool({
+            name: descriptor.name,
+            description: descriptor.description,
+            parameters: descriptor.parameters,
+        });
+        return {
+            name: descriptor.name,
+            description: descriptor.description,
+            parameters: inputSchema,
+            label: descriptor.name,
+            async execute(toolCallId, params, signal) {
+                const call = {
+                    id: toolCallId,
+                    name: descriptor.name,
+                    // Pi passes the schema-validated params object; normalize a non-object
+                    // to an empty record so the engine's own re-validation runs cleanly.
+                    arguments: isRecord(params) ? params : {},
+                };
+                const result = await engine.dispatch(call, signal);
+                if (!result.ok) {
+                    logger.debug({ tool: descriptor.name, kind: result.kind, code: result.code }, 'pi tool dispatch failed (contained)');
+                }
+                return toAgentToolResult(result);
+            },
+        };
+    });
+}
+/**
+ * Convert a {@link ToolDispatchResult} into the {@link PiBridgeToolResult} the
+ * loop reads. Success → the `display` body; failure → the redacted, classified
+ * `[CODE] message` body. Either way it is a normal (non-throwing) result so the
+ * loop continues — Pi's contract is that a tool encodes failure in its result,
+ * not by throwing.
+ *
+ * @param result - The dispatch outcome.
+ * @returns The Pi-shaped tool result.
+ */
+function toAgentToolResult(result) {
+    const text = result.ok
+        ? result.display
+        : `[${result.code}] ${result.message}${formatIssues(result)}`;
+    return { content: [{ type: 'text', text }], details: result };
+}
+/** Append flattened arg-validation issues to a failure body, when present. */
+function formatIssues(result) {
+    if (!result.issues || result.issues.length === 0)
+        return '';
+    return `\n${result.issues.map((i) => `- ${i.path ? `${i.path}: ` : ''}${i.message}`).join('\n')}`;
+}
+/** Narrow an unknown to a plain record (Pi may hand a non-object on edge cases). */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=pi-tool-bridge.js.map

package/dist/llm/pi/pi-tool-bridge.js.map

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

package/dist/llm/pi/pi-types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Core-internal Pi adapter types (T11761 · S2 · T11898).
+ *
+ * These types are the in-process contract between {@link createPiStreamFn} and
+ * {@link PiAgentAdapter}. They are deliberately **core-internal** — NOT promoted
+ * to `@cleocode/contracts` (Gate-4 Contracts Fan-Out: a type imported by >2
+ * packages must move to contracts; these are imported only within
+ * `core/src/llm/pi/`, so they stay here per YAGNI). The package barrel re-exports
+ * ONLY `createPiSkillRunner` (everything else, including these types, is internal).
+ *
+ * @epic T10403
+ * @task T11761
+ * @task T11898
+ */
+import type { SystemOfUseLabel } from '@cleocode/contracts';
+/**
+ * Run context handed to the Pi adapter + streamFn for a single agent run.
+ *
+ * Carries the resolution chokepoint key ({@link system}) and the daemon-stamped
+ * identity (NEVER minted by the adapter — read from env via the session-id
+ * resolvers). The adapter runs with ZERO authority: it resolves its LLM through
+ * `system`, never opens a DB writer, and never self-mints a session id.
+ */
+export interface PiAgentRunContext {
+    /**
+     * Semantic system-of-use label → role → resolved LLM, via the E9
+     * {@link import('../system-resolver.js').resolveLLMForSystem} chokepoint
+     * (e.g. `'task-executor'`).
+     */
+    readonly system: SystemOfUseLabel;
+    /** Daemon-stamped session identity (read from `CLEO_SESSION_ID`, NEVER minted). */
+    readonly sessionId: string;
+    /** Daemon-stamped agent id (`CLEO_AGENT_ID`), or `null` when un-stamped. */
+    readonly agentId: string | null;
+    /** Parent session id (`CLEO_PARENT_SESSION_ID`), or `null` at the fork root. */
+    readonly parentSessionId: string | null;
+    /** Project root for config + credential resolution. Defaults to `process.cwd()`. */
+    readonly projectRoot?: string;
+    /** Abort propagation into Pi's agent loop. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Terminal result of a single {@link PiAgentAdapter.run}.
+ *
+ * `output` carries the aggregated assistant text + any structured bindings, in
+ * the shape the `SkillRunner` slot projects onto a `SkillExecuteResult`.
+ */
+export interface PiAgentResult {
+    /** Whether the agent run succeeded or failed. */
+    readonly status: 'success' | 'failure';
+    /** Aggregated terminal output (assistant text + structured bindings). */
+    readonly output: Readonly<Record<string, unknown>>;
+    /** Human-readable failure reason; present iff `status === 'failure'`. */
+    readonly error?: string;
+}
+//# sourceMappingURL=pi-types.d.ts.map

package/dist/llm/pi/pi-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-types.d.ts","sourceRoot":"","sources":["../../../src/llm/pi/pi-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,gFAAgF;IAChF,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,oFAAoF;IACpF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC;IACvC,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB"}

package/dist/llm/pi/pi-types.js

@@ -0,0 +1,16 @@
+/**
+ * Core-internal Pi adapter types (T11761 · S2 · T11898).
+ *
+ * These types are the in-process contract between {@link createPiStreamFn} and
+ * {@link PiAgentAdapter}. They are deliberately **core-internal** — NOT promoted
+ * to `@cleocode/contracts` (Gate-4 Contracts Fan-Out: a type imported by >2
+ * packages must move to contracts; these are imported only within
+ * `core/src/llm/pi/`, so they stay here per YAGNI). The package barrel re-exports
+ * ONLY `createPiSkillRunner` (everything else, including these types, is internal).
+ *
+ * @epic T10403
+ * @task T11761
+ * @task T11898
+ */
+export {};
+//# sourceMappingURL=pi-types.js.map

package/dist/llm/pi/pi-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-types.js","sourceRoot":"","sources":["../../../src/llm/pi/pi-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/llm/pi/resolve-execution-env.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Per-run {@link PiExecutionEnv} selector + CI process-isolation fallback
+ * (T11910 · T11888-C · P5 Gondolin · epic T11599).
+ *
+ * The self-improvement loop wants ONE swap point that picks the strongest
+ * available confinement backend for a run and SILENTLY DEGRADES when the stronger
+ * one is unavailable — never erroring, never coupling the caller to whether a VM
+ * booted. That is this module:
+ *
+ * - When `backend: 'gondolin'` is requested AND the Gondolin sandbox is available
+ *   (the optional `@earendil-works/gondolin` package loads AND `/dev/kvm` exists
+ *   AND a working `qemu-system-x86_64` is on `PATH` — the AND-gate of
+ *   {@link import('./gondolin-loader.js').isGondolinAvailable}), the selector boots
+ *   a micro-VM-backed {@link import('./pi-gondolin-env.js').GondolinExecutionEnv}
+ *   (confinement = the VM boundary itself; guest has ZERO host authority).
+ * - OTHERWISE — `backend: 'in-process'`, OR `'gondolin'` requested on a box where
+ *   the package / `/dev/kvm` / QEMU is absent (the CI + most-developer-machines
+ *   case) — it returns the always-available in-process deny-first
+ *   {@link import('./pi-execution-env.js').GuardedExecutionEnv} (`ToolGuard` +
+ *   workspace boundary). The loop runs IDENTICALLY over either backend (the
+ *   `PiExecutionEnv` contract is byte-for-byte identical), just without VM
+ *   isolation in the fallback.
+ *
+ * So in CI — gondolin uninstalled AND `/dev/kvm`/QEMU usually absent —
+ * `isGondolinAvailable()` is `false`, the selector returns the in-process env, and
+ * the suite stays green with ZERO VM infra. The degradation is structural: a box
+ * that requested the VM but lacks the infra gets the guarded fallback, not an
+ * error.
+ *
+ * Optional-dep discipline (D11142): this module imports ONLY sibling Pi modules
+ * (`./gondolin-loader.js`, `./pi-gondolin-env.js`, `./pi-execution-env.js`). It has
+ * NO `import type` from `@earendil-works/gondolin` — the gondolin package is loaded
+ * lazily (and ONLY when chosen) inside `createGondolinExecutionEnv`. `core` builds
+ * + all non-gondolin tests pass with gondolin ABSENT, and this module is
+ * import-time side-effect-free (no top-level VM boot, no host probe).
+ *
+ * Scope (T11888-C): this is the SELECTOR ONLY. It does NOT wire the
+ * `pi-agent-adapter.ts` env seam (a separate follow-up) — it is the single
+ * function the loop calls to obtain a per-run env.
+ *
+ * @epic T11599
+ * @task T11910
+ * @see ./gondolin-loader.js — the optional-dep availability probe (`isGondolinAvailable`)
+ * @see ./pi-gondolin-env.js — the VM-backed backend booted when available
+ * @see ./pi-execution-env.js — the in-process `GuardedExecutionEnv` fallback
+ */
+import type { ToolGuard } from '../../tools/guard.js';
+import { type PiExecutionEnv } from './pi-execution-env.js';
+import { type CreateGondolinExecutionEnvOptions } from './pi-gondolin-env.js';
+/**
+ * Which confinement backend a run REQUESTS. `'gondolin'` is a PREFERENCE, not a
+ * guarantee — when the VM infra is absent the selector degrades to `'in-process'`
+ * (the guarded fallback). `'in-process'` always resolves to the in-process
+ * {@link import('./pi-execution-env.js').GuardedExecutionEnv} (no VM probe at all).
+ */
+export type ExecutionEnvBackend = 'gondolin' | 'in-process';
+/**
+ * Options for {@link resolveExecutionEnv}. The `guard` + `workspaceRoot` pair is
+ * ALWAYS required because they back the in-process fallback (the guarded env that
+ * runs when the VM is unavailable or not requested). The VM-only fields
+ * (`seededCopyDir`, `allowedHosts`, `vaultSecrets`, `memory`, `env`) are consumed
+ * ONLY when a Gondolin VM is actually booted.
+ */
+export interface ResolveExecutionEnvOptions {
+    /**
+     * The confinement backend this run PREFERS. `'gondolin'` boots a micro-VM when
+     * available and degrades to the guarded env otherwise; `'in-process'` always
+     * resolves to the guarded env.
+     */
+    readonly backend: ExecutionEnvBackend;
+    /**
+     * The deny-first guard surface backing the in-process fallback. REQUIRED even
+     * when `backend: 'gondolin'` — it is what the selector returns when the VM is
+     * unavailable. Must be an `enforce`-mode guard (the fallback factory asserts it).
+     */
+    readonly guard: ToolGuard;
+    /**
+     * The absolute workspace root the in-process fallback confines every fs path
+     * under. Used ONLY by the guarded fallback (the VM confines to its own
+     * `/workspace` mount).
+     */
+    readonly workspaceRoot: string;
+    /**
+     * The disposable seeded-copy host directory mounted RW at `/workspace` inside
+     * the guest. REQUIRED when a VM is actually booted (`backend: 'gondolin'` AND
+     * available); MUST be a `VACUUM INTO` snapshot dir, NEVER a path containing the
+     * live `.cleo/tasks.db` / `.cleo/brain.db`. Ignored by the fallback.
+     */
+    readonly seededCopyDir?: string;
+    /**
+     * Outbound host allowlist forwarded to the VM's egress hooks. Defaults to `[]`
+     * (DENY ALL) inside the VM factory when omitted. Ignored by the fallback.
+     */
+    readonly allowedHosts?: readonly string[];
+    /**
+     * Host-side secret injections for the VM's egress proxy (the guest only ever
+     * sees each entry's `placeholder`). Ignored by the fallback.
+     */
+    readonly vaultSecrets?: CreateGondolinExecutionEnvOptions['vaultSecrets'];
+    /**
+     * Guest memory bound (e.g. `"1G"`) for a booted VM. Defaults inside the VM
+     * factory. Ignored by the fallback.
+     */
+    readonly memory?: string;
+    /**
+     * Guest environment — the ONLY env a booted VM's guest sees (host `process.env`
+     * is NEVER inherited). Ignored by the fallback.
+     */
+    readonly env?: Readonly<Record<string, string>>;
+}
+/**
+ * Injectable seams for {@link resolveExecutionEnv}.
+ *
+ * EXPORTED FOR TESTS ONLY — lets the selector matrix test simulate
+ * "VM requested + available" (a mocked `isAvailable` returning `true` + a mocked
+ * `createGondolin` returning a fake env) and "VM requested + unavailable"
+ * (`isAvailable` returning `false`) WITHOUT touching the module graph or launching
+ * a real QEMU VM. In production both default to the real loader probe + the real
+ * VM factory.
+ *
+ * @internal
+ */
+export interface ResolveExecutionEnvSeams {
+    /**
+     * The availability probe. Defaults to the real
+     * {@link import('./gondolin-loader.js').isGondolinAvailable} (package + `/dev/kvm`
+     * + QEMU AND-gate).
+     */
+    readonly isAvailable?: () => Promise<boolean>;
+    /**
+     * The VM-backed env factory. Defaults to the real
+     * {@link import('./pi-gondolin-env.js').createGondolinExecutionEnv}.
+     */
+    readonly createGondolin?: (opts: CreateGondolinExecutionEnvOptions) => Promise<PiExecutionEnv>;
+}
+/**
+ * Thrown by {@link resolveExecutionEnv} when `backend: 'gondolin'` is requested,
+ * the VM is reported available, but no {@link ResolveExecutionEnvOptions.seededCopyDir}
+ * was supplied — a VM cannot boot without a disposable seeded-copy mount, and
+ * silently degrading to the in-process fallback here would HIDE a caller bug
+ * (the caller asked for the VM and the infra IS present). This is the ONE
+ * non-degrading failure: it signals a misconfiguration, not missing infra.
+ */
+export declare class ExecutionEnvConfigError extends Error {
+    /** Machine-readable code. */
+    readonly code = "E_EXECUTION_ENV_CONFIG";
+    constructor(message: string);
+}
+/**
+ * Resolve the {@link PiExecutionEnv} a single self-improvement run should use,
+ * preferring the Gondolin micro-VM when requested AND available and SILENTLY
+ * DEGRADING to the in-process {@link import('./pi-execution-env.js').GuardedExecutionEnv}
+ * otherwise.
+ *
+ * Selection matrix:
+ *
+ * | `backend`      | VM available? | Result                                  |
+ * |----------------|---------------|-----------------------------------------|
+ * | `'gondolin'`   | yes           | `createGondolinExecutionEnv` (micro-VM) |
+ * | `'gondolin'`   | no            | `createGuardedExecutionEnv` (degrade)   |
+ * | `'in-process'` | (not probed)  | `createGuardedExecutionEnv`             |
+ *
+ * The availability check (`package + /dev/kvm + QEMU`) is performed ONLY when
+ * `backend === 'gondolin'`, so an `'in-process'` request never probes the host or
+ * touches the optional package. Degradation NEVER throws — the one exception is a
+ * misconfiguration (`gondolin` requested + available but no `seededCopyDir`), which
+ * is a caller bug surfaced as {@link ExecutionEnvConfigError} rather than a hidden
+ * fallback.
+ *
+ * @param opts - The backend preference + the always-required guard/workspaceRoot
+ *   fallback inputs + the VM-only mount/egress inputs.
+ * @param seams - Test-only overrides for the availability probe + VM factory
+ *   (defaults are the real loader probe + the real VM factory). Production callers
+ *   pass nothing.
+ * @returns A {@link PiExecutionEnv} — VM-backed when the sandbox booted, in-process
+ *   guarded otherwise. The loop cannot tell the backends apart.
+ * @throws {ExecutionEnvConfigError} When the VM is requested AND available but no
+ *   `seededCopyDir` was supplied.
+ *
+ * @example
+ * ```ts
+ * // Prefer the VM; degrades to the guarded env in CI (no /dev/kvm / QEMU).
+ * const env = await resolveExecutionEnv({
+ *   backend: 'gondolin',
+ *   guard,                       // enforce-mode ToolGuard (the fallback)
+ *   workspaceRoot: projectRoot,  // the fallback's confinement root
+ *   seededCopyDir: snapshotDir,  // the VM's only RW mount (disposable copy)
+ * });
+ * // ... drive Pi's loop over `env` ...
+ * await env.cleanup();
+ * ```
+ */
+export declare function resolveExecutionEnv(opts: ResolveExecutionEnvOptions, seams?: ResolveExecutionEnvSeams): Promise<PiExecutionEnv>;
+//# sourceMappingURL=resolve-execution-env.d.ts.map

package/dist/llm/pi/resolve-execution-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-execution-env.d.ts","sourceRoot":"","sources":["../../../src/llm/pi/resolve-execution-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EAA6B,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvF,OAAO,EACL,KAAK,iCAAiC,EAEvC,MAAM,sBAAsB,CAAC;AAE9B;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,YAAY,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,iCAAiC,CAAC,cAAc,CAAC,CAAC;IAC1E;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACjD;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,iCAAiC,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;CAChG;AAED;;;;;;;GAOG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,4BAA4B;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,0BAA0B,EAChC,KAAK,GAAE,wBAA6B,GACnC,OAAO,CAAC,cAAc,CAAC,CAyBzB"}

package/dist/llm/pi/resolve-execution-env.js

@@ -0,0 +1,132 @@
+/**
+ * Per-run {@link PiExecutionEnv} selector + CI process-isolation fallback
+ * (T11910 · T11888-C · P5 Gondolin · epic T11599).
+ *
+ * The self-improvement loop wants ONE swap point that picks the strongest
+ * available confinement backend for a run and SILENTLY DEGRADES when the stronger
+ * one is unavailable — never erroring, never coupling the caller to whether a VM
+ * booted. That is this module:
+ *
+ * - When `backend: 'gondolin'` is requested AND the Gondolin sandbox is available
+ *   (the optional `@earendil-works/gondolin` package loads AND `/dev/kvm` exists
+ *   AND a working `qemu-system-x86_64` is on `PATH` — the AND-gate of
+ *   {@link import('./gondolin-loader.js').isGondolinAvailable}), the selector boots
+ *   a micro-VM-backed {@link import('./pi-gondolin-env.js').GondolinExecutionEnv}
+ *   (confinement = the VM boundary itself; guest has ZERO host authority).
+ * - OTHERWISE — `backend: 'in-process'`, OR `'gondolin'` requested on a box where
+ *   the package / `/dev/kvm` / QEMU is absent (the CI + most-developer-machines
+ *   case) — it returns the always-available in-process deny-first
+ *   {@link import('./pi-execution-env.js').GuardedExecutionEnv} (`ToolGuard` +
+ *   workspace boundary). The loop runs IDENTICALLY over either backend (the
+ *   `PiExecutionEnv` contract is byte-for-byte identical), just without VM
+ *   isolation in the fallback.
+ *
+ * So in CI — gondolin uninstalled AND `/dev/kvm`/QEMU usually absent —
+ * `isGondolinAvailable()` is `false`, the selector returns the in-process env, and
+ * the suite stays green with ZERO VM infra. The degradation is structural: a box
+ * that requested the VM but lacks the infra gets the guarded fallback, not an
+ * error.
+ *
+ * Optional-dep discipline (D11142): this module imports ONLY sibling Pi modules
+ * (`./gondolin-loader.js`, `./pi-gondolin-env.js`, `./pi-execution-env.js`). It has
+ * NO `import type` from `@earendil-works/gondolin` — the gondolin package is loaded
+ * lazily (and ONLY when chosen) inside `createGondolinExecutionEnv`. `core` builds
+ * + all non-gondolin tests pass with gondolin ABSENT, and this module is
+ * import-time side-effect-free (no top-level VM boot, no host probe).
+ *
+ * Scope (T11888-C): this is the SELECTOR ONLY. It does NOT wire the
+ * `pi-agent-adapter.ts` env seam (a separate follow-up) — it is the single
+ * function the loop calls to obtain a per-run env.
+ *
+ * @epic T11599
+ * @task T11910
+ * @see ./gondolin-loader.js — the optional-dep availability probe (`isGondolinAvailable`)
+ * @see ./pi-gondolin-env.js — the VM-backed backend booted when available
+ * @see ./pi-execution-env.js — the in-process `GuardedExecutionEnv` fallback
+ */
+import { isGondolinAvailable as realIsGondolinAvailable } from './gondolin-loader.js';
+import { createGuardedExecutionEnv } from './pi-execution-env.js';
+import { createGondolinExecutionEnv as realCreateGondolinExecutionEnv, } from './pi-gondolin-env.js';
+/**
+ * Thrown by {@link resolveExecutionEnv} when `backend: 'gondolin'` is requested,
+ * the VM is reported available, but no {@link ResolveExecutionEnvOptions.seededCopyDir}
+ * was supplied — a VM cannot boot without a disposable seeded-copy mount, and
+ * silently degrading to the in-process fallback here would HIDE a caller bug
+ * (the caller asked for the VM and the infra IS present). This is the ONE
+ * non-degrading failure: it signals a misconfiguration, not missing infra.
+ */
+export class ExecutionEnvConfigError extends Error {
+    /** Machine-readable code. */
+    code = 'E_EXECUTION_ENV_CONFIG';
+    constructor(message) {
+        super(message);
+        this.name = 'ExecutionEnvConfigError';
+    }
+}
+/**
+ * Resolve the {@link PiExecutionEnv} a single self-improvement run should use,
+ * preferring the Gondolin micro-VM when requested AND available and SILENTLY
+ * DEGRADING to the in-process {@link import('./pi-execution-env.js').GuardedExecutionEnv}
+ * otherwise.
+ *
+ * Selection matrix:
+ *
+ * | `backend`      | VM available? | Result                                  |
+ * |----------------|---------------|-----------------------------------------|
+ * | `'gondolin'`   | yes           | `createGondolinExecutionEnv` (micro-VM) |
+ * | `'gondolin'`   | no            | `createGuardedExecutionEnv` (degrade)   |
+ * | `'in-process'` | (not probed)  | `createGuardedExecutionEnv`             |
+ *
+ * The availability check (`package + /dev/kvm + QEMU`) is performed ONLY when
+ * `backend === 'gondolin'`, so an `'in-process'` request never probes the host or
+ * touches the optional package. Degradation NEVER throws — the one exception is a
+ * misconfiguration (`gondolin` requested + available but no `seededCopyDir`), which
+ * is a caller bug surfaced as {@link ExecutionEnvConfigError} rather than a hidden
+ * fallback.
+ *
+ * @param opts - The backend preference + the always-required guard/workspaceRoot
+ *   fallback inputs + the VM-only mount/egress inputs.
+ * @param seams - Test-only overrides for the availability probe + VM factory
+ *   (defaults are the real loader probe + the real VM factory). Production callers
+ *   pass nothing.
+ * @returns A {@link PiExecutionEnv} — VM-backed when the sandbox booted, in-process
+ *   guarded otherwise. The loop cannot tell the backends apart.
+ * @throws {ExecutionEnvConfigError} When the VM is requested AND available but no
+ *   `seededCopyDir` was supplied.
+ *
+ * @example
+ * ```ts
+ * // Prefer the VM; degrades to the guarded env in CI (no /dev/kvm / QEMU).
+ * const env = await resolveExecutionEnv({
+ *   backend: 'gondolin',
+ *   guard,                       // enforce-mode ToolGuard (the fallback)
+ *   workspaceRoot: projectRoot,  // the fallback's confinement root
+ *   seededCopyDir: snapshotDir,  // the VM's only RW mount (disposable copy)
+ * });
+ * // ... drive Pi's loop over `env` ...
+ * await env.cleanup();
+ * ```
+ */
+export async function resolveExecutionEnv(opts, seams = {}) {
+    const isAvailable = seams.isAvailable ?? realIsGondolinAvailable;
+    const createGondolin = seams.createGondolin ?? realCreateGondolinExecutionEnv;
+    if (opts.backend === 'gondolin' && (await isAvailable())) {
+        if (opts.seededCopyDir === undefined) {
+            throw new ExecutionEnvConfigError('backend "gondolin" is available but no seededCopyDir was supplied; ' +
+                'a VM requires a disposable seeded-copy mount (VACUUM INTO snapshot) — ' +
+                'live tasks.db/brain.db are NEVER mounted');
+        }
+        return createGondolin({
+            seededCopyDir: opts.seededCopyDir,
+            ...(opts.allowedHosts !== undefined ? { allowedHosts: opts.allowedHosts } : {}),
+            ...(opts.vaultSecrets !== undefined ? { vaultSecrets: opts.vaultSecrets } : {}),
+            ...(opts.memory !== undefined ? { memory: opts.memory } : {}),
+            ...(opts.env !== undefined ? { env: opts.env } : {}),
+        });
+    }
+    // Degrade (or honour `'in-process'`): the always-available in-process env. This
+    // is the CI / most-developer-machines path — no VM probe touched the host when
+    // backend was `'in-process'`; when it was `'gondolin'` the probe returned false.
+    return createGuardedExecutionEnv({ guard: opts.guard, workspaceRoot: opts.workspaceRoot });
+}
+//# sourceMappingURL=resolve-execution-env.js.map

package/dist/llm/pi/resolve-execution-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-execution-env.js","sourceRoot":"","sources":["../../../src/llm/pi/resolve-execution-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAGH,OAAO,EAAE,mBAAmB,IAAI,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACtF,OAAO,EAAE,yBAAyB,EAAuB,MAAM,uBAAuB,CAAC;AACvF,OAAO,EAEL,0BAA0B,IAAI,8BAA8B,GAC7D,MAAM,sBAAsB,CAAC;AA2F9B;;;;;;;GAOG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,6BAA6B;IACpB,IAAI,GAAG,wBAAwB,CAAC;IACzC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,IAAgC,EAChC,QAAkC,EAAE;IAEpC,MAAM,WAAW,GAAG,KAAK,CAAC,WAAW,IAAI,uBAAuB,CAAC;IACjE,MAAM,cAAc,GAAG,KAAK,CAAC,cAAc,IAAI,8BAA8B,CAAC;IAE9E,IAAI,IAAI,CAAC,OAAO,KAAK,UAAU,IAAI,CAAC,MAAM,WAAW,EAAE,CAAC,EAAE,CAAC;QACzD,IAAI,IAAI,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;YACrC,MAAM,IAAI,uBAAuB,CAC/B,qEAAqE;gBACnE,wEAAwE;gBACxE,0CAA0C,CAC7C,CAAC;QACJ,CAAC;QACD,OAAO,cAAc,CAAC;YACpB,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,GAAG,CAAC,IAAI,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/E,GAAG,CAAC,IAAI,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/E,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7D,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACrD,CAAC,CAAC;IACL,CAAC;IAED,gFAAgF;IAChF,+EAA+E;IAC/E,iFAAiF;IACjF,OAAO,yBAAyB,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC;AAC7F,CAAC"}