agentfootprint 1.0.0

package/dist/stages/commitMemory.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * CommitMemory stage — persist conversation history after the turn completes.
+ *
+ * Behavior:
+ *   - Reads `memory_shouldCommit` flag set by HandleResponse when the turn finalizes.
+ *   - If true: fires `store.save(conversationId, messages)` as a non-blocking Promise
+ *     (fire-and-forget), then calls scope.$break() so the loop ends.
+ *   - If false (tool-call turn still in progress): no-op — loop continues normally.
+ *
+ * Fire-and-forget rationale:
+ *   The caller receives the agent result immediately, without waiting for the DB write
+ *   to complete. This matches the design goal of LangGraph vs agentfootprint: LangGraph
+ *   blocks on its checkpointer; agentfootprint commits in parallel. Save errors are
+ *   caught internally and surfaced via the provided `onSaveError` callback (if any).
+ *
+ *   Dev-mode: if `onSaveError` is omitted and save() fails, a console.warn is emitted in
+ *   non-production environments so silent storage failures surface during development.
+ *
+ * Placement in the chart:
+ *   CommitMemory is placed BEFORE `loopTo('call-llm')`. On tool-call turns it
+ *   passes through (shouldCommit=false). On final turns it saves + breaks.
+ *   This means every loop pass checks whether the turn is done.
+ *
+ * Example:
+ *   SeedScope → PrepareMemory → ... → HandleResponse → CommitMemory → loopTo(CallLLM)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCommitMemoryStage = void 0;
+const isDevMode = () => process.env['NODE_ENV'] !== 'production';
+/**
+ * Build the CommitMemory stage function.
+ *
+ * Usage:
+ * ```typescript
+ * .addFunction('CommitMemory', createCommitMemoryStage(config), 'commit-memory')
+ * .loopTo('call-llm')
+ * ```
+ */
+function createCommitMemoryStage(config) {
+    return async (scope) => {
+        const shouldCommit = scope.memory_shouldCommit === true;
+        if (!shouldCommit) {
+            // Tool-call turn — loop continues, nothing to save yet
+            return;
+        }
+        // Reconstruct the full conversation history for storage.
+        //
+        // When a sliding window strategy is active, `messages` in scope contains only
+        // the windowed context + new LLM messages — the oldest turns were trimmed.
+        // We detect this by comparing storedHistory.length vs preparedMessages.length:
+        // if they differ, windowing occurred and we must rebuild from storedHistory.
+        //
+        // Full history = storedHistory (pre-LLM, includes new user message)
+        //              + newLLMMessages (messages appended by CallLLM/ParseResponse)
+        //
+        // PromptAssembly may inject a system message at position 0 when the windowed
+        // prepared context doesn't start with one. We account for that 1-message offset.
+        const messages = scope.messages ?? [];
+        const storedHistory = scope.memory_storedHistory ?? [];
+        const prepared = scope.memory_preparedMessages ?? [];
+        let toSave;
+        if (storedHistory.length > 0 && prepared.length < storedHistory.length) {
+            // Windowing trimmed the history — reconstruct: storedHistory + newLLMMessages.
+            const systemInjected = messages.length > 0 &&
+                messages[0].role === 'system' &&
+                (prepared.length === 0 || prepared[0].role !== 'system');
+            const preparedEnd = systemInjected ? prepared.length + 1 : prepared.length;
+            const newLLMMessages = messages.slice(preparedEnd);
+            toSave = [...storedHistory, ...newLLMMessages];
+        }
+        else {
+            // No windowing — messages array is the complete history.
+            toSave = messages;
+        }
+        // Fire-and-forget: don't await the save — caller gets result immediately.
+        // Use instanceof check to avoid allocating a Promise for synchronous save() returns.
+        const saveResult = config.store.save(config.conversationId, toSave);
+        if (saveResult instanceof Promise) {
+            saveResult.catch((error) => {
+                if (config.onSaveError) {
+                    config.onSaveError(error);
+                }
+                else if (isDevMode()) {
+                    // eslint-disable-next-line no-console
+                    console.warn('[agentfootprint] CommitMemory: store.save() failed and no onSaveError handler was provided.', error);
+                }
+            });
+        }
+        // Break the loop first — this is the real termination signal.
+        scope.$break();
+        // Reset the flag after breaking so CommitMemory is a no-op on any future loop
+        // passes (defensive — $break() already ends the loop).
+        scope.memory_shouldCommit = false;
+    };
+}
+exports.createCommitMemoryStage = createCommitMemoryStage;
+//# sourceMappingURL=commitMemory.js.map

