agentfootprint 2.7.2 → 2.8.0

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

@@ -0,0 +1,31 @@
+/**
+ * Default strategies — the four "shipped in core" sinks.
+ *
+ *   `consoleObservability`   — print events to console
+ *   `inMemorySinkCost`       — accumulate cost ticks in a process-local buffer
+ *   `chatBubbleLiveStatus`   — call a consumer-supplied line callback
+ *   `noopLens`               — drop graph updates (zero-arg fallback)
+ *
+ * Vendor strategies (datadog, otel, agentcore, cloudwatch, …) ship as
+ * separate subpaths with peer-dep on the vendor SDK. See
+ * `docs/inspiration/strategy-everywhere.md` for the AWS-first roadmap.
+ *
+ * ─────────────────────────────────────────────────────────────────
+ * Why defaults skip `validate()`:
+ *
+ * The optional `BaseStrategy.validate()` hook is the right place for
+ * runtime config checks (API keys, endpoint reachability, peer-dep
+ * presence). Defaults skip it by design — their inputs are TypeScript-
+ * checked at construction, and they don't talk to a remote vendor that
+ * might be misconfigured.
+ *
+ * Vendor strategies that DO talk to a remote (datadog, agentcore,
+ * cloudwatch) MUST implement `validate()` per the New Relic panel
+ * review — early-fail-with-useful-message beats silent zero-emission.
+ * ─────────────────────────────────────────────────────────────────
+ */
+export { consoleObservability } from './consoleObservability.js';
+export { inMemorySinkCost, } from './inMemorySinkCost.js';
+export { chatBubbleLiveStatus } from './chatBubbleLiveStatus.js';
+export { noopLens } from './noopLens.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/strategies/defaults/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,oBAAoB,EAAoC,MAAM,2BAA2B,CAAC;AACnG,OAAO,EACL,gBAAgB,GAGjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,oBAAoB,EAAoC,MAAM,2BAA2B,CAAC;AACnG,OAAO,EAAE,QAAQ,EAAwB,MAAM,eAAe,CAAC"}

package/dist/esm/strategies/defaults/noopLens.js

@@ -0,0 +1,29 @@
+/**
+ * `noopLens()` — default LensStrategy.
+ *
+ * Pattern: Strategy. Wildcard fallback. Same role as `NoOpCacheStrategy`.
+ * Role:    Drops every update. Used when no Lens vendor strategy is
+ *          configured AND the consumer hasn't supplied a callback.
+ *          Keeps `enable.lens()` callable without args without
+ *          throwing — important for the zero-arg HelloWorld pattern.
+ *
+ * Use when:
+ *   - You want the agent to run without a Lens UI (production
+ *     server-side, headless eval, batch jobs)
+ *   - Tier-1 of compose chains where you want the chain to compile
+ *     even if the real Lens strategy is conditional
+ *
+ * Don't use when: you actually want to see the StepGraph. Use
+ * `lens-browser`, `lens-cli`, or `lens-jsonExport` from the
+ * vendor-strategy subpaths once they ship in v2.12+.
+ */
+export function noopLens(opts = {}) {
+    return {
+        name: 'noop-lens',
+        capabilities: { interactive: false, serializable: false },
+        renderGraph(update) {
+            opts.onUpdate?.(update);
+        },
+    };
+}
+//# sourceMappingURL=noopLens.js.map

package/dist/esm/strategies/defaults/noopLens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noopLens.js","sourceRoot":"","sources":["../../../../src/strategies/defaults/noopLens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAYH,MAAM,UAAU,QAAQ,CAAC,OAAwB,EAAE;IACjD,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,YAAY,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE;QACzD,WAAW,CAAC,MAAkB;YAC5B,IAAI,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAC;QAC1B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/esm/strategies/index.js

@@ -0,0 +1,23 @@
+/**
+ * `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 as separate subpaths:
+ *   - `agentfootprint/observability-agentcore` (v2.8.1)
+ *   - `agentfootprint/observability-cloudwatch` (v2.8.2)
+ *   - `agentfootprint/observability-xray` (v2.8.3)
+ *   - `agentfootprint/observability-otel` (v2.9.x)
+ *   - `agentfootprint/observability-datadog` (v2.9.x)
+ *   - `agentfootprint/cost-stripe` (v2.10.x)
+ *   - `agentfootprint/lens-browser` / `lens-cli` (v2.12.x)
+ */
+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;;;;;;;;;;;;;;;;;GAiBG;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/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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"}