agentfootprint 1.0.0

package/dist/esm/concepts/RAG.js

@@ -0,0 +1,193 @@
+/**
+ * RAG — Retrieve-Augment-Generate concept.
+ *
+ * Flowchart: Seed → Retrieve → AugmentPrompt → CallLLM → ParseResponse → Finalize
+ *
+ * Usage:
+ *   const rag = RAG.create({ provider: mock([...]), retriever: mockRetriever([...]) })
+ *     .system('You are helpful.')
+ *     .topK(5)
+ *     .build();
+ *   const result = await rag.run('What is X?');
+ */
+import { flowChart, FlowChartExecutor, MetricRecorder } from 'footprintjs';
+import { annotateSpecIcons } from './specIcons';
+import { getTextContent } from '../types/content';
+import { userMessage, systemMessage } from '../types';
+import { RecorderBridge } from '../recorders/v2/RecorderBridge';
+import { resolveProvider } from '../adapters/createProvider';
+import { createRetrieveStage } from '../stages/retrieve';
+import { augmentPromptStage } from '../stages/augmentPrompt';
+import { createCallLLMStage } from '../stages/callLLM';
+import { parseResponseStage } from '../stages/parseResponse';
+import { finalizeStage } from '../stages/finalize';
+import { lastAssistantMessage } from '../memory';
+export class RAG {
+    provider;
+    retriever;
+    sysPrompt;
+    retrieveOptions = {};
+    recorders = [];
+    enableStreaming = false;
+    constructor(options) {
+        this.provider = resolveProvider(options.provider);
+        this.retriever = options.retriever;
+    }
+    static create(options) {
+        return new RAG(options);
+    }
+    /** Set system prompt. */
+    system(prompt) {
+        this.sysPrompt = prompt;
+        return this;
+    }
+    /** Set number of chunks to retrieve. */
+    topK(n) {
+        this.retrieveOptions = { ...this.retrieveOptions, topK: n };
+        return this;
+    }
+    /** Set minimum relevance score threshold. */
+    minScore(score) {
+        this.retrieveOptions = { ...this.retrieveOptions, minScore: score };
+        return this;
+    }
+    /** Enable token-by-token streaming for the LLM call. */
+    streaming(enabled) {
+        this.enableStreaming = enabled;
+        return this;
+    }
+    /** Attach an AgentRecorder to observe execution events. */
+    recorder(rec) {
+        this.recorders.push(rec);
+        return this;
+    }
+    /** Build the RAG pipeline and return a runner. */
+    build() {
+        return new RAGRunner(this.provider, this.retriever, this.sysPrompt, this.retrieveOptions, [...this.recorders], this.enableStreaming);
+    }
+}
+export class RAGRunner {
+    provider;
+    retriever;
+    sysPrompt;
+    retrieveOptions;
+    recorders;
+    lastExecutor;
+    lastSpec;
+    streamingEnabled;
+    constructor(provider, retriever, sysPrompt, retrieveOptions, recorders = [], streaming = false) {
+        this.provider = provider;
+        this.retriever = retriever;
+        this.sysPrompt = sysPrompt;
+        this.retrieveOptions = retrieveOptions;
+        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(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 FlowChartExecutor(chart, executorOpts);
+        executor.enableNarrative();
+        executor.attachRecorder(new 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 = lastAssistantMessage(messages);
+        const content = state.result ?? (lastAsst ? getTextContent(lastAsst.content) : '');
+        const retrievalResult = state.retrievalResult;
+        if (bridge) {
+            const response = state.adapterRawResponse;
+            if (response) {
+                bridge.dispatchLLMCall(response, Date.now() - startMs);
+            }
+            bridge.dispatchTurnComplete(content, messages.length);
+        }
+        return {
+            content,
+            messages,
+            chunks: retrievalResult?.chunks ?? [],
+            query: retrievalResult?.query ?? message,
+        };
+    }
+    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(systemMessage(sp));
+            msgs.push(userMessage(message));
+            scope.messages = msgs;
+        };
+        const retrieve = createRetrieveStage(this.retriever, this.retrieveOptions);
+        const callLLM = createCallLLMStage(this.provider);
+        let builder = flowChart('SystemPrompt', systemPromptStage, 'system-prompt')
+            .addFunction('Messages', messagesStage, 'messages')
+            .addFunction('Retrieve', retrieve, 'retrieve')
+            .addFunction('AugmentPrompt', augmentPromptStage, 'augment-prompt');
+        if (this.streamingEnabled) {
+            builder = builder.addStreamingFunction('CallLLM', callLLM, 'call-llm', 'llm-stream');
+        }
+        else {
+            builder = builder.addFunction('CallLLM', callLLM, 'call-llm');
+        }
+        builder = builder
+            .addFunction('ParseResponse', parseResponseStage, 'parse-response')
+            .addFunction('Finalize', finalizeStage, 'finalize');
+        this.lastSpec = annotateSpecIcons(builder.toSpec());
+        return builder.build();
+    }
+    /** Get the flowchart spec (stage graph metadata). */
+    getSpec() {
+        if (!this.lastSpec) {
+            this.buildChart('');
+        }
+        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();
+    }
+}
+//# sourceMappingURL=RAG.js.map

