@librechat/agents 3.1.77 → 3.1.78

package/dist/cjs/hooks/createWorkspacePolicyHook.cjs

@@ -0,0 +1,291 @@
+'use strict';
+
+var os = require('os');
+var path = require('path');
+var promises = require('fs/promises');
+var _enum = require('../common/enum.cjs');
+
+/**
+ * Workspace boundary policy as a `PreToolUse` hook.
+ *
+ * Local-engine file tools enforce a hard workspace boundary at the
+ * tool implementation layer (`resolveWorkspacePathSafe`). This hook
+ * adds a complementary, host-controlled layer on top that uses the
+ * standard PreToolUse / HITL machinery to *negotiate* access to
+ * paths outside the workspace — instead of just throwing.
+ *
+ * The host opts in by registering this hook on a `HookRegistry`; the
+ * hook inspects each tool call's input, extracts the file paths it
+ * mentions via per-tool extractors, and returns:
+ *
+ *   - `allow`               — every path is inside `workspace.root`
+ *                              (or `additionalRoots`)
+ *   - `deny`                — at least one path is outside, and the
+ *                              configured outside-policy is `'deny'`
+ *   - `ask`                 — at least one path is outside, and the
+ *                              outside-policy is `'ask'` (default).
+ *                              When `humanInTheLoop.enabled` is true,
+ *                              the existing PreToolUse `'ask'` flow
+ *                              raises a tool_approval interrupt the
+ *                              host UI can render. When HITL is off,
+ *                              `'ask'` collapses to `deny` (matches
+ *                              the rest of the SDK's default).
+ *
+ * Default per-tool path extractors cover the local-engine coding
+ * suite (`read_file`, `write_file`, `edit_file`, `grep_search`,
+ * `glob_search`, `list_directory`, `compile_check`). The host can
+ * override or extend via `pathExtractors`. Bash/code paths are not
+ * extracted by default — bash command parsing is its own concern, and
+ * the existing `bashAst` validator + sandbox-runtime fs allowlist are
+ * the right gates for those.
+ *
+ * Important: this hook does NOT replace `resolveWorkspacePathSafe`.
+ * Even if the hook returns `allow`, the file tool still enforces its
+ * own clamp unless `workspace.allowReadOutside` /
+ * `workspace.allowWriteOutside` (or the legacy
+ * `allowOutsideWorkspace`) is set. The recommended composition for
+ * "ask the user" semantics is:
+ *
+ *   workspace: {
+ *     root,
+ *     allowReadOutside: true,
+ *     allowWriteOutside: true,
+ *   },
+ *   // …with the hook installed and humanInTheLoop.enabled = true.
+ */
+const READ_TOOLS = new Set([
+    _enum.Constants.READ_FILE,
+    _enum.Constants.GREP_SEARCH,
+    _enum.Constants.GLOB_SEARCH,
+    _enum.Constants.LIST_DIRECTORY,
+    _enum.Constants.COMPILE_CHECK,
+]);
+const WRITE_TOOLS = new Set([
+    _enum.Constants.WRITE_FILE,
+    _enum.Constants.EDIT_FILE,
+]);
+/**
+ * Best-effort extractor for `compile_check` — pulls absolute and `~/`
+ * path tokens out of the `command` string so the workspace boundary
+ * sees them. Without this, a model could ship `command: 'cat
+ * /etc/passwd'` and the policy hook would short-circuit to `allow`
+ * (Codex P1 #26 — the prior `() => []` made the hook a no-op for
+ * compile_check). Conservative by design:
+ *
+ *   - Matches `/foo`, `~/foo`, `$HOME/foo`, `${HOME}/foo` followed by
+ *     non-shell-special chars. Stops at whitespace, quotes, redirect
+ *     operators, pipes, semicolons.
+ *   - Strips a leading `--flag=` so `--out=/etc/foo` extracts as
+ *     `/etc/foo` (the path the agent's actually trying to write).
+ *   - Misses relative paths (intended — those resolve under cwd
+ *     anyway), and shell-substituted paths whose final form isn't
+ *     visible at extract time. Hosts that need bulletproof gating
+ *     should pair this with a `bash_tool`-level policy.
+ */
+// `["']?` slots before AND after the captured path cover quoted
+// forms like `cat "/etc/passwd"` and `--out='/tmp/x'`. Codex P1 #31
+// — the previous regex only matched unquoted tokens, so a model
+// could trivially bypass the workspace policy by quoting any
+// destination path. The path content character class still excludes
+// quotes/whitespace/shell-specials so we don't over-extract; that's
+// the defensive trade we want for fallback-grep style matching.
+//
+// The `\.\.(?:\/[^…]*)?` alternation covers parent-traversal forms
+// (`..`, `../secrets.txt`, `../foo/bar`). Without it, a model could
+// exfiltrate parent-directory files via `cat ../secrets` and the
+// hook would short-circuit to `allow` because the extractor saw no
+// "absolute" token. The boundary check at the call site resolves
+// non-absolute extracted tokens against `root`, so `../secrets`
+// becomes `<parent-of-workspace>/secrets` which the boundary then
+// correctly flags as outside. Codex P2 #35.
+const PATH_TOKEN = /(?:^|[\s=])(?:--[^\s=]+=)?["']?(\/[^\s'"|;&<>()`]+|~\/[^\s'"|;&<>()`]+|\$\{?HOME\}?\/[^\s'"|;&<>()`]+|\.\.(?:\/[^\s'"|;&<>()`]*)?)["']?/g;
+// Back-compat alias kept for any downstream import.
+const ABSOLUTE_PATH_TOKEN = PATH_TOKEN;
+function expandHomeRelative(token) {
+    // Expand ~/foo and $HOME/foo and ${HOME}/foo to absolute. The
+    // workspace boundary check resolves non-absolute paths against the
+    // workspace root, which would silently treat `~/secret` as
+    // `<workspace>/~/secret` — exactly the bypass the codex flagged.
+    const home = os.homedir();
+    if (token.startsWith('~/'))
+        return `${home}/${token.slice(2)}`;
+    if (token.startsWith('${HOME}/'))
+        return `${home}/${token.slice(8)}`;
+    if (token.startsWith('$HOME/'))
+        return `${home}/${token.slice(6)}`;
+    return token;
+}
+function extractCompileCheckPaths(input) {
+    const command = typeof input.command === 'string' ? input.command : '';
+    if (command === '')
+        return [];
+    const out = [];
+    for (const match of command.matchAll(ABSOLUTE_PATH_TOKEN)) {
+        out.push(expandHomeRelative(match[1]));
+    }
+    return out;
+}
+const DEFAULT_EXTRACTORS = {
+    [_enum.Constants.READ_FILE]: (i) => typeof i.file_path === 'string' ? [i.file_path] : [],
+    [_enum.Constants.WRITE_FILE]: (i) => typeof i.file_path === 'string' ? [i.file_path] : [],
+    [_enum.Constants.EDIT_FILE]: (i) => typeof i.file_path === 'string' ? [i.file_path] : [],
+    [_enum.Constants.GREP_SEARCH]: (i) => typeof i.path === 'string' && i.path !== '' ? [i.path] : [],
+    [_enum.Constants.GLOB_SEARCH]: (i) => typeof i.path === 'string' && i.path !== '' ? [i.path] : [],
+    [_enum.Constants.LIST_DIRECTORY]: (i) => typeof i.path === 'string' && i.path !== '' ? [i.path] : [],
+    [_enum.Constants.COMPILE_CHECK]: extractCompileCheckPaths,
+};
+function isInsideAnyRoot(absolutePath, roots) {
+    for (const root of roots) {
+        if (absolutePath === root)
+            return true;
+        const rel = path.relative(root, absolutePath);
+        if (!rel.startsWith('..') && !path.isAbsolute(rel))
+            return true;
+    }
+    return false;
+}
+/**
+ * Symlink-aware variant: realpaths the candidate AND the roots before
+ * comparing. Without this, a symlink inside the workspace pointing
+ * outside (e.g. `workspace/link → /etc/passwd`) compares as
+ * "in-workspace" lexically, but actually grants the agent reach
+ * outside the boundary. Critical when this hook is the primary gate
+ * (i.e. the host opted into `workspace.allowReadOutside: true` /
+ * `allowWriteOutside: true` so the file tools' own clamp is off).
+ *
+ * Handles paths that don't yet exist (e.g. `write_file` to a brand
+ * new path) by walking up to the nearest existing ancestor and
+ * realpathing that, then re-attaching the unresolved suffix. Mirrors
+ * `resolveWorkspacePathSafe`'s approach in LocalExecutionEngine.
+ */
+async function realpathOrSelf(absolutePath) {
+    try {
+        return await promises.realpath(absolutePath);
+    }
+    catch {
+        return absolutePath;
+    }
+}
+async function realpathOfPathOrAncestor(absolutePath) {
+    let current = absolutePath;
+    let suffix = '';
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    while (true) {
+        try {
+            const real = await promises.realpath(current);
+            return suffix === '' ? real : path.resolve(real, suffix);
+        }
+        catch {
+            const parent = path.resolve(current, '..');
+            if (parent === current) {
+                return absolutePath;
+            }
+            const base = current.slice(parent.length + 1);
+            suffix = suffix === '' ? base : `${base}/${suffix}`;
+            current = parent;
+        }
+    }
+}
+async function isInsideAnyRootRealpath(absolutePath, realRoots) {
+    const real = await realpathOfPathOrAncestor(absolutePath);
+    return isInsideAnyRoot(real, [...realRoots]);
+}
+function formatReason(template, toolName, outsidePaths) {
+    const fallback = `Tool "${toolName}" wants to touch ${outsidePaths.length} path(s) outside the workspace: ${outsidePaths.join(', ')}`;
+    if (template == null)
+        return fallback;
+    return template
+        .replace(/\{tool\}/g, toolName)
+        .replace(/\{paths\}/g, outsidePaths.join(', '));
+}
+/**
+ * Build a `PreToolUse` callback that enforces the workspace policy.
+ * Register it on a `HookRegistry`:
+ *
+ * ```ts
+ * registry.register('PreToolUse', {
+ *   hooks: [createWorkspacePolicyHook({ root, outsideWrite: 'ask' })],
+ * });
+ * ```
+ *
+ * The hook is composable with `createToolPolicyHook` — register both;
+ * `executeHooks` precedence (`deny > ask > allow`) sorts out which
+ * decision wins per call.
+ */
+function createWorkspacePolicyHook(config) {
+    const root = path.resolve(config.root);
+    // Relative `additionalRoots` entries are anchored to `root` so a
+    // monorepo config like `additionalRoots: ['../shared']` resolves
+    // to a sibling of `root`, not of process.cwd. Matches
+    // `getWorkspaceRoots` in LocalExecutionEngine.
+    const additionalRoots = (config.additionalRoots ?? []).map((p) => path.isAbsolute(p) ? path.resolve(p) : path.resolve(root, p));
+    const allRoots = [root, ...additionalRoots];
+    // Pre-realpath the roots once at construction — these are stable
+    // per Run. The candidate paths get realpath'd lazily inside the
+    // hook callback. Cached so the per-call cost is just one realpath.
+    let realRootsPromise;
+    const getRealRoots = () => {
+        if (realRootsPromise == null) {
+            realRootsPromise = Promise.all(allRoots.map(realpathOrSelf));
+        }
+        return realRootsPromise;
+    };
+    const readPolicy = config.outsideRead ?? 'ask';
+    const writePolicy = config.outsideWrite ?? 'ask';
+    const extractors = {
+        ...DEFAULT_EXTRACTORS,
+        ...(config.pathExtractors ?? {}),
+    };
+    return async (input) => {
+        const extractor = extractors[input.toolName];
+        if (extractor == null)
+            return { decision: 'allow' };
+        const paths = extractor((input.toolInput ?? {}));
+        if (paths.length === 0)
+            return { decision: 'allow' };
+        // Two-stage check:
+        //   1. Lexical fast path — anything that's lexically inside the
+        //      workspace AND doesn't get redirected by realpath stays
+        //      allow-able without paying the realpath cost on every call.
+        //   2. For paths that look outside lexically OR look inside but
+        //      may have been routed through a symlink, realpath both the
+        //      candidate and the roots and compare. This catches the
+        //      `workspace/link → /etc/passwd` escape that lexical-only
+        //      checks miss.
+        const outside = [];
+        const realRoots = await getRealRoots();
+        for (const p of paths) {
+            const abs = path.isAbsolute(p) ? path.resolve(p) : path.resolve(root, p);
+            // Realpath is the source of truth — it catches both the
+            // symlink-escape case (lexically-inside path that resolves
+            // outside) and the alternate-mount case (lexically-outside
+            // path that resolves back inside the workspace). The lexical
+            // check alone gives the wrong answer for either, so we don't
+            // bother computing it.
+            const realInside = await isInsideAnyRootRealpath(abs, realRoots);
+            if (!realInside) {
+                outside.push(p);
+            }
+        }
+        if (outside.length === 0)
+            return { decision: 'allow' };
+        const policy = WRITE_TOOLS.has(input.toolName)
+            ? writePolicy
+            : READ_TOOLS.has(input.toolName)
+                ? readPolicy
+                : writePolicy; // unknown tools — treat as write (stricter)
+        if (policy === 'allow')
+            return { decision: 'allow' };
+        const decision = policy === 'deny' ? 'deny' : 'ask';
+        return {
+            decision,
+            reason: formatReason(config.reason, input.toolName, outside),
+            ...(decision === 'ask'
+                ? { allowedDecisions: ['approve', 'reject'] }
+                : {}),
+        };
+    };
+}
+
+exports.createWorkspacePolicyHook = createWorkspacePolicyHook;
+//# sourceMappingURL=createWorkspacePolicyHook.cjs.map

package/dist/cjs/hooks/createWorkspacePolicyHook.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"createWorkspacePolicyHook.cjs","sources":["../../../src/hooks/createWorkspacePolicyHook.ts"],"sourcesContent":["/**\n * Workspace boundary policy as a `PreToolUse` hook.\n *\n * Local-engine file tools enforce a hard workspace boundary at the\n * tool implementation layer (`resolveWorkspacePathSafe`). This hook\n * adds a complementary, host-controlled layer on top that uses the\n * standard PreToolUse / HITL machinery to *negotiate* access to\n * paths outside the workspace — instead of just throwing.\n *\n * The host opts in by registering this hook on a `HookRegistry`; the\n * hook inspects each tool call's input, extracts the file paths it\n * mentions via per-tool extractors, and returns:\n *\n *   - `allow`               — every path is inside `workspace.root`\n *                              (or `additionalRoots`)\n *   - `deny`                — at least one path is outside, and the\n *                              configured outside-policy is `'deny'`\n *   - `ask`                 — at least one path is outside, and the\n *                              outside-policy is `'ask'` (default).\n *                              When `humanInTheLoop.enabled` is true,\n *                              the existing PreToolUse `'ask'` flow\n *                              raises a tool_approval interrupt the\n *                              host UI can render. When HITL is off,\n *                              `'ask'` collapses to `deny` (matches\n *                              the rest of the SDK's default).\n *\n * Default per-tool path extractors cover the local-engine coding\n * suite (`read_file`, `write_file`, `edit_file`, `grep_search`,\n * `glob_search`, `list_directory`, `compile_check`). The host can\n * override or extend via `pathExtractors`. Bash/code paths are not\n * extracted by default — bash command parsing is its own concern, and\n * the existing `bashAst` validator + sandbox-runtime fs allowlist are\n * the right gates for those.\n *\n * Important: this hook does NOT replace `resolveWorkspacePathSafe`.\n * Even if the hook returns `allow`, the file tool still enforces its\n * own clamp unless `workspace.allowReadOutside` /\n * `workspace.allowWriteOutside` (or the legacy\n * `allowOutsideWorkspace`) is set. The recommended composition for\n * \"ask the user\" semantics is:\n *\n *   workspace: {\n *     root,\n *     allowReadOutside: true,\n *     allowWriteOutside: true,\n *   },\n *   // …with the hook installed and humanInTheLoop.enabled = true.\n */\n\nimport { homedir } from 'os';\nimport { isAbsolute, relative, resolve } from 'path';\nimport { realpath } from 'fs/promises';\nimport { Constants } from '@/common';\nimport type {\n  HookCallback,\n  PreToolUseHookInput,\n  PreToolUseHookOutput,\n  ToolDecision,\n} from './types';\n\n/**\n * What to do when a tool call references a path outside the workspace.\n *\n *   - `'ask'`    : default. Raise a PreToolUse `ask` (host UI prompts\n *                  via the HITL interrupt path).\n *   - `'allow'`  : let the call through (use the existing tool clamp\n *                  to actually enforce — the hook is purely advisory).\n *   - `'deny'`   : block the call with an error ToolMessage.\n */\nexport type OutsideAccessPolicy = 'ask' | 'allow' | 'deny';\n\nexport interface WorkspacePolicyConfig {\n  /** Canonical workspace root. Required. */\n  root: string;\n  /** Sibling roots that count as inside-workspace. */\n  additionalRoots?: readonly string[];\n  /** Policy applied to read-only file tools. Defaults to `'ask'`. */\n  outsideRead?: OutsideAccessPolicy;\n  /** Policy applied to write-shaped file tools. Defaults to `'ask'`. */\n  outsideWrite?: OutsideAccessPolicy;\n  /**\n   * Optional reason template surfaced in the `ask`/`deny` decision.\n   * Supports `{tool}` and `{paths}` substitution.\n   */\n  reason?: string;\n  /**\n   * Per-tool path extractors. Defaults cover the local-engine coding\n   * suite. Returning an empty array opts that tool out of policy.\n   */\n  pathExtractors?: Record<string, PathExtractor>;\n}\n\nexport type PathExtractor = (\n  toolInput: Record<string, unknown>\n) => readonly string[];\n\nconst READ_TOOLS = new Set<string>([\n  Constants.READ_FILE,\n  Constants.GREP_SEARCH,\n  Constants.GLOB_SEARCH,\n  Constants.LIST_DIRECTORY,\n  Constants.COMPILE_CHECK,\n]);\n\nconst WRITE_TOOLS = new Set<string>([\n  Constants.WRITE_FILE,\n  Constants.EDIT_FILE,\n]);\n\n/**\n * Best-effort extractor for `compile_check` — pulls absolute and `~/`\n * path tokens out of the `command` string so the workspace boundary\n * sees them. Without this, a model could ship `command: 'cat\n * /etc/passwd'` and the policy hook would short-circuit to `allow`\n * (Codex P1 #26 — the prior `() => []` made the hook a no-op for\n * compile_check). Conservative by design:\n *\n *   - Matches `/foo`, `~/foo`, `$HOME/foo`, `${HOME}/foo` followed by\n *     non-shell-special chars. Stops at whitespace, quotes, redirect\n *     operators, pipes, semicolons.\n *   - Strips a leading `--flag=` so `--out=/etc/foo` extracts as\n *     `/etc/foo` (the path the agent's actually trying to write).\n *   - Misses relative paths (intended — those resolve under cwd\n *     anyway), and shell-substituted paths whose final form isn't\n *     visible at extract time. Hosts that need bulletproof gating\n *     should pair this with a `bash_tool`-level policy.\n */\n// `[\"']?` slots before AND after the captured path cover quoted\n// forms like `cat \"/etc/passwd\"` and `--out='/tmp/x'`. Codex P1 #31\n// — the previous regex only matched unquoted tokens, so a model\n// could trivially bypass the workspace policy by quoting any\n// destination path. The path content character class still excludes\n// quotes/whitespace/shell-specials so we don't over-extract; that's\n// the defensive trade we want for fallback-grep style matching.\n//\n// The `\\.\\.(?:\\/[^…]*)?` alternation covers parent-traversal forms\n// (`..`, `../secrets.txt`, `../foo/bar`). Without it, a model could\n// exfiltrate parent-directory files via `cat ../secrets` and the\n// hook would short-circuit to `allow` because the extractor saw no\n// \"absolute\" token. The boundary check at the call site resolves\n// non-absolute extracted tokens against `root`, so `../secrets`\n// becomes `<parent-of-workspace>/secrets` which the boundary then\n// correctly flags as outside. Codex P2 #35.\nconst PATH_TOKEN =\n  /(?:^|[\\s=])(?:--[^\\s=]+=)?[\"']?(\\/[^\\s'\"|;&<>()`]+|~\\/[^\\s'\"|;&<>()`]+|\\$\\{?HOME\\}?\\/[^\\s'\"|;&<>()`]+|\\.\\.(?:\\/[^\\s'\"|;&<>()`]*)?)[\"']?/g;\n// Back-compat alias kept for any downstream import.\nconst ABSOLUTE_PATH_TOKEN = PATH_TOKEN;\nfunction expandHomeRelative(token: string): string {\n  // Expand ~/foo and $HOME/foo and ${HOME}/foo to absolute. The\n  // workspace boundary check resolves non-absolute paths against the\n  // workspace root, which would silently treat `~/secret` as\n  // `<workspace>/~/secret` — exactly the bypass the codex flagged.\n  const home = homedir();\n  if (token.startsWith('~/')) return `${home}/${token.slice(2)}`;\n  if (token.startsWith('${HOME}/')) return `${home}/${token.slice(8)}`;\n  if (token.startsWith('$HOME/')) return `${home}/${token.slice(6)}`;\n  return token;\n}\nfunction extractCompileCheckPaths(input: Record<string, unknown>): string[] {\n  const command = typeof input.command === 'string' ? input.command : '';\n  if (command === '') return [];\n  const out: string[] = [];\n  for (const match of command.matchAll(ABSOLUTE_PATH_TOKEN)) {\n    out.push(expandHomeRelative(match[1]));\n  }\n  return out;\n}\n\nconst DEFAULT_EXTRACTORS: Record<string, PathExtractor> = {\n  [Constants.READ_FILE]: (i) =>\n    typeof i.file_path === 'string' ? [i.file_path] : [],\n  [Constants.WRITE_FILE]: (i) =>\n    typeof i.file_path === 'string' ? [i.file_path] : [],\n  [Constants.EDIT_FILE]: (i) =>\n    typeof i.file_path === 'string' ? [i.file_path] : [],\n  [Constants.GREP_SEARCH]: (i) =>\n    typeof i.path === 'string' && i.path !== '' ? [i.path] : [],\n  [Constants.GLOB_SEARCH]: (i) =>\n    typeof i.path === 'string' && i.path !== '' ? [i.path] : [],\n  [Constants.LIST_DIRECTORY]: (i) =>\n    typeof i.path === 'string' && i.path !== '' ? [i.path] : [],\n  [Constants.COMPILE_CHECK]: extractCompileCheckPaths,\n};\n\nfunction isInsideAnyRoot(absolutePath: string, roots: string[]): boolean {\n  for (const root of roots) {\n    if (absolutePath === root) return true;\n    const rel = relative(root, absolutePath);\n    if (!rel.startsWith('..') && !isAbsolute(rel)) return true;\n  }\n  return false;\n}\n\n/**\n * Symlink-aware variant: realpaths the candidate AND the roots before\n * comparing. Without this, a symlink inside the workspace pointing\n * outside (e.g. `workspace/link → /etc/passwd`) compares as\n * \"in-workspace\" lexically, but actually grants the agent reach\n * outside the boundary. Critical when this hook is the primary gate\n * (i.e. the host opted into `workspace.allowReadOutside: true` /\n * `allowWriteOutside: true` so the file tools' own clamp is off).\n *\n * Handles paths that don't yet exist (e.g. `write_file` to a brand\n * new path) by walking up to the nearest existing ancestor and\n * realpathing that, then re-attaching the unresolved suffix. Mirrors\n * `resolveWorkspacePathSafe`'s approach in LocalExecutionEngine.\n */\nasync function realpathOrSelf(absolutePath: string): Promise<string> {\n  try {\n    return await realpath(absolutePath);\n  } catch {\n    return absolutePath;\n  }\n}\n\nasync function realpathOfPathOrAncestor(\n  absolutePath: string\n): Promise<string> {\n  let current = absolutePath;\n  let suffix = '';\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  while (true) {\n    try {\n      const real = await realpath(current);\n      return suffix === '' ? real : resolve(real, suffix);\n    } catch {\n      const parent = resolve(current, '..');\n      if (parent === current) {\n        return absolutePath;\n      }\n      const base = current.slice(parent.length + 1);\n      suffix = suffix === '' ? base : `${base}/${suffix}`;\n      current = parent;\n    }\n  }\n}\n\nasync function isInsideAnyRootRealpath(\n  absolutePath: string,\n  realRoots: readonly string[]\n): Promise<boolean> {\n  const real = await realpathOfPathOrAncestor(absolutePath);\n  return isInsideAnyRoot(real, [...realRoots]);\n}\n\nfunction formatReason(\n  template: string | undefined,\n  toolName: string,\n  outsidePaths: readonly string[]\n): string {\n  const fallback = `Tool \"${toolName}\" wants to touch ${outsidePaths.length} path(s) outside the workspace: ${outsidePaths.join(', ')}`;\n  if (template == null) return fallback;\n  return template\n    .replace(/\\{tool\\}/g, toolName)\n    .replace(/\\{paths\\}/g, outsidePaths.join(', '));\n}\n\n/**\n * Build a `PreToolUse` callback that enforces the workspace policy.\n * Register it on a `HookRegistry`:\n *\n * ```ts\n * registry.register('PreToolUse', {\n *   hooks: [createWorkspacePolicyHook({ root, outsideWrite: 'ask' })],\n * });\n * ```\n *\n * The hook is composable with `createToolPolicyHook` — register both;\n * `executeHooks` precedence (`deny > ask > allow`) sorts out which\n * decision wins per call.\n */\nexport function createWorkspacePolicyHook(\n  config: WorkspacePolicyConfig\n): HookCallback<'PreToolUse'> {\n  const root = resolve(config.root);\n  // Relative `additionalRoots` entries are anchored to `root` so a\n  // monorepo config like `additionalRoots: ['../shared']` resolves\n  // to a sibling of `root`, not of process.cwd. Matches\n  // `getWorkspaceRoots` in LocalExecutionEngine.\n  const additionalRoots = (config.additionalRoots ?? []).map((p) =>\n    isAbsolute(p) ? resolve(p) : resolve(root, p)\n  );\n  const allRoots = [root, ...additionalRoots];\n\n  // Pre-realpath the roots once at construction — these are stable\n  // per Run. The candidate paths get realpath'd lazily inside the\n  // hook callback. Cached so the per-call cost is just one realpath.\n  let realRootsPromise: Promise<string[]> | undefined;\n  const getRealRoots = (): Promise<string[]> => {\n    if (realRootsPromise == null) {\n      realRootsPromise = Promise.all(allRoots.map(realpathOrSelf));\n    }\n    return realRootsPromise;\n  };\n\n  const readPolicy: OutsideAccessPolicy = config.outsideRead ?? 'ask';\n  const writePolicy: OutsideAccessPolicy = config.outsideWrite ?? 'ask';\n\n  const extractors: Record<string, PathExtractor> = {\n    ...DEFAULT_EXTRACTORS,\n    ...(config.pathExtractors ?? {}),\n  };\n\n  return async (input: PreToolUseHookInput): Promise<PreToolUseHookOutput> => {\n    const extractor = extractors[input.toolName];\n    if (extractor == null) return { decision: 'allow' };\n\n    const paths = extractor(\n      (input.toolInput ?? {}) as Record<string, unknown>\n    );\n    if (paths.length === 0) return { decision: 'allow' };\n\n    // Two-stage check:\n    //   1. Lexical fast path — anything that's lexically inside the\n    //      workspace AND doesn't get redirected by realpath stays\n    //      allow-able without paying the realpath cost on every call.\n    //   2. For paths that look outside lexically OR look inside but\n    //      may have been routed through a symlink, realpath both the\n    //      candidate and the roots and compare. This catches the\n    //      `workspace/link → /etc/passwd` escape that lexical-only\n    //      checks miss.\n    const outside: string[] = [];\n    const realRoots = await getRealRoots();\n    for (const p of paths) {\n      const abs = isAbsolute(p) ? resolve(p) : resolve(root, p);\n      // Realpath is the source of truth — it catches both the\n      // symlink-escape case (lexically-inside path that resolves\n      // outside) and the alternate-mount case (lexically-outside\n      // path that resolves back inside the workspace). The lexical\n      // check alone gives the wrong answer for either, so we don't\n      // bother computing it.\n      const realInside = await isInsideAnyRootRealpath(abs, realRoots);\n      if (!realInside) {\n        outside.push(p);\n      }\n    }\n    if (outside.length === 0) return { decision: 'allow' };\n\n    const policy = WRITE_TOOLS.has(input.toolName)\n      ? writePolicy\n      : READ_TOOLS.has(input.toolName)\n        ? readPolicy\n        : writePolicy; // unknown tools — treat as write (stricter)\n    if (policy === 'allow') return { decision: 'allow' };\n\n    const decision: ToolDecision = policy === 'deny' ? 'deny' : 'ask';\n    return {\n      decision,\n      reason: formatReason(config.reason, input.toolName, outside),\n      ...(decision === 'ask'\n        ? { allowedDecisions: ['approve', 'reject'] as const }\n        : {}),\n    };\n  };\n}\n"],"names":["Constants","homedir","relative","isAbsolute","realpath","resolve"],"mappings":"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"}

