agentfootprint 1.23.0 → 2.1.0

package/dist/adapters/llm/OpenAIProvider.js

@@ -0,0 +1,353 @@
+"use strict";
+/**
+ * OpenAIProvider — wraps the `openai` SDK as an `LLMProvider`.
+ *
+ * Pattern: Adapter (GoF) + Ports-and-Adapters (Cockburn 2005).
+ * Role:    Outer ring — translates `LLMRequest`/`LLMResponse` to/from
+ *          OpenAI's Chat Completions API. Knows nothing about agents,
+ *          recorders, or compositions.
+ * Emits:   N/A.
+ *
+ * ─── 7-panel design review (2026-04-28) ─────────────────────────────
+ *
+ *   LLM-AI system design   ✓ Native function-calling. messages map
+ *                            1:1 to OpenAI shape (system/user/assistant/tool
+ *                            roles match) — minimal translation.
+ *   Performance            ✓ Single SDK call per `complete()`. Stream
+ *                            uses native SSE; deltas yielded as they
+ *                            arrive.
+ *   Scalability            ✓ Stateless; concurrent runs share one
+ *                            provider freely.
+ *   Research alignment     ✓ Mirrors v1 OpenAIAdapter conversion logic
+ *                            (origin/main `c6e11d0`); same usage
+ *                            normalization (prompt_tokens/completion_tokens
+ *                            → input/output).
+ *   Flexibility            ✓ `baseURL` enables OpenAI-compatible APIs
+ *                            (Ollama, Together, Groq, vLLM, LM Studio)
+ *                            without a separate adapter — see `ollama()`
+ *                            convenience factory below.
+ *   Abstraction-modular    ✓ Two converters (`toOpenAIMessages`,
+ *                            `fromOpenAIResponse`) isolate the
+ *                            shape-shifting; `complete()` and
+ *                            `stream()` reuse them.
+ *   Software engineering   ✓ Duck-typed SDK. Errors wrapped with
+ *                            provider tag. JSON-parsed tool args fall
+ *                            back to `{}` on malformed strings.
+ *
+ * ─── Limitations ────────────────────────────────────────────────────
+ *
+ * • Multi-modal NOT supported  (`LLMMessage.content` is
+ *   `string`). May extend in a future release.
+ * • `responseFormat` (JSON-mode) NOT exposed  — pass schema
+ *   instructions via `systemPrompt` for now.
+ *
+ * ─── 7-pattern test coverage ────────────────────────────────────────
+ *
+ *   See `test/adapters/unit/OpenAIProvider.test.ts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ollama = exports.OpenAIProvider = exports.openai = void 0;
+/**
+ * Build an `LLMProvider` backed by OpenAI's Chat Completions API.
+ *
+ * @example
+ *   import { Agent } from 'agentfootprint';
+ *   import { openai } from 'agentfootprint/providers';
+ *
+ *   const agent = Agent.create({
+ *     provider: openai({ defaultModel: 'gpt-4o' }),
+ *     model: 'openai',
+ *   })
+ *     .tool(searchTool)
+ *     .build();
+ */
+function openai(options = {}) {
+    const client = resolveClient(options);
+    const defaultModel = options.defaultModel ?? 'gpt-4o-mini';
+    const defaultMaxTokens = options.defaultMaxTokens;
+    const provider = {
+        name: 'openai',
+        async complete(req) {
+            const params = buildParams(req, defaultModel, defaultMaxTokens, false);
+            try {
+                const response = (await client.chat.completions.create(params));
+                return fromOpenAIResponse(response);
+            }
+            catch (err) {
+                throw wrapError(err);
+            }
+        },
+        async *stream(req) {
+            const params = buildParams(req, defaultModel, defaultMaxTokens, true);
+            let stream;
+            try {
+                stream = client.chat.completions.create(params);
+            }
+            catch (err) {
+                throw wrapError(err);
+            }
+            // Accumulate the streamed pieces so we can synthesize the
+            // authoritative LLMResponse on the terminal chunk. OpenAI streams
+            // tool_calls in chunks too — assemble id/name/args by index.
+            const textParts = [];
+            const toolCallsByIndex = new Map();
+            let lastFinishReason = null;
+            let lastUsage;
+            let lastId = '';
+            let tokenIndex = 0;
+            try {
+                for await (const chunk of stream) {
+                    const choice = chunk.choices[0];
+                    if (!choice)
+                        continue;
+                    if (chunk.id)
+                        lastId = chunk.id;
+                    if (chunk.usage)
+                        lastUsage = chunk.usage;
+                    if (choice.finish_reason)
+                        lastFinishReason = choice.finish_reason;
+                    const delta = choice.delta;
+                    if (delta.content) {
+                        textParts.push(delta.content);
+                        yield { tokenIndex, content: delta.content, done: false };
+                        tokenIndex++;
+                    }
+                    if (delta.tool_calls) {
+                        for (const tcDelta of delta.tool_calls) {
+                            const idx = tcDelta.index;
+                            const existing = toolCallsByIndex.get(idx) ?? { id: '', name: '', argsJson: '' };
+                            if (tcDelta.id)
+                                existing.id = tcDelta.id;
+                            if (tcDelta.function?.name)
+                                existing.name = tcDelta.function.name;
+                            if (tcDelta.function?.arguments)
+                                existing.argsJson += tcDelta.function.arguments;
+                            toolCallsByIndex.set(idx, existing);
+                        }
+                    }
+                }
+                const toolCalls = Array.from(toolCallsByIndex.values()).map((tc) => ({
+                    id: tc.id,
+                    name: tc.name,
+                    args: parseArgs(tc.argsJson),
+                }));
+                const response = {
+                    content: textParts.join(''),
+                    toolCalls,
+                    usage: {
+                        input: lastUsage?.prompt_tokens ?? 0,
+                        output: lastUsage?.completion_tokens ?? 0,
+                    },
+                    stopReason: normalizeStopReason(lastFinishReason ?? 'stop'),
+                    providerRef: lastId,
+                };
+                yield { tokenIndex, content: '', done: true, response };
+            }
+            catch (err) {
+                throw wrapError(err);
+            }
+        },
+    };
+    return provider;
+}
+exports.openai = openai;
+/**
+ * Class form for consumers who prefer `new OpenAIProvider(...)`.
+ */
+class OpenAIProvider {
+    name = 'openai';
+    inner;
+    constructor(options = {}) {
+        this.inner = openai(options);
+    }
+    complete(req) {
+        return this.inner.complete(req);
+    }
+    stream(req) {
+        if (!this.inner.stream)
+            throw new Error('stream() unavailable');
+        return this.inner.stream(req);
+    }
+}
+exports.OpenAIProvider = OpenAIProvider;
+/**
+ * Convenience factory for Ollama (OpenAI-compatible endpoint).
+ *
+ * @example
+ *   import { ollama } from 'agentfootprint/providers';
+ *
+ *   const provider = ollama({ defaultModel: 'llama3.2' });
+ *   // Talks to http://localhost:11434/v1 by default.
+ */
+function ollama(options = {}) {
+    const host = options.host ?? 'http://localhost:11434';
+    const inner = openai({
+        ...options,
+        baseURL: options.baseURL ?? `${host}/v1`,
+        apiKey: options.apiKey ?? 'ollama', // Ollama ignores the key; SDK requires non-empty.
+        defaultModel: options.defaultModel ?? 'llama3.2',
+    });
+    return { ...inner, name: 'ollama' };
+}
+exports.ollama = ollama;
+// ─── Internals ──────────────────────────────────────────────────────
+function resolveClient(options) {
+    if (options._client)
+        return options._client;
+    let OpenAI;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires, @typescript-eslint/no-require-imports
+        const mod = require('openai');
+        OpenAI = (mod.default ?? mod.OpenAI ?? mod);
+    }
+    catch {
+        throw new Error('OpenAIProvider requires the `openai` package.\n' +
+            '  Install:  npm install openai\n' +
+            '  Or pass `_client` for test injection.');
+    }
+    const apiKey = options.apiKey ?? process.env.OPENAI_API_KEY;
+    return new OpenAI({ apiKey, ...(options.baseURL && { baseURL: options.baseURL }) });
+}
+function buildParams(req, defaultModel, defaultMaxTokens, stream) {
+    const params = {
+        model: req.model === 'openai' || req.model === 'ollama' ? defaultModel : req.model,
+        messages: toOpenAIMessages(req.messages, req.systemPrompt),
+    };
+    if (stream)
+        params.stream = true;
+    if (req.tools && req.tools.length > 0)
+        params.tools = req.tools.map(toOpenAITool);
+    const maxTokens = req.maxTokens ?? defaultMaxTokens;
+    if (maxTokens !== undefined)
+        params.max_tokens = maxTokens;
+    if (req.temperature !== undefined)
+        params.temperature = req.temperature;
+    if (req.stop && req.stop.length > 0)
+        params.stop = [...req.stop];
+    return params;
+}
+/**
+ * messages → OpenAI messages.
+ *
+ * Roles map 1:1: system/user/assistant/tool. Assistant turns with
+ * `toolCalls` get those serialized into `message.tool_calls` (args
+ * JSON-stringified per OpenAI's contract). Tool messages map to
+ * `role: 'tool'` with `tool_call_id`.
+ */
+function toOpenAIMessages(messages, systemPrompt) {
+    const result = [];
+    // OpenAI accepts system role IN the messages array (unlike Anthropic's
+    // separate `system` field). Prepend systemPrompt as the first system
+    // message; subsequent in-message system entries pass through.
+    if (systemPrompt) {
+        result.push({ role: 'system', content: systemPrompt });
+    }
+    for (const m of messages) {
+        if (m.role === 'system') {
+            result.push({ role: 'system', content: m.content });
+            continue;
+        }
+        if (m.role === 'user') {
+            result.push({ role: 'user', content: m.content });
+            continue;
+        }
+        if (m.role === 'assistant') {
+            const msg = {
+                role: 'assistant',
+                content: m.content || null,
+            };
+            if (m.toolCalls && m.toolCalls.length > 0) {
+                msg.tool_calls = m.toolCalls.map((tc) => ({
+                    id: tc.id,
+                    type: 'function',
+                    function: {
+                        name: tc.name,
+                        arguments: JSON.stringify(tc.args),
+                    },
+                }));
+            }
+            result.push(msg);
+            continue;
+        }
+        if (m.role === 'tool') {
+            result.push({
+                role: 'tool',
+                content: m.content,
+                tool_call_id: m.toolCallId ?? '',
+            });
+            continue;
+        }
+    }
+    return result;
+}
+function toOpenAITool(schema) {
+    return {
+        type: 'function',
+        function: {
+            name: schema.name,
+            description: schema.description,
+            parameters: { ...schema.inputSchema },
+        },
+    };
+}
+function fromOpenAIResponse(response) {
+    const choice = response.choices[0];
+    if (!choice) {
+        throw new Error('[openai] response missing choices[0]');
+    }
+    const message = choice.message;
+    const toolCalls = (message.tool_calls ?? []).map((tc) => ({
+        id: tc.id,
+        name: tc.function.name,
+        args: parseArgs(tc.function.arguments),
+    }));
+    return {
+        content: message.content ?? '',
+        toolCalls,
+        usage: {
+            input: response.usage?.prompt_tokens ?? 0,
+            output: response.usage?.completion_tokens ?? 0,
+        },
+        stopReason: normalizeStopReason(choice.finish_reason),
+        providerRef: response.id,
+    };
+}
+function parseArgs(json) {
+    if (!json)
+        return {};
+    try {
+        const parsed = JSON.parse(json);
+        return typeof parsed === 'object' && parsed !== null ? parsed : {};
+    }
+    catch {
+        // Malformed JSON in tool args is rare but observed; surface empty
+        // args rather than crash. Consumers see the issue via the
+        // (still-arriving) tool-call event.
+        return {};
+    }
+}
+function normalizeStopReason(raw) {
+    switch (raw) {
+        case 'stop':
+            return 'stop';
+        case 'tool_calls':
+            return 'tool_use';
+        case 'length':
+            return 'max_tokens';
+        case 'content_filter':
+            return 'content_filter';
+        default:
+            return raw;
+    }
+}
+function wrapError(err) {
+    if (err instanceof Error) {
+        return Object.assign(new Error(`[openai] ${err.message}`), {
+            name: 'OpenAIProviderError',
+            cause: err,
+            status: err.status,
+        });
+    }
+    return new Error(`[openai] ${String(err)}`);
+}
+//# sourceMappingURL=OpenAIProvider.js.map

