@cleocode/core 2026.6.12 → 2026.6.14

package/dist/tools/fs.js

@@ -18,8 +18,61 @@
  * @task T11405
  * @saga T11387
  */
-import { mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { mkdir, readFile, realpath, rename, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, resolve as resolvePath } from 'node:path';
+/**
+ * Symlink-resolving canonicalization of a (possibly not-yet-existing) path.
+ *
+ * A purely LEXICAL path check (`resolve` + `relative`) is symlink-BLIND: a
+ * symlink planted inside an allowed root can point anywhere on the host, so the
+ * lexical path stays "inside" while the real target is outside. This is the
+ * classic symlink/TOCTOU escape. {@link canonicalizePath} resolves the REAL
+ * filesystem location so a containment check can be made against it:
+ *
+ * - If the path EXISTS, its own realpath is returned (every symlink component,
+ *   including the final one, is followed to its real target).
+ * - If the path does NOT exist (a fresh write target), the nearest existing
+ *   ANCESTOR directory is realpath'd and the not-yet-existing tail segments are
+ *   re-appended. This prevents a symlinked PARENT directory from redirecting a
+ *   write outside the boundary while still allowing legitimate new files.
+ *
+ * The returned path is always absolute. Containment MUST be re-checked against
+ * THIS value, not the lexical one.
+ *
+ * @param path - The path to canonicalize (absolute or relative to `process.cwd()`).
+ * @returns The symlink-resolved absolute path.
+ *
+ * @example
+ * ```ts
+ * // root/innocent.txt -> /tmp/secret  ⇒  canonicalizePath('root/innocent.txt')
+ * // returns '/tmp/secret', revealing the escape to the containment check.
+ * const real = await canonicalizePath(join(root, 'innocent.txt'));
+ * ```
+ */
+export async function canonicalizePath(path) {
+    const abs = isAbsolute(path) ? resolvePath(path) : resolvePath(path);
+    // Walk up to the nearest existing ancestor, realpath THAT, then re-attach the
+    // non-existing tail. This catches a symlinked parent directory AND a symlinked
+    // final component (when it exists, realpath(abs) follows it directly).
+    const tail = [];
+    let cursor = abs;
+    for (;;) {
+        try {
+            const real = await realpath(cursor);
+            return tail.length === 0 ? real : join(real, ...tail);
+        }
+        catch {
+            const parent = dirname(cursor);
+            if (parent === cursor) {
+                // Reached the filesystem root with nothing existing — return the lexical
+                // resolution (no symlink could have been involved on a missing chain).
+                return abs;
+            }
+            tail.unshift(basename(cursor));
+            cursor = parent;
+        }
+    }
+}
 /**
  * Read a file as text.
  *

package/dist/tools/fs.js.map

@@ -1 +1 @@
-{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../src/tools/fs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAU1C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,KAAoB;IACrD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,MAAM,EAAE,CAAC,CAAC;IACnF,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC;AACvC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAI,IAAY;IAC5C,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,YAAY,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;IACjD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAM,CAAC;AAClC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,KAAqB;IACzD,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,KAAK,CAAC,UAAU,KAAK,KAAK,EAAE,CAAC;QAC/B,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxC,CAAC;IACD,MAAM,YAAY,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC9D,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,OAAO,CAAC,GAAG,IAAI,YAAY,MAAM,CAAC,CAAC;IACjE,MAAM,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IAC9D,MAAM,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,YAAY,EAAE,CAAC;AAC5C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAsB;IACrD,IAAI,CAAC;QACH,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACjC,MAAM,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC;QAC3E,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC3B,CAAC;AACH,CAAC"}
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../src/tools/fs.ts"],"names":[],"mappings":"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"}

package/dist/tools/guard.d.ts

@@ -37,6 +37,7 @@
  * @task T11407
  * @saga T11387
  */
+import type { RunShellInput, RunShellResult } from '@cleocode/contracts/tools/agent-tools';
 import type { ExecuteShellInput, ExecuteShellResult, PathExistsInput, PathExistsResult, ReadFileInput, ReadFileResult, RunGitInput, WriteFileInput, WriteFileResult } from '@cleocode/contracts/tools/atomic';
 import { type ShellExecutor } from './shell.js';
 /** Enforcement posture for a {@link ToolGuard}. */
@@ -118,11 +119,25 @@ export declare class GuardDeniedError extends Error {
 }
 /** The guarded primitive surface returned by {@link createToolGuard}. */
 export interface ToolGuard {
+    /**
+     * The resolved enforcement posture this guard was constructed with. Exposed so
+     * a security-sensitive consumer (e.g. the Pi adapter) can ASSERT it received an
+     * `enforce`-mode guard before handing it untrusted work — in `warn` mode the
+     * allowlist/denylist are advisory (log-and-proceed) and provide no boundary.
+     */
+    readonly mode: GuardMode;
     readFileText(input: ReadFileInput): Promise<ReadFileResult>;
     readJson<T>(path: string): Promise<T>;
     writeFileAtomic(input: WriteFileInput): Promise<WriteFileResult>;
     pathExists(input: PathExistsInput): Promise<PathExistsResult>;
     executeShell(input: ExecuteShellInput, executor?: ShellExecutor): Promise<ExecuteShellResult>;
+    /**
+     * Run a command under a PTY (or a non-PTY spawn fallback) through the guard.
+     * The command basename is checked against the denylist BEFORE any process is
+     * spawned and the child env is scrubbed — same policy point as
+     * {@link ToolGuard.executeShell}.
+     */
+    executePty(input: RunShellInput): Promise<RunShellResult>;
     runGit(input: RunGitInput, executor?: ShellExecutor): Promise<ExecuteShellResult>;
 }
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/tools/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAGH,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,WAAW,EACX,cAAc,EACd,eAAe,EAChB,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAItE,mDAAmD;AACnD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3C;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,6BAA6B,CAAC;AAEjE;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,QAAQ,CAAC;AAEhD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,IAAiB,GAAG,SAAS,CAGzE;AAED,4CAA4C;AAC5C,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;CAC3B;AAED,+EAA+E;AAC/E,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,yBAAyB;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED,yEAAyE;AACzE,MAAM,WAAW,SAAS;IACxB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5D,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACtC,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACjE,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC9D,YAAY,CAAC,KAAK,EAAE,iBAAiB,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC9F,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACnF;AAiBD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,MAAM,GAAE,eAAoB,GAAG,SAAS,CAsDvE"}
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/tools/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAC3F,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,WAAW,EACX,cAAc,EACd,eAAe,EAChB,MAAM,kCAAkC,CAAC;AAK1C,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAItE,mDAAmD;AACnD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3C;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,6BAA6B,CAAC;AAEjE;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,QAAQ,CAAC;AAEhD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,IAAiB,GAAG,SAAS,CAGzE;AAED,4CAA4C;AAC5C,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;CAC3B;AAED,+EAA+E;AAC/E,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,yBAAyB;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAED,yEAAyE;AACzE,MAAM,WAAW,SAAS;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5D,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACtC,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACjE,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC9D,YAAY,CAAC,KAAK,EAAE,iBAAiB,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC9F;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC1D,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACnF;AAoCD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,MAAM,GAAE,eAAoB,GAAG,SAAS,CAuEvE"}

package/dist/tools/guard.js

@@ -39,7 +39,9 @@
  */
 import { isAbsolute, resolve as resolvePath } from 'node:path';
 import { getLogger } from '../logger.js';
-import { pathExists, readFileText, readJson, writeFileAtomic } from './fs.js';
+import { scrubSubprocessEnv } from './env-scrub.js';
+import { canonicalizePath, pathExists, readFileText, readJson, writeFileAtomic } from './fs.js';
+import { runPty } from './pty.js';
 import { executeShell, runGit } from './shell.js';
 const log = getLogger('tool-guard');
 /**
@@ -103,14 +105,32 @@ export class GuardDeniedError extends Error {
         this.name = 'GuardDeniedError';
     }
 }
-/** True when `path` resolves under one of `roots`. */
-function isPathAllowed(path, roots) {
-    const abs = isAbsolute(path) ? path : resolvePath(path);
+/** True when the resolved absolute `abs` is equal to or under one of `roots`. */
+function isUnderRoots(abs, roots) {
     return roots.some((root) => {
         const r = resolvePath(root);
         return abs === r || abs.startsWith(`${r}/`);
     });
 }
+/**
+ * Whether `path` is allowed under `roots` after SYMLINK RESOLUTION.
+ *
+ * Both the candidate path AND each allowed root are canonicalized via
+ * {@link canonicalizePath} (which follows every symlink component, including a
+ * symlinked parent of a not-yet-existing write target) BEFORE the containment
+ * comparison. A purely lexical check is symlink-blind — a symlink planted inside
+ * an allowed root that points outside it would pass, then the underlying fs
+ * primitive would follow it. Resolving first closes that escape.
+ *
+ * @param path - The candidate path.
+ * @param roots - The allowed roots.
+ * @returns `true` when the real target is contained.
+ */
+async function isPathAllowed(path, roots) {
+    const realAbs = await canonicalizePath(isAbsolute(path) ? path : resolvePath(path));
+    const realRoots = await Promise.all(roots.map((r) => canonicalizePath(resolvePath(r))));
+    return isUnderRoots(realAbs, realRoots);
+}
 /** The denied command name matched by the policy, or null when allowed. */
 function deniedCommand(command, denied) {
     const base = command.split('/').pop() ?? command;
@@ -132,12 +152,14 @@ export function createToolGuard(policy = {}) {
     // Explicit policy.mode always wins; otherwise the date-gated default applies
     // (held at 'warn' behind the owner-gated flip — T11474 · AC4).
     const mode = policy.mode ?? resolveDefaultGuardMode();
-    const denyFs = (op, path) => {
+    const denyFs = async (op, path) => {
         if (!policy.allowedRoots || policy.allowedRoots.length === 0)
             return false;
-        if (isPathAllowed(path, policy.allowedRoots))
+        // Symlink-resolving containment — a lexically-inside path whose REAL target
+        // (via a symlinked component) escapes the roots is rejected here.
+        if (await isPathAllowed(path, policy.allowedRoots))
             return false;
-        const msg = `tool-guard: fs.${op} path "${path}" is outside the allowed roots`;
+        const msg = `tool-guard: fs.${op} path "${path}" resolves outside the allowed roots`;
         if (mode === 'enforce')
             throw new GuardDeniedError(msg);
         log.warn({ op, path, allowedRoots: policy.allowedRoots }, msg);
@@ -159,25 +181,40 @@ export function createToolGuard(policy = {}) {
     // surfaces as a REJECTED promise (not a synchronous throw) — the API contract
     // is `Promise<…>`, and callers (+ vitest `.rejects`) expect rejection.
     return {
+        mode,
         async readFileText(input) {
-            denyFs('readFileText', input.path);
+            await denyFs('readFileText', input.path);
             return readFileText(input);
         },
         async readJson(path) {
-            denyFs('readJson', path);
+            await denyFs('readJson', path);
             return readJson(path);
         },
         async writeFileAtomic(input) {
-            denyFs('writeFileAtomic', input.path);
+            await denyFs('writeFileAtomic', input.path);
             return writeFileAtomic(input);
         },
         async pathExists(input) {
-            denyFs('pathExists', input.path);
+            await denyFs('pathExists', input.path);
             return pathExists(input);
         },
         async executeShell(input, executor) {
             denyShell('executeShell', input.command);
-            return executeShell(input, executor);
+            // Scrub the child env at the chokepoint: never inherit the daemon's
+            // secrets, never forward a Pi-controlled loader hook / PATH. The
+            // caller-supplied `env` is merged ON TOP but itself scrubbed (a forbidden
+            // key — loader hook, PATH, secret — is dropped here). `defaultShellExecutor`
+            // also scrubs as a redundant net, but the guard is the policy point.
+            const env = scrubSubprocessEnv({ extra: input.env });
+            return executeShell({ ...input, env }, executor);
+        },
+        async executePty(input) {
+            // Same policy point as executeShell: deny-check the command basename
+            // BEFORE spawning any PTY/process. `runPty` re-scrubs the env internally
+            // (PTY + spawn paths both use `scrubSubprocessEnv`), so the daemon's
+            // secrets and any Pi-controlled loader hook can never reach the child.
+            denyShell('executePty', input.command);
+            return runPty(input);
         },
         async runGit(input, executor) {
             denyShell('runGit', 'git');

package/dist/tools/guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"guard.js","sourceRoot":"","sources":["../../src/tools/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EAAE,UAAU,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,WAAW,CAAC;AAY/D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAE,MAAM,EAAsB,MAAM,YAAY,CAAC;AAEtE,MAAM,GAAG,GAAG,SAAS,CAAC,YAAY,CAAC,CAAC;AAKpC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,0BAA0B,CAAC;AAEjE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,KAAK,CAAC;AAEhD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAY,IAAI,IAAI,EAAE;IAC5D,IAAI,CAAC,0BAA0B;QAAE,OAAO,MAAM,CAAC;IAC/C,OAAO,GAAG,CAAC,OAAO,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC;AAClF,CAAC;AAwBD,+EAA+E;AAC/E,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC,6BAA6B;IACpB,IAAI,GAAG,qBAAqB,CAAC;IACtC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAYD,sDAAsD;AACtD,SAAS,aAAa,CAAC,IAAY,EAAE,KAAwB;IAC3D,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IACxD,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;QACzB,MAAM,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;QAC5B,OAAO,GAAG,KAAK,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;AACL,CAAC;AAED,2EAA2E;AAC3E,SAAS,aAAa,CAAC,OAAe,EAAE,MAAyB;IAC/D,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,OAAO,CAAC;IACjD,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACzE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,SAA0B,EAAE;IAC1D,6EAA6E;IAC7E,+DAA+D;IAC/D,MAAM,IAAI,GAAc,MAAM,CAAC,IAAI,IAAI,uBAAuB,EAAE,CAAC;IAEjE,MAAM,MAAM,GAAG,CAAC,EAAU,EAAE,IAAY,EAAW,EAAE;QACnD,IAAI,CAAC,MAAM,CAAC,YAAY,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QAC3E,IAAI,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,YAAY,CAAC;YAAE,OAAO,KAAK,CAAC;QAC3D,MAAM,GAAG,GAAG,kBAAkB,EAAE,UAAU,IAAI,gCAAgC,CAAC;QAC/E,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM,IAAI,gBAAgB,CAAC,GAAG,CAAC,CAAC;QACxD,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,EAAE,GAAG,CAAC,CAAC;QAC/D,OAAO,KAAK,CAAC,CAAC,oBAAoB;IACpC,CAAC,CAAC;IAEF,MAAM,SAAS,GAAG,CAAC,EAAU,EAAE,OAAe,EAAW,EAAE;QACzD,MAAM,GAAG,GAAG,MAAM,CAAC,cAAc,EAAE,MAAM;YACvC,CAAC,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,cAAc,CAAC;YAC/C,CAAC,CAAC,IAAI,CAAC;QACT,IAAI,CAAC,GAAG;YAAE,OAAO,KAAK,CAAC;QACvB,MAAM,GAAG,GAAG,qBAAqB,EAAE,aAAa,GAAG,sBAAsB,CAAC;QAC1E,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM,IAAI,gBAAgB,CAAC,GAAG,CAAC,CAAC;QACxD,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,GAAG,CAAC,CAAC;QAC/B,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,wEAAwE;IACxE,8EAA8E;IAC9E,uEAAuE;IACvE,OAAO;QACL,KAAK,CAAC,YAAY,CAAC,KAAK;YACtB,MAAM,CAAC,cAAc,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACnC,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;QACD,KAAK,CAAC,QAAQ,CAAI,IAAY;YAC5B,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;YACzB,OAAO,QAAQ,CAAI,IAAI,CAAC,CAAC;QAC3B,CAAC;QACD,KAAK,CAAC,eAAe,CAAC,KAAK;YACzB,MAAM,CAAC,iBAAiB,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACtC,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;QACD,KAAK,CAAC,UAAU,CAAC,KAAK;YACpB,MAAM,CAAC,YAAY,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACjC,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC;QACD,KAAK,CAAC,YAAY,CAAC,KAAK,EAAE,QAAQ;YAChC,SAAS,CAAC,cAAc,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;YACzC,OAAO,YAAY,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACvC,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ;YAC1B,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YAC3B,OAAO,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;QACjC,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"guard.js","sourceRoot":"","sources":["../../src/tools/guard.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.d.ts

@@ -42,6 +42,22 @@ export type { ScaffoldProjectOptions, ScaffoldProjectResult, ScaffoldProjectStep
 export { scaffoldProject } from '../scaffold/scaffold-project.js';
 export * from '../sdk/index.js';
 export * from '../task-tools/index.js';
+export { AGENT_TOOL_REGISTER_FN, type AgentToolDescriptor, type AgentToolDiscoveryOptions, type AgentToolExecutable, AgentToolRegistry, ALWAYS_AVAILABLE, type AvailabilityCheck, createAgentToolRegistry, type ToolAvailabilityContext, } from './agent-registry.js';
+export { applyFuzzyPatch, type FuzzyPatchOutcome, GIT_LOG_FORMAT, paginateLines, parseGitLog, parseGitStatus, parseRipgrepOutput, registerAgentToolFamilies, } from './agent-tool-families.js';
+export { BrowserSession, isPlaywrightAvailable, PLAYWRIGHT_INSTALL_HINT, type PlaywrightLoader, } from './browser-driver.js';
+export { registerBuiltinAgentTools } from './builtin-agent-tools.js';
+export { flattenZodIssues, formatToolResultForLlm, formatToolValueForLlm, MAX_TOOL_RESULT_CHARS, redactErrorMessage, TOOL_DISPATCH_ERROR_CODE, type ToolArgIssue, type ToolBudgetLimits, type ToolBudgetSnapshot, type ToolCall, ToolCallBudget, ToolDispatchEngine, type ToolDispatchEngineDeps, type ToolDispatchErrorKind, type ToolDispatchFailure, type ToolDispatchResult, type ToolDispatchSuccess, type ToolResultPayload, ToolTimeoutError, } from './dispatch.js';
+export { isForbiddenEnvName, type ScrubEnvOptions, scrubSubprocessEnv, TRUSTED_PATH, } from './env-scrub.js';
+export { buildExecCommand, codeExecAvailable, EXEC_CODE_LANGUAGES, type ExecCodeAgentToolOptions, type ExecCodeLanguage, type ExecCodeResult, type ExecutionEnvResolver, registerExecCodeAgentTool, } from './exec-code-agent-tool.js';
 export { createToolGuard, GUARD_ENFORCE_DEADLINE, GUARD_ENFORCE_FLIP_ENABLED, GuardDeniedError, type GuardMode, resolveDefaultGuardMode, type ToolGuard, type ToolGuardPolicy, } from './guard.js';
+export { buildMcpProxyTool, connectMcpServer, MCP_TRANSPORT_KINDS, type McpAgentToolOptions, type McpConnection, type McpRemoteTool, type McpToolCallResult, type McpTransport, type McpTransportKind, mcpToolName, registerMcpAgentTools, registerMcpConnectionTools, } from './mcp-agent-tool.js';
+export { type MediaAgentToolOptions, type MediaModelResult, multimodalAvailable, registerMediaAgentTools, } from './media-agent-tools.js';
+export { type MemoryAgentToolOptions, type MemoryOps, registerMemoryAgentTools, } from './memory-agent-tools.js';
+export { runPty } from './pty.js';
+export { type CronScheduleResult, registerScheduleAgentTools, type ScheduleAgentToolOptions, scheduleStoreAvailable, type TaskOps, } from './schedule-agent-tools.js';
+export { type ZodSchemaTool, zodSchemaToOpenAITool } from './schema-gen.js';
 export { defaultShellExecutor, type ShellExecutor } from './shell.js';
+export { type RunSkillResult, registerSkillAgentTool, type SkillAgentToolOptions, type SkillResolver, } from './skill-agent-tool.js';
+export { registerWebAgentTools, type WebAgentToolOptions } from './web-agent-tools.js';
+export { defaultHttpFetch, duckDuckGoBackend, extractTitle, fetchAndExtract, type HttpFetch, htmlToMarkdown, makeSearxngBackend, parseDuckDuckGoHtml, parseSearxngJson, resolveSearchBackends, runSearch, type WebSearchBackend, } from './web-search-backends.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,cAAc,yBAAyB,CAAC;AACxC,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAE7F,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,EACzB,0BAA0B,EAC1B,0BAA0B,EAC1B,sBAAsB,EACtB,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,2BAA2B,EAC3B,wBAAwB,EACxB,iBAAiB,EACjB,cAAc,EACd,wBAAwB,EACxB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,YAAY,EACV,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAElE,cAAc,iBAAiB,CAAC;AAEhC,cAAc,wBAAwB,CAAC;AAGvC,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,0BAA0B,EAC1B,gBAAgB,EAChB,KAAK,SAAS,EACd,uBAAuB,EACvB,KAAK,SAAS,EACd,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,oBAAoB,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.js

@@ -44,10 +44,62 @@ export { scaffoldProject } from '../scaffold/scaffold-project.js';
 export * from '../sdk/index.js';
 // TaskTools (Category B) — pure-functional task graph SDK tools (T10068 / T9835)
 export * from '../task-tools/index.js';
+// Agent-facing tool registry (T1739 · E-TOOLS · epic T11456) — the Hermes
+// `tools/registry.py` analogue. Self-discovering, OpenAI-format schema-emitting,
+// toolset-grouped, availability-gated, frozen-after-init registry. Side effects
+// always route through the guarded surface; auto-discovery is an EXPLICIT init()
+// (NOT at module import — AC7).
+export { AGENT_TOOL_REGISTER_FN, AgentToolRegistry, ALWAYS_AVAILABLE, createAgentToolRegistry, } from './agent-registry.js';
+// Agent-facing tool families (T1741 · epic T11456) — terminal `run_shell` (PTY +
+// non-PTY spawn fallback), paginated `read_file_paged`, atomic `write_file_atomic`,
+// fuzzy `apply_patch`, ripgrep `search_files`, and the git family. Pure helpers
+// (pagination, fuzzy patch, rg/git output parsing) are exported for direct unit
+// testing; every executable routes side effects through the guarded surface.
+export { applyFuzzyPatch, GIT_LOG_FORMAT, paginateLines, parseGitLog, parseGitStatus, parseRipgrepOutput, registerAgentToolFamilies, } from './agent-tool-families.js';
+// Web + browser agent tools (T1742 · epic T11456) — the `web` toolset:
+// `web_search` (pluggable keyless backends), `web_extract` (HTML→markdown), and
+// the Playwright-driven `browser_*` family. Playwright is OPTIONAL + lazily
+// loaded; the browser tools register but report unavailable (with an install
+// hint) when it is absent. The `browser_vision` AI call routes through the E9
+// `resolveLLMForSystem` chokepoint + sealed credential — no raw provider call.
+export { BrowserSession, isPlaywrightAvailable, PLAYWRIGHT_INSTALL_HINT, } from './browser-driver.js';
+export { registerBuiltinAgentTools } from './builtin-agent-tools.js';
+// Agent tool-call dispatch engine (T1740 · epic T11456) — the SDK chokepoint that
+// turns a model-emitted tool-call into an executed, LLM-safe result: registry
+// lookup → Zod-validate → availability → run-scoped budget → guarded execution →
+// classified result + LLM-facing formatting. Pure dispatch; defines NO new tool
+// primitive (Gate-11) and makes NO LLM call (Gate-13). The Pi adapter binds the
+// loop's tool execution to this engine (AC6 — see core/src/llm/pi/pi-tool-bridge).
+export { flattenZodIssues, formatToolResultForLlm, formatToolValueForLlm, MAX_TOOL_RESULT_CHARS, redactErrorMessage, TOOL_DISPATCH_ERROR_CODE, ToolCallBudget, ToolDispatchEngine, ToolTimeoutError, } from './dispatch.js';
+// Subprocess env scrubbing (T11897 · security) — the chokepoint builds a minimal,
+// allowlisted child env so daemon secrets never leak and a Pi-controlled loader
+// hook / PATH can never reach a spawned process.
+export { isForbiddenEnvName, scrubSubprocessEnv, TRUSTED_PATH, } from './env-scrub.js';
+// `execute_code` agent tool (T11946 · M7) — the `agent` toolset's guarded
+// code-execution capability. Routes every run through the existing
+// `resolveExecutionEnv` selector (Gondolin micro-VM when available, in-process
+// guarded `ExecutionEnv` otherwise — gondolin is OPTIONAL, so core builds with it
+// ABSENT). Registered always; available() hides it unless `capabilities.codeExec`.
+export { buildExecCommand, codeExecAvailable, EXEC_CODE_LANGUAGES, registerExecCodeAgentTool, } from './exec-code-agent-tool.js';
 // Atomic-tool guard chokepoint (E3 · T11407 · T11474) — the ONLY public route to
 // the fs/shell primitives. Raw primitives are intentionally not re-exported.
 export { createToolGuard, GUARD_ENFORCE_DEADLINE, GUARD_ENFORCE_FLIP_ENABLED, GuardDeniedError, resolveDefaultGuardMode, } from './guard.js';
+export { buildMcpProxyTool, connectMcpServer, MCP_TRANSPORT_KINDS, mcpToolName, registerMcpAgentTools, registerMcpConnectionTools, } from './mcp-agent-tool.js';
+// M7 agent-tool catalog (T11947–T11951) — memory / mcp / run_skill / cron-todo /
+// vision-media families. Each DEFINED here under `packages/core/src/tools`
+// (Gate-11) and CONSUMES an existing subsystem (BRAIN / skills / task store / E9
+// chokepoint) — no new store, no new loader, no raw provider client (Gate-13).
+export { multimodalAvailable, registerMediaAgentTools, } from './media-agent-tools.js';
+export { registerMemoryAgentTools, } from './memory-agent-tools.js';
+// PTY shell runner (T1741) — the terminal toolset's execution backend; lazily +
+// optionally loads `node-pty`, transparently degrading to non-PTY `spawn`.
+export { runPty } from './pty.js';
+export { registerScheduleAgentTools, scheduleStoreAvailable, } from './schedule-agent-tools.js';
+export { zodSchemaToOpenAITool } from './schema-gen.js';
 // Injectable shell executor (E3 · T11406) — threaded into the guard's
 // executeShell/runGit; substitutes the subprocess layer in tests/sandboxes.
 export { defaultShellExecutor } from './shell.js';
+export { registerSkillAgentTool, } from './skill-agent-tool.js';
+export { registerWebAgentTools } from './web-agent-tools.js';
+export { defaultHttpFetch, duckDuckGoBackend, extractTitle, fetchAndExtract, htmlToMarkdown, makeSearxngBackend, parseDuckDuckGoHtml, parseSearxngJson, resolveSearchBackends, runSearch, } from './web-search-backends.js';
 //# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,uFAAuF;AACvF,cAAc,yBAAyB,CAAC;AAExC,uFAAuF;AACvF,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,uDAAuD;AACvD,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,EACzB,0BAA0B,EAC1B,0BAA0B,EAC1B,sBAAsB,EACtB,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,2BAA2B,EAC3B,wBAAwB,EACxB,iBAAiB,EACjB,cAAc,EACd,wBAAwB,EACxB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAMhE,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,6EAA6E;AAC7E,cAAc,iBAAiB,CAAC;AAChC,iFAAiF;AACjF,cAAc,wBAAwB,CAAC;AACvC,iFAAiF;AACjF,6EAA6E;AAC7E,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,0BAA0B,EAC1B,gBAAgB,EAEhB,uBAAuB,GAGxB,MAAM,YAAY,CAAC;AACpB,sEAAsE;AACtE,4EAA4E;AAC5E,OAAO,EAAE,oBAAoB,EAAsB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/mcp-agent-tool.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Native MCP client (fan-IN) agent tool — connect-time `listTools` → register each
+ * remote tool into the {@link ./agent-registry.js | AgentToolRegistry}
+ * (T11948 · M7 · epic T11456 · SG-TOOLS · satisfies T11593 EP-MCP-HOST-FANIN + T1746).
+ *
+ * Where the runtime gateway is the MCP *server* (fan-OUT: it EXPOSES cleo ops as
+ * MCP tools), this is the MCP *client* (fan-IN: it CONNECTS to an external MCP
+ * server and PULLS its tools into cleo's own agent loop). On connect the client
+ * performs the MCP handshake (`initialize` → `tools/list`) and registers EACH
+ * remote tool as a proxy {@link AgentToolDescriptor} BEFORE the registry is frozen
+ * (init-time fan-in). Each proxy tool's `execute` issues a `tools/call` over the
+ * SAME transport and formats the result for the loop; a transport failure becomes a
+ * typed result (the executable NEVER throws — the frozen ToolDispatchEngine is
+ * unchanged).
+ *
+ * This REPLACES the external mcp-tool dependency for the host-loop path. It is a
+ * deliberately-minimal native client — NO external MCP SDK dependency: the wire is
+ * the standard MCP JSON-RPC ({@link McpTransport}), with stdio / SSE / HTTP
+ * transports as concrete {@link McpTransport} implementations. Placed in `core` per
+ * the package boundary (consumed by the harness, never redefined there — Gate-11).
+ *
+ * ## Availability (AC — live-connection only)
+ *
+ * A fan-in tool is available ONLY while its MCP server connection is live. The
+ * client exposes an {@link McpConnection.isLive} cell that each proxy tool's
+ * {@link AvailabilityCheck} reads; once the connection closes (or its transport
+ * errors fatally), the proxy tools report unavailable rather than dispatching into
+ * a dead transport.
+ *
+ * ## Gate-13
+ *
+ * No model/transport/provider LLM client is constructed here — the MCP transport
+ * speaks the tool protocol, not an LLM wire. There is no chokepoint concern.
+ *
+ * @epic T11456
+ * @task T11948
+ * @see ../../runtime/src/gateway/mcp/types.ts — the MCP server (fan-out) wire types this mirrors
+ * @see ./exec-code-agent-tool.js — the injectable-seam + self-registering-marker pattern mirrored here
+ */
+import type { AgentToolDescriptor, AgentToolRegistry } from './agent-registry.js';
+/** JSON Schema property descriptor for a single remote-tool input field. */
+export interface McpInputProperty {
+    /** JSON Schema primitive type (`'string'`, `'number'`, …). */
+    readonly type: string;
+    /** Human-readable description. */
+    readonly description?: string;
+    /** Allowed values (JSON Schema `enum`). */
+    readonly enum?: readonly string[];
+}
+/**
+ * MCP remote-tool definition (minimal subset — no external MCP SDK dependency).
+ * The shape returned by an MCP server's `tools/list`.
+ */
+export interface McpRemoteTool {
+    /** Stable remote tool name. */
+    readonly name: string;
+    /** Human-readable description. */
+    readonly description?: string;
+    /** JSON Schema for the tool's input parameters. */
+    readonly inputSchema?: {
+        readonly type?: string;
+        readonly properties?: Readonly<Record<string, McpInputProperty>>;
+        readonly required?: readonly string[];
+    };
+}
+/** A single content block returned by an MCP `tools/call`. */
+export interface McpContent {
+    readonly type: string;
+    readonly text?: string;
+}
+/** Result returned by an MCP `tools/call`. */
+export interface McpToolCallResult {
+    readonly content?: readonly McpContent[];
+    readonly isError?: boolean;
+}
+/**
+ * The wire seam every MCP transport implements: issue a JSON-RPC `method` with
+ * `params` and resolve the typed `result`. The stdio / SSE / HTTP transports are
+ * concrete implementations; the unit test injects an in-memory fake. The transport
+ * owns framing + correlation — this module only speaks MCP methods over it.
+ */
+export interface McpTransport {
+    /**
+     * Send an MCP JSON-RPC request and resolve its `result`.
+     *
+     * @param method - The MCP method (`'initialize'`, `'tools/list'`, `'tools/call'`).
+     * @param params - The method params.
+     * @returns The JSON-RPC `result` payload.
+     * @throws When the transport is dead or the server returns a JSON-RPC error.
+     */
+    request(method: string, params?: Readonly<Record<string, unknown>>): Promise<unknown>;
+    /** Close the transport (idempotent). After close, {@link request} rejects. */
+    close(): Promise<void>;
+}
+/** Transport kinds a native MCP client connection can speak over. */
+export declare const MCP_TRANSPORT_KINDS: readonly ["stdio", "sse", "http"];
+/** One supported {@link MCP_TRANSPORT_KINDS} value. */
+export type McpTransportKind = (typeof MCP_TRANSPORT_KINDS)[number];
+/**
+ * A live MCP client connection: a transport + the liveness cell the proxy tools'
+ * availability predicate reads. Produced by {@link connectMcpServer}.
+ */
+export interface McpConnection {
+    /** A stable server name used to namespace the fan-in tool names. */
+    readonly serverName: string;
+    /** The underlying transport. */
+    readonly transport: McpTransport;
+    /** The remote tools discovered at connect (`tools/list`). */
+    readonly tools: readonly McpRemoteTool[];
+    /** `true` while the connection is live; flips `false` on {@link disconnect}. */
+    isLive(): boolean;
+    /** Close the transport and flip the liveness cell to `false`. */
+    disconnect(): Promise<void>;
+}
+/**
+ * Perform the MCP handshake over `transport` and discover its tools: send
+ * `initialize`, then `tools/list`. Returns a live {@link McpConnection} whose
+ * liveness cell is `true` until {@link McpConnection.disconnect}. The transport is
+ * supplied by the caller (so stdio / SSE / HTTP — or an in-memory fake — all flow
+ * through the same path).
+ *
+ * @param serverName - Stable name to namespace this server's fan-in tools.
+ * @param transport - The MCP transport to handshake over.
+ * @returns The connected {@link McpConnection}.
+ * @throws When `initialize` or `tools/list` fails (the connection is not live).
+ */
+export declare function connectMcpServer(serverName: string, transport: McpTransport): Promise<McpConnection>;
+/**
+ * The namespaced agent-tool name for a remote MCP tool: `mcp_<server>_<tool>`. So
+ * two servers exposing a same-named tool never collide in the registry.
+ *
+ * @param serverName - The MCP server's stable name.
+ * @param toolName - The remote tool's name.
+ * @returns The namespaced, registry-unique tool name.
+ */
+export declare function mcpToolName(serverName: string, toolName: string): string;
+/**
+ * Build the proxy {@link AgentToolDescriptor} for ONE remote tool over a live
+ * connection. Its `execute` issues `tools/call` over the connection's transport
+ * and formats the result; a transport / server error becomes a typed result (never
+ * throws). Its availability returns `true` only while the connection is live.
+ *
+ * @param conn - The live MCP connection.
+ * @param tool - The remote tool to proxy.
+ * @returns The proxy descriptor to register.
+ */
+export declare function buildMcpProxyTool(conn: McpConnection, tool: McpRemoteTool): AgentToolDescriptor;
+/**
+ * Register every fan-in proxy tool for a live MCP connection into `registry`. Pure
+ * registration over an ALREADY-connected {@link McpConnection} — the connect /
+ * `tools/list` happened in {@link connectMcpServer} (which the host calls at
+ * init-time, before the registry is frozen). Each remote tool becomes one proxy
+ * descriptor (AC1); each is hidden once the connection drops (AC — live-only).
+ *
+ * @param registry - The registry to populate (must not yet be frozen).
+ * @param conn - The live MCP connection whose tools to fan in.
+ * @returns The registered proxy tool names.
+ */
+export declare function registerMcpConnectionTools(registry: AgentToolRegistry, conn: McpConnection): string[];
+/** Options for {@link registerMcpAgentTools} — the connections to fan in. */
+export interface McpAgentToolOptions {
+    /**
+     * Already-connected MCP connections whose remote tools to fan in. The host
+     * connects each server (via {@link connectMcpServer}) at init-time, BEFORE the
+     * registry is frozen, then passes the live connections here. Defaults to none —
+     * with no MCP servers configured this is a no-op (core runs MCP-OFF).
+     */
+    readonly connections?: readonly McpConnection[];
+}
+/**
+ * Register the fan-in proxy tools for every supplied MCP connection. Pure
+ * registration — no network handshake here (the connections are already live);
+ * the connect happens earlier in {@link connectMcpServer}. With no connections
+ * this is a no-op (the common no-MCP-configured case).
+ *
+ * @param registry - The registry to populate.
+ * @param options - The live connections to fan in.
+ */
+export declare function registerMcpAgentTools(registry: AgentToolRegistry, options?: McpAgentToolOptions): void;
+/**
+ * Self-registration marker (AC1) — the identifier the
+ * {@link AgentToolRegistry.discover} bounded source scan greps for. With no live
+ * connections supplied this registers nothing (a host wires connections via
+ * {@link registerMcpAgentTools} directly with its connected servers).
+ *
+ * @param registry - The registry to populate.
+ */
+export declare function registerAgentTools(registry: AgentToolRegistry): void;
+//# sourceMappingURL=mcp-agent-tool.d.ts.map

package/dist/tools/mcp-agent-tool.d.ts.map

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