@cleocode/core 2026.6.12 → 2026.6.13

package/dist/tools/pty.js

@@ -0,0 +1,166 @@
+/**
+ * Pseudo-terminal (PTY) shell runner (T1741 · epic T11456 · SG-TOOLS).
+ *
+ * The `terminal` toolset's execution backend. Runs a command under a PTY when
+ * the OPTIONAL `node-pty` native dependency is loadable, otherwise transparently
+ * degrades to a plain `child_process.spawn` (the {@link defaultShellExecutor}
+ * path) so the tool ALWAYS works without a heavy native dep. `node-pty` is
+ * loaded lazily via dynamic `import()` inside the runner — NEVER at module
+ * import — so this file is import-time side-effect-free (and adds no startup
+ * cost / hard dependency).
+ *
+ * The child runs under the SCRUBBED, explicitly-constructed environment from
+ * {@link scrubSubprocessEnv} (same security posture as the non-PTY path): the
+ * daemon's secrets are never inherited and a Pi-controlled loader hook / PATH
+ * can never reach the spawned process. This runner is invoked ONLY from the
+ * guard chokepoint ({@link ./guard.js}), so the command denylist applies before
+ * any process is spawned — there is no raw bypass.
+ *
+ * @epic T11456
+ * @task T1741
+ * @see ./guard.js — the deny-first chokepoint that wraps this runner
+ */
+import { spawn } from 'node:child_process';
+import { getLogger } from '../logger.js';
+import { scrubSubprocessEnv } from './env-scrub.js';
+const log = getLogger('tool-pty');
+/** Default PTY geometry. */
+const DEFAULT_COLS = 80;
+const DEFAULT_ROWS = 24;
+/**
+ * Attempt to lazily load `node-pty`. Returns `null` when the optional dep is not
+ * installed or fails to load (any reason), so the caller can degrade to spawn.
+ *
+ * The import specifier is held in a variable so bundlers/TS do not treat the
+ * missing optional dep as a hard, statically-resolved dependency.
+ *
+ * @returns The loaded module shape, or `null` when unavailable.
+ */
+async function loadNodePty() {
+    const specifier = 'node-pty';
+    try {
+        const mod = await import(specifier);
+        const candidate = mod.default ?? mod;
+        if (candidate !== null &&
+            typeof candidate === 'object' &&
+            typeof candidate.spawn === 'function') {
+            return candidate;
+        }
+        return null;
+    }
+    catch (err) {
+        log.debug({ err }, 'node-pty not loadable — falling back to non-PTY spawn');
+        return null;
+    }
+}
+/**
+ * Run a command under a non-PTY `spawn`, capturing stdout/stderr/exit-code.
+ * This is the always-available fallback when `node-pty` is absent or `spawn`
+ * mode was explicitly requested.
+ *
+ * @param input - {@link RunShellInput}.
+ * @param ptyFellBack - Whether this spawn is a fallback from a requested PTY.
+ * @returns The {@link RunShellResult} (`mode: 'spawn'`).
+ */
+function runSpawn(input, ptyFellBack) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(input.command, [...(input.args ?? [])], {
+            cwd: input.cwd,
+            env: scrubSubprocessEnv({ extra: input.env }),
+            timeout: input.timeoutMs,
+            shell: false,
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', (d) => {
+            stdout += d.toString('utf8');
+        });
+        child.stderr?.on('data', (d) => {
+            stderr += d.toString('utf8');
+        });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            resolve({ stdout, stderr, code, mode: 'spawn', ptyFellBack });
+        });
+    });
+}
+/**
+ * Run a command under a PTY via the lazily-loaded `node-pty`. The PTY interleaves
+ * stdout + stderr on a single stream (as a real terminal does), so the result's
+ * `stderr` is empty and all output lands in `stdout`.
+ *
+ * @param pty - The loaded `node-pty` module.
+ * @param input - {@link RunShellInput}.
+ * @returns The {@link RunShellResult} (`mode: 'pty'`).
+ */
+function runWithPty(pty, input) {
+    return new Promise((resolve, reject) => {
+        let proc;
+        try {
+            proc = pty.spawn(input.command, [...(input.args ?? [])], {
+                name: 'xterm-256color',
+                cols: input.cols ?? DEFAULT_COLS,
+                rows: input.rows ?? DEFAULT_ROWS,
+                cwd: input.cwd,
+                env: scrubSubprocessEnv({ extra: input.env }),
+            });
+        }
+        catch (err) {
+            reject(err instanceof Error ? err : new Error(String(err)));
+            return;
+        }
+        let stdout = '';
+        let timer;
+        if (typeof input.timeoutMs === 'number' && input.timeoutMs > 0) {
+            timer = setTimeout(() => {
+                proc.kill();
+            }, input.timeoutMs);
+        }
+        proc.onData((data) => {
+            stdout += data;
+        });
+        proc.onExit(({ exitCode, signal }) => {
+            if (timer)
+                clearTimeout(timer);
+            resolve({
+                stdout,
+                stderr: '',
+                code: typeof signal === 'number' && signal > 0 ? null : exitCode,
+                mode: 'pty',
+                ptyFellBack: false,
+            });
+        });
+    });
+}
+/**
+ * Run a command under a PTY when possible, else a non-PTY spawn.
+ *
+ * - `spawn` mode → always {@link runSpawn}.
+ * - `pty` / `auto` mode → attempt {@link loadNodePty}; on success {@link runWithPty},
+ *   otherwise degrade to {@link runSpawn} with `ptyFellBack: true`.
+ *
+ * The actual process is always launched under the scrubbed subprocess env. This
+ * function performs NO policy decision of its own — it is the executor the guard
+ * chokepoint ({@link ./guard.js}) invokes AFTER its denylist check passes.
+ *
+ * @param input - {@link RunShellInput}.
+ * @returns The {@link RunShellResult}.
+ *
+ * @example
+ * ```ts
+ * const res = await runPty({ command: 'echo', args: ['hi'], mode: 'auto' });
+ * // res.mode === 'pty' when node-pty is installed, else 'spawn' (ptyFellBack: true)
+ * ```
+ */
+export async function runPty(input) {
+    const mode = input.mode ?? 'auto';
+    if (mode === 'spawn') {
+        return runSpawn(input, false);
+    }
+    const pty = await loadNodePty();
+    if (pty === null) {
+        return runSpawn(input, true);
+    }
+    return runWithPty(pty, input);
+}
+//# sourceMappingURL=pty.js.map

