agentfootprint 2.7.3 → 2.8.1

package/dist/esm/strategies/index.js

@@ -0,0 +1,37 @@
+/**
+ * `agentfootprint/strategies` — typed strategy interfaces + default
+ * sinks for the v2.8 grouped-enabler architecture.
+ *
+ * See:
+ *   - `docs/inspiration/strategy-everywhere.md` — design memo + AWS-first roadmap
+ *   - `types.ts` — typed interfaces (Observability, Cost, LiveStatus, Lens)
+ *   - `defaults/` — the 4 in-core default strategies
+ *
+ * Vendor strategies ship under three GROUPED subpaths (matching the
+ * parallel-providers pattern v2.5 established for `llm-providers` /
+ * `tool-providers` / `memory-providers`). Each subpath holds N
+ * vendor-named factories — adding a vendor never adds a new subpath:
+ *
+ *   - `agentfootprint/observability-providers`
+ *       agentcoreObservability (v2.8.1)
+ *       cloudwatchObservability (v2.8.2)
+ *       xrayObservability (v2.8.3)
+ *       otelObservability (v2.9.x)
+ *       datadogObservability (v2.9.x)
+ *
+ *   - `agentfootprint/cost-providers`
+ *       stripeCost (v2.10.x)
+ *
+ *   - `agentfootprint/lens-providers`
+ *       browserLens / cliLens (v2.12.x)
+ *
+ * Each adapter lazy-imports its vendor SDK via `lib/lazyRequire.ts`,
+ * so consumers who never call a particular factory don't have to
+ * install that SDK. Peer-deps are declared in package.json with
+ * `peerDependenciesMeta.{name}.optional = true`.
+ */
+export * from './types.js';
+export * from './defaults/index.js';
+export { composeObservability, composeCost, composeLiveStatus, composeLens } from './compose.js';
+export { attachObservabilityStrategy, attachCostStrategy, attachLiveStatusStrategy, } from './attach.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/strategies/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AACjG,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,wBAAwB,GAIzB,MAAM,aAAa,CAAC"}

package/dist/esm/strategies/registry.js

