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

package/dist/mcp-agent-tools.js

@@ -0,0 +1,1147 @@
+/**
+ * Bridges the canonical agent tools (`@nodetool-ai/agents`) onto the MCP server
+ * so external agents (Claude Code, ChatGPT, …) get the same surface the in-app
+ * chat agent runs on.
+ *
+ * That surface is CodeAct, not a flat catalog. `execute_code` is built by the
+ * same {@link createChatCodeActSession} the chat runner uses. `view_image` and
+ * asset transfer stay direct because pixels and file bytes need MCP channels.
+ * Every other capability lives inside the sandbox as `tools.<name>()` and the
+ * `nodetool.*` object model, found with `nodetool.searchTools()` and catalogued
+ * on `nodetool://capabilities` and `nodetool://sandbox`.
+ *
+ * The bridged set is *derived*, not hand-listed: `getBuiltinTools()` plus
+ * `getAllMcpTools()` plus the Google Workspace tools are exactly what
+ * `websocket-client-session` assembles for a chat turn, so a tool added to
+ * either catalog reaches the sandbox belt with no edit here. Only tools whose
+ * constructor needs something the catalogs can't supply (a timeline loader, the
+ * lazily probed provider map) are named
+ * individually below.
+ */
+import { z } from "zod";
+import { DIRECT_TOOL_NAMES, ProcessingContext as ProcessingContextImpl, SDK_NATIVE_TOOL_REPLACEMENTS, detectImageMime, isSvgBytes, loadMediaRefBytes, zodToJsonSchema } from "@nodetool-ai/runtime";
+import { Tool, CODEACT_RESIDENT_TOOL_NAMES, createChatCodeActSession, availableBuiltinToolNames, GOOGLE_WORKSPACE_TOOL_NAMES, APIFY_TOOL_NAMES, SERPAPI_TOOL_NAMES, capabilityForName, capabilityFromTool, getAllMcpCapabilitySpecs, createCapabilityRun, contextSecretAvailability, headlessGate, EXECUTE_CODE_TOOL_NAME, NODETOOL_API_NAMESPACE_TOOLS, MCP_GUEST_CONTRACT, MCP_SANDBOX_RESOURCE_URI, MCP_SANDBOX_PROMPTS, buildMcpSandboxCatalog, extractInjectableImages, stripImagePayload } from "@nodetool-ai/agents";
+import { FileStorageAdapter } from "@nodetool-ai/storage";
+import { uiToolSchemas } from "@nodetool-ai/protocol";
+import { loadConfiguredProviders } from "./configured-providers.js";
+import { mcpToolHostDeps } from "./mcp-tool-deps.js";
+import { getSecret, Asset, ImageDocument, TimelineSequence } from "@nodetool-ai/models";
+import { WORKFLOW_DOCUMENT_TOOL_NAMES } from "@nodetool-ai/node-sdk";
+import { createLogger, getNodetoolDataDir, isGoogleWorkspaceEnabled } from "@nodetool-ai/config";
+import { basename, dirname, isAbsolute, join } from "node:path";
+import { mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import sharp from "sharp";
+import { getAssetAdapter } from "./lib/storage.js";
+import { normalizeAssetContentType } from "./lib/asset-paths.js";
+import { createAssetModelInterface, updateAssetBytesModelInterface } from "./lib/asset-model-interface.js";
+import { isRecord, isString } from "./lib/wire-values.js";
+const log = createLogger("nodetool.websocket.mcp-agent-tools");
+const execFile = promisify(execFileCallback);
+/**
+ * These capabilities answer readiness questions from the configured-provider
+ * map. Populate that map before dispatch so a first workflow call cannot
+ * mistake lazy loading for a missing provider.
+ */
+const WORKFLOW_READINESS_TOOL_NAMES = new Set([
+    "plan_workflow",
+    "update_workflow_plan_step",
+    "build_workflow_from_plan"
+]);
+/**
+ * Per-user workspace directory the bridged file tools (read_file, write_file,
+ * glob, grep, …) are rooted at. Kept under the NodeTool data dir rather than a
+ * temp dir because an MCP session is long-lived and spans many calls — a file
+ * written on one call has to still be there on the next. One directory per
+ * user, so a multi-user mount cannot let one caller read another's files.
+ */
+function mcpWorkspaceDir(userId) {
+    // A user id reaches the filesystem as a path segment here, so allow only
+    // characters that cannot traverse out of the parent directory.
+    const safeUserId = userId.replace(/[^A-Za-z0-9_-]/g, "_") || "default";
+    return join(getNodetoolDataDir(), "mcp-workspaces", safeUserId);
+}
+/** Test-only: expose the workspace path rule for isolation assertions. */
+export const __mcpWorkspaceDirForTests = mcpWorkspaceDir;
+/**
+ * Build the shared ProcessingContext the bridged tools run against. REST-backed
+ * tools (create_workflow, list_models, …) read `NODETOOL_API_URL` from the
+ * inherited environment; media tools resolve providers via the secret resolver;
+ * save/media tools persist artifacts through `createAsset`; file tools read and
+ * write under the session's workspace directory.
+ */
+function buildAgentToolContext(userId) {
+    const storage = getAssetAdapter();
+    const workspaceDir = mcpWorkspaceDir(userId);
+    const context = new ProcessingContextImpl({
+        jobId: "mcp-agent-tools",
+        userId,
+        // Bind secret lookups to the scoped user — never a global default.
+        secretResolver: (key) => getSecret(key, userId),
+        storage,
+        workspaceDir,
+        workspaceStorage: new FileStorageAdapter(workspaceDir)
+    });
+    context.setModelInterfaces({
+        createAsset: createAssetModelInterface,
+        updateAssetBytes: updateAssetBytesModelInterface,
+        getAssetInfo: async ({ userId, assetId }) => {
+            const asset = await Asset.find(userId, assetId);
+            if (!asset)
+                return null;
+            return {
+                id: asset.id,
+                content_type: asset.content_type,
+                name: asset.name,
+                metadata: asset.metadata ?? null
+            };
+        }
+    });
+    return context;
+}
+/**
+ * Read a `timeline_sequences` row for `validate_timeline`. There is no REST
+ * route for timelines (the API is tRPC-only), so the tool takes this loader
+ * instead of fetching. Ownership is checked the same way the tRPC router's
+ * `loadOwned` does — a row belonging to another user reads as not found.
+ */
+const loadTimelineForUser = async (context, id) => {
+    const row = await TimelineSequence.findById(id);
+    if (!row || row.user_id !== context.userId)
+        return null;
+    return {
+        document: row.document,
+        fps: row.fps,
+        width: row.width,
+        height: row.height,
+        name: row.name
+    };
+};
+/**
+ * Read an `image_documents` row for `validate_sketch`. There is no REST route
+ * for sketches (the API is tRPC-only), so the tool takes this loader instead of
+ * fetching. Ownership is checked the same way the tRPC router's `loadOwned`
+ * does — a row belonging to another user reads as not found.
+ */
+const loadSketchForUser = async (context, id) => {
+    const row = await ImageDocument.findById(id);
+    if (!row || row.user_id !== context.userId)
+        return null;
+    return {
+        document: row.document,
+        width: row.width,
+        height: row.height,
+        backgroundColor: row.background_color,
+        name: row.name
+    };
+};
+/** Test-only: expose the per-user context construction for scope assertions. */
+export const __buildAgentToolContextForTests = (userId) => buildAgentToolContext(userId);
+// ── JSON Schema → Zod shape ─────────────────────────────────────────
+//
+// The agent tools declare plain JSON-Schema; the MCP SDK's `server.tool`
+// wants a Zod raw shape. These converters cover the property kinds the tools
+// actually use (string/number/boolean/array/object, enums, defaults).
+function jsonSchemaPropToZod(prop) {
+    const type = prop["type"];
+    switch (type) {
+        case "string": {
+            const values = prop["enum"];
+            if (Array.isArray(values) &&
+                values.every((v) => isString(v)) &&
+                values.length > 0) {
+                return z.enum(values);
+            }
+            return z.string();
+        }
+        case "number":
+        case "integer":
+            return z.number();
+        case "boolean":
+            return z.boolean();
+        case "array": {
+            const items = prop["items"];
+            return z.array(items ? jsonSchemaPropToZod(items) : z.unknown());
+        }
+        case "object":
+            return z.record(z.string(), z.unknown());
+        default:
+            return z.unknown();
+    }
+}
+function jsonSchemaToZodShape(schema) {
+    const shape = {};
+    const s = schema;
+    if (!s || s["type"] !== "object")
+        return shape;
+    const properties = s["properties"];
+    if (!properties)
+        return shape;
+    const required = new Set(Array.isArray(s["required"]) ? s["required"] : []);
+    for (const [key, prop] of Object.entries(properties)) {
+        let zt = jsonSchemaPropToZod(prop);
+        if (isString(prop["description"])) {
+            zt = zt.describe(prop["description"]);
+        }
+        if ("default" in prop) {
+            zt = zt.default(prop["default"]);
+        }
+        else if (!required.has(key)) {
+            zt = zt.optional();
+        }
+        shape[key] = zt;
+    }
+    return shape;
+}
+// ── MCP response helpers ────────────────────────────────────────────
+function isErrorResult(result) {
+    if (!isRecord(result))
+        return false;
+    const r = result;
+    return Boolean(r["error"]) || r["success"] === false;
+}
+function toToolResponse(result) {
+    const isObject = isRecord(result);
+    const isError = isErrorResult(result);
+    const base = {
+        content: [{ type: "text", text: JSON.stringify(result ?? null) }]
+    };
+    const withError = isError ? { ...base, isError: true } : base;
+    return isObject && !isError
+        ? { ...withError, structuredContent: result }
+        : withError;
+}
+async function toImageToolResponse(result, context) {
+    const extracted = extractInjectableImages(result);
+    if (!extracted || isErrorResult(result)) {
+        return toToolResponse(result);
+    }
+    const response = toToolResponse(stripImagePayload(result));
+    const images = await Promise.all(extracted.images.map(async ({ image }) => {
+        const bytes = await loadMediaRefBytes(image, context);
+        if (!bytes?.length) {
+            throw new Error("Could not load image bytes for the MCP response.");
+        }
+        return {
+            type: "image",
+            data: Buffer.from(bytes).toString("base64"),
+            mimeType: detectImageMime(bytes)
+        };
+    }));
+    return { ...response, content: [...response.content, ...images] };
+}
+function errorResponse(err) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    error: err instanceof Error ? err.message : String(err)
+                })
+            }
+        ],
+        isError: true
+    };
+}
+/**
+ * Every agent tool the bridge offers, in registration order. Derived from the
+ * same catalogs `websocket-client-session` assembles a chat toolbelt from, so
+ * the two surfaces cannot drift.
+ *
+ * Dependency resolution is deferred to the session-owned capability run.
+ */
+function collectBridgedSpecs(options) {
+    return [
+        ...availableBuiltinToolNames().map((name) => capabilityForName(name).spec),
+        ...getAllMcpCapabilitySpecs({ registry: options?.registry }),
+        ...(isGoogleWorkspaceEnabled() ? GOOGLE_WORKSPACE_TOOL_NAMES : []).map((name) => capabilityForName(name).spec),
+        ...[...APIFY_TOOL_NAMES, ...SERPAPI_TOOL_NAMES, "find_model", "list_models"].map((name) => capabilityForName(name).spec)
+    ];
+}
+/**
+ * The gate an MCP session runs under: `auto`, denying every escalation the
+ * ladder raises, with one standing approval.
+ *
+ * `auto` is D4 — a client's user connected this agent deliberately, and the
+ * session has no approval UI of its own, so a gate that could ask would only
+ * deadlock. The approver therefore denies: resolving `"allow"` would grant
+ * exactly what an escalation exists to withhold, and never resolving would
+ * hang the run (invariant I-4).
+ *
+ * The exception is `execute_code` itself, seeded into `sessionAllow`. Every
+ * action arrives as an MCP tool call the *client* put in front of its user —
+ * with the code in it — before sending it, and `sessionAllow` is the ladder's
+ * own channel for "the user already said yes". Without the seed,
+ * `admitCodeAction` would refuse every action that does not declare
+ * `risk: "low"` (an omitted declaration reads as `high`), which is most of
+ * them: the mount would answer and never act. Escalations raised *inside* a
+ * run — an Apify actor this install has not allowlisted, a security-monitor
+ * consult — are a different matter and still deny, because nothing here can
+ * put those in front of that user.
+ */
+function mcpSessionGate() {
+    const gate = headlessGate("MCP");
+    gate.sessionAllow.add(EXECUTE_CODE_TOOL_NAME);
+    return gate;
+}
+/** URI of the structured capability catalog this mount publishes. */
+export const MCP_CAPABILITIES_RESOURCE_URI = "nodetool://capabilities";
+/** URI of the guest-JS surface this mount publishes. Re-exported for callers. */
+export { MCP_SANDBOX_RESOURCE_URI };
+const RENDERER_ID_PROPERTY = {
+    type: "string",
+    description: "Target a specific connected NodeTool editor. Omit to use the " +
+        "most-recently-active one. List ids with list_renderers()."
+};
+function recordValue(value) {
+    return isRecord(value) ? value : {};
+}
+async function executeFrontendTool(options, userId, name, args) {
+    const registry = options.frontendRendererRegistry;
+    if (!registry)
+        return { handled: false };
+    const { renderer_id, ...toolArgs } = args;
+    return registry.execute({
+        userId,
+        rendererId: isString(renderer_id) ? renderer_id : undefined,
+        toolName: name,
+        args: toolArgs
+    });
+}
+/** Import a local file or a URL into the current user's asset library. */
+class ImportAssetTool extends Tool {
+    localFilePathsAllowed;
+    saveAsset;
+    name = "import_asset";
+    description = "Import a local file on a local MCP connection or an http(s) URL as a NodeTool asset. Returns its asset URI, size and media duration.";
+    jsonSchema = {
+        type: "object",
+        properties: {
+            path: {
+                type: "string",
+                description: "Absolute server-local path; local connections only."
+            },
+            url: { type: "string", description: "HTTP or HTTPS URL to fetch." },
+            name: { type: "string", description: "Optional asset name." },
+            content_type: { type: "string", description: "Optional MIME type." }
+        },
+        required: []
+    };
+    constructor(localFilePathsAllowed, saveAsset) {
+        super();
+        this.localFilePathsAllowed = localFilePathsAllowed;
+        this.saveAsset = saveAsset;
+    }
+    async process(context, params) {
+        const path = params["path"];
+        const url = params["url"];
+        if (isString(path) === isString(url)) {
+            throw new Error("Provide exactly one of path or url.");
+        }
+        if (isString(path) && (!this.localFilePathsAllowed || !isAbsolute(path))) {
+            throw new Error("path requires an absolute path on a local MCP connection.");
+        }
+        if (isString(url) && !/^https?:\/\//.test(url)) {
+            throw new Error("url must be an HTTP or HTTPS URL.");
+        }
+        const sourceName = isString(path)
+            ? basename(path)
+            : basename(new URL(url).pathname) || "download";
+        const name = isString(params["name"]) && params["name"].trim()
+            ? params["name"].trim()
+            : sourceName;
+        let result;
+        if (isString(path)) {
+            const bytes = await readFile(path);
+            const asset = await createAssetModelInterface({
+                userId: context.userId,
+                name,
+                contentType: isString(params["content_type"])
+                    ? params["content_type"]
+                    : "",
+                content: bytes
+            });
+            result = {
+                asset_id: asset.id,
+                asset_uri: `asset://${asset.id}`,
+                size: bytes.length
+            };
+        }
+        else {
+            const saveParams = {
+                name,
+                source: url
+            };
+            if (isString(params["content_type"])) {
+                saveParams["content_type"] = params["content_type"];
+            }
+            result = await this.saveAsset(saveParams);
+        }
+        if (!isRecord(result) || !isString(result["asset_id"]))
+            return result;
+        const asset = await Asset.find(context.userId, result["asset_id"]);
+        if (!asset)
+            return result;
+        return {
+            ...result,
+            asset_uri: `asset://${asset.id}`,
+            content_type: normalizeAssetContentType(asset.content_type, asset.name),
+            size: asset.size,
+            duration: asset.duration
+        };
+    }
+}
+class RenderDemoSurfaceTool extends Tool {
+    name = "render_demo_surface";
+    description = "Render a NodeTool product surface as a silent video asset. Cast IDs: chat hero-brief or chat-agent-qa; storyboard hero-storyboard or storyboard-assistant; script script-assistant; sketch sketch-assistant; timeline hero-timeline or promo-timeline; graph promo-trailer. A range plays at recorded speed unless duration_ms compresses it. For exact frame matching at 30 fps, duration_ms may be a multiple of 1000/30; sample_span_frames selects the cast range's interpolation span independently of output length. Available from a NodeTool source checkout with the demo renderer installed.";
+    jsonSchema = {
+        type: "object",
+        properties: {
+            surface: {
+                type: "string",
+                enum: ["chat", "storyboard", "script", "sketch", "timeline", "graph", "3d"]
+            },
+            cast_id: {
+                type: "string",
+                description: "Cast ID for the selected surface. See the tool description for valid IDs."
+            },
+            from_ms: {
+                type: "number",
+                description: "Source range start in milliseconds; provide with to_ms."
+            },
+            to_ms: {
+                type: "number",
+                description: "Source range end in milliseconds; provide with from_ms."
+            },
+            duration_ms: { type: "number", description: "Output duration in milliseconds for a ranged cast; compresses or expands the selected range." },
+            sample_span_frames: { type: "number", description: "Frame span from source range start to end. Defaults to output frame count minus one. Use 79 for the sizzle montage's cast clock." },
+            logical_width: { type: "number", description: "CSS layout width of the product surface before scaling to the output width." },
+            output_width: { type: "number", description: "Even output video width in pixels." },
+            output_height: { type: "number", description: "Even output video height in pixels." },
+            viewport: { type: "object", description: "Graph viewport {x, y, zoom} in logical surface pixels.", properties: { x: { type: "number" }, y: { type: "number" }, zoom: { type: "number" } }, required: ["x", "y", "zoom"] },
+            tracks_height_px: { type: "number", description: "Timeline track area height in logical CSS pixels." },
+            chrome: { type: "boolean", description: "Show timeline editor chrome; defaults to false." },
+            label: {
+                type: "boolean",
+                description: "Show the corner label; defaults to false."
+            }
+        },
+        required: ["surface"]
+    };
+    async process(context, params) {
+        const surface = params["surface"];
+        if (!isString(surface) ||
+            !["chat", "storyboard", "script", "sketch", "timeline", "graph", "3d"].includes(surface)) {
+            throw new Error("surface must be chat, storyboard, script, sketch, timeline, graph or 3d.");
+        }
+        const fromMs = params["from_ms"];
+        const toMs = params["to_ms"];
+        if (fromMs !== undefined &&
+            (typeof fromMs !== "number" || !Number.isFinite(fromMs) || fromMs < 0)) {
+            throw new Error("from_ms must be a nonnegative number.");
+        }
+        if (toMs !== undefined &&
+            (typeof toMs !== "number" || !Number.isFinite(toMs) || toMs <= 0)) {
+            throw new Error("to_ms must be a positive number.");
+        }
+        if (typeof fromMs === "number" &&
+            typeof toMs === "number" &&
+            toMs <= fromMs) {
+            throw new Error("to_ms must exceed from_ms.");
+        }
+        if ((fromMs === undefined) !== (toMs === undefined)) {
+            throw new Error("from_ms and to_ms must be supplied together.");
+        }
+        if (surface === "3d" && typeof toMs === "number" && toMs > 6000) {
+            throw new Error("The 3d surface range must end by 6000 ms.");
+        }
+        const casts = {
+            chat: ["hero-brief", "chat-agent-qa"],
+            storyboard: ["hero-storyboard", "storyboard-assistant"],
+            script: ["script-assistant"],
+            sketch: ["sketch-assistant"],
+            timeline: ["hero-timeline", "promo-timeline"],
+            graph: ["promo-trailer"],
+            "3d": []
+        };
+        const castId = params["cast_id"];
+        if (castId !== undefined && (!isString(castId) || !casts[surface]?.includes(castId))) {
+            throw new Error(`cast_id for ${surface} must be one of: ${casts[surface]?.join(", ") || "none"}.`);
+        }
+        const durationMs = params["duration_ms"];
+        if (durationMs !== undefined &&
+            (typeof durationMs !== "number" || !Number.isFinite(durationMs) || durationMs <= 0 || typeof fromMs !== "number")) {
+            throw new Error("duration_ms requires a source range and must be positive.");
+        }
+        const sampleSpanFrames = params["sample_span_frames"];
+        if (sampleSpanFrames !== undefined &&
+            (typeof sampleSpanFrames !== "number" || !Number.isInteger(sampleSpanFrames) || sampleSpanFrames <= 0 || typeof fromMs !== "number")) {
+            throw new Error("sample_span_frames requires a source range and must be a positive integer.");
+        }
+        for (const key of ["logical_width", "tracks_height_px"]) {
+            const value = params[key];
+            if (value !== undefined && (typeof value !== "number" || !Number.isFinite(value) || value <= 0)) {
+                throw new Error(`${key} must be a positive number.`);
+            }
+        }
+        for (const key of ["output_width", "output_height"]) {
+            const value = params[key];
+            if (value !== undefined && (typeof value !== "number" || !Number.isInteger(value) || value <= 0 || value % 2 !== 0)) {
+                throw new Error(`${key} must be a positive even integer.`);
+            }
+        }
+        const viewport = params["viewport"];
+        if (viewport !== undefined &&
+            (surface !== "graph" || !isRecord(viewport) ||
+                ["x", "y", "zoom"].some((key) => typeof viewport[key] !== "number" || !Number.isFinite(viewport[key])) ||
+                typeof viewport["zoom"] !== "number" || viewport["zoom"] <= 0)) {
+            throw new Error("viewport requires graph and finite x, y and positive zoom.");
+        }
+        if (params["tracks_height_px"] !== undefined && surface !== "timeline") {
+            throw new Error("tracks_height_px requires the timeline surface.");
+        }
+        const demoDir = join(dirname(fileURLToPath(import.meta.url)), "../../../demo");
+        const renderer = join(demoDir, "../node_modules/.bin/remotion");
+        try {
+            await stat(renderer);
+            await stat(join(demoDir, "src/index.ts"));
+        }
+        catch {
+            throw new Error("The demo renderer is unavailable on this NodeTool server.");
+        }
+        const props = {};
+        if (isString(castId))
+            props["castId"] = castId;
+        if (typeof fromMs === "number")
+            props["fromMs"] = fromMs;
+        if (typeof toMs === "number")
+            props["toMs"] = toMs;
+        if (typeof durationMs === "number") {
+            props["durationMs"] = durationMs;
+            props["realtime"] = false;
+        }
+        if (typeof sampleSpanFrames === "number")
+            props["sampleSpanFrames"] = sampleSpanFrames;
+        if (typeof params["logical_width"] === "number")
+            props["logicalWidth"] = params["logical_width"];
+        if (typeof params["output_width"] === "number")
+            props["outputWidth"] = params["output_width"];
+        if (typeof params["output_height"] === "number")
+            props["outputHeight"] = params["output_height"];
+        if (viewport !== undefined)
+            props["viewport"] = viewport;
+        if (typeof params["tracks_height_px"] === "number")
+            props["tracksHeightPx"] = params["tracks_height_px"];
+        if (typeof params["chrome"] === "boolean")
+            props["chrome"] = params["chrome"];
+        const ranged = typeof fromMs === "number";
+        if (ranged)
+            props["labelVisible"] = params["label"] === true;
+        const composition = `Surface-${surface}${ranged ? "-Harness" : params["label"] === true ? "" : "-Clean"}`;
+        const directory = await mkdtemp(join(tmpdir(), "nodetool-surface-"));
+        const output = join(directory, `${surface}.mp4`);
+        try {
+            await execFile(renderer, [
+                "render",
+                "src/index.ts",
+                composition,
+                output,
+                "--props",
+                JSON.stringify(props),
+                ...(surface === "3d" ? ["--gl=angle"] : [])
+            ], {
+                cwd: demoDir,
+                timeout: 300_000,
+                maxBuffer: 2 * 1024 * 1024
+            });
+            const bytes = await readFile(output);
+            const asset = await createAssetModelInterface({
+                userId: context.userId,
+                name: `${surface}-surface.mp4`,
+                contentType: "video/mp4",
+                content: bytes
+            });
+            return {
+                asset_id: asset.id,
+                asset_uri: `asset://${asset.id}`,
+                duration: asset.duration,
+                size: asset.size,
+                content_type: asset.content_type
+            };
+        }
+        finally {
+            await rm(directory, { recursive: true, force: true });
+        }
+    }
+}
+/** A `ui_*` request that must be handled by a connected editor. */
+class FrontendUiTool extends Tool {
+    options;
+    userId;
+    name;
+    description;
+    jsonSchema;
+    constructor(name, description, jsonSchema, options, userId) {
+        super();
+        this.options = options;
+        this.userId = userId;
+        this.name = name;
+        this.description = description;
+        this.jsonSchema = jsonSchema;
+    }
+    // HOLDOUT (anti-slop/no-unknown-returns): a bridged tool's result is
+    // whatever the editor or capability answered — the open tool-result domain
+    // the base `Tool.process` contract in `@nodetool-ai/agents` declares.
+    async process(_context, params) {
+        const outcome = await executeFrontendTool(this.options, this.userId, this.name, params);
+        if (!outcome.handled) {
+            const rendererId = params["renderer_id"];
+            throw new Error(isString(rendererId)
+                ? `No connected NodeTool renderer with id "${rendererId}".`
+                : `${this.name} needs a connected NodeTool editor; none is open.`);
+        }
+        return outcome.result;
+    }
+}
+/** `list_renderers` as a belt tool: which editors a `ui_*` call could target. */
+class ListRenderersTool extends Tool {
+    options;
+    userId;
+    name = "list_renderers";
+    description = "List connected NodeTool editor renderers that can run ui_* tools. Pass a " +
+        "returned renderer_id to a ui_* tool to target that editor; omit it to use " +
+        "the active one.";
+    jsonSchema = {
+        type: "object",
+        properties: {}
+    };
+    constructor(options, userId) {
+        super();
+        this.options = options;
+        this.userId = userId;
+    }
+    async process() {
+        const renderers = this.options.frontendRendererRegistry
+            ? this.options.frontendRendererRegistry
+                .list(this.userId)
+                .map((renderer, index) => ({
+                renderer_id: renderer.renderer_id,
+                active: index === 0
+            }))
+            : [];
+        return { renderers };
+    }
+}
+/**
+ * The `ui_*` schemas that steer a connected editor rather than edit a
+ * persisted workflow document, plus `list_renderers`.
+ */
+function editorSteeringTools(options, userId) {
+    const documentToolNames = new Set(WORKFLOW_DOCUMENT_TOOL_NAMES);
+    const tools = [new ListRenderersTool(options, userId)];
+    for (const [name, schema] of Object.entries(uiToolSchemas)) {
+        if (documentToolNames.has(name))
+            continue;
+        const params = zodToJsonSchema(z.object(schema.parameters));
+        const properties = {
+            ...recordValue(params["properties"]),
+            renderer_id: RENDERER_ID_PROPERTY
+        };
+        tools.push(new FrontendUiTool(name, schema.description, { ...params, type: "object", properties }, options, userId));
+    }
+    return tools;
+}
+/** First sentence of a tool description, for the capabilities catalog. */
+function oneLine(description) {
+    const flat = description.replace(/\s+/g, " ").trim();
+    const stop = flat.indexOf(". ");
+    const line = stop > 0 ? flat.slice(0, stop + 1) : flat;
+    return line.length > 200 ? `${line.slice(0, 197)}…` : line;
+}
+/**
+ * The machine-readable form of what this session can do, served as the
+ * `nodetool://capabilities` resource. A client that lists two tools learns the
+ * contract from the `execute_code` description, which is right for a model and
+ * poor for tooling; this is the same catalog with structure, and costs nothing
+ * at list time.
+ */
+function buildCapabilityCatalog(belt, directToolNames) {
+    const available = new Set(belt.map((tool) => tool.name));
+    const modules = Object.entries(NODETOOL_API_NAMESPACE_TOOLS)
+        .map(([namespace, names]) => ({
+        namespace,
+        import: `nodetool.${namespace}`,
+        exports: names.filter((name) => available.has(name))
+    }))
+        .filter((entry) => entry.exports.length > 0);
+    return {
+        server: "nodetool",
+        direct_tools: directToolNames,
+        modules,
+        tools: belt
+            .map((tool) => ({
+            name: tool.name,
+            description: oneLine(tool.description),
+            permission_category: tool.category
+        }))
+            .sort((a, b) => a.name.localeCompare(b.name))
+    };
+}
+/**
+ * Register the agent surface on `server`: CodeAct, image viewing, asset
+ * transfer, and the promoted direct tools.
+ *
+ * `gate` defaults to {@link mcpSessionGate} — `auto` with an approver that
+ * denies, because an MCP session has no user of its own to ask. A host that
+ * does have an approval channel passes its own gate instead.
+ *
+ * Everything else the catalogs offer becomes the sandbox belt instead of an MCP
+ * tool. It stays fully reachable — `tools.<name>()`, the `nodetool.*` object
+ * model, `await nodetool.searchTools("query")` — and the `execute_code` description
+ * carries the same contract and catalog the chat runner puts in its system
+ * prompt, because MCP has no system prompt to put it in.
+ */
+export function registerAgentMcpTools(server, options, gate = mcpSessionGate()) {
+    // Every bridged tool runs against one user's secrets and assets, so a session
+    // without an explicit user binding has no surface at all — a default user
+    // here would cross the tenant boundary on any mount serving more than one
+    // caller. `createMcpServer` refuses such a session before reaching here.
+    const scope = options.agentToolsScope;
+    if (!scope) {
+        throw new Error("registerAgentMcpTools requires options.agentToolsScope: an MCP session " +
+            "must be bound to a user id.");
+    }
+    const localFilePathsAllowed = scope.source === "stdio-local" || options.allowLocalFilePaths === true;
+    const context = buildAgentToolContext(scope.userId);
+    // Populated lazily on first `find_model` call — provider probing hits the
+    // secret store and network, so it's deferred out of server construction.
+    const sharedProviders = {};
+    let providersPromise = null;
+    const ensureProviders = () => {
+        if (!providersPromise) {
+            providersPromise = loadConfiguredProviders(scope.userId).then((loaded) => {
+                Object.assign(sharedProviders, loaded);
+            });
+        }
+        return providersPromise;
+    };
+    // The gate: `auto` with the headless deny, `mcpSessionGate` above. What
+    // bounds this surface is the session's user binding, not a per-call
+    // question the mount has nobody to ask.
+    //
+    // The codeact session mounts this run, so an action can import
+    // `@nodetool-ai/sandbox-nodetool/<namespace>` and land on `run.invoke`; the
+    // same run handles `tools.<name>()` and direct MCP registrations.
+    const workflowDocumentToolNames = new Set(WORKFLOW_DOCUMENT_TOOL_NAMES);
+    /**
+     * Run one bridged tool. The single execution path for both surfaces — a
+     * direct MCP call and a `tools.<name>()` call inside an action — so a
+     * capability cannot behave differently depending on how it was reached.
+     */
+    // HOLDOUT (anti-slop/no-unknown-returns): one path for every bridged tool,
+    // so the result is the open tool-result domain `Tool.process` declares.
+    const runBridgedTool = async (tool, args) => {
+        return capabilityRun.invoke(tool.name, args);
+    };
+    const register = (tool) => {
+        const isImageTool = tool.name === "view_image";
+        const schema = { ...jsonSchemaToZodShape(tool.inputSchema) };
+        if (isImageTool) {
+            schema["image_id"] = z
+                .string()
+                .describe("An asset id, asset:// URI, public https:// URL, or data: URI. " +
+                "Local MCP connections also accept an absolute disk image path or file:// URI.");
+        }
+        server.tool(tool.name, tool.description +
+            (isImageTool
+                ? " Returns MCP image content so you can see the pixels. On local MCP connections, image_id also accepts an absolute disk path or file:// URI."
+                : ""), schema, async (args) => {
+            try {
+                const input = { ...args };
+                const imageId = isImageTool && isString(input["image_id"])
+                    ? input["image_id"].trim()
+                    : undefined;
+                const isDiskImage = imageId &&
+                    !imageId.startsWith("/api/storage/") &&
+                    (isAbsolute(imageId) || imageId.startsWith("file://"));
+                if (isDiskImage) {
+                    if (!localFilePathsAllowed) {
+                        throw new Error("Disk image paths require a local MCP connection. Use an asset id on remote sessions.");
+                    }
+                    const path = imageId.startsWith("file://")
+                        ? fileURLToPath(imageId)
+                        : imageId;
+                    const bytes = await readFile(path);
+                    await sharp(bytes).metadata();
+                    const mime = isSvgBytes(bytes)
+                        ? "image/svg+xml"
+                        : detectImageMime(bytes);
+                    input["image_id"] =
+                        `data:${mime};base64,${bytes.toString("base64")}`;
+                    if (!isString(input["question"]) || !input["question"].trim()) {
+                        input["question"] = `Image ${imageId}:`;
+                    }
+                }
+                else if (imageId?.startsWith("data:")) {
+                    if (!isString(input["question"]) || !input["question"].trim()) {
+                        input["question"] = "Inline image:";
+                    }
+                }
+                const result = await runBridgedTool(tool, input);
+                if (!isImageTool) {
+                    return toToolResponse(result);
+                }
+                if (isRecord(result) && imageId && !isErrorResult(result)) {
+                    result["image_id"] = imageId.startsWith("data:")
+                        ? "inline image"
+                        : imageId;
+                }
+                return await toImageToolResponse(result, context);
+            }
+            catch (err) {
+                return errorResponse(err);
+            }
+        });
+    };
+    // The belt the sandbox sees. Deduped by name, because the two catalogs
+    // overlap and a session must not offer one tool under two instances.
+    const hostCapabilities = [];
+    const legacyEntries = [
+        new ImportAssetTool(localFilePathsAllowed, (args) => capabilityRun.invoke("save_asset", args)),
+        new RenderDemoSurfaceTool(),
+        ...editorSteeringTools(options, scope.userId)
+    ].map(capabilityFromTool);
+    const entries = [
+        ...legacyEntries,
+        ...collectBridgedSpecs(options).map((spec) => capabilityForName(spec.name))
+    ];
+    const belt = [];
+    const beltNames = new Set();
+    for (const entry of entries) {
+        const tool = entry.spec;
+        if (beltNames.has(tool.name)) {
+            continue;
+        }
+        beltNames.add(tool.name);
+        const spec = workflowDocumentToolNames.has(tool.name)
+            ? {
+                ...tool,
+                zodSchema: tool.zodSchema instanceof z.ZodObject
+                    ? tool.zodSchema.extend({ renderer_id: z.string().optional() })
+                    : tool.zodSchema,
+                inputSchema: {
+                    ...tool.inputSchema,
+                    properties: {
+                        ...recordValue(tool.inputSchema["properties"]),
+                        renderer_id: RENDERER_ID_PROPERTY
+                    }
+                }
+            }
+            : tool;
+        belt.push(spec);
+        hostCapabilities.push({
+            spec,
+            impl: async (run, args) => {
+                // Model search and workflow readiness read the configured-providers map at
+                // call time, so populate it before either handler runs. Without the
+                // workflow entries, the first plan/build call sees the lazy map while it
+                // is still empty and reports a false missing-provider blocker.
+                if (tool.name === "find_model" ||
+                    tool.name === "list_models" ||
+                    WORKFLOW_READINESS_TOOL_NAMES.has(tool.name)) {
+                    await ensureProviders();
+                }
+                const isWorkflowDocumentTool = workflowDocumentToolNames.has(tool.name);
+                const isFrontendTool = tool.name.startsWith("ui_");
+                if (isWorkflowDocumentTool || isFrontendTool) {
+                    const live = await executeFrontendTool(options, scope.userId, tool.name, args);
+                    if (live.handled) {
+                        return live.result;
+                    }
+                    const rendererId = args["renderer_id"];
+                    if (isString(rendererId)) {
+                        throw new Error(`No connected NodeTool renderer with id "${rendererId}".`);
+                    }
+                    // Workflow document tools have a server-side implementation and use the
+                    // live editor when one is available. Other editor tools only exist in a
+                    // connected renderer, so report the missing target clearly.
+                    if (isFrontendTool && !isWorkflowDocumentTool) {
+                        throw new Error(`${tool.name} needs a connected NodeTool editor; none is open.`);
+                    }
+                }
+                const { renderer_id: _rendererId, ...serverArgs } = args;
+                return entry.impl(run, serverArgs);
+            }
+        });
+    }
+    const capabilityRun = createCapabilityRun({
+        capabilities: hostCapabilities,
+        context,
+        gate,
+        availableSecrets: contextSecretAvailability(context),
+        nodeRegistry: options.registry,
+        ...mcpToolHostDeps({
+            registry: options.registry,
+            metadataRoots: options.metadataRoots,
+            metadataMaxDepth: options.metadataMaxDepth,
+            examplesDir: options.examplesDir
+        }),
+        providers: sharedProviders,
+        loaders: { timeline: loadTimelineForUser, sketch: loadSketchForUser }
+    });
+    const byName = new Map(belt.map((tool) => [tool.name, tool]));
+    // `view_image` is the one channel that puts pixels into a caller's context,
+    // and pixels cannot ride the sandbox's JSON observation envelope — so it is a
+    // direct tool and is kept off the belt, exactly as the chat runner does.
+    const beltForSandbox = belt.filter((tool) => tool.name !== "view_image");
+    // The direct set, derived the way the CLI turn and the websocket runner
+    // derive theirs — minus the tools an MCP *client* already serves natively.
+    //
+    // `DIRECT_TOOL_NAMES` goes top level everywhere else because those are the
+    // shapes models are trained on, so a sandbox round trip whose only job is to
+    // forward one buys nothing. That argument holds here too. What does not hold
+    // is the file/search half: `SDK_NATIVE_TOOL_REPLACEMENTS` already names the
+    // tools a host agent covers with its own — and an MCP client (Claude Code,
+    // ChatGPT) is that host. Offering NodeTool's workspace-scoped `read_file`
+    // beside the client's own would put two tools of one name and two different
+    // roots in front of the same model.
+    //
+    // What is left has no host equivalent: discovery (which providers, models
+    // and node types this install has — a guess there is a hallucinated id that
+    // fails at generation time, after the run was paid for), the server-side
+    // reach that runs behind NodeTool's own SSRF guard and secrets, and
+    // `run_subtask`, whose child gets the NodeTool belt rather than the client's.
+    //
+    // Derived from both tables rather than hand-listed, so a tool added to
+    // either reaches this mount with no edit here.
+    const promotedDirect = belt.filter((tool) => DIRECT_TOOL_NAMES.has(tool.name) &&
+        !SDK_NATIVE_TOOL_REPLACEMENTS.has(tool.name));
+    // They stay on the belt: an action still calls them from code. Listing them
+    // as direct only moves where the prompt documents them.
+    const directToolNames = [
+        "view_image",
+        ...promotedDirect.map((tool) => tool.name)
+    ];
+    const session = createChatCodeActSession({
+        tools: beltForSandbox.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema
+        })),
+        directToolNames,
+        residentToolNames: CODEACT_RESIDENT_TOOL_NAMES,
+        executeTool: async (call) => {
+            const tool = byName.get(call.name);
+            if (!tool)
+                throw new Error(`Unknown tool: ${call.name}`);
+            return runBridgedTool(tool, call.args);
+        },
+        capabilityRun
+    });
+    // The action tool. MCP has no system prompt, so the guest contract, the
+    // catalog and the sandbox summary ride in the description — the only field
+    // every MCP client is guaranteed to show the model. The short contract
+    // leads: many clients truncate a long description.
+    // `title` is a display label for NodeTool's own chat UI, and the action path
+    // never reads it — `executeAction` takes `code` and discards the rest. On the
+    // provider tool it is required because a system prompt teaches the contract
+    // and the label is what the user watches. MCP has neither: a client whose
+    // model skipped a field this server does not use had its whole action
+    // rejected on validation. It stays in the schema — described, and the
+    // contract in the description still asks for one — but is optional here.
+    //
+    // `risk` is optional here for the same reason, and it still decides
+    // nothing: `admitCodeAction` reads the standing `execute_code` approval in
+    // this session's gate (see `mcpSessionGate`) before it looks at the declared
+    // risk, because the client already asked its user about this very call.
+    //
+    // `description` follows `risk`: it is the text an approval dialog asks the
+    // user about, and this surface never opens one.
+    const optionalOnMcp = new Set(["title", "risk", "description"]);
+    const actionSchema = session.providerTool.inputSchema;
+    const actionShape = jsonSchemaToZodShape({
+        ...actionSchema,
+        required: (Array.isArray(actionSchema["required"])
+            ? actionSchema["required"]
+            : []).filter((name) => !optionalOnMcp.has(name))
+    });
+    server.tool(session.providerTool.name, `${MCP_GUEST_CONTRACT}\n\n${session.providerTool.description}\n\n${session.systemPromptSection}`, actionShape, async (args) => {
+        try {
+            // The session already returns the observation envelope as JSON text.
+            // Passing it through `toToolResponse` would encode it a second time
+            // and hand the caller a quoted string instead of an object.
+            const observation = await session.executeAction(args ?? {});
+            return {
+                content: [{ type: "text", text: observation }]
+            };
+        }
+        catch (err) {
+            return errorResponse(err);
+        }
+    });
+    // `view_image` carries image content, which an action's observation envelope
+    // cannot, so it is direct for a reason no other tool shares.
+    const viewImage = byName.get("view_image");
+    if (viewImage)
+        register(viewImage);
+    // The rest of the direct set, for parity with every other entrance.
+    for (const tool of promotedDirect)
+        register(tool);
+    server.tool("upload_asset", "Upload bytes to this user's NodeTool asset library. Pass content_base64 " +
+        "from any MCP client, or an absolute file_path on a local connection. " +
+        "The path is on the NodeTool server, not on a remote MCP client's machine.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Asset name; defaults to the file name for file_path."),
+        content_base64: z
+            .string()
+            .optional()
+            .describe("File bytes encoded as base64."),
+        file_path: z
+            .string()
+            .optional()
+            .describe("Absolute server-local file path; local connections only."),
+        content_type: z
+            .string()
+            .optional()
+            .describe("MIME type; inferred from file_path or name when omitted.")
+    }, async ({ name, content_base64, file_path, content_type }) => {
+        try {
+            if (Boolean(content_base64) === Boolean(file_path)) {
+                throw new Error("Provide exactly one of content_base64 or file_path.");
+            }
+            if (file_path && (!localFilePathsAllowed || !isAbsolute(file_path))) {
+                throw new Error("file_path requires an absolute path on a local MCP connection.");
+            }
+            const assetName = name?.trim() || (file_path ? basename(file_path) : "");
+            if (!assetName)
+                throw new Error("name is required for a base64 upload.");
+            if (content_base64 &&
+                !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(content_base64)) {
+                throw new Error("content_base64 must be valid base64.");
+            }
+            const bytes = file_path
+                ? await readFile(file_path)
+                : Buffer.from(content_base64 ?? "", "base64");
+            const asset = await createAssetModelInterface({
+                userId: scope.userId,
+                name: assetName,
+                contentType: normalizeAssetContentType(content_type ?? "", file_path ?? assetName),
+                content: bytes
+            });
+            return toToolResponse({
+                asset_id: asset.id,
+                asset_uri: `asset://${asset.id}`,
+                name: asset.name,
+                content_type: asset.content_type,
+                size: bytes.length
+            });
+        }
+        catch (err) {
+            return errorResponse(err);
+        }
+    });
+    server.tool("download_asset", "Download an asset owned by this user. Returns content_base64, or writes " +
+        "to an absolute output_path on a local connection. The path is on the " +
+        "NodeTool server, not on a remote MCP client's machine.", {
+        asset_id: z
+            .string()
+            .describe("Asset ID returned by upload_asset or list_assets."),
+        output_path: z
+            .string()
+            .optional()
+            .describe("Absolute server-local output path; local connections only.")
+    }, async ({ asset_id, output_path }) => {
+        try {
+            if (output_path &&
+                (!localFilePathsAllowed || !isAbsolute(output_path))) {
+                throw new Error("output_path requires an absolute path on a local MCP connection.");
+            }
+            const asset = await Asset.find(scope.userId, asset_id);
+            if (!asset || asset.isFolder)
+                throw new Error("Asset not found.");
+            const bytes = await loadMediaRefBytes({ asset_id: asset.id }, context);
+            if (!bytes)
+                throw new Error("Asset bytes not found.");
+            if (output_path)
+                await writeFile(output_path, bytes);
+            return toToolResponse({
+                asset_id: asset.id,
+                name: asset.name,
+                content_type: asset.content_type,
+                size: bytes.length,
+                ...(output_path
+                    ? { output_path }
+                    : { content_base64: Buffer.from(bytes).toString("base64") })
+            });
+        }
+        catch (err) {
+            return errorResponse(err);
+        }
+    });
+    // The structured catalog, for clients that want more than a description.
+    const catalog = buildCapabilityCatalog(belt, [
+        session.providerTool.name,
+        ...directToolNames,
+        "upload_asset",
+        "download_asset"
+    ]);
+    server.registerResource("NodeTool Capabilities", MCP_CAPABILITIES_RESOURCE_URI, {
+        description: "What this NodeTool session can do: the nodetool.* modules mounted for " +
+            "it, every tool an execute_code action can call, and each tool's " +
+            "permission category.",
+        mimeType: "application/json"
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "application/json",
+                text: JSON.stringify(catalog, null, 2)
+            }
+        ]
+    }));
+    const sandbox = buildMcpSandboxCatalog();
+    server.registerResource("NodeTool Sandbox", MCP_SANDBOX_RESOURCE_URI, {
+        description: "How to write execute_code: the guest contract, blocked globals, " +
+            "bridges this chat session cannot use, and two worked examples.",
+        mimeType: "application/json"
+    }, async (uri) => ({
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "application/json",
+                text: JSON.stringify(sandbox, null, 2)
+            }
+        ]
+    }));
+    for (const prompt of MCP_SANDBOX_PROMPTS) {
+        server.registerPrompt(prompt.name, {
+            title: prompt.title,
+            description: prompt.description
+        }, async () => ({
+            messages: [
+                {
+                    role: "user",
+                    content: { type: "text", text: prompt.snippet }
+                }
+            ]
+        }));
+    }
+    log.info("Registered agent MCP tools", {
+        userId: scope.userId,
+        source: scope.source,
+        registered: [
+            session.providerTool.name,
+            ...(viewImage ? ["view_image"] : []),
+            "upload_asset",
+            "download_asset"
+        ],
+        beltSize: belt.length
+    });
+    return capabilityRun;
+}
+//# sourceMappingURL=mcp-agent-tools.js.map