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

package/dist/codeact/graph-model.js

@@ -0,0 +1,408 @@
+/**
+ * CodeAct graph object model — workflow graph and node editing as a JS object
+ * model instead of one bridged `ui_*` tool call per mutation.
+ *
+ * The guest prelude defines `openWorkflow(workflowId?)`, which loads the graph
+ * once through `ui_get_graph` and returns a model whose mutators are
+ * synchronous: they update a local mirror and queue the equivalent `ui_*`
+ * operation. `commit()` replays the queue through the bridged tools — the same
+ * contract the renderer and the headless document tools already implement, so
+ * client/server routing, validation, and live-editor sync are untouched. One
+ * code action can therefore build a whole graph and pay one round trip per
+ * mutation only at commit time, with local reads in between.
+ *
+ * The prelude assumes `CODEACT_PRELUDE` ran first (it calls the belt through
+ * `__callBeltTool`).
+ */
+/** The `ui_*` document tools the object model drives. */
+export const GRAPH_MODEL_TOOL_NAMES = [
+    "ui_get_graph",
+    "ui_add_node",
+    "ui_connect_nodes",
+    "ui_update_node_data",
+    "ui_delete_node",
+    "ui_delete_edge",
+    "ui_move_node",
+    "ui_set_node_title"
+];
+/**
+ * The model needs the read plus the two constructive mutations; the rest
+ * degrade gracefully (an op whose tool is missing fails at commit with the
+ * tool named).
+ */
+const REQUIRED_TOOL_NAMES = ["ui_get_graph", "ui_add_node", "ui_connect_nodes"];
+/** Whether a toolbelt carries enough of the `ui_*` contract for the model. */
+export function hasGraphModelTools(toolNames) {
+    const names = new Set(toolNames);
+    return REQUIRED_TOOL_NAMES.every((name) => names.has(name));
+}
+/** Guest names {@link GRAPH_MODEL_PRELUDE} defines. */
+export const GRAPH_MODEL_GLOBALS = ["openWorkflow"];
+/**
+ * Guest-side prelude defining `openWorkflow()`. Plain QuickJS-safe JS — no
+ * host bridges of its own; every effect goes through the `ui_*` belt calls.
+ */
+export const GRAPH_MODEL_PRELUDE = `
+async function openWorkflow(workflowId) {
+  const __wfArgs = (extra) => {
+    const args = extra ? Object.assign({}, extra) : {};
+    if (workflowId !== undefined && workflowId !== null) {
+      args.workflow_id = workflowId;
+    }
+    return args;
+  };
+  const __snapNodes = (snap) => (snap && Array.isArray(snap.nodes) ? snap.nodes : []);
+  const __snapEdges = (snap) => (snap && Array.isArray(snap.edges) ? snap.edges : []);
+
+  const snap = await __callBeltTool("ui_get_graph")(__wfArgs());
+  const queueRoot =
+    typeof __graphQueues === "object" && __graphQueues !== null
+      ? __graphQueues
+      : {};
+  const queueKey = String((snap && snap.workflow_id) || workflowId || "__focused__");
+
+  // A ui_get_graph served from the saved row ("source": "server") is a
+  // read-only snapshot: no editor is open, so every queued write would fail at
+  // commit with "No node store". Say so here instead, before any op is queued.
+  const editable =
+    !snap || typeof snap.source !== "string" || snap.source === "editor";
+  const __requireEditable = () => {
+    if (!editable) {
+      throw new Error(
+        "openWorkflow(): this snapshot came from the server because no editor " +
+          "is open for workflow " + JSON.stringify(queueKey) + " — reads work, " +
+          "but every write would fail at commit(). Open it first: " +
+          "ui_open_document({type: 'workflow', id: <id>}) or ui_open_workflow" +
+          "({workflow_id: <id>}), then reopen it with openWorkflow."
+      );
+    }
+  };
+  const storedOps = queueRoot[queueKey];
+  const ops = Array.isArray(storedOps) ? storedOps : [];
+  queueRoot[queueKey] = ops;
+  let edgeSeq = 0;
+  for (const op of ops) {
+    const match =
+      op && typeof op.localEdgeId === "string"
+        ? /^pending_edge_(\\d+)$/.exec(op.localEdgeId)
+        : null;
+    if (match) edgeSeq = Math.max(edgeSeq, Number(match[1]));
+  }
+
+  const model = {
+    workflowId: (snap && snap.workflow_id) || workflowId || null,
+    editable,
+    nodes: [],
+    edges: [],
+    node(id) {
+      const found = model.nodes.find((n) => n.id === id);
+      if (!found) {
+        throw new Error(
+          "Node not found: " + id + ". Known: " + model.nodes.map((n) => n.id).join(", ")
+        );
+      }
+      return found;
+    },
+    addNode(id, type, properties, position) {
+      __requireEditable();
+      if (model.nodes.some((n) => n.id === id)) {
+        throw new Error('A node with id "' + id + '" already exists.');
+      }
+      const pos = position || {
+        x: 120 + (model.nodes.length % 6) * 240,
+        y: 120 + Math.floor(model.nodes.length / 6) * 160
+      };
+      ops.push({
+        tool: "ui_add_node",
+        args: __wfArgs({ id, type, properties: properties || {}, position: pos })
+      });
+      return __wrapNode({
+        id,
+        type,
+        position: pos,
+        data: { properties: properties || {} }
+      });
+    },
+    connect(sourceId, sourceHandle, targetId, targetHandle) {
+      __requireEditable();
+      if (!model.nodes.some((n) => n.id === sourceId)) {
+        throw new Error(
+          "connect(): source node not found: " + sourceId + ". Known: " +
+            model.nodes.map((n) => n.id).join(", ")
+        );
+      }
+      if (!model.nodes.some((n) => n.id === targetId)) {
+        throw new Error(
+          "connect(): target node not found: " + targetId + ". Known: " +
+            model.nodes.map((n) => n.id).join(", ")
+        );
+      }
+      edgeSeq++;
+      const localEdgeId = "pending_edge_" + edgeSeq;
+      ops.push({
+        tool: "ui_connect_nodes",
+        localEdgeId,
+        args: __wfArgs({
+          source_node_id: sourceId,
+          source_handle: sourceHandle,
+          target_node_id: targetId,
+          target_handle: targetHandle
+        })
+      });
+      const edge = {
+        id: localEdgeId,
+        source: sourceId,
+        sourceHandle: sourceHandle,
+        target: targetId,
+        targetHandle: targetHandle,
+        pending: true
+      };
+      model.edges.push(edge);
+      return edge;
+    },
+    removeNode(id) {
+      __requireEditable();
+      model.node(id);
+      const addIndex = ops.findIndex(
+        (op) => op.tool === "ui_add_node" && op.args.id === id
+      );
+      if (addIndex >= 0) {
+        // Never committed: cancel the add and every queued op touching it.
+        for (let i = ops.length - 1; i >= 0; i--) {
+          const a = ops[i].args;
+          if (
+            a.id === id ||
+            a.node_id === id ||
+            a.source_node_id === id ||
+            a.target_node_id === id
+          ) {
+            ops.splice(i, 1);
+          }
+        }
+      } else {
+        ops.push({ tool: "ui_delete_node", args: __wfArgs({ node_id: id }) });
+      }
+      model.nodes = model.nodes.filter((n) => n.id !== id);
+      model.edges = model.edges.filter((e) => e.source !== id && e.target !== id);
+    },
+    removeEdge(edgeId) {
+      __requireEditable();
+      const edge = model.edges.find((e) => e.id === edgeId);
+      if (!edge) throw new Error("Edge not found: " + edgeId);
+      if (edge.pending) {
+        const opIndex = ops.findIndex(
+          (op) =>
+            op.tool === "ui_connect_nodes" &&
+            (op.localEdgeId === edgeId ||
+              (op.args.source_node_id === edge.source &&
+                op.args.source_handle === edge.sourceHandle &&
+                op.args.target_node_id === edge.target &&
+                op.args.target_handle === edge.targetHandle))
+        );
+        if (opIndex >= 0) ops.splice(opIndex, 1);
+      } else {
+        ops.push({ tool: "ui_delete_edge", args: __wfArgs({ edge_id: edgeId }) });
+      }
+      model.edges = model.edges.filter((e) => e.id !== edgeId);
+    },
+    pending() {
+      return ops.length;
+    },
+    async commit() {
+      // Queued ops survive between actions, so the queue can outlive its
+      // editor: action one queues writes, the tab closes, and this snapshot
+      // now comes from the server. Replaying them would fail mid-queue with
+      // "No node store" — refuse up front instead. An empty queue is just a
+      // refresh and stays allowed on a read-only snapshot.
+      if (ops.length > 0 && !editable) {
+        throw new Error(
+          "commit(): " + ops.length + " operation(s) were queued while an " +
+            "editor was open, but workflow " + JSON.stringify(queueKey) +
+            " has no editor any more (this snapshot comes from the server). " +
+            "Replaying them would fail with 'No node store'. Open the " +
+            "workflow again with ui_open_document or ui_open_workflow, reopen " +
+            "it here with openWorkflow(), and rebuild the edits."
+        );
+      }
+      let applied = 0;
+      while (ops.length > 0) {
+        const op = ops[0];
+        try {
+          const result = await __callBeltTool(op.tool)(op.args);
+          if (
+            op.tool === "ui_connect_nodes" &&
+            typeof op.localEdgeId === "string" &&
+            result &&
+            typeof result.edge_id === "string"
+          ) {
+            const edge = model.edges.find((item) => item.id === op.localEdgeId);
+            if (edge) {
+              edge.id = result.edge_id;
+              edge.pending = false;
+            }
+          }
+        } catch (e) {
+          throw new Error(
+            "commit() failed on " + op.tool + " " + JSON.stringify(op.args).slice(0, 300) +
+            ": " + (e && e.message ? e.message : String(e)) +
+            ". " + applied + " ops were applied; the failed op and " + (ops.length - 1) +
+            " later ops are still queued — fix the problem and call commit() again." +
+            " To drop a queued connection instead, call wf.removeEdge('" +
+            (op.localEdgeId || "<edge id>") + "') for its pending edge."
+          );
+        }
+        ops.shift();
+        applied++;
+      }
+      const fresh = await __callBeltTool("ui_get_graph")(__wfArgs());
+      __load(fresh);
+      return { ok: true, applied, nodes: model.nodes.length, edges: model.edges.length };
+    }
+  };
+
+  function __wrapNode(raw) {
+    const data = raw && raw.data && typeof raw.data === "object" ? raw.data : {};
+    const view = {
+      id: raw.id,
+      type: raw.type,
+      position: raw.position || { x: 0, y: 0 },
+      title: typeof data.title === "string" ? data.title : null,
+      properties:
+        data.properties && typeof data.properties === "object" ? data.properties : {},
+      set(props) {
+        __requireEditable();
+        ops.push({
+          tool: "ui_update_node_data",
+          args: __wfArgs({ node_id: view.id, data: { properties: props } })
+        });
+        Object.assign(view.properties, props);
+        return view;
+      },
+      setTitle(title) {
+        __requireEditable();
+        ops.push({
+          tool: "ui_set_node_title",
+          args: __wfArgs({ node_id: view.id, title })
+        });
+        view.title = title;
+        return view;
+      },
+      moveTo(x, y) {
+        __requireEditable();
+        ops.push({
+          tool: "ui_move_node",
+          args: __wfArgs({ node_id: view.id, position: { x, y } })
+        });
+        view.position = { x, y };
+        return view;
+      },
+      remove() {
+        model.removeNode(view.id);
+      }
+    };
+    model.nodes.push(view);
+    return view;
+  }
+
+  function __load(fromSnap) {
+    model.nodes = [];
+    model.edges = __snapEdges(fromSnap).map((e) => Object.assign({}, e));
+    const rawNodes = __snapNodes(fromSnap);
+    for (const raw of rawNodes) __wrapNode(raw);
+  }
+
+  function __applyPending(op) {
+    if (!op || typeof op !== "object" || !op.args) return;
+    const args = op.args;
+    if (op.tool === "ui_add_node") {
+      if (!model.nodes.some((node) => node.id === args.id)) {
+        __wrapNode({
+          id: args.id,
+          type: args.type,
+          position: args.position,
+          data: { properties: args.properties || {} }
+        });
+      }
+      return;
+    }
+    if (op.tool === "ui_connect_nodes") {
+      const localEdgeId =
+        typeof op.localEdgeId === "string"
+          ? op.localEdgeId
+          : "pending_edge_" + ++edgeSeq;
+      op.localEdgeId = localEdgeId;
+      model.edges.push({
+        id: localEdgeId,
+        source: args.source_node_id,
+        sourceHandle: args.source_handle,
+        target: args.target_node_id,
+        targetHandle: args.target_handle,
+        pending: true
+      });
+      return;
+    }
+    if (op.tool === "ui_update_node_data") {
+      const node = model.nodes.find((item) => item.id === args.node_id);
+      const properties = args.data && args.data.properties;
+      if (node && properties && typeof properties === "object") {
+        Object.assign(node.properties, properties);
+      }
+      return;
+    }
+    if (op.tool === "ui_set_node_title") {
+      const node = model.nodes.find((item) => item.id === args.node_id);
+      if (node) node.title = args.title;
+      return;
+    }
+    if (op.tool === "ui_move_node") {
+      const node = model.nodes.find((item) => item.id === args.node_id);
+      if (node) node.position = args.position;
+      return;
+    }
+    if (op.tool === "ui_delete_node") {
+      model.nodes = model.nodes.filter((node) => node.id !== args.node_id);
+      model.edges = model.edges.filter(
+        (edge) => edge.source !== args.node_id && edge.target !== args.node_id
+      );
+      return;
+    }
+    if (op.tool === "ui_delete_edge") {
+      model.edges = model.edges.filter((edge) => edge.id !== args.edge_id);
+    }
+  }
+
+  __load(snap);
+  for (const op of ops) __applyPending(op);
+  return model;
+}
+`;
+/** Prompt section documenting the object model, for codeact system prompts. */
+export const GRAPH_MODEL_PROMPT_SECTION = `# Workflow graph editing (object model)
+
+Edit workflow graphs through the object model, not by calling the \`ui_*\` tools
+one mutation at a time:
+
+\`\`\`js
+const wf = await openWorkflow(workflowId);   // id from the UI context; omit for the focused workflow
+const input = wf.addNode("prompt_1", "nodetool.input.StringInput", { name: "prompt" });
+const llm = wf.addNode("llm_1", "nodetool.agents.Agent", {}, { x: 400, y: 120 });
+wf.connect("prompt_1", "output", "llm_1", "prompt");
+llm.setTitle("Draft the note").set({ system: "You draft short notes." });
+await wf.commit();                            // applies the queued ops, then reloads
+\`\`\`
+
+- \`wf.nodes\` / \`wf.edges\` are local mirrors; \`wf.node(id)\` returns a node
+  with \`.set(props)\`, \`.setTitle(t)\`, \`.moveTo(x, y)\`, \`.remove()\`.
+- Check \`wf.editable\` before editing. \`false\` means no editor is open for
+  that workflow (the snapshot came from the server), so writes are refused —
+  open the workflow with \`ui_open_document\` and reopen it first.
+- \`wf.removeNode(id)\` / \`wf.removeEdge(id)\` delete; removing a not-yet-
+  committed edge just cancels its queued op.
+- Mutators are synchronous and only queue work; nothing changes in the editor
+  until \`await wf.commit()\`. A failed commit names the failing operation,
+  keeps it and later ops queued, and can be retried after a fix.
+- Use \`ui_search_nodes(...)\` / \`search_nodes(...)\` (imported from
+  \`@nodetool-ai/sandbox-nodetool/ui\` and \`.../nodes\`) first when
+  unsure of a node type, and \`await wf.commit()\` before telling the user the
+  graph is ready.`;
+//# sourceMappingURL=graph-model.js.map