package/dist/stages/commitMemory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commitMemory.js","sourceRoot":"","sources":["../../src/stages/commitMemory.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAkBH,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,YAAY,CAAC;AAEjE;;;;;;;;GAQG;AACH,SAAgB,uBAAuB,CAAC,MAA0B;IAChE,OAAO,KAAK,EAAE,KAAiC,EAAE,EAAE;QACjD,MAAM,YAAY,GAAG,KAAK,CAAC,mBAAmB,KAAK,IAAI,CAAC;QAExD,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,uDAAuD;YACvD,OAAO;QACT,CAAC;QAED,yDAAyD;QACzD,EAAE;QACF,8EAA8E;QAC9E,2EAA2E;QAC3E,+EAA+E;QAC/E,6EAA6E;QAC7E,EAAE;QACF,oEAAoE;QACpE,6EAA6E;QAC7E,EAAE;QACF,6EAA6E;QAC7E,iFAAiF;QACjF,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;QACtC,MAAM,aAAa,GAAG,KAAK,CAAC,oBAAoB,IAAI,EAAE,CAAC;QACvD,MAAM,QAAQ,GAAG,KAAK,CAAC,uBAAuB,IAAI,EAAE,CAAC;QAErD,IAAI,MAAuB,CAAC;QAC5B,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,MAAM,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC;YACvE,+EAA+E;YAC/E,MAAM,cAAc,GAClB,QAAQ,CAAC,MAAM,GAAG,CAAC;gBACnB,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ;gBAC7B,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;YAC3D,MAAM,WAAW,GAAG,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC;YAC3E,MAAM,cAAc,GAAG,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;YACnD,MAAM,GAAG,CAAC,GAAG,aAAa,EAAE,GAAG,cAAc,CAAC,CAAC;QACjD,CAAC;aAAM,CAAC;YACN,yDAAyD;YACzD,MAAM,GAAG,QAAQ,CAAC;QACpB,CAAC;QAED,0EAA0E;QAC1E,qFAAqF;QACrF,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QACpE,IAAI,UAAU,YAAY,OAAO,EAAE,CAAC;YAClC,UAAU,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;gBAClC,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;oBACvB,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;gBAC5B,CAAC;qBAAM,IAAI,SAAS,EAAE,EAAE,CAAC;oBACvB,sCAAsC;oBACtC,OAAO,CAAC,IAAI,CACV,6FAA6F,EAC7F,KAAK,CACN,CAAC;gBACJ,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC;QAED,8DAA8D;QAC9D,KAAK,CAAC,MAAM,EAAE,CAAC;QAEf,8EAA8E;QAC9E,uDAAuD;QACvD,KAAK,CAAC,mBAAmB,GAAG,KAAK,CAAC;IACpC,CAAC,CAAC;AACJ,CAAC;AAhED,0DAgEC"}

package/dist/stages/finalize.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * Finalize stage — extract the final response from conversation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.finalizeStage = void 0;
+const content_1 = require("../types/content");
+const memory_1 = require("../memory");
+function finalizeStage(scope) {
+    const messages = scope.messages ?? [];
+    const lastAsst = (0, memory_1.lastAssistantMessage)(messages);
+    const result = lastAsst ? (0, content_1.getTextContent)(lastAsst.content) : '';
+    scope.result = result;
+}
+exports.finalizeStage = finalizeStage;
+//# sourceMappingURL=finalize.js.map

package/dist/stages/finalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"finalize.js","sourceRoot":"","sources":["../../src/stages/finalize.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAGH,8CAAkD;AAElD,sCAAiD;AAEjD,SAAgB,aAAa,CAAC,KAA+B;IAC3D,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;IACtC,MAAM,QAAQ,GAAG,IAAA,6BAAoB,EAAC,QAAQ,CAAC,CAAC;IAEhD,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAA,wBAAc,EAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAChE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC;AACxB,CAAC;AAND,sCAMC"}

