agentfootprint 1.0.0

package/dist/esm/executor/agentLoop.js

@@ -0,0 +1,150 @@
+/**
+ * agentLoop — the core execution engine.
+ *
+ * Takes an AgentLoopConfig (providers + recorders + options) and executes
+ * a single turn of the agent loop:
+ *   1. Resolve system prompt (PromptProvider)
+ *   2. Prepare messages (MessageStrategy)
+ *   3. Call LLM
+ *   4. If tool calls → execute tools → loop to step 3
+ *   5. If final response → return result
+ *
+ * Built on footprintjs flowchart (SeedScope → Prompt → LLM → Parse → Handle → loop).
+ * All observation happens through AgentRecorders attached to the config.
+ *
+ * Usage:
+ *   const result = await agentLoop(config, 'Hello', { signal, timeoutMs });
+ */
+import { userMessage, assistantMessage, toolResultMessage, hasToolCalls } from '../types/messages';
+import { getTextContent } from '../types/content';
+// ── Engine ───────────────────────────────────────────────────
+export async function agentLoop(config, message, options = {}) {
+    const { promptProvider, messageStrategy, toolProvider, llmProvider, maxIterations, recorders } = config;
+    const signal = options.signal;
+    const turnNumber = options.turnNumber ?? 0;
+    const history = [...(options.history ?? [])];
+    // Add user message
+    history.push(userMessage(message));
+    // Notify recorders: turn start
+    const startEvent = { turnNumber, message };
+    dispatchRecorderEvent(recorders, 'onTurnStart', startEvent);
+    try {
+        // 1. Resolve system prompt
+        const promptCtx = { message, turnNumber, history, signal };
+        const systemPrompt = await promptProvider.resolve(promptCtx);
+        let loopIteration = 0;
+        let finalContent = '';
+        while (loopIteration < maxIterations) {
+            checkAborted(signal);
+            // 2. Prepare messages
+            const messageCtx = { message, turnNumber, loopIteration, signal };
+            const messageDecision = await messageStrategy.prepare(history, messageCtx);
+            const preparedMessages = messageDecision.value;
+            // 3. Call LLM
+            const toolDecision = await toolProvider.resolve({
+                message,
+                turnNumber,
+                loopIteration,
+                messages: preparedMessages,
+                signal,
+            });
+            const toolDescriptions = toolDecision.value;
+            const llmStart = Date.now();
+            const llmResponse = await llmProvider.chat(preparedMessages, {
+                tools: toolDescriptions.length > 0 ? toolDescriptions : undefined,
+                signal,
+                ...(systemPrompt ? {} : {}),
+            });
+            const llmLatency = Date.now() - llmStart;
+            // Notify recorders: LLM call
+            const llmEvent = {
+                model: undefined,
+                usage: llmResponse.usage,
+                latencyMs: llmLatency,
+                turnNumber,
+                loopIteration,
+                finishReason: llmResponse.finishReason,
+            };
+            dispatchRecorderEvent(recorders, 'onLLMCall', llmEvent);
+            loopIteration++;
+            // Add assistant message to history
+            const assistantContent = getTextContent(llmResponse.content);
+            const assistantMsg = assistantMessage(assistantContent, llmResponse.toolCalls);
+            history.push(assistantMsg);
+            // 4. Check for tool calls
+            if (hasToolCalls(assistantMsg) && assistantMsg.toolCalls.length > 0) {
+                // Execute each tool call
+                for (const toolCall of assistantMsg.toolCalls) {
+                    checkAborted(signal);
+                    const toolStart = Date.now();
+                    let toolResult;
+                    if (toolProvider.execute) {
+                        toolResult = await toolProvider.execute(toolCall, signal);
+                    }
+                    else {
+                        toolResult = { content: `No executor for tool: ${toolCall.name}`, error: true };
+                    }
+                    const toolLatency = Date.now() - toolStart;
+                    // Notify recorders: tool call
+                    const toolEvent = {
+                        toolName: toolCall.name,
+                        args: toolCall.arguments,
+                        result: toolResult,
+                        latencyMs: toolLatency,
+                    };
+                    dispatchRecorderEvent(recorders, 'onToolCall', toolEvent);
+                    // Add tool result to history
+                    history.push(toolResultMessage(toolResult.content, toolCall.id));
+                }
+                // Continue loop — LLM needs to process tool results
+                continue;
+            }
+            // 5. Final response — no tool calls
+            finalContent = assistantContent;
+            break;
+        }
+        // Notify recorders: turn complete
+        const completeEvent = {
+            turnNumber,
+            messageCount: history.length,
+            totalLoopIterations: loopIteration,
+            content: finalContent,
+        };
+        dispatchRecorderEvent(recorders, 'onTurnComplete', completeEvent);
+        return {
+            content: finalContent,
+            messages: history,
+            loopIterations: loopIteration,
+        };
+    }
+    catch (err) {
+        // Notify recorders: error
+        const errorEvent = {
+            phase: 'llm',
+            error: err,
+            turnNumber,
+        };
+        dispatchRecorderEvent(recorders, 'onError', errorEvent);
+        throw err;
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────
+function checkAborted(signal) {
+    if (signal?.aborted) {
+        throw signal.reason ?? new Error('Aborted');
+    }
+}
+function dispatchRecorderEvent(recorders, hook, event) {
+    for (const recorder of recorders) {
+        try {
+            const fn = recorder[hook];
+            if (typeof fn === 'function') {
+                fn.call(recorder, event);
+            }
+        }
+        catch {
+            // Error isolation
+        }
+    }
+}
+//# sourceMappingURL=agentLoop.js.map

package/dist/esm/executor/agentLoop.js.map

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

package/dist/esm/executor/index.js

@@ -0,0 +1,5 @@
+/**
+ * executor/ — The agentLoop execution engine.
+ */
+export { agentLoop } from './agentLoop';
+//# sourceMappingURL=index.js.map

package/dist/esm/executor/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/executor/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/esm/explain.barrel.js

@@ -0,0 +1,19 @@
+/**
+ * agentfootprint/explain — Understand agent decisions.
+ *
+ * Extract grounding sources (tool results) and LLM claims for hallucination detection.
+ * Verbose narrative mode for full values. AgentScopeKey enum for type-safe queries.
+ *
+ * @example
+ * ```typescript
+ * import { getGroundingSources, getLLMClaims } from 'agentfootprint/explain';
+ *
+ * const entries = agent.getNarrativeEntries();
+ * const sources = getGroundingSources(entries);  // what tools returned
+ * const claims = getLLMClaims(entries);           // what the LLM said
+ * ```
+ */
+export { getGroundingSources, getLLMClaims, getFullLLMContext, createAgentRenderer } from './lib/narrative';
+// ExplainRecorder — collect grounding data during traversal (no post-processing)
+export { ExplainRecorder } from './recorders/v2/ExplainRecorder';
+//# sourceMappingURL=explain.barrel.js.map

package/dist/esm/explain.barrel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.barrel.js","sourceRoot":"","sources":["../../src/explain.barrel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAG5G,iFAAiF;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,29 @@
+/**
+ * agentfootprint — The explainable agent framework.
+ *
+ * Core: builders, tools, providers, messages, types.
+ *
+ * Focused capabilities (also importable from subpaths):
+ *   agentfootprint/instructions  → Conditional context injection
+ *   agentfootprint/observe       → Monitor execution (recorders)
+ *   agentfootprint/resilience    → Retry, fallback, circuit breaker
+ *   agentfootprint/security      → Tool gating, permissions
+ *   agentfootprint/explain       → Narrative, grounding analysis
+ *   agentfootprint/stream        → Real-time lifecycle events
+ */
+// ── Concepts (Builders + Runners) ───────────────────────────
+export { Agent, AgentRunner, LLMCall, LLMCallRunner, RAG, RAGRunner, FlowChart, FlowChartRunner, Swarm, SwarmRunner, Parallel, ParallelRunner, } from './concepts';
+// ── Tools ───────────────────────────────────────────────────
+export { defineTool, askHuman, ToolRegistry } from './tools';
+// ── Providers (core — you can't build an agent without these) ─
+export { mock, MockAdapter, mockRetriever, MockRetriever, createProvider } from './adapters';
+export { anthropic, openai, ollama, bedrock } from './models';
+export { AnthropicAdapter, OpenAIAdapter, BedrockAdapter } from './adapters';
+export { BrowserAnthropicAdapter, BrowserOpenAIAdapter } from './adapters';
+export { InMemoryStore } from './adapters/memory/inMemory';
+export { redisStore, dynamoStore, postgresStore } from './adapters/memory/stores';
+// ── Messages + Content ──────────────────────────────────────
+export { systemMessage, userMessage, assistantMessage, toolResultMessage, textBlock, imageBlock, base64Image, urlImage, } from './types';
+// ── Errors ──────────────────────────────────────────────────
+export { LLMError } from './types';
+//# sourceMappingURL=index.js.map

package/dist/esm/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,OAAO,EACL,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,aAAa,EACtB,GAAG,EAAE,SAAS,EACd,SAAS,EAAE,eAAe,EAC1B,KAAK,EAAE,WAAW,EAClB,QAAQ,EAAE,cAAc,GACzB,MAAM,YAAY,CAAC;AAEpB,+DAA+D;AAC/D,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE7D,iEAAiE;AACjE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7F,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAalF,+DAA+D;AAC/D,OAAO,EACL,aAAa,EAAE,WAAW,EAAE,gBAAgB,EAAE,iBAAiB,EAC/D,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,GAC7C,MAAM,SAAS,CAAC;AAEjB,+DAA+D;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC"}

package/dist/esm/instructions.barrel.js

@@ -0,0 +1,22 @@
+/**
+ * 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],
+ * });
+ * ```
+ */
+export { defineInstruction, follow, quickBind } from './lib/instructions';
+export { AgentPattern } from './lib/loop';
+export { InstructionRecorder } from './lib/instructions';
+//# sourceMappingURL=instructions.barrel.js.map

package/dist/esm/instructions.barrel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.barrel.js","sourceRoot":"","sources":["../../src/instructions.barrel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAS1E,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC"}

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

@@ -0,0 +1,64 @@
+/**
+ * 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 }
+ */
+import { normalizeAdapterResponse } from './helpers';
+/**
+ * Create the CallLLM stage function.
+ */
+export 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 = 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,
+        });
+    };
+}
+//# sourceMappingURL=callLLMStage.js.map

