@nodetool-ai/agents 0.7.0-rc.11

package/dist/step-executor.js

@@ -0,0 +1,1114 @@
+/**
+ * StepExecutor -- the core execution engine for a single step.
+ *
+ * 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.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { withAgentSpanGen } from "@nodetool-ai/runtime";
+import { createLogger } from "@nodetool-ai/config";
+import { TaskUpdateEvent } from "@nodetool-ai/protocol";
+import { ControlNodeTool } from "./tools/control-tool.js";
+import { FinishStepTool } from "./tools/finish-step-tool.js";
+import { extractJSON } from "./utils/json-parser.js";
+import { DEFAULT_TOKEN_LIMIT, MAX_TOOL_RESULT_CHARS } from "./constants.js";
+import { rejectAgenticProvider } from "./reject-agentic-provider.js";
+const log = createLogger("nodetool.agents.step-executor");
+const DEFAULT_MAX_ITERATIONS = 30;
+const JSON_FAILURE_ALERT_THRESHOLD = 3;
+const MAX_JSON_PARSE_FAILURES = 6;
+// ---------------------------------------------------------------------------
+// Shared prompt fragments (DRY)
+// ---------------------------------------------------------------------------
+const PROMPT_NO_HUMAN_FEEDBACK = `# Hard Constraint: No Human Feedback
+- Do NOT ask clarifying questions or request user input.
+- If something is ambiguous or missing, choose the simplest reasonable assumption, record it in your reasoning, and proceed.`;
+const PROMPT_SCHEMA_STRICT = `# Output Discipline
+- Never invent fields: the final result must match the schema exactly (no extra keys; include all required keys).
+- Do not reveal chain-of-thought or internal reasoning traces in assistant text.
+- Keep non-tool messages concise and factual.`;
+const PROMPT_OUTPUT_SCHEMA = `# Output Schema
+The final result must match this JSON schema exactly:
+\`\`\`json
+{{ output_schema_json }}
+\`\`\``;
+const PROMPT_TOOL_USE = `# Tool Use
+- Use tools only when they materially improve correctness or are required.
+- Avoid exploratory or repeated tool calls that are unlikely to change the outcome.
+- Before each tool call, emit a one-sentence rationale describing what you're doing and why.
+
+## File Tools
+- Use \`read_file\` to read files. Do not use \`run_code\` with cat/head/tail.
+- Use \`edit_file\` for modifying existing files — it performs exact string replacement and only sends the diff. Prefer it over \`write_file\` for modifications.
+- Use \`write_file\` only for creating new files or complete rewrites.
+- Use \`glob\` to find files by name pattern (e.g. "**/*.ts"). Do not use \`run_code\` with find or ls.
+- Use \`grep\` to search file contents with regex. Do not use \`run_code\` with grep or rg.
+- Use \`run_code\` with language="bash" only for system commands and operations that require shell execution.
+
+## Web Tools
+- Use \`browser\` to fetch and read the content of a web page. It returns cleaned, readable text extracted from HTML. This is the right choice for reading articles, documentation, or any page content.
+- Use \`http_request\` for API calls, POST/PUT/PATCH requests, or when you need raw response headers and body. Do not use it for reading page content — use \`browser\` instead.
+- Use \`download_file\` to save a file (binary or text) from a URL to disk.`;
+const PROMPT_FINISH_STEP = `# Completion (Tool Call Only)
+- When done, CALL \`finish_step\` exactly once with:
+  {"result": <result>}
+- Do NOT output the final result in assistant text — only use the tool.
+- Stop immediately after calling \`finish_step\`.`;
+// ---------------------------------------------------------------------------
+// Assembled system prompts
+// ---------------------------------------------------------------------------
+const DEFAULT_EXECUTION_SYSTEM_PROMPT = `# Role
+You are executing EXACTLY one step within a larger plan. Complete this step end-to-end without asking for clarification.
+
+# Objective
+{{ step_content }}
+
+${PROMPT_NO_HUMAN_FEEDBACK}
+
+# Scope & Discipline
+- Do ONLY what is required to satisfy this step objective; avoid tangents and extra work.
+- Use upstream step results already present in context; do not ask for them again.
+${PROMPT_SCHEMA_STRICT}
+
+${PROMPT_OUTPUT_SCHEMA}
+
+${PROMPT_TOOL_USE}
+
+${PROMPT_FINISH_STEP}`;
+const DEFAULT_FINISH_TASK_SYSTEM_PROMPT = `# Role
+You are completing the final aggregation task, synthesizing results from prior steps into a single coherent deliverable.
+
+${PROMPT_NO_HUMAN_FEEDBACK}
+
+# Scope & Discipline
+- Focus on synthesis and aggregation only. Do NOT do additional research or data gathering.
+- Preserve every concrete artifact from upstream results (image URLs, file paths, tables, key facts) — never drop or paraphrase them away.
+- Use upstream step results already present in context; do not ask for them again.
+${PROMPT_SCHEMA_STRICT}
+
+${PROMPT_OUTPUT_SCHEMA}
+
+${PROMPT_TOOL_USE}
+
+${PROMPT_FINISH_STEP}`;
+const DEFAULT_UNSTRUCTURED_SYSTEM_PROMPT = `# Role
+You are executing a task. Your job is to complete it end-to-end without asking for clarification.
+
+# Objective
+{{ step_content }}
+
+${PROMPT_NO_HUMAN_FEEDBACK}
+
+# Operating Mode
+- Use tools as needed to achieve the objective.
+- When you have the final answer or have completed the task, provide the result as your final response.
+- Do not reveal chain-of-thought or internal reasoning traces.
+
+# Communication Pattern (Tool Preambles)
+Before making tool calls, provide clear progress updates:
+1. First assistant message: Restate the objective in one sentence, then list a short numbered plan (1-3 steps).
+2. Before each tool call: Emit a one-sentence message describing what you're doing and why.
+3. After tool results: Provide a brief update only if the result changes your plan.
+
+${PROMPT_TOOL_USE}`;
+// ---------------------------------------------------------------------------
+// Schema validation helpers
+// ---------------------------------------------------------------------------
+function validateAndSanitizeSchema(schema, defaultDescription = "Result object") {
+    if (schema === null || schema === undefined) {
+        throw new Error("Schema is null or undefined");
+    }
+    let parsed = schema;
+    if (typeof parsed === "string") {
+        parsed = JSON.parse(parsed);
+    }
+    if (typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`Schema is not an object (type: ${typeof parsed})`);
+    }
+    // Deep copy
+    const result = JSON.parse(JSON.stringify(parsed));
+    if (!("type" in result)) {
+        result["type"] = "object";
+    }
+    if (!("description" in result)) {
+        result["description"] = defaultDescription;
+    }
+    const disallowedExtensionKeys = new Set([
+        "oneOf",
+        "anyOf",
+        "allOf",
+        "not",
+        "if",
+        "then",
+        "else",
+        "patternProperties"
+    ]);
+    function shouldDefaultAdditionalProperties(obj) {
+        if ("additionalProperties" in obj)
+            return false;
+        if (Object.keys(obj).some((k) => disallowedExtensionKeys.has(k)))
+            return false;
+        const schemaType = obj["type"];
+        if (Array.isArray(schemaType)) {
+            if (schemaType.length !== 1 || schemaType[0] !== "object")
+                return false;
+        }
+        else if (schemaType !== undefined && schemaType !== "object") {
+            return false;
+        }
+        return (schemaType === "object" ||
+            (schemaType === undefined && obj["properties"] !== undefined));
+    }
+    function cleanSchemaRecursive(obj) {
+        if (Array.isArray(obj)) {
+            return obj.map(cleanSchemaRecursive);
+        }
+        if (obj !== null && typeof obj === "object") {
+            const cleaned = {};
+            for (const [key, value] of Object.entries(obj)) {
+                cleaned[key] = cleanSchemaRecursive(value);
+            }
+            if (shouldDefaultAdditionalProperties(cleaned)) {
+                cleaned["additionalProperties"] = false;
+            }
+            return cleaned;
+        }
+        return obj;
+    }
+    return cleanSchemaRecursive(result);
+}
+// ---------------------------------------------------------------------------
+// Think-tag removal
+// ---------------------------------------------------------------------------
+function removeThinkTags(text) {
+    if (!text)
+        return "";
+    return text
+        .replace(/<think>[\s\S]*?<\/(?:redacted_thinking|think)>/g, "")
+        .replace(/<think>[\s\S]*/g, "")
+        .trim();
+}
+// ---------------------------------------------------------------------------
+// Tool result normalization
+// ---------------------------------------------------------------------------
+function normalizeToolResult(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean")
+        return value;
+    if (Array.isArray(value))
+        return value.map(normalizeToolResult);
+    if (typeof value === "object") {
+        const obj = value;
+        if (typeof obj["toJSON"] === "function") {
+            return normalizeToolResult(obj.toJSON());
+        }
+        const result = {};
+        for (const [k, v] of Object.entries(obj)) {
+            result[k] = normalizeToolResult(v);
+        }
+        return result;
+    }
+    return String(value);
+}
+// ---------------------------------------------------------------------------
+// Simple template rendering (replaces Jinja2)
+// ---------------------------------------------------------------------------
+function renderTemplate(template, context) {
+    let result = template;
+    for (const [key, value] of Object.entries(context)) {
+        result = result.replaceAll(`{{ ${key} }}`, value);
+        result = result.replaceAll(`{{${key}}}`, value);
+    }
+    return result;
+}
+export class StepExecutor {
+    history = [];
+    step;
+    task;
+    tools;
+    provider;
+    model;
+    context;
+    systemPrompt;
+    maxTokenLimit;
+    maxIterations;
+    useFinishTask;
+    inConclusionStage = false;
+    result = null;
+    finishStepTool = null;
+    resultSchema = null;
+    iterations = 0;
+    jsonParseFailures = 0;
+    generationFailures = 0;
+    sources = [];
+    sourcesSet = new Set();
+    inputTokensTotal = 0;
+    outputTokensTotal = 0;
+    _controlEvents = [];
+    threadId;
+    constructor(opts) {
+        this.task = opts.task;
+        this.step = opts.step;
+        this.context = opts.context;
+        this.provider = opts.provider;
+        this.model = opts.model;
+        this.tools = opts.tools ? [...opts.tools] : [];
+        this.maxTokenLimit = opts.maxTokenLimit ?? DEFAULT_TOKEN_LIMIT;
+        this.maxIterations = opts.maxIterations ?? DEFAULT_MAX_ITERATIONS;
+        this.useFinishTask = opts.useFinishTask ?? false;
+        this.threadId = opts.threadId;
+        // Load and sanitize the output schema
+        this.resultSchema = this.loadResultSchema();
+        // Setup finish_step tool if we have a schema
+        if (this.resultSchema) {
+            this.finishStepTool = new FinishStepTool(this.resultSchema);
+            this.tools.push(this.finishStepTool);
+        }
+        // Build the system prompt from templates
+        this.systemPrompt = this.buildSystemPrompt(opts.systemPrompt);
+    }
+    /**
+     * Rough token estimate based on JSON serialized history length / 4.
+     */
+    estimateTokens() {
+        return Math.ceil(JSON.stringify(this.history).length / 4);
+    }
+    /**
+     * Parse and sanitize the declared output schema for this step.
+     */
+    loadResultSchema() {
+        if (!this.step.outputSchema)
+            return null;
+        const defaultDescription = this.useFinishTask
+            ? "The task result"
+            : "The step result";
+        try {
+            const raw = typeof this.step.outputSchema === "string"
+                ? JSON.parse(this.step.outputSchema)
+                : this.step.outputSchema;
+            return validateAndSanitizeSchema(raw, defaultDescription);
+        }
+        catch {
+            // Fallback: permissive object schema
+            return { type: "object", description: defaultDescription };
+        }
+    }
+    /**
+     * Build the system prompt for this step using templates.
+     */
+    buildSystemPrompt(customPrompt) {
+        let basePrompt;
+        const templateContext = {};
+        if (this.resultSchema) {
+            const schemaJson = JSON.stringify(this.resultSchema, null, 2);
+            templateContext["output_schema_json"] = schemaJson;
+            if (this.useFinishTask) {
+                basePrompt = customPrompt ?? DEFAULT_FINISH_TASK_SYSTEM_PROMPT;
+                templateContext["step_content"] = this.step.instructions;
+            }
+            else {
+                basePrompt = customPrompt ?? DEFAULT_EXECUTION_SYSTEM_PROMPT;
+                templateContext["step_content"] = this.step.instructions;
+            }
+        }
+        else {
+            basePrompt = customPrompt ?? DEFAULT_UNSTRUCTURED_SYSTEM_PROMPT;
+            templateContext["step_content"] = this.step.instructions;
+        }
+        let prompt = renderTemplate(basePrompt, templateContext);
+        prompt += `\n\nToday's date is ${new Date().toISOString().slice(0, 10)}`;
+        return prompt;
+    }
+    /**
+     * Validate a result payload against the declared schema.
+     * Returns [isValid, errorDetail, normalizedResult].
+     */
+    validateResultPayload(resultPayload) {
+        const normalized = normalizeToolResult(resultPayload);
+        if (this.resultSchema === null) {
+            return [true, null, normalized];
+        }
+        // Basic structural validation: check required keys from schema
+        if (this.resultSchema["type"] === "object" &&
+            typeof normalized === "object" &&
+            normalized !== null) {
+            const requiredKeys = this.resultSchema["required"];
+            if (Array.isArray(requiredKeys)) {
+                const obj = normalized;
+                for (const key of requiredKeys) {
+                    if (!(key in obj)) {
+                        return [false, `Missing required key: ${key}`, normalized];
+                    }
+                }
+            }
+        }
+        // Type check
+        const expectedType = this.resultSchema["type"];
+        if (expectedType === "string" && typeof normalized !== "string") {
+            return [false, `Expected string, got ${typeof normalized}`, normalized];
+        }
+        if (expectedType === "object" &&
+            (typeof normalized !== "object" || normalized === null)) {
+            return [false, `Expected object, got ${typeof normalized}`, normalized];
+        }
+        if (expectedType === "array" && !Array.isArray(normalized)) {
+            return [false, `Expected array, got ${typeof normalized}`, normalized];
+        }
+        return [true, null, normalized];
+    }
+    /**
+     * Persist the final result and mark the step as completed.
+     */
+    async storeCompletionResult(normalizedResult) {
+        this.step.completed = true;
+        this.step.endTime = Date.now();
+        await this.context.storeStepResult(this.step.id, normalizedResult);
+        if (this.useFinishTask) {
+            await this.context.storeStepResult(this.task.id, normalizedResult);
+        }
+        this.result = normalizedResult;
+    }
+    /**
+     * Append a system message instructing the LLM to complete via finish_step.
+     */
+    appendCompletionFeedback(detail, submittedResult) {
+        const schemaStr = JSON.stringify(this.resultSchema, null, 2);
+        const lines = [
+            "SYSTEM: Step completion must be signaled via the `finish_step` tool.",
+            `Detail: ${detail}`,
+            "Call `finish_step` exactly once with:",
+            '{"result": <result>}',
+            "Schema for `result`:",
+            schemaStr
+        ];
+        if (submittedResult !== undefined) {
+            try {
+                const preview = JSON.stringify(normalizeToolResult(submittedResult), null, 2);
+                lines.push("Previous submission preview:", preview);
+            }
+            catch {
+                lines.push("Previous submission preview:", String(submittedResult));
+            }
+        }
+        this.history.push({ role: "system", content: lines.join("\n") });
+    }
+    /**
+     * Attempt to parse and store a completion payload from the assistant message.
+     */
+    maybeFinalizeFromMessage(message) {
+        if (!message)
+            return [false, null];
+        // For unstructured steps (no schema), accept text content as the result
+        if (this.resultSchema === null) {
+            if (!message.toolCalls || message.toolCalls.length === 0) {
+                return [true, message.content];
+            }
+            return [false, null];
+        }
+        if (!message.content || typeof message.content !== "string")
+            return [false, null];
+        const parsed = extractJSON(message.content);
+        if (!parsed || typeof parsed !== "object")
+            return [false, null];
+        const obj = parsed;
+        const status = obj["status"];
+        if (status !== undefined && status !== "completed")
+            return [false, null];
+        if (status === "completed" && !("result" in obj)) {
+            this.history.push({
+                role: "system",
+                content: 'Missing \'result\' in completion payload. Provide: {"status": "completed", "result": <your_result>}.'
+            });
+            return [false, null];
+        }
+        const candidateResult = "result" in obj ? obj["result"] : parsed;
+        const [isValid, errorDetail, normalizedResult] = this.validateResultPayload(candidateResult);
+        if (!isValid ||
+            normalizedResult === null ||
+            normalizedResult === undefined) {
+            this.history.push({
+                role: "system",
+                content: `Schema validation failed: ${errorDetail ?? "unknown error"}`
+            });
+            return [false, null];
+        }
+        return [true, normalizedResult];
+    }
+    /**
+     * Track JSON parsing/validation failures and enforce a hard stop.
+     */
+    registerJsonFailure(detail) {
+        this.jsonParseFailures++;
+        if (this.jsonParseFailures === JSON_FAILURE_ALERT_THRESHOLD) {
+            const reminder = "SYSTEM: Do NOT output completion JSON in assistant text. You MUST call " +
+                "`finish_step` with {'result': <result>} matching the schema, with no extra keys.";
+            this.history.push({ role: "system", content: reminder });
+            this.inConclusionStage = true;
+        }
+        if (this.jsonParseFailures >= MAX_JSON_PARSE_FAILURES) {
+            throw new Error(`Exceeded maximum JSON parse attempts (${MAX_JSON_PARSE_FAILURES}) for step ${this.step.id}. Last failure: ${detail}`);
+        }
+    }
+    /**
+     * Filter tool calls based on whether we're in the conclusion stage.
+     */
+    filterToolCallsForCurrentStage(toolCalls) {
+        if (!this.inConclusionStage)
+            return toolCalls;
+        return toolCalls.filter((tc) => tc.name === "finish_step");
+    }
+    /**
+     * Get the tools available for the current stage.
+     */
+    getCurrentTools() {
+        if (this.inConclusionStage) {
+            return this.finishStepTool ? [this.finishStepTool] : [];
+        }
+        return [...this.tools];
+    }
+    /**
+     * Transition to conclusion stage: restrict tools to finish_step only.
+     */
+    enterConclusionStage() {
+        if (this.inConclusionStage)
+            return;
+        this.inConclusionStage = true;
+        const hasFinishTool = !!this.finishStepTool;
+        const message = hasFinishTool
+            ? `SYSTEM: The conversation history is approaching the token limit (${this.maxTokenLimit} tokens).\n` +
+                "ENTERING CONCLUSION STAGE: You MUST now synthesize all gathered information and finalize the step.\n" +
+                "Only the `finish_step` tool is available. Call `finish_step` exactly once with:\n" +
+                '{"result": <result>} where <result> matches the declared schema.'
+            : `SYSTEM: The conversation history is approaching the token limit (${this.maxTokenLimit} tokens).\n` +
+                "ENTERING CONCLUSION STAGE: You MUST now synthesize all gathered information and finalize the step.\n" +
+                "Tools are not available. Provide the final answer concisely.";
+        // Prevent duplicate conclusion messages
+        if (!this.history.some((m) => m.role === "system" &&
+            typeof m.content === "string" &&
+            m.content.includes("ENTERING CONCLUSION STAGE"))) {
+            this.history.push({ role: "system", content: message });
+        }
+    }
+    /**
+     * Summarize older messages into a concise, factual summary.
+     */
+    async summarizeMessages(messages) {
+        const joined = messages
+            .filter((m) => m.content)
+            .map((m) => `${(m.role ?? "").toUpperCase()}: ${m.content}`)
+            .join("\n");
+        const prompt = "Summarize the following conversation concisely while preserving key facts, " +
+            "decisions, and results:\n\n" +
+            joined;
+        try {
+            const msg = await this.provider.generateMessageTraced({
+                messages: [
+                    { role: "system", content: "Summarize previous context." },
+                    { role: "user", content: prompt }
+                ],
+                model: this.model,
+                tools: [],
+                maxTokens: 512
+            });
+            return String(msg.content ?? "").trim();
+        }
+        catch {
+            return "Summary unavailable due to compression error.";
+        }
+    }
+    /**
+     * Trim or summarize older messages to stay within token limits.
+     */
+    async trimHistoryIfNeeded() {
+        const tokenCount = this.estimateTokens();
+        if (tokenCount < this.maxTokenLimit * 0.9)
+            return;
+        // Preserve the last 6 messages
+        const preserved = [];
+        for (let i = this.history.length - 1; i >= 0 && preserved.length < 6; i--) {
+            preserved.unshift(this.history[i]);
+        }
+        const earlierCount = this.history.length - preserved.length;
+        const earlierContext = earlierCount > 1 ? this.history.slice(1, earlierCount) : [];
+        if (earlierContext.length > 0) {
+            const summary = await this.summarizeMessages(earlierContext);
+            const systemPrompt = this.history[0];
+            this.history = [];
+            if (systemPrompt) {
+                this.history.push(systemPrompt);
+            }
+            this.history.push({
+                role: "system",
+                content: `Summary of previous context:\n${summary}`
+            });
+        }
+        else {
+            this.history = this.history.slice(0, 1);
+        }
+        this.history.push(...preserved);
+        // Trim further if still over budget
+        let currentTokens = this.estimateTokens();
+        while (currentTokens > this.maxTokenLimit * 0.85 &&
+            this.history.length > 2) {
+            this.history.splice(2, 1);
+            currentTokens = this.estimateTokens();
+        }
+    }
+    /**
+     * Serialize a tool result for history, with truncation.
+     */
+    serializeToolResultForHistory(toolResult, _toolName) {
+        if (toolResult === null || toolResult === undefined) {
+            return "Tool returned no output.";
+        }
+        try {
+            const normalized = normalizeToolResult(toolResult);
+            const serialized = JSON.stringify(normalized);
+            if (serialized.length > MAX_TOOL_RESULT_CHARS) {
+                return (serialized.slice(0, MAX_TOOL_RESULT_CHARS) +
+                    "... [truncated to maintain context size]");
+            }
+            return serialized;
+        }
+        catch (e) {
+            return JSON.stringify({
+                error: `Failed to serialize tool result: ${e}`,
+                result_repr: String(toolResult).slice(0, 500)
+            });
+        }
+    }
+    /**
+     * Save base64 encoded binary data (images, audio) from tool results to workspace files.
+     * Mirrors Python's StepExecutor._handle_binary_artifact().
+     */
+    async handleBinaryArtifact(toolResult) {
+        if (typeof toolResult !== "object" ||
+            toolResult === null ||
+            Array.isArray(toolResult)) {
+            return toolResult;
+        }
+        const result = { ...toolResult };
+        const workspaceDir = this.context.workspaceDir;
+        if (!workspaceDir)
+            return result;
+        for (const field of ["image", "audio"]) {
+            const value = result[field];
+            if (typeof value !== "string")
+                continue;
+            const dataUriMatch = value.match(/^data:([^;]+);base64,(.+)$/s);
+            if (!dataUriMatch)
+                continue;
+            const [, mimeType, base64Data] = dataUriMatch;
+            const ext = mimeType.split("/")[1] ?? "bin";
+            const hash = createHash("sha256")
+                .update(base64Data)
+                .digest("hex")
+                .slice(0, 16);
+            const filename = `artifact_${hash}.${ext}`;
+            const artifactsDir = path.join(workspaceDir, "artifacts");
+            await fs.mkdir(artifactsDir, { recursive: true });
+            const filepath = path.join(artifactsDir, filename);
+            await fs.writeFile(filepath, Buffer.from(base64Data, "base64"));
+            result[field] = filepath;
+            if (!this.sourcesSet.has(filepath)) {
+                this.sources.push(filepath);
+                this.sourcesSet.add(filepath);
+            }
+        }
+        return result;
+    }
+    /**
+     * Persist important sandbox outputs (downloads, screenshots, generated artifacts)
+     * as assets so they survive ephemeral workspace/container cleanup.
+     */
+    async capturePersistentSandboxOutputs(toolName, toolArgs, toolResult) {
+        if (typeof toolResult !== "object" ||
+            toolResult === null ||
+            Array.isArray(toolResult)) {
+            return toolResult;
+        }
+        const result = { ...toolResult };
+        if (result.success === false) {
+            return result;
+        }
+        const candidates = [];
+        const candidateKeys = new Set();
+        const isExternalUri = (value) => {
+            const lower = value.toLowerCase();
+            return (lower.startsWith("http://") ||
+                lower.startsWith("https://") ||
+                lower.startsWith("asset://") ||
+                lower.startsWith("memory://") ||
+                lower.startsWith("s3://") ||
+                lower.startsWith("file://"));
+        };
+        const maybeAdd = (label, value) => {
+            if (typeof value === "string" &&
+                value.trim().length > 0 &&
+                !value.startsWith("data:") &&
+                !isExternalUri(value)) {
+                const key = `${label}:${value}`;
+                if (!candidateKeys.has(key)) {
+                    candidates.push({ label, path: value });
+                    candidateKeys.add(key);
+                }
+            }
+        };
+        maybeAdd("output_file", result.output_file);
+        if (result.success === true) {
+            maybeAdd("output_file", toolArgs?.["output_file"]);
+        }
+        maybeAdd("image", result.image);
+        maybeAdd("audio", result.audio);
+        if (candidates.length === 0) {
+            return result;
+        }
+        const refs = {};
+        for (const candidate of candidates) {
+            try {
+                const ref = await this.context.sandboxToAsset(candidate.path);
+                refs[candidate.label] = ref;
+                const uri = ref.uri;
+                if (typeof uri === "string" && uri && !this.sourcesSet.has(uri)) {
+                    this.sources.push(uri);
+                    this.sourcesSet.add(uri);
+                }
+            }
+            catch (error) {
+                log.warn("Failed to persist sandbox output as asset", {
+                    stepId: this.step.id,
+                    toolName,
+                    path: candidate.path,
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+        if (Object.keys(refs).length > 0) {
+            const existing = result.asset_refs;
+            if (typeof existing === "object" &&
+                existing !== null &&
+                !Array.isArray(existing)) {
+                result.asset_refs = { ...existing, ...refs };
+            }
+            else {
+                result.asset_refs = refs;
+            }
+        }
+        return result;
+    }
+    /**
+     * Track URLs from browser tool navigation results.
+     * Mirrors Python's _process_special_tool_side_effects().
+     */
+    trackToolSideEffects(toolName, result) {
+        if (toolName === "browser" &&
+            typeof result === "object" &&
+            result !== null) {
+            const url = result.url;
+            if (typeof url === "string" && url && !this.sourcesSet.has(url)) {
+                this.sources.push(url);
+                this.sourcesSet.add(url);
+            }
+        }
+    }
+    /**
+     * Generate a user-facing message for a tool call.
+     */
+    generateToolCallMessage(toolCall) {
+        for (const tool of this.tools) {
+            if (tool.name === toolCall.name) {
+                return tool.userMessage(toolCall.args);
+            }
+        }
+        return `Running ${toolCall.name}`;
+    }
+    /**
+     * Build the initial user message with instructions and dependency results.
+     */
+    async buildUserMessage() {
+        const parts = [this.step.instructions];
+        if (this.step.dependsOn.length > 0) {
+            for (const depId of this.step.dependsOn) {
+                const depResult = await this.context.loadStepResult(depId);
+                if (depResult !== undefined && depResult !== null) {
+                    parts.push(`**Result from Task ${depId}:**\n${JSON.stringify(depResult, null, 2)}\n`);
+                }
+            }
+        }
+        parts.push("Please perform the step based on the provided context, instructions, and upstream task results.");
+        return parts.join("\n");
+    }
+    /**
+     * Execute the step, yielding ProcessingMessages as progress updates.
+     */
+    async *execute() {
+        yield* withAgentSpanGen("step", {
+            provider: this.provider.provider,
+            model: this.model,
+            task: this.step.instructions,
+            toolsCount: this.tools.length,
+            extra: {
+                "agent.step.id": this.step.id,
+                "agent.task.id": this.task.id
+            }
+        }, () => this._executeImpl());
+    }
+    async *_executeImpl() {
+        log.debug("Step started", {
+            stepId: this.step.id,
+            instructions: this.step.instructions.slice(0, 60)
+        });
+        // Initialize history with system prompt
+        this.history.push({ role: "system", content: this.systemPrompt });
+        // Build user message with instructions and dependency results
+        const userContent = await this.buildUserMessage();
+        this.history.push({ role: "user", content: userContent });
+        // Yield task update: step started
+        this.step.startTime = Date.now();
+        yield {
+            type: "task_update",
+            node_id: this.step.id,
+            task: { id: this.task.id, title: this.task.title },
+            step: { id: this.step.id, instructions: this.step.instructions },
+            event: TaskUpdateEvent.StepStarted
+        };
+        rejectAgenticProvider(this.provider, "StepExecutor.execute");
+        // --- Standard multi-iteration loop ---
+        while (!this.step.completed && this.iterations < this.maxIterations) {
+            this.iterations++;
+            // Check token budget
+            const tokenCount = this.estimateTokens();
+            if (tokenCount > this.maxTokenLimit && !this.inConclusionStage) {
+                this.enterConclusionStage();
+                yield {
+                    type: "task_update",
+                    node_id: this.step.id,
+                    task: { id: this.task.id, title: this.task.title },
+                    step: { id: this.step.id, instructions: this.step.instructions },
+                    event: TaskUpdateEvent.EnteredConclusionStage
+                };
+            }
+            // Trim history if needed
+            await this.trimHistoryIfNeeded();
+            // Determine available tools
+            const currentTools = this.getCurrentTools();
+            const providerTools = currentTools.map((t) => t.toProviderTool());
+            // Yield log update
+            yield {
+                type: "log_update",
+                node_id: this.step.id,
+                node_name: `Step: ${this.step.id}`,
+                content: !this.inConclusionStage
+                    ? "Generating next steps..."
+                    : "Synthesizing final answer...",
+                severity: "info"
+            };
+            // Track input tokens
+            this.inputTokensTotal += this.estimateTokens();
+            // Call LLM
+            let content = "";
+            const toolCalls = [];
+            let message;
+            try {
+                const stream = this.provider.generateMessagesTraced({
+                    messages: [...this.history],
+                    model: this.model,
+                    tools: providerTools.length > 0 ? providerTools : undefined,
+                    threadId: this.threadId
+                });
+                for await (const item of stream) {
+                    if (isChunk(item)) {
+                        content += item.content ?? "";
+                        yield {
+                            type: "chunk",
+                            node_id: this.step.id,
+                            content: item.content,
+                            done: false
+                        };
+                    }
+                    if (isToolCall(item)) {
+                        log.debug("Tool call", { name: item.name });
+                        toolCalls.push(item);
+                    }
+                }
+                // Clean think tags from content
+                content = removeThinkTags(content);
+                message = { role: "assistant", content: content ?? "" };
+                if (toolCalls.length > 0) {
+                    message.toolCalls = toolCalls;
+                }
+                // Estimate output tokens
+                this.outputTokensTotal += Math.ceil((content.length + JSON.stringify(toolCalls).length) / 4);
+            }
+            catch (e) {
+                log.error("Step failed", { stepId: this.step.id, error: String(e) });
+                this.generationFailures++;
+                if (this.generationFailures >= 3)
+                    throw e;
+                message = {
+                    role: "assistant",
+                    content: `Error generating message: ${e}`
+                };
+            }
+            // Filter tool calls for current stage
+            const filteredToolCalls = message.toolCalls
+                ? this.filterToolCallsForCurrentStage(message.toolCalls)
+                : [];
+            message.toolCalls =
+                filteredToolCalls.length > 0 ? filteredToolCalls : undefined;
+            // Add assistant message to history
+            this.history.push(message);
+            // Process tool calls
+            if (filteredToolCalls.length > 0) {
+                // Check for finish_step tool call first
+                const finishStepCall = filteredToolCalls.find((tc) => tc.name === "finish_step");
+                if (finishStepCall && this.finishStepTool) {
+                    // Yield tool call update
+                    yield {
+                        type: "tool_call_update",
+                        node_id: this.step.id,
+                        name: finishStepCall.name,
+                        args: finishStepCall.args,
+                        message: this.generateToolCallMessage(finishStepCall)
+                    };
+                    // Extract and validate result
+                    const resultPayload = finishStepCall.args?.["result"] ?? finishStepCall.args;
+                    if (resultPayload !== undefined && resultPayload !== null) {
+                        const [isValid, errorDetail, normalizedResult] = this.validateResultPayload(resultPayload);
+                        if (isValid &&
+                            normalizedResult !== null &&
+                            normalizedResult !== undefined) {
+                            // Add tool result to history
+                            this.history.push({
+                                role: "tool",
+                                toolCallId: finishStepCall.id,
+                                content: '{"status": "completed"}'
+                            });
+                            await this.storeCompletionResult(normalizedResult);
+                            log.debug("Step completed", { stepId: this.step.id });
+                            yield {
+                                type: "task_update",
+                                node_id: this.step.id,
+                                task: { id: this.task.id, title: this.task.title },
+                                step: {
+                                    id: this.step.id,
+                                    instructions: this.step.instructions
+                                },
+                                event: TaskUpdateEvent.StepCompleted
+                            };
+                            yield {
+                                type: "step_result",
+                                step: {
+                                    id: this.step.id,
+                                    instructions: this.step.instructions
+                                },
+                                result: normalizedResult,
+                                is_task_result: this.useFinishTask
+                            };
+                            break;
+                        }
+                        else {
+                            // Invalid result - add feedback and continue loop
+                            this.history.push({
+                                role: "tool",
+                                toolCallId: finishStepCall.id,
+                                content: JSON.stringify({
+                                    error: `Result validation failed: ${errorDetail}`
+                                })
+                            });
+                            this.appendCompletionFeedback(errorDetail ?? "Result failed schema validation.", resultPayload);
+                        }
+                    }
+                    else {
+                        this.history.push({
+                            role: "tool",
+                            toolCallId: finishStepCall.id,
+                            content: '{"error": "Missing result in finish_step call"}'
+                        });
+                    }
+                }
+                else {
+                    // Process non-finish_step tool calls
+                    const regularToolCalls = filteredToolCalls.filter((tc) => tc.name !== "finish_step");
+                    // Yield tool call updates
+                    for (const tc of regularToolCalls) {
+                        yield {
+                            type: "tool_call_update",
+                            node_id: this.step.id,
+                            name: tc.name,
+                            args: tc.args,
+                            message: this.generateToolCallMessage(tc)
+                        };
+                    }
+                    const toolNamesStr = regularToolCalls.map((tc) => tc.name).join(", ");
+                    // Standard execution path: run tools ourselves and add results to history
+                    yield {
+                        type: "log_update",
+                        node_id: this.step.id,
+                        node_name: `Step: ${this.step.id}`,
+                        content: `Executing tools: ${toolNamesStr}...`,
+                        severity: "info"
+                    };
+                    // Execute tool calls in parallel
+                    const toolResults = await Promise.allSettled(regularToolCalls.map(async (tc) => {
+                        const tool = this.tools.find((t) => t.name === tc.name);
+                        if (!tool)
+                            return { error: `Unknown tool: ${tc.name}` };
+                        // Intercept ControlNodeTool: create event instead of calling process()
+                        if (tool instanceof ControlNodeTool) {
+                            const event = tool.createControlEvent(tc.args ?? {});
+                            this._controlEvents.push({
+                                targetNodeId: tool.targetNodeId,
+                                event
+                            });
+                            return tool.userMessage(tc.args ?? {});
+                        }
+                        try {
+                            const result = await tool.process(this.context, tc.args ?? {});
+                            return result;
+                        }
+                        catch (e) {
+                            return { error: String(e) };
+                        }
+                    }));
+                    // Add tool results to history
+                    for (let i = 0; i < regularToolCalls.length; i++) {
+                        const tc = regularToolCalls[i];
+                        const settledResult = toolResults[i];
+                        let toolResult;
+                        if (settledResult.status === "fulfilled") {
+                            toolResult = settledResult.value;
+                        }
+                        else {
+                            toolResult = {
+                                error: `Tool execution failed: ${settledResult.reason}`
+                            };
+                        }
+                        // Save base64 binary artifacts (images, audio) to workspace files
+                        toolResult = await this.handleBinaryArtifact(toolResult);
+                        toolResult = await this.capturePersistentSandboxOutputs(tc.name, tc.args, toolResult);
+                        // Track browser URLs for source lineage (from args and results)
+                        if (tc.name === "browser" && tc.args?.["url"]) {
+                            const url = String(tc.args["url"]);
+                            if (!this.sourcesSet.has(url)) {
+                                this.sources.push(url);
+                                this.sourcesSet.add(url);
+                            }
+                        }
+                        this.trackToolSideEffects(tc.name, toolResult);
+                        const resultStr = this.serializeToolResultForHistory(toolResult, tc.name);
+                        this.history.push({
+                            role: "tool",
+                            toolCallId: tc.id,
+                            content: resultStr
+                        });
+                    }
+                    yield {
+                        type: "log_update",
+                        node_id: this.step.id,
+                        node_name: `Step: ${this.step.id}`,
+                        content: `Completed tool execution: ${toolNamesStr}.`,
+                        severity: "info"
+                    };
+                }
+            }
+            // Try to finalize from message content (inline JSON completion).
+            if (!this.step.completed) {
+                const [completed, normalizedResult] = this.maybeFinalizeFromMessage(message);
+                if (completed &&
+                    normalizedResult !== null &&
+                    normalizedResult !== undefined) {
+                    await this.storeCompletionResult(normalizedResult);
+                    yield {
+                        type: "task_update",
+                        node_id: this.step.id,
+                        task: { id: this.task.id, title: this.task.title },
+                        step: { id: this.step.id, instructions: this.step.instructions },
+                        event: TaskUpdateEvent.StepCompleted
+                    };
+                    yield {
+                        type: "step_result",
+                        step: { id: this.step.id, instructions: this.step.instructions },
+                        result: normalizedResult,
+                        is_task_result: this.useFinishTask
+                    };
+                    break;
+                }
+            }
+        }
+        // If we exhausted iterations without completing, yield a failure event
+        // and a step_result so downstream steps see an explicit error rather than undefined.
+        if (!this.step.completed) {
+            this.step.completed = true;
+            this.step.endTime = Date.now();
+            const errorResult = {
+                error: `Step failed: exceeded ${this.maxIterations} iterations without completion`
+            };
+            this.result = errorResult;
+            await this.context.storeStepResult(this.step.id, errorResult);
+            yield {
+                type: "task_update",
+                node_id: this.step.id,
+                task: { id: this.task.id, title: this.task.title },
+                step: { id: this.step.id, instructions: this.step.instructions },
+                event: TaskUpdateEvent.StepFailed
+            };
+            yield {
+                type: "step_result",
+                step: { id: this.step.id, instructions: this.step.instructions },
+                result: errorResult,
+                is_task_result: this.useFinishTask
+            };
+        }
+    }
+    /**
+     * Get the captured result after execution completes.
+     */
+    getResult() {
+        return this.result;
+    }
+    /**
+     * Get tracked sources (e.g. browser URLs).
+     */
+    getSources() {
+        return [...this.sources];
+    }
+    /**
+     * Get token usage statistics.
+     */
+    getTokenUsage() {
+        return {
+            inputTokensTotal: this.inputTokensTotal,
+            outputTokensTotal: this.outputTokensTotal
+        };
+    }
+    /**
+     * Get control events emitted during execution (from ControlNodeTool calls).
+     * The caller (workflow actor/runner) is responsible for dispatching these.
+     */
+    getControlEvents() {
+        return [...this._controlEvents];
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers to discriminate ProviderStreamItem union members
+// ---------------------------------------------------------------------------
+function isChunk(item) {
+    return ("type" in item &&
+        item["type"] === "chunk" &&
+        typeof item["content"] === "string");
+}
+function isToolCall(item) {
+    return ("name" in item &&
+        typeof item["name"] === "string" &&
+        "id" in item);
+}
+//# sourceMappingURL=step-executor.js.map