@cleocode/core 2026.6.12 → 2026.6.13

package/dist/llm/pi/gondolin-loader.d.ts

@@ -0,0 +1,241 @@
+/**
+ * Gondolin micro-VM sandbox — the OPTIONAL, lazily-loaded execution backend
+ * (T11908 · T11888-A · P5 Gondolin · epic T11599).
+ *
+ * The {@link import('./pi-execution-env.js').PiExecutionEnv} seam gains a SECOND
+ * implementation (`GondolinExecutionEnv`, T11888-B) whose confinement is a real
+ * micro-VM boundary instead of the in-process deny-first guard. The VM backend is
+ * powered by `@earendil-works/gondolin`, which is an OPTIONAL dependency
+ * (dependency-discipline · D11142): it is NEVER a hard dependency of
+ * `@cleocode/core`. Exactly like `playwright` (see {@link ../../tools/browser-driver.js})
+ * and `node-pty` (see {@link ../../tools/pty.js}), it is deliberately NOT declared
+ * in `core`'s `dependencies` / `optionalDependencies` and is loaded ONLY via a
+ * dynamic `import()` whose specifier is held in a variable — so neither the
+ * bundler nor TS treats the missing package as a hard, statically-resolved
+ * dependency, the published `@cleocode/core` carries no Gondolin / QEMU weight,
+ * and `core` builds + non-sandbox tests pass with Gondolin NOT installed.
+ *
+ * An environment that wants the sandbox opts in by installing the package itself
+ * (`pnpm add @earendil-works/gondolin`) AND providing the host infra (QEMU +
+ * `/dev/kvm`). Availability is the AND of all three — package present, `/dev/kvm`
+ * present, and a working `qemu-system-x86_64` — so a box with the package but no
+ * KVM still reports UNAVAILABLE and the selector ({@link ./resolve-execution-env.js},
+ * T11888-C) silently degrades to the in-process `GuardedExecutionEnv` rather than
+ * erroring.
+ *
+ * Import-time side-effect-free: NO top-level `@earendil-works/gondolin` import; the
+ * VM is booted lazily on the first `resolveExecutionEnv`. When Gondolin is absent,
+ * {@link loadGondolin} resolves `null` and {@link isGondolinAvailable} resolves
+ * `false` — nothing throws at import.
+ *
+ * The structural shapes of the consumed Gondolin surface are declared LOCALLY in
+ * this file (`VM`, `VMOptions`, `VmFs`, `ExecResult`, `RealFSProvider`,
+ * `createHttpHooks`); there is NO `import type` from the optional package, so the
+ * type-check passes with the package uninstalled.
+ *
+ * @epic T11599
+ * @task T11908
+ * @see ../../tools/browser-driver.js — the analogous optional-dep (Playwright) lazy-load pattern
+ * @see ./pi-execution-env.js — the `PiExecutionEnv` seam this backend implements
+ */
+/**
+ * The npm install hint surfaced to the model / caller when the sandbox backend is
+ * unavailable because `@earendil-works/gondolin` (or its QEMU/KVM host infra) is
+ * not present. Gondolin is an OPTIONAL dep — the selector degrades to the
+ * in-process `GuardedExecutionEnv` regardless, but reports the sandbox
+ * UNAVAILABLE until this is satisfied.
+ */
+export declare const GONDOLIN_INSTALL_HINT: string;
+/**
+ * A buffered result of `vm.exec` (gondolin `exec.d.ts` `ExecResult`).
+ *
+ * `exitCode` is NON-nullable here (a `number`); a SEPARATE optional `signal`
+ * field is set when the process was killed by a signal. The Pi adapter
+ * (T11888-B) maps this to Pi's `exitCode: number | null` by emitting `null`
+ * whenever `signal` is present.
+ */
+export interface ExecResult {
+    /** Captured standard output. */
+    readonly stdout: string;
+    /** Captured standard error. */
+    readonly stderr: string;
+    /** Process exit code (always a number; `signal` distinguishes signal-kills). */
+    readonly exitCode: number;
+    /** The terminating signal number, when the process was killed by a signal. */
+    readonly signal?: number;
+}
+/** Options for a single `vm.exec` invocation. */
+export interface ExecOptions {
+    /** Working directory inside the guest. */
+    readonly cwd?: string;
+    /** Extra guest environment variables. */
+    readonly env?: Readonly<Record<string, string>>;
+    /** Host abort signal — cancels the in-flight guest process. */
+    readonly signal?: AbortSignal;
+    /** Hard timeout in milliseconds. */
+    readonly timeout?: number;
+}
+/** Metadata returned by `vm.fs.stat`. */
+export interface VmStat {
+    /** Whether the entry is a regular file. */
+    isFile(): boolean;
+    /** Whether the entry is a directory. */
+    isDirectory(): boolean;
+}
+/**
+ * The guest filesystem surface (`vm.fs`). Only the members the sandbox backend
+ * consumes are modelled. All paths are guest-absolute under the single
+ * `/workspace` RW mount.
+ */
+export interface VmFs {
+    readFile(path: string, options: {
+        readonly encoding: 'utf-8';
+    }): Promise<string>;
+    readFile(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: string): Promise<void>;
+    stat(path: string): Promise<VmStat>;
+    listDir(path: string): Promise<string[]>;
+    access(path: string): Promise<void>;
+    mkdir(path: string, options: {
+        readonly recursive: boolean;
+    }): Promise<void>;
+    deleteFile(path: string, options: {
+        readonly recursive: boolean;
+        readonly force: boolean;
+    }): Promise<void>;
+}
+/**
+ * A running micro-VM handle (gondolin `vm.d.ts` `VM`). The sandbox backend owns
+ * exactly one of these per run and releases it in `cleanup()` via `close()`.
+ */
+export interface VM {
+    /** The guest filesystem surface. */
+    readonly fs: VmFs;
+    /**
+     * Run a command in the guest. STRING form runs via `/bin/sh -lc`; ARRAY form
+     * runs the argv directly with no `$PATH` / shell expansion. The returned value
+     * `implements PromiseLike<ExecResult>`, so `await vm.exec(...)` resolves the
+     * buffered result.
+     */
+    exec(command: string | readonly string[], options?: ExecOptions): PromiseLike<ExecResult>;
+    /** Tear down the VM and release its host resources (idempotent host-side guard recommended). */
+    close(): Promise<void>;
+}
+/**
+ * A single readable+writable secret the egress proxy injects HOST-side. The guest
+ * only ever sees `placeholder` — never the real `value` bytes.
+ */
+export interface SecretDefinition {
+    /** Hosts the secret may be sent to. */
+    readonly hosts: readonly string[];
+    /** The real secret bytes — injected host-side, NEVER visible to the guest. */
+    readonly value: string;
+    /** The opaque token the guest sees in place of `value`. */
+    readonly placeholder: string;
+}
+/**
+ * Options for {@link CreateHttpHooks}. Per the gondolin docs, `allowedHosts`
+ * OMITTED = allow-all; `allowedHosts: []` (present-and-empty) = deny-all. The
+ * backend MUST pass it present-and-empty by default (the egress-deny footgun).
+ */
+export interface CreateHttpHooksOptions {
+    /** Outbound host allowlist. Present-and-empty `[]` = deny all; omitted = allow all. */
+    readonly allowedHosts: readonly string[];
+    /** Host-side secret injection (guest sees only `placeholder`). */
+    readonly secrets?: Readonly<Record<string, SecretDefinition>>;
+}
+/** Opaque HTTP-hook handle wired into a VM's network namespace via {@link VMOptions}. */
+export interface HttpHooks {
+    readonly __httpHooks: true;
+}
+/** The `createHttpHooks` factory — allowlists egress + injects credential placeholders. */
+export type CreateHttpHooks = (options: CreateHttpHooksOptions) => HttpHooks;
+/**
+ * A read/write filesystem provider rooted at a host directory, mounted into the
+ * guest VFS (gondolin `fs/real.d.ts` `RealFSProvider`). The sandbox backend
+ * mounts ONLY a disposable seeded-copy directory at `/workspace`; live
+ * `tasks.db`/`brain.db` are NEVER in the mount set.
+ */
+export interface RealFSProviderInstance {
+    readonly __realFsProvider: true;
+}
+/** The `RealFSProvider` constructor surface. */
+export interface RealFSProvider {
+    new (hostRootDir: string): RealFSProviderInstance;
+}
+/**
+ * Options for {@link VMConstructor.create}. The guest's environment is ONLY
+ * `env` (host `process.env` is NEVER inherited — that isolation is structural);
+ * `memory` bounds the guest in-process (default `"1G"`, set explicitly).
+ */
+export interface VMOptions {
+    /** Guest memory bound (e.g. `"1G"`). Set explicitly — never rely on the default. */
+    readonly memory?: string;
+    /** Guest environment — the ONLY env the guest sees (no host `process.env` inheritance). */
+    readonly env?: Readonly<Record<string, string>>;
+    /** VFS mount set — guest path → host FS provider. Live DBs never appear here. */
+    readonly vfs?: {
+        readonly mounts: Readonly<Record<string, RealFSProviderInstance>>;
+    };
+    /** Network egress hooks (allowlist + credential injection). */
+    readonly httpHooks?: HttpHooks;
+}
+/** The `VM` constructor / factory surface (`VM.create`). */
+export interface VMConstructor {
+    create(options?: VMOptions): Promise<VM>;
+}
+/**
+ * The minimal shape of the `@earendil-works/gondolin` module we depend on. Only
+ * the three named exports the sandbox backend consumes are modelled.
+ */
+export interface GondolinModule {
+    readonly VM: VMConstructor;
+    readonly RealFSProvider: RealFSProvider;
+    readonly createHttpHooks: CreateHttpHooks;
+}
+/** A pluggable dynamic-importer (test seam). Defaults to the real `import()`. */
+type DynamicImporter = (specifier: string) => Promise<unknown>;
+/**
+ * Attempt to lazily load `@earendil-works/gondolin`. Returns `null` when the
+ * optional dep is not installed, fails to load, OR does not expose the expected
+ * `VM` / `RealFSProvider` / `createHttpHooks` surface — so callers can report the
+ * sandbox unavailable rather than crashing. NEVER throws.
+ *
+ * The import specifier is held in a variable (passed to the {@link importer}
+ * seam) so bundlers / TS do not treat the missing optional dep as a hard,
+ * statically-resolved dependency (same technique as
+ * {@link ../../tools/browser-driver.js}'s Playwright load).
+ *
+ * @returns The shape-checked module, or `null` when unavailable.
+ */
+export declare function loadGondolin(): Promise<GondolinModule | null>;
+export declare function isGondolinAvailable(): Promise<boolean>;
+/**
+ * Reset the cached Gondolin-availability probe.
+ *
+ * EXPORTED FOR TESTS ONLY — lets a unit test toggle the mocked availability of
+ * the optional dep + host probes between cases without a fresh module graph.
+ *
+ * @internal
+ */
+export declare function __resetGondolinAvailabilityCache(): void;
+/**
+ * Override the dynamic-importer and/or host probes, and reset the availability
+ * cache.
+ *
+ * EXPORTED FOR TESTS ONLY — lets a unit test simulate "package absent" (importer
+ * rejects), "package present" (importer resolves a mock module), and "no
+ * `/dev/kvm`" / "no QEMU" deterministically, WITHOUT touching the module graph or
+ * launching a real QEMU VM. Pass `undefined` for a field to leave it at the real
+ * default; call with no arguments to restore the real importer + probes.
+ *
+ * @param hooks - Partial overrides for the importer and host probes.
+ * @internal
+ */
+export declare function __setGondolinTestHooks(hooks?: {
+    importer?: DynamicImporter;
+    hasKvm?: () => boolean;
+    hasQemu?: () => boolean;
+}): void;
+export {};
+//# sourceMappingURL=gondolin-loader.d.ts.map