@@ -0,0 +1,102 @@
+/**
+ * Strategy registry — name → factory for each of the 4 groups.
+ *
+ * Mirrors `src/cache/strategyRegistry.ts` exactly: maps a string name
+ * to a factory function that takes vendor-specific config and returns
+ * a typed strategy instance. Vendor adapter subpaths self-register on
+ * import via side-effect.
+ *
+ * Two ways consumers wire a strategy:
+ *
+ *   1. By NAME (registry lookup) — the recommended path for vendor
+ *      adapters:
+ *        ```ts
+ *        import 'agentfootprint/observability-datadog';  // self-registers 'datadog'
+ *        agent.enable.observability({ vendor: 'datadog', config: { apiKey } });
+ *        ```
+ *
+ *   2. By INSTANCE (explicit pass) — for custom in-house strategies
+ *      or test mocks:
+ *        ```ts
+ *        agent.enable.observability({ strategy: myCustomStrategy });
+ *        ```
+ *
+ * The two paths are mutually exclusive in `EnableOptions` — the type
+ * union enforces that consumers pick one.
+ *
+ * Lookup is exact-match by name (case-insensitive fallback). Unknown
+ * names return `undefined`; the consumer's `enable.X` then no-ops
+ * (per "do nothing if not configured" rule).
+ */
+// ─── 4 registries (one per group) ────────────────────────────────────
+const OBSERVABILITY_REGISTRY = new Map();
+const COST_REGISTRY = new Map();
+const LIVE_STATUS_REGISTRY = new Map();
+const LENS_REGISTRY = new Map();
+// ─── Register / lookup / list — observability ────────────────────────
+/**
+ * Register a vendor observability strategy by name. Called from the
+ * vendor's subpath at module load (side-effect import):
+ *
+ *   ```ts
+ *   // agentfootprint/observability-datadog/index.ts
+ *   import { registerObservabilityStrategy } from 'agentfootprint/strategies';
+ *   registerObservabilityStrategy('datadog', (config) => datadogObservability(config));
+ *   ```
+ *
+ * Replacing an existing registration is allowed — most-recent wins.
+ * Useful for test mocks.
+ */
+export function registerObservabilityStrategy(name, factory) {
+    OBSERVABILITY_REGISTRY.set(name, factory);
+}
+/** Look up an observability factory by vendor name. Case-insensitive
+ *  fallback. Returns `undefined` when the name is unknown — caller
+ *  decides to noop or throw. */
+export function getObservabilityStrategy(name) {
+    return OBSERVABILITY_REGISTRY.get(name) ?? OBSERVABILITY_REGISTRY.get(name.toLowerCase());
+}
+/** Diagnostic — list all registered vendor names. */
+export function listObservabilityStrategies() {
+    return [...OBSERVABILITY_REGISTRY.keys()];
+}
+// ─── Cost ────────────────────────────────────────────────────────────
+export function registerCostStrategy(name, factory) {
+    COST_REGISTRY.set(name, factory);
+}
+export function getCostStrategy(name) {
+    return COST_REGISTRY.get(name) ?? COST_REGISTRY.get(name.toLowerCase());
+}
+export function listCostStrategies() {
+    return [...COST_REGISTRY.keys()];
+}
+// ─── Live status ─────────────────────────────────────────────────────
+export function registerLiveStatusStrategy(name, factory) {
+    LIVE_STATUS_REGISTRY.set(name, factory);
+}
+export function getLiveStatusStrategy(name) {
+    return LIVE_STATUS_REGISTRY.get(name) ?? LIVE_STATUS_REGISTRY.get(name.toLowerCase());
+}
+export function listLiveStatusStrategies() {
+    return [...LIVE_STATUS_REGISTRY.keys()];
+}
+// ─── Lens ────────────────────────────────────────────────────────────
+export function registerLensStrategy(name, factory) {
+    LENS_REGISTRY.set(name, factory);
+}
+export function getLensStrategy(name) {
+    return LENS_REGISTRY.get(name) ?? LENS_REGISTRY.get(name.toLowerCase());
+}
+export function listLensStrategies() {
+    return [...LENS_REGISTRY.keys()];
+}
+// ─── Test helpers ────────────────────────────────────────────────────
+/** Reset every registry to empty. Tests only — not in the public
+ *  barrel. */
+export function _resetRegistriesForTests() {
+    OBSERVABILITY_REGISTRY.clear();
+    COST_REGISTRY.clear();
+    LIVE_STATUS_REGISTRY.clear();
+    LENS_REGISTRY.clear();
+}
+//# sourceMappingURL=registry.js.map

package/dist/esm/strategies/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../src/strategies/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAmBH,wEAAwE;AAExE,MAAM,sBAAsB,GAAG,IAAI,GAAG,EAAgC,CAAC;AACvE,MAAM,aAAa,GAAG,IAAI,GAAG,EAAuB,CAAC;AACrD,MAAM,oBAAoB,GAAG,IAAI,GAAG,EAA6B,CAAC;AAClE,MAAM,aAAa,GAAG,IAAI,GAAG,EAAuB,CAAC;AAErD,wEAAwE;AAExE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,6BAA6B,CAAC,IAAY,EAAE,OAA6B;IACvF,sBAAsB,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC;AAED;;gCAEgC;AAChC,MAAM,UAAU,wBAAwB,CAAC,IAAY;IACnD,OAAO,sBAAsB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,sBAAsB,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;AAC5F,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,2BAA2B;IACzC,OAAO,CAAC,GAAG,sBAAsB,CAAC,IAAI,EAAE,CAAC,CAAC;AAC5C,CAAC;AAED,wEAAwE;AAExE,MAAM,UAAU,oBAAoB,CAAC,IAAY,EAAE,OAAoB;IACrE,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;AAC1E,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO,CAAC,GAAG,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;AACnC,CAAC;AAED,wEAAwE;AAExE,MAAM,UAAU,0BAA0B,CAAC,IAAY,EAAE,OAA0B;IACjF,oBAAoB,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,OAAO,oBAAoB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,oBAAoB,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;AACxF,CAAC;AAED,MAAM,UAAU,wBAAwB;IACtC,OAAO,CAAC,GAAG,oBAAoB,CAAC,IAAI,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED,wEAAwE;AAExE,MAAM,UAAU,oBAAoB,CAAC,IAAY,EAAE,OAAoB;IACrE,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;AAC1E,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO,CAAC,GAAG,aAAa,CAAC,IAAI,EAAE,CAAC,CAAC;AACnC,CAAC;AAED,wEAAwE;AAExE;cACc;AACd,MAAM,UAAU,wBAAwB;IACtC,sBAAsB,CAAC,KAAK,EAAE,CAAC;IAC/B,aAAa,CAAC,KAAK,EAAE,CAAC;IACtB,oBAAoB,CAAC,KAAK,EAAE,CAAC;IAC7B,aAAa,CAAC,KAAK,EAAE,CAAC;AACxB,CAAC"}

