@nodetool-ai/llm-nodes 0.8.1

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

@@ -0,0 +1,29 @@
+import type { Chunk } from "@nodetool-ai/protocol";
+export declare function extractThinkTags(text: string): {
+    thinking: string;
+    text: string;
+};
+/**
+ * Splits streamed text so `<think>…` never appears on the text channel:
+ * reasoning goes to `thinking`, user-visible text to `text` chunks only.
+ */
+export declare class RedactedThinkingStreamSplitter {
+    private buf;
+    private inThink;
+    feed(incoming: string): Generator<{
+        kind: "text";
+        content: string;
+    } | {
+        kind: "thinking";
+        content: string;
+    }>;
+    flush(): Generator<{
+        kind: "text";
+        content: string;
+    } | {
+        kind: "thinking";
+        content: string;
+    }>;
+}
+export declare function yieldSplitThinkChunks(item: Chunk, rawPiece: string, splitter: RedactedThinkingStreamSplitter): Generator<Record<string, unknown>>;
+//# sourceMappingURL=agent-thinking.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-thinking.d.ts","sourceRoot":"","sources":["../../src/nodes/agent-thinking.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAwCnD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM;IAazC,QAAQ;IACR,IAAI;EAEP;AAED;;;GAGG;AACH,qBAAa,8BAA8B;IACzC,OAAO,CAAC,GAAG,CAAM;IACjB,OAAO,CAAC,OAAO,CAAS;IAEvB,IAAI,CACH,QAAQ,EAAE,MAAM,GACf,SAAS,CACV;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAC1E,CA+CA;IAEA,KAAK,IAAI,SAAS,CACjB;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAC1E,CASA;CACF;AAED,wBAAiB,qBAAqB,CACpC,IAAI,EAAE,KAAK,EACX,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,8BAA8B,GACvC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAsBpC"}

package/dist/nodes/agent-thinking.js