package/dist/esm/concepts/RAG.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RAG.js","sourceRoot":"","sources":["../../../src/concepts/RAG.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE3E,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAYhD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEtD,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAE7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAQjD,MAAM,OAAO,GAAG;IACG,QAAQ,CAAc;IACtB,SAAS,CAAoB;IACtC,SAAS,CAAU;IACnB,eAAe,GAAoB,EAAE,CAAC;IAC7B,SAAS,GAAoB,EAAE,CAAC;IACzC,eAAe,GAAG,KAAK,CAAC;IAEhC,YAAoB,OAAmB;QACrC,IAAI,CAAC,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAClD,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACrC,CAAC;IAED,MAAM,CAAC,MAAM,CAAC,OAAmB;QAC/B,OAAO,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;IAED,yBAAyB;IACzB,MAAM,CAAC,MAAc;QACnB,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wCAAwC;IACxC,IAAI,CAAC,CAAS;QACZ,IAAI,CAAC,eAAe,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QAC5D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,6CAA6C;IAC7C,QAAQ,CAAC,KAAa;QACpB,IAAI,CAAC,eAAe,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;QACpE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wDAAwD;IACxD,SAAS,CAAC,OAAgB;QACxB,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC;QAC/B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,2DAA2D;IAC3D,QAAQ,CAAC,GAAkB;QACzB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kDAAkD;IAClD,KAAK;QACH,OAAO,IAAI,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,eAAe,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;IACvI,CAAC;CACF;AAED,MAAM,OAAO,SAAS;IACH,QAAQ,CAAc;IACtB,SAAS,CAAoB;IAC7B,SAAS,CAAU;IACnB,eAAe,CAAkB;IACjC,SAAS,CAAkB;IACpC,YAAY,CAAqB;IACjC,QAAQ,CAAW;IAEV,gBAAgB,CAAU;IAE3C,YACE,QAAqB,EACrB,SAA4B,EAC5B,SAA6B,EAC7B,eAAgC,EAChC,YAA6B,EAAE,EAC/B,SAAS,GAAG,KAAK;QAEjB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACvC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,gBAAgB,GAAG,SAAS,CAAC;IACpC,CAAC;IAED,6DAA6D;IAC7D,WAAW;QACT,OAAO,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,GAAG,CACP,OAAe,EACf,OAAyF;QAEzF,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACvC,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAErF,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAEnC,MAAM,YAAY,GAA6B,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC;QACzE,IAAI,OAAO,EAAE,OAAO,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC9C,YAAY,CAAC,cAAc,GAAG;gBAC5B,OAAO,EAAE,CAAC,SAAiB,EAAE,KAAa,EAAE,EAAE,CAAC,OAAO,CAAC,OAAQ,CAAC,KAAK,CAAC;gBACtE,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC;gBACjB,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;aAChB,CAAC;QACJ,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,iBAAiB,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;QAC5D,QAAQ,CAAC,eAAe,EAAE,CAAC;QAC3B,QAAQ,CAAC,cAAc,CAAC,IAAI,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC;QACvD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE3B,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,GAAG,CAAC;gBACjB,KAAK,EAAE,EAAE,OAAO,EAAE;gBAClB,MAAM,EAAE,OAAO,EAAE,MAAM;gBACvB,SAAS,EAAE,OAAO,EAAE,SAAS;aAC9B,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,EAAE,aAAa,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAClC,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,IAAI,CAAC,YAAY,GAAG,QAAQ,CAAC;QAE7B,MAAM,QAAQ,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;QACxC,MAAM,KAAK,GAAG,QAAQ,EAAE,WAAW,IAAI,EAAE,CAAC;QAC1C,MAAM,QAAQ,GAAI,KAAK,CAAC,QAAsB,IAAI,EAAE,CAAC;QACrD,MAAM,QAAQ,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;QAChD,MAAM,OAAO,GAAI,KAAK,CAAC,MAAiB,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC/F,MAAM,eAAe,GAAG,KAAK,CAAC,eAA8C,CAAC;QAE7E,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,QAAQ,GAAG,KAAK,CAAC,kBAA6C,CAAC;YACrE,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,CAAC,eAAe,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC;YACzD,CAAC;YACD,MAAM,CAAC,oBAAoB,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;QACxD,CAAC;QAED,OAAO;YACL,OAAO;YACP,QAAQ;YACR,MAAM,EAAE,eAAe,EAAE,MAAM,IAAI,EAAE;YACrC,KAAK,EAAE,eAAe,EAAE,KAAK,IAAI,OAAO;SACzC,CAAC;IACJ,CAAC;IAEO,UAAU,CAAC,OAAe;QAChC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAEjC,sDAAsD;QACtD,MAAM,iBAAiB,GAAG,CAAC,KAA2B,EAAE,EAAE;YACxD,IAAI,SAAS,EAAE,CAAC;gBACd,KAAK,CAAC,YAAY,GAAG,SAAS,CAAC;YACjC,CAAC;QACH,CAAC,CAAC;QAEF,yDAAyD;QACzD,MAAM,aAAa,GAAG,CAAC,KAA2B,EAAE,EAAE;YACpD,MAAM,IAAI,GAAc,EAAE,CAAC;YAC3B,MAAM,EAAE,GAAG,KAAK,CAAC,YAAY,CAAC;YAC9B,IAAI,EAAE;gBAAE,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC;YACrC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;YAChC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC;QACxB,CAAC,CAAC;QAEF,MAAM,QAAQ,GAAG,mBAAmB,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;QAC3E,MAAM,OAAO,GAAG,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAElD,IAAI,OAAO,GAAG,SAAS,CAAW,cAAc,EAAE,iBAAiB,EAAE,eAAe,CAAC;aAClF,WAAW,CAAC,UAAU,EAAE,aAAa,EAAE,UAAU,CAAC;aAClD,WAAW,CAAC,UAAU,EAAE,QAAQ,EAAE,UAAU,CAAC;aAC7C,WAAW,CAAC,eAAe,EAAE,kBAAkB,EAAE,gBAAgB,CAAC,CAAC;QAEtE,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC1B,OAAO,GAAG,OAAO,CAAC,oBAAoB,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,CAAC,CAAC;QACvF,CAAC;aAAM,CAAC;YACN,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;QAChE,CAAC;QAED,OAAO,GAAG,OAAO;aACd,WAAW,CAAC,eAAe,EAAE,kBAAkB,EAAE,gBAAgB,CAAC;aAClE,WAAW,CAAC,UAAU,EAAE,aAAa,EAAE,UAAU,CAAC,CAAC;QAEtD,IAAI,CAAC,QAAQ,GAAG,iBAAiB,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QACpD,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;IAED,qDAAqD;IACrD,OAAO;QACL,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QACtB,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,2CAA2C;IAC3C,YAAY;QACV,OAAO,IAAI,CAAC,YAAY,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;IACjD,CAAC;IAED,0DAA0D;IAC1D,mBAAmB;QACjB,OAAO,IAAI,CAAC,YAAY,EAAE,mBAAmB,EAAE,IAAI,EAAE,CAAC;IACxD,CAAC;IAED,yDAAyD;IACzD,WAAW;QACT,OAAO,IAAI,CAAC,YAAY,EAAE,WAAW,EAAE,CAAC;IAC1C,CAAC;CACF"}

