agentfootprint 1.0.0

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

@@ -0,0 +1,103 @@
+/**
+ * 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
+ */
+import { normalizeAdapterResponse } from './helpers';
+/**
+ * Create a streaming-capable CallLLM stage function.
+ */
+export 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 = 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 = normalizeAdapterResponse(response);
+        onStreamEvent?.({
+            type: 'llm_end',
+            iteration,
+            toolCallCount: response.toolCalls?.length ?? 0,
+            content: response.content,
+            model: response.model,
+            latencyMs: Date.now() - startMs,
+        });
+    };
+}
+//# sourceMappingURL=streamingCallLLMStage.js.map

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

@@ -0,0 +1,87 @@
+/**
+ * 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.
+ */
+import { flowChart } from 'footprintjs';
+import { executeToolCalls } from './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.
+ */
+export 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 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 flowChart('ExecuteToolCalls', handler, 'execute-tool-calls', undefined, 'Execute tool calls and append results to conversation').build();
+}
+//# sourceMappingURL=toolExecutionSubflow.js.map

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

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

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

@@ -0,0 +1,10 @@
+/**
+ * Call module types.
+ *
+ * The call module contains the three stages that happen AFTER the three API slots:
+ *   CallLLM → ParseResponse → HandleResponse
+ *
+ * These stages consume what the slots wrote to scope and produce the LLM result.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/lib/call/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/esm/lib/concepts/Agent.js

@@ -0,0 +1,7 @@
+/**
+ * Agent — re-exports builder and runner from split files.
+ * Preserves backward compatibility for imports.
+ */
+export { Agent } from './AgentBuilder';
+export { AgentRunner } from './AgentRunner';
+//# sourceMappingURL=Agent.js.map

package/dist/esm/lib/concepts/Agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Agent.js","sourceRoot":"","sources":["../../../../src/lib/concepts/Agent.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEvC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/esm/lib/concepts/AgentBuilder.js

