@nodetool-ai/agents 0.7.0-rc.23 → 0.8.2

package/dist/codeact/tool-api.d.ts

@@ -0,0 +1,200 @@
+/**
+ * CodeAct tool API — the bridge that exposes an agent toolbelt to sandboxed
+ * JavaScript actions, and the signature rendering that documents it in the
+ * system prompt.
+ *
+ * One host bridge (`__callTool`) serves every tool; a generated guest prelude
+ * builds the belt caller on top of it. Host bridges follow the
+ * js-sandbox never-reject convention: they resolve `{ok, ...}` envelopes and
+ * the guest wrapper re-throws, so the QuickJS host-promise-rejection leak is
+ * never hit.
+ */
+import { type ProcessingContext } from "@nodetool-ai/runtime";
+import type { MessageImageContent, ProviderTool } from "@nodetool-ai/runtime";
+import { Tool } from "../tools/base-tool.js";
+import type { JsonValue } from "../utils/json-parser.js";
+export { TOOLS_PRELUDE } from "./tools-prelude.js";
+/** Tool-call ceiling per code action; a runaway guest loop stops here. */
+export declare const DEFAULT_MAX_TOOL_CALLS_PER_ACTION = 50;
+export interface ToolCallRecord {
+    name: string;
+    args: Record<string, unknown>;
+    /** Synthetic id (`codeact_<n>`) this call runs under. */
+    toolCallId: string;
+}
+/** What a bridged tool handed back, as the UI reports it. */
+export interface ToolResultRecord {
+    name: string;
+    toolCallId: string;
+    /** The tool's return value, or the error text when the call failed. */
+    result: unknown;
+    isError: boolean;
+}
+export interface ToolBridgeOptions {
+    tools: readonly {
+        name: string;
+        needsToolCallId?: boolean;
+    }[];
+    invoke: (name: string, args: Record<string, unknown>, toolCallId: string) => Promise<unknown>;
+    /** Observability hook — fires before each bridged tool executes. */
+    onToolCall?: (record: ToolCallRecord) => void;
+    /** Observability hook — fires with what the call returned. */
+    onToolResult?: (record: ToolResultRecord) => void;
+    maxToolCallsPerAction?: number;
+}
+export interface ToolBridge {
+    /** Globals to merge into the sandbox run (`__callTool`, `__toolNames`). */
+    globals: Record<string, unknown>;
+    /** Calls consumed so far in the current action. Reset per action. */
+    callCount: () => number;
+    resetActionBudget: () => void;
+    /**
+     * Pixels a tool returned during this action, removed from the observation
+     * and waiting to ride the tool result as a provider image message. At most
+     * {@link MAX_ACTION_IMAGES} are kept; `dropped` counts the rest. Draining
+     * clears both.
+     */
+    drainImages: () => {
+        images: MessageImageContent[];
+        dropped: number;
+    };
+    /**
+     * The `generation_id` of every result a bridged call answered with, across
+     * all of the step's actions. A failing step intersects the user's completed
+     * generations with this set so it names its own paid work and not a
+     * sibling step's.
+     */
+    generationIds: () => ReadonlySet<string>;
+}
+/** Force a value through JSON so it marshals cleanly across the WASM boundary. */
+export declare function toTransferable(value: unknown): JsonValue;
+/**
+ * Tool errors and failed edit batches stop dependent guest code. Successful
+ * operations in a partial batch may already be persisted.
+ */
+export declare function extractErrorPayload(result: unknown): string | null;
+/**
+ * Wire name → the capability namespace it is imported from, for the names a
+ * module owns. A session tool (a client `ui_*` schema, an external MCP tool)
+ * owns no module and is left out, which is how the guest's `tools` thrower
+ * tells "import it from here" from "ask searchTools".
+ */
+export declare function toolModuleMap(tools: readonly {
+    name: string;
+}[]): Record<string, string>;
+export declare function buildToolBridge(options: ToolBridgeOptions): ToolBridge;
+/**
+ * Split a toolbelt into the tools also offered top level and the rest.
+ *
+ * Membership is {@link DIRECT_TOOL_NAMES}: the core set that mirrors a Claude
+ * Agent SDK built-in, plus discovery — which providers, models and node types
+ * this install has. Both are shapes a plain tool call fits, so a sandbox round
+ * trip whose only job is to forward one buys nothing.
+ *
+ * `core` is a view, not a removal: the belt keeps every tool, because the
+ * object model (`nodetool.models.pick`, `nodetool.web`, `nodetool.agents`) and
+ * any hand-written fan-out call them from inside an action. What the top-level
+ * offer changes is the *documented* path — the prompt catalog lists them as
+ * direct tools, and the default way to reach one is a tool call.
+ */
+export declare function splitCoreTools(tools: Tool[]): {
+    core: Tool[];
+    belt: Tool[];
+};
+/**
+ * Render core tools as provider tool definitions that execute themselves.
+ *
+ * The result travels as text; pixels a tool returns are handed back as image
+ * content blocks instead, the way the sandbox bridge holds them out of the
+ * observation.
+ */
+export declare function buildCoreProviderTools(options: {
+    tools: Tool[];
+    context: ProcessingContext;
+    onToolCall?: (record: ToolCallRecord) => void;
+}): ProviderTool[];
+/**
+ * Guest-side prelude prepended to every code action. Builds the belt caller
+ * over `__callTool` (via {@link TOOLS_PRELUDE}) and `finish()` over
+ * `__finish`. Hosts without a `__finish` bridge — the Code node — prepend
+ * `TOOLS_PRELUDE` alone. Tool discovery lives on the object model as
+ * `nodetool.searchTools()`, so a session reaches every capability under one
+ * name.
+ */
+export declare const CODEACT_PRELUDE = "\nconst __callBeltTool = (name) => async (args) => {\n  const __r = await __callTool(\n    name,\n    JSON.stringify(args === undefined ? {} : args)\n  );\n  if (!__r || __r.ok !== true) {\n    throw new Error(__r && __r.error ? __r.error : \"tool call failed: \" + name);\n  }\n  return __r.result;\n};\nconst tools = new Proxy({}, {\n  get(target, prop) {\n    // \"then\" is excluded so awaiting or resolving this object cannot mistake\n    // it for a thenable and call the thrower.\n    if (typeof prop !== \"string\" || prop === \"then\") return undefined;\n    return () => {\n      const __module =\n        typeof __toolModules === \"object\" && __toolModules !== null\n          ? __toolModules[prop]\n          : undefined;\n      throw new Error(\n        __module\n          ? 'tools.' + prop + ' is gone. Import it instead: ' +\n            'import { ' + prop + ' } from ' +\n            '\"@nodetool-ai/sandbox-nodetool/' + __module + '\";'\n          : 'tools.' + prop + ' is gone \u2014 every capability is an import now. ' +\n            'nodetool.searchTools(\"' + prop + '\") reports the module to ' +\n            'import it from.'\n      );\n    };\n  }\n});\n\nasync function finish(result) {\n  const __r = await __finish(JSON.stringify(result === undefined ? null : result));\n  if (!__r || __r.ok !== true) {\n    throw new Error(__r && __r.error ? __r.error : \"finish() rejected the result\");\n  }\n  return \"step finished\";\n}\n";
+/**
+ * Every name the guest already has beyond the sandbox manifest's own surface:
+ * the host bridges the executors install as `globals`, the wrappers
+ * {@link CODEACT_PRELUDE} builds over them, and the two optional object-model
+ * preludes. User code cannot rebind these, and prompt text may name them
+ * without the sandbox-manifest drift check calling them undefined.
+ */
+export declare const CODEACT_INJECTED_GLOBALS: readonly ["tools", "finish", "__callTool", "__finish", "__toolNames", "__toolModules", "__callBeltTool", "__searchTools", "__graphQueues", "openWorkflow", "nodetool", "__NT_NAMESPACE_TOOLS", "__graphJsonOf"];
+/**
+ * The injected names a model's own code can collide with: the bindings above
+ * minus the `__`-prefixed host bridges, which nobody writes by accident.
+ *
+ * The prelude declares them with `const`, so `const tools = [...]` in an action
+ * is a SyntaxError before a line runs ("lexical redefinition of 'tools'") — a
+ * failure whose cause is invisible from the action's own source. They are named
+ * in the `execute_code` contract, and {@link annotateFailure} names the one
+ * that collided.
+ */
+export declare const RESERVED_ACTION_BINDINGS: readonly string[];
+/** One sentence naming the reserved bindings, for the action contract. */
+export declare const RESERVED_BINDINGS_SENTENCE: string;
+/**
+ * The structural slice of a tool the signature renderer needs. `Tool`
+ * instances satisfy it, and so do bare provider-tool schemas — the chat
+ * runner documents client (`ui_*`) tools that exist only as JSON schemas.
+ */
+export interface ToolSignatureSource {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+}
+/** The bare call signature: `await web_search({query: string, ...})`. */
+export declare function toolSignature(tool: ToolSignatureSource): string;
+/** The specifier a capability is imported from, or `undefined` for a session tool. */
+export declare function toolSpecifier(name: string): string | undefined;
+/**
+ * The import statement that makes one capability callable, or `undefined` for
+ * a name no module owns.
+ */
+export declare function toolImportLine(name: string): string | undefined;
+/** Signature bullet + first sentence of the description. */
+export declare function renderToolSignature(tool: ToolSignatureSource): string;
+/**
+ * The catalog, grouped by the module each capability is imported from.
+ *
+ * The group header IS the import statement the action has to write, with every
+ * name in that group already in the braces — so a model that copies the header
+ * and then calls two of the listed signatures has written a working action.
+ * Listing a signature without saying where the name comes from is what made
+ * the flat belt readable at a glance and unwritable in practice.
+ */
+export declare function renderToolCatalog(tools: ToolSignatureSource[], 
+/**
+ * Specifiers for names no capability module owns but the host has grafted
+ * onto a namespace anyway — a chat session's `ui_*` tools, a step's own
+ * belt. A name absent from it is documented as a plain tool call, which is
+ * what an external MCP tool is.
+ */
+grafted?: ReadonlyMap<string, string>): string;
+/** What `nodetool.searchTools()` returns to the guest, per matched tool. */
+export interface ToolSearchHit {
+    name: string;
+    signature: string;
+    description: string;
+    /** The capability namespace, absent for a tool no module owns. */
+    module?: string;
+    /** The specifier to import it from, absent for the same reason. */
+    specifier?: string;
+    /** The exact import statement to write. */
+    import?: string;
+}
+/** One search hit, with everything needed to write the call. */
+export declare function toolSearchHit(tool: ToolSignatureSource, 
+/** The namespace a host grafted this name onto, if any. */
+graftedModule?: string): ToolSearchHit;
+//# sourceMappingURL=tool-api.d.ts.map