package/dist/cjs/main.cjs

@@ -9,11 +9,13 @@ var ids = require('./messages/ids.cjs');
 var prune = require('./messages/prune.cjs');
 var format = require('./messages/format.cjs');
 var cache = require('./messages/cache.cjs');
+var anthropicToolCache = require('./messages/anthropicToolCache.cjs');
 var content = require('./messages/content.cjs');
 var tools$1 = require('./messages/tools.cjs');
 var contextPruning = require('./messages/contextPruning.cjs');
 var contextPruningSettings = require('./messages/contextPruningSettings.cjs');
 var reducer = require('./messages/reducer.cjs');
+var recency = require('./messages/recency.cjs');
 var Graph = require('./graphs/Graph.cjs');
 var MultiAgentGraph = require('./graphs/MultiAgentGraph.cjs');
 var index$2 = require('./summarization/index.cjs');
@@ -31,6 +33,18 @@ var ToolSearch = require('./tools/ToolSearch.cjs');
 var ToolNode = require('./tools/ToolNode.cjs');
 var schema$1 = require('./tools/schema.cjs');
 var handlers$1 = require('./tools/handlers.cjs');
+var CompileCheckTool = require('./tools/local/CompileCheckTool.cjs');
+var FileCheckpointer = require('./tools/local/FileCheckpointer.cjs');
+var LocalCodingTools = require('./tools/local/LocalCodingTools.cjs');
+var LocalExecutionEngine = require('./tools/local/LocalExecutionEngine.cjs');
+var LocalExecutionTools = require('./tools/local/LocalExecutionTools.cjs');
+var LocalProgrammaticToolCalling = require('./tools/local/LocalProgrammaticToolCalling.cjs');
+var resolveLocalExecutionTools = require('./tools/local/resolveLocalExecutionTools.cjs');
+var attachments = require('./tools/local/attachments.cjs');
+var bashAst = require('./tools/local/bashAst.cjs');
+var editStrategies = require('./tools/local/editStrategies.cjs');
+var syntaxCheck = require('./tools/local/syntaxCheck.cjs');
+var textEncoding = require('./tools/local/textEncoding.cjs');
 var tool = require('./tools/search/tool.cjs');
 var schema = require('./tools/search/schema.cjs');
 var constants = require('./common/constants.cjs');
