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

package/dist/codeact/action-diagnostics.js

@@ -0,0 +1,147 @@
+/**
+ * Error diagnostics for CodeAct actions.
+ *
+ * An action runs as `${prelude}\n${action code}` inside one guest module named
+ * `user-code`, so QuickJS stack positions count the prelude's thousand-odd
+ * lines first. The observation an agent sees therefore pointed far past its own
+ * program (`at user-code:1245:26` for a sixty-line action) and syntax errors
+ * arrived with no excerpt to look at — two failures a model cannot fix from
+ * that alone.
+ *
+ * {@link annotateActionStack} rewinds each `user-code` frame into the action's
+ * own coordinates and appends the offending source line, so the frame reads
+ * `at action:<line>:<col>` and the excerpt sits under it.
+ */
+import { parseCodeBody } from "@nodetool-ai/node-sdk";
+import { entryBodyLineOffset } from "../js-sandbox-worker/interpreter.js";
+import { RESERVED_ACTION_BINDINGS, RESERVED_BINDINGS_SENTENCE } from "./tool-api.js";
+/**
+ * A stack frame pointing into the guest's `user-code` module. Both shapes
+ * appear: bare frames from module-level code (`at user-code:8:9`) and named
+ * ones (`at helper (user-code:12:3)`).
+ */
+const USER_CODE_FRAME = /^(\s*at\s+(?:[^(]*\()?)user-code:(\d+):(\d+)(\)?)\s*$/;
+const MAX_EXCERPT_CHARS = 200;
+function excerptFor(code, line, column) {
+    const lines = code.split("\n");
+    if (line < 1 || line > lines.length)
+        return "";
+    const text = lines[line - 1];
+    const shown = text.length > MAX_EXCERPT_CHARS
+        ? text.slice(0, MAX_EXCERPT_CHARS) + "…"
+        : text;
+    // A one-character column is approximate across tabs, but it still points a
+    // model at the offending token far better than the bare pair of numbers.
+    const caret = column >= 1 && text.length <= MAX_EXCERPT_CHARS
+        ? `\n         ${" ".repeat(Math.min(column - 1, shown.length))}^`
+        : "";
+    return shown + caret;
+}
+/** How many module lines precede the action's first line. */
+function actionLineOffset(prelude, code) {
+    // The joining "\n" makes the prelude occupy exactly split("\n").length lines
+    // of the combined source before the action begins.
+    return prelude.split("\n").length + entryBodyLineOffset(prelude + "\n" + code);
+}
+/**
+ * Rewrite `at user-code:L:C` frames against `${prelude}\n${code}`.
+ *
+ * Frames above the action's first line belong to the prelude itself; they keep
+ * their original coordinates rather than a negative rewrite. The first frame
+ * that lands on real action code gains the source-line note under it.
+ */
+export function annotateActionStack(stack, prelude, code) {
+    if (!stack)
+        return {};
+    const offset = actionLineOffset(prelude, code);
+    let noted = false;
+    const rewritten = stack.split("\n").map((frameLine) => {
+        const match = USER_CODE_FRAME.exec(frameLine);
+        if (!match)
+            return frameLine;
+        const mapped = Number(match[2]) - offset;
+        if (mapped < 1)
+            return frameLine;
+        const frame = `${match[1]}action:${mapped}:${match[3]}${match[4]}`;
+        if (!noted) {
+            noted = true;
+            const text = excerptFor(code, mapped, Number(match[3]));
+            if (text) {
+                return `${frame}\n    >> your code, line ${mapped}: ${text}`;
+            }
+        }
+        return frame;
+    });
+    return { stack: rewritten.join("\n") };
+}
+/**
+ * The failure fields of an action observation: the guest error plus its stack
+ * rewound into action coordinates. Both CodeAct executors build the same shape,
+ * so they share this instead of repeating the wiring.
+ */
+export function annotateFailure(error, stack, prelude, code) {
+    const collision = reservedRedeclaration(error);
+    if (collision !== undefined)
+        return { error: collision };
+    const reparsed = reparseSyntaxError(error, code);
+    if (reparsed !== undefined)
+        return reparsed;
+    if (!stack)
+        return { error };
+    return { error, stack: annotateActionStack(stack, prelude, code).stack };
+}
+/**
+ * Re-diagnose a guest syntax error with acorn, which knows where it is.
+ *
+ * QuickJS compiles the whole entry module and reports a position that need not
+ * be the offending one: `import { integerInput } = "…"` on line 3 arrived as
+ * `SyntaxError: expecting '(' at action:1:26`, with the excerpt showing a line
+ * that was perfectly good. A model reading that rewrites line 1 and hits the
+ * same error again — which is what happened, twice, in the session this comes
+ * from.
+ *
+ * Only a body acorn *also* rejects is re-reported, so this can never override
+ * a genuine failure the parser is happy with. The other SyntaxError a guest
+ * raises — module linking, "Could not find export 'x'" — parses fine here and
+ * passes through untouched.
+ */
+function reparseSyntaxError(error, code) {
+    if (error === undefined || !error.includes("SyntaxError"))
+        return undefined;
+    const parsed = parseCodeBody(code);
+    if (!("error" in parsed))
+        return undefined;
+    const line = parsed.line;
+    const message = `SyntaxError: ${parsed.error}`;
+    if (line === undefined)
+        return { error: message };
+    const excerpt = excerptFor(code, line, 1);
+    const stack = excerpt === ""
+        ? `    at action:${line}`
+        : `    at action:${line}\n    >> your code, line ${line}: ${excerpt}`;
+    return { error: message, stack };
+}
+/**
+ * QuickJS names a redeclared binding but not where it came from, so
+ * "SyntaxError: lexical redefinition of 'tools'" points a model at a
+ * declaration that looks fine — the clashing one is in the prelude it never
+ * sees. Say which prelude binding it hit and what to do about it.
+ *
+ * Only a name the prelude actually reserves is rewritten; a redeclaration
+ * inside the action's own code is the model's to find, and the position it
+ * already carries is enough.
+ */
+function reservedRedeclaration(error) {
+    if (error === undefined || !error.includes("SyntaxError"))
+        return undefined;
+    const match = /(?:redefinition|redeclaration) of (?:lexical identifier )?['"`]?([A-Za-z_$][\w$]*)/.exec(error);
+    const name = match?.[1];
+    if (name === undefined || !RESERVED_ACTION_BINDINGS.includes(name)) {
+        return undefined;
+    }
+    return (`${error.trim()} — \`${name}\` is a binding the action prelude declares ` +
+        `before your code runs, not one of yours. Rename your variable (e.g. ` +
+        `\`my${name.charAt(0).toUpperCase()}${name.slice(1)}\`). ` +
+        RESERVED_BINDINGS_SENTENCE);
+}
+//# sourceMappingURL=action-diagnostics.js.map

package/dist/codeact/action-diagnostics.js.map

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

package/dist/codeact/capability-modules.d.ts

@@ -0,0 +1,66 @@
+import type { CapabilityRun } from "../capabilities/types.js";
+import type { SandboxCapabilityMount } from "../js-sandbox.js";
+/**
+ * What a capability answering with pixels is told inside an action.
+ *
+ * `view_image` answers with an `image_content` payload the tool loop injects
+ * into the model's next turn as a real image block. A capability imported into
+ * a code action has no such channel: its result is a JavaScript value that
+ * reaches the model only as the action's JSON observation, so the pixels went
+ * nowhere and the model read back its own question. Say where the pixels are
+ * instead of pretending they arrived.
+ */
+export declare const SANDBOX_IMAGE_NOTE: string;
+export type CapabilityModuleMount = {
+    ok: true;
+    mount?: SandboxCapabilityMount;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Session tools a host wants importable alongside the registry's own modules.
+ *
+ * Chat is the case this exists for: its client `ui_*` tools are JSON schemas
+ * routed back to the browser, not capabilities, so no registry module owns
+ * them. Grafting them onto a namespace keeps one resolution path — a chat
+ * action imports `ui_add_node` exactly the way it imports `list_workflows` —
+ * without inventing a second global for the difference. External MCP-server
+ * tools are deliberately NOT offered this way: they stay provider-level tool
+ * calls.
+ */
+/**
+ * The namespace belt tools with no capability module of their own are grafted
+ * onto. It is not in the registry — nothing declares it — which is the point:
+ * a name under it belongs to this session, not to the platform.
+ */
+export declare const SESSION_CAPABILITY_MODULE = "session";
+/**
+ * The guest namespace a belt name no capability module owns is grafted onto:
+ * a client `ui_*` tool goes under `ui`, an external MCP tool under `mcp`,
+ * anything else a host added under `session`.
+ */
+export declare function graftedModuleFor(name: string): string;
+export interface SessionCapabilityModule {
+    /** The namespace to graft onto, e.g. `"ui"`. */
+    readonly module: string;
+    /** Wire names to export, added to whatever the registry module declares. */
+    readonly exports: readonly string[];
+    /** What a call to one of those names runs. */
+    readonly call: (name: string, args: unknown) => Promise<unknown>;
+}
+export interface MountCapabilityModulesOptions {
+    signal?: AbortSignal;
+    /** Session tools grafted onto a namespace. Empty by default. */
+    session?: readonly SessionCapabilityModule[];
+}
+/**
+ * The platform modules one action's code needs, or nothing when it imports
+ * none — and nothing at all when the session has no run to serve them.
+ *
+ * A specifier under the pack that names no registered namespace stops the
+ * action before the guest starts, the way an unresolvable pack import does:
+ * the model sees the refusal as its observation and can correct the import.
+ */
+export declare function mountCapabilityModules(code: string, run: CapabilityRun | undefined, options?: MountCapabilityModulesOptions): Promise<CapabilityModuleMount>;
+//# sourceMappingURL=capability-modules.d.ts.map

package/dist/codeact/capability-modules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-modules.d.ts","sourceRoot":"","sources":["../../src/codeact/capability-modules.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAO9D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE/D;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,QAIuC,CAAC;AAqBvE,MAAM,MAAM,qBAAqB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,sBAAsB,CAAA;CAAE,GAC5C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjC;;;;;;;;;;GAUG;AACH;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,YAAY,CAAC;AAEnD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrD;AAED,MAAM,WAAW,uBAAuB;IACtC,gDAAgD;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAClE;AAED,MAAM,WAAW,6BAA6B;IAC5C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,gEAAgE;IAChE,OAAO,CAAC,EAAE,SAAS,uBAAuB,EAAE,CAAC;CAC9C;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,aAAa,GAAG,SAAS,EAC9B,OAAO,GAAE,6BAAkC,GAC1C,OAAO,CAAC,qBAAqB,CAAC,CA2GhC"}

package/dist/codeact/capability-modules.js

@@ -0,0 +1,278 @@
+/**
+ * Mounting the platform's own modules for one action.
+ *
+ * `@nodetool-ai/sandbox-nodetool/<namespace>` is not a pack: it is NodeTool's
+ * own surface, mounted by the host for a session that has a `CapabilityRun`,
+ * and deliberately outside the model-facing consent allowlist
+ * (`sandbox-packages.ts`) — consent gates third-party code, and the host
+ * already decided what this session can do when it built the run.
+ *
+ * Only the namespaces the action imports are loaded. The dispatcher accepts
+ * every registered module, so what an import costs is one module's dependency
+ * cone, not the registry's — the laziness the registry's loader table exists
+ * for.
+ *
+ * A session without a run mounts nothing, and the import is refused by name.
+ */
+import { generateSandboxCapabilityFacade, sandboxCapabilityModuleName, sandboxCapabilitySpecifier, MCP_CAPABILITY_MODULE, MCP_TOOL_PREFIX, SANDBOX_CAPABILITY_PACK } from "@nodetool-ai/protocol";
+import { parseCodeBody, staticImportBindings, staticImportSpecifiers } from "@nodetool-ai/node-sdk";
+import { capabilityModuleSpecs, createCapabilityDispatcher } from "../capabilities/dispatcher.js";
+import { listCapabilityModules } from "../capabilities/registry.js";
+import { extractInjectableImages, IMAGE_CONTENT_FIELD, IMAGE_CONTENTS_FIELD } from "../tools/image-injection.js";
+import { isRecord, isString } from "../utils/type-guards.js";
+/**
+ * What a capability answering with pixels is told inside an action.
+ *
+ * `view_image` answers with an `image_content` payload the tool loop injects
+ * into the model's next turn as a real image block. A capability imported into
+ * a code action has no such channel: its result is a JavaScript value that
+ * reaches the model only as the action's JSON observation, so the pixels went
+ * nowhere and the model read back its own question. Say where the pixels are
+ * instead of pretending they arrived.
+ */
+export const SANDBOX_IMAGE_NOTE = "No pixels were delivered: an image cannot cross into a code action, only " +
+    "its reference. To look at it, call view_image as a direct tool call " +
+    "(outside execute_code) with this image_id, or ask a vision model about it " +
+    "with critique_image / score_image_adherence, which answer in text.";
+/**
+ * Replace an injectable-image payload with the note above. Every other result
+ * passes through untouched.
+ */
+function withoutPixels(result) {
+    if (extractInjectableImages(result) === null || !isRecord(result)) {
+        return result;
+    }
+    const stripped = { ...result };
+    delete stripped[IMAGE_CONTENT_FIELD];
+    delete stripped[IMAGE_CONTENTS_FIELD];
+    const note = stripped["note"];
+    stripped["note"] =
+        isString(note) && note.length > 0
+            ? `${note} ${SANDBOX_IMAGE_NOTE}`
+            : SANDBOX_IMAGE_NOTE;
+    return stripped;
+}
+/**
+ * Session tools a host wants importable alongside the registry's own modules.
+ *
+ * Chat is the case this exists for: its client `ui_*` tools are JSON schemas
+ * routed back to the browser, not capabilities, so no registry module owns
+ * them. Grafting them onto a namespace keeps one resolution path — a chat
+ * action imports `ui_add_node` exactly the way it imports `list_workflows` —
+ * without inventing a second global for the difference. External MCP-server
+ * tools are deliberately NOT offered this way: they stay provider-level tool
+ * calls.
+ */
+/**
+ * The namespace belt tools with no capability module of their own are grafted
+ * onto. It is not in the registry — nothing declares it — which is the point:
+ * a name under it belongs to this session, not to the platform.
+ */
+export const SESSION_CAPABILITY_MODULE = "session";
+/**
+ * The guest namespace a belt name no capability module owns is grafted onto:
+ * a client `ui_*` tool goes under `ui`, an external MCP tool under `mcp`,
+ * anything else a host added under `session`.
+ */
+export function graftedModuleFor(name) {
+    if (name.startsWith("ui_"))
+        return "ui";
+    if (name.startsWith(MCP_TOOL_PREFIX))
+        return MCP_CAPABILITY_MODULE;
+    return SESSION_CAPABILITY_MODULE;
+}
+/**
+ * The platform modules one action's code needs, or nothing when it imports
+ * none — and nothing at all when the session has no run to serve them.
+ *
+ * A specifier under the pack that names no registered namespace stops the
+ * action before the guest starts, the way an unresolvable pack import does:
+ * the model sees the refusal as its observation and can correct the import.
+ */
+export async function mountCapabilityModules(code, run, options = {}) {
+    const session = options.session ?? [];
+    if (run === undefined && session.length === 0)
+        return { ok: true };
+    const parsed = parseCodeBody(code);
+    // A body that does not parse has no imports to serve; the sandbox reports the
+    // syntax error itself, where the position still points at the model's code.
+    if ("error" in parsed)
+        return { ok: true };
+    const imported = [...new Set(staticImportSpecifiers(parsed.statements))];
+    const wanted = imported.filter((specifier) => specifier.startsWith(SANDBOX_CAPABILITY_PACK));
+    if (wanted.length === 0)
+        return { ok: true };
+    const sessionByModule = new Map(session.map((entry) => [entry.module, entry]));
+    // A run serves the registry's modules; without one only the grafted
+    // namespaces resolve, so the refusal names what this session actually has.
+    const registered = new Set(run === undefined ? sessionByModule.keys() : listCapabilityModules());
+    for (const name of sessionByModule.keys())
+        registered.add(name);
+    const modules = [];
+    for (const specifier of wanted) {
+        const name = sandboxCapabilityModuleName(specifier);
+        if (name === undefined || !registered.has(name)) {
+            return {
+                ok: false,
+                error: `The action imports "${specifier}", which is not a NodeTool ` +
+                    `capability module. Available modules: ${[...registered]
+                        .map((module) => `"${SANDBOX_CAPABILITY_PACK}/${module}"`)
+                        .join(", ")}.`
+            };
+        }
+        modules.push(name);
+    }
+    const unique = [...new Set(modules)];
+    const registrySpecs = run === undefined
+        ? []
+        : await capabilityModuleSpecs(unique.filter((name) => listCapabilityModules().includes(name)));
+    const exportsByModule = new Map(registrySpecs.map((spec) => [spec.module, [...spec.exports]]));
+    // A session export shadows nothing: a name the registry already declares
+    // stays the registry's, so grafting can add reach but never redirect a
+    // gated capability at the browser.
+    const sessionNames = new Map();
+    for (const name of unique) {
+        const graft = sessionByModule.get(name);
+        if (graft === undefined)
+            continue;
+        const declared = exportsByModule.get(name) ?? [];
+        const added = graft.exports.filter((exported) => !declared.includes(exported));
+        exportsByModule.set(name, [...declared, ...added]);
+        sessionNames.set(name, new Set(added));
+    }
+    const unknown = unknownImportedExports(parsed.statements, exportsByModule);
+    if (unknown !== undefined)
+        return { ok: false, error: unknown };
+    const facades = new Map(unique.map((name) => [
+        sandboxCapabilitySpecifier(name),
+        generateSandboxCapabilityFacade(sandboxCapabilitySpecifier(name), exportsByModule.get(name) ?? [])
+    ]));
+    const dispatcher = run === undefined
+        ? undefined
+        : createCapabilityDispatcher(run, listCapabilityModules(), options.signal === undefined ? {} : { signal: options.signal });
+    const call = async (moduleKey, exportName, args) => {
+        const module = sandboxCapabilityModuleName(moduleKey) ?? moduleKey;
+        if (sessionNames.get(module)?.has(exportName) === true) {
+            const graft = sessionByModule.get(module);
+            if (graft === undefined) {
+                throw new Error(`no session module serves "${moduleKey}"`);
+            }
+            return withoutPixels(await graft.call(exportName, args[0] === undefined ? {} : args[0]));
+        }
+        if (dispatcher === undefined) {
+            throw new Error(`"${exportName}" is not available in this run — it needs a capability run.`);
+        }
+        return withoutPixels(await dispatcher.call(moduleKey, exportName, args));
+    };
+    return { ok: true, mount: { facades, call } };
+}
+/**
+ * A guessed import that names neither a real export nor a casing/underscore
+ * variant of one — a synonym the model reached for by habit. `images` is the
+ * "web" module's own case: it is now the real `image_search` export's name,
+ * but a model still guesses `images`, `image`, `search_images`, or the
+ * retired `google_images` (see `RETIRED_TOOL_NAMES` in
+ * `packages/llm-nodes/src/nodes/agent-tool-hydration.ts`) for it.
+ */
+const MODULE_EXPORT_SYNONYMS = {
+    web: {
+        images: "image_search",
+        image: "image_search",
+        search_images: "image_search",
+        google_images: "image_search",
+        dataforseo_images: "image_search"
+    }
+};
+/** "Did you mean …" for a known synonym of a real export in this module. */
+function synonymHintSentence(module, missingName, available) {
+    const target = MODULE_EXPORT_SYNONYMS[module]?.[missingName.toLowerCase()];
+    if (target === undefined || !available.includes(target))
+        return "";
+    return `Did you mean "${target}" for "${missingName}"? `;
+}
+/**
+ * `web_search` absorbed news search as a `search_type` argument rather than a
+ * name of its own (`google_news` is retired — see `RETIRED_TOOL_NAMES` in
+ * `packages/llm-nodes/src/nodes/agent-tool-hydration.ts`). Nothing in the
+ * "web" module's export list says so, so a model reaching for a news search
+ * guesses a name like `news_search`, is told only that "web" exports
+ * `web_search, image_search, browser, take_screenshot, http_request,
+ * download_file", and calls plain `web_search` next — which silently returns
+ * page results instead of the dated articles it was asked for. Naming the
+ * parameter here, at the point the guess failed, is cheaper than hoping the
+ * model infers it from a bare export list.
+ */
+const WEB_SEARCH_TYPE_HINTS = {
+    news: "news",
+    news_search: "news",
+    search_news: "news",
+    google_news: "news"
+};
+/** A sentence pointing a guessed news-search import at `web_search`. */
+function searchTypeHintSentence(module, missingName) {
+    if (module !== "web")
+        return "";
+    const searchType = WEB_SEARCH_TYPE_HINTS[missingName.toLowerCase()];
+    if (searchType === undefined)
+        return "";
+    return (`There is no separate ${searchType} search — call "web_search" with ` +
+        `{search_type: "${searchType}"} instead. `);
+}
+/**
+ * A capability module exports its wire names verbatim — `generate_image`, not
+ * `generateImage` — so the spelling a model reaches for by habit resolves to
+ * nothing. Left to the guest that surfaces as QuickJS's "Could not find export
+ * 'generateImage'", which names neither the module's exports nor the one it
+ * meant; the model then guesses again. Refuse the action here instead, with
+ * the export list and the near match.
+ *
+ * Returns the refusal, or `undefined` when every imported name exists.
+ */
+function unknownImportedExports(statements, exportsByModule) {
+    for (const binding of staticImportBindings(statements)) {
+        const module = sandboxCapabilityModuleName(binding.specifier);
+        const available = module === undefined ? undefined : exportsByModule.get(module);
+        if (available === undefined)
+            continue;
+        const missing = binding.named.filter((name) => !available.includes(name));
+        if (missing.length === 0)
+            continue;
+        const names = missing.map((name) => `"${name}"`).join(", ");
+        const suggestions = missing
+            .map((name) => synonymHintSentence(module ?? "", name, available) ||
+            nearMatchSentence(name, available) ||
+            searchTypeHintSentence(module ?? "", name))
+            .filter((sentence) => sentence.length > 0)
+            .join(" ");
+        return (`The action imports ${names} from "${binding.specifier}", which that ` +
+            `module does not export. ${suggestions}Capability modules export the ` +
+            `wire name verbatim, in snake_case. "${binding.specifier}" exports: ` +
+            `${available.join(", ")}.`);
+    }
+    return undefined;
+}
+/**
+ * "Did you mean …" for the one name that differs only in casing, `_`, or a
+ * missing tail.
+ *
+ * The tail is the half that was missing: `preview_timeline` is not a casing
+ * slip of `preview_timeline_frame`, and a model that dropped the last word
+ * read a message listing every export and concluded the capability was gone.
+ * A prefix hint only fires when exactly one export extends the name, so it
+ * never picks between two plausible ones.
+ */
+function nearMatchSentence(wanted, available) {
+    const flatten = (name) => name.replace(/_/g, "").toLowerCase();
+    const target = flatten(wanted);
+    const exact = available.find((name) => flatten(name) === target);
+    if (exact !== undefined) {
+        return `Did you mean "${exact}" for "${wanted}"? `;
+    }
+    if (target.length < 4)
+        return "";
+    const extending = available.filter((name) => flatten(name).startsWith(target) || target.startsWith(flatten(name)));
+    return extending.length === 1
+        ? `Did you mean "${extending[0]}" for "${wanted}"? `
+        : "";
+}
+//# sourceMappingURL=capability-modules.js.map

package/dist/codeact/capability-modules.js.map

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

package/dist/codeact/chat-codeact.d.ts

@@ -0,0 +1,104 @@
+/**
+ * CodeAct for chat turns — the adapter a chat runner uses to make sandboxed
+ * JavaScript the action space of a turn.
+ *
+ * A chat toolbelt is not a `Tool[]`: it mixes server tools with client (`ui_*`)
+ * tools that exist here only as schemas, and every call must go through the
+ * chat runner's own router (permission gate, client round-trips over the
+ * ToolBridge, asset materialization). So instead of `buildToolBridge`, this
+ * session routes every imported belt name to a caller-supplied `executeTool` and
+ * leaves the routing where it is. Everything else matches the step executor:
+ * one `execute_code` provider tool, `nodetool.searchTools()` for the deferred
+ * long tail, and an observation envelope as the tool result. Results a later
+ * turn needs go through memory (`nodetool.memory.*`).
+ *
+ * When the belt carries the `ui_*` workflow document tools, actions also get
+ * the graph object model (`openWorkflow()` — see graph-model.ts), so graph and
+ * node editing happens on a JS object model committed through the same tools.
+ */
+import { type ProcessingContext, type SandboxModuleCatalog } from "@nodetool-ai/runtime";
+import { type SandboxClock } from "../js-sandbox.js";
+import type { CapabilityRun } from "../capabilities/types.js";
+import { type ToolSignatureSource } from "./tool-api.js";
+export interface ChatCodeActToolCall {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+export interface ChatCodeActSessionOptions {
+    /** False only when the host already includes the shared product knowledge. */
+    includeProductKnowledge?: boolean;
+    /** The full chat toolbelt as schemas (server + client tools alike). */
+    tools: ToolSignatureSource[];
+    /**
+     * The chat runner's tool router. Receives a synthetic call id
+     * (`codeact_<n>`); returns whatever the router returns — a JSON string, a
+     * plain value, or `MessageContent[]` blocks (flattened to their text here).
+     */
+    executeTool: (call: ChatCodeActToolCall) => Promise<unknown>;
+    /**
+     * @deprecated Chat code never receives the ProcessingContext directly.
+     * Capabilities that need it must go through the gated tool router.
+     */
+    context?: ProcessingContext;
+    signal?: AbortSignal;
+    /** Wall-clock limit per code action. Defaults to {@link DEFAULT_CODEACT_ACTION_TIMEOUT_MS}. */
+    actionTimeoutMs?: number;
+    /** Tool calls one action may consume. Default 50. */
+    maxToolCallsPerAction?: number;
+    /** Tools documented in full; defaults to {@link CODEACT_RESIDENT_TOOL_NAMES}. */
+    residentToolNames?: Iterable<string>;
+    /**
+     * Tools the caller also offers as ordinary provider tools. They stay on the
+     * belt — code composes them — but the prompt documents them as direct calls
+     * instead of repeating their catalog signature.
+     */
+    directToolNames?: Iterable<string>;
+    /**
+     * The action's wall clock, which the host stops while a bridged call waits on
+     * the user (a permission prompt). Without it, the time a person spends
+     * deciding is charged to the action budget and the program is killed
+     * mid-wait; the answer then resolves nothing.
+     */
+    clock?: SandboxClock;
+    /**
+     * Sandbox package specifiers this chat session consents to. Defaults to
+     * none: a chat turn's code is model-written, so nothing is importable until
+     * the caller names what the session allows.
+     */
+    sandboxPackages?: readonly string[];
+    /**
+     * Catalog the allowed specifiers resolve through. Defaults to the process
+     * catalog the host installed — a chat session gets no ProcessingContext, so
+     * there is no other place to read one from. Pass `null` to resolve nothing.
+     */
+    sandboxModuleCatalog?: SandboxModuleCatalog | null;
+    /**
+     * The session's capability run. With one, an action may import NodeTool's
+     * own modules (`@nodetool-ai/sandbox-nodetool/<namespace>`), which land on
+     * `run.invoke` — the same gate, lookup and implementation the belt reaches.
+     * Without one nothing is mounted and such an import is refused by name.
+     */
+    capabilityRun?: CapabilityRun;
+    /** Observability hook — fires before each bridged tool executes. */
+    onToolCall?: (record: {
+        name: string;
+        args: Record<string, unknown>;
+    }) => void;
+}
+export interface ChatCodeActSession {
+    /** The one provider tool the chat turn exposes in codeact mode. */
+    providerTool: {
+        name: string;
+        description: string;
+        inputSchema: Record<string, unknown>;
+    };
+    /** Appended to the chat system prompt: contract, catalog, sandbox summary. */
+    systemPromptSection: string;
+    /** Run one code action; returns the observation envelope as JSON text. */
+    executeAction(args: Record<string, unknown>): Promise<string>;
+    /** Bridged tool calls consumed so far this turn (across actions). */
+    toolCallCount(): number;
+}
+export declare function createChatCodeActSession(options: ChatCodeActSessionOptions): ChatCodeActSession;
+//# sourceMappingURL=chat-codeact.d.ts.map

package/dist/codeact/chat-codeact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-codeact.d.ts","sourceRoot":"","sources":["../../src/codeact/chat-codeact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAkC9D,OAAO,EAOL,KAAK,mBAAmB,EACzB,MAAM,eAAe,CAAC;AAgCvB,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,yBAAyB;IACxC,8EAA8E;IAC9E,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,uEAAuE;IACvE,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B;;;;OAIG;IACH,WAAW,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7D;;;OAGG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,+FAA+F;IAC/F,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qDAAqD;IACrD,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,iFAAiF;IACjF,iBAAiB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACrC;;;;OAIG;IACH,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACnC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;;OAIG;IACH,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACnD;;;;;OAKG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,oEAAoE;IACpE,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC/B,KAAK,IAAI,CAAC;CACZ;AAED,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,YAAY,EAAE;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACtC,CAAC;IACF,8EAA8E;IAC9E,mBAAmB,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9D,qEAAqE;IACrE,aAAa,IAAI,MAAM,CAAC;CACzB;AA4CD,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,yBAAyB,GACjC,kBAAkB,CA6apB"}