package/dist/codeact/tool-api.d.ts.map

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

package/dist/codeact/tool-api.js

@@ -0,0 +1,452 @@
+/**
+ * CodeAct tool API — the bridge that exposes an agent toolbelt to sandboxed
+ * JavaScript actions, and the signature rendering that documents it in the
+ * system prompt.
+ *
+ * One host bridge (`__callTool`) serves every tool; a generated guest prelude
+ * builds the belt caller on top of it. Host bridges follow the
+ * js-sandbox never-reject convention: they resolve `{ok, ...}` envelopes and
+ * the guest wrapper re-throws, so the QuickJS host-promise-rejection leak is
+ * never hit.
+ */
+import { DIRECT_TOOL_NAMES } from "@nodetool-ai/runtime";
+import { sandboxCapabilitySpecifier } from "@nodetool-ai/protocol";
+import { capabilityModuleOf } from "../capabilities/registry.js";
+import { MAX_ACTION_IMAGES } from "../constants.js";
+import { Tool } from "../tools/base-tool.js";
+import { TOOL_CALL_ID_FIELD } from "../tools/subtask-fields.js";
+import { extractInjectableImages, stripImagePayload } from "../tools/image-injection.js";
+import { compactResourceIds } from "./compact-ids.js";
+import { GRAPH_MODEL_GLOBALS } from "./graph-model.js";
+import { NODETOOL_API_GLOBALS } from "./nodetool-api.js";
+import { TOOLS_PRELUDE } from "./tools-prelude.js";
+import { isBoolean, isNonEmptyString, isNumber, isObjectLike, isRecord, isString } from "../utils/type-guards.js";
+export { TOOLS_PRELUDE } from "./tools-prelude.js";
+/** Tool-call ceiling per code action; a runaway guest loop stops here. */
+export const DEFAULT_MAX_TOOL_CALLS_PER_ACTION = 50;
+/** The `generation_id` a generation-producing capability answers with. */
+function generationIdOf(result) {
+    if (!isRecord(result))
+        return null;
+    const id = result["generation_id"];
+    return isNonEmptyString(id) ? id : null;
+}
+/** Force a value through JSON so it marshals cleanly across the WASM boundary. */
+export function toTransferable(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (isString(value) || isNumber(value) || isBoolean(value)) {
+        return value;
+    }
+    try {
+        return JSON.parse(JSON.stringify(value));
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * Tool errors and failed edit batches stop dependent guest code. Successful
+ * operations in a partial batch may already be persisted.
+ */
+export function extractErrorPayload(result) {
+    if (!isObjectLike(result) || Array.isArray(result)) {
+        return null;
+    }
+    const record = result;
+    if (isString(record["error"])) {
+        const message = record["message"];
+        const summary = isNonEmptyString(message) ? message : record["error"];
+        const validation = record["validation"];
+        return isObjectLike(validation)
+            ? summary + "\n" + JSON.stringify(validation, null, 2)
+            : summary;
+    }
+    const { applied, failed, ops } = record;
+    if (isNumber(applied) &&
+        isNumber(failed) &&
+        failed > 0 &&
+        Array.isArray(ops)) {
+        const errors = ops.flatMap((op) => {
+            if (!isObjectLike(op) || op.ok !== false || !isString(op.error)) {
+                return [];
+            }
+            return [`${isString(op.op) ? op.op : "operation"}: ${op.error}`];
+        });
+        return (`Edit batch: ${applied} applied, ${failed} failed. ${errors.join(" ")} ` +
+            (applied > 0
+                ? "Successful operations may already be saved. "
+                : "No operations applied. ") +
+            "Read the current document state before retrying or issuing dependent edits.");
+    }
+    return null;
+}
+/**
+ * Wire name → the capability namespace it is imported from, for the names a
+ * module owns. A session tool (a client `ui_*` schema, an external MCP tool)
+ * owns no module and is left out, which is how the guest's `tools` thrower
+ * tells "import it from here" from "ask searchTools".
+ */
+export function toolModuleMap(tools) {
+    const map = {};
+    for (const tool of tools) {
+        const module = capabilityModuleOf(tool.name);
+        if (module !== undefined)
+            map[tool.name] = module;
+    }
+    return map;
+}
+export function buildToolBridge(options) {
+    const byName = new Map(options.tools.map((t) => [t.name, t]));
+    const maxCalls = options.maxToolCallsPerAction ?? DEFAULT_MAX_TOOL_CALLS_PER_ACTION;
+    let calls = 0;
+    // Lifetime count across actions — the id a tool sees must stay unique.
+    let totalCalls = 0;
+    let pendingImages = [];
+    let droppedImages = 0;
+    const generationIds = new Set();
+    const callTool = async (name, argsJson) => {
+        try {
+            const tool = isString(name) ? byName.get(name) : undefined;
+            if (!isString(name) || !tool) {
+                return {
+                    ok: false,
+                    error: `Unknown tool "${String(name)}". Available: ${[...byName.keys()].join(", ")}`
+                };
+            }
+            if (calls >= maxCalls) {
+                return {
+                    ok: false,
+                    error: `Tool-call budget for this action exhausted (max ${maxCalls} calls). Return an intermediate result and continue in the next action.`
+                };
+            }
+            calls++;
+            let args = {};
+            if (isNonEmptyString(argsJson)) {
+                try {
+                    const parsed = JSON.parse(argsJson);
+                    if (isRecord(parsed)) {
+                        args = parsed;
+                    }
+                    else if (parsed !== null) {
+                        return {
+                            ok: false,
+                            error: `tools.${name}: arguments must be an object`
+                        };
+                    }
+                }
+                catch {
+                    return {
+                        ok: false,
+                        error: `tools.${name}: arguments must be JSON-serializable`
+                    };
+                }
+            }
+            totalCalls++;
+            const toolCallId = `codeact_${totalCalls}`;
+            options.onToolCall?.({ name, args, toolCallId });
+            const input = Tool.stripMessage(args);
+            if (tool.needsToolCallId) {
+                input[TOOL_CALL_ID_FIELD] = toolCallId;
+            }
+            let result = await options.invoke(name, input, toolCallId);
+            // Read before the error branch: a failed generation still answers with
+            // its id, and the registry decides later whether it completed.
+            const generationId = generationIdOf(result);
+            if (generationId !== null)
+                generationIds.add(generationId);
+            // A view-image-style result carries pixels the model asked for. They
+            // cannot ride the JSON observation (base64 would burn the context for
+            // nothing), so strip them here and let the caller forward them as a
+            // provider image message alongside the observation.
+            const injected = extractInjectableImages(result);
+            if (injected) {
+                for (const image of injected.images) {
+                    if (pendingImages.length < MAX_ACTION_IMAGES)
+                        pendingImages.push(image);
+                    else
+                        droppedImages++;
+                }
+                result = stripImagePayload(result);
+            }
+            const errorPayload = extractErrorPayload(result);
+            if (errorPayload !== null) {
+                options.onToolResult?.({
+                    name,
+                    toolCallId,
+                    result: errorPayload,
+                    isError: true
+                });
+                return { ok: false, error: `tools.${name}: ${errorPayload}` };
+            }
+            const transferable = toTransferable(compactResourceIds(result));
+            options.onToolResult?.({
+                name,
+                toolCallId,
+                result: transferable,
+                isError: false
+            });
+            return { ok: true, result: transferable };
+        }
+        catch (e) {
+            return {
+                ok: false,
+                error: e instanceof Error ? e.message : String(e)
+            };
+        }
+    };
+    return {
+        globals: {
+            __callTool: callTool,
+            __toolNames: options.tools.map((t) => t.name),
+            __toolModules: toolModuleMap(options.tools)
+        },
+        callCount: () => calls,
+        resetActionBudget: () => {
+            calls = 0;
+        },
+        drainImages: () => {
+            const images = pendingImages;
+            const dropped = droppedImages;
+            pendingImages = [];
+            droppedImages = 0;
+            return { images, dropped };
+        },
+        generationIds: () => generationIds
+    };
+}
+/**
+ * Split a toolbelt into the tools also offered top level and the rest.
+ *
+ * Membership is {@link DIRECT_TOOL_NAMES}: the core set that mirrors a Claude
+ * Agent SDK built-in, plus discovery — which providers, models and node types
+ * this install has. Both are shapes a plain tool call fits, so a sandbox round
+ * trip whose only job is to forward one buys nothing.
+ *
+ * `core` is a view, not a removal: the belt keeps every tool, because the
+ * object model (`nodetool.models.pick`, `nodetool.web`, `nodetool.agents`) and
+ * any hand-written fan-out call them from inside an action. What the top-level
+ * offer changes is the *documented* path — the prompt catalog lists them as
+ * direct tools, and the default way to reach one is a tool call.
+ */
+export function splitCoreTools(tools) {
+    const core = [];
+    const belt = [];
+    for (const tool of tools) {
+        (DIRECT_TOOL_NAMES.has(tool.name) ? core : belt).push(tool);
+    }
+    return { core, belt };
+}
+/**
+ * Render core tools as provider tool definitions that execute themselves.
+ *
+ * The result travels as text; pixels a tool returns are handed back as image
+ * content blocks instead, the way the sandbox bridge holds them out of the
+ * observation.
+ */
+export function buildCoreProviderTools(options) {
+    return options.tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        execute: async (args, toolCallId) => {
+            const id = toolCallId ?? `core_${tool.name}`;
+            options.onToolCall?.({ name: tool.name, args, toolCallId: id });
+            let result = await Tool.executeTool(tool, options.context, args, {
+                toolCallId: id
+            });
+            const injected = extractInjectableImages(result);
+            if (!injected)
+                return JSON.stringify(toTransferable(result));
+            result = stripImagePayload(result);
+            return [
+                { type: "text", text: JSON.stringify(toTransferable(result)) },
+                ...injected.images
+            ];
+        }
+    }));
+}
+/**
+ * Guest-side prelude prepended to every code action. Builds the belt caller
+ * over `__callTool` (via {@link TOOLS_PRELUDE}) and `finish()` over
+ * `__finish`. Hosts without a `__finish` bridge — the Code node — prepend
+ * `TOOLS_PRELUDE` alone. Tool discovery lives on the object model as
+ * `nodetool.searchTools()`, so a session reaches every capability under one
+ * name.
+ */
+export const CODEACT_PRELUDE = `${TOOLS_PRELUDE}
+async function finish(result) {
+  const __r = await __finish(JSON.stringify(result === undefined ? null : result));
+  if (!__r || __r.ok !== true) {
+    throw new Error(__r && __r.error ? __r.error : "finish() rejected the result");
+  }
+  return "step finished";
+}
+`;
+/**
+ * Every name the guest already has beyond the sandbox manifest's own surface:
+ * the host bridges the executors install as `globals`, the wrappers
+ * {@link CODEACT_PRELUDE} builds over them, and the two optional object-model
+ * preludes. User code cannot rebind these, and prompt text may name them
+ * without the sandbox-manifest drift check calling them undefined.
+ */
+export const CODEACT_INJECTED_GLOBALS = [
+    // Host bridges (`runInSandbox` globals) plus the prelude's wrappers.
+    "tools",
+    "finish",
+    "__callTool",
+    "__finish",
+    "__toolNames",
+    "__toolModules",
+    "__callBeltTool",
+    "__searchTools",
+    "__graphQueues",
+    ...GRAPH_MODEL_GLOBALS,
+    ...NODETOOL_API_GLOBALS
+];
+/**
+ * The injected names a model's own code can collide with: the bindings above
+ * minus the `__`-prefixed host bridges, which nobody writes by accident.
+ *
+ * The prelude declares them with `const`, so `const tools = [...]` in an action
+ * is a SyntaxError before a line runs ("lexical redefinition of 'tools'") — a
+ * failure whose cause is invisible from the action's own source. They are named
+ * in the `execute_code` contract, and {@link annotateFailure} names the one
+ * that collided.
+ */
+export const RESERVED_ACTION_BINDINGS = CODEACT_INJECTED_GLOBALS.filter((name) => !name.startsWith("__"));
+/** One sentence naming the reserved bindings, for the action contract. */
+export const RESERVED_BINDINGS_SENTENCE = `The prelude already declares ${RESERVED_ACTION_BINDINGS.map((n) => `\`${n}\``).join(", ")}. ` +
+    "Declaring one of them again is a SyntaxError before your code runs, so " +
+    "name your own variables something else.";
+function schemaTypeLabel(schema, depth = 0) {
+    if (!isObjectLike(schema))
+        return "unknown";
+    const s = schema;
+    if (Array.isArray(s["enum"])) {
+        return s["enum"]
+            .slice(0, 6)
+            .map((v) => JSON.stringify(v))
+            .join(" | ");
+    }
+    const type = s["type"];
+    if (type === "array") {
+        return `${schemaTypeLabel(s["items"], depth + 1)}[]`;
+    }
+    if (type === "object") {
+        const props = s["properties"];
+        if (!props || depth >= 2)
+            return "object";
+        const required = new Set(Array.isArray(s["required"]) ? s["required"] : []);
+        const fields = Object.entries(props)
+            .map(([key, value]) => `${key}${required.has(key) ? "" : "?"}: ${schemaTypeLabel(value, depth + 1)}`)
+            .join(", ");
+        return `{${fields}}`;
+    }
+    if (type === "integer")
+        return "number";
+    if (isString(type))
+        return type;
+    if (Array.isArray(type))
+        return type.join(" | ");
+    return "unknown";
+}
+function firstSentence(text) {
+    const trimmed = text.trim().replace(/\s+/g, " ");
+    const period = trimmed.indexOf(". ");
+    return period > 0 ? trimmed.slice(0, period + 1) : trimmed;
+}
+/** The bare call signature: `await web_search({query: string, ...})`. */
+export function toolSignature(tool) {
+    const schema = tool.inputSchema;
+    const params = schemaTypeLabel(schema);
+    const args = params === "{}" ? "" : params;
+    return `await ${tool.name}(${args})`;
+}
+/** The specifier a capability is imported from, or `undefined` for a session tool. */
+export function toolSpecifier(name) {
+    const module = capabilityModuleOf(name);
+    return module === undefined ? undefined : sandboxCapabilitySpecifier(module);
+}
+/**
+ * The import statement that makes one capability callable, or `undefined` for
+ * a name no module owns.
+ */
+export function toolImportLine(name) {
+    const specifier = toolSpecifier(name);
+    return specifier === undefined
+        ? undefined
+        : `import { ${name} } from ${JSON.stringify(specifier)};`;
+}
+/** Signature bullet + first sentence of the description. */
+export function renderToolSignature(tool) {
+    const description = firstSentence(tool.description ?? "");
+    return description
+        ? `- ${toolSignature(tool)}\n  ${description}`
+        : `- ${toolSignature(tool)}`;
+}
+/**
+ * The catalog, grouped by the module each capability is imported from.
+ *
+ * The group header IS the import statement the action has to write, with every
+ * name in that group already in the braces — so a model that copies the header
+ * and then calls two of the listed signatures has written a working action.
+ * Listing a signature without saying where the name comes from is what made
+ * the flat belt readable at a glance and unwritable in practice.
+ */
+export function renderToolCatalog(tools, 
+/**
+ * Specifiers for names no capability module owns but the host has grafted
+ * onto a namespace anyway — a chat session's `ui_*` tools, a step's own
+ * belt. A name absent from it is documented as a plain tool call, which is
+ * what an external MCP tool is.
+ */
+grafted = new Map()) {
+    if (tools.length === 0)
+        return "(no tools available)";
+    const groups = new Map();
+    const ungrouped = [];
+    for (const tool of tools) {
+        const specifier = toolSpecifier(tool.name) ?? grafted.get(tool.name);
+        if (specifier === undefined) {
+            ungrouped.push(tool);
+            continue;
+        }
+        const group = groups.get(specifier);
+        if (group === undefined)
+            groups.set(specifier, [tool]);
+        else
+            group.push(tool);
+    }
+    const blocks = [...groups.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([specifier, group]) => [
+        `import { ${group.map((t) => t.name).join(", ")} } from ${JSON.stringify(specifier)};`,
+        ...group.map(renderToolSignature)
+    ].join("\n"));
+    if (ungrouped.length > 0) {
+        blocks.push([
+            "// no import — these are called as ordinary tools:",
+            ...ungrouped.map(renderToolSignature)
+        ].join("\n"));
+    }
+    return blocks.join("\n\n");
+}
+/** One search hit, with everything needed to write the call. */
+export function toolSearchHit(tool, 
+/** The namespace a host grafted this name onto, if any. */
+graftedModule) {
+    const hit = {
+        name: tool.name,
+        signature: toolSignature(tool),
+        description: tool.description ?? ""
+    };
+    const module = capabilityModuleOf(tool.name) ?? graftedModule;
+    if (module !== undefined) {
+        hit.module = module;
+        hit.specifier = sandboxCapabilitySpecifier(module);
+        hit.import = `import { ${tool.name} } from ${JSON.stringify(sandboxCapabilitySpecifier(module))};`;
+    }
+    return hit;
+}
+//# sourceMappingURL=tool-api.js.map