package/dist/adapters/llm/OpenAIProvider.js.map

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

package/dist/adapters/llm/createProvider.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * createProvider — by-name factory for any built-in LLMProvider.
+ *
+ * Pattern: Abstract Factory (GoF) over the concrete provider factories.
+ * Role:    Convenience entry point. Useful for config-driven setups
+ *          where the provider is chosen at runtime (env var, feature
+ *          flag, tenant preference).
+ * Emits:   N/A.
+ *
+ * @example
+ *   const provider = createProvider({
+ *     kind: process.env.LLM_PROVIDER ?? 'mock',
+ *     apiKey: process.env.LLM_API_KEY,
+ *     defaultModel: process.env.LLM_MODEL,
+ *   });
+ *
+ * For provider-specific options (Bedrock region, Ollama host, Browser
+ * apiUrl, etc.) construct the underlying factory directly — this
+ * helper deliberately exposes only the common subset.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProvider = void 0;
+const MockProvider_js_1 = require("./MockProvider.js");
+const AnthropicProvider_js_1 = require("./AnthropicProvider.js");
+const OpenAIProvider_js_1 = require("./OpenAIProvider.js");
+const BedrockProvider_js_1 = require("./BedrockProvider.js");
+const BrowserAnthropicProvider_js_1 = require("./BrowserAnthropicProvider.js");
+const BrowserOpenAIProvider_js_1 = require("./BrowserOpenAIProvider.js");
+/**
+ * Build any built-in LLMProvider from a tagged options object.
+ */
+function createProvider(options) {
+    switch (options.kind) {
+        case 'mock':
+            return (0, MockProvider_js_1.mock)(options);
+        case 'anthropic':
+            return (0, AnthropicProvider_js_1.anthropic)(options);
+        case 'openai':
+            return (0, OpenAIProvider_js_1.openai)(options);
+        case 'ollama':
+            return (0, OpenAIProvider_js_1.ollama)(options);
+        case 'bedrock':
+            return (0, BedrockProvider_js_1.bedrock)(options);
+        case 'browser-anthropic':
+            return (0, BrowserAnthropicProvider_js_1.browserAnthropic)(options);
+        case 'browser-openai':
+            return (0, BrowserOpenAIProvider_js_1.browserOpenai)(options);
+        default: {
+            // Exhaustiveness check — TypeScript will surface a missing case here.
+            const _exhaustive = options;
+            throw new Error(`createProvider: unknown kind ${JSON.stringify(_exhaustive.kind)}`);
+        }
+    }
+}
+exports.createProvider = createProvider;
+//# sourceMappingURL=createProvider.js.map