package/dist/esm/concepts/Swarm.js

@@ -0,0 +1,265 @@
+/**
+ * Swarm — multi-agent delegation via buildAgentLoop + buildSwarmRouting.
+ *
+ * An orchestrator LLM selects which specialist to invoke. Each specialist
+ * is mounted as a **lazy subflow** — visible in BTS with drill-down.
+ *
+ * Swarm IS an Agent with a different routing strategy:
+ *   Agent:  ... → RouteResponse{tool-calls | final}
+ *   Swarm:  ... → RouteSpecialist{specialist-A | specialist-B | swarm-tools | final}
+ *
+ * Everything upstream (SystemPrompt, Messages, Tools, AssemblePrompt,
+ * CallLLM, ParseResponse) is the same Agent loop infrastructure.
+ *
+ * > "Every feature you add to Agent automatically works in Swarm."
+ */
+import { FlowChartExecutor, MetricRecorder } from 'footprintjs';
+import { buildAgentLoop } from '../lib/loop';
+import { buildSwarmRouting } from '../lib/swarm/buildSwarmRouting';
+import { staticPrompt } from '../providers/prompt/static';
+import { slidingWindow } from '../providers/messages/slidingWindow';
+import { ToolRegistry } from '../tools';
+import { createAgentRenderer } from '../lib/narrative';
+import { RecorderBridge } from '../recorders/v2/RecorderBridge';
+import { annotateSpecIcons } from './specIcons';
+import { userMessage } from '../types';
+import { resolveProvider } from '../adapters/createProvider';
+// Specialist ID validation — alphanumeric + hyphens, max 64 chars
+const VALID_SPECIALIST_ID = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+// ── Builder ──────────────────────────────────────────────────
+export class Swarm {
+    provider;
+    swarmName;
+    systemPromptText;
+    specialists = [];
+    extraTools = [];
+    recorders = [];
+    maxIter = 10;
+    streamingEnabled = false;
+    constructor(options) {
+        this.provider = resolveProvider(options.provider);
+        this.swarmName = options.name ?? 'swarm';
+    }
+    static create(options) {
+        return new Swarm(options);
+    }
+    system(prompt) {
+        this.systemPromptText = prompt;
+        return this;
+    }
+    /**
+     * Register a specialist agent.
+     *
+     * Each specialist is mounted as a **lazy subflow** — only built when the
+     * orchestrator LLM selects it. Visible in BTS with drill-down.
+     */
+    specialist(id, description, runner) {
+        if (!VALID_SPECIALIST_ID.test(id)) {
+            throw new Error(`Invalid specialist ID '${id}'. Must match ${VALID_SPECIALIST_ID}.`);
+        }
+        this.specialists.push({ id, description, runner });
+        return this;
+    }
+    /** Register a non-specialist tool (calculator, search, etc.) available to the orchestrator. */
+    tool(toolDef) {
+        this.extraTools.push(toolDef);
+        return this;
+    }
+    maxIterations(n) {
+        this.maxIter = n;
+        return this;
+    }
+    streaming(enabled) {
+        this.streamingEnabled = enabled;
+        return this;
+    }
+    recorder(rec) {
+        this.recorders.push(rec);
+        return this;
+    }
+    build() {
+        if (this.specialists.length === 0) {
+            throw new Error('Swarm requires at least one specialist');
+        }
+        return new SwarmRunner(this.provider, this.swarmName, this.systemPromptText, [...this.specialists], [...this.extraTools], this.maxIter, this.streamingEnabled, [...this.recorders]);
+    }
+}
+// ── Runner ───────────────────────────────────────────────────
+export class SwarmRunner {
+    provider;
+    name;
+    systemPromptText;
+    specialists;
+    extraTools;
+    maxIter;
+    streamingEnabled;
+    recorders;
+    conversationHistory = [];
+    lastExecutor;
+    lastSpec;
+    narrativeRenderer = createAgentRenderer();
+    /** Cached routing config — constructed once, reused across runs. */
+    routingConfig;
+    /** Cached tool descriptions — constructed once, reused across runs. */
+    toolDescs;
+    /** Cached system prompt — constructed once, reused across runs. */
+    fullSystemPrompt;
+    constructor(provider, name, systemPromptText, specialists, extraTools, maxIter, streaming, recorders = []) {
+        this.provider = provider;
+        this.name = name;
+        this.systemPromptText = systemPromptText;
+        this.specialists = specialists;
+        this.extraTools = extraTools;
+        this.maxIter = maxIter;
+        this.streamingEnabled = streaming;
+        this.recorders = recorders;
+        // Cache at construction time — these don't change between runs
+        this.fullSystemPrompt = this.buildSystemPrompt();
+        this.toolDescs = this.buildToolDescriptions();
+        this.routingConfig = buildSwarmRouting({
+            specialists: this.specialists,
+            extraTools: this.extraTools.length > 0 ? this.extraTools : undefined,
+        });
+    }
+    /** Build the system prompt with specialist descriptions appended. */
+    buildSystemPrompt() {
+        const base = this.systemPromptText ?? 'You are an orchestrator. Route to the best specialist.';
+        const specialistList = this.specialists
+            .map((s) => `- ${s.id}: ${s.description}`)
+            .join('\n');
+        return `${base}\n\nYou have access to these specialist agents:\n${specialistList}\n\nCall the most appropriate specialist to handle the user's request. When done, respond directly without calling any specialist.`;
+    }
+    /** Build tool descriptions for specialist + extra tools. */
+    buildToolDescriptions() {
+        return [
+            ...this.specialists.map((s) => ({
+                name: s.id,
+                description: s.description,
+                inputSchema: {
+                    type: 'object',
+                    properties: { message: { type: 'string', description: 'The task or question to delegate.' } },
+                    required: ['message'],
+                },
+            })),
+            ...this.extraTools.map((t) => ({
+                name: t.id,
+                description: t.description,
+                inputSchema: t.inputSchema,
+            })),
+        ];
+    }
+    /** Build AgentLoopConfig — Swarm uses the same loop as Agent with custom routing. */
+    buildConfig() {
+        const toolDescs = this.toolDescs;
+        return {
+            provider: this.provider,
+            systemPrompt: { provider: staticPrompt(this.fullSystemPrompt) },
+            messages: { strategy: slidingWindow({ maxMessages: 50 }) },
+            tools: {
+                provider: {
+                    resolve: (_context) => ({ value: toolDescs, chosen: 'swarm-specialists' }),
+                },
+            },
+            registry: new ToolRegistry(),
+            maxIterations: this.maxIter,
+            streaming: this.streamingEnabled,
+            routing: this.routingConfig,
+        };
+    }
+    /** Expose the swarm's internal flowChart for subflow composition. */
+    toFlowChart() {
+        const { chart, spec } = this.buildLoop('');
+        this.lastSpec = annotateSpecIcons(spec);
+        return chart;
+    }
+    buildLoop(message) {
+        const config = this.buildConfig();
+        return buildAgentLoop(config, {
+            messages: message ? [userMessage(message)] : [],
+            existingMessages: this.conversationHistory,
+        }, { captureSpec: true });
+    }
+    async run(message, options) {
+        const startTime = Date.now();
+        const { chart, spec } = this.buildLoop(message);
+        this.lastSpec = annotateSpecIcons(spec);
+        const executorOpts = { enrichSnapshots: true };
+        if (options?.onToken && this.streamingEnabled) {
+            executorOpts.streamHandlers = {
+                onToken: (_streamId, token) => options.onToken(token),
+                onStart: () => { },
+                onEnd: () => { },
+            };
+        }
+        const executor = new FlowChartExecutor(chart, executorOpts);
+        executor.enableNarrative({ renderer: this.narrativeRenderer });
+        executor.attachRecorder(new MetricRecorder('metrics'));
+        // Wire AgentRecorders via RecorderBridge
+        const bridge = this.recorders.length > 0 ? new RecorderBridge(this.recorders) : null;
+        bridge?.dispatchTurnStart(message);
+        try {
+            await executor.run({
+                signal: options?.signal,
+                timeoutMs: options?.timeoutMs,
+            });
+        }
+        catch (err) {
+            this.lastExecutor = executor;
+            // Update conversation history with whatever partial state exists
+            const partialState = executor.getSnapshot()?.sharedState ?? {};
+            const partialMessages = partialState.messages;
+            if (partialMessages)
+                this.conversationHistory = partialMessages;
+            bridge?.dispatchError('llm', err);
+            throw err;
+        }
+        this.lastExecutor = executor;
+        const snapshot = executor.getSnapshot();
+        const state = snapshot?.sharedState ?? {};
+        const result = state.result ?? '';
+        const messages = state.messages ?? [];
+        // Structural specialist tracking — read from scope with runtime validation
+        const rawInvoked = state.invokedSpecialists;
+        const invokedIds = Array.isArray(rawInvoked) ? rawInvoked.filter((x) => typeof x === 'string') : [];
+        const agents = invokedIds.map((id) => ({
+            id,
+            name: id,
+            content: '',
+            latencyMs: 0,
+        }));
+        // Update conversation history for multi-turn
+        this.conversationHistory = messages;
+        // Dispatch recorder events
+        bridge?.dispatchTurnComplete(result, messages.length, state.loopCount ?? 0);
+        return {
+            content: result,
+            agents,
+            totalLatencyMs: Date.now() - startTime,
+        };
+    }
+    /** Get conversation history (for multi-turn). */
+    getMessages() {
+        return [...this.conversationHistory];
+    }
+    /** Reset conversation state for a fresh conversation. */
+    resetConversation() {
+        this.conversationHistory = [];
+    }
+    getNarrative() {
+        return this.lastExecutor?.getNarrative() ?? [];
+    }
+    getNarrativeEntries() {
+        return this.lastExecutor?.getNarrativeEntries() ?? [];
+    }
+    getSnapshot() {
+        return this.lastExecutor?.getSnapshot();
+    }
+    getSpec() {
+        if (!this.lastSpec) {
+            const { spec } = this.buildLoop('');
+            this.lastSpec = annotateSpecIcons(spec);
+        }
+        return this.lastSpec;
+    }
+}
+//# sourceMappingURL=Swarm.js.map