@@ -0,0 +1,139 @@
+/**
+ * Opening tag plus the close tags models may emit. The canonical close is
+ * `</redacted_thinking>`; `</think>` is the legacy/typo variant. Both must be
+ * recognized so the streaming splitter matches what `extractThinkTags` does.
+ */
+const REDACTED_THINKING_OPEN = "<think>";
+const REDACTED_THINKING_CLOSES = ["</redacted_thinking>", "</think>"];
+function findEarliestThinkClose(buf) {
+    let best = null;
+    for (const c of REDACTED_THINKING_CLOSES) {
+        const i = buf.indexOf(c);
+        if (i !== -1 && (best === null || i < best.idx)) {
+            best = { idx: i, len: c.length };
+        }
+    }
+    return best;
+}
+/** Longest suffix of buf that is a proper prefix of one of the candidate strings (for streaming). */
+function holdSuffixForPartialTag(buf, candidates) {
+    const maxCheck = Math.max(0, ...candidates.map((c) => Math.max(0, c.length - 1)));
+    const limit = Math.min(buf.length, maxCheck);
+    for (let len = limit; len >= 1; len--) {
+        const suf = buf.slice(-len);
+        if (candidates.some((c) => c.startsWith(suf)))
+            return len;
+    }
+    return 0;
+}
+export function extractThinkTags(text) {
+    const parts = [];
+    const re = /<think>([\s\S]*?)<\/(?:redacted_thinking|think)>/g;
+    let cleaned = text.replace(re, (_, content) => {
+        parts.push(content.trim());
+        return "";
+    });
+    const orphan = cleaned.match(/<think>([\s\S]*)$/);
+    if (orphan && orphan.index !== undefined) {
+        parts.push(orphan[1].trim());
+        cleaned = cleaned.slice(0, orphan.index);
+    }
+    return {
+        thinking: parts.filter((p) => p.length > 0).join("\n\n"),
+        text: cleaned.trim()
+    };
+}
+/**
+ * Splits streamed text so `<think>…` never appears on the text channel:
+ * reasoning goes to `thinking`, user-visible text to `text` chunks only.
+ */
+export class RedactedThinkingStreamSplitter {
+    buf = "";
+    inThink = false;
+    *feed(incoming) {
+        if (!incoming)
+            return;
+        this.buf += incoming;
+        while (true) {
+            if (!this.inThink) {
+                const openIdx = this.buf.indexOf(REDACTED_THINKING_OPEN);
+                if (openIdx === -1) {
+                    const keep = holdSuffixForPartialTag(this.buf, [
+                        REDACTED_THINKING_OPEN
+                    ]);
+                    if (this.buf.length > keep) {
+                        const emitEnd = this.buf.length - keep;
+                        const out = this.buf.slice(0, emitEnd);
+                        this.buf = this.buf.slice(emitEnd);
+                        if (out)
+                            yield { kind: "text", content: out };
+                    }
+                    return;
+                }
+                if (openIdx > 0) {
+                    const out = this.buf.slice(0, openIdx);
+                    if (out)
+                        yield { kind: "text", content: out };
+                }
+                this.buf = this.buf.slice(openIdx + REDACTED_THINKING_OPEN.length);
+                this.inThink = true;
+                continue;
+            }
+            const close = findEarliestThinkClose(this.buf);
+            if (!close) {
+                const keep = holdSuffixForPartialTag(this.buf, REDACTED_THINKING_CLOSES);
+                if (this.buf.length > keep) {
+                    const emitEnd = this.buf.length - keep;
+                    const out = this.buf.slice(0, emitEnd);
+                    this.buf = this.buf.slice(emitEnd);
+                    if (out)
+                        yield { kind: "thinking", content: out };
+                }
+                return;
+            }
+            const thinkBody = this.buf.slice(0, close.idx);
+            this.buf = this.buf.slice(close.idx + close.len);
+            this.inThink = false;
+            if (thinkBody)
+                yield { kind: "thinking", content: thinkBody };
+        }
+    }
+    *flush() {
+        if (!this.buf && !this.inThink)
+            return;
+        if (this.inThink) {
+            if (this.buf)
+                yield { kind: "thinking", content: this.buf };
+        }
+        else if (this.buf) {
+            yield { kind: "text", content: this.buf };
+        }
+        this.buf = "";
+        this.inThink = false;
+    }
+}
+export function* yieldSplitThinkChunks(item, rawPiece, splitter) {
+    for (const part of splitter.feed(rawPiece)) {
+        if (part.kind === "text" && part.content.length > 0) {
+            yield {
+                chunk: { ...item, content: part.content },
+                thinking: null,
+                text: null,
+                audio: null
+            };
+        }
+        else if (part.kind === "thinking" && part.content.length > 0) {
+            yield {
+                chunk: null,
+                thinking: {
+                    type: "chunk",
+                    content: part.content,
+                    thinking: true
+                },
+                text: null,
+                audio: null
+            };
+        }
+    }
+}
+//# sourceMappingURL=agent-thinking.js.map

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

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

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

@@ -0,0 +1,17 @@
+import type { Message, ProcessingContext } from "@nodetool-ai/runtime";
+type ThreadLike = {
+    id: string;
+    title: string;
+    messages: Message[];
+};
+export declare const THREAD_STORE: Map<string, ThreadLike>;
+/**
+ * Get-or-create a fallback thread and mark it most-recently-used (Map keeps
+ * insertion order, so delete+set moves it to the end). Evicts the oldest
+ * threads once the cap is exceeded.
+ */
+export declare function seedFallbackThread(threadId: string, title: string): ThreadLike;
+export declare function loadThreadMessages(context: ProcessingContext | undefined, threadId: string): Promise<Message[]>;
+export declare function saveThreadMessage(context: ProcessingContext | undefined, threadId: string, message: Message): Promise<void>;
+export {};
+//# sourceMappingURL=agent-threads.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-threads.d.ts","sourceRoot":"","sources":["../../src/nodes/agent-threads.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAKvE,KAAK,UAAU,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,EAAE,CAAA;CAAE,CAAC;AAYrE,eAAO,MAAM,YAAY,yBAAgC,CAAC;AAE1D;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,UAAU,CAW9E;AAED,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,iBAAiB,GAAG,SAAS,EACtC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,EAAE,CAAC,CA4BpB;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,iBAAiB,GAAG,SAAS,EACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,GACf,OAAO,CAAC,IAAI,CAAC,CAmCf"}