package/dist/codeact/graph-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-model.js","sourceRoot":"","sources":["../../src/codeact/graph-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,yDAAyD;AACzD,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,cAAc;IACd,aAAa;IACb,kBAAkB;IAClB,qBAAqB;IACrB,gBAAgB;IAChB,gBAAgB;IAChB,cAAc;IACd,mBAAmB;CACX,CAAC;AAEX;;;;GAIG;AACH,MAAM,mBAAmB,GAAG,CAAC,cAAc,EAAE,aAAa,EAAE,kBAAkB,CAAC,CAAC;AAEhF,8EAA8E;AAC9E,MAAM,UAAU,kBAAkB,CAAC,SAA2B;IAC5D,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;IACjC,OAAO,mBAAmB,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,uDAAuD;AACvD,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,cAAc,CAAU,CAAC;AAE7D;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6UlC,CAAC;AAEF,+EAA+E;AAC/E,MAAM,CAAC,MAAM,0BAA0B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA2BxB,CAAC"}

package/dist/codeact/mcp-guest-contract.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The short guest contract MCP clients are guaranteed to see.
+ *
+ * MCP has no system prompt. The full CodeAct catalog still rides in the
+ * `execute_code` description; this block leads that description, is the
+ * server `instructions` string, and is echoed on `nodetool://sandbox`.
+ * Keep it short — many clients truncate a long tool description.
+ */
+import { type SandboxManifest } from "../code-gen/sandbox-manifest.js";
+/** Structured guest surface for MCP clients that read resources. */
+export declare const MCP_SANDBOX_RESOURCE_URI = "nodetool://sandbox";
+/**
+ * A complete action that lists, picks a model, and generates one image.
+ * Teaching example — do not run it in CI (pick/generate need a configured model).
+ */
+export declare const MCP_SANDBOX_ACTION_SNIPPET = "const listed = await nodetool.workflows.list();\nconst model = await nodetool.models.pick(\"text_to_image\");\nconst image = await nodetool.media.generateImage(\"a red fox\", model);\nreturn { count: listed.workflows.length, uri: image.asset_uri };";
+/**
+ * List one asset and fetch it as a ref. Pass the ref through.
+ * Do not open it with fs or fetch. Runs against an empty library.
+ */
+export declare const MCP_SANDBOX_ASSET_SNIPPET = "const listed = await nodetool.assets.list({ limit: 1 });\nconst row = listed.assets[0];\nif (!row) return { found: 0 };\nconst asset = await nodetool.assets.get(row.id);\nreturn { id: asset.id, uri: asset.uri };";
+/**
+ * Cheap probe: list workflows and look up a deferred tool.
+ * Safe to run in tests — no model, no spend.
+ */
+export declare const MCP_SANDBOX_PROBE_SNIPPET = "const listed = await nodetool.workflows.list();\nconst hits = await nodetool.searchTools(\"validate_workflow\");\nreturn { count: listed.workflows.length, tools: hits.map((h) => h.name) };";
+/** Lead-in every MCP client is supposed to inject next to the system prompt. */
+export declare const MCP_GUEST_CONTRACT: string;
+export interface McpSandboxBridge {
+    name: string;
+    members: string[];
+}
+export interface McpSandboxCatalog {
+    server: "nodetool";
+    runtime: string;
+    resource: typeof MCP_SANDBOX_RESOURCE_URI;
+    contract: string;
+    native_globals: readonly string[];
+    blocked_globals: readonly string[];
+    unavailable_bridges: readonly string[];
+    available_bridges: McpSandboxBridge[];
+    packages: readonly string[];
+    examples: {
+        action: string;
+        asset: string;
+        probe: string;
+    };
+}
+export interface McpSandboxCatalogOptions {
+    packageSpecifiers?: readonly string[];
+    manifest?: SandboxManifest;
+}
+/** Machine-readable guest surface, derived from the sandbox manifest. */
+export declare function buildMcpSandboxCatalog(options?: McpSandboxCatalogOptions): McpSandboxCatalog;
+export declare const MCP_SANDBOX_PROMPTS: readonly [{
+    readonly name: "sandbox-action";
+    readonly title: "Sandbox action";
+    readonly description: "A complete execute_code body: list workflows, pick a model, generate one image.";
+    readonly snippet: "const listed = await nodetool.workflows.list();\nconst model = await nodetool.models.pick(\"text_to_image\");\nconst image = await nodetool.media.generateImage(\"a red fox\", model);\nreturn { count: listed.workflows.length, uri: image.asset_uri };";
+}, {
+    readonly name: "sandbox-asset";
+    readonly title: "Sandbox asset";
+    readonly description: "A complete execute_code body: list one asset and fetch the ref. Do not open bytes with fs.";
+    readonly snippet: "const listed = await nodetool.assets.list({ limit: 1 });\nconst row = listed.assets[0];\nif (!row) return { found: 0 };\nconst asset = await nodetool.assets.get(row.id);\nreturn { id: asset.id, uri: asset.uri };";
+}];
+//# sourceMappingURL=mcp-guest-contract.d.ts.map