@@ -48,6 +62,7 @@ var HookRegistry = require('./hooks/HookRegistry.cjs');
 var executeHooks = require('./hooks/executeHooks.cjs');
 var matchers = require('./hooks/matchers.cjs');
 var createToolPolicyHook = require('./hooks/createToolPolicyHook.cjs');
+var createWorkspacePolicyHook = require('./hooks/createWorkspacePolicyHook.cjs');
 var types = require('./hooks/types.cjs');
 var askUserQuestion = require('./hitl/askUserQuestion.cjs');
 var messages = require('@langchain/core/messages');
@@ -87,9 +102,11 @@ exports.getConverseOverrideMessage = core.getConverseOverrideMessage;
 exports.modifyDeltaProperties = core.modifyDeltaProperties;
 exports.getMessageId = ids.getMessageId;
 exports.DEFAULT_RESERVE_RATIO = prune.DEFAULT_RESERVE_RATIO;
+exports.ORIGINAL_CONTENT_MAX_CHARS = prune.ORIGINAL_CONTENT_MAX_CHARS;
 exports.calculateTotalTokens = prune.calculateTotalTokens;
 exports.checkValidNumber = prune.checkValidNumber;
 exports.createPruneMessages = prune.createPruneMessages;
+exports.enforceOriginalContentCap = prune.enforceOriginalContentCap;
 exports.getMessagesWithinTokenLimit = prune.getMessagesWithinTokenLimit;
 exports.maskConsumedToolResults = prune.maskConsumedToolResults;
 exports.preFlightTruncateToolCallInputs = prune.preFlightTruncateToolCallInputs;