package/dist/adapters/llm/createProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createProvider.js","sourceRoot":"","sources":["../../../src/adapters/llm/createProvider.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;;AAGH,uDAAmE;AACnE,iEAAkF;AAClF,2DAAiF;AACjF,6DAA4E;AAC5E,+EAGuC;AACvC,yEAA8F;AA2B9F;;GAEG;AACH,SAAgB,cAAc,CAAC,OAA8B;IAC3D,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,MAAM;YACT,OAAO,IAAA,sBAAI,EAAC,OAAO,CAAC,CAAC;QACvB,KAAK,WAAW;YACd,OAAO,IAAA,gCAAS,EAAC,OAAO,CAAC,CAAC;QAC5B,KAAK,QAAQ;YACX,OAAO,IAAA,0BAAM,EAAC,OAAO,CAAC,CAAC;QACzB,KAAK,QAAQ;YACX,OAAO,IAAA,0BAAM,EAAC,OAAO,CAAC,CAAC;QACzB,KAAK,SAAS;YACZ,OAAO,IAAA,4BAAO,EAAC,OAAO,CAAC,CAAC;QAC1B,KAAK,mBAAmB;YACtB,OAAO,IAAA,8CAAgB,EAAC,OAAO,CAAC,CAAC;QACnC,KAAK,gBAAgB;YACnB,OAAO,IAAA,wCAAa,EAAC,OAAO,CAAC,CAAC;QAChC,OAAO,CAAC,CAAC,CAAC;YACR,sEAAsE;YACtE,MAAM,WAAW,GAAU,OAAO,CAAC;YACnC,MAAM,IAAI,KAAK,CACb,gCAAgC,IAAI,CAAC,SAAS,CAAE,WAAgC,CAAC,IAAI,CAAC,EAAE,CACzF,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAxBD,wCAwBC"}