package/dist/codeact/mcp-guest-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-guest-contract.d.ts","sourceRoot":"","sources":["../../src/codeact/mcp-guest-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,iCAAiC,CAAC;AAIzC,oEAAoE;AACpE,eAAO,MAAM,wBAAwB,uBAAuB,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,0BAA0B,6PAG0B,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,yBAAyB,wNAIG,CAAC;AAE1C;;;GAGG;AACH,eAAO,MAAM,yBAAyB,iMAEqC,CAAC;AAE5E,gFAAgF;AAChF,eAAO,MAAM,kBAAkB,QAqB4E,CAAC;AAE5G,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,wBAAwB,CAAC;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IACtC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,QAAQ,EAAE;QACR,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED,MAAM,WAAW,wBAAwB;IACvC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,yEAAyE;AACzE,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,wBAA6B,GACrC,iBAAiB,CA6BnB;AAED,eAAO,MAAM,mBAAmB;aAE5B,IAAI,EAAE,gBAAgB;aACtB,KAAK,EAAE,gBAAgB;aACvB,WAAW,EACT,iFAAiF;aACnF,OAAO;;aAGP,IAAI,EAAE,eAAe;aACrB,KAAK,EAAE,eAAe;aACtB,WAAW,EACT,4FAA4F;aAC9F,OAAO;EAED,CAAC"}

