@cleocode/core 2026.6.12 → 2026.6.14

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

@@ -0,0 +1,250 @@
+/**
+ * Gondolin micro-VM Pi `ExecutionEnv` — the SECOND backend of the
+ * {@link PiExecutionEnv} seam (T11909 · T11888-B · P5 Gondolin · epic T11599).
+ *
+ * Where the in-process {@link import('./pi-execution-env.js').GuardedExecutionEnv}
+ * (S1 · T11761 · T11897) confines Pi with a deny-first `ToolGuard` + workspace
+ * boundary INSIDE the host process, this backend's confinement is the
+ * **micro-VM boundary itself**. Guest code runs with:
+ *
+ * - **ZERO host authority** — no `cleo.db` handle, no writer-lease IPC socket, no
+ *   host `process.env` secrets, no host filesystem outside the single RW
+ *   `/workspace` mount. The guest is a different kernel; it cannot reach the
+ *   daemon, the lease arbiter, or BRAIN even if Pi-driven code tries.
+ * - **Egress only via the credential-injection proxy** — `createHttpHooks` is
+ *   constructed with `allowedHosts: []` (present-and-empty = DENY ALL per the
+ *   gondolin docs; OMITTING it = allow-all — the egress footgun this guards) and
+ *   host-side secret PLACEHOLDERS, so the guest only ever sees the `placeholder`
+ *   bytes, never the real token. The loop appends specific hosts per run.
+ * - **Live DBs NEVER mounted** — `.cleo/tasks.db` / `.cleo/brain.db` are NOT in
+ *   the VFS mount set. A replay operates on a DISPOSABLE seeded copy
+ *   (`VACUUM INTO` snapshot), so the T5158 data-loss vector (git overwrites the
+ *   live WAL-backed DB) is structurally impossible: there is no live handle
+ *   inside the VM to corrupt.
+ *
+ * This is strictly stronger than S1's env-scrub: S1 protects against an in-process
+ * Pi escape via the guard allowlist; Gondolin protects via kernel + VFS + network
+ * namespace separation. A thin in-guest deny layer (lexical `/workspace`
+ * confinement + a command denylist for real egress verbs) is kept as DEFENSE IN
+ * DEPTH — the boundary is the VM, but a Pi escape that runs a binary still cannot
+ * do damage that survives the run.
+ *
+ * Optional-dep discipline (D11142): `@earendil-works/gondolin` is loaded ONLY via
+ * the {@link import('./gondolin-loader.js').loadGondolin} dynamic import — it is
+ * in NEITHER `dependencies` NOR `optionalDependencies`, and this module declares
+ * NO `import type` from the package (the consumed structural shapes come from the
+ * loader's LOCAL types). `core` builds + all non-gondolin tests pass with gondolin
+ * ABSENT, and this module is import-time side-effect-free (no top-level VM boot).
+ *
+ * Never-throw discipline: every `vm.fs.*` / `vm.exec` call is wrapped exactly as
+ * S1's `#toFsErr` / `execErr` — a thrown gondolin/guest error becomes a
+ * {@link PiResult} `err` with `E_PI_FS_*` / `E_PI_EXEC_*` codes. The
+ * `PiResult<T, E>` contract is byte-for-byte identical to S1, so the Pi loop
+ * cannot tell the two backends apart.
+ *
+ * @epic T11599
+ * @task T11909
+ * @see ./pi-execution-env.js — the S1 `GuardedExecutionEnv` this mirrors over a VM
+ * @see ./gondolin-loader.js — the optional-dep loader supplying the structural types
+ */
+import { type GondolinModule, type SecretDefinition, type VM } from './gondolin-loader.js';
+import type { PiExecOptions, PiExecResult, PiExecutionEnv, PiExecutionError, PiFileError, PiFileInfo, PiResult } from './pi-execution-env.js';
+/** The single RW mount point inside the guest — the ONLY writable location. */
+export declare const GONDOLIN_WORKSPACE_ROOT: "/workspace";
+/**
+ * The real egress verbs the guest is NEVER allowed to run. Sandbox output is a
+ * DRAFT PR opened HOST-side by the loop's egress step (never from inside the
+ * guest). The guest may run `git diff`/`git apply`/`git status` to PRODUCE a
+ * patch, but pushing/publishing is a host-only, budget-gated action. `cleo` is
+ * denied for completeness (no daemon is reachable from the guest anyway).
+ *
+ * Each entry is matched against the command's argv-0 basename, plus the
+ * two-token forms `git push` / `git remote` so a `git`-rooted egress is caught
+ * even though `git`'s OWN basename is allowed (for `git diff` etc.).
+ */
+export declare const DENIED_EXEC_PREFIXES: readonly string[];
+/**
+ * Whether `command` (string or argv) is a denied real-egress verb. Deny-first:
+ * checked BEFORE the command ever reaches `vm.exec`. Comparison is on the
+ * normalized leading tokens (argv-0 basename + a possible second subcommand
+ * token), so `git push origin main`, `/usr/bin/gh pr create`, and
+ * `npm publish --tag x` are all rejected, while `git diff` / `git status` pass.
+ *
+ * @param command - The string command or argv array the env received.
+ * @returns The matched denied prefix, or `null` when the command is allowed.
+ */
+export declare function deniedEgressVerb(command: string | readonly string[]): string | null;
+/**
+ * The injectable factory the {@link createGondolinExecutionEnv} uses to obtain
+ * the gondolin module. Defaults to the real lazy {@link loadGondolin}; unit
+ * tests inject a fake that returns a MOCK module so NO real QEMU VM is launched.
+ */
+export type GondolinLoader = () => Promise<GondolinModule | null>;
+/** Construction options for {@link createGondolinExecutionEnv}. */
+export interface CreateGondolinExecutionEnvOptions {
+    /**
+     * The host directory mounted RW at `/workspace` inside the guest. This MUST be
+     * a DISPOSABLE seeded copy (e.g. a `VACUUM INTO` snapshot dir) — NEVER a path
+     * containing the live `.cleo/tasks.db` / `.cleo/brain.db`. The factory mounts
+     * ONLY this directory; live DBs are structurally absent from the guest VFS.
+     */
+    readonly seededCopyDir: string;
+    /**
+     * Outbound host allowlist. Defaults to `[]` (DENY ALL) when omitted — the
+     * egress footgun guard. The loop appends ONLY the specific hosts it needs
+     * (e.g. the model endpoint via the Vault proxy) per run.
+     */
+    readonly allowedHosts?: readonly string[];
+    /**
+     * Host-side secret injections. The guest only ever sees each entry's
+     * `placeholder`; the real `value` bytes never enter the VM.
+     */
+    readonly vaultSecrets?: Readonly<Record<string, SecretDefinition>>;
+    /** Guest memory bound (e.g. `"1G"`). Defaults to {@link DEFAULT_GUEST_MEMORY}. */
+    readonly memory?: string;
+    /**
+     * Guest environment — the ONLY env the guest sees (host `process.env` is NEVER
+     * inherited; that isolation is structural). Defaults to an empty map.
+     */
+    readonly env?: Readonly<Record<string, string>>;
+    /**
+     * Optional loader override (tests inject a fake → a MOCK VM, no QEMU). Defaults
+     * to the real {@link loadGondolin}.
+     */
+    readonly load?: GondolinLoader;
+}
+/**
+ * A {@link PiExecutionEnv} whose confinement is a gondolin micro-VM. Owns exactly
+ * ONE {@link VM} and releases it in {@link cleanup} via `vm.close()`.
+ *
+ * Every fs op maps to `vm.fs.*`; `exec` maps to `vm.exec`. Each call is wrapped
+ * try/catch → {@link PiResult} `err`, so no method ever throws. A thin in-guest
+ * deny layer (lexical `/workspace` confinement + the {@link DENIED_EXEC_PREFIXES}
+ * command denylist) is the defense-in-depth net BEHIND the VM boundary.
+ *
+ * Unlike the stateless {@link import('./pi-execution-env.js').GuardedExecutionEnv}
+ * (whose `cleanup()` is a no-op), this env OWNS the VM and MUST release it.
+ * `cleanup()` is idempotent (guarded by a `#closed` flag).
+ */
+export declare class GondolinExecutionEnv implements PiExecutionEnv {
+    #private;
+    /**
+     * @param vm - The booted gondolin VM this env owns. Construct via
+     *   {@link createGondolinExecutionEnv}, not directly — the factory wires the
+     *   deny-by-default egress hooks + seeded-copy-only mount set.
+     */
+    constructor(vm: VM);
+    /** The guest workspace root — the in-VM Pi run's working directory. */
+    cwd(): string;
+    /** Resolve `path` to a guest-absolute path anchored at `/workspace`. */
+    absolutePath(path: string): string;
+    /** Join path segments (pure POSIX) anchored at the guest workspace root. */
+    joinPath(...segments: string[]): string;
+    /** Read a file's text from the guest workspace. */
+    readTextFile(path: string): Promise<PiResult<string, PiFileError>>;
+    /** Read a file's text as an array of lines. */
+    readTextLines(path: string): Promise<PiResult<string[], PiFileError>>;
+    /**
+     * Binary read — FILLS S1's v0 denial. The guest VFS supports binary reads
+     * directly via `vm.fs.readFile(p)` (returns a `Uint8Array`).
+     */
+    readBinaryFile(path: string): Promise<PiResult<Uint8Array, PiFileError>>;
+    /** Write a file to the guest workspace. */
+    writeFile(path: string, content: string): Promise<PiResult<void, PiFileError>>;
+    /**
+     * Append to a file. The guest fs surface offers only whole-file writes, so this
+     * reads-then-writes the concatenation (still confined). A missing file is
+     * treated as empty (append-creates).
+     */
+    appendFile(path: string, content: string): Promise<PiResult<void, PiFileError>>;
+    /** Report whether a guest path is a file or directory. */
+    fileInfo(path: string): Promise<PiResult<PiFileInfo, PiFileError>>;
+    /** Whether a guest path exists. */
+    exists(path: string): Promise<PiResult<boolean, PiFileError>>;
+    /**
+     * Canonicalize a guest path via `realpath` inside the guest. Runs the binary in
+     * ARRAY form (no `$PATH` / shell expansion) so the path argument cannot be
+     * reinterpreted as shell.
+     */
+    canonicalPath(path: string): Promise<PiResult<string, PiFileError>>;
+    /** List a guest directory — FILLS S1's v0 denial. */
+    listDir(path: string): Promise<PiResult<string[], PiFileError>>;
+    /** Create a guest directory (recursive) — FILLS S1's v0 denial. */
+    createDir(path: string): Promise<PiResult<void, PiFileError>>;
+    /** Remove a guest path (recursive, force) — FILLS S1's v0 denial. */
+    remove(path: string): Promise<PiResult<void, PiFileError>>;
+    /**
+     * Create a temp directory under `/workspace/.tmp` — FILLS S1's v0 denial. Runs
+     * `mktemp -d` in ARRAY form (no `$PATH` / shell expansion).
+     */
+    createTempDir(prefix?: string): Promise<PiResult<string, PiFileError>>;
+    /**
+     * Create a temp file under `/workspace/.tmp` — FILLS S1's v0 denial. Runs
+     * `mktemp` in ARRAY form (no `$PATH` / shell expansion).
+     */
+    createTempFile(prefix?: string): Promise<PiResult<string, PiFileError>>;
+    /**
+     * Execute a command in the guest via `vm.exec`. Deny-first: a real-egress verb
+     * ({@link DENIED_EXEC_PREFIXES} — `gh` / `git push` / `npm publish` / `cleo` /
+     * `git remote`) is rejected BEFORE reaching the VM, even though the VM itself
+     * has no egress (the network namespace is deny-by-default). `cwd` is confined
+     * to the workspace; the host `AbortSignal` is forwarded only when supplied.
+     *
+     * ## exitCode mapping
+     *
+     * gondolin's `ExecResult.exitCode` is `number` (NON-nullable) with a SEPARATE
+     * optional `signal` field; Pi's `PiExecResult.exitCode` is `number | null`
+     * ("null when killed by signal"). So a signal-kill is mapped to `null`, NOT
+     * the raw `exitCode`.
+     */
+    exec(command: string, options?: PiExecOptions): Promise<PiResult<PiExecResult, PiExecutionError>>;
+    /**
+     * Tear down the owned VM (`vm.close()`). Idempotent: a second call is a no-op.
+     * Best-effort and never throws (a close failure is logged, not propagated) so
+     * the Pi contract — `cleanup()` must not throw — holds.
+     */
+    cleanup(): Promise<void>;
+}
+/**
+ * Thrown by {@link createGondolinExecutionEnv} when the optional
+ * `@earendil-works/gondolin` package (or its QEMU/KVM host infra) is not
+ * available, so a VM cannot be booted. Callers that want graceful degradation
+ * should check `isGondolinAvailable()` first (the selector
+ * {@link import('./resolve-execution-env.js')} does this) and fall back to the
+ * in-process {@link import('./pi-execution-env.js').GuardedExecutionEnv}.
+ */
+export declare class GondolinUnavailableError extends Error {
+    /** Machine-readable code. */
+    readonly code = "E_GONDOLIN_UNAVAILABLE";
+    constructor(message: string);
+}
+/**
+ * Boot a gondolin micro-VM and wrap it in a {@link GondolinExecutionEnv}.
+ *
+ * The VM is configured for ZERO host authority:
+ * - **mount set** = ONLY `{ '/workspace': new RealFSProvider(seededCopyDir) }`.
+ *   The disposable seeded copy is the single RW mount; live `tasks.db`/`brain.db`
+ *   are structurally absent from the guest VFS (T5158 impossible in-VM).
+ * - **egress** = `createHttpHooks({ allowedHosts, secrets })` with `allowedHosts`
+ *   defaulting to `[]` (DENY ALL — the footgun guard) and host-side secret
+ *   PLACEHOLDERS (the guest never sees real token bytes).
+ * - **env** = ONLY `opts.env` (host `process.env` is NEVER inherited).
+ * - **memory** = `opts.memory` (default `"1G"`), set EXPLICITLY.
+ *
+ * Import-time side-effect-free: the gondolin module is loaded lazily HERE (not at
+ * module top-level) via the injectable {@link GondolinLoader} (tests pass a fake
+ * → a MOCK VM, so NO real QEMU boots).
+ *
+ * @param opts - The seeded-copy mount dir + egress allowlist/secrets + guest env.
+ * @returns A {@link PiExecutionEnv} backed by the booted VM.
+ * @throws {GondolinUnavailableError} When the optional package cannot be loaded.
+ *
+ * @example
+ * ```ts
+ * const env = await createGondolinExecutionEnv({ seededCopyDir: snapshotDir });
+ * // ... drive Pi's loop over `env` ...
+ * await env.cleanup(); // releases the VM
+ * ```
+ */
+export declare function createGondolinExecutionEnv(opts: CreateGondolinExecutionEnvOptions): Promise<PiExecutionEnv>;
+//# sourceMappingURL=pi-gondolin-env.d.ts.map

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

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