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

package/dist/serpapi/normalize.js

@@ -0,0 +1,140 @@
+/**
+ * Turning one SerpAPI response into something a model can read, and one
+ * parameter bag into something SerpAPI will accept.
+ *
+ * Both directions exist for the same reason. A SerpAPI response is a whole
+ * results page — `google` alone answers with organic results, ads, knowledge
+ * graph, related questions, pagination, and inline images — and handing all of
+ * it back spends a model's context on the twelve keys it did not ask for. A
+ * parameter bag is the mirror image: a wrong key is not an error on SerpAPI's
+ * side, it is a silently ignored field and a result for a different query, so
+ * it has to be caught here against the engine's catalogued contract.
+ */
+import { HOST_OWNED_PARAMS } from "./client.js";
+/** Keys that describe the request rather than its results. */
+const METADATA_KEYS = new Set([
+    "search_metadata",
+    "search_parameters",
+    "search_information",
+    "serpapi_pagination",
+    "pagination"
+]);
+/** How many items of each result array are returned when nothing says. */
+export const DEFAULT_MAX_ITEMS = 10;
+/** The ceiling on `max_items`, whatever a caller asks for. */
+export const MAX_ITEMS_LIMIT = 100;
+/**
+ * Trim one response to the keys asked for and the items allowed.
+ *
+ * Nothing is dropped silently: a key that was left out is named in `omitted`
+ * and an array that was cut is counted in `truncated`, so a model can ask for
+ * the rest by name instead of guessing that there was more.
+ */
+export function summarizeSearch(body, options = {}) {
+    const maxItems = clampItems(options.maxItems);
+    const wanted = options.fields === undefined || options.fields.length === 0
+        ? undefined
+        : new Set(options.fields);
+    const metadata = {};
+    const results = {};
+    const omitted = [];
+    const truncated = {};
+    for (const [key, value] of Object.entries(body)) {
+        if (METADATA_KEYS.has(key)) {
+            metadata[key] = value;
+            continue;
+        }
+        if (wanted !== undefined && !wanted.has(key)) {
+            omitted.push(key);
+            continue;
+        }
+        if (Array.isArray(value) && value.length > maxItems) {
+            results[key] = value.slice(0, maxItems);
+            truncated[key] = value.length - maxItems;
+            continue;
+        }
+        results[key] = value;
+    }
+    return { metadata, results, omitted, truncated };
+}
+function clampItems(requested) {
+    if (requested === undefined || !Number.isFinite(requested)) {
+        return DEFAULT_MAX_ITEMS;
+    }
+    return Math.min(Math.max(1, Math.floor(requested)), MAX_ITEMS_LIMIT);
+}
+/** The result keys a response carries, for a caller choosing `fields`. */
+export function resultKeys(body) {
+    return Object.keys(body).filter((key) => !METADATA_KEYS.has(key));
+}
+/**
+ * Check a parameter bag against one engine's catalogued contract.
+ *
+ * Unknown keys are errors rather than warnings on purpose: SerpAPI ignores
+ * them, so the run succeeds, bills a search, and answers a question nobody
+ * asked. Naming the near-misses is what turns that into a fixable message.
+ */
+export function checkParams(engine, raw) {
+    const known = new Map(engine.parameters.map((p) => [p.name, p]));
+    const params = {};
+    const errors = [];
+    for (const [name, value] of Object.entries(raw)) {
+        if (HOST_OWNED_PARAMS.has(name)) {
+            errors.push(`"${name}" is set by NodeTool, not by the caller. Remove it.`);
+            continue;
+        }
+        if (name === "engine")
+            continue;
+        if (value === undefined || value === null)
+            continue;
+        const parameter = known.get(name);
+        if (parameter === undefined) {
+            const near = nearest(name, [...known.keys()]);
+            errors.push(`"${name}" is not a parameter of the ${engine.engine} engine.` +
+                (near === undefined ? "" : ` Did you mean "${near}"?`) +
+                " Read get_serpapi_engine_schema for the full list.");
+            continue;
+        }
+        const scalar = toScalar(value);
+        if (scalar === undefined) {
+            errors.push(`"${name}" must be a string, number, or boolean — got ${typeof value}.`);
+            continue;
+        }
+        const allowed = parameter.options;
+        if (allowed !== undefined && !allowed.some((o) => o.value === String(scalar))) {
+            errors.push(`"${name}" must be one of: ${allowed.map((o) => o.value).join(", ")}.`);
+            continue;
+        }
+        params[name] = scalar;
+    }
+    for (const parameter of engine.parameters) {
+        if (parameter.required && !Object.hasOwn(params, parameter.name)) {
+            errors.push(`"${parameter.name}" (${parameter.label}) is required by the ` +
+                `${engine.engine} engine.`);
+        }
+    }
+    return { params, errors };
+}
+function toScalar(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    return undefined;
+}
+/**
+ * The closest known name, when one is close enough to be worth suggesting.
+ *
+ * A prefix or substring relationship covers the mistakes that actually happen
+ * — `query` for `q`, `hl_code` for `hl`, `num_results` for `num` — without the
+ * cost of an edit-distance pass over 40 names on every rejected parameter.
+ */
+function nearest(name, candidates) {
+    const lower = name.toLowerCase();
+    return candidates.find((candidate) => candidate.length > 1 &&
+        (lower.includes(candidate.toLowerCase()) ||
+            candidate.toLowerCase().includes(lower)));
+}
+//# sourceMappingURL=normalize.js.map