package/dist/adapters/types.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * adapters/types — the Ports of the hexagonal architecture.
+ *
+ * Pattern: Adapter (GoF, Design Patterns ch. 4) + Ports-and-Adapters
+ *          (Cockburn, 2005).
+ * Role:    Contracts for every external dependency the library reaches for:
+ *          LLM providers, memory stores, context sources, embeddings,
+ *          guardrails, policy engines, pricing tables.
+ * Emits:   N/A (interfaces only).
+ *
+ * Concrete adapters (AnthropicProvider, PineconeStore, LlamaGuardDetector,
+ * ...) implement these contracts. `core/` and `core-flow/` depend only on
+ * these interfaces — never on concrete adapters.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/adapters/types.js.map

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

package/dist/bridge/eventMeta.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * eventMeta — build EventMeta from a footprintjs TraversalContext.
+ *
+ * Pattern: Adapter (GoF) — translates footprintjs's per-stage context into
+ *          agentfootprint's per-event metadata shape.
+ * Role:    Used by every core recorder to attach meta to emitted events.
+ * Emits:   N/A (helper only).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSubflowPath = exports.buildEventMeta = void 0;
+const trace_1 = require("footprintjs/trace");
+/**
+ * Build an EventMeta from a stage origin + run-level context.
+ *
+ * Accepts footprintjs's TraversalContext (FlowRecorder events), RecorderContext
+ * (WriteEvent / CommitEvent / etc.), or a bare StageOrigin. When the origin
+ * has no runtimeStageId (rare — manual emit during tests), the meta degrades
+ * gracefully to 'unknown#0'.
+ */
+function buildEventMeta(origin, run) {
+    const now = Date.now();
+    const runtimeStageId = origin?.runtimeStageId ?? 'unknown#0';
+    // Normalize subflowPath across the 3 shapes footprintjs uses:
+    //   - undefined (RecorderContext: derive from runtimeStageId)
+    //   - /-separated string (TraversalContext: parse)
+    //   - readonly string[] (EmitEvent: pass through)
+    const raw = origin?.subflowPath;
+    const subflowPath = Array.isArray(raw)
+        ? raw
+        : typeof raw === 'string'
+            ? parseSubflowPath(raw)
+            : parseSubflowPath((0, trace_1.parseRuntimeStageId)(runtimeStageId).subflowPath);
+    return {
+        wallClockMs: now,
+        runOffsetMs: now - run.runStartMs,
+        runtimeStageId,
+        subflowPath,
+        compositionPath: run.compositionPath,
+        runId: run.runId,
+        ...(run.traceId !== undefined && { traceId: run.traceId }),
+        ...(run.correlationId !== undefined && { correlationId: run.correlationId }),
+        ...(run.turnIndex !== undefined && { turnIndex: run.turnIndex }),
+        ...(run.iterIndex !== undefined && { iterIndex: run.iterIndex }),
+    };
+}
+exports.buildEventMeta = buildEventMeta;
+/**
+ * Parse footprintjs's `/`-separated subflow path into a readonly array.
+ *
+ * The source of truth for runtimeStageId parsing lives in footprintjs at
+ * `footprintjs/trace::parseRuntimeStageId`. We only need the path-split
+ * convenience here; the `/` separator is stable across footprintjs
+ * versions (covered by their `parseRuntimeStageId` tests).
+ */
+function parseSubflowPath(raw) {
+    if (!raw)
+        return [];
+    return raw.split('/').filter((s) => s.length > 0);
+}
+exports.parseSubflowPath = parseSubflowPath;
+//# sourceMappingURL=eventMeta.js.map