package/dist/tools/pty.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pty.js","sourceRoot":"","sources":["../../src/tools/pty.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE3C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD,MAAM,GAAG,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;AAElC,4BAA4B;AAC5B,MAAM,YAAY,GAAG,EAAE,CAAC;AACxB,MAAM,YAAY,GAAG,EAAE,CAAC;AA4BxB;;;;;;;;GAQG;AACH,KAAK,UAAU,WAAW;IACxB,MAAM,SAAS,GAAG,UAAU,CAAC;IAC7B,IAAI,CAAC;QACH,MAAM,GAAG,GAAY,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC;QAC7C,MAAM,SAAS,GAAI,GAA6B,CAAC,OAAO,IAAI,GAAG,CAAC;QAChE,IACE,SAAS,KAAK,IAAI;YAClB,OAAO,SAAS,KAAK,QAAQ;YAC7B,OAAQ,SAAiC,CAAC,KAAK,KAAK,UAAU,EAC9D,CAAC;YACD,OAAO,SAA0B,CAAC;QACpC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,EAAE,uDAAuD,CAAC,CAAC;QAC5E,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,QAAQ,CAAC,KAAoB,EAAE,WAAoB;IAC1D,OAAO,IAAI,OAAO,CAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,EAAE;YAC1D,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,GAAG,EAAE,kBAAkB,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC;YAC7C,OAAO,EAAE,KAAK,CAAC,SAAS;YACxB,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;QACH,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE;YACrC,MAAM,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC/B,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE;YACrC,MAAM,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC/B,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC1B,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YACzB,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;QAChE,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,UAAU,CAAC,GAAkB,EAAE,KAAoB;IAC1D,OAAO,IAAI,OAAO,CAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrD,IAAI,IAAoB,CAAC;QACzB,IAAI,CAAC;YACH,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,EAAE;gBACvD,IAAI,EAAE,gBAAgB;gBACtB,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,YAAY;gBAChC,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,YAAY;gBAChC,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,GAAG,EAAE,kBAAkB,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC;aAC9C,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC5D,OAAO;QACT,CAAC;QACD,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,KAAiC,CAAC;QACtC,IAAI,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,IAAI,KAAK,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;YAC/D,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBACtB,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;QACtB,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;YACnB,MAAM,IAAI,IAAI,CAAC;QACjB,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE;YACnC,IAAI,KAAK;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YAC/B,OAAO,CAAC;gBACN,MAAM;gBACN,MAAM,EAAE,EAAE;gBACV,IAAI,EAAE,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ;gBAChE,IAAI,EAAE,KAAK;gBACX,WAAW,EAAE,KAAK;aACnB,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,KAAoB;IAC/C,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,MAAM,CAAC;IAClC,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACrB,OAAO,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAChC,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,WAAW,EAAE,CAAC;IAChC,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,OAAO,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;AAChC,CAAC"}