package/dist/esm/strategies/types.js

@@ -0,0 +1,36 @@
+/**
+ * Strategy interface types for the v2.8 grouped-enabler architecture.
+ *
+ * Pattern: Strategy + Bridge + Hexagonal port. See the design memo
+ *          `docs/inspiration/strategy-everywhere.md`.
+ *
+ * Four groups, four typed strategy interfaces. Each follows the same
+ * shape (one canonical contract, locked at the type level):
+ *
+ *   1. `name: string`            — registry key for auto-registration
+ *   2. `capabilities: {...}`     — what this strategy supports
+ *   3. `onEvent(...)`            — hot path; sync, side-effect-only
+ *   4. `flush?(): Promise<void>` — optional batch flushing
+ *   5. `stop?(): void`           — optional teardown
+ *
+ * Design constraints (from the panel review):
+ *   - **PASSIVE / non-blocking by construction.** Strategies are
+ *     observers — they NEVER block the agent loop. Async work
+ *     (HTTP shipment, disk I/O, batching) is the STRATEGY's internal
+ *     concern: buffer in `onEvent` (sync), drain in `flush()` (async
+ *     OK). The dispatcher never awaits a strategy's `onEvent`.
+ *   - `onEvent` MUST be sync `void`. MUST NOT throw. Errors caught +
+ *     routed to `_onError` at the dispatch layer; one bad strategy
+ *     never breaks the agent loop.
+ *   - Idempotent registration — registering the same `name` twice
+ *     replaces, doesn't double-fire.
+ *   - `stop()` is idempotent — halts everything that strategy enabled,
+ *     nothing else, calling twice is a no-op.
+ *   - `flush()` is optional, may be sync OR async — strategies that
+ *     don't batch can omit it. Consumer's `agent.run()` lifecycle
+ *     calls flush at boundary points (turn end, run end) so batched
+ *     strategies don't lose tail events. Flush is the ONLY async
+ *     path; the hot path is always sync.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/strategies/types.js.map

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

package/dist/observability-providers.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * agentfootprint/observability-providers — vendor observability strategies.
+ *
+ * Grouped subpath following the parallel-providers pattern v2.5
+ * established for `llm-providers` / `tool-providers` /
+ * `memory-providers`. Adding a new vendor adds an export here, NOT
+ * a new subpath — keeps `package.json#exports` from sprawling.
+ *
+ * Each adapter lazy-imports its vendor SDK via `lib/lazyRequire.ts`,
+ * so consumers who never call a particular factory don't have to
+ * install that SDK. Peer-deps are declared in package.json with
+ * `peerDependenciesMeta.{name}.optional = true`.
+ *
+ * @example
+ * ```ts
+ * import { agentcoreObservability } from 'agentfootprint/observability-providers';
+ * import { microtaskBatchDriver } from 'footprintjs/detach';
+ *
+ * agent.enable.observability({
+ *   strategy: agentcoreObservability({
+ *     region: 'us-east-1',
+ *     logGroupName: '/agentfootprint/my-agent',
+ *   }),
+ *   // Recommended — keeps the agent loop unblocked by network latency.
+ *   detach: { driver: microtaskBatchDriver, mode: 'forget' },
+ * });
+ * ```
+ *
+ * Roadmap:
+ *   - agentcoreObservability   ← v2.8.1 (this release)
+ *   - cloudwatchObservability  ← v2.8.2
+ *   - xrayObservability        ← v2.8.3
+ *   - otelObservability        ← v2.9.x
+ *   - datadogObservability     ← v2.9.x
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentcoreObservability = void 0;
+var agentcore_js_1 = require("./adapters/observability/agentcore.js");
+Object.defineProperty(exports, "agentcoreObservability", { enumerable: true, get: function () { return agentcore_js_1.agentcoreObservability; } });
+//# sourceMappingURL=observability-providers.js.map

package/dist/observability-providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability-providers.js","sourceRoot":"","sources":["../src/observability-providers.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;;;AAEH,sEAG+C;AAF7C,sHAAA,sBAAsB,OAAA"}

package/dist/strategies/attach.js

@@ -0,0 +1,256 @@
+"use strict";
+/**
+ * Wire each grouped strategy to its data source on the dispatcher /
+ * recorder substrate. These are the 4 `enable.*` facades' actual
+ * implementations; `RunnerBase.enable` calls them with the right
+ * dispatcher / attach handle.
+ *
+ * Pattern: every facade follows the same shape:
+ *
+ *   1. Resolve strategy (consumer-supplied OR default)
+ *   2. Run `strategy.validate?()` — early-fail on misconfig (New Relic
+ *      panel review)
+ *   3. Set up subscription / projection
+ *   4. Apply per-strategy event-type filter (`relevantEventTypes`)
+ *   5. Apply per-call sample rate
+ *   6. Wrap calls in try/catch — route errors to `_onError` (passive
+ *      recorder rule: never throw to caller)
+ *   7. Return Unsubscribe (or handle for lens)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachLiveStatusStrategy = exports.attachCostStrategy = exports.attachObservabilityStrategy = void 0;
+const footprintjs_1 = require("footprintjs");
+const thinkingTemplates_js_1 = require("../recorders/observability/thinking/thinkingTemplates.js");
+// Registry-lookup helpers (`getObservabilityStrategy` etc.) are
+// defined in `./registry.js` and used by consumers via the
+// `enable.*({ vendor, config })` path elsewhere — not used in the
+// current attach() implementations, which take `opts.strategy` directly.
+/**
+ * Sentinel returned when consumer calls `enable.X()` without supplying
+ * a strategy or vendor. We DON'T auto-default — that would be an
+ * unwelcome opinion. Consumer chose to call `enable.X` but didn't hand
+ * us anywhere to ship; just no-op silently and return a stoppable
+ * unsubscribe so the call site stays composable.
+ */
+const NOOP_UNSUBSCRIBE = () => { };
+/** Build a one-stage flowchart that performs `args.work(event)` and
+ *  routes any thrown error to `args.onError`. The driver schedules
+ *  this chart per event. */
+function buildDetachWrapperChart(args) {
+    return (0, footprintjs_1.flowChart)('agentfootprint:detach:wrapper', async (scope) => {
+        const event = scope.$getArgs();
+        try {
+            args.work(event);
+        }
+        catch (err) {
+            args.onError?.(err instanceof Error ? err : new Error(String(err)), event);
+        }
+    }, 'wrap').build();
+}
+let detachExecutorSingleton;
+/** Lazy-import a shared `FlowChartExecutor` we use purely as the
+ *  bare-executor entry point for `detachAndForget` / `detachAndJoinLater`.
+ *  No chart actually runs through it — we just need its detach methods. */
+async function getDetachExecutor() {
+    if (detachExecutorSingleton)
+        return detachExecutorSingleton;
+    const fp = await Promise.resolve().then(() => __importStar(require('footprintjs')));
+    // Trivial host chart — never run, just satisfies the constructor.
+    const noopChart = fp.flowChart('agentfootprint:detach:host', async () => { }, 'host').build();
+    detachExecutorSingleton = new fp.FlowChartExecutor(noopChart);
+    return detachExecutorSingleton;
+}
+/**
+ * Build an event-handling function that respects `opts.detach`.
+ *
+ *   - `opts.detach` undefined → returns a sync handler that runs
+ *     `work(event)` inline and routes errors to `onError`. Same as
+ *     pre-v2.8 behavior.
+ *
+ *   - `opts.detach` set → returns a handler that schedules a wrapper
+ *     chart on the driver. `mode === 'forget'` discards the handle;
+ *     `mode === 'join-later'` delivers it to `opts.detach.onHandle`.
+ *
+ * The detached path is async-loaded — the executor singleton is built
+ * on first call so consumers who don't enable detach pay zero cost.
+ */
+function buildEventHandler(detach, args) {
+    if (!detach) {
+        // Sync path — current behavior.
+        return (event) => {
+            try {
+                args.work(event);
+            }
+            catch (err) {
+                args.onError?.(err instanceof Error ? err : new Error(String(err)), event);
+            }
+        };
+    }
+    // Detached path — schedule via the driver. We need the wrapper chart
+    // (for the runChild side) and the executor (for the bare-executor
+    // entry point that returns / discards the handle).
+    const wrapperChart = buildDetachWrapperChart(args);
+    const mode = detach.mode ?? 'forget';
+    const onHandle = detach.onHandle;
+    if (mode === 'join-later' && !onHandle) {
+        throw new TypeError(`[enable.*] detach.mode === 'join-later' requires \`onHandle\`. ` +
+            `Without it, the returned DetachHandle would be unreachable. ` +
+            `Pass \`onHandle: (h) => myHandles.push(h)\` (and await later via ` +
+            `Promise.all(myHandles.map(h => h.wait()))).`);
+    }
+    return (event) => {
+        // Lazy-resolve the executor. The Promise here is fire-and-forget
+        // itself — we never await it, so the agent loop returns sync. Any
+        // error from the import OR the schedule call routes to onError.
+        getDetachExecutor()
+            .then((exec) => {
+            if (mode === 'forget') {
+                exec.detachAndForget(detach.driver, wrapperChart, event);
+            }
+            else {
+                const handle = exec.detachAndJoinLater(detach.driver, wrapperChart, event);
+                onHandle(handle);
+            }
+        })
+            .catch((err) => {
+            args.onError?.(err instanceof Error ? err : new Error(String(err)), event);
+        });
+    };
+}
+const TIER_FILTER = {
+    minimal: (t) => t.startsWith('agentfootprint.error.') || t.startsWith('agentfootprint.agent.'),
+    standard: (t) => !t.startsWith('agentfootprint.stream.token'),
+    firehose: () => true,
+};
+function attachObservabilityStrategy(dispatcher, opts = {}) {
+    const strategy = opts.strategy;
+    // Consumer chose to call enable.observability() but didn't supply
+    // a strategy. Don't auto-default — that imposes an opinion. Just
+    // no-op so the call site stays composable.
+    if (!strategy)
+        return NOOP_UNSUBSCRIBE;
+    strategy.validate?.();
+    const tierFilter = TIER_FILTER[opts.tier ?? 'standard'];
+    const sampleRate = opts.sampleRate ?? 1;
+    const relevant = strategy.relevantEventTypes
+        ? new Set(strategy.relevantEventTypes)
+        : null;
+    // Build the event handler ONCE per attach call. Sync if no
+    // `opts.detach`; otherwise schedules on the driver so the agent
+    // loop never blocks on slow exporters.
+    const handle = buildEventHandler(opts.detach, {
+        work: (event) => strategy.exportEvent(event),
+        onError: (err, event) => strategy._onError?.(err, event),
+    });
+    return dispatcher.on('*', (event) => {
+        if (!tierFilter(event.type))
+            return;
+        if (relevant && !relevant.has(event.type))
+            return;
+        if (sampleRate < 1 && Math.random() > sampleRate)
+            return;
+        handle(event);
+    });
+}
+exports.attachObservabilityStrategy = attachObservabilityStrategy;
+/**
+ * Subscribe to `agentfootprint.cost.tick` events, project payload into
+ * the canonical `CostTick` shape, hand to strategy.
+ */
+function attachCostStrategy(dispatcher, opts = {}) {
+    const strategy = opts.strategy;
+    if (!strategy)
+        return NOOP_UNSUBSCRIBE;
+    strategy.validate?.();
+    // Cost strategy detach mirrors observability — sync by default,
+    // schedules on the driver when `opts.detach` is set. Useful when
+    // `recordCost` does heavy work (per-tick DB write, vendor budget
+    // API, etc.).
+    const handle = buildEventHandler(opts.detach, {
+        work: (tickInput) => strategy.recordCost(tickInput),
+        onError: (err, tickInput) => strategy._onError?.(err, tickInput),
+    });
+    return dispatcher.on('agentfootprint.cost.tick', (event) => {
+        const p = event.payload;
+        const tick = {
+            cumulativeInputTokens: Number(p.cumulativeInputTokens ?? 0),
+            cumulativeOutputTokens: Number(p.cumulativeOutputTokens ?? 0),
+            cumulativeCostUsd: Number(p.cumulativeCostUsd ?? 0),
+            recentInputTokens: Number(p.recentInputTokens ?? 0),
+            recentOutputTokens: Number(p.recentOutputTokens ?? 0),
+            recentCostUsd: Number(p.recentCostUsd ?? 0),
+            model: String(p.model ?? 'unknown'),
+            ...(typeof p.iteration === 'number' ? { iteration: p.iteration } : {}),
+            ...(typeof p.runtimeStageId === 'string' ? { runtimeStageId: p.runtimeStageId } : {}),
+        };
+        handle(tick);
+    });
+}
+exports.attachCostStrategy = attachCostStrategy;
+/**
+ * Subscribe to '*', maintain a rolling event log, project current
+ * thinking state on each event, render via templates, hand to strategy.
+ *
+ * Lower bound on emissions: dedupes — only fires `renderStatus` when
+ * the rendered line CHANGES (avoids floods on every token).
+ */
+/** Sliding-window cap for `attachLiveStatusStrategy`'s internal event
+ *  log. Long-lived agent servers would otherwise leak memory through
+ *  unbounded growth (per OTel SIG panel review). The cap is high
+ *  enough that `selectThinkingState` always sees the relevant recent
+ *  history. */
+const LIVE_STATUS_LOG_CAP = 1000;
+function attachLiveStatusStrategy(dispatcher, opts) {
+    opts.strategy.validate?.();
+    const templates = { ...thinkingTemplates_js_1.defaultThinkingTemplates, ...(opts.templates ?? {}) };
+    const ctx = { appName: opts.appName ?? 'Agent' };
+    const eventLog = [];
+    let lastLine = null;
+    return dispatcher.on('*', (event) => {
+        eventLog.push(event);
+        // Sliding-window — drop oldest when over cap. O(1) amortized
+        // because shift() runs only once per overflow.
+        while (eventLog.length > LIVE_STATUS_LOG_CAP)
+            eventLog.shift();
+        const state = (0, thinkingTemplates_js_1.selectThinkingState)(eventLog);
+        if (!state) {
+            lastLine = null;
+            return;
+        }
+        const line = (0, thinkingTemplates_js_1.renderThinkingLine)(state, ctx, templates);
+        if (line === null || line === lastLine)
+            return;
+        lastLine = line;
+        try {
+            opts.strategy.renderStatus({ line, state });
+        }
+        catch (err) {
+            opts.strategy._onError?.(err instanceof Error ? err : new Error(String(err)), event);
+        }
+    });
+}
+exports.attachLiveStatusStrategy = attachLiveStatusStrategy;
+//# sourceMappingURL=attach.js.map

