agentfootprint 1.0.0

package/dist/compositions/withFallback.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * withFallback — wraps a primary RunnerLike with a fallback.
+ *
+ * If the primary runner throws, the fallback runner is called instead.
+ * Useful for degraded-mode patterns (e.g., expensive LLM → cheap LLM).
+ *
+ * Usage:
+ *   const safe = withFallback(gpt4Agent, gpt35Agent);
+ *   const result = await safe.run('Hello');
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withFallback = void 0;
+function withFallback(primary, fallback, options = {}) {
+    const { shouldFallback = () => true } = options;
+    return {
+        run: async (message, runOptions) => {
+            try {
+                return await primary.run(message, runOptions);
+            }
+            catch (err) {
+                if (!shouldFallback(err))
+                    throw err;
+                return fallback.run(message, runOptions);
+            }
+        },
+        // Narrative/snapshot from whichever runner succeeded
+        getNarrative: () => primary.getNarrative?.() ?? fallback.getNarrative?.() ?? [],
+        getSnapshot: () => primary.getSnapshot?.() ?? fallback.getSnapshot?.(),
+    };
+}
+exports.withFallback = withFallback;
+//# sourceMappingURL=withFallback.js.map

package/dist/compositions/withFallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"withFallback.js","sourceRoot":"","sources":["../../src/compositions/withFallback.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AASH,SAAgB,YAAY,CAC1B,OAAmB,EACnB,QAAoB,EACpB,UAA2B,EAAE;IAE7B,MAAM,EAAE,cAAc,GAAG,GAAG,EAAE,CAAC,IAAI,EAAE,GAAG,OAAO,CAAC;IAEhD,OAAO;QACL,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE;YACjC,IAAI,CAAC;gBACH,OAAO,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YAChD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC;oBAAE,MAAM,GAAG,CAAC;gBACpC,OAAO,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;QACD,qDAAqD;QACrD,YAAY,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,IAAI,QAAQ,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE;QAC/E,WAAW,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,IAAI,QAAQ,CAAC,WAAW,EAAE,EAAE;KACvE,CAAC;AACJ,CAAC;AApBD,oCAoBC"}

package/dist/compositions/withRetry.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * withRetry — wraps a RunnerLike with retry logic.
+ *
+ * On failure, retries up to maxRetries times with configurable backoff.
+ * Respects AbortSignal for cancellation during wait periods.
+ *
+ * Usage:
+ *   const reliable = withRetry(unreliableAgent, {
+ *     maxRetries: 3,
+ *     backoffMs: 1000,
+ *     backoffMultiplier: 2,
+ *   });
+ *   const result = await reliable.run('Hello');
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry = void 0;
+function withRetry(runner, options = {}) {
+    const { maxRetries = 3, backoffMs = 0, backoffMultiplier = 1, shouldRetry = () => true, } = options;
+    return {
+        run: async (message, runOptions) => {
+            let lastError;
+            let delay = backoffMs;
+            for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                try {
+                    return await runner.run(message, runOptions);
+                }
+                catch (err) {
+                    lastError = err;
+                    if (attempt >= maxRetries || !shouldRetry(err)) {
+                        break;
+                    }
+                    if (delay > 0) {
+                        await sleep(delay, runOptions?.signal);
+                        delay *= backoffMultiplier;
+                    }
+                }
+            }
+            throw lastError;
+        },
+        getNarrative: runner.getNarrative?.bind(runner),
+        getSnapshot: runner.getSnapshot?.bind(runner),
+    };
+}
+exports.withRetry = withRetry;
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason ?? new Error('Aborted'));
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            reject(signal.reason ?? new Error('Aborted'));
+        }, { once: true });
+    });
+}
+//# sourceMappingURL=withRetry.js.map

