agentfootprint 1.0.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAEH,+DAA+D;AAC/D,uCAOoB;AANlB,iGAAA,KAAK,OAAA;AAAE,uGAAA,WAAW,OAAA;AAClB,mGAAA,OAAO,OAAA;AAAE,yGAAA,aAAa,OAAA;AACtB,+FAAA,GAAG,OAAA;AAAE,qGAAA,SAAS,OAAA;AACd,qGAAA,SAAS,OAAA;AAAE,2GAAA,eAAe,OAAA;AAC1B,iGAAA,KAAK,OAAA;AAAE,uGAAA,WAAW,OAAA;AAClB,oGAAA,QAAQ,OAAA;AAAE,0GAAA,cAAc,OAAA;AAG1B,+DAA+D;AAC/D,iCAA6D;AAApD,mGAAA,UAAU,OAAA;AAAE,iGAAA,QAAQ,OAAA;AAAE,qGAAA,YAAY,OAAA;AAE3C,iEAAiE;AACjE,uCAA6F;AAApF,gGAAA,IAAI,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,0GAAA,cAAc,OAAA;AACxE,mCAA8D;AAArD,mGAAA,SAAS,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,iGAAA,OAAO,OAAA;AAC3C,uCAA6E;AAApE,4GAAA,gBAAgB,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,0GAAA,cAAc,OAAA;AACxD,uCAA2E;AAAlE,mHAAA,uBAAuB,OAAA;AAAE,gHAAA,oBAAoB,OAAA;AACtD,uDAA2D;AAAlD,yGAAA,aAAa,OAAA;AACtB,mDAAkF;AAAzE,oGAAA,UAAU,OAAA;AAAE,qGAAA,WAAW,OAAA;AAAE,uGAAA,aAAa,OAAA;AAa/C,+DAA+D;AAC/D,iCAGiB;AAFf,sGAAA,aAAa,OAAA;AAAE,oGAAA,WAAW,OAAA;AAAE,yGAAA,gBAAgB,OAAA;AAAE,0GAAA,iBAAiB,OAAA;AAC/D,kGAAA,SAAS,OAAA;AAAE,mGAAA,UAAU,OAAA;AAAE,oGAAA,WAAW,OAAA;AAAE,iGAAA,QAAQ,OAAA;AAG9C,+DAA+D;AAC/D,iCAAmC;AAA1B,iGAAA,QAAQ,OAAA"}