package/dist/esm/concepts/Swarm.js.map

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

package/dist/esm/concepts/index.js

@@ -0,0 +1,8 @@
+// Agent rebuilt on library-of-libraries architecture (src/lib/)
+export { Agent, AgentRunner } from '../lib/concepts';
+export { LLMCall, LLMCallRunner } from './LLMCall';
+export { RAG, RAGRunner } from './RAG';
+export { FlowChart, FlowChartRunner } from './FlowChart';
+export { Swarm, SwarmRunner } from './Swarm';
+export { Parallel, ParallelRunner } from './Parallel';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/concepts/index.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAErD,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE7C,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/esm/concepts/specIcons.js

@@ -0,0 +1,44 @@
+/**
+ * Annotates a pipeline spec tree with semantic icon hints for visualization.
+ * Icons are matched by stage ID — unknown IDs are left without an icon.
+ * Mutates the spec in-place and returns it for chaining.
+ */
+/** Well-known stage ID → icon mapping for agent concepts. */
+const ICON_MAP = {
+    // API slot stages
+    'system-prompt': 'start',
+    'messages': 'memory',
+    'seed': 'start',
+    // Call stages
+    'call-llm': 'llm',
+    'parse': 'parse',
+    'parse-response': 'parse',
+    'finalize': 'end',
+    'handle-response': 'tool',
+    // Agent loop stages
+    'assemble-prompt': 'process',
+    'apply-prepared-messages': 'memory',
+    'commit-memory': 'memory',
+    // RAG-specific
+    'retrieve': 'rag',
+    'augment-prompt': 'process',
+};
+export function annotateSpecIcons(spec, extraIcons) {
+    const icons = extraIcons ? { ...ICON_MAP, ...extraIcons } : ICON_MAP;
+    walkSpec(spec, icons);
+    return spec;
+}
+function walkSpec(node, icons) {
+    if (node.id && icons[node.id] && !node.icon) {
+        node.icon = icons[node.id];
+    }
+    if (node.children) {
+        for (const child of node.children)
+            walkSpec(child, icons);
+    }
+    if (node.next)
+        walkSpec(node.next, icons);
+    if (node.subflowStructure)
+        walkSpec(node.subflowStructure, icons);
+}
+//# sourceMappingURL=specIcons.js.map