@@ -0,0 +1,224 @@
+/**
+ * Agent builder — fluent API for configuring an agent.
+ *
+ * Usage:
+ *   const agent = Agent.create({ provider })
+ *     .system('You are helpful.')
+ *     .tool(searchTool)
+ *     .build();
+ */
+import { resolveProvider } from '../../adapters/createProvider';
+import { zodToJsonSchema, isZodSchema } from '../../tools/zodToJsonSchema';
+import { ToolRegistry } from '../../tools';
+import { AgentPattern } from '../loop';
+import { AgentRunner } from './AgentRunner';
+export class Agent {
+    provider;
+    agentName;
+    systemPromptText;
+    customPromptProvider;
+    registry = new ToolRegistry();
+    customToolProvider;
+    maxIter = 10;
+    recorders = [];
+    memoryConfig;
+    agentPattern = AgentPattern.Regular;
+    overrides = new Map();
+    agentInstructions = [];
+    initialDecisionScope;
+    enableStreaming = false;
+    enableVerboseNarrative = false;
+    outputResponseFormat;
+    constructor(options) {
+        this.provider = resolveProvider(options.provider);
+        this.agentName = options.name ?? 'agent';
+    }
+    /**
+     * Create an agent builder.
+     *
+     * Accepts either an LLMProvider or a ModelConfig from factory functions:
+     * ```ts
+     * // With ModelConfig (auto-resolved)
+     * Agent.create({ provider: anthropic('claude-sonnet-4-20250514') })
+     *
+     * // With LLMProvider (direct)
+     * Agent.create({ provider: new AnthropicAdapter({ model: '...' }) })
+     * ```
+     */
+    static create(options) {
+        return new Agent(options);
+    }
+    /** Set system prompt (static — same every iteration). */
+    system(prompt) {
+        this.systemPromptText = prompt;
+        return this;
+    }
+    /**
+     * Set a custom prompt provider (dynamic — can change each iteration).
+     * Overrides `.system()`.
+     */
+    promptProvider(provider) {
+        this.customPromptProvider = provider;
+        return this;
+    }
+    /** Register a tool. */
+    tool(toolDef) {
+        this.registry.register(toolDef);
+        return this;
+    }
+    /** Register multiple tools. */
+    tools(toolDefs) {
+        for (const t of toolDefs)
+            this.registry.register(t);
+        return this;
+    }
+    /**
+     * Set a custom tool provider (dynamic — can change each iteration).
+     * Overrides `.tool()` / `.tools()`.
+     */
+    toolProvider(provider) {
+        this.customToolProvider = provider;
+        return this;
+    }
+    /** Set max ReAct loop iterations. */
+    maxIterations(n) {
+        this.maxIter = n;
+        return this;
+    }
+    /** Enable streaming — tokens emitted incrementally via onToken callback. */
+    streaming(enabled = true) {
+        this.enableStreaming = enabled;
+        return this;
+    }
+    /**
+     * Enable verbose narrative — full values, no truncation.
+     * Shows complete system prompts, tool results, and LLM outputs in the narrative.
+     * Enables grounding analysis via getGroundingSources() / getLLMClaims().
+     */
+    verbose(enabled = true) {
+        this.enableVerboseNarrative = enabled;
+        return this;
+    }
+    /**
+     * Request structured JSON output matching a schema.
+     * Accepts JSON Schema or Zod schema (auto-converted).
+     *
+     * @param schema - JSON Schema object or Zod schema
+     * @param options - Optional: name for the schema, injection position for non-native providers
+     *
+     * @example
+     * ```ts
+     * // JSON Schema
+     * agent.outputSchema({ type: 'object', properties: { city: { type: 'string' } } })
+     *
+     * // Zod schema
+     * agent.outputSchema(z.object({ city: z.string() }))
+     *
+     * // Inject in user message (recency window) instead of system prompt
+     * agent.outputSchema(z.object({ city: z.string() }), { injection: 'user' })
+     * ```
+     */
+    outputSchema(schema, options) {
+        if (isZodSchema(schema)) {
+            schema = zodToJsonSchema(schema);
+        }
+        this.outputResponseFormat = {
+            type: 'json_schema',
+            schema,
+            name: options?.name,
+            injection: options?.injection,
+        };
+        return this;
+    }
+    /**
+     * Set the agent loop pattern.
+     * - `AgentPattern.Regular` (default): slots resolve once
+     * - `AgentPattern.Dynamic`: all slots re-evaluate each iteration
+     */
+    pattern(p) {
+        this.agentPattern = p;
+        return this;
+    }
+    /**
+     * Override instructions on a shared tool without modifying the tool definition.
+     */
+    instructionOverride(toolId, override) {
+        this.overrides.set(toolId, override);
+        return this;
+    }
+    /**
+     * Register an agent-level instruction.
+     * Instructions inject into system prompt, tools, and tool-result processing
+     * based on the Decision Scope state.
+     *
+     * @example
+     * ```typescript
+     * Agent.create({ provider })
+     *   .instruction(defineInstruction({
+     *     id: 'refund',
+     *     activeWhen: (d) => d.orderStatus === 'denied',
+     *     prompt: 'Be empathetic.',
+     *   }))
+     *   .build();
+     * ```
+     */
+    instruction(instr) {
+        this.agentInstructions.push(instr);
+        return this;
+    }
+    /** Register multiple agent-level instructions. */
+    instructions(instrs) {
+        for (const i of instrs)
+            this.agentInstructions.push(i);
+        return this;
+    }
+    /**
+     * Set the initial Decision Scope values.
+     * Tool handlers update these values; InstructionsToLLM reads them
+     * to evaluate `activeWhen` predicates.
+     *
+     * @example
+     * ```typescript
+     * Agent.create({ provider })
+     *   .decision<MyDecision>({ orderStatus: null, riskLevel: 'unknown' })
+     *   .instruction(refundInstruction)
+     *   .build();
+     * ```
+     */
+    decision(scope) {
+        this.initialDecisionScope = scope;
+        return this;
+    }
+    /** Enable persistent conversation memory. */
+    memory(config) {
+        this.memoryConfig = config;
+        return this;
+    }
+    /** Attach an AgentRecorder to observe execution events. */
+    recorder(rec) {
+        this.recorders.push(rec);
+        return this;
+    }
+    /** Build the agent and return a runner. */
+    build() {
+        return new AgentRunner({
+            provider: this.provider,
+            name: this.agentName,
+            systemPromptText: this.systemPromptText,
+            registry: this.registry,
+            maxIterations: this.maxIter,
+            recorders: [...this.recorders],
+            memoryConfig: this.memoryConfig,
+            pattern: this.agentPattern,
+            promptProvider: this.customPromptProvider,
+            toolProvider: this.customToolProvider,
+            instructionOverrides: this.overrides.size > 0 ? new Map(this.overrides) : undefined,
+            agentInstructions: this.agentInstructions.length > 0 ? [...this.agentInstructions] : undefined,
+            initialDecision: this.agentInstructions.length > 0 ? this.initialDecisionScope : undefined,
+            streaming: this.enableStreaming,
+            verboseNarrative: this.enableVerboseNarrative,
+            responseFormat: this.outputResponseFormat,
+        });
+    }
+}
+//# sourceMappingURL=AgentBuilder.js.map

package/dist/esm/lib/concepts/AgentBuilder.js.map

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