package/dist/nodes/agent-threads.js

@@ -0,0 +1,93 @@
+import { createLogger } from "@nodetool-ai/config";
+import { messageContentText, normalizeMessage } from "./agent-utils.js";
+const log = createLogger("nodetool.base-nodes.agents");
+// In-memory thread store used ONLY as a fallback for runs where the context
+// has no message-store model interface wired — hermetic CLI runs
+// (`node run --no-secrets`) and unit tests. When the store IS wired, agent
+// nodes read/write the DB-backed context directly and DB errors propagate; the
+// map below is never touched. It is bounded so a long-running provider-less
+// process can't leak: at most MAX_THREADS threads (least-recently-used evicted)
+// and MAX_MESSAGES_PER_THREAD messages per thread (oldest dropped).
+const MAX_THREADS = 100;
+const MAX_MESSAGES_PER_THREAD = 1000;
+export const THREAD_STORE = new Map();
+/**
+ * Get-or-create a fallback thread and mark it most-recently-used (Map keeps
+ * insertion order, so delete+set moves it to the end). Evicts the oldest
+ * threads once the cap is exceeded.
+ */
+export function seedFallbackThread(threadId, title) {
+    const existing = THREAD_STORE.get(threadId);
+    const thread = existing ?? { id: threadId, title, messages: [] };
+    if (existing)
+        THREAD_STORE.delete(threadId);
+    THREAD_STORE.set(threadId, thread);
+    while (THREAD_STORE.size > MAX_THREADS) {
+        const oldest = THREAD_STORE.keys().next().value;
+        if (oldest === undefined || oldest === threadId)
+            break;
+        THREAD_STORE.delete(oldest);
+    }
+    return thread;
+}
+export async function loadThreadMessages(context, threadId) {
+    if (!threadId)
+        return [];
+    // DB-backed path: the getMessages interface is wired, so read through the
+    // typed context method and let any error propagate (no silent fallback).
+    if (context?.hasModelInterface?.("getMessages")) {
+        const result = await context.getThreadMessages(threadId, 1000, null, false);
+        const messages = (result.messages ?? [])
+            .map((item) => normalizeMessage(item))
+            .filter((message) => message !== null && message.role !== "system");
+        log.info("Agent thread history loaded from context", {
+            threadId,
+            messageCount: messages.length
+        });
+        return messages;
+    }
+    const fallbackMessages = (THREAD_STORE.get(threadId)?.messages ?? [])
+        .filter((message) => message.role !== "system")
+        .map((message) => ({ ...message }));
+    log.info("Agent thread history loaded from fallback store", {
+        threadId,
+        messageCount: fallbackMessages.length
+    });
+    return fallbackMessages;
+}
+export async function saveThreadMessage(context, threadId, message) {
+    if (!threadId)
+        return;
+    // DB-backed path: the createMessage interface is wired, so write through the
+    // typed context method and let any error propagate (no silent fallback that
+    // would disguise data loss as success).
+    if (context?.hasModelInterface?.("createMessage")) {
+        await context.createMessage({
+            thread_id: threadId,
+            role: message.role,
+            content: message.content ?? null,
+            tool_calls: message.toolCalls ?? null,
+            tool_call_id: message.toolCallId ?? null
+        });
+        log.info("Agent thread message saved via context", {
+            threadId,
+            role: message.role,
+            hasToolCalls: (message.toolCalls?.length ?? 0) > 0,
+            textLength: messageContentText(message.content).length
+        });
+        return;
+    }
+    const thread = seedFallbackThread(threadId, "Agent Conversation");
+    thread.messages.push({ ...message, threadId });
+    while (thread.messages.length > MAX_MESSAGES_PER_THREAD) {
+        thread.messages.shift();
+    }
+    log.info("Agent thread message saved via fallback store", {
+        threadId,
+        role: message.role,
+        threadSize: thread.messages.length,
+        hasToolCalls: (message.toolCalls?.length ?? 0) > 0,
+        textLength: messageContentText(message.content).length
+    });
+}
+//# sourceMappingURL=agent-threads.js.map

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

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