package/dist/tools/schema-gen.d.ts

@@ -0,0 +1,57 @@
+/**
+ * OpenAI-format tool-schema generation (T1739 · AC3 · epic T11456).
+ *
+ * The SINGLE generator that turns a Cleo Zod parameter schema into the
+ * OpenAI / JSON-Schema {@link TransportTool} shape the ModelRunner + transport
+ * wire layer (and the Pi adapter) consume. Both the agent-facing
+ * {@link ./agent-registry.js | AgentToolRegistry} (AC3) and the Pi streamFn
+ * bridge (`core/src/llm/pi/pi-stream-fn.ts`) call THIS function, so there is one
+ * conversion doctrine and no drift (DRY).
+ *
+ * Uses Zod v4's native `z.toJSONSchema` — NO `zod-to-json-schema` dependency and
+ * NO typebox value-import, so the cleo↔Pi tool surface carries zero typebox
+ * (Gate 10). The resulting `inputSchema` is a plain JSON-Schema object the
+ * transport passes through verbatim after any provider-specific adaptation.
+ *
+ * @task T1739
+ * @epic T11456
+ */
+import type { TransportTool } from '@cleocode/contracts/llm/normalized-response.js';
+import { z } from 'zod';
+/**
+ * A name + description + Zod-schema tool definition, in the shape the schema
+ * generator consumes. Both the agent registry's {@link
+ * ./agent-registry.js | AgentToolDescriptor} and the Pi streamFn's `PiZodTool`
+ * structurally satisfy this, so one generator serves both.
+ */
+export interface ZodSchemaTool {
+    /** Tool name as the provider / model will see it. */
+    readonly name: string;
+    /** Human-readable description for the model. */
+    readonly description: string;
+    /** Zod schema for the tool's input parameters. */
+    readonly parameters: z.ZodType;
+}
+/**
+ * Convert a Cleo Zod-schema tool into the OpenAI-format JSON-Schema
+ * {@link TransportTool}.
+ *
+ * The conversion is purely a function of its input (no I/O, no global state), so
+ * it is safe to call at any time, including during a lazy
+ * {@link ./agent-registry.js | AgentToolRegistry} discovery pass.
+ *
+ * @param tool - The Cleo Zod tool ({@link ZodSchemaTool}).
+ * @returns The transport-shaped JSON-Schema tool (OpenAI function format).
+ *
+ * @example
+ * ```ts
+ * const t = zodSchemaToOpenAITool({
+ *   name: 'read_file',
+ *   description: 'Read a file as text',
+ *   parameters: z.object({ path: z.string() }),
+ * });
+ * // t.inputSchema === { type: 'object', properties: { path: { type: 'string' } }, ... }
+ * ```
+ */
+export declare function zodSchemaToOpenAITool(tool: ZodSchemaTool): TransportTool;
+//# sourceMappingURL=schema-gen.d.ts.map

package/dist/tools/schema-gen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-gen.d.ts","sourceRoot":"","sources":["../../src/tools/schema-gen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gDAAgD,CAAC;AACpF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,GAAG,aAAa,CAUxE"}

package/dist/tools/schema-gen.js