package/dist/esm/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,OAAO,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAOrD;;GAEG;AACH,MAAM,UAAU,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,wBAAwB,CAAC,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"}

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

@@ -0,0 +1,49 @@
+/**
+ * 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)
+ */
+import { getTextContent } from '../../types/content';
+import { lastAssistantMessage } from '../../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.
+ */
+export 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 = lastAssistantMessage(messages);
+        scope.result = lastAsst ? getTextContent(lastAsst.content) : '';
+        if (useCommitFlag) {
+            scope.memory_shouldCommit = true;
+        }
+        else {
+            scope.$break();
+        }
+    };
+}
+//# sourceMappingURL=handleResponseStage.js.map

package/dist/esm/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,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAUpD;;;;;;GAMG;AACH,MAAM,UAAU,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,oBAAoB,CAAC,QAAQ,CAAC,CAAC;QAChD,KAAK,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,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"}

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

@@ -0,0 +1,164 @@
+/**
+ * Shared helpers for call module stages.
+ */
+import { toolResultMessage } from '../../types';
+import { isAskHumanResult } from '../../tools/askHuman';
+import { validateToolInput, formatValidationErrors } from '../../tools/validateInput';
+import { processInstructions } from '../instructions';
+/**
+ * Normalize an LLMResponse into an AdapterResult discriminated union.
+ */
+export 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,
+    };
+}
+export 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 = validateToolInput(toolArgs, tool.inputSchema);
+                    if (!validation.valid) {
+                        errorInfo = { code: 'INVALID_INPUT', message: `Invalid arguments for '${tool.id}': ${formatValidationErrors(validation.errors)}` };
+                        resultContent = JSON.stringify({ error: true, message: errorInfo.message });
+                        result.push(toolResultMessage(resultContent, toolCall.id));
+                        continue;
+                    }
+                }
+                try {
+                    const execResult = await tool.handler(toolArgs);
+                    resultContent = execResult.content;
+                    // Check for ask_human pause marker
+                    if (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 = 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(toolResultMessage(resultContent, toolCall.id));
+    }
+    return { messages: result, askHumanPause };
+}
+//# sourceMappingURL=helpers.js.map

package/dist/esm/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/esm/lib/call/index.js

@@ -0,0 +1,7 @@
+export { createCallLLMStage } from './callLLMStage';
+export { createStreamingCallLLMStage } from './streamingCallLLMStage';
+export { parseResponseStage } from './parseResponseStage';
+export { createHandleResponseStage } from './handleResponseStage';
+export { buildToolExecutionSubflow } from './toolExecutionSubflow';
+export { normalizeAdapterResponse, executeToolCalls } from './helpers';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/call/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAElE,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AAEnE,OAAO,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC"}

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

@@ -0,0 +1,48 @@
+/**
+ * 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)
+ */
+import { assistantMessage } from '../../types';
+import { appendMessage } from '../../memory';
+/**
+ * ParseResponse stage function.
+ * Stateless — no factory needed.
+ */
+export 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 = assistantMessage(result.content, result.type === 'tools' ? result.toolCalls : undefined);
+    scope.messages = 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}"`;
+    }
+}
+//# sourceMappingURL=parseResponseStage.js.map

package/dist/esm/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,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C;;;GAGG;AACH,MAAM,UAAU,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,gBAAgB,CAC9B,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,aAAa,CAAC,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"}