package/dist/strategies/attach.js.map

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

package/dist/strategies/compose.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * `compose([...])` — fan-out combinator.
+ *
+ * Pattern: Composite. Same shape as React's children array, RxJS's
+ *          `merge`, OTel's `MultiSpanProcessor`. Pass an array of
+ *          strategies; get back a single strategy that fan-outs each
+ *          call to every child.
+ *
+ * Use when:
+ *   - Multi-vendor pipelines (`compose([datadog(), otel(), console()])`)
+ *   - Test instrumentation alongside production sink
+ *     (`compose([inMemorySink(), stripeBilling()])`) so test assertions
+ *     can read ticks while production also ships
+ *   - Tier-staging — local dev mirrors what production sees
+ *
+ * Per-child error isolation: if one child's `exportEvent` throws, the
+ * other children still receive the event. The throwing child's
+ * `_onError` is called (if present); otherwise the error is logged
+ * via `console.warn` once. One bad sink never breaks the chain.
+ *
+ * Capabilities are OR-ed across children — if any child supports a
+ * capability, the composite reports it as supported. The dispatcher
+ * uses this to decide whether to bother building event objects at all.
+ *
+ * Idempotent operations:
+ *   - `flush()` — calls every child's `flush()` (sync or async)
+ *     concurrently, awaits all
+ *   - `stop()` — calls every child's `stop()` once, in order; failures
+ *     in one child don't block the others
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeLens = exports.composeLiveStatus = exports.composeCost = exports.composeObservability = void 0;
+// ─── Internal helpers ────────────────────────────────────────────────
+/** Run `cb()` for every child; isolate errors via the child's
+ *  `_onError` or a single `console.warn`. */
+function safeForEach(children, cb) {
+    for (const child of children) {
+        try {
+            cb(child);
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            if (child._onError) {
+                try {
+                    child._onError(e);
+                }
+                catch {
+                    // Even _onError can throw; final fallback is silent drop —
+                    // we MUST NOT propagate to the caller (passive recorder rule).
+                }
+            }
+            else {
+                // eslint-disable-next-line no-console
+                console.warn('[compose] child threw and has no _onError:', e.message);
+            }
+        }
+    }
+}
+/** OR-merge a capability bag across children. Generic over the
+ *  concrete capability type — the runtime walk treats every entry as
+ *  `boolean | undefined` regardless of the typed shape. */
+function mergeCaps(children) {
+    const merged = {};
+    for (const c of children) {
+        for (const [k, v] of Object.entries(c.capabilities)) {
+            if (v === true)
+                merged[k] = true;
+        }
+    }
+    return merged;
+}
+/** Run every child's optional `flush` concurrently. */
+async function flushAll(children) {
+    const promises = [];
+    for (const c of children) {
+        if (!c.flush)
+            continue;
+        try {
+            const result = c.flush();
+            if (result instanceof Promise)
+                promises.push(result.catch(() => { }));
+        }
+        catch {
+            // ignore — passive recorder rule
+        }
+    }
+    if (promises.length > 0)
+        await Promise.all(promises);
+}
+function stopAll(children) {
+    for (const c of children) {
+        if (!c.stop)
+            continue;
+        try {
+            c.stop();
+        }
+        catch {
+            // ignore — passive recorder rule
+        }
+    }
+}
+// ─── Composite factories — one per strategy kind ─────────────────────
+/**
+ * Compose multiple ObservabilityStrategies into a single fan-out.
+ *
+ * @example
+ *   const all = composeObservability([
+ *     consoleObservability(),
+ *     datadogObservability({ apiKey }),
+ *     otelObservability(tracer),
+ *   ]);
+ */
+function composeObservability(children) {
+    return {
+        name: 'compose',
+        capabilities: mergeCaps(children),
+        exportEvent(event) {
+            safeForEach(children, (c) => c.exportEvent(event));
+        },
+        flush: () => flushAll(children),
+        stop: () => stopAll(children),
+    };
+}
+exports.composeObservability = composeObservability;
+/** Compose CostStrategies. */
+function composeCost(children) {
+    return {
+        name: 'compose',
+        capabilities: mergeCaps(children),
+        recordCost(tick) {
+            safeForEach(children, (c) => c.recordCost(tick));
+        },
+        flush: () => flushAll(children),
+        stop: () => stopAll(children),
+    };
+}
+exports.composeCost = composeCost;
+/** Compose LiveStatusStrategies. */
+function composeLiveStatus(children) {
+    return {
+        name: 'compose',
+        capabilities: mergeCaps(children),
+        renderStatus(update) {
+            safeForEach(children, (c) => c.renderStatus(update));
+        },
+        flush: () => flushAll(children),
+        stop: () => stopAll(children),
+    };
+}
+exports.composeLiveStatus = composeLiveStatus;
+/** Compose LensStrategies. */
+function composeLens(children) {
+    return {
+        name: 'compose',
+        capabilities: mergeCaps(children),
+        renderGraph(update) {
+            safeForEach(children, (c) => c.renderGraph(update));
+        },
+        flush: () => flushAll(children),
+        stop: () => stopAll(children),
+    };
+}
+exports.composeLens = composeLens;
+//# sourceMappingURL=compose.js.map