package/dist/stages/helpers.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Shared helpers for agent stages.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeToolCalls = exports.normalizeAdapterResponse = void 0;
+const types_1 = require("../types");
+const memory_1 = require("../memory");
+/**
+ * Normalize an LLMResponse into an AdapterResult discriminated union.
+ * Shared by callLLM stage and createAdapterSubflow.
+ */
+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;
+/**
+ * Execute tool calls and append results to conversation messages.
+ * Returns the updated messages array.
+ */
+async function executeToolCalls(toolCalls, registry, messages) {
+    let msgs = messages;
+    for (const toolCall of toolCalls) {
+        const tool = registry.get(toolCall.name);
+        let resultContent;
+        if (!tool) {
+            resultContent = JSON.stringify({
+                error: true,
+                message: `Tool '${toolCall.name}' not found`,
+            });
+        }
+        else {
+            try {
+                const result = await tool.handler(toolCall.arguments);
+                resultContent = result.content;
+            }
+            catch (err) {
+                resultContent = JSON.stringify({
+                    error: true,
+                    message: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        msgs = (0, memory_1.appendMessage)(msgs, (0, types_1.toolResultMessage)(resultContent, toolCall.id));
+    }
+    return msgs;
+}
+exports.executeToolCalls = executeToolCalls;
+//# sourceMappingURL=helpers.js.map

package/dist/stages/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../src/stages/helpers.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAGH,oCAA6C;AAG7C,sCAA0C;AAE1C;;;GAGG;AACH,SAAgB,wBAAwB,CAAC,QAAqB;IAC5D,IAAI,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxD,OAAO;YACL,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,QAAQ,CAAC,OAAO,IAAI,EAAE;YAC/B,SAAS,EAAE,QAAQ,CAAC,SAAS;YAC7B,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,KAAK,EAAE,QAAQ,CAAC,KAAK;SACtB,CAAC;IACJ,CAAC;IACD,OAAO;QACL,IAAI,EAAE,OAAO;QACb,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,KAAK,EAAE,QAAQ,CAAC,KAAK;KACtB,CAAC;AACJ,CAAC;AAhBD,4DAgBC;AAED;;;GAGG;AACI,KAAK,UAAU,gBAAgB,CACpC,SAAqB,EACrB,QAAsB,EACtB,QAAmB;IAEnB,IAAI,IAAI,GAAG,QAAQ,CAAC;IAEpB,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAEzC,IAAI,aAAqB,CAAC;QAC1B,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,aAAa,GAAG,IAAI,CAAC,SAAS,CAAC;gBAC7B,KAAK,EAAE,IAAI;gBACX,OAAO,EAAE,SAAS,QAAQ,CAAC,IAAI,aAAa;aAC7C,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;gBACtD,aAAa,GAAG,MAAM,CAAC,OAAO,CAAC;YACjC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,aAAa,GAAG,IAAI,CAAC,SAAS,CAAC;oBAC7B,KAAK,EAAE,IAAI;oBACX,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;iBAC1D,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,IAAI,GAAG,IAAA,sBAAa,EAAC,IAAI,EAAE,IAAA,yBAAiB,EAAC,aAAa,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5E,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAhCD,4CAgCC"}

package/dist/stages/index.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runnerAsStage = exports.augmentPromptStage = exports.createRetrieveStage = exports.executeToolCalls = exports.normalizeAdapterResponse = exports.finalizeStage = exports.parseResponseStage = exports.createCallLLMStage = exports.createCommitMemoryStage = void 0;
+var commitMemory_1 = require("./commitMemory");
+Object.defineProperty(exports, "createCommitMemoryStage", { enumerable: true, get: function () { return commitMemory_1.createCommitMemoryStage; } });
+var callLLM_1 = require("./callLLM");
+Object.defineProperty(exports, "createCallLLMStage", { enumerable: true, get: function () { return callLLM_1.createCallLLMStage; } });
+var parseResponse_1 = require("./parseResponse");
+Object.defineProperty(exports, "parseResponseStage", { enumerable: true, get: function () { return parseResponse_1.parseResponseStage; } });
+var finalize_1 = require("./finalize");
+Object.defineProperty(exports, "finalizeStage", { enumerable: true, get: function () { return finalize_1.finalizeStage; } });
+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; } });
+var retrieve_1 = require("./retrieve");
+Object.defineProperty(exports, "createRetrieveStage", { enumerable: true, get: function () { return retrieve_1.createRetrieveStage; } });
+var augmentPrompt_1 = require("./augmentPrompt");
+Object.defineProperty(exports, "augmentPromptStage", { enumerable: true, get: function () { return augmentPrompt_1.augmentPromptStage; } });
+var runnerAsStage_1 = require("./runnerAsStage");
+Object.defineProperty(exports, "runnerAsStage", { enumerable: true, get: function () { return runnerAsStage_1.runnerAsStage; } });
+//# sourceMappingURL=index.js.map

package/dist/stages/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/stages/index.ts"],"names":[],"mappings":";;;AAAA,+CAAyD;AAAhD,uHAAA,uBAAuB,OAAA;AAEhC,qCAA+C;AAAtC,6GAAA,kBAAkB,OAAA;AAC3B,iDAAqD;AAA5C,mHAAA,kBAAkB,OAAA;AAC3B,uCAA2C;AAAlC,yGAAA,aAAa,OAAA;AACtB,qCAAuE;AAA9D,mHAAA,wBAAwB,OAAA;AAAE,2GAAA,gBAAgB,OAAA;AACnD,uCAAiD;AAAxC,+GAAA,mBAAmB,OAAA;AAC5B,iDAAqD;AAA5C,mHAAA,kBAAkB,OAAA;AAC3B,iDAAgD;AAAvC,8GAAA,aAAa,OAAA"}

package/dist/stages/parseResponse.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * ParseResponse stage — extract ParsedResponse from AdapterResult.
+ * Also appends assistant message to conversation history.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseResponseStage = void 0;
+const types_1 = require("../types");
+const memory_1 = require("../memory");
+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;
+    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);
+}
+exports.parseResponseStage = parseResponseStage;
+//# sourceMappingURL=parseResponse.js.map