@@ -0,0 +1,52 @@
+/**
+ * OpenAI-format tool-schema generation (T1739 · AC3 · epic T11456).
+ *
+ * The SINGLE generator that turns a Cleo Zod parameter schema into the
+ * OpenAI / JSON-Schema {@link TransportTool} shape the ModelRunner + transport
+ * wire layer (and the Pi adapter) consume. Both the agent-facing
+ * {@link ./agent-registry.js | AgentToolRegistry} (AC3) and the Pi streamFn
+ * bridge (`core/src/llm/pi/pi-stream-fn.ts`) call THIS function, so there is one
+ * conversion doctrine and no drift (DRY).
+ *
+ * Uses Zod v4's native `z.toJSONSchema` — NO `zod-to-json-schema` dependency and
+ * NO typebox value-import, so the cleo↔Pi tool surface carries zero typebox
+ * (Gate 10). The resulting `inputSchema` is a plain JSON-Schema object the
+ * transport passes through verbatim after any provider-specific adaptation.
+ *
+ * @task T1739
+ * @epic T11456
+ */
+import { z } from 'zod';
+/**
+ * Convert a Cleo Zod-schema tool into the OpenAI-format JSON-Schema
+ * {@link TransportTool}.
+ *
+ * The conversion is purely a function of its input (no I/O, no global state), so
+ * it is safe to call at any time, including during a lazy
+ * {@link ./agent-registry.js | AgentToolRegistry} discovery pass.
+ *
+ * @param tool - The Cleo Zod tool ({@link ZodSchemaTool}).
+ * @returns The transport-shaped JSON-Schema tool (OpenAI function format).
+ *
+ * @example
+ * ```ts
+ * const t = zodSchemaToOpenAITool({
+ *   name: 'read_file',
+ *   description: 'Read a file as text',
+ *   parameters: z.object({ path: z.string() }),
+ * });
+ * // t.inputSchema === { type: 'object', properties: { path: { type: 'string' } }, ... }
+ * ```
+ */
+export function zodSchemaToOpenAITool(tool) {
+    // Zod v4's native `z.toJSONSchema` renders a plain JSON-Schema object — NO
+    // `zod-to-json-schema` dep and NO typebox value-import at this boundary, so
+    // every tool surface (registry + Pi bridge) carries zero typebox (Gate 10).
+    const inputSchema = z.toJSONSchema(tool.parameters);
+    return {
+        name: tool.name,
+        description: tool.description,
+        inputSchema,
+    };
+}
+//# sourceMappingURL=schema-gen.js.map

package/dist/tools/schema-gen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-gen.js","sourceRoot":"","sources":["../../src/tools/schema-gen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiBxB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAmB;IACvD,2EAA2E;IAC3E,4EAA4E;IAC5E,4EAA4E;IAC5E,MAAM,WAAW,GAAG,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAA4B,CAAC;IAC/E,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/dist/tools/shell.d.ts

@@ -30,6 +30,18 @@ export type ShellExecutor = (input: ExecuteShellInput) => Promise<ExecuteShellRe
  * stderr and resolving `{ stdout, stderr, code }`. A `timeoutMs` kills the
  * process (code resolves to `null` on signal/timeout). Never rejects on a
  * non-zero exit — the exit code is the result, not an error.
+ *
+ * ## Environment is SCRUBBED, never inherited (T11897 · security)
+ *
+ * The child runs under a MINIMAL, explicitly-constructed environment built by
+ * {@link scrubSubprocessEnv} — it does NOT inherit the parent `process.env`.
+ * This is load-bearing: the parent (the Cleo daemon) holds resolved provider
+ * credentials (`ANTHROPIC_API_KEY`, vault material, OAuth headers); blindly
+ * forwarding the full env into a child spawned on behalf of an in-process Pi
+ * loop would let a single `env`/`printenv` exfiltrate them, and would forward a
+ * Pi-poisoned `LD_PRELOAD`/`PATH`/`NODE_OPTIONS` into the loader. The
+ * caller-supplied `input.env` is merged on top but itself scrubbed (forbidden
+ * keys dropped, `PATH` pinned). Benign vars (locale/term/home) pass through.
  */
 export declare const defaultShellExecutor: ShellExecutor;
 /**

package/dist/tools/shell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../src/tools/shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACZ,MAAM,kCAAkC,CAAC;AAE1C;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAEtF;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAoB/B,CAAC;AAEL;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,iBAAiB,EACxB,QAAQ,GAAE,aAAoC,GAC7C,OAAO,CAAC,kBAAkB,CAAC,CAE7B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CACpB,KAAK,EAAE,WAAW,EAClB,QAAQ,GAAE,aAAoC,GAC7C,OAAO,CAAC,kBAAkB,CAAC,CAK7B"}
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../src/tools/shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACZ,MAAM,kCAAkC,CAAC;AAG1C;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAEtF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAoB/B,CAAC;AAEL;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,iBAAiB,EACxB,QAAQ,GAAE,aAAoC,GAC7C,OAAO,CAAC,kBAAkB,CAAC,CAE7B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CACpB,KAAK,EAAE,WAAW,EAClB,QAAQ,GAAE,aAAoC,GAC7C,OAAO,CAAC,kBAAkB,CAAC,CAK7B"}

package/dist/tools/shell.js

@@ -19,16 +19,29 @@
  * @saga T11387
  */
 import { spawn } from 'node:child_process';
