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

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

@@ -0,0 +1,31 @@
+/**
+ * The native flow surface for a CodeAct session: call a registry node as a
+ * typed async function and write the control flow in plain JavaScript.
+ *
+ * The graph DSL authors an artifact — a workflow the editor can open and the
+ * server can run. The flow pack is for a turn that just wants values: no
+ * graph, no edges, `await` is the edge and `Promise.all` is the fan-out.
+ * Each call bridges through the `flow` capability module, so it passes the
+ * same per-call permission gate every capability call does.
+ *
+ * The pack is guest code like any other, so it reaches an action only
+ * through the session allowlist. This module adds it when the catalog
+ * actually serves the pack — never when it is missing, so no prompt
+ * advertises an import that fails.
+ */
+import type { SandboxModuleCatalog } from "@nodetool-ai/runtime";
+/** The pack's root specifier: one generated module per node namespace. */
+export declare const FLOW_PACKAGE = "@nodetool-ai/sandbox-flow";
+/** Whether a catalog serves the flow pack — i.e. whether it is installed. */
+export declare function catalogServesFlow(catalog: SandboxModuleCatalog | null | undefined): boolean;
+/**
+ * The session allowlist with the flow pack added when this machine installed
+ * it. Leaves the list unchanged when the pack is absent or already allowed.
+ */
+export declare function withFlowPackage(allowed: readonly string[], catalog: SandboxModuleCatalog | null | undefined): string[];
+/**
+ * The prompt section for calling nodes directly. Render only when the pack
+ * is on the allowlist — {@link withFlowPackage} decides that.
+ */
+export declare const FLOW_PROMPT_SECTION = "# Calling nodes directly (native flow)\n\nRun a node as a typed async function with `@nodetool-ai/sandbox-flow`: one generated\nfunction per node type, taking that node's real inputs and resolving to its\noutputs record. This is how a turn *does* node work. \"Generate an image, then\nremove its background\" is two calls in one action \u2014 branches, loops, retries\nand fan-out are plain JavaScript.\n\n```js\nimport \"@nodetool-ai/sandbox-nodetool/flow\"; // mounts the bridge \u2014 required\nimport { textToImage, removeBackground } from \"@nodetool-ai/sandbox-flow/nodetool.image\";\n\nconst model = await nodetool.models.pick(\"text_to_image\");\nconst shot = await textToImage({ prompt: \"a red fox in snow\", model: model.ref });\nconst cutout = (await removeBackground({ image: shot.output })).output;\nawait nodetool.media.toImage(cutout);\nreturn { generated: true };\n```\n\n- The bare capability import must appear in the body \u2014 without it every flow\n  call fails saying the bridge is not mounted.\n- The export name is the node class in camelCase:\n  `nodetool.image.RemoveBackground` is `removeBackground`,\n  `nodetool.constant.Integer` is `integer`, and a reserved word takes a\n  trailing underscore (`if_`).\n- An input you leave out runs the node's own default. A `*_model` input is\n  the one worth always setting: pass `(await nodetool.models.pick(task)).ref`\n  so the node runs on a model this install has.\n- Outputs come back keyed by slot \u2014 `r.output` is the default one. Feed one\n  node's output straight into the next call. A media output is a ref that can\n  carry inline bytes: save finished handles with\n  `nodetool.media.toImage/toAudio/toVideo` before the action ends, and record\n  the `asset://` uri with `nodetool.memory.save` when a later turn needs it.\n  Never return inline bytes as the observation.\n- A streaming-output node also carries `.stream(inputs)`, an async iterable\n  of partial outputs; early `break` closes the stream and runs node cleanup.\n- Errors reject the call \u2014 `try`/`catch` is the supervisor. Stream-typed\n  inputs accept plain arrays.\n- A node type the catalog does not have has no export, so the import fails\n  before the action runs. Find the real one with `nodetool.nodes.search()`,\n  then import its namespace.";
+//# sourceMappingURL=flow-package.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"flow-package.d.ts","sourceRoot":"","sources":["../../src/codeact/flow-package.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEjE,0EAA0E;AAC1E,eAAO,MAAM,YAAY,8BAA8B,CAAC;AAExD,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,oBAAoB,GAAG,IAAI,GAAG,SAAS,GAC/C,OAAO,CAIT;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,oBAAoB,GAAG,IAAI,GAAG,SAAS,GAC/C,MAAM,EAAE,CAQV;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,owEAwCH,CAAC"}