package/dist/nodes/agent-tool-hydration.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Builtin agent-tool registry + hydration.
+ *
+ * Tools can be referenced by name as bare stubs (`{ name }`) and hydrated into
+ * real `Tool` instances on demand. The registry is the default agent toolbelt
+ * (`getBuiltinTools()` — no hand-maintained name list) plus anything other
+ * modules append via {@link registerBuiltinAgentToolClasses} at load time
+ * (e.g. `sandbox.ts` registers the `browser_*` CDP tools).
+ *
+ * CONTRACT: a name-stub is NOT executable until hydrated. `runAgentLoop` and
+ * the AgentNode (`normalizeTools`) both hydrate their `tools` before use, so a
+ * stub or a real Tool reaches the loop equivalently. Any other caller that
+ * builds tools by name and runs them itself MUST call
+ * {@link resolveBuiltinAgentTool} / {@link hydrateBuiltinAgentTool} first — an
+ * unhydrated stub has no `process`/`inputSchema` and silently can't be called.
+ */
+import { Tool } from "@nodetool-ai/agents";
+type ToolCtor = new () => Tool;
+type MaybeTool = {
+    name: string;
+    process?: unknown;
+};
+/**
+ * Append additional Tool classes to the built-in registry. Called from
+ * other modules (e.g. `sandbox.ts`) at module-load time so they don't have
+ * to be imported here, which would re-introduce a circular dependency.
+ */
+export declare function registerBuiltinAgentToolClasses(classes: ToolCtor[]): void;
+/**
+ * Register a factory that produces Tool classes on demand. Unlike
+ * `registerBuiltinAgentToolClasses`, the factory is called lazily on the
+ * first `resolveBuiltinAgentTool` call, after all modules are initialized.
+ * Use this when the tool classes depend on module-level constants that may
+ * not be initialized at the time the registering module is evaluated (e.g.
+ * `BROWSER_ACTION_SPECS` in esbuild bundles where `__esm` lazy init can
+ * cause the constant to be `undefined` at module load time).
+ */
+export declare function registerBuiltinAgentToolFactory(factory: () => ToolCtor[]): void;
+/** Resolve a registered builtin tool by name to a runnable `Tool`, or null. */
+export declare function resolveBuiltinAgentTool(name: string): Tool | null;
+/**
+ * Hydrate one tool: a real tool (has `process`) passes through unchanged; a
+ * bare name-stub is resolved from the registry (or returned as-is if unknown,
+ * so the caller can detect the still-unrunnable stub).
+ */
+export declare function hydrateBuiltinAgentTool<T extends MaybeTool>(tool: T): T | Tool;
+/** Hydrate a list of tools — see {@link hydrateBuiltinAgentTool}. */
+export declare function hydrateBuiltinAgentTools<T extends MaybeTool>(tools: T[]): Array<T | Tool>;
+export {};
+//# sourceMappingURL=agent-tool-hydration.d.ts.map

package/dist/nodes/agent-tool-hydration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tool-hydration.d.ts","sourceRoot":"","sources":["../../src/nodes/agent-tool-hydration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAkC,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAG3E,KAAK,QAAQ,GAAG,UAAU,IAAI,CAAC;AAE/B,KAAK,SAAS,GAAG;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAmCF;;;;GAIG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,QAAQ,EAAE,GAAG,IAAI,CAGzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,MAAM,QAAQ,EAAE,GAAG,IAAI,CAG/E;AAED,+EAA+E;AAC/E,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAgBjE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,SAAS,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,IAAI,CAG9E;AAED,qEAAqE;AACrE,wBAAgB,wBAAwB,CAAC,CAAC,SAAS,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,CAEzF"}

