agentfootprint 1.22.0 → 2.0.1

package/dist/esm/bridge/eventMeta.js

@@ -0,0 +1,57 @@
+/**
+ * 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).
+ */
+import { parseRuntimeStageId } from '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'.
+ */
+export 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(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 }),
+    };
+}
+/**
+ * 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).
+ */
+export function parseSubflowPath(raw) {
+    if (!raw)
+        return [];
+    return raw.split('/').filter((s) => s.length > 0);
+}
+//# sourceMappingURL=eventMeta.js.map

package/dist/esm/bridge/eventMeta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eventMeta.js","sourceRoot":"","sources":["../../../src/bridge/eventMeta.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAwCxD;;;;;;;GAOG;AACH,MAAM,UAAU,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,mBAAmB,CAAC,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;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,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"}

package/dist/esm/conventions.js

@@ -0,0 +1,101 @@
+/**
+ * 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.
+ */
+/** Subflow IDs — mounted by builders, observed by recorders. */
+export const 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. */
+export const 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. */
+export function isSlotSubflow(id) {
+    return (id === SUBFLOW_IDS.SYSTEM_PROMPT || id === SUBFLOW_IDS.MESSAGES || id === SUBFLOW_IDS.TOOLS);
+}
+/** Map a slot subflow id to its ContextSlot type. Undefined for non-slot ids. */
+export 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 SUBFLOW_IDS.SYSTEM_PROMPT:
+            return 'system-prompt';
+        case SUBFLOW_IDS.MESSAGES:
+            return 'messages';
+        case SUBFLOW_IDS.TOOLS:
+            return 'tools';
+        default:
+            return undefined;
+    }
+}
+/** True when an id is any of the library's known subflow IDs. */
+export function isKnownSubflow(id) {
+    return Object.values(SUBFLOW_IDS).includes(id);
+}
+/** True when an id is any of the library's known stage IDs. */
+export function isKnownStage(id) {
+    return Object.values(STAGE_IDS).includes(id);
+}
+/**
+ * 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.
+ */
+export const INJECTION_KEYS = {
+    SYSTEM_PROMPT: 'systemPromptInjections',
+    MESSAGES: 'messagesInjections',
+    TOOLS: 'toolsInjections',
+};
+/** Map a slot to its injection scope key. */
+export function injectionKeyForSlot(slot) {
+    switch (slot) {
+        case 'system-prompt':
+            return INJECTION_KEYS.SYSTEM_PROMPT;
+        case 'messages':
+            return INJECTION_KEYS.MESSAGES;
+        case 'tools':
+            return INJECTION_KEYS.TOOLS;
+    }
+}
+/** True when a scope key is any of the known injection keys. */
+export function isInjectionKey(key) {
+    return Object.values(INJECTION_KEYS).includes(key);
+}
+//# sourceMappingURL=conventions.js.map

package/dist/esm/conventions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../../src/conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,gEAAgE;AAChE,MAAM,CAAC,MAAM,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;AAC7D,MAAM,CAAC,MAAM,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,MAAM,UAAU,aAAa,CAC3B,EAAU;IAEV,OAAO,CACL,EAAE,KAAK,WAAW,CAAC,aAAa,IAAI,EAAE,KAAK,WAAW,CAAC,QAAQ,IAAI,EAAE,KAAK,WAAW,CAAC,KAAK,CAC5F,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,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,WAAW,CAAC,aAAa;YAC5B,OAAO,eAAe,CAAC;QACzB,KAAK,WAAW,CAAC,QAAQ;YACvB,OAAO,UAAU,CAAC;QACpB,KAAK,WAAW,CAAC,KAAK;YACpB,OAAO,OAAO,CAAC;QACjB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,cAAc,CAAC,EAAU;IACvC,OAAQ,MAAM,CAAC,MAAM,CAAC,WAAW,CAAc,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,YAAY,CAAC,EAAU;IACrC,OAAQ,MAAM,CAAC,MAAM,CAAC,SAAS,CAAc,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,aAAa,EAAE,wBAAwB;IACvC,QAAQ,EAAE,oBAAoB;IAC9B,KAAK,EAAE,iBAAiB;CAChB,CAAC;AAIX,6CAA6C;AAC7C,MAAM,UAAU,mBAAmB,CAAC,IAA4C;IAC9E,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,eAAe;YAClB,OAAO,cAAc,CAAC,aAAa,CAAC;QACtC,KAAK,UAAU;YACb,OAAO,cAAc,CAAC,QAAQ,CAAC;QACjC,KAAK,OAAO;YACV,OAAO,cAAc,CAAC,KAAK,CAAC;IAChC,CAAC;AACH,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAQ,MAAM,CAAC,MAAM,CAAC,cAAc,CAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;AACnE,CAAC"}