package/dist/instructions.barrel.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * agentfootprint/instructions — Make agents smart with conditional context injection.
+ *
+ * Define rules that inject into system prompt, tools, and tool-result recency window
+ * based on accumulated Decision Scope state.
+ *
+ * @example
+ * ```typescript
+ * import { defineInstruction, AgentPattern } from 'agentfootprint/instructions';
+ *
+ * const refund = defineInstruction({
+ *   id: 'refund-handling',
+ *   activeWhen: (d) => d.orderStatus === 'denied',
+ *   prompt: 'Be empathetic.',
+ *   tools: [processRefund],
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InstructionRecorder = exports.AgentPattern = exports.quickBind = exports.follow = exports.defineInstruction = void 0;
+var instructions_1 = require("./lib/instructions");
+Object.defineProperty(exports, "defineInstruction", { enumerable: true, get: function () { return instructions_1.defineInstruction; } });
+Object.defineProperty(exports, "follow", { enumerable: true, get: function () { return instructions_1.follow; } });
+Object.defineProperty(exports, "quickBind", { enumerable: true, get: function () { return instructions_1.quickBind; } });
+var loop_1 = require("./lib/loop");
+Object.defineProperty(exports, "AgentPattern", { enumerable: true, get: function () { return loop_1.AgentPattern; } });
+var instructions_2 = require("./lib/instructions");
+Object.defineProperty(exports, "InstructionRecorder", { enumerable: true, get: function () { return instructions_2.InstructionRecorder; } });
+//# sourceMappingURL=instructions.barrel.js.map

package/dist/instructions.barrel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.barrel.js","sourceRoot":"","sources":["../src/instructions.barrel.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAEH,mDAA0E;AAAjE,iHAAA,iBAAiB,OAAA;AAAE,sGAAA,MAAM,OAAA;AAAE,yGAAA,SAAS,OAAA;AAS7C,mCAA0C;AAAjC,oGAAA,YAAY,OAAA;AACrB,mDAAyD;AAAhD,mHAAA,mBAAmB,OAAA"}

package/dist/lib/call/callLLMStage.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * CallLLM stage — sends messages + tools to the LLM provider.
+ *
+ * Reads from scope:
+ *   - messages (set by Messages slot or prior stages)
+ *   - toolDescriptions (set by Tools slot)
+ *
+ * Writes to scope:
+ *   - adapterResult (discriminated union: 'final' | 'tools' | 'error')
+ *   - adapterRawResponse (raw LLM response for recorders)
+ *   - llmCall (narrative summary of the LLM call)
+ *
+ * Emits AgentStreamEvents:
+ *   - llm_start { iteration }
+ *   - llm_end { iteration, toolCallCount, content, model, latencyMs }
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCallLLMStage = void 0;
+const helpers_1 = require("./helpers");
+/**
+ * Create the CallLLM stage function.
+ */
+function createCallLLMStage(provider, optionsOrHandler) {
+    if (!provider) {
+        throw new Error('createCallLLMStage: provider is required');
+    }
+    // Backward compat: accept bare handler or options object
+    const stageOpts = typeof optionsOrHandler === 'function'
+        ? { onStreamEvent: optionsOrHandler }
+        : optionsOrHandler ?? {};
+    const { onStreamEvent, responseFormat } = stageOpts;
+    return async (scope) => {
+        const messages = scope.messages ?? [];
+        const tools = scope.toolDescriptions ?? [];
+        const signal = scope.$getEnv()?.signal;
+        const iteration = (scope.loopCount ?? 0) + 1;
+        const startMs = Date.now();
+        onStreamEvent?.({ type: 'llm_start', iteration });
+        const options = {
+            ...(tools.length > 0 ? { tools } : {}),
+            ...(signal ? { signal } : {}),
+            ...(responseFormat ? { responseFormat } : {}),
+        };
+        const response = await provider.chat(messages, Object.keys(options).length > 0 ? options : undefined);
+        // Write raw response for recorders to observe
+        scope.adapterRawResponse = response;
+        // Normalize to AdapterResult
+        scope.adapterResult = (0, helpers_1.normalizeAdapterResponse)(response);
+        // Write summary for narrative visibility
+        const model = response.model ?? 'unknown';
+        const usage = response.usage;
+        const usageSummary = usage
+            ? `${usage.inputTokens ?? '?'}in / ${usage.outputTokens ?? '?'}out`
+            : 'no usage data';
+        scope.llmCall = `${model} (${usageSummary})`;
+        onStreamEvent?.({
+            type: 'llm_end',
+            iteration,
+            toolCallCount: response.toolCalls?.length ?? 0,
+            content: response.content,
+            model: response.model,
+            latencyMs: Date.now() - startMs,
+        });
+    };
+}
+exports.createCallLLMStage = createCallLLMStage;
+//# sourceMappingURL=callLLMStage.js.map

package/dist/lib/call/callLLMStage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callLLMStage.js","sourceRoot":"","sources":["../../../src/lib/call/callLLMStage.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAMH,uCAAqD;AAOrD;;GAEG;AACH,SAAgB,kBAAkB,CAChC,QAAqB,EACrB,gBAAgE;IAEhE,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IAED,yDAAyD;IACzD,MAAM,SAAS,GAAwB,OAAO,gBAAgB,KAAK,UAAU;QAC3E,CAAC,CAAC,EAAE,aAAa,EAAE,gBAAgB,EAAE;QACrC,CAAC,CAAC,gBAAgB,IAAI,EAAE,CAAC;IAE3B,MAAM,EAAE,aAAa,EAAE,cAAc,EAAE,GAAG,SAAS,CAAC;IAEpD,OAAO,KAAK,EAAE,KAAiC,EAAE,EAAE;QACjD,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;QACtC,MAAM,KAAK,GAAG,KAAK,CAAC,gBAAgB,IAAI,EAAE,CAAC;QAC3C,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC;QACvC,MAAM,SAAS,GAAG,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE3B,aAAa,EAAE,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC,CAAC;QAElD,MAAM,OAAO,GAAmB;YAC9B,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACtC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7B,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9C,CAAC;QACF,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAEtG,8CAA8C;QAC9C,KAAK,CAAC,kBAAkB,GAAG,QAAQ,CAAC;QAEpC,6BAA6B;QAC7B,KAAK,CAAC,aAAa,GAAG,IAAA,kCAAwB,EAAC,QAAQ,CAAC,CAAC;QAEzD,yCAAyC;QACzC,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,IAAI,SAAS,CAAC;QAC1C,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;QAC7B,MAAM,YAAY,GAAG,KAAK;YACxB,CAAC,CAAC,GAAG,KAAK,CAAC,WAAW,IAAI,GAAG,QAAQ,KAAK,CAAC,YAAY,IAAI,GAAG,KAAK;YACnE,CAAC,CAAC,eAAe,CAAC;QACpB,KAAK,CAAC,OAAO,GAAG,GAAG,KAAK,KAAK,YAAY,GAAG,CAAC;QAE7C,aAAa,EAAE,CAAC;YACd,IAAI,EAAE,SAAS;YACf,SAAS;YACT,aAAa,EAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC;YAC9C,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO;SAChC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC;AAtDD,gDAsDC"}

package/dist/lib/call/handleResponseStage.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * HandleResponse stage — finalize the turn when no tool calls remain.
+ *
+ * @deprecated Use the RouteResponse decider pattern in buildAgentLoop instead.
+ * The loop now uses addDeciderFunction('RouteResponse') with 'tool-calls' and
+ * 'final' branches. The Finalize branch (createFinalizeStage) replaces this stage.
+ * Kept for backward compatibility with custom chart builders.
+ *
+ * Reads from scope:
+ *   - parsedResponse (set by ParseResponse)
+ *   - loopCount, maxIterations
+ *   - messages
+ *
+ * Writes to scope:
+ *   - result (final answer text)
+ *   - memory_shouldCommit (when useCommitFlag)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHandleResponseStage = void 0;
+const content_1 = require("../../types/content");
+const memory_1 = require("../../memory");
+/**
+ * Create the HandleResponse stage function.
+ *
+ * Tool execution is handled by the upstream sf-execute-tools subflow.
+ * HandleResponse only finalizes: if no tool calls remain, extract result + break.
+ * If tools were executed (loopCount incremented by subflow), loop continues.
+ */
+function createHandleResponseStage(options) {
+    const { useCommitFlag } = options;
+    return (scope) => {
+        const parsed = scope.parsedResponse;
+        const loopCount = scope.loopCount ?? 0;
+        const maxIterations = scope.maxIterations ?? 10;
+        // If tools were executed by sf-execute-tools, loop continues
+        if (parsed?.hasToolCalls && loopCount < maxIterations) {
+            return;
+        }
+        // Finalize: no tool calls, or max iterations reached
+        const messages = scope.messages ?? [];
+        const lastAsst = (0, memory_1.lastAssistantMessage)(messages);
+        scope.result = lastAsst ? (0, content_1.getTextContent)(lastAsst.content) : '';
+        if (useCommitFlag) {
+            scope.memory_shouldCommit = true;
+        }
+        else {
+            scope.$break();
+        }
+    };
+}
+exports.createHandleResponseStage = createHandleResponseStage;
+//# sourceMappingURL=handleResponseStage.js.map

package/dist/lib/call/handleResponseStage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handleResponseStage.js","sourceRoot":"","sources":["../../../src/lib/call/handleResponseStage.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AAIH,iDAAqD;AACrD,yCAAoD;AAUpD;;;;;;GAMG;AACH,SAAgB,yBAAyB,CAAC,OAA8B;IACtE,MAAM,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC;IAClC,OAAO,CAAC,KAAiC,EAAE,EAAE;QAC3C,MAAM,MAAM,GAAG,KAAK,CAAC,cAAc,CAAC;QACpC,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,CAAC,CAAC;QACvC,MAAM,aAAa,GAAG,KAAK,CAAC,aAAa,IAAI,EAAE,CAAC;QAEhD,6DAA6D;QAC7D,IAAI,MAAM,EAAE,YAAY,IAAI,SAAS,GAAG,aAAa,EAAE,CAAC;YACtD,OAAO;QACT,CAAC;QAED,qDAAqD;QACrD,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,IAAA,6BAAoB,EAAC,QAAQ,CAAC,CAAC;QAChD,KAAK,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAA,wBAAc,EAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAEhE,IAAI,aAAa,EAAE,CAAC;YAClB,KAAK,CAAC,mBAAmB,GAAG,IAAI,CAAC;QACnC,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,MAAM,EAAE,CAAC;QACjB,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAvBD,8DAuBC"}

package/dist/lib/call/helpers.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * Shared helpers for call module stages.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeToolCalls = exports.normalizeAdapterResponse = void 0;
+const types_1 = require("../../types");
+const askHuman_1 = require("../../tools/askHuman");
+const validateInput_1 = require("../../tools/validateInput");
+const instructions_1 = require("../instructions");
+/**
+ * Normalize an LLMResponse into an AdapterResult discriminated union.
+ */
+function normalizeAdapterResponse(response) {
+    if (response.toolCalls && response.toolCalls.length > 0) {
+        return {
+            type: 'tools',
+            content: response.content ?? '',
+            toolCalls: response.toolCalls,
+            usage: response.usage,
+            model: response.model,
+        };
+    }
+    return {
+        type: 'final',
+        content: response.content,
+        usage: response.usage,
+        model: response.model,
+    };
+}
+exports.normalizeAdapterResponse = normalizeAdapterResponse;
+async function executeToolCalls(toolCalls, registry, messages, toolProvider, signal, instructionConfig, decision) {
+    // Single copy upfront — O(M+N) instead of O(M*N) from repeated spreads
+    const result = [...messages];
+    let askHumanPause;
+    const onStreamEvent = instructionConfig?.onStreamEvent;
+    for (const toolCall of toolCalls) {
+        let resultContent;
+        let runtimeInstructions;
+        let runtimeFollowUps;
+        let errorInfo;
+        const startMs = Date.now();
+        onStreamEvent?.({
+            type: 'tool_start',
+            toolName: toolCall.name,
+            toolCallId: toolCall.id,
+            args: (toolCall.arguments ?? {}),
+        });
+        // Try ToolProvider.execute() first (handles remote tools, gated tools, etc.)
+        // Skip ToolProvider for ask_human — it must run locally (uses Symbol marker for pause detection).
+        if (toolProvider?.execute && toolCall.name !== 'ask_human') {
+            try {
+                const execResult = await toolProvider.execute(toolCall, signal);
+                resultContent = execResult.content;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                errorInfo = { message: msg };
+                resultContent = JSON.stringify({ error: true, message: msg });
+            }
+        }
+        else {
+            // Fall back to ToolRegistry (local ToolDefinition handlers)
+            const tool = registry.get(toolCall.name);
+            if (!tool) {
+                // Sanitize tool name to prevent injection into error messages fed back to LLM
+                const safeName = String(toolCall.name).slice(0, 100).replace(/[\n\r]/g, '');
+                errorInfo = { code: 'NOT_FOUND', message: `Tool '${safeName}' not found` };
+                resultContent = JSON.stringify({ error: true, message: errorInfo.message });
+            }
+            else {
+                // Validate input against tool's inputSchema before calling handler
+                const toolArgs = (toolCall.arguments ?? {});
+                if (tool.inputSchema && Object.keys(tool.inputSchema).length > 0) {
+                    const validation = (0, validateInput_1.validateToolInput)(toolArgs, tool.inputSchema);
+                    if (!validation.valid) {
+                        errorInfo = { code: 'INVALID_INPUT', message: `Invalid arguments for '${tool.id}': ${(0, validateInput_1.formatValidationErrors)(validation.errors)}` };
+                        resultContent = JSON.stringify({ error: true, message: errorInfo.message });
+                        result.push((0, types_1.toolResultMessage)(resultContent, toolCall.id));
+                        continue;
+                    }
+                }
+                try {
+                    const execResult = await tool.handler(toolArgs);
+                    resultContent = execResult.content;
+                    // Check for ask_human pause marker
+                    if ((0, askHuman_1.isAskHumanResult)(execResult)) {
+                        askHumanPause = { question: execResult.question, toolCallId: toolCall.id };
+                    }
+                    // Check for InstructedToolResult (runtime instructions/followUps)
+                    const instructed = execResult;
+                    runtimeInstructions = instructed.instructions;
+                    runtimeFollowUps = instructed.followUps;
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    errorInfo = { message: msg };
+                    resultContent = JSON.stringify({ error: true, message: msg });
+                }
+            }
+        }
+        // Capture tool execution latency BEFORE instruction processing overhead
+        const toolExecLatencyMs = Date.now() - startMs;
+        const latencyMs = toolExecLatencyMs;
+        // Process instructions if config provided (build-time, agent-level, or runtime)
+        if (instructionConfig) {
+            const perToolInstructions = instructionConfig.instructionsByToolId.get(toolCall.name);
+            const agentRules = instructionConfig.agentResponseRules;
+            // Merge agent-level response rules (captured by closure) with per-tool instructions
+            const buildTimeInstructions = agentRules?.length
+                ? [...agentRules, ...(perToolInstructions ?? [])]
+                : perToolInstructions;
+            const hasInstructions = buildTimeInstructions?.length || runtimeInstructions?.length || runtimeFollowUps?.length;
+            if (hasInstructions) {
+                // Parse content for InstructionContext — try JSON, fall back to raw string
+                let parsedContent;
+                try {
+                    parsedContent = JSON.parse(resultContent);
+                }
+                catch {
+                    parsedContent = resultContent;
+                }
+                const ctx = {
+                    content: parsedContent,
+                    error: errorInfo,
+                    latencyMs,
+                    input: toolCall.arguments,
+                    toolId: toolCall.name,
+                };
+                const injectionResult = (0, instructions_1.processInstructions)(resultContent, buildTimeInstructions, ctx, (runtimeInstructions || runtimeFollowUps)
+                    ? { instructions: runtimeInstructions, followUps: runtimeFollowUps }
+                    : undefined, instructionConfig?.template);
+                if (injectionResult.injected) {
+                    resultContent = injectionResult.content;
+                }
+                if (injectionResult.fired.length > 0 && instructionConfig?.onInstructionsFired) {
+                    instructionConfig.onInstructionsFired(toolCall.name, injectionResult.fired);
+                }
+                // Run decide() functions for matched instructions — updates Decision Scope.
+                // decide functions are in the closure map (not in scope — functions stripped on scope write).
+                if (decision && instructionConfig?.decideFunctions?.size) {
+                    for (const fired of injectionResult.fired) {
+                        const decideFn = instructionConfig.decideFunctions.get(fired.id);
+                        if (decideFn) {
+                            try {
+                                decideFn(decision, ctx);
+                            }
+                            catch {
+                                // decide errors are fail-open — don't crash tool execution
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        onStreamEvent?.({
+            type: 'tool_end',
+            toolName: toolCall.name,
+            toolCallId: toolCall.id,
+            result: resultContent,
+            error: !!errorInfo,
+            latencyMs: toolExecLatencyMs,
+        });
+        result.push((0, types_1.toolResultMessage)(resultContent, toolCall.id));
+    }
+    return { messages: result, askHumanPause };
+}
+exports.executeToolCalls = executeToolCalls;
+//# sourceMappingURL=helpers.js.map

package/dist/lib/call/helpers.js.map

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

package/dist/lib/call/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeToolCalls = exports.normalizeAdapterResponse = exports.buildToolExecutionSubflow = exports.createHandleResponseStage = exports.parseResponseStage = exports.createStreamingCallLLMStage = exports.createCallLLMStage = void 0;
+var callLLMStage_1 = require("./callLLMStage");
+Object.defineProperty(exports, "createCallLLMStage", { enumerable: true, get: function () { return callLLMStage_1.createCallLLMStage; } });
+var streamingCallLLMStage_1 = require("./streamingCallLLMStage");
+Object.defineProperty(exports, "createStreamingCallLLMStage", { enumerable: true, get: function () { return streamingCallLLMStage_1.createStreamingCallLLMStage; } });
+var parseResponseStage_1 = require("./parseResponseStage");
+Object.defineProperty(exports, "parseResponseStage", { enumerable: true, get: function () { return parseResponseStage_1.parseResponseStage; } });
+var handleResponseStage_1 = require("./handleResponseStage");
+Object.defineProperty(exports, "createHandleResponseStage", { enumerable: true, get: function () { return handleResponseStage_1.createHandleResponseStage; } });
+var toolExecutionSubflow_1 = require("./toolExecutionSubflow");
+Object.defineProperty(exports, "buildToolExecutionSubflow", { enumerable: true, get: function () { return toolExecutionSubflow_1.buildToolExecutionSubflow; } });
+var helpers_1 = require("./helpers");
+Object.defineProperty(exports, "normalizeAdapterResponse", { enumerable: true, get: function () { return helpers_1.normalizeAdapterResponse; } });
+Object.defineProperty(exports, "executeToolCalls", { enumerable: true, get: function () { return helpers_1.executeToolCalls; } });
+//# sourceMappingURL=index.js.map

package/dist/lib/call/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/call/index.ts"],"names":[],"mappings":";;;AAAA,+CAAoD;AAA3C,kHAAA,kBAAkB,OAAA;AAC3B,iEAAsE;AAA7D,oIAAA,2BAA2B,OAAA;AACpC,2DAA0D;AAAjD,wHAAA,kBAAkB,OAAA;AAC3B,6DAAkE;AAAzD,gIAAA,yBAAyB,OAAA;AAElC,+DAAmE;AAA1D,iIAAA,yBAAyB,OAAA;AAElC,qCAAuE;AAA9D,mHAAA,wBAAwB,OAAA;AAAE,2GAAA,gBAAgB,OAAA"}

package/dist/lib/call/parseResponseStage.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * ParseResponse stage — extract ParsedResponse from AdapterResult.
+ *
+ * Also appends the assistant message to conversation history.
+ *
+ * Reads from scope:
+ *   - adapterResult (set by CallLLM)
+ *
+ * Writes to scope:
+ *   - parsedResponse (hasToolCalls, toolCalls[], content)
+ *   - messages (appends assistant message)
+ *   - responseType (narrative summary of the response)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseResponseStage = void 0;
+const types_1 = require("../../types");
+const memory_1 = require("../../memory");
+/**
+ * ParseResponse stage function.
+ * Stateless — no factory needed.
+ */
+function parseResponseStage(scope) {
+    const result = scope.adapterResult;
+    if (!result) {
+        throw new Error('ParseResponse: no adapter result in scope');
+    }
+    if (result.type === 'error') {
+        throw new Error(`LLM call failed: [${result.code}] ${result.message}`);
+    }
+    const parsed = {
+        hasToolCalls: result.type === 'tools',
+        toolCalls: result.type === 'tools' ? result.toolCalls : [],
+        content: result.content,
+    };
+    scope.parsedResponse = parsed;
+    // Append assistant message to conversation
+    const messages = scope.messages ?? [];
+    const asstMsg = (0, types_1.assistantMessage)(result.content, result.type === 'tools' ? result.toolCalls : undefined);
+    scope.messages = (0, memory_1.appendMessage)(messages, asstMsg);
+    // Write summary for narrative visibility
+    if (parsed.hasToolCalls) {
+        const toolNames = parsed.toolCalls.map((tc) => tc.name).join(', ');
+        scope.responseType = `tool_calls: [${toolNames}]`;
+    }
+    else {
+        const preview = result.content.length > 80 ? result.content.slice(0, 80) + '...' : result.content;
+        scope.responseType = `final: "${preview}"`;
+    }
+}
+exports.parseResponseStage = parseResponseStage;
+//# sourceMappingURL=parseResponseStage.js.map

package/dist/lib/call/parseResponseStage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseResponseStage.js","sourceRoot":"","sources":["../../../src/lib/call/parseResponseStage.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAIH,uCAA+C;AAC/C,yCAA6C;AAE7C;;;GAGG;AACH,SAAgB,kBAAkB,CAAC,KAAiC;IAClE,MAAM,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC;IAEnC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,qBAAqB,MAAM,CAAC,IAAI,KAAK,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,MAAM,MAAM,GAAG;QACb,YAAY,EAAE,MAAM,CAAC,IAAI,KAAK,OAAO;QACrC,SAAS,EAAE,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE;QAC1D,OAAO,EAAE,MAAM,CAAC,OAAO;KACxB,CAAC;IAEF,KAAK,CAAC,cAAc,GAAG,MAAM,CAAC;IAE9B,2CAA2C;IAC3C,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;IACtC,MAAM,OAAO,GAAG,IAAA,wBAAgB,EAC9B,MAAM,CAAC,OAAO,EACd,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CACvD,CAAC;IACF,KAAK,CAAC,QAAQ,GAAG,IAAA,sBAAa,EAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAElD,yCAAyC;IACzC,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;QACxB,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnE,KAAK,CAAC,YAAY,GAAG,gBAAgB,SAAS,GAAG,CAAC;IACpD,CAAC;SAAM,CAAC;QACN,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;QAClG,KAAK,CAAC,YAAY,GAAG,WAAW,OAAO,GAAG,CAAC;IAC7C,CAAC;AACH,CAAC;AAnCD,gDAmCC"}

package/dist/lib/call/streamingCallLLMStage.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * Streaming CallLLM stage — bridges LLMProvider.chatStream() with footprintjs StreamCallback
+ * and emits AgentStreamEvents for consumer visibility.
+ *
+ * Events emitted:
+ *   - llm_start { iteration } — before the LLM call
+ *   - token { content } — each text chunk from the LLM
+ *   - thinking { content } — extended thinking blocks (Anthropic)
+ *   - llm_end { iteration, toolCallCount, content, model, latencyMs } — after LLM completes
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStreamingCallLLMStage = void 0;
+const helpers_1 = require("./helpers");
+/**
+ * Create a streaming-capable CallLLM stage function.
+ */
+function createStreamingCallLLMStage(provider, optionsOrHandler) {
+    // Backward compat: accept bare handler or options object
+    const stageOpts = typeof optionsOrHandler === 'function'
+        ? { onStreamEvent: optionsOrHandler }
+        : optionsOrHandler ?? {};
+    const { onStreamEvent, responseFormat } = stageOpts;
+    return async (scope, _breakFn, streamCallback) => {
+        const messages = scope.messages ?? [];
+        const tools = scope.toolDescriptions ?? [];
+        const signal = scope.$getEnv?.()?.signal;
+        const options = {
+            ...(tools.length > 0 ? { tools } : {}),
+            ...(signal ? { signal } : {}),
+            ...(responseFormat ? { responseFormat } : {}),
+        };
+        const iteration = (scope.loopCount ?? 0) + 1;
+        const startMs = Date.now();
+        onStreamEvent?.({ type: 'llm_start', iteration });
+        // If streaming is available and callback is injected, use chatStream
+        if (streamCallback && provider.chatStream) {
+            const contentParts = [];
+            const thinkingParts = [];
+            const toolCalls = [];
+            let usage;
+            for await (const chunk of provider.chatStream(messages, Object.keys(options).length > 0 ? options : undefined)) {
+                switch (chunk.type) {
+                    case 'thinking':
+                        if (chunk.content) {
+                            thinkingParts.push(chunk.content);
+                            // Emit as AgentStreamEvent.thinking (not as token)
+                            onStreamEvent?.({ type: 'thinking', content: chunk.content });
+                        }
+                        break;
+                    case 'token':
+                        if (chunk.content) {
+                            contentParts.push(chunk.content);
+                            streamCallback(chunk.content);
+                        }
+                        break;
+                    case 'tool_call':
+                        if (chunk.toolCall) {
+                            toolCalls.push(chunk.toolCall);
+                        }
+                        break;
+                    case 'usage':
+                        if (chunk.usage) {
+                            usage = chunk.usage;
+                        }
+                        break;
+                    case 'done':
+                        break;
+                }
+            }
+            const content = contentParts.join('');
+            const thinking = thinkingParts.length > 0 ? thinkingParts.join('') : undefined;
+            const response = {
+                content,
+                toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+                usage,
+                model: 'model' in provider ? provider.model : undefined,
+                thinking,
+            };
+            scope.adapterRawResponse = response;
+            scope.adapterResult = (0, helpers_1.normalizeAdapterResponse)(response);
+            onStreamEvent?.({
+                type: 'llm_end',
+                iteration,
+                toolCallCount: toolCalls.length,
+                content,
+                model: response.model,
+                latencyMs: Date.now() - startMs,
+            });
+            return;
+        }
+        // Fallback: non-streaming chat()
+        const response = await provider.chat(messages, options);
+        scope.adapterRawResponse = response;
+        scope.adapterResult = (0, helpers_1.normalizeAdapterResponse)(response);
+        onStreamEvent?.({
+            type: 'llm_end',
+            iteration,
+            toolCallCount: response.toolCalls?.length ?? 0,
+            content: response.content,
+            model: response.model,
+            latencyMs: Date.now() - startMs,
+        });
+    };
+}
+exports.createStreamingCallLLMStage = createStreamingCallLLMStage;
+//# sourceMappingURL=streamingCallLLMStage.js.map

package/dist/lib/call/streamingCallLLMStage.js.map

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

package/dist/lib/call/toolExecutionSubflow.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Tool Execution Subflow — executes tool calls as a visible subflow.
+ *
+ * Replaces inline executeToolCalls() in HandleResponse with a proper subflow
+ * that appears in the flowchart and narrative. Enables:
+ *   - BTS drill-down into tool execution
+ *   - Per-tool visibility in narrative
+ *   - Future: parallel fork stages for individual tool calls
+ *
+ * The subflow has a single stage (ExecuteToolCalls) that runs all tools
+ * sequentially and appends results to messages.
+ *
+ * Config (registry, toolProvider) is closed over at build time — not
+ * passed through inputMapper.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildToolExecutionSubflow = void 0;
+const footprintjs_1 = require("footprintjs");
+const helpers_1 = require("./helpers");
+// ── Builder ──────────────────────────────────────────────────
+/**
+ * Build the tool execution subflow.
+ *
+ * Registry and toolProvider are closed over — they don't travel
+ * through inputMapper. Only scope state (parsedResponse, messages,
+ * loopCount) is mapped.
+ */
+function buildToolExecutionSubflow(config) {
+    const { registry, toolProvider, instructionConfig } = config;
+    const executeStageFn = async (scope) => {
+        const parsed = scope.parsedResponse;
+        const loopCount = scope.currentLoopCount ?? 0;
+        const maxIter = scope.maxIterations ?? 10;
+        // Defense-in-depth: the RouteResponse decider already routes to 'final'
+        // when loopCount >= maxIter, but this guard protects against standalone
+        // subflow usage without a preceding decider.
+        if (!parsed?.toolCalls?.length || loopCount >= maxIter) {
+            scope.toolResultMessages = [];
+            scope.updatedLoopCount = loopCount;
+            return;
+        }
+        const messages = scope.currentMessages ?? [];
+        // $getEnv() is a TypedScope proxy method — always available, not in state interface
+        const signal = scope.$getEnv()?.signal;
+        // Copy decision scope for `decide` field mutations.
+        // decide() functions mutate the copy in-place; we write it back as updatedDecision.
+        // currentDecision may be undefined when initial decision is {} (empty objects
+        // are dropped by footprintjs inputMapper). Use {} as fallback when instructions are configured.
+        const rawDecision = scope.currentDecision;
+        const decisionRef = rawDecision ? { ...rawDecision } : (instructionConfig?.decideFunctions?.size ? {} : undefined);
+        const { messages: resultMessages, askHumanPause } = await (0, helpers_1.executeToolCalls)(parsed.toolCalls, registry, messages, toolProvider, signal, instructionConfig, decisionRef);
+        // Output DELTA only — footprintjs applyOutputMapping concatenates arrays,
+        // so the parent's outputMapper maps this to `messages` and concat appends correctly.
+        scope.toolResultMessages = resultMessages.slice(messages.length);
+        scope.updatedLoopCount = (scope.currentLoopCount ?? 0) + 1;
+        // Write mutated decision as output so it flows through outputMapper.
+        // Always write when decisionRef exists — even if no decide() ran, the
+        // decision may need to propagate for the next iteration's InstructionsToLLM.
+        if (decisionRef) {
+            scope.updatedDecision = decisionRef;
+        }
+        // If ask_human was called, store pause data on scope and return it.
+        // Engine: non-void return from isPausable stage → PauseSignal with this as pauseData.
+        if (askHumanPause) {
+            scope.askHumanPause = askHumanPause;
+            return askHumanPause;
+        }
+        return undefined;
+    };
+    const resumeStageFn = (scope, humanResponse) => {
+        const pauseInfo = scope.askHumanPause;
+        if (pauseInfo && humanResponse !== undefined) {
+            const toolCallId = pauseInfo.toolCallId;
+            scope.toolResultMessages = (scope.toolResultMessages ?? []).map((msg) => msg.role === 'tool' && msg.toolCallId === toolCallId
+                ? { ...msg, content: String(humanResponse) }
+                : msg);
+        }
+    };
+    // Pausable root stage — flowChart() accepts PausableHandler directly (footprintjs v4.4.1+).
+    // Cast needed: executeStageFn has wider return type (includes pause data object)
+    // than PausableHandler.execute's generic — this is the standard pattern for stages
+    // that conditionally return pause data.
+    const handler = {
+        execute: executeStageFn,
+        resume: resumeStageFn,
+    };
+    return (0, footprintjs_1.flowChart)('ExecuteToolCalls', handler, 'execute-tool-calls', undefined, 'Execute tool calls and append results to conversation').build();
+}
+exports.buildToolExecutionSubflow = buildToolExecutionSubflow;
+//# sourceMappingURL=toolExecutionSubflow.js.map