@@ -108,6 +125,8 @@ exports.addBedrockCacheControl = cache.addBedrockCacheControl;
 exports.addCacheControl = cache.addCacheControl;
 exports.stripAnthropicCacheControl = cache.stripAnthropicCacheControl;
 exports.stripBedrockCacheControl = cache.stripBedrockCacheControl;
+exports.makeIsDeferred = anthropicToolCache.makeIsDeferred;
+exports.partitionAndMarkAnthropicToolCache = anthropicToolCache.partitionAndMarkAnthropicToolCache;
 exports.formatContentStrings = content.formatContentStrings;
 exports.extractToolDiscoveries = tools$1.extractToolDiscoveries;
 exports.hasToolSearchInCurrentTurn = tools$1.hasToolSearchInCurrentTurn;
@@ -117,6 +136,7 @@ exports.resolveContextPruningSettings = contextPruningSettings.resolveContextPru
 exports.REMOVE_ALL_MESSAGES = reducer.REMOVE_ALL_MESSAGES;
 exports.createRemoveAllMessage = reducer.createRemoveAllMessage;
 exports.messagesStateReducer = reducer.messagesStateReducer;
+exports.splitAtRecencyBoundary = recency.splitAtRecencyBoundary;
 exports.Graph = Graph.Graph;
 exports.StandardGraph = Graph.StandardGraph;
 exports.MultiAgentGraph = MultiAgentGraph.MultiAgentGraph;