package/dist/serpapi/normalize.js.map

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

package/dist/skill-prompt.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Rendering skills into a chat turn's prompt.
+ *
+ * Two tiers, the same shape the sandbox packs use. The **catalog** — one line
+ * per skill, name and description — is always in context, so the agent knows
+ * what exists without a tool call. The **body** costs a `load_skill` call, or
+ * arrives for free when the user typed `/<name>`: naming a skill is asking for
+ * it, so the turn should not spend a round trip re-fetching what was named.
+ *
+ * String in, string out — the host reads the rows and calls these.
+ */
+/** One skill as the catalog knows it. */
+export interface SkillCatalogEntry {
+    name: string;
+    description: string;
+}
+/** One skill in full. */
+export interface SkillInstructions extends SkillCatalogEntry {
+    content: string;
+}
+/** Skill names the text invokes with a leading slash, in order, deduped. */
+export declare function findInvokedSkillNames(text: string, available: readonly string[]): string[];
+/** The always-on catalog block: what exists, and how to read one in full. */
+export declare function formatSkillCatalogForPrompt(skills: readonly SkillCatalogEntry[]): string;
+/** The bodies of the skills this turn named, already loaded. */
+export declare function formatInvokedSkillsForPrompt(skills: readonly SkillInstructions[]): string;
+//# sourceMappingURL=skill-prompt.d.ts.map

package/dist/skill-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-prompt.d.ts","sourceRoot":"","sources":["../src/skill-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,yCAAyC;AACzC,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,yBAAyB;AACzB,MAAM,WAAW,iBAAkB,SAAQ,iBAAiB;IAC1D,OAAO,EAAE,MAAM,CAAC;CACjB;AAQD,4EAA4E;AAC5E,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,MAAM,EAAE,CAQV;AAED,6EAA6E;AAC7E,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,SAAS,iBAAiB,EAAE,GACnC,MAAM,CAeR;AAED,gEAAgE;AAChE,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,SAAS,iBAAiB,EAAE,GACnC,MAAM,CAYR"}

package/dist/skill-prompt.js