package/dist/codeact/flow-package.js

@@ -0,0 +1,80 @@
+/**
+ * The native flow surface for a CodeAct session: call a registry node as a
+ * typed async function and write the control flow in plain JavaScript.
+ *
+ * The graph DSL authors an artifact — a workflow the editor can open and the
+ * server can run. The flow pack is for a turn that just wants values: no
+ * graph, no edges, `await` is the edge and `Promise.all` is the fan-out.
+ * Each call bridges through the `flow` capability module, so it passes the
+ * same per-call permission gate every capability call does.
+ *
+ * The pack is guest code like any other, so it reaches an action only
+ * through the session allowlist. This module adds it when the catalog
+ * actually serves the pack — never when it is missing, so no prompt
+ * advertises an import that fails.
+ */
+/** The pack's root specifier: one generated module per node namespace. */
+export const FLOW_PACKAGE = "@nodetool-ai/sandbox-flow";
+/** Whether a catalog serves the flow pack — i.e. whether it is installed. */
+export function catalogServesFlow(catalog) {
+    return (catalog?.summaries() ?? []).some((summary) => summary.specifier === FLOW_PACKAGE);
+}
+/**
+ * The session allowlist with the flow pack added when this machine installed
+ * it. Leaves the list unchanged when the pack is absent or already allowed.
+ */
+export function withFlowPackage(allowed, catalog) {
+    if (allowed.includes(FLOW_PACKAGE)) {
+        return [...allowed];
+    }
+    if (!catalogServesFlow(catalog)) {
+        return [...allowed];
+    }
+    return [...allowed, FLOW_PACKAGE];
+}
+/**
+ * The prompt section for calling nodes directly. Render only when the pack
+ * is on the allowlist — {@link withFlowPackage} decides that.
+ */
+export const FLOW_PROMPT_SECTION = `# Calling nodes directly (native flow)
+
+Run a node as a typed async function with \`${FLOW_PACKAGE}\`: one generated
+function per node type, taking that node's real inputs and resolving to its
+outputs record. This is how a turn *does* node work. "Generate an image, then
+remove its background" is two calls in one action — branches, loops, retries
+and fan-out are plain JavaScript.
+
+\`\`\`js
+import "@nodetool-ai/sandbox-nodetool/flow"; // mounts the bridge — required
+import { textToImage, removeBackground } from "${FLOW_PACKAGE}/nodetool.image";
+
+const model = await nodetool.models.pick("text_to_image");
+const shot = await textToImage({ prompt: "a red fox in snow", model: model.ref });
+const cutout = (await removeBackground({ image: shot.output })).output;
+await nodetool.media.toImage(cutout);
+return { generated: true };
+\`\`\`
+
+- The bare capability import must appear in the body — without it every flow
+  call fails saying the bridge is not mounted.
+- The export name is the node class in camelCase:
+  \`nodetool.image.RemoveBackground\` is \`removeBackground\`,
+  \`nodetool.constant.Integer\` is \`integer\`, and a reserved word takes a
+  trailing underscore (\`if_\`).
+- An input you leave out runs the node's own default. A \`*_model\` input is
+  the one worth always setting: pass \`(await nodetool.models.pick(task)).ref\`
+  so the node runs on a model this install has.
+- Outputs come back keyed by slot — \`r.output\` is the default one. Feed one
+  node's output straight into the next call. A media output is a ref that can
+  carry inline bytes: save finished handles with
+  \`nodetool.media.toImage/toAudio/toVideo\` before the action ends, and record
+  the \`asset://\` uri with \`nodetool.memory.save\` when a later turn needs it.
+  Never return inline bytes as the observation.
+- A streaming-output node also carries \`.stream(inputs)\`, an async iterable
+  of partial outputs; early \`break\` closes the stream and runs node cleanup.
+- Errors reject the call — \`try\`/\`catch\` is the supervisor. Stream-typed
+  inputs accept plain arrays.
+- A node type the catalog does not have has no export, so the import fails
+  before the action runs. Find the real one with \`nodetool.nodes.search()\`,
+  then import its namespace.`;
+//# sourceMappingURL=flow-package.js.map