package/dist/llm/pi/gondolin-loader.d.ts.map

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

package/dist/llm/pi/gondolin-loader.js

@@ -0,0 +1,195 @@
+/**
+ * Gondolin micro-VM sandbox — the OPTIONAL, lazily-loaded execution backend
+ * (T11908 · T11888-A · P5 Gondolin · epic T11599).
+ *
+ * The {@link import('./pi-execution-env.js').PiExecutionEnv} seam gains a SECOND
+ * implementation (`GondolinExecutionEnv`, T11888-B) whose confinement is a real
+ * micro-VM boundary instead of the in-process deny-first guard. The VM backend is
+ * powered by `@earendil-works/gondolin`, which is an OPTIONAL dependency
+ * (dependency-discipline · D11142): it is NEVER a hard dependency of
+ * `@cleocode/core`. Exactly like `playwright` (see {@link ../../tools/browser-driver.js})
+ * and `node-pty` (see {@link ../../tools/pty.js}), it is deliberately NOT declared
+ * in `core`'s `dependencies` / `optionalDependencies` and is loaded ONLY via a
+ * dynamic `import()` whose specifier is held in a variable — so neither the
+ * bundler nor TS treats the missing package as a hard, statically-resolved
+ * dependency, the published `@cleocode/core` carries no Gondolin / QEMU weight,
+ * and `core` builds + non-sandbox tests pass with Gondolin NOT installed.
+ *
+ * An environment that wants the sandbox opts in by installing the package itself
+ * (`pnpm add @earendil-works/gondolin`) AND providing the host infra (QEMU +
+ * `/dev/kvm`). Availability is the AND of all three — package present, `/dev/kvm`
+ * present, and a working `qemu-system-x86_64` — so a box with the package but no
+ * KVM still reports UNAVAILABLE and the selector ({@link ./resolve-execution-env.js},
+ * T11888-C) silently degrades to the in-process `GuardedExecutionEnv` rather than
+ * erroring.
+ *
+ * Import-time side-effect-free: NO top-level `@earendil-works/gondolin` import; the
+ * VM is booted lazily on the first `resolveExecutionEnv`. When Gondolin is absent,
+ * {@link loadGondolin} resolves `null` and {@link isGondolinAvailable} resolves
+ * `false` — nothing throws at import.
+ *
+ * The structural shapes of the consumed Gondolin surface are declared LOCALLY in
+ * this file (`VM`, `VMOptions`, `VmFs`, `ExecResult`, `RealFSProvider`,
+ * `createHttpHooks`); there is NO `import type` from the optional package, so the
+ * type-check passes with the package uninstalled.
+ *
+ * @epic T11599
+ * @task T11908
+ * @see ../../tools/browser-driver.js — the analogous optional-dep (Playwright) lazy-load pattern
+ * @see ./pi-execution-env.js — the `PiExecutionEnv` seam this backend implements
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { getLogger } from '../../logger.js';
+const log = getLogger('pi-gondolin');
+/**
+ * The npm install hint surfaced to the model / caller when the sandbox backend is
+ * unavailable because `@earendil-works/gondolin` (or its QEMU/KVM host infra) is
+ * not present. Gondolin is an OPTIONAL dep — the selector degrades to the
+ * in-process `GuardedExecutionEnv` regardless, but reports the sandbox
+ * UNAVAILABLE until this is satisfied.
+ */
+export const GONDOLIN_INSTALL_HINT = 'Sandbox execution requires the optional "@earendil-works/gondolin" package + QEMU/KVM. ' +
+    'Install with `pnpm add @earendil-works/gondolin` (boots a ~200MB Alpine guest on first run), ' +
+    'and ensure `/dev/kvm` plus a working `qemu-system-x86_64` are available on the host.';
+// ---------------------------------------------------------------------------
+// Injectable seams — overridable ONLY by the unit tests so a mocked import() /
+// host probe can deterministically simulate "package absent" and "no /dev/kvm"
+// WITHOUT touching the module graph or launching a real QEMU VM. In production
+// these resolve to the real dynamic import + host probes.
+// ---------------------------------------------------------------------------
+/** The npm specifier — held in a VARIABLE so it is never statically resolved. */
+const GONDOLIN_SPECIFIER = '@earendil-works/gondolin';
+/**
+ * The real dynamic importer. The specifier is passed as an argument (held in a
+ * variable at the call site) so the bundler / TS never treats the optional
+ * package as a hard dependency.
+ */
+const realImporter = (specifier) => import(specifier);
+/** `true` when `/dev/kvm` exists — KVM acceleration is available on the host. */
+function realHasKvm() {
+    try {
+        return existsSync('/dev/kvm');
+    }
+    catch {
+        return false;
+    }
+}
+/** `true` when `qemu-system-x86_64 --version` runs successfully (cheap probe). */
+function realHasQemu() {
+    try {
+        execFileSync('qemu-system-x86_64', ['--version'], {
+            stdio: ['ignore', 'ignore', 'ignore'],
+            timeout: 5000,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The active importer (swapped only by {@link __setGondolinTestHooks}). */
+let importer = realImporter;
+/** The active host probes (swapped only by {@link __setGondolinTestHooks}). */
+let hostProbes = { hasKvm: realHasKvm, hasQemu: realHasQemu };
+/**
+ * Structurally validate a dynamically-imported candidate against the three
+ * Gondolin exports the backend consumes. Returns the typed module on a match,
+ * else `null` — so a shape-incompatible package version reports unavailable
+ * rather than crashing later at VM-boot time.
+ */
+function shapeCheck(candidate) {
+    if (candidate === null || typeof candidate !== 'object')
+        return null;
+    const mod = candidate;
+    const vmOk = typeof mod.VM === 'object' &&
+        mod.VM !== null &&
+        typeof mod.VM.create === 'function';
+    const realFsOk = typeof mod.RealFSProvider === 'function';
+    const hooksOk = typeof mod.createHttpHooks === 'function';
+    if (vmOk && realFsOk && hooksOk) {
+        return candidate;
+    }
+    return null;
+}
+/**
+ * Attempt to lazily load `@earendil-works/gondolin`. Returns `null` when the
+ * optional dep is not installed, fails to load, OR does not expose the expected
+ * `VM` / `RealFSProvider` / `createHttpHooks` surface — so callers can report the
+ * sandbox unavailable rather than crashing. NEVER throws.
+ *
+ * The import specifier is held in a variable (passed to the {@link importer}
+ * seam) so bundlers / TS do not treat the missing optional dep as a hard,
+ * statically-resolved dependency (same technique as
+ * {@link ../../tools/browser-driver.js}'s Playwright load).
+ *
+ * @returns The shape-checked module, or `null` when unavailable.
+ */
+export async function loadGondolin() {
+    try {
+        const mod = await importer(GONDOLIN_SPECIFIER);
+        const candidate = mod.default ?? mod;
+        return shapeCheck(candidate);
+    }
+    catch (err) {
+        log.debug({ err }, 'gondolin not loadable — sandbox execution unavailable');
+        return null;
+    }
+}
+/**
+ * Whether the Gondolin sandbox backend can run in this process. The AND of three
+ * conditions:
+ *
+ * 1. the `@earendil-works/gondolin` package loads ({@link loadGondolin} is non-`null`),
+ * 2. `/dev/kvm` exists (KVM acceleration is present),
+ * 3. a working `qemu-system-x86_64` is on `PATH`.
+ *
+ * A box with the package but no KVM still reports `false` so the selector
+ * ({@link ./resolve-execution-env.js}) degrades to the in-process
+ * `GuardedExecutionEnv` — it NEVER errors. The result is cached after the first
+ * probe so availability checks stay cheap; {@link __resetGondolinAvailabilityCache}
+ * clears it (tests only).
+ *
+ * @returns `true` only when package + `/dev/kvm` + QEMU are all present.
+ */
+let cachedAvailable;
+export async function isGondolinAvailable() {
+    if (cachedAvailable !== undefined)
+        return cachedAvailable;
+    const pkgPresent = (await loadGondolin()) !== null;
+    cachedAvailable = pkgPresent && hostProbes.hasKvm() && hostProbes.hasQemu();
+    return cachedAvailable;
+}
+/**
+ * Reset the cached Gondolin-availability probe.
+ *
+ * EXPORTED FOR TESTS ONLY — lets a unit test toggle the mocked availability of
+ * the optional dep + host probes between cases without a fresh module graph.
+ *
+ * @internal
+ */
+export function __resetGondolinAvailabilityCache() {
+    cachedAvailable = undefined;
+}
+/**
+ * Override the dynamic-importer and/or host probes, and reset the availability
+ * cache.
+ *
+ * EXPORTED FOR TESTS ONLY — lets a unit test simulate "package absent" (importer
+ * rejects), "package present" (importer resolves a mock module), and "no
+ * `/dev/kvm`" / "no QEMU" deterministically, WITHOUT touching the module graph or
+ * launching a real QEMU VM. Pass `undefined` for a field to leave it at the real
+ * default; call with no arguments to restore the real importer + probes.
+ *
+ * @param hooks - Partial overrides for the importer and host probes.
+ * @internal
+ */
+export function __setGondolinTestHooks(hooks) {
+    importer = hooks?.importer ?? realImporter;
+    hostProbes = {
+        hasKvm: hooks?.hasKvm ?? realHasKvm,
+        hasQemu: hooks?.hasQemu ?? realHasQemu,
+    };
+    cachedAvailable = undefined;
+}
+//# sourceMappingURL=gondolin-loader.js.map

package/dist/llm/pi/gondolin-loader.js.map

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

package/dist/llm/pi/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pi in-process embed — public barrel (T11761 · S2 · T11898).
+ *
+ * The Pi agent loop runs in-process inside the Cleo daemon as the body of the
+ * `SkillRunner` strategy slot, with ZERO authority — resolving its LLM only
+ * through the E9 chokepoint, touching the filesystem/shell only through the
+ * deny-first guarded `ExecutionEnv`, and running under `process.exit`
+ * containment. See {@link ./pi-agent-adapter.js}.
+ *
+ * ## Public surface (intentionally minimal — Gate-4 Contracts Fan-Out)
+ *
+ * Only the SkillRunner factory + the default-OFF flag are exported. The adapter
+ * internals (`PiAgentAdapter`, the streamFn, the session storage, the run-context
+ * types) are core-internal and NOT re-exported here, so they cannot become a
+ * cross-package contract by accident. When a second consumer ever needs one,
+ * promote it to `@cleocode/contracts` then (YAGNI).
+ *
+ * The whole embed is gated by {@link isPiRunnerEnabled} (default-OFF): when the
+ * flag is off, {@link createPiSkillRunner} is never wired into the dispatcher and
+ * `defaultSkillRunner` runs instead.
+ *
+ * @epic T10403
+ * @task T11761
+ * @task T11898
+ */
+export type { PiAgentAdapterDeps } from './pi-agent-adapter.js';
+export { createPiSkillRunner, isPiRunnerEnabled } from './pi-agent-adapter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/llm/pi/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/llm/pi/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,YAAY,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/llm/pi/index.js

@@ -0,0 +1,27 @@
+/**
+ * Pi in-process embed — public barrel (T11761 · S2 · T11898).
+ *
+ * The Pi agent loop runs in-process inside the Cleo daemon as the body of the
+ * `SkillRunner` strategy slot, with ZERO authority — resolving its LLM only
+ * through the E9 chokepoint, touching the filesystem/shell only through the
+ * deny-first guarded `ExecutionEnv`, and running under `process.exit`
+ * containment. See {@link ./pi-agent-adapter.js}.
+ *
+ * ## Public surface (intentionally minimal — Gate-4 Contracts Fan-Out)
+ *
+ * Only the SkillRunner factory + the default-OFF flag are exported. The adapter
+ * internals (`PiAgentAdapter`, the streamFn, the session storage, the run-context
+ * types) are core-internal and NOT re-exported here, so they cannot become a
+ * cross-package contract by accident. When a second consumer ever needs one,
+ * promote it to `@cleocode/contracts` then (YAGNI).
+ *
+ * The whole embed is gated by {@link isPiRunnerEnabled} (default-OFF): when the
+ * flag is off, {@link createPiSkillRunner} is never wired into the dispatcher and
+ * `defaultSkillRunner` runs instead.
+ *
+ * @epic T10403
+ * @task T11761
+ * @task T11898
+ */
+export { createPiSkillRunner, isPiRunnerEnabled } from './pi-agent-adapter.js';
+//# sourceMappingURL=index.js.map

package/dist/llm/pi/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/llm/pi/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/llm/pi/pi-agent-adapter.d.ts

@@ -0,0 +1,135 @@
+/**
+ * `PiAgentAdapter` — the in-process Pi agent-loop embed (T11761 · S2 · T11898).
+ *
+ * THE KEYSTONE of the Pi-harness work: the Pi agent loop runs **in-process**
+ * inside the Cleo daemon as the body of the `SkillRunner` strategy slot, with
+ * ZERO authority. It:
+ *
+ *  - resolves its LLM ONLY through the E9 chokepoint (`resolveLLMForSystem` →
+ *    `ModelRunner`) via the Cleo-owned {@link createPiStreamFn} — `pi-ai`'s
+ *    registry env-fallback is never reached;
+ *  - touches the filesystem/shell ONLY through the deny-first
+ *    {@link GuardedExecutionEnv} (S1) bound to the injected guarded tool surface;
+ *  - reads its session identity from the daemon-stamped env (NEVER mints one);
+ *  - runs under {@link wrapPiCall} containment so a `process.exit()` from any Pi
+ *    code path becomes a thrown typed error, not a daemon-fatal exit;
+ *  - is gated behind a **default-OFF** feature flag ({@link isPiRunnerEnabled}).
+ *
+ * The `SkillRunner` slot (`SkillExecutorAdapterOptions.runner`, line 124 of
+ * `skill-executor-adapter.ts`) CALLS this adapter via {@link createPiSkillRunner};
+ * the adapter is NOT hosted inside `defaultSkillRunner` (which stays untouched).
+ *
+ * Session durability is S3's concern: this subtask uses
+ * {@link InMemorySessionStorage} (in-RAM, no DB writer, no lease) so the
+ * read/stream path is buildable with ZERO write authority.
+ *
+ * @epic T10403
+ * @task T11761
+ * @task T11898
+ */
+import type { GuardedToolSurface } from '@cleocode/contracts/tools/skill-executor';
+import type { SkillRunner } from '../../skills/skill-executor-adapter.js';
+import type { AgentToolRegistry } from '../../tools/agent-registry.js';
+import { type ToolBudgetLimits } from '../../tools/dispatch.js';
+import type { PiAgentResult, PiAgentRunContext } from './pi-types.js';
+/**
+ * Default-OFF feature flag controlling whether the Pi runner is constructed and
+ * used. Reads `CLEO_PI_RUNNER_ENABLED === '1'`. The whole adapter is gated by
+ * this — when disabled, {@link createPiSkillRunner} is never wired into the
+ * dispatcher and `defaultSkillRunner` runs instead.
+ *
+ * @returns `true` when the Pi runner is explicitly enabled.
+ */
+export declare function isPiRunnerEnabled(): boolean;
+/**
+ * Construction dependencies for {@link PiAgentAdapter}.
+ */
+export interface PiAgentAdapterDeps {
+    /**
+     * The {@link SystemOfUseLabel} this adapter resolves its LLM through (E9).
+     * Defaults to `'task-executor'` when the SkillRunner closure builds the ctx.
+     */
+    readonly system?: PiAgentRunContext['system'];
+    /**
+     * Project root for config + credential resolution. Defaults to
+     * `process.cwd()` inside `resolveLLMForSystem`.
+     */
+    readonly projectRoot?: string;
+    /**
+     * The frozen {@link AgentToolRegistry} whose tools the loop may CALL (T1740 ·
+     * AC6). When supplied, {@link run} builds a {@link ToolDispatchEngine} over it
+     * + the injected guarded surface and projects executable `AgentTool`s onto the
+     * loop, so a model tool-call actually runs through the dispatch engine. When
+     * omitted the loop is text-only (no tools offered for execution) — the prior
+     * behaviour, preserved so existing callers are unchanged.
+     */
+    readonly registry?: AgentToolRegistry;
+    /**
+     * Optional per-run tool-call budget limits (T1740 · AC5) applied to the
+     * dispatch engine: max call count, per-call timeout, total time. Omitted →
+     * unbounded.
+     */
+    readonly budget?: ToolBudgetLimits;
+}
+/**
+ * In-process Pi agent-loop adapter with ZERO authority.
+ *
+ * {@link run} drives `pi-agent-core`'s `runAgentLoop` with a Cleo-owned streamFn
+ * (Gate-13), an in-RAM session (no DB writer), and `wrapPiCall` exit/error
+ * containment, then projects the terminal assistant message onto a
+ * {@link PiAgentResult}. It NEVER throws past the containment boundary for a Pi
+ * failure — a Pi error becomes a `{ status: 'failure', error }` result.
+ */
+export declare class PiAgentAdapter {
+    #private;
+    /**
+     * Construct the adapter.
+     *
+     * `deps` supplies the construction-time defaults (resolution system + project
+     * root) that {@link run} merges UNDER the per-call context — a field the call
+     * supplies on `ctx` always wins. The factory {@link createPiSkillRunner} builds
+     * the full `ctx` from these same deps; a direct caller may pass a partial `ctx`
+     * and rely on the deps for the rest.
+     *
+     * @param deps - Resolution system + optional project root defaults.
+     */
+    constructor(deps?: PiAgentAdapterDeps);
+    /**
+     * Run one Pi agent turn over the guarded tool surface.
+     *
+     * The `tools` surface is the injected {@link GuardedToolSurface}; the v0
+     * read/stream path threads it into the loop for future tool wiring (S3+ maps
+     * Pi's `ExecutionEnv` onto it). Resolution + streaming are owned by
+     * {@link createPiStreamFn} (Gate-13). The session id MUST already be
+     * daemon-stamped (read from env in {@link createPiSkillRunner}); the adapter
+     * never mints one.
+     *
+     * @param prompt - The user prompt for this turn.
+     * @param tools - The deny-first guarded tool surface (injected, never built here).
+     * @param ctx - The run context (system label + daemon-stamped identity + signal).
+     * @returns The terminal {@link PiAgentResult}; never throws for a Pi failure.
+     */
+    run(prompt: string, tools: GuardedToolSurface, ctx: PiAgentRunContext): Promise<PiAgentResult>;
+}
+/**
+ * Factory returning a {@link SkillRunner} whose body delegates to
+ * {@link PiAgentAdapter.run}.
+ *
+ * This is the seam adaptation: the real `SkillRunner` shape is
+ * `(skill, input) => Promise<SkillExecuteResult>` — it carries NO free `prompt`
+ * / `ctx`, so the closure DERIVES the prompt from the skill+context and reads
+ * the daemon-stamped identity from env. When the env is un-stamped the runner
+ * fails closed (it NEVER mints a session id).
+ *
+ * Wire it into the dispatcher behind the default-OFF flag:
+ * ```ts
+ * new SkillExecutorAdapter({
+ *   runner: isPiRunnerEnabled() ? createPiSkillRunner(deps) : undefined,
+ * });
+ * ```
+ *
+ * @param deps - Adapter construction deps (resolution system + project root).
+ * @returns A `SkillRunner` that runs the Pi loop in-process.
+ */
+export declare function createPiSkillRunner(deps?: PiAgentAdapterDeps): SkillRunner;
+//# sourceMappingURL=pi-agent-adapter.d.ts.map

package/dist/llm/pi/pi-agent-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-agent-adapter.d.ts","sourceRoot":"","sources":["../../../src/llm/pi/pi-agent-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAGnB,MAAM,0CAA0C,CAAC;AAelD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wCAAwC,CAAC;AAE1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,KAAK,gBAAgB,EAAsC,MAAM,yBAAyB,CAAC;AAIpG,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAItE;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC9C;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,qBAAa,cAAc;;IAIzB;;;;;;;;;;OAUG;gBACS,IAAI,GAAE,kBAAuB;IAIzC;;;;;;;;;;;;;;OAcG;IACG,GAAG,CACP,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,kBAAkB,EACzB,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC,aAAa,CAAC;CAkH1B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,kBAAuB,GAAG,WAAW,CAiC9E"}