@nodetool-ai/llm-nodes 0.8.1

package/README.md

@@ -0,0 +1,52 @@
+# @nodetool-ai/llm-nodes
+
+LLM provider and agent nodes for [NodeTool](https://nodetool.ai).
+
+Call OpenAI, Google Gemini, Mistral, and xAI directly from visual AI workflows —
+chat, embeddings, image generation, speech, transcription, web search — plus
+NodeTool agent nodes for summarizing, extracting, classifying, and generating
+structured output.
+
+## Install
+
+```bash
+npm install @nodetool-ai/llm-nodes
+```
+
+## Nodes
+
+**OpenAI** (`openai.*`) — `text.Embedding`, `text.WebSearch`, `text.Moderation`,
+`image.CreateImage`, `image.EditImage`, `image.ImageVariation`,
+`audio.TextToSpeech`, `audio.Transcribe`, `audio.Translate`,
+`agents.RealtimeAgent`, `agents.RealtimeTranscription`, `agents.LiveAgent`.
+
+**Gemini** (`gemini.*`) — `text.GroundedSearch`, `text.Embedding`,
+`image.ImageGeneration`, `video.TextToVideo`, `video.ImageToVideo`,
+`audio.TextToSpeech`, `audio.Transcribe`.
+
+**Mistral** (`mistral.*`) — `text.ChatComplete`, `text.CodeComplete`,
+`embeddings.Embedding`, `vision.ImageToText`, `vision.OCR`.
+
+**xAI** (`xai.*`) — `text.ChatComplete`, `text.WebSearch`, `vision.ImageToText`,
+`image.GenerateImage`.
+
+**Agents** (`nodetool.agents.*`) — `Summarizer`, `Extractor`, `Classifier`,
+`EnhancePrompt`, `CreateThread`.
+
+**Generators** (`nodetool.generators.*`) — `StructuredOutputGenerator`,
+`DataGenerator`, `ListGenerator`, `ChartGenerator`, `SVGGenerator`.
+
+## Configuration
+
+Set the provider keys you use in NodeTool's secret store (Settings → API Keys)
+or as environment variables:
+
+- `OPENAI_API_KEY`
+- `GEMINI_API_KEY`
+- `MISTRAL_API_KEY`
+- `XAI_API_KEY`
+
+## Links
+
+- [NodeTool](https://nodetool.ai)
+- [GitHub](https://github.com/nodetool-ai/nodetool)

package/dist/.nodetool-build-stamp

@@ -0,0 +1 @@
+2026-09-28T09:19:15.219Z

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @nodetool-ai/llm-nodes — LLM provider + agent node bundle.
+ *
+ * Classes from `openai.ts`, `gemini.ts` and `xai.ts` share names with
+ * each other and with `mistral.ts` (e.g. `EmbeddingNode`,
+ * `ChatComplete`, `ImageToText`), so we re-export those provider modules
+ * via subpath exports (`@nodetool-ai/llm-nodes/openai`, `/gemini`,
+ * `/mistral`, `/xai`, `/agents`) rather than the barrel. The barrel fully
+ * re-exports everything else.
+ */
+export * from "./nodes/agents.js";
+export * from "./nodes/agent-tool-hydration.js";
+export * from "./nodes/generators.js";
+export * from "./nodes/mistral.js";
+export { OPENAI_NODES } from "./nodes/openai.js";
+export { GEMINI_NODES } from "./nodes/gemini.js";
+export { XAI_NODES } from "./nodes/xai.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,iCAAiC,CAAC;AAChD,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AAMnC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * @nodetool-ai/llm-nodes — LLM provider + agent node bundle.
+ *
+ * Classes from `openai.ts`, `gemini.ts` and `xai.ts` share names with
+ * each other and with `mistral.ts` (e.g. `EmbeddingNode`,
+ * `ChatComplete`, `ImageToText`), so we re-export those provider modules
+ * via subpath exports (`@nodetool-ai/llm-nodes/openai`, `/gemini`,
+ * `/mistral`, `/xai`, `/agents`) rather than the barrel. The barrel fully
+ * re-exports everything else.
+ */
+export * from "./nodes/agents.js";
+export * from "./nodes/agent-tool-hydration.js";
+export * from "./nodes/generators.js";
+export * from "./nodes/mistral.js";
+// `openai.ts`, `gemini.ts` and `xai.ts` reuse class names (`EmbeddingNode`,
+// `ChatComplete`, `ImageToText`); barrel callers get only the registration
+// arrays. Use the `/openai`, `/gemini` and `/xai` subpath exports for the
+// individual classes.
+export { OPENAI_NODES } from "./nodes/openai.js";
+export { GEMINI_NODES } from "./nodes/gemini.js";
+export { XAI_NODES } from "./nodes/xai.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,iCAAiC,CAAC;AAChD,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AAEnC,4EAA4E;AAC5E,2EAA2E;AAC3E,0EAA0E;AAC1E,sBAAsB;AACtB,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/nodes/agent-control-tools.d.ts

@@ -0,0 +1,22 @@
+import type { ProcessingContext } from "@nodetool-ai/runtime";
+import type { ToolLike } from "./agent-utils.js";
+/**
+ * A control tool is a normal {@link ToolLike} whose `process` dispatches a
+ * control event to a target node. `targetNodeId` is kept on the object for
+ * diagnostics/logging by the caller; execution flows through the generic
+ * `tool.process` path like any other tool.
+ */
+interface ControlTool extends ToolLike {
+    targetNodeId: string;
+    process: (context: ProcessingContext, params: Record<string, unknown>) => Promise<Record<string, unknown>>;
+}
+/**
+ * Build control tools from `_control_context` input. Each tool's `process`
+ * filters the model's arguments to the node's declared properties, then
+ * dispatches a control event through the context and returns the result — so
+ * control tools run through the same generic `tool.process` path as any other
+ * tool (including plan mode's ToolLikeAdapter).
+ */
+export declare function buildControlTools(controlContext: unknown): ControlTool[];
+export {};
+//# sourceMappingURL=agent-control-tools.d.ts.map

package/dist/nodes/agent-control-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-control-tools.d.ts","sourceRoot":"","sources":["../../src/nodes/agent-control-tools.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AASjD;;;;;GAKG;AACH,UAAU,WAAY,SAAQ,QAAQ;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,CACP,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvC;AAuBD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,OAAO,GAAG,WAAW,EAAE,CA2GxE"}

package/dist/nodes/agent-control-tools.js

@@ -0,0 +1,123 @@
+import { createLogger } from "@nodetool-ai/config";
+import { isObjectLike } from "@nodetool-ai/node-sdk";
+// ---------------------------------------------------------------------------
+// Control tool support for Agent nodes with outgoing control edges
+// ---------------------------------------------------------------------------
+const log = createLogger("nodetool.base-nodes.agents");
+/**
+ * Sanitize a node title to a valid tool name (snake_case, max 64 chars).
+ * Prefixed with `run_` to avoid collisions with provider-reserved built-in
+ * tool names (e.g. Gemini's native `google_search`, which would otherwise
+ * shadow our schema and pass `queries` instead of the node's actual props).
+ */
+function sanitizeControlToolName(name) {
+    const fallback = "run_node";
+    if (!name)
+        return fallback;
+    let s = name
+        .replace(/[^a-zA-Z0-9]/g, "_")
+        .replace(/([a-z])([A-Z])/g, "$1_$2")
+        .toLowerCase()
+        .replace(/_+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    if (!s)
+        return fallback;
+    s = `run_${s}`;
+    if (s.length > 64)
+        s = s.slice(0, 64);
+    return s;
+}
+/**
+ * Build control tools from `_control_context` input. Each tool's `process`
+ * filters the model's arguments to the node's declared properties, then
+ * dispatches a control event through the context and returns the result — so
+ * control tools run through the same generic `tool.process` path as any other
+ * tool (including plan mode's ToolLikeAdapter).
+ */
+export function buildControlTools(controlContext) {
+    if (!isObjectLike(controlContext))
+        return [];
+    const tools = [];
+    const usedNames = new Set();
+    for (const [targetId, info] of Object.entries(controlContext)) {
+        if (!isObjectLike(info))
+            continue;
+        const nodeInfo = info;
+        const nodeTitle = String(nodeInfo.node_title ?? nodeInfo.node_type ?? targetId);
+        const baseName = sanitizeControlToolName(nodeTitle);
+        let toolName = baseName;
+        let suffix = 2;
+        while (usedNames.has(toolName)) {
+            const suffixText = `_${suffix}`;
+            toolName = `${baseName.slice(0, 64 - suffixText.length)}${suffixText}`;
+            suffix++;
+        }
+        usedNames.add(toolName);
+        // Build input schema from control_actions.run.properties
+        const actions = (nodeInfo.control_actions ?? {});
+        const runAction = (actions.run ?? {});
+        const rawProperties = (runAction.properties ?? {});
+        const properties = {};
+        for (const [key, schema] of Object.entries(rawProperties)) {
+            if (isObjectLike(schema)) {
+                properties[key] = { ...schema };
+            }
+            else {
+                properties[key] = { type: "string", description: String(schema) };
+            }
+        }
+        const inputSchema = {
+            type: "object",
+            properties,
+            required: [],
+            additionalProperties: false
+        };
+        let description = `Control ${nodeTitle}: trigger execution with optional property overrides`;
+        const propNames = Object.keys(properties);
+        if (propNames.length > 0) {
+            description += `. Available properties: ${propNames.join(", ")}`;
+        }
+        const allowedProperties = new Set(propNames);
+        tools.push({
+            targetNodeId: targetId,
+            name: toolName,
+            description,
+            inputSchema,
+            async process(context, params) {
+                const callArgs = Object.fromEntries(Object.entries(params ?? {}).filter(([key]) => allowedProperties.has(key)));
+                log.info("Control tool dispatching", {
+                    toolName,
+                    targetNodeId: targetId,
+                    argKeys: Object.keys(callArgs)
+                });
+                if (!context.hasControlEventSupport) {
+                    return {
+                        status: "error",
+                        target_node_id: targetId,
+                        error: "Control event dispatch is not available in this execution context"
+                    };
+                }
+                try {
+                    const result = await context.sendControlEvent(targetId, callArgs);
+                    return {
+                        status: "completed",
+                        target_node_id: targetId,
+                        result
+                    };
+                }
+                catch (err) {
+                    return {
+                        status: "error",
+                        target_node_id: targetId,
+                        error: err instanceof Error ? err.message : String(err)
+                    };
+                }
+            },
+            toProviderTool() {
+                return { name: toolName, description, inputSchema };
+            }
+        });
+    }
+    return tools;
+}
+//# sourceMappingURL=agent-control-tools.js.map

package/dist/nodes/agent-control-tools.js.map

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

package/dist/nodes/agent-loop.d.ts

@@ -0,0 +1,73 @@
+import type { Message, MessageContent, ProcessingContext } from "@nodetool-ai/runtime";
+import type { Chunk } from "@nodetool-ai/protocol";
+import { Tool as AgentTool } from "@nodetool-ai/agents";
+import type { ToolLike, ToolResult } from "./agent-utils.js";
+/**
+ * Adapter that wraps a ToolLike (from base-nodes) as an AgentTool (from @nodetool-ai/agents).
+ * This bridges the tool systems so Agent can use tools defined in the node graph.
+ */
+export declare class ToolLikeAdapter extends AgentTool {
+    readonly name: string;
+    readonly description: string;
+    protected readonly jsonSchema: Record<string, unknown>;
+    private readonly _process;
+    private readonly _execute;
+    constructor(toolLike: ToolLike);
+    /**
+     * Delegate to the wrapped tool's own `execute` when it has one: that is
+     * where param stripping/coercion and `toolCallId` forwarding live, and
+     * double-wrapping through `process` would skip both.
+     */
+    execute(context: ProcessingContext, params: Record<string, unknown> | null | undefined, options?: {
+        toolCallId?: string;
+    }): Promise<unknown>;
+    process(context: ProcessingContext, params: Record<string, unknown>): Promise<ToolResult>;
+}
+export interface AgentLoopOptions {
+    context: ProcessingContext;
+    providerId: string;
+    modelId: string;
+    systemPrompt: string;
+    prompt: string;
+    /**
+     * Tools the model may call. Each may be a fully-formed {@link ToolLike} (has
+     * `process` + `inputSchema`) OR a bare name-stub (`{ name }`) for a builtin
+     * tool registered via `registerBuiltinAgentToolClasses` — runAgentLoop
+     * hydrates stubs by name. Anything that can't be hydrated (no `process`) is
+     * logged and treated as an unknown tool by the model.
+     */
+    tools: ToolLike[];
+    contentParts?: MessageContent[];
+    maxTokens?: number;
+    maxIterations?: number;
+    threadId?: string;
+    /**
+     * Optional sink for streamed assistant text deltas (non-thinking). Lets a
+     * caller surface incremental output (e.g. a node `chunk` output) without
+     * changing the loop's accumulate-and-return contract.
+     */
+    onText?: (delta: string) => void;
+    /**
+     * Optional sink for each tool call the model makes, formatted as a
+     * `tool_call` {@link Chunk} (same shape the Agent node emits). Fired just
+     * before the tool runs.
+     */
+    onToolCall?: (chunk: Chunk) => void;
+}
+export interface AgentLoopResult {
+    text: string;
+    messages: Message[];
+}
+/**
+ * Run a streaming tool-use loop: the model streams text/tool-calls, tools
+ * execute, results feed back, repeat until no more tool calls or
+ * `maxIterations`. Returns the final assistant text plus the full message
+ * trail. Stream via `onText` / `onToolCall`.
+ *
+ * Tools (`options.tools`) may be real {@link ToolLike}s or bare `{ name }`
+ * stubs for registered builtin tools — they are hydrated here (see the `tools`
+ * field doc). This mirrors the AgentNode's `normalizeTools`; both paths now
+ * hydrate, so a tool reaches the loop the same way regardless of entry point.
+ */
+export declare function runAgentLoop(options: AgentLoopOptions): Promise<AgentLoopResult>;
+//# sourceMappingURL=agent-loop.d.ts.map

package/dist/nodes/agent-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-loop.d.ts","sourceRoot":"","sources":["../../src/nodes/agent-loop.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,OAAO,EACP,cAAc,EACd,iBAAiB,EAElB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAY7D;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,SAAS;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAGA;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAE/C,YAAY,QAAQ,EAAE,QAAQ,EAY7B;IAED;;;;OAIG;IACG,OAAO,CACX,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EAClD,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO,GACpC,OAAO,CAAC,OAAO,CAAC,CAKlB;IAEK,OAAO,CACX,OAAO,EAAE,iBAAiB,EAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,UAAU,CAAC,CAErB;CACF;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CAmI1B"}

package/dist/nodes/agent-loop.js

@@ -0,0 +1,168 @@
+import { createLogger } from "@nodetool-ai/config";
+import { Tool as AgentTool } from "@nodetool-ai/agents";
+import { hydrateBuiltinAgentTools } from "./agent-tool-hydration.js";
+import { classifyProviderStream, serializeToolResult, toProviderTools, toolCallChunk } from "./agent-utils.js";
+import { meterProviderSpend } from "./provider-spend.js";
+import { isCallable } from "@nodetool-ai/node-sdk";
+const log = createLogger("nodetool.base-nodes.agents");
+/**
+ * Adapter that wraps a ToolLike (from base-nodes) as an AgentTool (from @nodetool-ai/agents).
+ * This bridges the tool systems so Agent can use tools defined in the node graph.
+ */
+export class ToolLikeAdapter extends AgentTool {
+    name;
+    description;
+    jsonSchema;
+    _process;
+    _execute;
+    constructor(toolLike) {
+        super();
+        this.name = toolLike.name;
+        this.description = toolLike.description ?? "";
+        this.jsonSchema = toolLike.inputSchema ?? {
+            type: "object",
+            properties: {}
+        };
+        this._execute = toolLike.execute;
+        this._process =
+            toolLike.process ??
+                (async () => ({ error: "Tool has no process implementation" }));
+    }
+    /**
+     * Delegate to the wrapped tool's own `execute` when it has one: that is
+     * where param stripping/coercion and `toolCallId` forwarding live, and
+     * double-wrapping through `process` would skip both.
+     */
+    async execute(context, params, options = {}) {
+        if (this._execute) {
+            return this._execute(context, params ?? {}, options);
+        }
+        return super.execute(context, params, options);
+    }
+    async process(context, params) {
+        return this._process(context, params);
+    }
+}
+/**
+ * Run a streaming tool-use loop: the model streams text/tool-calls, tools
+ * execute, results feed back, repeat until no more tool calls or
+ * `maxIterations`. Returns the final assistant text plus the full message
+ * trail. Stream via `onText` / `onToolCall`.
+ *
+ * Tools (`options.tools`) may be real {@link ToolLike}s or bare `{ name }`
+ * stubs for registered builtin tools — they are hydrated here (see the `tools`
+ * field doc). This mirrors the AgentNode's `normalizeTools`; both paths now
+ * hydrate, so a tool reaches the loop the same way regardless of entry point.
+ */
+export async function runAgentLoop(options) {
+    const { context, providerId, modelId, systemPrompt, prompt, tools, contentParts, maxTokens = 4096, maxIterations = 10 } = options;
+    if (!context || !isCallable(context.getProvider)) {
+        throw new Error("Processing context with provider access is required");
+    }
+    const userContent = [{ type: "text", text: prompt }];
+    if (contentParts) {
+        userContent.push(...contentParts);
+    }
+    const messages = [
+        { role: "system", content: systemPrompt },
+        { role: "user", content: userContent }
+    ];
+    // Hydrate builtin tools passed as bare name-stubs ({ name }) into real Tool
+    // instances (same as the AgentNode path's normalizeTools). Without this a
+    // stub has no `process`/`inputSchema`, so the model gets a schemaless tool
+    // and every call is rejected as "Unknown tool". A real Tool passes through
+    // unchanged. Warn for anything still unrunnable so it fails loudly, not
+    // silently.
+    const resolvedTools = hydrateBuiltinAgentTools(tools);
+    for (const t of resolvedTools) {
+        if (!isCallable(t.process)) {
+            log.warn(`runAgentLoop received tool '${t.name}' with no process() and could ` +
+                "not hydrate it — the model cannot call it. Pass a real Tool or a " +
+                "registered builtin tool name.");
+        }
+    }
+    // The provider drives the tool-calling loop via generateLoop. This is what
+    // makes the Claude Agent SDK provider work: it registers `providerTools` as
+    // an in-process MCP server and runs the SDK's own loop, while normal
+    // providers run the standard completion loop. Each provider tool carries its
+    // own `execute` (generateLoop dispatches to it), so there is no harness-level
+    // executeTool callback. The stream surfaces text chunks (for onText),
+    // tool-call announcements (for onToolCall), and finalized message events
+    // (assistant turns + tool results) that we collect into the returned
+    // conversation. There is no terminal tool here — the loop ends when the model
+    // stops calling tools.
+    const providerTools = resolvedTools.length > 0
+        ? toProviderTools(resolvedTools).map((pt, i) => {
+            const tool = resolvedTools[i];
+            return {
+                ...pt,
+                execute: async (args) => {
+                    if (!isCallable(tool.process)) {
+                        return JSON.stringify({ error: `Unknown tool: ${tool.name}` });
+                    }
+                    const result = await tool.process(context, args);
+                    return JSON.stringify(serializeToolResult(result));
+                }
+            };
+        })
+        : undefined;
+    const provider = await context.getProvider(providerId);
+    // generateLoop owns its own copy of the message array internally, so rebuild
+    // the full returned conversation locally from the message events it streams.
+    const outMessages = [...messages];
+    let lastAssistantText = "";
+    let currentTurnText = "";
+    const stream = provider.generateLoop({
+        messages,
+        model: modelId,
+        tools: providerTools,
+        maxTokens,
+        threadId: options.threadId,
+        maxIterations,
+        // Run-level cancellation: without it a cancelled workflow leaves this
+        // loop (and its tool calls) running.
+        signal: context.signal
+    });
+    // Book this loop's token spend against the calling node, so the run leaves a
+    // prediction row. See `meterProviderSpend`.
+    const spend = meterProviderSpend(context, provider, modelId);
+    try {
+        for await (const event of classifyProviderStream(stream)) {
+            if (event.kind === "tool_call") {
+                options.onToolCall?.(toolCallChunk(event.toolCall));
+                continue;
+            }
+            if (event.kind === "text") {
+                // Only genuine text feeds the returned text / onText stream. Tool-call
+                // chunks (and audio, agent_status, etc.) carry content_type !== "text"
+                // and must not leak into the text output.
+                if (event.chunk.content_type === "text" && event.delta) {
+                    currentTurnText += event.delta;
+                    options.onText?.(event.delta);
+                }
+                continue;
+            }
+            // thinking / audio events carry no returned text — ignore them here.
+            if (event.kind === "assistant_message" || event.kind === "tool_message") {
+                // A finalized message event. Append it to the returned trail; an
+                // assistant turn also closes the current text run so `text` reflects
+                // the model's last assistant message, not a concatenation.
+                outMessages.push(event.message);
+                if (event.kind === "assistant_message") {
+                    if (currentTurnText)
+                        lastAssistantText = currentTurnText;
+                    currentTurnText = "";
+                }
+            }
+        }
+    }
+    finally {
+        spend.report();
+    }
+    // A provider that runs its own loop may stream final text without a trailing
+    // assistant message event — keep that text.
+    if (currentTurnText)
+        lastAssistantText = currentTurnText;
+    return { text: lastAssistantText, messages: outMessages };
+}
+//# sourceMappingURL=agent-loop.js.map

package/dist/nodes/agent-loop.js.map

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