package/dist/stages/parseResponse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseResponse.js","sourceRoot":"","sources":["../../src/stages/parseResponse.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAGH,oCAA4C;AAG5C,sCAA0C;AAE1C,SAAgB,kBAAkB,CAAC,KAA+B;IAChE,MAAM,MAAM,GAAG,KAAK,CAAC,aAA0C,CAAC;IAEhE,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,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;AACpD,CAAC;AAzBD,gDAyBC"}

package/dist/stages/retrieve.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Retrieve stage — calls retriever provider, writes RetrievalResult to scope.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRetrieveStage = void 0;
+const content_1 = require("../types/content");
+function createRetrieveStage(retriever, options) {
+    return async (scope) => {
+        // Use explicit retrieval query if set, otherwise last user message
+        const lastUserContent = (scope.messages ?? [])
+            .filter((m) => m.role === 'user')
+            .pop()?.content;
+        const query = scope.retrievalQuery ??
+            (lastUserContent ? (0, content_1.getTextContent)(lastUserContent) : '');
+        const result = await retriever.retrieve(query, options);
+        // Write to scope — recorders observe this
+        scope.retrievalResult = result;
+    };
+}
+exports.createRetrieveStage = createRetrieveStage;
+//# sourceMappingURL=retrieve.js.map

package/dist/stages/retrieve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieve.js","sourceRoot":"","sources":["../../src/stages/retrieve.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAIH,8CAAkD;AAGlD,SAAgB,mBAAmB,CAAC,SAA4B,EAAE,OAAyB;IACzF,OAAO,KAAK,EAAE,KAA2B,EAAE,EAAE;QAC3C,mEAAmE;QACnE,MAAM,eAAe,GAAG,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;aAC3C,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;aAChC,GAAG,EAAE,EAAE,OAAO,CAAC;QAClB,MAAM,KAAK,GACT,KAAK,CAAC,cAAc;YACpB,CAAC,eAAe,CAAC,CAAC,CAAC,IAAA,wBAAc,EAAC,eAAe,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAE3D,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAExD,0CAA0C;QAC1C,KAAK,CAAC,eAAe,GAAG,MAAM,CAAC;IACjC,CAAC,CAAC;AACJ,CAAC;AAfD,kDAeC"}