package/dist/codeact/flow-package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-package.js","sourceRoot":"","sources":["../../src/codeact/flow-package.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,YAAY,GAAG,2BAA2B,CAAC;AAExD,6EAA6E;AAC7E,MAAM,UAAU,iBAAiB,CAC/B,OAAgD;IAEhD,OAAO,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CACtC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,KAAK,YAAY,CAChD,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,OAA0B,EAC1B,OAAgD;IAEhD,IAAI,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;QACnC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;IACtB,CAAC;IACD,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,CAAC,GAAG,OAAO,EAAE,YAAY,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;;8CAEW,YAAY;;;;;;;;iDAQT,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;6BA8BhC,CAAC"}

package/dist/codeact/graph-dsl-package.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The workflow DSL a CodeAct session authors graphs with.
+ *
+ * The `nodetool.graph()` builder this replaced took a node type as a string,
+ * so every type and every input name was something the model invented and
+ * nothing checked until the graph was validated — or, worse, until it ran. The
+ * DSL pack ships one generated function per node type, with that node's real
+ * inputs, so a type the catalog does not have has no export to import and the
+ * action fails before any code runs.
+ *
+ * The pack is guest code like any other, so it reaches an action only through
+ * the session allowlist. That is what this module wires: a belt that can save,
+ * validate and run a workflow gets the pack added to its allowlist, provided
+ * the catalog actually serves it. A machine without the pack installed gets
+ * neither the specifier nor the prompt section that names it.
+ */
+import type { SandboxModuleCatalog } from "@nodetool-ai/runtime";
+/** The pack's root specifier: `workflow()` plus every namespace under one name. */
+export declare const GRAPH_DSL_PACKAGE = "@nodetool-ai/sandbox-dsl";
+/**
+ * The belt tools a graph-authoring session needs. Building a graph nothing can
+ * check or save is not authoring, so all three must be present — the same rule
+ * `nodetool.graph()` was gated by.
+ */
+export declare const GRAPH_DSL_TOOLS: readonly ["create_workflow", "validate_workflow", "run_workflow"];
+/** Whether a belt can author, check and run a workflow. */
+export declare function hasGraphDslTools(toolNames: Iterable<string>): boolean;
+/** Whether a catalog serves the DSL pack — i.e. whether it is installed here. */
+export declare function catalogServesGraphDsl(catalog: SandboxModuleCatalog | null | undefined): boolean;
+/**
+ * The session allowlist with the DSL pack added when this session can use it.
+ * Returns the allowlist unchanged when the belt cannot author graphs or the
+ * pack is not installed, so no prompt ever advertises an import that fails.
+ */
+export declare function withGraphDslPackage(allowed: readonly string[], toolNames: Iterable<string>, catalog: SandboxModuleCatalog | null | undefined): string[];
+/**
+ * The prompt section for authoring a graph. Rendered only for a session that
+ * has both the tools and the pack — {@link withGraphDslPackage} decides that,
+ * and the caller passes the answer in.
+ */
+export declare const GRAPH_DSL_PROMPT_SECTION = "# Authoring a workflow graph\n\nBuild graphs with `@nodetool-ai/sandbox-dsl`: one generated function per node\ntype, taking that node's real inputs. Import the namespaces you need, wire\nhandles, and `workflow(...terminals)` returns `{nodes, edges}`.\n\n```js\nimport { workflow } from \"@nodetool-ai/sandbox-dsl\";\nimport { stringInput } from \"@nodetool-ai/sandbox-dsl/nodetool.input\";\nimport { concat } from \"@nodetool-ai/sandbox-dsl/nodetool.text\";\nimport { output } from \"@nodetool-ai/sandbox-dsl/nodetool.output\";\n\nconst name = stringInput({ name: \"name\" });\nconst line = concat({ a: name.output(), b: \", welcome aboard!\" });\nconst graph = workflow(output({ name: \"greeting\", value: line.output() }));\n\nconst check = await nodetool.workflows.validate(graph);  // before spending\nconst saved = await nodetool.workflows.create(\"Greeter\", graph);\nconst run = await nodetool.workflows.run(saved.id, { name: \"Ada\" });\n```\n\nThe three verbs are also importable \u2014\n`import { validate_workflow, run_workflow, debug_workflow } from\n\"@nodetool-ai/sandbox-nodetool/workflows\"` \u2014 wherever this session mounts the\ncapability modules. Both forms reach one implementation past one gate.\n\n- `ref.output()` is the default output slot, `ref.output(\"mask\")` names one.\n  A handle passed as an input value wires the edge.\n- Only nodes reachable from the terminals you pass ship, and `workflow()`\n  clears the registry \u2014 one graph per call.\n- A node type the catalog does not have has no export, so the import fails\n  before the action runs. Find the real one with `nodetool.nodes.search()`,\n  then import its namespace.\n- A `*_model` property left unset fails validation: assign\n  `(await nodetool.models.pick(task)).ref` \u2014 the typed\n  `{type, provider, id, name}` value, not a bare model id.\n- Authoring and saving a graph does not run it. A user who asked for results\n  gets them from `nodetool.workflows.run(saved.id, params)`; a workflow id on\n  its own answers a question they did not ask.\n- `nodetool.workflows.debug(id, params)` reports per-node status when a run\n  fails and the graph looks right. It answers `{workflow_id, run, job,\n  workflow}`: read `run.status`, `run.outputs` (keyed by output name; each\n  name holds an array of emitted values) and `run.verdict.issues`.";
+//# sourceMappingURL=graph-dsl-package.d.ts.map