package/dist/esm/concepts/specIcons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specIcons.js","sourceRoot":"","sources":["../../../src/concepts/specIcons.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,6DAA6D;AAC7D,MAAM,QAAQ,GAA2B;IACvC,kBAAkB;IAClB,eAAe,EAAE,OAAO;IACxB,UAAU,EAAE,QAAQ;IACpB,MAAM,EAAE,OAAO;IAEf,cAAc;IACd,UAAU,EAAE,KAAK;IACjB,OAAO,EAAE,OAAO;IAChB,gBAAgB,EAAE,OAAO;IACzB,UAAU,EAAE,KAAK;IACjB,iBAAiB,EAAE,MAAM;IAEzB,oBAAoB;IACpB,iBAAiB,EAAE,SAAS;IAC5B,yBAAyB,EAAE,QAAQ;IACnC,eAAe,EAAE,QAAQ;IAEzB,eAAe;IACf,UAAU,EAAE,KAAK;IACjB,gBAAgB,EAAE,SAAS;CAC5B,CAAC;AAUF,MAAM,UAAU,iBAAiB,CAC/B,IAAO,EACP,UAAmC;IAEnC,MAAM,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,QAAQ,EAAE,GAAG,UAAU,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;IACrE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACtB,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,QAAQ,CAAC,IAAc,EAAE,KAA6B;IAC7D,IAAI,IAAI,CAAC,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5C,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC7B,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;YAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC5D,CAAC;IACD,IAAI,IAAI,CAAC,IAAI;QAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC1C,IAAI,IAAI,CAAC,gBAAgB;QAAE,QAAQ,CAAC,IAAI,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;AACpE,CAAC"}