@@ -210,6 +230,73 @@ exports.handleServerToolResult = handlers$1.handleServerToolResult;
 exports.handleToolCallChunks = handlers$1.handleToolCallChunks;
 exports.handleToolCalls = handlers$1.handleToolCalls;
 exports.toolResultTypes = handlers$1.toolResultTypes;
+exports.CompileCheckToolName = CompileCheckTool.CompileCheckToolName;
+exports.createCompileCheckTool = CompileCheckTool.createCompileCheckTool;
+exports.createCompileCheckToolDefinition = CompileCheckTool.createCompileCheckToolDefinition;
+exports.LocalFileCheckpointerImpl = FileCheckpointer.LocalFileCheckpointerImpl;
+exports.createLocalFileCheckpointer = FileCheckpointer.createLocalFileCheckpointer;
+exports.LocalEditFileToolName = LocalCodingTools.LocalEditFileToolName;
+exports.LocalEditFileToolSchema = LocalCodingTools.LocalEditFileToolSchema;
+exports.LocalGlobSearchToolName = LocalCodingTools.LocalGlobSearchToolName;
+exports.LocalGlobSearchToolSchema = LocalCodingTools.LocalGlobSearchToolSchema;
+exports.LocalGrepSearchToolName = LocalCodingTools.LocalGrepSearchToolName;
+exports.LocalGrepSearchToolSchema = LocalCodingTools.LocalGrepSearchToolSchema;
+exports.LocalListDirectoryToolName = LocalCodingTools.LocalListDirectoryToolName;
+exports.LocalListDirectoryToolSchema = LocalCodingTools.LocalListDirectoryToolSchema;
+exports.LocalReadFileToolSchema = LocalCodingTools.LocalReadFileToolSchema;
+exports.LocalWriteFileToolName = LocalCodingTools.LocalWriteFileToolName;
+exports.LocalWriteFileToolSchema = LocalCodingTools.LocalWriteFileToolSchema;
+exports._resetRipgrepCacheForTests = LocalCodingTools._resetRipgrepCacheForTests;
+exports.createLocalCodingToolBundle = LocalCodingTools.createLocalCodingToolBundle;
+exports.createLocalCodingToolDefinitions = LocalCodingTools.createLocalCodingToolDefinitions;
+exports.createLocalCodingToolRegistry = LocalCodingTools.createLocalCodingToolRegistry;
+exports.createLocalCodingTools = LocalCodingTools.createLocalCodingTools;
+exports.createLocalEditFileTool = LocalCodingTools.createLocalEditFileTool;
+exports.createLocalGlobSearchTool = LocalCodingTools.createLocalGlobSearchTool;
+exports.createLocalGrepSearchTool = LocalCodingTools.createLocalGrepSearchTool;
+exports.createLocalListDirectoryTool = LocalCodingTools.createLocalListDirectoryTool;
+exports.createLocalReadFileTool = LocalCodingTools.createLocalReadFileTool;
+exports.createLocalWriteFileTool = LocalCodingTools.createLocalWriteFileTool;
+exports._resetLocalEngineWarningsForTests = LocalExecutionEngine._resetLocalEngineWarningsForTests;
+exports.buildSandboxRuntimeConfig = LocalExecutionEngine.buildSandboxRuntimeConfig;
+exports.executeLocalBash = LocalExecutionEngine.executeLocalBash;
+exports.executeLocalBashWithArgs = LocalExecutionEngine.executeLocalBashWithArgs;
+exports.executeLocalCode = LocalExecutionEngine.executeLocalCode;
+exports.getLocalCwd = LocalExecutionEngine.getLocalCwd;
+exports.getLocalSessionId = LocalExecutionEngine.getLocalSessionId;
+exports.getReadRoots = LocalExecutionEngine.getReadRoots;
+exports.getSpawn = LocalExecutionEngine.getSpawn;
+exports.getWorkspaceFS = LocalExecutionEngine.getWorkspaceFS;
+exports.getWorkspaceRoots = LocalExecutionEngine.getWorkspaceRoots;
+exports.getWriteRoots = LocalExecutionEngine.getWriteRoots;
+exports.resolveLocalExecutionConfig = LocalExecutionEngine.resolveLocalExecutionConfig;
+exports.resolveWorkspacePath = LocalExecutionEngine.resolveWorkspacePath;
+exports.resolveWorkspacePathSafe = LocalExecutionEngine.resolveWorkspacePathSafe;
+exports.shellQuote = LocalExecutionEngine.shellQuote;
+exports.spawnLocalProcess = LocalExecutionEngine.spawnLocalProcess;
+exports.truncateLocalOutput = LocalExecutionEngine.truncateLocalOutput;
+exports.validateBashCommand = LocalExecutionEngine.validateBashCommand;
+exports.LocalBashExecutionToolDescription = LocalExecutionTools.LocalBashExecutionToolDescription;
+exports.LocalCodeExecutionToolDescription = LocalExecutionTools.LocalCodeExecutionToolDescription;
+exports.createLocalBashExecutionTool = LocalExecutionTools.createLocalBashExecutionTool;
+exports.createLocalCodeExecutionTool = LocalExecutionTools.createLocalCodeExecutionTool;
+exports._createBashProgramForTests = LocalProgrammaticToolCalling._createBashProgramForTests;
+exports.applyPreToolUseHooksForBridge = LocalProgrammaticToolCalling.applyPreToolUseHooksForBridge;
+exports.createLocalBashProgrammaticToolCallingTool = LocalProgrammaticToolCalling.createLocalBashProgrammaticToolCallingTool;
+exports.createLocalProgrammaticToolCallingTool = LocalProgrammaticToolCalling.createLocalProgrammaticToolCallingTool;
+exports.resolveLocalExecutionTools = resolveLocalExecutionTools.resolveLocalExecutionTools;
+exports.resolveLocalToolRegistry = resolveLocalExecutionTools.resolveLocalToolRegistry;
+exports.resolveLocalToolsForBinding = resolveLocalExecutionTools.resolveLocalToolsForBinding;
+exports.classifyAttachment = attachments.classifyAttachment;
+exports.imageAttachmentContent = attachments.imageAttachmentContent;
+exports.bashAstFindingsToErrors = bashAst.bashAstFindingsToErrors;
+exports.runBashAstChecks = bashAst.runBashAstChecks;
+exports.applyEdit = editStrategies.applyEdit;
+exports.locateEdit = editStrategies.locateEdit;
+exports._resetSyntaxCheckProbeCacheForTests = syntaxCheck._resetSyntaxCheckProbeCacheForTests;
+exports.runPostEditSyntaxCheck = syntaxCheck.runPostEditSyntaxCheck;
+exports.decodeFile = textEncoding.decodeFile;
+exports.encodeFile = textEncoding.encodeFile;
 exports.createSearchTool = tool.createSearchTool;
 Object.defineProperty(exports, "DATE_RANGE", {
 	enumerable: true,
@@ -262,6 +349,8 @@ Object.defineProperty(exports, "GraphNodeKeys", {
 	enumerable: true,
 	get: function () { return _enum.GraphNodeKeys; }
 });
+exports.LOCAL_CODING_BUNDLE_NAMES = _enum.LOCAL_CODING_BUNDLE_NAMES;
+exports.LOCAL_CODING_TOOL_NAMES = _enum.LOCAL_CODING_TOOL_NAMES;
 Object.defineProperty(exports, "Providers", {
 	enumerable: true,
 	get: function () { return _enum.Providers; }
@@ -314,6 +403,7 @@ exports.MAX_PATTERN_LENGTH = matchers.MAX_PATTERN_LENGTH;
 exports.hasNestedQuantifier = matchers.hasNestedQuantifier;
 exports.matchesQuery = matchers.matchesQuery;
 exports.createToolPolicyHook = createToolPolicyHook.createToolPolicyHook;
+exports.createWorkspacePolicyHook = createWorkspacePolicyHook.createWorkspacePolicyHook;
 exports.HOOK_EVENTS = types.HOOK_EVENTS;
 exports.askUserQuestion = askUserQuestion.askUserQuestion;
 Object.defineProperty(exports, "AIMessage", {

package/dist/cjs/main.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"main.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"main.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/messages/anthropicToolCache.cjs

@@ -0,0 +1,102 @@
+'use strict';
+
+/**
+ * Anthropic prompt-caching helper for the `tools[]` request field.
+ *
+ * Anthropic accepts `cache_control: { type: 'ephemeral' }` on individual
+ * tool definitions. Whichever tool carries the marker becomes the end of
+ * a cached prefix: `tools[0..N]` (everything up to and including the
+ * marked tool) is cached and rebated on subsequent matching requests.
+ *
+ * For agents that mix static and deferred (lazily-discovered) tools, the
+ * winning configuration is:
+ *
+ *   1. Stable-partition tools so all *static* (non-deferred) tools come
+ *      first and discovered-deferred tools come last.
+ *   2. Stamp `cache_control` on the LAST static tool.
+ *
+ * That way, the cached prefix covers exactly the static tool inventory.
+ * Discovered tools that show up later (or vary turn-to-turn as new ones
+ * get discovered) never invalidate the prefix because they sit *after*
+ * the breakpoint.
+ *
+ * LangChain's Anthropic adapter passes the marker through via
+ * `tool.extras.cache_control` (`AnthropicToolExtrasSchema`), so we set
+ * it as an `extras` field on a fresh wrapper around the tool — never
+ * mutating the original tool instance, since callers may share them
+ * across runs.
+ */
+/**
+ * Returns a callable that reports whether a given tool *name* is deferred
+ * according to the supplied registry of tool definitions. Tools without
+ * a registry entry are treated as non-deferred (i.e. static), matching
+ * the host-supplied `graphTools` semantics elsewhere in the SDK.
+ */
+function makeIsDeferred(toolDefinitions) {
+    if (toolDefinitions == null || toolDefinitions.length === 0) {
+        return () => false;
+    }
+    const deferred = new Set();
+    for (const def of toolDefinitions) {
+        if (def.defer_loading === true)
+            deferred.add(def.name);
+    }
+    if (deferred.size === 0)
+        return () => false;
+    return (name) => deferred.has(name);
+}
+/**
+ * Stable-partition `tools` into [static..., deferred...] and stamp the
+ * Anthropic `cache_control: ephemeral` marker on the last static tool.
+ *
+ * If `tools` is undefined or empty, or no entry has a usable `.name`,
+ * returns the input unchanged. If there are no static tools at all,
+ * also returns unchanged (nothing to cache).
+ *
+ * The original tool instances are never mutated. The marked entry is a
+ * shallow wrapper that preserves the prototype chain so downstream
+ * `instanceof` checks still pass. `extras` is merged so any existing
+ * `providerToolDefinition` / other extras the host attached are kept.
+ */
+function partitionAndMarkAnthropicToolCache(tools, isDeferred) {
+    if (tools == null || tools.length === 0)
+        return tools;
+    // Use unknown[] internally to avoid GraphTools' union-array variance
+    // (each member is one of three array types). We cast back to
+    // GraphTools when returning.
+    const staticTools = [];
+    const deferredTools = [];
+    for (const tool of tools) {
+        const name = tool.name;
+        if (typeof name === 'string' && isDeferred(name)) {
+            deferredTools.push(tool);
+        }
+        else {
+            staticTools.push(tool);
+        }
+    }
+    if (staticTools.length === 0) {
+        return tools;
+    }
+    const last = staticTools[staticTools.length - 1];
+    // Already marked? Don't double-clone.
+    if (last.extras != null &&
+        'cache_control' in last.extras &&
+        last.extras.cache_control != null) {
+        if (deferredTools.length === 0)
+            return tools;
+        return [...staticTools, ...deferredTools];
+    }
+    const wrapped = Object.assign(Object.create(Object.getPrototypeOf(last) ?? Object.prototype), last, {
+        extras: {
+            ...(last.extras ?? {}),
+            cache_control: { type: 'ephemeral' },
+        },
+    });
+    staticTools[staticTools.length - 1] = wrapped;
+    return [...staticTools, ...deferredTools];
+}
+
+exports.makeIsDeferred = makeIsDeferred;
+exports.partitionAndMarkAnthropicToolCache = partitionAndMarkAnthropicToolCache;
+//# sourceMappingURL=anthropicToolCache.cjs.map

package/dist/cjs/messages/anthropicToolCache.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropicToolCache.cjs","sources":["../../../src/messages/anthropicToolCache.ts"],"sourcesContent":["/**\n * Anthropic prompt-caching helper for the `tools[]` request field.\n *\n * Anthropic accepts `cache_control: { type: 'ephemeral' }` on individual\n * tool definitions. Whichever tool carries the marker becomes the end of\n * a cached prefix: `tools[0..N]` (everything up to and including the\n * marked tool) is cached and rebated on subsequent matching requests.\n *\n * For agents that mix static and deferred (lazily-discovered) tools, the\n * winning configuration is:\n *\n *   1. Stable-partition tools so all *static* (non-deferred) tools come\n *      first and discovered-deferred tools come last.\n *   2. Stamp `cache_control` on the LAST static tool.\n *\n * That way, the cached prefix covers exactly the static tool inventory.\n * Discovered tools that show up later (or vary turn-to-turn as new ones\n * get discovered) never invalidate the prefix because they sit *after*\n * the breakpoint.\n *\n * LangChain's Anthropic adapter passes the marker through via\n * `tool.extras.cache_control` (`AnthropicToolExtrasSchema`), so we set\n * it as an `extras` field on a fresh wrapper around the tool — never\n * mutating the original tool instance, since callers may share them\n * across runs.\n */\n\nimport type { GraphTools } from '@/types';\n\n/**\n * Returns a callable that reports whether a given tool *name* is deferred\n * according to the supplied registry of tool definitions. Tools without\n * a registry entry are treated as non-deferred (i.e. static), matching\n * the host-supplied `graphTools` semantics elsewhere in the SDK.\n */\nexport function makeIsDeferred(\n  toolDefinitions:\n    | ReadonlyArray<{ name: string; defer_loading?: boolean }>\n    | undefined\n): (toolName: string) => boolean {\n  if (toolDefinitions == null || toolDefinitions.length === 0) {\n    return () => false;\n  }\n  const deferred = new Set<string>();\n  for (const def of toolDefinitions) {\n    if (def.defer_loading === true) deferred.add(def.name);\n  }\n  if (deferred.size === 0) return () => false;\n  return (name) => deferred.has(name);\n}\n\n/**\n * Stable-partition `tools` into [static..., deferred...] and stamp the\n * Anthropic `cache_control: ephemeral` marker on the last static tool.\n *\n * If `tools` is undefined or empty, or no entry has a usable `.name`,\n * returns the input unchanged. If there are no static tools at all,\n * also returns unchanged (nothing to cache).\n *\n * The original tool instances are never mutated. The marked entry is a\n * shallow wrapper that preserves the prototype chain so downstream\n * `instanceof` checks still pass. `extras` is merged so any existing\n * `providerToolDefinition` / other extras the host attached are kept.\n */\nexport function partitionAndMarkAnthropicToolCache(\n  tools: GraphTools | undefined,\n  isDeferred: (toolName: string) => boolean\n): GraphTools | undefined {\n  if (tools == null || tools.length === 0) return tools;\n\n  // Use unknown[] internally to avoid GraphTools' union-array variance\n  // (each member is one of three array types). We cast back to\n  // GraphTools when returning.\n  const staticTools: unknown[] = [];\n  const deferredTools: unknown[] = [];\n\n  for (const tool of tools) {\n    const name = (tool as { name?: unknown }).name;\n    if (typeof name === 'string' && isDeferred(name)) {\n      deferredTools.push(tool);\n    } else {\n      staticTools.push(tool);\n    }\n  }\n\n  if (staticTools.length === 0) {\n    return tools;\n  }\n\n  const last = staticTools[staticTools.length - 1] as {\n    extras?: Record<string, unknown>;\n  };\n  // Already marked? Don't double-clone.\n  if (\n    last.extras != null &&\n    'cache_control' in last.extras &&\n    (last.extras as { cache_control?: unknown }).cache_control != null\n  ) {\n    if (deferredTools.length === 0) return tools;\n    return [...staticTools, ...deferredTools] as GraphTools;\n  }\n\n  const wrapped = Object.assign(\n    Object.create(Object.getPrototypeOf(last) ?? Object.prototype),\n    last,\n    {\n      extras: {\n        ...((last.extras as Record<string, unknown> | undefined) ?? {}),\n        cache_control: { type: 'ephemeral' as const },\n      },\n    }\n  );\n\n  staticTools[staticTools.length - 1] = wrapped;\n  return [...staticTools, ...deferredTools] as GraphTools;\n}\n"],"names":[],"mappings":";;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;AAyBG;AAIH;;;;;AAKG;AACG,SAAU,cAAc,CAC5B,eAEa,EAAA;IAEb,IAAI,eAAe,IAAI,IAAI,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE;AAC3D,QAAA,OAAO,MAAM,KAAK;IACpB;AACA,IAAA,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU;AAClC,IAAA,KAAK,MAAM,GAAG,IAAI,eAAe,EAAE;AACjC,QAAA,IAAI,GAAG,CAAC,aAAa,KAAK,IAAI;AAAE,YAAA,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC;IACxD;AACA,IAAA,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC;AAAE,QAAA,OAAO,MAAM,KAAK;IAC3C,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;AACrC;AAEA;;;;;;;;;;;;AAYG;AACG,SAAU,kCAAkC,CAChD,KAA6B,EAC7B,UAAyC,EAAA;IAEzC,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;AAAE,QAAA,OAAO,KAAK;;;;IAKrD,MAAM,WAAW,GAAc,EAAE;IACjC,MAAM,aAAa,GAAc,EAAE;AAEnC,IAAA,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE;AACxB,QAAA,MAAM,IAAI,GAAI,IAA2B,CAAC,IAAI;QAC9C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE;AAChD,YAAA,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC;QAC1B;aAAO;AACL,YAAA,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;QACxB;IACF;AAEA,IAAA,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE;AAC5B,QAAA,OAAO,KAAK;IACd;IAEA,MAAM,IAAI,GAAG,WAAW,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAE9C;;AAED,IAAA,IACE,IAAI,CAAC,MAAM,IAAI,IAAI;QACnB,eAAe,IAAI,IAAI,CAAC,MAAM;AAC7B,QAAA,IAAI,CAAC,MAAsC,CAAC,aAAa,IAAI,IAAI,EAClE;AACA,QAAA,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC;AAAE,YAAA,OAAO,KAAK;AAC5C,QAAA,OAAO,CAAC,GAAG,WAAW,EAAE,GAAG,aAAa,CAAe;IACzD;IAEA,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAC3B,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,SAAS,CAAC,EAC9D,IAAI,EACJ;AACE,QAAA,MAAM,EAAE;AACN,YAAA,IAAK,IAAI,CAAC,MAA8C,IAAI,EAAE,CAAC;AAC/D,YAAA,aAAa,EAAE,EAAE,IAAI,EAAE,WAAoB,EAAE;AAC9C,SAAA;AACF,KAAA,CACF;IAED,WAAW,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,OAAO;AAC7C,IAAA,OAAO,CAAC,GAAG,WAAW,EAAE,GAAG,aAAa,CAAe;AACzD;;;;;"}