package/dist/nodes/agent-tool-hydration.js

@@ -0,0 +1,106 @@
+/**
+ * Builtin agent-tool registry + hydration.
+ *
+ * Tools can be referenced by name as bare stubs (`{ name }`) and hydrated into
+ * real `Tool` instances on demand. The registry is the default agent toolbelt
+ * (`getBuiltinTools()` — no hand-maintained name list) plus anything other
+ * modules append via {@link registerBuiltinAgentToolClasses} at load time
+ * (e.g. `sandbox.ts` registers the `browser_*` CDP tools).
+ *
+ * CONTRACT: a name-stub is NOT executable until hydrated. `runAgentLoop` and
+ * the AgentNode (`normalizeTools`) both hydrate their `tools` before use, so a
+ * stub or a real Tool reaches the loop equivalently. Any other caller that
+ * builds tools by name and runs them itself MUST call
+ * {@link resolveBuiltinAgentTool} / {@link hydrateBuiltinAgentTool} first — an
+ * unhydrated stub has no `process`/`inputSchema` and silently can't be called.
+ */
+import { getBuiltinTools, getMediaTools } from "@nodetool-ai/agents";
+import { isCallable } from "@nodetool-ai/node-sdk";
+/**
+ * Names a saved workflow may still carry, mapped to what replaced them.
+ *
+ * The provider-specific search and media tools were retired: one `web_search`
+ * chooses a backend host-side and takes a `search_type` for news, image
+ * search is the dedicated `image_search`, and `generate_image` /
+ * `generate_speech` are provider-agnostic. An AgentNode saved before that
+ * stores the old name as a bare stub, and a stub that resolves to nothing is
+ * silently uncallable — so resolve it to the tool that took over instead.
+ */
+const RETIRED_TOOL_NAMES = {
+    openai_web_search: "web_search",
+    google_grounded_search: "web_search",
+    dataforseo_search: "web_search",
+    // The news search folded into `web_search`'s `search_type`; image search
+    // split out into its own `image_search` tool. A hydrated stub carries the
+    // name only, so it lands on a real tool — one that exists and answers,
+    // rather than resolving to nothing and being silently uncallable, which is
+    // what this map is for.
+    dataforseo_news: "web_search",
+    google_news: "web_search",
+    dataforseo_images: "image_search",
+    google_images: "image_search",
+    image_generation: "generate_image",
+    openai_image_generation: "generate_image",
+    google_image_generation: "generate_image",
+    openai_text_to_speech: "generate_speech"
+};
+const extraToolClasses = [];
+const toolFactories = [];
+let builtinAgentTools = null;
+/**
+ * Append additional Tool classes to the built-in registry. Called from
+ * other modules (e.g. `sandbox.ts`) at module-load time so they don't have
+ * to be imported here, which would re-introduce a circular dependency.
+ */
+export function registerBuiltinAgentToolClasses(classes) {
+    for (const c of classes)
+        extraToolClasses.push(c);
+    builtinAgentTools = null;
+}
+/**
+ * Register a factory that produces Tool classes on demand. Unlike
+ * `registerBuiltinAgentToolClasses`, the factory is called lazily on the
+ * first `resolveBuiltinAgentTool` call, after all modules are initialized.
+ * Use this when the tool classes depend on module-level constants that may
+ * not be initialized at the time the registering module is evaluated (e.g.
+ * `BROWSER_ACTION_SPECS` in esbuild bundles where `__esm` lazy init can
+ * cause the constant to be `undefined` at module load time).
+ */
+export function registerBuiltinAgentToolFactory(factory) {
+    toolFactories.push(factory);
+    builtinAgentTools = null;
+}
+/** Resolve a registered builtin tool by name to a runnable `Tool`, or null. */
+export function resolveBuiltinAgentTool(name) {
+    if (!builtinAgentTools) {
+        builtinAgentTools = new Map();
+        for (const tool of [...getBuiltinTools(), ...getMediaTools()]) {
+            builtinAgentTools.set(tool.name, tool);
+        }
+        const dynamicClasses = toolFactories.flatMap((f) => f());
+        for (const ToolClass of [...extraToolClasses, ...dynamicClasses]) {
+            const tool = new ToolClass();
+            builtinAgentTools.set(tool.name, tool);
+        }
+    }
+    const direct = builtinAgentTools.get(name);
+    if (direct)
+        return direct;
+    const replacement = RETIRED_TOOL_NAMES[name];
+    return replacement ? (builtinAgentTools.get(replacement) ?? null) : null;
+}
+/**
+ * Hydrate one tool: a real tool (has `process`) passes through unchanged; a
+ * bare name-stub is resolved from the registry (or returned as-is if unknown,
+ * so the caller can detect the still-unrunnable stub).
+ */
+export function hydrateBuiltinAgentTool(tool) {
+    if (isCallable(tool.process))
+        return tool;
+    return resolveBuiltinAgentTool(tool.name) ?? tool;
+}
+/** Hydrate a list of tools — see {@link hydrateBuiltinAgentTool}. */
+export function hydrateBuiltinAgentTools(tools) {
+    return tools.map(hydrateBuiltinAgentTool);
+}
+//# sourceMappingURL=agent-tool-hydration.js.map

