@cleocode/core 2026.6.12 → 2026.6.14

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

@@ -0,0 +1,99 @@
+/**
+ * Memory (BRAIN) agent-tool family — `memory_search` / `memory_observe` /
+ * `memory_fetch` / `memory_timeline` (T11947 · M7 · epic T11456 · SG-TOOLS).
+ *
+ * Surfaces the EXISTING BRAIN cognitive-memory operations to the agent loop as
+ * `agent`-toolset tools, mirroring the `cleo memory find|observe|fetch|timeline`
+ * CLI verbs. It adds NO new store, NO new SQL, and NO new schema: each tool
+ * DELEGATES to the established memory ops in
+ * {@link import('../memory/engine-compat.js')}
+ * ({@link memoryFind} / {@link memoryObserve} / {@link memoryFetch} /
+ * {@link memoryTimeline}), which themselves route through the BRAIN retrieval
+ * accessors + the store chokepoint. The agent loop never re-implements brain
+ * retrieval — it reuses the SAME path the CLI and the orchestrator use.
+ *
+ * ## Why a seam, not a hardcoded import (AC5 + Gate-11)
+ *
+ * The four memory ops are injected through the {@link MemoryOps} seam, defaulting
+ * to the real `engine-compat` functions. This lets the unit test inject a FAKE
+ * Brain surface and assert delegation + schema validation WITHOUT opening a real
+ * `brain.db`. Production binds the real ops. The tools are DEFINED here under
+ * `packages/core/src/tools` and CONSUME the memory subsystem — they construct no
+ * new atomic primitive (Gate-11).
+ *
+ * ## Availability (AC4)
+ *
+ * BRAIN read/write is a LOCAL SQLite operation through the store chokepoint — no
+ * credential, no network, no daemon. Every memory tool is therefore
+ * {@link ALWAYS_AVAILABLE}: it works daemon-OFF and credential-OFF.
+ *
+ * ## Gate-13
+ *
+ * No model/transport/provider client is constructed here — BRAIN search is a
+ * local FTS/SQLite query, not an LLM call. There is no chokepoint concern.
+ *
+ * @epic T11456
+ * @task T11947
+ * @see ../memory/engine-compat.js — the memory ops this family delegates to
+ * @see ./exec-code-agent-tool.js — the injectable-seam + self-registering-marker pattern mirrored here
+ */
+import type { EngineResult } from '../engine-result.js';
+import { type AgentToolRegistry } from './agent-registry.js';
+/**
+ * The BRAIN memory operations the family delegates to. Each member has the SAME
+ * signature as the corresponding `engine-compat` function — `(params, root?) →
+ * Promise<EngineResult>`. Injectable so the unit test can supply a fake Brain
+ * surface; defaults to the real ops in production.
+ */
+export interface MemoryOps {
+    /** Token-efficient compact search (→ `cleo memory find`). */
+    readonly find: (params: {
+        query: string;
+        limit?: number;
+    }, projectRoot?: string) => Promise<EngineResult>;
+    /** Append an observation (→ `cleo memory observe`). */
+    readonly observe: (params: {
+        text: string;
+        title?: string;
+    }, projectRoot?: string) => Promise<EngineResult>;
+    /** Batch fetch entries by ID (→ `cleo memory fetch`). */
+    readonly fetch: (params: {
+        ids: string[];
+    }, projectRoot?: string) => Promise<EngineResult>;
+    /** Chronological context around an anchor (→ `cleo memory timeline`). */
+    readonly timeline: (params: {
+        anchor: string;
+        depthBefore?: number;
+        depthAfter?: number;
+    }, projectRoot?: string) => Promise<EngineResult>;
+}
+/** Options for {@link registerMemoryAgentTools} — all injectable for testing. */
+export interface MemoryAgentToolOptions {
+    /** The memory ops seam. Defaults to the real `engine-compat` functions. */
+    readonly memory?: MemoryOps;
+    /**
+     * The project root threaded into every op (defaults to the resolved project
+     * root via {@link resolveOrCwd} — never a bare `process.cwd()` in core, T9584).
+     */
+    readonly projectRoot?: string;
+}
+/**
+ * Register the memory (BRAIN) agent-tool family into `registry`. Pure
+ * registration — no `brain.db` is opened, no query runs here; all of that happens
+ * later inside each tool's `execute` through the injected (or default) ops.
+ * Import-time side-effect-free.
+ *
+ * @param registry - The registry to populate.
+ * @param options - Injectable memory ops / project root (for testing).
+ */
+export declare function registerMemoryAgentTools(registry: AgentToolRegistry, options?: MemoryAgentToolOptions): void;
+/**
+ * Self-registration marker (AC1) — the identifier the
+ * {@link AgentToolRegistry.discover} bounded source scan greps for. Aliases
+ * {@link registerMemoryAgentTools} so a future scan-dir discovery (or the
+ * built-in aggregator) can call it uniformly with the other agent-tool modules.
+ *
+ * @param registry - The registry to populate.
+ */
+export declare function registerAgentTools(registry: AgentToolRegistry): void;
+//# sourceMappingURL=memory-agent-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory-agent-tools.d.ts","sourceRoot":"","sources":["../../src/tools/memory-agent-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAQxD,OAAO,EAAE,KAAK,iBAAiB,EAAoB,MAAM,qBAAqB,CAAC;AAE/E;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,CACb,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EACzC,WAAW,CAAC,EAAE,MAAM,KACjB,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,CAChB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EACxC,WAAW,CAAC,EAAE,MAAM,KACjB,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,WAAW,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3F,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,CACjB,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,EACrE,WAAW,CAAC,EAAE,MAAM,KACjB,OAAO,CAAC,YAAY,CAAC,CAAC;CAC5B;AAUD,iFAAiF;AACjF,MAAM,WAAW,sBAAsB;IACrC,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAgBD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,GAAE,sBAA2B,GACnC,IAAI,CAgHN;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAEpE"}