package/dist/stages/runnerAsStage.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * runnerAsStage — wraps any RunnerLike as a flowchart stage function.
+ *
+ * This is the core primitive for multi-agent composition. Any runner
+ * (Agent, RAG, LLMCall, or user-built) can become a stage in a pipeline.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runnerAsStage = void 0;
+/**
+ * Creates a stage function that executes a runner and writes its result to scope.
+ *
+ * Default behavior:
+ * - Input: reads previous agent's output (or pipelineInput for first agent)
+ * - Output: writes to 'result' and records agent entry in agentResults
+ */
+function runnerAsStage(config) {
+    return async (scope) => {
+        const state = buildStateSnapshot(scope);
+        // Default: prefer previous agent's result, fall back to pipeline input
+        const input = config.inputMapper
+            ? config.inputMapper(state)
+            : state.result ?? state.pipelineInput ?? '';
+        const startTime = Date.now();
+        const env = scope.$getEnv();
+        const signal = env?.signal;
+        const timeoutMs = env?.timeoutMs;
+        const output = await config.runner.run(input, { signal, timeoutMs });
+        const latencyMs = Date.now() - startTime;
+        // Apply output mapper or default write
+        if (config.outputMapper) {
+            const mapped = config.outputMapper(output, state);
+            for (const [key, value] of Object.entries(mapped)) {
+                scope.$setValue(key, value);
+            }
+        }
+        else {
+            scope.result = output.content;
+        }
+        // Record agent result entry
+        const entry = {
+            id: config.id,
+            name: config.name,
+            content: output.content,
+            latencyMs,
+            narrative: config.runner.getNarrative?.() ?? undefined,
+        };
+        const existing = scope.agentResults ?? [];
+        scope.agentResults = [...existing, entry];
+    };
+}
+exports.runnerAsStage = runnerAsStage;
+/** Build a plain object snapshot of scope state for mappers. */
+function buildStateSnapshot(scope) {
+    const result = {};
+    // Read well-known keys that mappers might need
+    for (const key of [
+        'pipelineInput',
+        'result',
+        'agentResults',
+        'messages',
+        'systemPrompt',
+    ]) {
+        const val = scope.$getValue(key);
+        if (val !== undefined)
+            result[key] = val;
+    }
+    return result;
+}
+//# sourceMappingURL=runnerAsStage.js.map