package/dist/nodes/agent-tool-hydration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tool-hydration.js","sourceRoot":"","sources":["../../src/nodes/agent-tool-hydration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,eAAe,EAAE,aAAa,EAAQ,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AASnD;;;;;;;;;GASG;AACH,MAAM,kBAAkB,GAAqC;IAC3D,iBAAiB,EAAE,YAAY;IAC/B,sBAAsB,EAAE,YAAY;IACpC,iBAAiB,EAAE,YAAY;IAC/B,yEAAyE;IACzE,0EAA0E;IAC1E,uEAAuE;IACvE,2EAA2E;IAC3E,wBAAwB;IACxB,eAAe,EAAE,YAAY;IAC7B,WAAW,EAAE,YAAY;IACzB,iBAAiB,EAAE,cAAc;IACjC,aAAa,EAAE,cAAc;IAC7B,gBAAgB,EAAE,gBAAgB;IAClC,uBAAuB,EAAE,gBAAgB;IACzC,uBAAuB,EAAE,gBAAgB;IACzC,qBAAqB,EAAE,iBAAiB;CACzC,CAAC;AAEF,MAAM,gBAAgB,GAAe,EAAE,CAAC;AACxC,MAAM,aAAa,GAAyB,EAAE,CAAC;AAC/C,IAAI,iBAAiB,GAA6B,IAAI,CAAC;AAEvD;;;;GAIG;AACH,MAAM,UAAU,+BAA+B,CAAC,OAAmB;IACjE,KAAK,MAAM,CAAC,IAAI,OAAO;QAAE,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClD,iBAAiB,GAAG,IAAI,CAAC;AAC3B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,+BAA+B,CAAC,OAAyB;IACvE,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5B,iBAAiB,GAAG,IAAI,CAAC;AAC3B,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,uBAAuB,CAAC,IAAY;IAClD,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACvB,iBAAiB,GAAG,IAAI,GAAG,EAAgB,CAAC;QAC5C,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,eAAe,EAAE,EAAE,GAAG,aAAa,EAAE,CAAC,EAAE,CAAC;YAC9D,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACzC,CAAC;QACD,MAAM,cAAc,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QACzD,KAAK,MAAM,SAAS,IAAI,CAAC,GAAG,gBAAgB,EAAE,GAAG,cAAc,CAAC,EAAE,CAAC;YACjE,MAAM,IAAI,GAAG,IAAI,SAAS,EAAE,CAAC;YAC7B,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3C,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,MAAM,WAAW,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAC7C,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAsB,IAAO;IAClE,IAAI,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,OAAO,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AACpD,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,wBAAwB,CAAsB,KAAU;IACtE,OAAO,KAAK,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC;AAC5C,CAAC"}

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