package/dist/tools/memory-agent-tools.js

@@ -0,0 +1,190 @@
+/**
+ * Memory (BRAIN) agent-tool family — `memory_search` / `memory_observe` /
+ * `memory_fetch` / `memory_timeline` (T11947 · M7 · epic T11456 · SG-TOOLS).
+ *
+ * Surfaces the EXISTING BRAIN cognitive-memory operations to the agent loop as
+ * `agent`-toolset tools, mirroring the `cleo memory find|observe|fetch|timeline`
+ * CLI verbs. It adds NO new store, NO new SQL, and NO new schema: each tool
+ * DELEGATES to the established memory ops in
+ * {@link import('../memory/engine-compat.js')}
+ * ({@link memoryFind} / {@link memoryObserve} / {@link memoryFetch} /
+ * {@link memoryTimeline}), which themselves route through the BRAIN retrieval
+ * accessors + the store chokepoint. The agent loop never re-implements brain
+ * retrieval — it reuses the SAME path the CLI and the orchestrator use.
+ *
+ * ## Why a seam, not a hardcoded import (AC5 + Gate-11)
+ *
+ * The four memory ops are injected through the {@link MemoryOps} seam, defaulting
+ * to the real `engine-compat` functions. This lets the unit test inject a FAKE
+ * Brain surface and assert delegation + schema validation WITHOUT opening a real
+ * `brain.db`. Production binds the real ops. The tools are DEFINED here under
+ * `packages/core/src/tools` and CONSUME the memory subsystem — they construct no
+ * new atomic primitive (Gate-11).
+ *
+ * ## Availability (AC4)
+ *
+ * BRAIN read/write is a LOCAL SQLite operation through the store chokepoint — no
+ * credential, no network, no daemon. Every memory tool is therefore
+ * {@link ALWAYS_AVAILABLE}: it works daemon-OFF and credential-OFF.
+ *
+ * ## Gate-13
+ *
+ * No model/transport/provider client is constructed here — BRAIN search is a
+ * local FTS/SQLite query, not an LLM call. There is no chokepoint concern.
+ *
+ * @epic T11456
+ * @task T11947
+ * @see ../memory/engine-compat.js — the memory ops this family delegates to
+ * @see ./exec-code-agent-tool.js — the injectable-seam + self-registering-marker pattern mirrored here
+ */
+import { z } from 'zod';
+import { memoryFetch as realMemoryFetch, memoryFind as realMemoryFind, memoryObserve as realMemoryObserve, memoryTimeline as realMemoryTimeline, } from '../memory/engine-compat.js';
+import { resolveOrCwd } from '../paths.js';
+import { ALWAYS_AVAILABLE } from './agent-registry.js';
+/** The real BRAIN memory ops — the production default for {@link MemoryOps}. */
+const REAL_MEMORY_OPS = {
+    find: realMemoryFind,
+    observe: realMemoryObserve,
+    fetch: realMemoryFetch,
+    timeline: realMemoryTimeline,
+};
+/**
+ * Coerce an {@link EngineResult} into the opaque value the loop serialises back
+ * to the model. On success the `data` payload is returned as-is; on failure a
+ * stable `{ ok: false, error }` shape is returned (the op never throws for an
+ * expected failure — it returns a typed `EngineFailure`).
+ *
+ * @param result - The op's EngineResult.
+ * @returns The success data, or a typed failure object.
+ */
+function unwrapEngineResult(result) {
+    if (result.success)
+        return result.data;
+    return { ok: false, error: result.error };
+}
+/**
+ * Register the memory (BRAIN) agent-tool family into `registry`. Pure
+ * registration — no `brain.db` is opened, no query runs here; all of that happens
+ * later inside each tool's `execute` through the injected (or default) ops.
+ * Import-time side-effect-free.
+ *
+ * @param registry - The registry to populate.
+ * @param options - Injectable memory ops / project root (for testing).
+ */
+export function registerMemoryAgentTools(registry, options = {}) {
+    const memory = options.memory ?? REAL_MEMORY_OPS;
+    const projectRoot = resolveOrCwd(options.projectRoot);
+    // --- memory_search (→ memoryFind) ----------------------------------------
+    registry.register({
+        name: 'memory_search',
+        // 'search' — a local read-query of the BRAIN store (no side effect beyond reading).
+        class: 'search',
+        description: 'Search BRAIN cognitive memory (decisions / patterns / learnings / observations) ' +
+            'for entries matching a query, returning compact hits (IDs + titles). Use memory_fetch ' +
+            'to retrieve full details for a hit.',
+        toolset: 'agent',
+        stateless: true,
+        available: ALWAYS_AVAILABLE,
+        parameters: z.object({
+            query: z.string().describe('Free-text search query.'),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe('Maximum number of compact hits to return.'),
+        }),
+        execute: async (rawArgs) => {
+            const query = String(rawArgs.query);
+            const limit = typeof rawArgs.limit === 'number' ? rawArgs.limit : undefined;
+            const result = await memory.find({ query, limit }, projectRoot);
+            return unwrapEngineResult(result);
+        },
+    });
+    // --- memory_observe (→ memoryObserve) ------------------------------------
+    registry.register({
+        name: 'memory_observe',
+        // 'fs' — persists a row to the local BRAIN store (its strongest side-effect surface).
+        class: 'fs',
+        description: 'Append a new observation to BRAIN memory (an O-prefixed entry). Use after a ' +
+            'non-trivial step to record a learning or decision for future sessions.',
+        toolset: 'agent',
+        stateless: false,
+        available: ALWAYS_AVAILABLE,
+        parameters: z.object({
+            text: z.string().describe('The observation body to store.'),
+            title: z.string().optional().describe('A short title for the observation.'),
+        }),
+        execute: async (rawArgs) => {
+            const text = String(rawArgs.text);
+            const title = rawArgs.title === undefined ? undefined : String(rawArgs.title);
+            const result = await memory.observe({ text, title }, projectRoot);
+            return unwrapEngineResult(result);
+        },
+    });
+    // --- memory_fetch (→ memoryFetch) ----------------------------------------
+    registry.register({
+        name: 'memory_fetch',
+        class: 'search',
+        description: 'Fetch full details for one or more BRAIN entries by ID (e.g. O-abc123, D-def456). ' +
+            'Use after memory_search to expand a compact hit.',
+        toolset: 'agent',
+        stateless: true,
+        available: ALWAYS_AVAILABLE,
+        parameters: z.object({
+            ids: z
+                .array(z.string())
+                .min(1)
+                .describe('One or more BRAIN entry IDs to fetch (e.g. ["O-abc123"]).'),
+        }),
+        execute: async (rawArgs) => {
+            const ids = Array.isArray(rawArgs.ids) ? rawArgs.ids.map(String) : [];
+            const result = await memory.fetch({ ids }, projectRoot);
+            return unwrapEngineResult(result);
+        },
+    });
+    // --- memory_timeline (→ memoryTimeline) ----------------------------------
+    registry.register({
+        name: 'memory_timeline',
+        class: 'search',
+        description: 'Retrieve chronological context around a BRAIN entry — the entries recorded before ' +
+            'and after a given anchor ID — to understand the sequence of observations and decisions.',
+        toolset: 'agent',
+        stateless: true,
+        available: ALWAYS_AVAILABLE,
+        parameters: z.object({
+            anchor: z.string().describe('The BRAIN entry ID to anchor the timeline window on.'),
+            depthBefore: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe('How many entries before the anchor to include.'),
+            depthAfter: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe('How many entries after the anchor to include.'),
+        }),
+        execute: async (rawArgs) => {
+            const anchor = String(rawArgs.anchor);
+            const depthBefore = typeof rawArgs.depthBefore === 'number' ? rawArgs.depthBefore : undefined;
+            const depthAfter = typeof rawArgs.depthAfter === 'number' ? rawArgs.depthAfter : undefined;
+            const result = await memory.timeline({ anchor, depthBefore, depthAfter }, projectRoot);
+            return unwrapEngineResult(result);
+        },
+    });
+}
+/**
+ * Self-registration marker (AC1) — the identifier the
+ * {@link AgentToolRegistry.discover} bounded source scan greps for. Aliases
+ * {@link registerMemoryAgentTools} so a future scan-dir discovery (or the
+ * built-in aggregator) can call it uniformly with the other agent-tool modules.
+ *
+ * @param registry - The registry to populate.
+ */
+export function registerAgentTools(registry) {
+    registerMemoryAgentTools(registry);
+}
+//# sourceMappingURL=memory-agent-tools.js.map

package/dist/tools/memory-agent-tools.js.map

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

package/dist/tools/pty.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 type { RunShellInput, RunShellResult } from '@cleocode/contracts/tools/agent-tools';
+/**
+ * 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 declare function runPty(input: RunShellInput): Promise<RunShellResult>;
+//# sourceMappingURL=pty.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pty.d.ts","sourceRoot":"","sources":["../../src/tools/pty.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AA+I3F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAU1E"}

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":"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"}