@@ -0,0 +1,61 @@
+/**
+ * Rendering skills into a chat turn's prompt.
+ *
+ * Two tiers, the same shape the sandbox packs use. The **catalog** — one line
+ * per skill, name and description — is always in context, so the agent knows
+ * what exists without a tool call. The **body** costs a `load_skill` call, or
+ * arrives for free when the user typed `/<name>`: naming a skill is asking for
+ * it, so the turn should not spend a round trip re-fetching what was named.
+ *
+ * String in, string out — the host reads the rows and calls these.
+ */
+/**
+ * A `/name` the user typed: at the start of the text or after whitespace, so a
+ * path (`src/utils`) and a closing `</tag>` are not skill invocations.
+ */
+const SLASH_COMMAND_RE = /(?:^|\s)\/([a-z0-9][a-z0-9-]{0,63})\b/g;
+/** Skill names the text invokes with a leading slash, in order, deduped. */
+export function findInvokedSkillNames(text, available) {
+    const known = new Set(available.map((name) => name.toLowerCase()));
+    const found = [];
+    for (const match of text.toLowerCase().matchAll(SLASH_COMMAND_RE)) {
+        const name = match[1];
+        if (known.has(name) && !found.includes(name))
+            found.push(name);
+    }
+    return found;
+}
+/** The always-on catalog block: what exists, and how to read one in full. */
+export function formatSkillCatalogForPrompt(skills) {
+    if (skills.length === 0)
+        return "";
+    const lines = [
+        "## Skills",
+        "",
+        "The user has these skills — saved instructions for a kind of work. The",
+        "description says when a skill applies; call `load_skill` with its name to",
+        "read the instructions before you act on it. A message that names one with",
+        "a leading slash (`/name`) is asking for that skill.",
+        ""
+    ];
+    for (const skill of skills) {
+        lines.push(`- \`/${skill.name}\` — ${skill.description}`);
+    }
+    return lines.join("\n");
+}
+/** The bodies of the skills this turn named, already loaded. */
+export function formatInvokedSkillsForPrompt(skills) {
+    if (skills.length === 0)
+        return "";
+    const lines = [
+        "## Skill instructions",
+        "",
+        "The user's message names these skills. Follow them for this turn.",
+        ""
+    ];
+    for (const skill of skills) {
+        lines.push(`### /${skill.name}`, "", skill.content.trim(), "");
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=skill-prompt.js.map

package/dist/skill-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-prompt.js","sourceRoot":"","sources":["../src/skill-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAaH;;;GAGG;AACH,MAAM,gBAAgB,GAAG,wCAAwC,CAAC;AAElE,4EAA4E;AAC5E,MAAM,UAAU,qBAAqB,CACnC,IAAY,EACZ,SAA4B;IAE5B,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IACnE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,2BAA2B,CACzC,MAAoC;IAEpC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,KAAK,GAAG;QACZ,WAAW;QACX,EAAE;QACF,wEAAwE;QACxE,2EAA2E;QAC3E,2EAA2E;QAC3E,qDAAqD;QACrD,EAAE;KACH,CAAC;IACF,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,IAAI,QAAQ,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,4BAA4B,CAC1C,MAAoC;IAEpC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACnC,MAAM,KAAK,GAAG;QACZ,uBAAuB;QACvB,EAAE;QACF,mEAAmE;QACnE,EAAE;KACH,CAAC;IACF,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/step-executor.d.ts

@@ -4,13 +4,14 @@
  * Port of src/nodetool/agents/step_executor.py
  *
  * Manages the LLM interaction loop: sending messages, handling tool calls,
- * monitoring token limits, and capturing the step result via finish_step
- * or inline JSON extraction.
+ * and capturing the step result via finish_step (for schema'd steps) or the
+ * assistant's text response (for unstructured steps).
  */
 import type { BaseProvider, ProcessingContext } from "@nodetool-ai/runtime";
+import type { TurnBudget } from "@nodetool-ai/runtime";
 import { type ProcessingMessage } from "@nodetool-ai/protocol";
 import type { Step, Task } from "./types.js";
-import type { Tool } from "./tools/base-tool.js";
+import { Tool } from "./tools/base-tool.js";
 export interface StepExecutorOptions {
     task: Task;
     step: Step;
@@ -19,11 +20,55 @@ export interface StepExecutorOptions {
     model: string;
     tools?: Tool[];
     systemPrompt?: string;
-    maxTokenLimit?: number;
     maxIterations?: number;
+    /**
+     * Cap on output tokens per provider turn. Forwarded to `generateLoop`;
+     * undefined lets the provider use its own default. Plan-mode Agent nodes
+     * thread the node's `max_tokens` here for parity with loop mode.
+     */
+    maxTokens?: number;
     useFinishTask?: boolean;
     threadId?: string;
+    /**
+     * Additional memory keys to surface in the user message as required
+     * upstream context for this step. Typically `task:<id>` keys derived from
+     * the parent task's `dependsOn` (set by ParallelTaskExecutor / TaskExecutor).
+     *
+     * The step's own `step.dependsOn` IDs are added automatically as
+     * `step:<id>` keys — callers should not duplicate them here.
+     */
+    upstreamMemoryKeys?: string[];
+    /** External cancellation. Aborts the provider loop mid-flight. */
+    signal?: AbortSignal;
+    /**
+     * Final say on a schema-valid result, for contracts whose acceptance can
+     * only be decided asynchronously — a repaired value that must resolve
+     * against run storage, say. A rejection is not a failure: it returns to the
+     * model as a tool error inside the still-open conversation, so the next
+     * attempt has the reason. After {@link MAX_REPAIR_ROUNDS} rejections the
+     * step fails rather than looping on an answer the model cannot produce.
+     */
+    acceptResult?: (result: unknown) => Promise<StepResultAcceptance>;
+    /**
+     * Spend admission consulted before every provider turn. Forwarded to
+     * `generateLoop`; a refusal ends the loop, which surfaces here as a step
+     * that never completed.
+     */
+    turnBudget?: TurnBudget;
 }
+/** Answer from {@link StepExecutorOptions.acceptResult}. */
+export type StepResultAcceptance = {
+    accepted: true;
+} | {
+    accepted: false;
+    reason: string;
+};
+/**
+ * Rejections by the acceptance callback before the step gives up. Three is
+ * enough for the model to read the reason and correct course; more is a model
+ * that cannot satisfy the contract, and looping costs real money.
+ */
+export declare const MAX_REPAIR_ROUNDS = 3;
 export declare class StepExecutor {
     private history;
     private step;
@@ -33,33 +78,37 @@ export declare class StepExecutor {
     private model;
     private context;
     private systemPrompt;
-    private maxTokenLimit;
     private maxIterations;
+    private maxTokens?;
     private useFinishTask;
-    private inConclusionStage;
+    private signal?;
     private result;
     private finishStepTool;
     private resultSchema;
+    /** The schema as the caller wrote it — what host validation checks. */
+    private declaredSchema;
     private iterations;
-    private jsonParseFailures;
     private generationFailures;
-    private sources;
-    private sourcesSet;
-    private inputTokensTotal;
-    private outputTokensTotal;
-    private _controlEvents;
     private threadId?;
+    private upstreamMemoryKeys;
+    private acceptResult?;
+    private turnBudget?;
+    private repairRounds;
+    /** Set when acceptance rejected the result once too often. */
+    private acceptanceError;
     constructor(opts: StepExecutorOptions);
-    /**
-     * Rough token estimate based on JSON serialized history length / 4.
-     */
-    private estimateTokens;
     /**
      * Parse and sanitize the declared output schema for this step.
      */
     private loadResultSchema;
     /**
      * Build the system prompt for this step using templates.
+     *
+     * The default execution prompts encode the contract every step relies on
+     * (output discipline, finish_step protocol). They must always be present.
+     * A caller-supplied `userPrompt` is added as a preamble — never as a
+     * replacement — so domain context can be layered in without losing the
+     * execution discipline.
      */
     private buildSystemPrompt;
     /**
@@ -69,6 +118,11 @@ export declare class StepExecutor {
     private validateResultPayload;
     /**
      * Persist the final result and mark the step as completed.
+     *
+     * Writes a `step_result` entry to {@link ProcessingContext.memory} under
+     * `step:<id>`. For finish-task steps it additionally writes the same value
+     * as a `task_result` under `task:<id>` so downstream tasks can discover it
+     * via memory.
      */
     private storeCompletionResult;
     /**
@@ -76,58 +130,36 @@ export declare class StepExecutor {
      */
     private appendCompletionFeedback;
     /**
-     * Attempt to parse and store a completion payload from the assistant message.
+     * For unstructured steps (no schema), accept the assistant's text content
+     * as the result when the model produces a final response without tool
+     * calls. Schema'd steps finalize exclusively through `finish_step`.
      */
     private maybeFinalizeFromMessage;
-    /**
-     * Track JSON parsing/validation failures and enforce a hard stop.
-     */
-    private registerJsonFailure;
-    /**
-     * Filter tool calls based on whether we're in the conclusion stage.
-     */
-    private filterToolCallsForCurrentStage;
-    /**
-     * Get the tools available for the current stage.
-     */
-    private getCurrentTools;
-    /**
-     * Transition to conclusion stage: restrict tools to finish_step only.
-     */
-    private enterConclusionStage;
-    /**
-     * Summarize older messages into a concise, factual summary.
-     */
-    private summarizeMessages;
-    /**
-     * Trim or summarize older messages to stay within token limits.
-     */
-    private trimHistoryIfNeeded;
     /**
      * Serialize a tool result for history, with truncation.
      */
     private serializeToolResultForHistory;
     /**
-     * Save base64 encoded binary data (images, audio) from tool results to workspace files.
-     * Mirrors Python's StepExecutor._handle_binary_artifact().
-     */
-    private handleBinaryArtifact;
-    /**
-     * Persist important sandbox outputs (downloads, screenshots, generated artifacts)
-     * as assets so they survive ephemeral workspace/container cleanup.
-     */
-    private capturePersistentSandboxOutputs;
-    /**
-     * Track URLs from browser tool navigation results.
-     * Mirrors Python's _process_special_tool_side_effects().
-     */
-    private trackToolSideEffects;
-    /**
-     * Generate a user-facing message for a tool call.
+     * Generate a user-facing message for a tool call. Prefers the LLM-authored
+     * `_message` arg; falls back to the tool's parameter-aware template.
      */
     private generateToolCallMessage;
     /**
-     * Build the initial user message with instructions and dependency results.
+     * Build the initial user message.
+     *
+     * Memory contents are NOT auto-included — callers fetch on demand via the
+     * `list_shared` / `read_shared` tools (progressive disclosure; tool usage
+     * is documented in the default system prompt).
+     *
+     * The only memory information the user message carries is a short list of
+     * **specific** upstream keys the planner declared as relevant to this step:
+     *
+     *   - `step:<id>` for every entry of `step.dependsOn` (intra-task deps).
+     *   - any caller-supplied {@link StepExecutorOptions.upstreamMemoryKeys}
+     *     (typically `task:<id>` entries from the parent task's `dependsOn`).
+     *
+     * Only keys that actually exist in `context.memory` are listed. The LLM
+     * is expected to call `read_shared` with whichever subset it needs.
      */
     private buildUserMessage;
     /**
@@ -139,24 +171,5 @@ export declare class StepExecutor {
      * Get the captured result after execution completes.
      */
     getResult(): unknown;
-    /**
-     * Get tracked sources (e.g. browser URLs).
-     */
-    getSources(): string[];
-    /**
-     * Get token usage statistics.
-     */
-    getTokenUsage(): {
-        inputTokensTotal: number;
-        outputTokensTotal: number;
-    };
-    /**
-     * Get control events emitted during execution (from ControlNodeTool calls).
-     * The caller (workflow actor/runner) is responsible for dispatching these.
-     */
-    getControlEvents(): Array<{
-        targetNodeId: string;
-        event: import("@nodetool-ai/protocol").ControlEvent;
-    }>;
 }
 //# sourceMappingURL=step-executor.d.ts.map

package/dist/step-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"step-executor.d.ts","sourceRoot":"","sources":["../src/step-executor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"step-executor.d.ts","sourceRoot":"","sources":["../src/step-executor.ts"],"names":[],"mappings":"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"}