package/dist/codeact/mcp-guest-contract.js

@@ -0,0 +1,108 @@
+/**
+ * The short guest contract MCP clients are guaranteed to see.
+ *
+ * MCP has no system prompt. The full CodeAct catalog still rides in the
+ * `execute_code` description; this block leads that description, is the
+ * server `instructions` string, and is echoed on `nodetool://sandbox`.
+ * Keep it short — many clients truncate a long tool description.
+ */
+import { getSandboxManifest } from "../code-gen/sandbox-manifest.js";
+import { chatUnavailableBridges } from "./prompt.js";
+import { RESERVED_BINDINGS_SENTENCE } from "./tool-api.js";
+/** Structured guest surface for MCP clients that read resources. */
+export const MCP_SANDBOX_RESOURCE_URI = "nodetool://sandbox";
+/**
+ * A complete action that lists, picks a model, and generates one image.
+ * Teaching example — do not run it in CI (pick/generate need a configured model).
+ */
+export const MCP_SANDBOX_ACTION_SNIPPET = `const listed = await nodetool.workflows.list();
+const model = await nodetool.models.pick("text_to_image");
+const image = await nodetool.media.generateImage("a red fox", model);
+return { count: listed.workflows.length, uri: image.asset_uri };`;
+/**
+ * List one asset and fetch it as a ref. Pass the ref through.
+ * Do not open it with fs or fetch. Runs against an empty library.
+ */
+export const MCP_SANDBOX_ASSET_SNIPPET = `const listed = await nodetool.assets.list({ limit: 1 });
+const row = listed.assets[0];
+if (!row) return { found: 0 };
+const asset = await nodetool.assets.get(row.id);
+return { id: asset.id, uri: asset.uri };`;
+/**
+ * Cheap probe: list workflows and look up a deferred tool.
+ * Safe to run in tests — no model, no spend.
+ */
+export const MCP_SANDBOX_PROBE_SNIPPET = `const listed = await nodetool.workflows.list();
+const hits = await nodetool.searchTools("validate_workflow");
+return { count: listed.workflows.length, tools: hits.map((h) => h.name) };`;
+/** Lead-in every MCP client is supposed to inject next to the system prompt. */
+export const MCP_GUEST_CONTRACT = `# Guest JavaScript (not Node)
+
+\`execute_code\` runs in a QuickJS guest. There is no Node and no host filesystem.
+Do not use \`fs\`, \`require\`, \`process\`, \`Buffer\`, \`setTimeout\`, or \`eval\`.
+
+Write one action:
+
+\`\`\`js
+${MCP_SANDBOX_ACTION_SNIPPET}
+\`\`\`
+
+Rules:
+- Call \`nodetool.<namespace>.<method>()\`. Do not invent MCP tools. There is no \`tools.*\` global — anything the object model does not cover is a static \`import\` from \`@nodetool-ai/sandbox-nodetool/<namespace>\`.
+- Unknown tool: \`await nodetool.searchTools("query")\` first. Each hit carries the \`import\` line to write. Do not guess arguments, and do not guess the module.
+- Static \`import\` only for allowed packs. This session lists them below; anything else fails.
+- \`return\` a small summary. Nothing carries over between actions except what a tool saved — generation results are already assets (\`asset://\`). Record anything a later action needs with \`nodetool.memory.save\`; the next action must reuse it, not generate again.
+- \`await nodetool.packs.docs(specifier)\` returns a markdown string. Use string methods directly. Operator-allowlisted packs return their guide unchanged. Other packs retain the untrusted reference-data wrapper.
+- A failed tool throws. Use \`try/catch\`.
+- ${RESERVED_BINDINGS_SENTENCE}
+- This is a chat turn: there is no \`finish()\`. A plain assistant message ends the turn.
+- \`fetch\`, \`workspace\`, \`media\`, and \`getSecret\` are not available here. Files and assets go through \`nodetool.*\`: feed a generation result into \`image.*\`, save with \`nodetool.media.toImage(handle)\`. The guest holds handles, never encoded bytes. \`nodetool.assets.read/save\` the library, \`nodetool.web.fetch\` the network.
+- Full guest surface: resource \`${MCP_SANDBOX_RESOURCE_URI}\`. Tool catalog: \`nodetool://capabilities\`.`;
+/** Machine-readable guest surface, derived from the sandbox manifest. */
+export function buildMcpSandboxCatalog(options = {}) {
+    const manifest = options.manifest ?? getSandboxManifest();
+    const unavailable = chatUnavailableBridges(manifest);
+    const hidden = new Set(unavailable);
+    const available_bridges = [];
+    for (const bridge of Object.values(manifest.bridges)) {
+        if (bridge.internal || bridge.members.length === 0)
+            continue;
+        if (hidden.has(bridge.name))
+            continue;
+        available_bridges.push({
+            name: bridge.name,
+            members: bridge.members.map((member) => member.signature)
+        });
+    }
+    return {
+        server: "nodetool",
+        runtime: manifest.runtime,
+        resource: MCP_SANDBOX_RESOURCE_URI,
+        contract: MCP_GUEST_CONTRACT,
+        native_globals: manifest.nativeGlobals,
+        blocked_globals: manifest.blockedGlobals,
+        unavailable_bridges: unavailable,
+        available_bridges,
+        packages: options.packageSpecifiers ?? [],
+        examples: {
+            action: MCP_SANDBOX_ACTION_SNIPPET,
+            asset: MCP_SANDBOX_ASSET_SNIPPET,
+            probe: MCP_SANDBOX_PROBE_SNIPPET
+        }
+    };
+}
+export const MCP_SANDBOX_PROMPTS = [
+    {
+        name: "sandbox-action",
+        title: "Sandbox action",
+        description: "A complete execute_code body: list workflows, pick a model, generate one image.",
+        snippet: MCP_SANDBOX_ACTION_SNIPPET
+    },
+    {
+        name: "sandbox-asset",
+        title: "Sandbox asset",
+        description: "A complete execute_code body: list one asset and fetch the ref. Do not open bytes with fs.",
+        snippet: MCP_SANDBOX_ASSET_SNIPPET
+    }
+];
+//# sourceMappingURL=mcp-guest-contract.js.map