package/dist/esm/core/config.js

@@ -0,0 +1,6 @@
+/**
+ * AgentLoopConfig — everything the core loop needs to run.
+ * Assembled by builders (Agent.create(), etc.).
+ */
+export {};
+//# sourceMappingURL=config.js.map

package/dist/esm/core/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/core/config.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/esm/core/index.js

@@ -0,0 +1,13 @@
+/**
+ * core/ — Agent loop interfaces and types.
+ *
+ * The "traversal engine" of agentfootprint. Defines the provider
+ * and recorder interfaces that everything else plugs into.
+ *
+ * Three files:
+ *   providers.ts — active strategies (shape behavior)
+ *   recorders.ts — passive observers (watch behavior)
+ *   config.ts    — loop configuration
+ */
+export {};
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/esm/core/providers.js

@@ -0,0 +1,18 @@
+/**
+ * Provider interfaces — active strategies that shape what the LLM sees.
+ *
+ * Every provider resolves a value AND explains its decision via SlotDecision<T>.
+ * The decision (chosen + rationale) appears in the narrative — making every
+ * strategy choice explainable.
+ *
+ * @example
+ * ```typescript
+ * // Static provider — always returns the same value
+ * { value: 'You are helpful.', chosen: 'static' }
+ *
+ * // Dynamic provider — changes based on conversation state
+ * { value: [...adminTools], chosen: 'elevated', rationale: 'identity verified' }
+ * ```
+ */
+export {};
+//# sourceMappingURL=providers.js.map

package/dist/esm/core/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../../src/core/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/esm/core/recorders.js

@@ -0,0 +1,6 @@
+/**
+ * Recorder interface — passive observers that watch but don't shape behavior.
+ * Like Recorder/FlowRecorder in footprintjs.
+ */
+export {};
+//# sourceMappingURL=recorders.js.map

package/dist/esm/core/recorders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorders.js","sourceRoot":"","sources":["../../../src/core/recorders.ts"],"names":[],"mappings":"AAAA;;;GAGG"}