package/dist/codeact/graph-dsl-package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-dsl-package.d.ts","sourceRoot":"","sources":["../../src/codeact/graph-dsl-package.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEjE,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,6BAA6B,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,eAAe,YAC1B,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,CACN,CAAC;AAEX,2DAA2D;AAC3D,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAGrE;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,oBAAoB,GAAG,IAAI,GAAG,SAAS,GAC/C,OAAO,CAIT;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,EAC3B,OAAO,EAAE,oBAAoB,GAAG,IAAI,GAAG,SAAS,GAC/C,MAAM,EAAE,CAKV;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,0yEA0CgC,CAAC"}

package/dist/codeact/graph-dsl-package.js

@@ -0,0 +1,100 @@
+/**
+ * The workflow DSL a CodeAct session authors graphs with.
+ *
+ * The `nodetool.graph()` builder this replaced took a node type as a string,
+ * so every type and every input name was something the model invented and
+ * nothing checked until the graph was validated — or, worse, until it ran. The
+ * DSL pack ships one generated function per node type, with that node's real
+ * inputs, so a type the catalog does not have has no export to import and the
+ * action fails before any code runs.
+ *
+ * The pack is guest code like any other, so it reaches an action only through
+ * the session allowlist. That is what this module wires: a belt that can save,
+ * validate and run a workflow gets the pack added to its allowlist, provided
+ * the catalog actually serves it. A machine without the pack installed gets
+ * neither the specifier nor the prompt section that names it.
+ */
+/** The pack's root specifier: `workflow()` plus every namespace under one name. */
+export const GRAPH_DSL_PACKAGE = "@nodetool-ai/sandbox-dsl";
+/**
+ * The belt tools a graph-authoring session needs. Building a graph nothing can
+ * check or save is not authoring, so all three must be present — the same rule
+ * `nodetool.graph()` was gated by.
+ */
+export const GRAPH_DSL_TOOLS = [
+    "create_workflow",
+    "validate_workflow",
+    "run_workflow"
+];
+/** Whether a belt can author, check and run a workflow. */
+export function hasGraphDslTools(toolNames) {
+    const names = new Set(toolNames);
+    return GRAPH_DSL_TOOLS.every((tool) => names.has(tool));
+}
+/** Whether a catalog serves the DSL pack — i.e. whether it is installed here. */
+export function catalogServesGraphDsl(catalog) {
+    return (catalog?.summaries() ?? []).some((summary) => summary.specifier === GRAPH_DSL_PACKAGE);
+}
+/**
+ * The session allowlist with the DSL pack added when this session can use it.
+ * Returns the allowlist unchanged when the belt cannot author graphs or the
+ * pack is not installed, so no prompt ever advertises an import that fails.
+ */
+export function withGraphDslPackage(allowed, toolNames, catalog) {
+    if (allowed.includes(GRAPH_DSL_PACKAGE))
+        return [...allowed];
+    if (!hasGraphDslTools(toolNames))
+        return [...allowed];
+    if (!catalogServesGraphDsl(catalog))
+        return [...allowed];
+    return [...allowed, GRAPH_DSL_PACKAGE];
+}
+/**
+ * The prompt section for authoring a graph. Rendered only for a session that
+ * has both the tools and the pack — {@link withGraphDslPackage} decides that,
+ * and the caller passes the answer in.
+ */
+export const GRAPH_DSL_PROMPT_SECTION = `# Authoring a workflow graph
+
+Build graphs with \`${GRAPH_DSL_PACKAGE}\`: one generated function per node
+type, taking that node's real inputs. Import the namespaces you need, wire
+handles, and \`workflow(...terminals)\` returns \`{nodes, edges}\`.
+
+\`\`\`js
+import { workflow } from "${GRAPH_DSL_PACKAGE}";
+import { stringInput } from "${GRAPH_DSL_PACKAGE}/nodetool.input";
+import { concat } from "${GRAPH_DSL_PACKAGE}/nodetool.text";
+import { output } from "${GRAPH_DSL_PACKAGE}/nodetool.output";
+
+const name = stringInput({ name: "name" });
+const line = concat({ a: name.output(), b: ", welcome aboard!" });
+const graph = workflow(output({ name: "greeting", value: line.output() }));
+
+const check = await nodetool.workflows.validate(graph);  // before spending
+const saved = await nodetool.workflows.create("Greeter", graph);
+const run = await nodetool.workflows.run(saved.id, { name: "Ada" });
+\`\`\`
+
+The three verbs are also importable —
+\`import { validate_workflow, run_workflow, debug_workflow } from
+"@nodetool-ai/sandbox-nodetool/workflows"\` — wherever this session mounts the
+capability modules. Both forms reach one implementation past one gate.
+
+- \`ref.output()\` is the default output slot, \`ref.output("mask")\` names one.
+  A handle passed as an input value wires the edge.
+- Only nodes reachable from the terminals you pass ship, and \`workflow()\`
+  clears the registry — one graph per call.
+- A node type the catalog does not have has no export, so the import fails
+  before the action runs. Find the real one with \`nodetool.nodes.search()\`,
+  then import its namespace.
+- A \`*_model\` property left unset fails validation: assign
+  \`(await nodetool.models.pick(task)).ref\` — the typed
+  \`{type, provider, id, name}\` value, not a bare model id.
+- Authoring and saving a graph does not run it. A user who asked for results
+  gets them from \`nodetool.workflows.run(saved.id, params)\`; a workflow id on
+  its own answers a question they did not ask.
+- \`nodetool.workflows.debug(id, params)\` reports per-node status when a run
+  fails and the graph looks right. It answers \`{workflow_id, run, job,
+  workflow}\`: read \`run.status\`, \`run.outputs\` (keyed by output name; each
+  name holds an array of emitted values) and \`run.verdict.issues\`.`;
+//# sourceMappingURL=graph-dsl-package.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graph-dsl-package.js","sourceRoot":"","sources":["../../src/codeact/graph-dsl-package.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,mFAAmF;AACnF,MAAM,CAAC,MAAM,iBAAiB,GAAG,0BAA0B,CAAC;AAE5D;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,iBAAiB;IACjB,mBAAmB;IACnB,cAAc;CACN,CAAC;AAEX,2DAA2D;AAC3D,MAAM,UAAU,gBAAgB,CAAC,SAA2B;IAC1D,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;IACjC,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,qBAAqB,CACnC,OAAgD;IAEhD,OAAO,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CACtC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,KAAK,iBAAiB,CACrD,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAA0B,EAC1B,SAA2B,EAC3B,OAAgD;IAEhD,IAAI,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC;QAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;IAC7D,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC;QAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;IACtD,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC;QAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC;IACzD,OAAO,CAAC,GAAG,OAAO,EAAE,iBAAiB,CAAC,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;;sBAElB,iBAAiB;;;;;4BAKX,iBAAiB;+BACd,iBAAiB;0BACtB,iBAAiB;0BACjB,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qEAgC0B,CAAC"}

package/dist/codeact/graph-model.d.ts

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

package/dist/codeact/graph-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-model.d.ts","sourceRoot":"","sources":["../../src/codeact/graph-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,yDAAyD;AACzD,eAAO,MAAM,sBAAsB,YACjC,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,mBAAmB,CACX,CAAC;AASX,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAGvE;AAED,uDAAuD;AACvD,eAAO,MAAM,mBAAmB,YAAI,cAAc,CAAU,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,mBAAmB,6vXA6U/B,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,0BAA0B,ilDA2BrB,CAAC"}