+import { scrubSubprocessEnv } from './env-scrub.js';
 /**
  * Default executor: `spawn(command, args)` with no shell, capturing stdout +
  * stderr and resolving `{ stdout, stderr, code }`. A `timeoutMs` kills the
  * process (code resolves to `null` on signal/timeout). Never rejects on a
  * non-zero exit — the exit code is the result, not an error.
+ *
+ * ## Environment is SCRUBBED, never inherited (T11897 · security)
+ *
+ * The child runs under a MINIMAL, explicitly-constructed environment built by
+ * {@link scrubSubprocessEnv} — it does NOT inherit the parent `process.env`.
+ * This is load-bearing: the parent (the Cleo daemon) holds resolved provider
+ * credentials (`ANTHROPIC_API_KEY`, vault material, OAuth headers); blindly
+ * forwarding the full env into a child spawned on behalf of an in-process Pi
+ * loop would let a single `env`/`printenv` exfiltrate them, and would forward a
+ * Pi-poisoned `LD_PRELOAD`/`PATH`/`NODE_OPTIONS` into the loader. The
+ * caller-supplied `input.env` is merged on top but itself scrubbed (forbidden
+ * keys dropped, `PATH` pinned). Benign vars (locale/term/home) pass through.
  */
 export const defaultShellExecutor = (input) => new Promise((resolve, reject) => {
     const child = spawn(input.command, [...(input.args ?? [])], {
         cwd: input.cwd,
-        env: input.env ? { ...process.env, ...input.env } : process.env,
+        env: scrubSubprocessEnv({ extra: input.env }),
         timeout: input.timeoutMs,
         shell: false,
     });

package/dist/tools/shell.js.map

@@ -1 +1 @@
-{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../src/tools/shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAc3C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAkB,CAAC,KAAK,EAAE,EAAE,CAC3D,IAAI,OAAO,CAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;IAClD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,EAAE;QAC1D,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG;QAC/D,OAAO,EAAE,KAAK,CAAC,SAAS;QACxB,KAAK,EAAE,KAAK;KACb,CAAC,CAAC;IACH,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE;QACrC,MAAM,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IACH,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE;QACrC,MAAM,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC1B,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;QACzB,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEL;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAwB,EACxB,WAA0B,oBAAoB;IAE9C,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,MAAM,CACpB,KAAkB,EAClB,WAA0B,oBAAoB;IAE9C,OAAO,YAAY,CACjB,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,EAChF,QAAQ,CACT,CAAC;AACJ,CAAC"}
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../src/tools/shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAM3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AASpD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAkB,CAAC,KAAK,EAAE,EAAE,CAC3D,IAAI,OAAO,CAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;IAClD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,EAAE;QAC1D,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,GAAG,EAAE,kBAAkB,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC;QAC7C,OAAO,EAAE,KAAK,CAAC,SAAS;QACxB,KAAK,EAAE,KAAK;KACb,CAAC,CAAC;IACH,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE;QACrC,MAAM,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IACH,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE;QACrC,MAAM,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC1B,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;QACzB,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEL;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAwB,EACxB,WAA0B,oBAAoB;IAE9C,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,MAAM,CACpB,KAAkB,EAClB,WAA0B,oBAAoB;IAE9C,OAAO,YAAY,CACjB,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,EAChF,QAAQ,CACT,CAAC;AACJ,CAAC"}

package/dist/tools/web-agent-tools.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Web + browser agent-tool FAMILY — registration (T1742 · epic T11456 · SG-TOOLS).
+ *
+ * Registers the `web` toolset into the {@link ./agent-registry.js |
+ * AgentToolRegistry}, on top of the terminal/file/search/git families
+ * ({@link ./agent-tool-families.js}):
+ *
+ *   - **AC1** `web_search` — pluggable, backend-agnostic search
+ *     ({@link ./web-search-backends.js}); graceful `unavailable` result when no
+ *     backend can answer. NO hard paid-API dependency.
+ *   - **AC2** `web_extract` — fetch a URL + convert HTML to markdown.
+ *   - **AC3** `browser_navigate` — Playwright (lazily, optionally loaded).
+ *   - **AC4** `browser_click` / `browser_type` / `browser_press`.
+ *   - **AC5** `browser_snapshot` — accessibility tree.
+ *   - **AC6** `browser_vision` — screenshot + AI analysis routed THROUGH the E9
+ *     `resolveLLMForSystem` chokepoint + sealed-credential handle (never a raw
+ *     provider call).
+ *   - **AC7** `browser_scroll` up / down.
+ *   - **AC8** all registered; the browser tools' `available()` returns `false`
+ *     (with an install hint) when Playwright is absent.
+ *
+ * Browser tools share ONE lazily-launched {@link BrowserSession} per registration
+ * (a closure cell), so the optional Playwright load happens at most once per run.
+ * The web tools' network egress flows through an injectable {@link HttpFetch}; the
+ * vision AI call flows through the single E9 chokepoint — neither bypasses the
+ * resolver / credential layer. Import-time side-effect-free (NO top-level
+ * playwright import).
+ *
+ * @epic T11456
+ * @task T1742
+ * @see ./browser-driver.js — the optional-Playwright lazy-load backend
+ * @see ./web-search-backends.js — the pluggable search backends + HTML→markdown
+ */
+import type { AgentToolRegistry } from './agent-registry.js';
+import { BrowserSession } from './browser-driver.js';
+import { type HttpFetch } from './web-search-backends.js';
+/**
+ * Options for {@link registerWebAgentTools} — all injectable so tests run with
+ * NO real network and NO real browser launch (AC9).
+ */
+export interface WebAgentToolOptions {
+    /** Injected HTTP fetch (defaults to the platform `fetch`). */
+    readonly http?: HttpFetch;
+    /** Injected browser session (defaults to a real lazy-Playwright session). */
+    readonly browser?: BrowserSession;
+    /**
+     * SearXNG instance URL for the `searxng` backend. When omitted, the SearXNG
+     * backend reports unconfigured and only DuckDuckGo answers — preserving the
+     * "graceful when unconfigured" contract (AC1). Read from `SEARXNG_URL` env when
+     * not supplied.
+     */
+    readonly searxngUrl?: string;
+    /**
+     * Project root threaded into the E9 `resolveLLMForSystem` chokepoint for
+     * `browser_vision` (defaults to the resolver's own `process.cwd()` fallback).
+     */
+    readonly projectRoot?: string;
+}
+/**
+ * Register the web + browser agent-tool family into `registry`. Pure
+ * registration — no network, no browser launch, no scan; side effects happen
+ * later through the injected {@link HttpFetch} / {@link BrowserSession}.
+ *
+ * The browser tools are registered with a `playwright`-gated availability
+ * predicate (AC8): present in the registry but hidden by `available()` until a
+ * context advertises the optional Playwright capability.
+ *
+ * @param registry - The registry to populate.
+ * @param options - Injectable backends (HTTP fetch, browser session, searxng URL).
+ */
+export declare function registerWebAgentTools(registry: AgentToolRegistry, options?: WebAgentToolOptions): void;
+//# sourceMappingURL=web-agent-tools.d.ts.map

package/dist/tools/web-agent-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-agent-tools.d.ts","sourceRoot":"","sources":["../../src/tools/web-agent-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAWH,OAAO,KAAK,EAAE,iBAAiB,EAAqB,MAAM,qBAAqB,CAAC;AAChF,OAAO,EAAE,cAAc,EAA2B,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAGL,KAAK,SAAS,EAGf,MAAM,0BAA0B,CAAC;AAuBlC;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AA0FD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,GAAE,mBAAwB,GAChC,IAAI,CAkRN"}