@@ -0,0 +1,174 @@
+import type { BaseNode } from "@nodetool-ai/node-sdk";
+import { type PermissionGateOptions } from "@nodetool-ai/agents";
+import type { BaseProvider, Message, MessageContent, ProcessingContext, ProviderStop, ProviderStreamItem, ToolCall } from "@nodetool-ai/runtime";
+import { extractJson, generateStructured } from "@nodetool-ai/runtime";
+import type { Chunk } from "@nodetool-ai/protocol";
+export { extractJson, generateStructured };
+/**
+ * What a tool hands back: a primitive, or any object — a record, an array, a
+ * byte buffer. `serializeToolResult` renders it to JSON before it reaches the
+ * model.
+ */
+export type ToolResult = string | number | boolean | null | undefined | object;
+export type ToolLike = {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    process?: (context: ProcessingContext, params: Record<string, unknown>) => Promise<ToolResult>;
+    /**
+     * Preferred entry point when present (agent-system tools have one): strips
+     * reserved fields like `_message` and coerces params against the tool's
+     * schema before dispatching to `process`.
+     */
+    execute?: (context: ProcessingContext, params: Record<string, unknown>, options?: {
+        toolCallId?: string;
+    }) => Promise<ToolResult>;
+    toProviderTool?: () => {
+        name: string;
+        description?: string;
+        inputSchema?: Record<string, unknown>;
+    };
+};
+export declare function asText(value: unknown): string;
+export declare function makeThreadId(): string;
+export declare function getCategories(value: unknown): string[];
+export declare function getModelConfig(props: Record<string, unknown>): {
+    providerId: string;
+    modelId: string;
+};
+/**
+ * Whether this context can hand out a provider. False for the bare context a
+ * hermetic single-node run supplies, which carries no provider access.
+ */
+export declare function hasProviderAccess(context: ProcessingContext | undefined): context is ProcessingContext & {
+    getProvider(providerId: string): Promise<BaseProvider>;
+};
+export declare function hasProviderSupport(context: ProcessingContext | undefined, providerId: string, modelId: string): context is ProcessingContext & {
+    getProvider(providerId: string): Promise<BaseProvider>;
+};
+export declare function normalizeProviderStreamItem(item: ProviderStreamItem): ProviderStreamItem;
+/**
+ * Render a tool-call streaming item as a Chunk so callers see tool dispatches
+ * inline with the assistant's text/thinking stream. The structured payload
+ * lives in `content_metadata`; `content` is a human-readable summary.
+ */
+export declare function toolCallChunk(toolCall: ToolCall): Chunk;
+export declare function streamProviderMessages(provider: BaseProvider, args: Parameters<BaseProvider["generateMessages"]>[0]): AsyncGenerator<ProviderStreamItem>;
+/**
+ * Map a model's raw classification output to one of the allowed categories.
+ * Tries the parsed JSON `category` field (case-insensitive exact match) first,
+ * then a substring-containment scan of the raw text. Throws if neither matches
+ * — never invents an answer by defaulting to the first category.
+ */
+export declare function parseCategory(raw: string, categories: string[]): string;
+export declare function messageContentText(content: Message["content"] | unknown): string;
+export declare function normalizeRole(role: unknown): Message["role"] | null;
+export declare function normalizeBinaryRef(value: unknown): {
+    uri?: string;
+    data?: Uint8Array | string;
+    mimeType?: string;
+} | null;
+export declare function normalizeMessageContent(value: unknown): Message["content"];
+export declare function normalizeToolCalls(value: unknown): ToolCall[] | null;
+export declare function normalizeMessage(value: unknown): Message | null;
+/**
+ * Normalize a list-typed media input to an array. Accepts an array (the
+ * declared `list[image]`/`list[audio]` shape), a lone ref (defensive, in case
+ * coercion didn't run), or null/undefined.
+ */
+export declare function toRefArray(value: unknown): unknown[];
+export declare function buildUserMessage(prompt: string, images: unknown, audios: unknown): Message;
+/**
+ * A user message that keeps `content` a plain string unless a media ref is
+ * actually attached. The Summarizer/Extractor/Classifier nodes declare `image`
+ * and `audio` props; wiring them through {@link buildUserMessage} unconditionally
+ * would also turn every text-only request into a parts array and run the prompt
+ * through `expandAssetReferences`, changing what existing graphs send. This
+ * keeps the old string shape whenever no ref resolves.
+ */
+export declare function userMessageWithMedia(text: string, images: unknown, audios: unknown): Message;
+/**
+ * A single classified item from a provider's {@link BaseProvider.generateLoop}
+ * stream. Both {@link runAgentLoop} and the AgentNode's genProcess drive the
+ * same normalize → classify dance off generateLoop; keeping that classification
+ * in one place stops the two from drifting (they did once). Presentation and
+ * per-turn accumulation stay with each consumer — this only untangles the raw
+ * stream into typed events.
+ */
+export type ProviderStreamEvent = {
+    kind: "tool_call";
+    toolCall: ToolCall;
+} | {
+    kind: "thinking";
+    chunk: Chunk;
+} | {
+    kind: "audio";
+    chunk: Chunk;
+} | {
+    kind: "text";
+    chunk: Chunk;
+    delta: string;
+} | {
+    kind: "assistant_message";
+    message: Message;
+} | {
+    kind: "tool_message";
+    message: Message;
+}
+/**
+ * The loop ended for a reason other than the model ending its turn — a
+ * budget, the deadline, the iteration cap, or an abort. Dropping it would
+ * make a refused run read exactly like a finished one (invariant I-3), so
+ * every consumer sees it and decides what to do.
+ */
+ | {
+    kind: "stop";
+    stop: ProviderStop;
+};
+/**
+ * Normalize and classify a provider stream into {@link ProviderStreamEvent}s.
+ * Mirrors the branch structure both consumers previously inlined: tool-call
+ * announcements, thinking chunks, audio chunks, any other content chunk (as
+ * `text`, carrying the original chunk so a consumer can inspect content_type),
+ * finalized `{ type: "message" }` events split by role, and the loop's `stop`
+ * item. The `text` event's `delta` is the chunk's string content ("" for
+ * non-string payloads).
+ */
+export declare function classifyProviderStream(stream: AsyncIterable<ProviderStreamItem>): AsyncGenerator<ProviderStreamEvent>;
+/**
+ * Resolve selected tool names to executable tools.
+ *
+ * A tool the caller injected into the context wins over builtin hydration:
+ * only the caller can wire MCP, workspace, skill, and security-gated tools,
+ * and a builtin stub of the same name would be the weaker of the two.
+ */
+export declare function normalizeTools(value: unknown, context?: ProcessingContext): ToolLike[];
+/**
+ * Wrap an agent node's tools in the run's permission gate.
+ *
+ * One ladder covers every host (invariant I-1): the node's tools go through
+ * the same `decidePermission` a chat turn's belt does, with the gate the host
+ * put on the context. Approving `run_node` is then approval to run the node,
+ * not to run whatever the node decides to call — its tools used to resolve
+ * ungated, so every call inside it ran unasked.
+ *
+ * A name-stub that never hydrated is left alone: it has nothing to run, and
+ * the node's dispatch already answers for it by name.
+ */
+export declare function gateAgentTools(tools: ToolLike[], gate: PermissionGateOptions): ToolLike[];
+export declare function uniqueToolName(baseName: string, existingNames: string[]): string;
+export declare function toProviderTools(tools: ToolLike[]): Array<{
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+}>;
+/**
+ * A tool result rendered as JSON: every byte buffer has become a base64 string.
+ */
+export type SerializedToolResult = string | number | boolean | null | undefined | SerializedToolResult[] | {
+    [key: string]: SerializedToolResult;
+};
+export declare function serializeToolResult(value: unknown): SerializedToolResult;
+export declare function getStructuredOutputSchema(node: BaseNode): Record<string, unknown> | null;
+export declare function hasContentType(message: Message | undefined, type: MessageContent["type"]): boolean;
+//# sourceMappingURL=agent-utils.d.ts.map