package/dist/bridge/eventMeta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventMeta.js","sourceRoot":"","sources":["../../src/bridge/eventMeta.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAGH,6CAAwD;AAwCxD;;;;;;;GAOG;AACH,SAAgB,cAAc,CAC5B,MAAkD,EAClD,GAAe;IAEf,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,cAAc,GAAG,MAAM,EAAE,cAAc,IAAI,WAAW,CAAC;IAC7D,8DAA8D;IAC9D,8DAA8D;IAC9D,mDAAmD;IACnD,kDAAkD;IAClD,MAAM,GAAG,GAAI,MAAkC,EAAE,WAAW,CAAC;IAC7D,MAAM,WAAW,GAAsB,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QACvD,CAAC,CAAC,GAAG;QACL,CAAC,CAAC,OAAO,GAAG,KAAK,QAAQ;YACzB,CAAC,CAAC,gBAAgB,CAAC,GAAG,CAAC;YACvB,CAAC,CAAC,gBAAgB,CAAC,IAAA,2BAAmB,EAAC,cAAc,CAAC,CAAC,WAAW,CAAC,CAAC;IACtE,OAAO;QACL,WAAW,EAAE,GAAG;QAChB,WAAW,EAAE,GAAG,GAAG,GAAG,CAAC,UAAU;QACjC,cAAc;QACd,WAAW;QACX,eAAe,EAAE,GAAG,CAAC,eAAe;QACpC,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,GAAG,CAAC,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;QAC1D,GAAG,CAAC,GAAG,CAAC,aAAa,KAAK,SAAS,IAAI,EAAE,aAAa,EAAE,GAAG,CAAC,aAAa,EAAE,CAAC;QAC5E,GAAG,CAAC,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC;QAChE,GAAG,CAAC,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC;KACjE,CAAC;AACJ,CAAC;AA5BD,wCA4BC;AAED;;;;;;;GAOG;AACH,SAAgB,gBAAgB,CAAC,GAAuB;IACtD,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IACpB,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACpD,CAAC;AAHD,4CAGC"}