package/dist/codeact/mcp-guest-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-guest-contract.js","sourceRoot":"","sources":["../../src/codeact/mcp-guest-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,kBAAkB,EAEnB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAE3D,oEAAoE;AACpE,MAAM,CAAC,MAAM,wBAAwB,GAAG,oBAAoB,CAAC;AAE7D;;;GAGG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG;;;iEAGuB,CAAC;AAElE;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;;;;yCAIA,CAAC;AAE1C;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;;2EAEkC,CAAC;AAE5E,gFAAgF;AAChF,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;EAQhC,0BAA0B;;;;;;;;;;IAUxB,0BAA0B;;;mCAGK,wBAAwB,gDAAgD,CAAC;AA6B5G,yEAAyE;AACzE,MAAM,UAAU,sBAAsB,CACpC,OAAO,GAA6B,EAAE;IAEtC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,kBAAkB,EAAE,CAAC;IAC1D,MAAM,WAAW,GAAG,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,CAAC;IACpC,MAAM,iBAAiB,GAAuB,EAAE,CAAC;IACjD,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACrD,IAAI,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAC7D,IAAI,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;YAAE,SAAS;QACtC,iBAAiB,CAAC,IAAI,CAAC;YACrB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC;SAC1D,CAAC,CAAC;IACL,CAAC;IACD,OAAO;QACL,MAAM,EAAE,UAAU;QAClB,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,QAAQ,EAAE,wBAAwB;QAClC,QAAQ,EAAE,kBAAkB;QAC5B,cAAc,EAAE,QAAQ,CAAC,aAAa;QACtC,eAAe,EAAE,QAAQ,CAAC,cAAc;QACxC,mBAAmB,EAAE,WAAW;QAChC,iBAAiB;QACjB,QAAQ,EAAE,OAAO,CAAC,iBAAiB,IAAI,EAAE;QACzC,QAAQ,EAAE;YACR,MAAM,EAAE,0BAA0B;YAClC,KAAK,EAAE,yBAAyB;YAChC,KAAK,EAAE,yBAAyB;SACjC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC;QACE,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,gBAAgB;QACvB,WAAW,EACT,iFAAiF;QACnF,OAAO,EAAE,0BAA0B;KACpC;IACD;QACE,IAAI,EAAE,eAAe;QACrB,KAAK,EAAE,eAAe;QACtB,WAAW,EACT,4FAA4F;QAC9F,OAAO,EAAE,yBAAyB;KACnC;CACO,CAAC"}