package/dist/stages/runnerAsStage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runnerAsStage.js","sourceRoot":"","sources":["../../src/stages/runnerAsStage.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAMH;;;;;;GAMG;AACH,SAAgB,aAAa,CAAC,MAAwB;IACpD,OAAO,KAAK,EAAE,KAAkC,EAAiB,EAAE;QACjE,MAAM,KAAK,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;QACxC,uEAAuE;QACvE,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW;YAC9B,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC;YAC3B,CAAC,CAAE,KAAK,CAAC,MAAiB,IAAK,KAAK,CAAC,aAAwB,IAAI,EAAE,CAAC;QAEtE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,GAAG,EAAE,MAAM,CAAC;QAC3B,MAAM,SAAS,GAAG,GAAG,EAAE,SAAS,CAAC;QAEjC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;QACrE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QAEzC,uCAAuC;QACvC,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;YACxB,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YAClD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBAClD,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC;QAChC,CAAC;QAED,4BAA4B;QAC5B,MAAM,KAAK,GAAqB;YAC9B,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,SAAS;YACT,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,EAAE,IAAI,SAAS;SACvD,CAAC;QAEF,MAAM,QAAQ,GAAG,KAAK,CAAC,YAAY,IAAI,EAAE,CAAC;QAC1C,KAAK,CAAC,YAAY,GAAG,CAAC,GAAG,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC5C,CAAC,CAAC;AACJ,CAAC;AAvCD,sCAuCC;AAED,gEAAgE;AAChE,SAAS,kBAAkB,CAAC,KAAkC;IAC5D,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,+CAA+C;IAC/C,KAAK,MAAM,GAAG,IAAI;QAChB,eAAe;QACf,QAAQ;QACR,cAAc;QACd,UAAU;QACV,cAAc;KACN,EAAE,CAAC;QACX,MAAM,GAAG,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,GAAG,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IAC3C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/stream.barrel.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * agentfootprint/stream — See agents work in real-time.
+ *
+ * 9-event discriminated union for CLI/web/mobile consumers.
+ * SSEFormatter for Server-Sent Events.
+ *
+ * @example
+ * ```typescript
+ * import { SSEFormatter } from 'agentfootprint/stream';
+ * import type { AgentStreamEvent } from 'agentfootprint/stream';
+ *
+ * await agent.run('hello', {
+ *   onEvent: (e: AgentStreamEvent) => res.write(SSEFormatter.format(e)),
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SSEFormatter = exports.StreamEmitter = void 0;
+var streaming_1 = require("./streaming");
+Object.defineProperty(exports, "StreamEmitter", { enumerable: true, get: function () { return streaming_1.StreamEmitter; } });
+Object.defineProperty(exports, "SSEFormatter", { enumerable: true, get: function () { return streaming_1.SSEFormatter; } });
+//# sourceMappingURL=stream.barrel.js.map

package/dist/stream.barrel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.barrel.js","sourceRoot":"","sources":["../src/stream.barrel.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAEH,yCAA0D;AAAjD,0GAAA,aAAa,OAAA;AAAE,yGAAA,YAAY,OAAA"}

package/dist/streaming/StreamEmitter.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SSEFormatter = exports.StreamEmitter = void 0;
+/**
+ * StreamEmitter — dispatches AgentStreamEvents to consumers.
+ *
+ * Error isolation: handler errors are swallowed — never break the agent pipeline.
+ * This is the correct behavior for a push-to-consumer system (same as RecorderBridge).
+ */
+class StreamEmitter {
+    handlers = [];
+    on(handler) {
+        this.handlers.push(handler);
+        return () => {
+            this.handlers = this.handlers.filter((h) => h !== handler);
+        };
+    }
+    emit(event) {
+        for (const handler of this.handlers) {
+            try {
+                handler(event);
+            }
+            catch {
+                // Swallow handler errors — never break the pipeline
+            }
+        }
+    }
+}
+exports.StreamEmitter = StreamEmitter;
+/**
+ * SSEFormatter — converts AgentStreamEvent to Server-Sent Events text.
+ *
+ * @example
+ * ```typescript
+ * res.write(SSEFormatter.format({ type: 'token', content: 'Hello' }));
+ * // event: token\ndata: {"type":"token","content":"Hello"}\n\n
+ * ```
+ */
+class SSEFormatter {
+    static format(event) {
+        return `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`;
+    }
+    static formatAll(events) {
+        return events.map(SSEFormatter.format).join('');
+    }
+}
+exports.SSEFormatter = SSEFormatter;
+//# sourceMappingURL=StreamEmitter.js.map

package/dist/streaming/StreamEmitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamEmitter.js","sourceRoot":"","sources":["../../src/streaming/StreamEmitter.ts"],"names":[],"mappings":";;;AAqCA;;;;;GAKG;AACH,MAAa,aAAa;IAChB,QAAQ,GAA8B,EAAE,CAAC;IAEjD,EAAE,CAAC,OAAgC;QACjC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC5B,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC;QAC7D,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,KAAuB;QAC1B,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YACpC,IAAI,CAAC;gBACH,OAAO,CAAC,KAAK,CAAC,CAAC;YACjB,CAAC;YAAC,MAAM,CAAC;gBACP,oDAAoD;YACtD,CAAC;QACH,CAAC;IACH,CAAC;CACF;AAnBD,sCAmBC;AAED;;;;;;;;GAQG;AACH,MAAa,YAAY;IACvB,MAAM,CAAC,MAAM,CAAC,KAAuB;QACnC,OAAO,UAAU,KAAK,CAAC,IAAI,WAAW,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC;IACpE,CAAC;IAED,MAAM,CAAC,SAAS,CAAC,MAA0B;QACzC,OAAO,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAClD,CAAC;CACF;AARD,oCAQC"}

package/dist/streaming/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SSEFormatter = exports.StreamEmitter = void 0;
+var StreamEmitter_1 = require("./StreamEmitter");
+Object.defineProperty(exports, "StreamEmitter", { enumerable: true, get: function () { return StreamEmitter_1.StreamEmitter; } });
+Object.defineProperty(exports, "SSEFormatter", { enumerable: true, get: function () { return StreamEmitter_1.SSEFormatter; } });
+//# sourceMappingURL=index.js.map

package/dist/streaming/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/streaming/index.ts"],"names":[],"mappings":";;;AAAA,iDAA8D;AAArD,8GAAA,aAAa,OAAA;AAAE,6GAAA,YAAY,OAAA"}

package/dist/subflows/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPrepareMemorySubflow = void 0;
+var prepareMemory_1 = require("./prepareMemory");
+Object.defineProperty(exports, "createPrepareMemorySubflow", { enumerable: true, get: function () { return prepareMemory_1.createPrepareMemorySubflow; } });
+//# sourceMappingURL=index.js.map

package/dist/subflows/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/subflows/index.ts"],"names":[],"mappings":";;;AAAA,iDAA6D;AAApD,2HAAA,0BAA0B,OAAA"}

package/dist/subflows/prepareMemory.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * PrepareMemory subflow — load history from store + apply MessageStrategy.
+ *
+ * Flowchart (2 stages):
+ *   LoadHistory → ApplyStrategy
+ *
+ * LoadHistory: calls store.load(conversationId), merges stored history with
+ *   the current turn's message (added by SeedScope), writes merged history
+ *   to scope as `memory_storedHistory`.
+ *
+ * ApplyStrategy: applies the configured MessageStrategy to the merged history
+ *   (trim, window, summarize). Writes prepared messages to scope as
+ *   `memory_preparedMessages`. If no strategy, passes merged history through.
+ *
+ * The subflow is mounted via addSubFlowChartNext in Agent.ts:
+ *   inputMapper  — copies current messages from parent scope into subflow
+ *   outputMapper — copies prepared messages back to parent scope's `messages`
+ *
+ * No-op behavior:
+ *   - No store:    LoadHistory writes current messages as-is (no DB hit)
+ *   - No strategy: ApplyStrategy writes merged history as-is (no trimming)
+ *   Both stages are always present in the flowchart for narrative visibility.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPrepareMemorySubflow = void 0;
+const footprintjs_1 = require("footprintjs");
+// ── Subflow factory ───────────────────────────────────────────
+/**
+ * Build the PrepareMemory subflow.
+ *
+ * Mount this with addSubFlowChartNext after SeedScope:
+ * ```typescript
+ * .addSubFlowChartNext('sf-prepare-memory', createPrepareMemorySubflow(config), 'PrepareMemory', {
+ *   inputMapper: (parent) => ({
+ *     currentMessages: parent.messages ?? [],
+ *     loopCount: parent.loopCount ?? 0,
+ *   }),
+ *   outputMapper: (sfOutput) => ({
+ *     memory_preparedMessages: sfOutput.memory_preparedMessages,
+ *     memory_storedHistory: sfOutput.memory_storedHistory,
+ *   }),
+ * })
+ * ```
+ */
+function createPrepareMemorySubflow(config) {
+    // ── Stage 1: LoadHistory ─────────────────────────────────
+    const loadHistory = async (scope) => {
+        const current = scope.currentMessages ?? [];
+        if (!config.store || !config.conversationId) {
+            // No store configured — pass current messages through unchanged
+            scope.memory_storedHistory = current;
+            return;
+        }
+        // Null-safe: store.load() may return null for backends that don't have a record.
+        const stored = (await config.store.load(config.conversationId)) ?? [];
+        // Merge strategy: stored history first, then new messages from this turn.
+        // currentMessages contains only the new messages for this turn (e.g. [user('question')]).
+        // Append unconditionally — the store holds all prior turns.
+        const merged = stored.length > 0 ? [...stored, ...current] : current;
+        scope.memory_storedHistory = merged;
+    };
+    // ── Stage 2: ApplyStrategy ───────────────────────────────
+    const applyStrategy = async (scope) => {
+        const merged = scope.memory_storedHistory ?? [];
+        if (!config.strategy) {
+            // No strategy — pass through as-is
+            scope.memory_preparedMessages = merged;
+            return;
+        }
+        // Build a minimal MessageContext. Turn number and loop iteration are
+        // not available here; strategies that need them (rare) can derive from
+        // the message array length.
+        const ctx = {
+            message: '',
+            turnNumber: 0,
+            loopIteration: 0,
+        };
+        const decision = await config.strategy.prepare(merged, ctx);
+        scope.memory_preparedMessages = decision.value;
+    };
+    return (0, footprintjs_1.flowChart)('LoadHistory', loadHistory, 'load-history')
+        .addFunction('ApplyStrategy', applyStrategy, 'apply-strategy')
+        .build();
+}
+exports.createPrepareMemorySubflow = createPrepareMemorySubflow;
+//# sourceMappingURL=prepareMemory.js.map

package/dist/subflows/prepareMemory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepareMemory.js","sourceRoot":"","sources":["../../src/subflows/prepareMemory.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;AAEH,6CAAwC;AAuBxC,iEAAiE;AAEjE;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,0BAA0B,CAAC,MAA2B;IACpE,4DAA4D;IAE5D,MAAM,WAAW,GAAG,KAAK,EAAE,KAAuC,EAAE,EAAE;QACpE,MAAM,OAAO,GAAG,KAAK,CAAC,eAAe,IAAI,EAAE,CAAC;QAE5C,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;YAC5C,gEAAgE;YAChE,KAAK,CAAC,oBAAoB,GAAG,OAAO,CAAC;YACrC,OAAO;QACT,CAAC;QAED,iFAAiF;QACjF,MAAM,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,IAAI,EAAE,CAAC;QAEtE,0EAA0E;QAC1E,0FAA0F;QAC1F,4DAA4D;QAC5D,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;QAErE,KAAK,CAAC,oBAAoB,GAAG,MAAM,CAAC;IACtC,CAAC,CAAC;IAEF,4DAA4D;IAE5D,MAAM,aAAa,GAAG,KAAK,EAAE,KAAuC,EAAE,EAAE;QACtE,MAAM,MAAM,GAAG,KAAK,CAAC,oBAAoB,IAAI,EAAE,CAAC;QAEhD,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;YACrB,mCAAmC;YACnC,KAAK,CAAC,uBAAuB,GAAG,MAAM,CAAC;YACvC,OAAO;QACT,CAAC;QAED,qEAAqE;QACrE,uEAAuE;QACvE,4BAA4B;QAC5B,MAAM,GAAG,GAAmB;YAC1B,OAAO,EAAE,EAAE;YACX,UAAU,EAAE,CAAC;YACb,aAAa,EAAE,CAAC;SACjB,CAAC;QAEF,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAC5D,KAAK,CAAC,uBAAuB,GAAG,QAAQ,CAAC,KAAK,CAAC;IACjD,CAAC,CAAC;IAEF,OAAO,IAAA,uBAAS,EAAuB,aAAa,EAAE,WAAW,EAAE,cAAc,CAAC;SAC/E,WAAW,CAAC,eAAe,EAAE,aAAa,EAAE,gBAAgB,CAAC;SAC7D,KAAK,EAAE,CAAC;AACb,CAAC;AAlDD,gEAkDC"}

package/dist/tools/ToolRegistry.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * ToolRegistry — register, lookup, and format tools for LLM function calling.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineTool = exports.ToolRegistry = void 0;
+const zodToJsonSchema_1 = require("./zodToJsonSchema");
+class ToolRegistry {
+    tools = new Map();
+    /** Register a tool. Throws if ID already registered. */
+    register(tool) {
+        if (this.tools.has(tool.id)) {
+            throw new Error(`ToolRegistry: tool '${tool.id}' already registered`);
+        }
+        this.tools.set(tool.id, tool);
+        return this;
+    }
+    /** Get a tool by ID. */
+    get(id) {
+        return this.tools.get(id);
+    }
+    /** Check if a tool is registered. */
+    has(id) {
+        return this.tools.has(id);
+    }
+    /** Get all registered tool IDs. */
+    ids() {
+        return Array.from(this.tools.keys());
+    }
+    /** Get all registered tools. */
+    all() {
+        return Array.from(this.tools.values());
+    }
+    /** Format tools for LLM function calling (OpenAI-compatible schema). */
+    formatForLLM(toolIds) {
+        const tools = toolIds
+            ? toolIds.map((id) => {
+                const tool = this.tools.get(id);
+                if (!tool)
+                    throw new Error(`ToolRegistry: tool '${id}' not found`);
+                return tool;
+            })
+            : this.all();
+        return tools.map((tool) => ({
+            name: tool.id,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }));
+    }
+    /** Number of registered tools. */
+    get size() {
+        return this.tools.size;
+    }
+}
+exports.ToolRegistry = ToolRegistry;
+/**
+ * Define a tool inline. Accepts JSON Schema or Zod schema for `inputSchema`.
+ *
+ * @example JSON Schema
+ * ```typescript
+ * defineTool({
+ *   id: 'search',
+ *   description: 'Search the web',
+ *   inputSchema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
+ *   handler: async ({ query }) => ({ content: `Results for: ${query}` }),
+ * });
+ * ```
+ *
+ * @example Zod schema (auto-converted, no zod dependency in core)
+ * ```typescript
+ * import { z } from 'zod';
+ * defineTool({
+ *   id: 'search',
+ *   description: 'Search the web',
+ *   inputSchema: z.object({ query: z.string().describe('Search query') }),
+ *   handler: async ({ query }) => ({ content: `Results for: ${query}` }),
+ * });
+ * ```
+ */
+function defineTool(tool) {
+    const schema = tool.inputSchema;
+    // Duck-type Zod detection: Zod schemas have ._def and .safeParse
+    if ((0, zodToJsonSchema_1.isZodSchema)(schema)) {
+        return { ...tool, inputSchema: (0, zodToJsonSchema_1.zodToJsonSchema)(schema) };
+    }
+    return tool;
+}
+exports.defineTool = defineTool;
+//# sourceMappingURL=ToolRegistry.js.map