package/dist/conventions.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * conventions — subflow + stage ID constants (builder↔recorder protocol).
+ *
+ * Pattern: Single Source of Truth constants (Ward Cunningham's SSOT).
+ * Role:    Contract between `core/` builders and `recorders/core/` observers.
+ *          Builders mount subflows with these IDs; recorders pattern-match
+ *          on the IDs to emit grouped domain events.
+ * Emits:   N/A (constants only).
+ *
+ * Rename any ID here → both builders and recorders stay in sync.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isInjectionKey = exports.injectionKeyForSlot = exports.INJECTION_KEYS = exports.isKnownStage = exports.isKnownSubflow = exports.slotFromSubflowId = exports.isSlotSubflow = exports.STAGE_IDS = exports.SUBFLOW_IDS = void 0;
+/** Subflow IDs — mounted by builders, observed by recorders. */
+exports.SUBFLOW_IDS = {
+    /** Injection Engine subflow. Evaluates every Injection's trigger
+     *  and writes activeInjections[] for the slot subflows to consume. */
+    INJECTION_ENGINE: 'sf-injection-engine',
+    /** System-prompt slot subflow. Observed by ContextRecorder. */
+    SYSTEM_PROMPT: 'sf-system-prompt',
+    /** Messages slot subflow. */
+    MESSAGES: 'sf-messages',
+    /** Tools slot subflow. */
+    TOOLS: 'sf-tools',
+    /** ReAct router subflow (inside Agent). */
+    ROUTE: 'sf-route',
+    /** Tool-call execution subflow (inside Agent loop). */
+    TOOL_CALLS: 'sf-tool-calls',
+    /** Merge step inside Parallel. */
+    MERGE: 'sf-merge',
+    /** Final-answer composition inside Agent. */
+    FINAL: 'sf-final',
+};
+/** Stage IDs — plain function stages that builders mount. */
+exports.STAGE_IDS = {
+    SEED: 'seed',
+    CALL_LLM: 'call-llm',
+    FINAL: 'final',
+    FORMAT_MERGE: 'format-merge',
+    MERGE_LLM: 'merge-llm',
+    EXTRACT_MERGE: 'extract-merge',
+};
+// ─── Type guards ─────────────────────────────────────────────────────
+/** True when a subflow id corresponds to one of the 3 context slots. */
+function isSlotSubflow(id) {
+    return (id === exports.SUBFLOW_IDS.SYSTEM_PROMPT || id === exports.SUBFLOW_IDS.MESSAGES || id === exports.SUBFLOW_IDS.TOOLS);
+}
+exports.isSlotSubflow = isSlotSubflow;
+/** Map a slot subflow id to its ContextSlot type. Undefined for non-slot ids. */
+function slotFromSubflowId(id) {
+    // Footprintjs prefixes nested subflow IDs with the parent's path
+    // (e.g., 'llm-call-internals/sf-system-prompt' when a slot subflow
+    // is mounted inside a wrapper subflow). Match the LAST segment so
+    // the convention works at any nesting depth.
+    const lastSegment = id.includes('/') ? id.slice(id.lastIndexOf('/') + 1) : id;
+    switch (lastSegment) {
+        case exports.SUBFLOW_IDS.SYSTEM_PROMPT:
+            return 'system-prompt';
+        case exports.SUBFLOW_IDS.MESSAGES:
+            return 'messages';
+        case exports.SUBFLOW_IDS.TOOLS:
+            return 'tools';
+        default:
+            return undefined;
+    }
+}
+exports.slotFromSubflowId = slotFromSubflowId;
+/** True when an id is any of the library's known subflow IDs. */
+function isKnownSubflow(id) {
+    return Object.values(exports.SUBFLOW_IDS).includes(id);
+}
+exports.isKnownSubflow = isKnownSubflow;
+/** True when an id is any of the library's known stage IDs. */
+function isKnownStage(id) {
+    return Object.values(exports.STAGE_IDS).includes(id);
+}
+exports.isKnownStage = isKnownStage;
+/**
+ * Scope-key convention for context injections.
+ *
+ * Each slot subflow writes its injections to a well-known scope key.
+ * ContextRecorder observes writes to these keys to emit context.injected
+ * events. Builders that mount slot subflows MUST write injections to the
+ * corresponding key; this is the data-level contract between builder and
+ * recorder.
+ */
+exports.INJECTION_KEYS = {
+    SYSTEM_PROMPT: 'systemPromptInjections',
+    MESSAGES: 'messagesInjections',
+    TOOLS: 'toolsInjections',
+};
+/** Map a slot to its injection scope key. */
+function injectionKeyForSlot(slot) {
+    switch (slot) {
+        case 'system-prompt':
+            return exports.INJECTION_KEYS.SYSTEM_PROMPT;
+        case 'messages':
+            return exports.INJECTION_KEYS.MESSAGES;
+        case 'tools':
+            return exports.INJECTION_KEYS.TOOLS;
+    }
+}
+exports.injectionKeyForSlot = injectionKeyForSlot;
+/** True when a scope key is any of the known injection keys. */
+function isInjectionKey(key) {
+    return Object.values(exports.INJECTION_KEYS).includes(key);
+}
+exports.isInjectionKey = isInjectionKey;
+//# sourceMappingURL=conventions.js.map

package/dist/conventions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../src/conventions.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAIH,gEAAgE;AACnD,QAAA,WAAW,GAAG;IACzB;0EACsE;IACtE,gBAAgB,EAAE,qBAAqB;IACvC,+DAA+D;IAC/D,aAAa,EAAE,kBAAkB;IACjC,6BAA6B;IAC7B,QAAQ,EAAE,aAAa;IACvB,0BAA0B;IAC1B,KAAK,EAAE,UAAU;IACjB,2CAA2C;IAC3C,KAAK,EAAE,UAAU;IACjB,uDAAuD;IACvD,UAAU,EAAE,eAAe;IAC3B,kCAAkC;IAClC,KAAK,EAAE,UAAU;IACjB,6CAA6C;IAC7C,KAAK,EAAE,UAAU;CACT,CAAC;AAIX,6DAA6D;AAChD,QAAA,SAAS,GAAG;IACvB,IAAI,EAAE,MAAM;IACZ,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,OAAO;IACd,YAAY,EAAE,cAAc;IAC5B,SAAS,EAAE,WAAW;IACtB,aAAa,EAAE,eAAe;CACtB,CAAC;AAIX,wEAAwE;AAExE,wEAAwE;AACxE,SAAgB,aAAa,CAC3B,EAAU;IAEV,OAAO,CACL,EAAE,KAAK,mBAAW,CAAC,aAAa,IAAI,EAAE,KAAK,mBAAW,CAAC,QAAQ,IAAI,EAAE,KAAK,mBAAW,CAAC,KAAK,CAC5F,CAAC;AACJ,CAAC;AAND,sCAMC;AAED,iFAAiF;AACjF,SAAgB,iBAAiB,CAAC,EAAU;IAC1C,iEAAiE;IACjE,mEAAmE;IACnE,kEAAkE;IAClE,6CAA6C;IAC7C,MAAM,WAAW,GAAG,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9E,QAAQ,WAAW,EAAE,CAAC;QACpB,KAAK,mBAAW,CAAC,aAAa;YAC5B,OAAO,eAAe,CAAC;QACzB,KAAK,mBAAW,CAAC,QAAQ;YACvB,OAAO,UAAU,CAAC;QACpB,KAAK,mBAAW,CAAC,KAAK;YACpB,OAAO,OAAO,CAAC;QACjB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAhBD,8CAgBC;AAED,iEAAiE;AACjE,SAAgB,cAAc,CAAC,EAAU;IACvC,OAAQ,MAAM,CAAC,MAAM,CAAC,mBAAW,CAAc,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAC/D,CAAC;AAFD,wCAEC;AAED,+DAA+D;AAC/D,SAAgB,YAAY,CAAC,EAAU;IACrC,OAAQ,MAAM,CAAC,MAAM,CAAC,iBAAS,CAAc,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAC7D,CAAC;AAFD,oCAEC;AAED;;;;;;;;GAQG;AACU,QAAA,cAAc,GAAG;IAC5B,aAAa,EAAE,wBAAwB;IACvC,QAAQ,EAAE,oBAAoB;IAC9B,KAAK,EAAE,iBAAiB;CAChB,CAAC;AAIX,6CAA6C;AAC7C,SAAgB,mBAAmB,CAAC,IAA4C;IAC9E,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,eAAe;YAClB,OAAO,sBAAc,CAAC,aAAa,CAAC;QACtC,KAAK,UAAU;YACb,OAAO,sBAAc,CAAC,QAAQ,CAAC;QACjC,KAAK,OAAO;YACV,OAAO,sBAAc,CAAC,KAAK,CAAC;IAChC,CAAC;AACH,CAAC;AATD,kDASC;AAED,gEAAgE;AAChE,SAAgB,cAAc,CAAC,GAAW;IACxC,OAAQ,MAAM,CAAC,MAAM,CAAC,sBAAc,CAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AACnE,CAAC;AAFD,wCAEC"}