agentfootprint 1.0.0

package/dist/concepts/Swarm.js

@@ -0,0 +1,270 @@
+"use strict";
+/**
+ * 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."
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SwarmRunner = exports.Swarm = void 0;
+const footprintjs_1 = require("footprintjs");
+const loop_1 = require("../lib/loop");
+const buildSwarmRouting_1 = require("../lib/swarm/buildSwarmRouting");
+const static_1 = require("../providers/prompt/static");
+const slidingWindow_1 = require("../providers/messages/slidingWindow");
+const tools_1 = require("../tools");
+const narrative_1 = require("../lib/narrative");
+const RecorderBridge_1 = require("../recorders/v2/RecorderBridge");
+const specIcons_1 = require("./specIcons");
+const types_1 = require("../types");
+const createProvider_1 = require("../adapters/createProvider");
+// Specialist ID validation — alphanumeric + hyphens, max 64 chars
+const VALID_SPECIALIST_ID = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+// ── Builder ──────────────────────────────────────────────────
+class Swarm {
+    provider;
+    swarmName;
+    systemPromptText;
+    specialists = [];
+    extraTools = [];
+    recorders = [];
+    maxIter = 10;
+    streamingEnabled = false;
+    constructor(options) {
+        this.provider = (0, createProvider_1.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]);
+    }
+}
+exports.Swarm = Swarm;
+// ── Runner ───────────────────────────────────────────────────
+class SwarmRunner {
+    provider;
+    name;
+    systemPromptText;
+    specialists;
+    extraTools;
+    maxIter;
+    streamingEnabled;
+    recorders;
+    conversationHistory = [];
+    lastExecutor;
+    lastSpec;
+    narrativeRenderer = (0, narrative_1.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 = (0, buildSwarmRouting_1.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: (0, static_1.staticPrompt)(this.fullSystemPrompt) },
+            messages: { strategy: (0, slidingWindow_1.slidingWindow)({ maxMessages: 50 }) },
+            tools: {
+                provider: {
+                    resolve: (_context) => ({ value: toolDescs, chosen: 'swarm-specialists' }),
+                },
+            },
+            registry: new tools_1.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 = (0, specIcons_1.annotateSpecIcons)(spec);
+        return chart;
+    }
+    buildLoop(message) {
+        const config = this.buildConfig();
+        return (0, loop_1.buildAgentLoop)(config, {
+            messages: message ? [(0, types_1.userMessage)(message)] : [],
+            existingMessages: this.conversationHistory,
+        }, { captureSpec: true });
+    }
+    async run(message, options) {
+        const startTime = Date.now();
+        const { chart, spec } = this.buildLoop(message);
+        this.lastSpec = (0, specIcons_1.annotateSpecIcons)(spec);
+        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({ renderer: this.narrativeRenderer });
+        executor.attachRecorder(new footprintjs_1.MetricRecorder('metrics'));
+        // Wire AgentRecorders via RecorderBridge
+        const bridge = this.recorders.length > 0 ? new RecorderBridge_1.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 = (0, specIcons_1.annotateSpecIcons)(spec);
+        }
+        return this.lastSpec;
+    }
+}
+exports.SwarmRunner = SwarmRunner;
+//# sourceMappingURL=Swarm.js.map

package/dist/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/concepts/index.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ParallelRunner = exports.Parallel = exports.SwarmRunner = exports.Swarm = exports.FlowChartRunner = exports.FlowChart = exports.RAGRunner = exports.RAG = exports.LLMCallRunner = exports.LLMCall = exports.AgentRunner = exports.Agent = void 0;
+// Agent rebuilt on library-of-libraries architecture (src/lib/)
+var concepts_1 = require("../lib/concepts");
+Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return concepts_1.Agent; } });
+Object.defineProperty(exports, "AgentRunner", { enumerable: true, get: function () { return concepts_1.AgentRunner; } });
+var LLMCall_1 = require("./LLMCall");
+Object.defineProperty(exports, "LLMCall", { enumerable: true, get: function () { return LLMCall_1.LLMCall; } });
+Object.defineProperty(exports, "LLMCallRunner", { enumerable: true, get: function () { return LLMCall_1.LLMCallRunner; } });
+var RAG_1 = require("./RAG");
+Object.defineProperty(exports, "RAG", { enumerable: true, get: function () { return RAG_1.RAG; } });
+Object.defineProperty(exports, "RAGRunner", { enumerable: true, get: function () { return RAG_1.RAGRunner; } });
+var FlowChart_1 = require("./FlowChart");
+Object.defineProperty(exports, "FlowChart", { enumerable: true, get: function () { return FlowChart_1.FlowChart; } });
+Object.defineProperty(exports, "FlowChartRunner", { enumerable: true, get: function () { return FlowChart_1.FlowChartRunner; } });
+var Swarm_1 = require("./Swarm");
+Object.defineProperty(exports, "Swarm", { enumerable: true, get: function () { return Swarm_1.Swarm; } });
+Object.defineProperty(exports, "SwarmRunner", { enumerable: true, get: function () { return Swarm_1.SwarmRunner; } });
+var Parallel_1 = require("./Parallel");
+Object.defineProperty(exports, "Parallel", { enumerable: true, get: function () { return Parallel_1.Parallel; } });
+Object.defineProperty(exports, "ParallelRunner", { enumerable: true, get: function () { return Parallel_1.ParallelRunner; } });
+//# sourceMappingURL=index.js.map

package/dist/concepts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/concepts/index.ts"],"names":[],"mappings":";;;AAAA,gEAAgE;AAChE,4CAAqD;AAA5C,iGAAA,KAAK,OAAA;AAAE,uGAAA,WAAW,OAAA;AAE3B,qCAAmD;AAA1C,kGAAA,OAAO,OAAA;AAAE,wGAAA,aAAa,OAAA;AAE/B,6BAAuC;AAA9B,0FAAA,GAAG,OAAA;AAAE,gGAAA,SAAS,OAAA;AAEvB,yCAAyD;AAAhD,sGAAA,SAAS,OAAA;AAAE,4GAAA,eAAe,OAAA;AACnC,iCAA6C;AAApC,8FAAA,KAAK,OAAA;AAAE,oGAAA,WAAW,OAAA;AAE3B,uCAAsD;AAA7C,oGAAA,QAAQ,OAAA;AAAE,0GAAA,cAAc,OAAA"}

package/dist/concepts/specIcons.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.annotateSpecIcons = void 0;
+/** 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',
+};
+function annotateSpecIcons(spec, extraIcons) {
+    const icons = extraIcons ? { ...ICON_MAP, ...extraIcons } : ICON_MAP;
+    walkSpec(spec, icons);
+    return spec;
+}
+exports.annotateSpecIcons = annotateSpecIcons;
+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/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,SAAgB,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;AAPD,8CAOC;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/core/config.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * AgentLoopConfig — everything the core loop needs to run.
+ * Assembled by builders (Agent.create(), etc.).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=config.js.map

package/dist/core/config.js.map

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

package/dist/core/index.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/dist/core/index.js.map

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

package/dist/core/providers.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * 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' }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=providers.js.map

package/dist/core/providers.js.map

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

package/dist/core/recorders.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Recorder interface — passive observers that watch but don't shape behavior.
+ * Like Recorder/FlowRecorder in footprintjs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=recorders.js.map

package/dist/core/recorders.js.map

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

package/dist/esm/adapters/a2a/a2aRunner.js

@@ -0,0 +1,32 @@
+/**
+ * a2aRunner — wraps an A2A (Agent-to-Agent) endpoint as a RunnerLike.
+ *
+ * A2A protocol enables agents to communicate across services.
+ * This adapter bridges the A2A interface to agentfootprint's RunnerLike,
+ * enabling composition in FlowChart, Swarm, or agentAsTool.
+ *
+ * The adapter accepts an A2AClient interface (transport-agnostic).
+ * Users provide their own A2A client implementation.
+ *
+ * Usage:
+ *   const remoteAgent = a2aRunner({
+ *     client: myA2AClient,
+ *     agentId: 'research-agent',
+ *   });
+ *   const pipeline = FlowChart.create()
+ *     .agent('remote-research', 'Research', remoteAgent)
+ *     .build();
+ */
+export function a2aRunner(options) {
+    const { client, agentId } = options;
+    return {
+        run: async (message, runOptions) => {
+            const response = await client.sendMessage(agentId, message, {
+                signal: runOptions?.signal,
+                timeoutMs: runOptions?.timeoutMs,
+            });
+            return { content: response.content };
+        },
+    };
+}
+//# sourceMappingURL=a2aRunner.js.map

package/dist/esm/adapters/a2a/a2aRunner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2aRunner.js","sourceRoot":"","sources":["../../../../src/adapters/a2a/a2aRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA8BH,MAAM,UAAU,SAAS,CAAC,OAAyB;IACjD,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAEpC,OAAO;QACL,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE;YACjC,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE;gBAC1D,MAAM,EAAE,UAAU,EAAE,MAAM;gBAC1B,SAAS,EAAE,UAAU,EAAE,SAAS;aACjC,CAAC,CAAC;YACH,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC;QACvC,CAAC;KACF,CAAC;AACJ,CAAC"}