package/dist/compositions/withRetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"withRetry.js","sourceRoot":"","sources":["../../src/compositions/withRetry.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAeH,SAAgB,SAAS,CAAC,MAAkB,EAAE,UAAwB,EAAE;IACtE,MAAM,EACJ,UAAU,GAAG,CAAC,EACd,SAAS,GAAG,CAAC,EACb,iBAAiB,GAAG,CAAC,EACrB,WAAW,GAAG,GAAG,EAAE,CAAC,IAAI,GACzB,GAAG,OAAO,CAAC;IAEZ,OAAO;QACL,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE;YACjC,IAAI,SAAkB,CAAC;YACvB,IAAI,KAAK,GAAG,SAAS,CAAC;YAEtB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;gBACvD,IAAI,CAAC;oBACH,OAAO,MAAM,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;gBAC/C,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,SAAS,GAAG,GAAG,CAAC;oBAEhB,IAAI,OAAO,IAAI,UAAU,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;wBAC/C,MAAM;oBACR,CAAC;oBAED,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;wBACd,MAAM,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;wBACvC,KAAK,IAAI,iBAAiB,CAAC;oBAC7B,CAAC;gBACH,CAAC;YACH,CAAC;YAED,MAAM,SAAS,CAAC;QAClB,CAAC;QACD,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC;QAC/C,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC;KAC9C,CAAC;AACJ,CAAC;AAnCD,8BAmCC;AAED,SAAS,KAAK,CAAC,EAAU,EAAE,MAAoB;IAC7C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;YAC9C,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACtC,MAAM,EAAE,gBAAgB,CACtB,OAAO,EACP,GAAG,EAAE;YACH,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;QAChD,CAAC,EACD,EAAE,IAAI,EAAE,IAAI,EAAE,CACf,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/concepts/FlowChart.js

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * FlowChart — sequential composition of runners as a flowchart.
+ *
+ * The simplest multi-agent pattern: run agents in order, each feeding into the next.
+ * More complex patterns (fan-out, hierarchy, swarm) are user-built with footprintjs
+ * primitives (fork, addDeciderFunction, loopTo).
+ *
+ * Usage:
+ *   const composed = FlowChart.create()
+ *     .agent('researcher', 'Research', researchRunner)
+ *     .agent('writer', 'Write', writerRunner)
+ *     .build();
+ *   const result = await composed.run('Write about AI');
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowChartRunner = exports.FlowChart = void 0;
+const footprintjs_1 = require("footprintjs");
+const specIcons_1 = require("./specIcons");
+const runnerAsStage_1 = require("../stages/runnerAsStage");
+const RecorderBridge_1 = require("../recorders/v2/RecorderBridge");
+/**
+ * Check if a runner exposes its internal flowChart for subflow composition.
+ * Runners with `toFlowChart()` are mounted as subflows (enables UI drill-down).
+ * Runners without it fall back to `addFunction + runnerAsStage`.
+ */
+function hasToFlowChart(runner) {
+    return typeof runner.toFlowChart === 'function';
+}
+class FlowChart {
+    agents = [];
+    recorders = [];
+    constructor() { }
+    static create() {
+        return new FlowChart();
+    }
+    /** Add a runner to the flowchart. Runners execute in the order added. */
+    agent(id, name, runner, options) {
+        this.agents.push({
+            id,
+            name,
+            runner,
+            inputMapper: options?.inputMapper,
+            outputMapper: options?.outputMapper,
+        });
+        return this;
+    }
+    /** Attach an AgentRecorder to observe execution events. */
+    recorder(rec) {
+        this.recorders.push(rec);
+        return this;
+    }
+    /** Build the composed flowchart and return a runner. */
+    build() {
+        if (this.agents.length === 0) {
+            throw new Error('FlowChart requires at least one agent');
+        }
+        return new FlowChartRunner([...this.agents], [...this.recorders]);
+    }
+}
+exports.FlowChart = FlowChart;
+class FlowChartRunner {
+    agents;
+    recorders;
+    lastExecutor;
+    lastSpec;
+    constructor(agents, recorders = []) {
+        this.agents = agents;
+        this.recorders = recorders;
+    }
+    async run(message, options) {
+        const startTime = Date.now();
+        const bridge = this.recorders.length > 0 ? new RecorderBridge_1.RecorderBridge(this.recorders) : null;
+        bridge?.dispatchTurnStart(message);
+        // Seed stage: set input and initialize agent results.
+        // Signal/timeout are passed via executor.run({ signal, timeoutMs }) and
+        // available to stages via scope.$getEnv() — no need to duplicate in scope state.
+        const seedStage = (scope) => {
+            scope.pipelineInput = message;
+            scope.agentResults = [];
+        };
+        // Build flowchart: Seed → Runner1 → Runner2 → ... → RunnerN
+        // Runners with toFlowChart() are mounted as subflows (UI drill-down).
+        // Runners without it fall back to addFunction + runnerAsStage.
+        let builder = (0, footprintjs_1.flowChart)('Seed', seedStage, 'seed');
+        for (const agentConfig of this.agents) {
+            if (hasToFlowChart(agentConfig.runner)) {
+                // Mount as subflow — enables snapshot drill-down via getSubtreeSnapshot.
+                // No outputMapper — results are extracted from subflowResults after execution.
+                builder = builder.addSubFlowChartNext(agentConfig.id, agentConfig.runner.toFlowChart(), agentConfig.name, {
+                    inputMapper: (parentState) => {
+                        const input = agentConfig.inputMapper
+                            ? agentConfig.inputMapper(parentState)
+                            : parentState.result ??
+                                parentState.pipelineInput ??
+                                '';
+                        return { message: input };
+                    },
+                });
+            }
+            else {
+                // Fallback: wrap as a stage function
+                const stage = (0, runnerAsStage_1.runnerAsStage)(agentConfig);
+                builder = builder.addFunction(agentConfig.name, stage, agentConfig.id);
+            }
+        }
+        this.lastSpec = (0, specIcons_1.annotateSpecIcons)(builder.toSpec());
+        const chart = builder.build();
+        const executor = new footprintjs_1.FlowChartExecutor(chart, { enrichSnapshots: true });
+        executor.enableNarrative();
+        executor.attachRecorder(new footprintjs_1.MetricRecorder('metrics'));
+        try {
+            await executor.run({
+                input: { message },
+                signal: options?.signal,
+                timeoutMs: options?.timeoutMs,
+            });
+        }
+        catch (err) {
+            bridge?.dispatchError('llm', err);
+            throw err;
+        }
+        this.lastExecutor = executor;
+        // Extract results from snapshot.
+        // For subflow-mounted agents, read from subflowResults (child shared state).
+        // For flat-stage agents, read from parent's agentResults.
+        const snapshot = executor.getSnapshot();
+        const state = snapshot?.sharedState ?? {};
+        const subflowResults = snapshot?.subflowResults ?? {};
+        const flatAgentResults = state.agentResults ?? [];
+        const subflowAgentResults = [];
+        for (const agentConfig of this.agents) {
+            const sfResult = subflowResults[agentConfig.id];
+            if (sfResult) {
+                const childState = sfResult.treeContext
+                    ?.globalContext;
+                const childContent = childState ? childState.result ?? '' : '';
+                subflowAgentResults.push({
+                    id: agentConfig.id,
+                    name: agentConfig.name,
+                    content: childContent,
+                    latencyMs: 0, // Individual subflow timing not available from SubflowResult
+                });
+            }
+        }
+        const allAgentResults = [...flatAgentResults, ...subflowAgentResults];
+        const lastSubflowContent = subflowAgentResults.length > 0
+            ? subflowAgentResults[subflowAgentResults.length - 1].content
+            : undefined;
+        const content = state.result ??
+            lastSubflowContent ??
+            (flatAgentResults.length > 0 ? flatAgentResults[flatAgentResults.length - 1].content : '');
+        bridge?.dispatchTurnComplete(content, 0);
+        return {
+            content,
+            agents: allAgentResults,
+            totalLatencyMs: Date.now() - startTime,
+        };
+    }
+    /** Get the flowchart spec (stage graph metadata). */
+    getSpec() {
+        if (!this.lastSpec) {
+            // Build chart structure to capture spec without executing
+            const seedStage = (scope) => {
+                scope.pipelineInput = '';
+                scope.agentResults = [];
+            };
+            let builder = (0, footprintjs_1.flowChart)('Seed', seedStage, 'seed');
+            for (const agentConfig of this.agents) {
+                if (hasToFlowChart(agentConfig.runner)) {
+                    builder = builder.addSubFlowChartNext(agentConfig.id, agentConfig.runner.toFlowChart(), agentConfig.name, {
+                        inputMapper: (parentState) => {
+                            const input = agentConfig.inputMapper
+                                ? agentConfig.inputMapper(parentState)
+                                : parentState.result ??
+                                    parentState.pipelineInput ??
+                                    '';
+                            return { message: input };
+                        },
+                    });
+                }
+                else {
+                    const stage = (0, runnerAsStage_1.runnerAsStage)(agentConfig);
+                    builder = builder.addFunction(agentConfig.name, stage, agentConfig.id);
+                }
+            }
+            this.lastSpec = (0, specIcons_1.annotateSpecIcons)(builder.toSpec());
+        }
+        return this.lastSpec;
+    }
+    /** Get the narrative from the last run. */
+    getNarrative() {
+        return this.lastExecutor?.getNarrative() ?? [];
+    }
+    /** Get structured narrative entries from the last run. */
+    getNarrativeEntries() {
+        return this.lastExecutor?.getNarrativeEntries() ?? [];
+    }
+    /** Get the full execution snapshot from the last run. */
+    getSnapshot() {
+        return this.lastExecutor?.getSnapshot();
+    }
+}
+exports.FlowChartRunner = FlowChartRunner;
+//# sourceMappingURL=FlowChart.js.map

package/dist/concepts/FlowChart.js.map

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

package/dist/concepts/LLMCall.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * LLMCall — simplest concept: single LLM call, no tools, no loop.
+ *
+ * Flowchart: SystemPrompt → Messages → CallLLM → ParseResponse → Finalize
+ *
+ * Usage:
+ *   const caller = LLMCall.create({ provider: mock([{ content: 'Hi!' }]) })
+ *     .system('You are helpful.')
+ *     .build();
+ *   const result = await caller.run('Hello');
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMCallRunner = exports.LLMCall = void 0;
+const footprintjs_1 = require("footprintjs");
+const specIcons_1 = require("./specIcons");
+const content_1 = require("../types/content");
+const types_1 = require("../types");
+const callLLM_1 = require("../stages/callLLM");
+const parseResponse_1 = require("../stages/parseResponse");
+const finalize_1 = require("../stages/finalize");
+const memory_1 = require("../memory");
+const RecorderBridge_1 = require("../recorders/v2/RecorderBridge");
+const createProvider_1 = require("../adapters/createProvider");
+class LLMCall {
+    provider;
+    sysPrompt;
+    recorders = [];
+    enableStreaming = false;
+    constructor(options) {
+        this.provider = (0, createProvider_1.resolveProvider)(options.provider);
+    }
+    static create(options) {
+        return new LLMCall(options);
+    }
+    system(prompt) {
+        this.sysPrompt = prompt;
+        return this;
+    }
+    streaming(enabled) {
+        this.enableStreaming = enabled;
+        return this;
+    }
+    /** Attach an AgentRecorder to observe execution events. */
+    recorder(rec) {
+        this.recorders.push(rec);
+        return this;
+    }
+    build() {
+        return new LLMCallRunner(this.provider, this.sysPrompt, [...this.recorders], this.enableStreaming);
+    }
+}
+exports.LLMCall = LLMCall;
+class LLMCallRunner {
+    provider;
+    sysPrompt;
+    recorders;
+    streamingEnabled;
+    lastExecutor;
+    lastSpec;
+    constructor(provider, sysPrompt, recorders = [], streaming = false) {
+        this.provider = provider;
+        this.sysPrompt = sysPrompt;
+        this.recorders = recorders;
+        this.streamingEnabled = streaming;
+    }
+    /** Expose the internal flowChart for subflow composition. */
+    toFlowChart() {
+        return this.buildChart('');
+    }
+    async run(message, options) {
+        const chart = this.buildChart(message);
+        const bridge = this.recorders.length > 0 ? new RecorderBridge_1.RecorderBridge(this.recorders) : null;
+        bridge?.dispatchTurnStart(message);
+        const executorOpts = { enrichSnapshots: true };
+        if (options?.onToken && this.streamingEnabled) {
+            executorOpts.streamHandlers = {
+                onToken: (_streamId, token) => options.onToken(token),
+                onStart: () => { },
+                onEnd: () => { },
+            };
+        }
+        const executor = new footprintjs_1.FlowChartExecutor(chart, executorOpts);
+        executor.enableNarrative();
+        executor.attachRecorder(new footprintjs_1.MetricRecorder('metrics'));
+        const startMs = Date.now();
+        try {
+            await executor.run({
+                input: { message },
+                signal: options?.signal,
+                timeoutMs: options?.timeoutMs,
+            });
+        }
+        catch (err) {
+            bridge?.dispatchError('llm', err);
+            throw err;
+        }
+        this.lastExecutor = executor;
+        const snapshot = executor.getSnapshot();
+        const state = snapshot?.sharedState ?? {};
+        const messages = state.messages ?? [];
+        const lastAsst = (0, memory_1.lastAssistantMessage)(messages);
+        const content = state.result ?? (lastAsst ? (0, content_1.getTextContent)(lastAsst.content) : '');
+        // Dispatch LLM call event from the adapter response stored in scope
+        if (bridge) {
+            const response = state.adapterRawResponse;
+            if (response) {
+                bridge.dispatchLLMCall(response, Date.now() - startMs);
+            }
+            bridge.dispatchTurnComplete(content, messages.length);
+        }
+        return { content, messages };
+    }
+    buildChart(message) {
+        const sysPrompt = this.sysPrompt;
+        // API slot: SystemPrompt — set the system instruction
+        const systemPromptStage = (scope) => {
+            if (sysPrompt) {
+                scope.systemPrompt = sysPrompt;
+            }
+        };
+        // API slot: Messages — prepare the conversation messages
+        const messagesStage = (scope) => {
+            const msgs = [];
+            const sp = scope.systemPrompt;
+            if (sp)
+                msgs.push((0, types_1.systemMessage)(sp));
+            msgs.push((0, types_1.userMessage)(message));
+            scope.messages = msgs;
+        };
+        const callLLM = (0, callLLM_1.createCallLLMStage)(this.provider);
+        let builder = (0, footprintjs_1.flowChart)('SystemPrompt', systemPromptStage, 'system-prompt')
+            .addFunction('Messages', messagesStage, 'messages');
+        if (this.streamingEnabled) {
+            builder = builder.addStreamingFunction('CallLLM', callLLM, 'call-llm', 'llm-stream');
+        }
+        else {
+            builder = builder.addFunction('CallLLM', callLLM, 'call-llm');
+        }
+        builder = builder
+            .addFunction('ParseResponse', parseResponse_1.parseResponseStage, 'parse')
+            .addFunction('Finalize', finalize_1.finalizeStage, 'finalize');
+        this.lastSpec = (0, specIcons_1.annotateSpecIcons)(builder.toSpec());
+        return builder.build();
+    }
+    getSpec() {
+        if (!this.lastSpec) {
+            this.buildChart('');
+        }
+        return this.lastSpec;
+    }
+    getNarrative() {
+        return this.lastExecutor?.getNarrative() ?? [];
+    }
+    getSnapshot() {
+        return this.lastExecutor?.getSnapshot();
+    }
+}
+exports.LLMCallRunner = LLMCallRunner;
+//# sourceMappingURL=LLMCall.js.map

package/dist/concepts/LLMCall.js.map

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