agentfootprint 2.8.0 → 2.8.2

package/dist/adapters/observability/agentcore.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * agentcoreObservability — AWS Bedrock AgentCore observability adapter.
+ *
+ * Ships every `AgentfootprintEvent` to **CloudWatch Logs** in a
+ * structured-JSON shape AgentCore's hosted-agent telemetry layer
+ * understands. Use when:
+ *
+ *   1. Your agent runs INSIDE AgentCore — events show up alongside
+ *      AgentCore's own runtime telemetry in the same log group.
+ *   2. Your agent runs OUTSIDE AgentCore but you want to query agent
+ *      behavior in CloudWatch Insights / X-Ray traces using the same
+ *      schema AgentCore uses internally.
+ *
+ * Subpath:  `agentfootprint/observability-providers`
+ * Peer dep: `@aws-sdk/client-cloudwatch-logs` (OPTIONAL — installed
+ *           only when this adapter is used; declared via
+ *           `peerDependenciesMeta.{name}.optional = true`).
+ *
+ * **Implementation:** thin wrapper over `cloudwatchObservability`'s
+ * shared base. The only difference is the strategy `name` (used for
+ * registry lookup + diagnostics). All batching, flush, error-routing,
+ * and SDK-loading behavior is identical. As we evolve the CloudWatch
+ * shipping path (retry, sequence tokens, metrics emission), every
+ * CloudWatch-shaped adapter inherits the improvement.
+ *
+ * @example Basic
+ * ```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',
+ *     logStreamName: `${process.env.HOSTNAME}/${Date.now()}`,
+ *   }),
+ *   detach: { driver: microtaskBatchDriver, mode: 'forget' },
+ * });
+ * ```
+ *
+ * @example Test injection (skip SDK require entirely)
+ * ```ts
+ * agentcoreObservability({
+ *   _client: {
+ *     putLogEvents: async (input) => { capturedBatches.push(input); },
+ *   },
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentcoreObservability = void 0;
+const cloudwatch_js_1 = require("./cloudwatch.js");
+/**
+ * Build an AgentCore-flavored CloudWatch Logs observability strategy.
+ * Functionally identical to `cloudwatchObservability` except for the
+ * strategy `name`, which lets registry-lookup + diagnostics
+ * distinguish AgentCore-targeted shipping from generic CloudWatch.
+ */
+function agentcoreObservability(opts) {
+    return (0, cloudwatch_js_1._buildCloudWatchObservability)(opts, 'agentcore');
+}
+exports.agentcoreObservability = agentcoreObservability;
+//# sourceMappingURL=agentcore.js.map

package/dist/adapters/observability/agentcore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentcore.js","sourceRoot":"","sources":["../../../src/adapters/observability/agentcore.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;;;AAIH,mDAGyB;AAWzB;;;;;GAKG;AACH,SAAgB,sBAAsB,CAAC,IAAmC;IACxE,OAAO,IAAA,6CAA6B,EAAC,IAAI,EAAE,WAAW,CAAC,CAAC;AAC1D,CAAC;AAFD,wDAEC"}

package/dist/adapters/observability/cloudwatch.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * cloudwatchObservability — Generic AWS CloudWatch Logs adapter.
+ *
+ * Ships every `AgentfootprintEvent` to a CloudWatch Logs stream. Use
+ * when you want agent telemetry alongside the rest of your AWS
+ * observability stack — CloudWatch Insights queries, alarms,
+ * cross-service correlation. Same SDK as `agentcoreObservability`
+ * but **without** the AgentCore-specific defaults (log-stream
+ * convention, format opinions). Use this when:
+ *
+ *   1. You're shipping to CloudWatch but NOT running inside Bedrock
+ *      AgentCore (most common case).
+ *   2. You want full control over log group / stream / format and
+ *      don't need AgentCore's hosted-agent telemetry conventions.
+ *
+ * Subpath:  `agentfootprint/observability-providers`
+ * Peer dep: `@aws-sdk/client-cloudwatch-logs` (OPTIONAL — installed
+ *           only when this adapter is used; declared via
+ *           `peerDependenciesMeta.{name}.optional = true`).
+ *
+ * This module also exports the underlying base function used by
+ * `agentcoreObservability` — keeps the per-event hot path in one
+ * place so improvements (batching, retry, backpressure) flow to
+ * every CloudWatch-shaped adapter automatically.
+ *
+ * @example
+ * ```ts
+ * import { cloudwatchObservability } from 'agentfootprint/observability-providers';
+ * import { microtaskBatchDriver } from 'footprintjs/detach';
+ *
+ * agent.enable.observability({
+ *   strategy: cloudwatchObservability({
+ *     region: 'us-east-1',
+ *     logGroupName: '/myapp/agent-prod',
+ *     logStreamName: `${process.env.HOSTNAME}/${Date.now()}`,
+ *   }),
+ *   detach: { driver: microtaskBatchDriver, mode: 'forget' },
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cloudwatchObservability = exports._buildCloudWatchObservability = void 0;
+const lazyRequire_js_1 = require("../../lib/lazyRequire.js");
+// ─── Generic base — also used by agentcoreObservability ──────────────
+/**
+ * Internal: shared CloudWatch Logs base used by every adapter that
+ * ships to CWL. `cloudwatchObservability` is the public generic
+ * factory; `agentcoreObservability` calls this with AgentCore-flavored
+ * defaults.
+ *
+ * Exported for adapter authors only — consumers should call
+ * `cloudwatchObservability` or `agentcoreObservability` directly.
+ *
+ * @internal
+ */
+function _buildCloudWatchObservability(opts, strategyName) {
+    if (!opts.logGroupName) {
+        throw new TypeError(`[${strategyName}Observability] \`logGroupName\` is required. ` +
+            `Pass an existing CloudWatch log group, e.g. '/myapp/agent-prod'.`);
+    }
+    const logStreamName = opts.logStreamName ?? 'agentfootprint';
+    const maxBatchEvents = opts.maxBatchEvents ?? 100;
+    const maxBatchBytes = opts.maxBatchBytes ?? 10_240;
+    const flushIntervalMs = opts.flushIntervalMs ?? 1000;
+    // Buffered batch — drained by `flush()` / size-trigger / time-trigger.
+    const buffer = [];
+    let bufferBytes = 0;
+    let lastFlushPromise = Promise.resolve();
+    let timer;
+    let stopped = false;
+    let onErrorHook;
+    // Lazy-resolved on first flush so consumers who never trigger a
+    // flush (because nothing was emitted) don't even hit the SDK.
+    let client = opts._client;
+    function ensureClient() {
+        if (client)
+            return client;
+        client = createCloudWatchClient(opts.region, strategyName);
+        return client;
+    }
+    function scheduleTimedFlush() {
+        if (timer || flushIntervalMs <= 0 || stopped)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            void doFlush();
+        }, flushIntervalMs);
+    }
+    async function doFlush() {
+        if (buffer.length === 0 || stopped)
+            return;
+        // Snapshot + clear so concurrent emits during the in-flight put
+        // accumulate into the next batch.
+        const batch = buffer.splice(0);
+        bufferBytes = 0;
+        try {
+            await ensureClient().putLogEvents({
+                logGroupName: opts.logGroupName,
+                logStreamName,
+                logEvents: batch,
+            });
+        }
+        catch (err) {
+            onErrorHook?.(err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    function enqueue(event) {
+        if (stopped)
+            return;
+        const message = JSON.stringify(event);
+        const bytes = Buffer.byteLength(message, 'utf8');
+        buffer.push({ timestamp: Date.now(), message });
+        bufferBytes += bytes;
+        if (buffer.length >= maxBatchEvents || bufferBytes >= maxBatchBytes) {
+            // Size trigger — flush immediately. Chain onto last to preserve
+            // CloudWatch's per-stream ordering requirement.
+            lastFlushPromise = lastFlushPromise.then(doFlush, doFlush);
+        }
+        else {
+            scheduleTimedFlush();
+        }
+    }
+    return {
+        name: strategyName,
+        capabilities: { events: true, logs: true },
+        exportEvent: enqueue,
+        async flush() {
+            // Drain anything pending. Awaits both an in-flight put AND any
+            // newly-buffered events that arrived during it.
+            while (buffer.length > 0 || lastFlushPromise !== Promise.resolve()) {
+                const before = lastFlushPromise;
+                await before;
+                if (buffer.length > 0) {
+                    lastFlushPromise = doFlush();
+                }
+                // Loop one more pass if the chained doFlush() queued more
+                // work, then bail.
+                if (lastFlushPromise === before && buffer.length === 0)
+                    break;
+            }
+        },
+        stop() {
+            stopped = true;
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+        },
+        _onError(err, event) {
+            // Capture for use inside doFlush (the strategy doesn't know what
+            // the consumer's error sink is unless they wire `_onError` via
+            // the strategy options. We store it on this hook so put-failures
+            // route correctly).
+            onErrorHook =
+                onErrorHook ??
+                    ((e) => {
+                        // eslint-disable-next-line no-console
+                        console.error(`[${strategyName}Observability] flush failed:`, e.message);
+                    });
+            onErrorHook(err, event);
+        },
+    };
+}
+exports._buildCloudWatchObservability = _buildCloudWatchObservability;
+// ─── Public factory: cloudwatchObservability ─────────────────────────
+/**
+ * Generic CloudWatch Logs observability adapter. See
+ * `CloudwatchObservabilityOptions` for the per-option contract.
+ *
+ * For AgentCore-specific conventions, use `agentcoreObservability`
+ * which thin-wraps this with AgentCore-flavored defaults.
+ */
+function cloudwatchObservability(opts) {
+    return _buildCloudWatchObservability(opts, 'cloudwatch');
+}
+exports.cloudwatchObservability = cloudwatchObservability;
+// ─── SDK client construction (lazy) ──────────────────────────────────
+function createCloudWatchClient(region, strategyName) {
+    let mod;
+    try {
+        mod = (0, lazyRequire_js_1.lazyRequire)('@aws-sdk/client-cloudwatch-logs');
+    }
+    catch {
+        throw new Error(`[${strategyName}Observability] requires the \`@aws-sdk/client-cloudwatch-logs\` peer dependency.\n` +
+            `  Install:  npm install @aws-sdk/client-cloudwatch-logs\n` +
+            `  Or pass \`_client\` for test injection.`);
+    }
+    if (!mod.CloudWatchLogsClient || !mod.PutLogEventsCommand) {
+        throw new Error(`[${strategyName}Observability]: \`@aws-sdk/client-cloudwatch-logs\` is installed but ` +
+            `\`CloudWatchLogsClient\` / \`PutLogEventsCommand\` was not found. Update the SDK.`);
+    }
+    const sdkClient = new mod.CloudWatchLogsClient({ ...(region && { region }) });
+    return {
+        async putLogEvents(input) {
+            // Cast the SDK constructor to the call shape — same trick as
+            // the memory adapter to stay forward-compat with SDK shape drift.
+            const cmd = new mod.PutLogEventsCommand(input);
+            await sdkClient.send(cmd);
+        },
+    };
+}
+//# sourceMappingURL=cloudwatch.js.map

package/dist/adapters/observability/cloudwatch.js.map

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

package/dist/esm/adapters/observability/agentcore.js

@@ -0,0 +1,60 @@
+/**
+ * agentcoreObservability — AWS Bedrock AgentCore observability adapter.
+ *
+ * Ships every `AgentfootprintEvent` to **CloudWatch Logs** in a
+ * structured-JSON shape AgentCore's hosted-agent telemetry layer
+ * understands. Use when:
+ *
+ *   1. Your agent runs INSIDE AgentCore — events show up alongside
+ *      AgentCore's own runtime telemetry in the same log group.
+ *   2. Your agent runs OUTSIDE AgentCore but you want to query agent
+ *      behavior in CloudWatch Insights / X-Ray traces using the same
+ *      schema AgentCore uses internally.
+ *
+ * Subpath:  `agentfootprint/observability-providers`
+ * Peer dep: `@aws-sdk/client-cloudwatch-logs` (OPTIONAL — installed
+ *           only when this adapter is used; declared via
+ *           `peerDependenciesMeta.{name}.optional = true`).
+ *
+ * **Implementation:** thin wrapper over `cloudwatchObservability`'s
+ * shared base. The only difference is the strategy `name` (used for
+ * registry lookup + diagnostics). All batching, flush, error-routing,
+ * and SDK-loading behavior is identical. As we evolve the CloudWatch
+ * shipping path (retry, sequence tokens, metrics emission), every
+ * CloudWatch-shaped adapter inherits the improvement.
+ *
+ * @example Basic
+ * ```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',
+ *     logStreamName: `${process.env.HOSTNAME}/${Date.now()}`,
+ *   }),
+ *   detach: { driver: microtaskBatchDriver, mode: 'forget' },
+ * });
+ * ```
+ *
+ * @example Test injection (skip SDK require entirely)
+ * ```ts
+ * agentcoreObservability({
+ *   _client: {
+ *     putLogEvents: async (input) => { capturedBatches.push(input); },
+ *   },
+ * });
+ * ```
+ */
+import { _buildCloudWatchObservability, } from './cloudwatch.js';
+/**
+ * Build an AgentCore-flavored CloudWatch Logs observability strategy.
+ * Functionally identical to `cloudwatchObservability` except for the
+ * strategy `name`, which lets registry-lookup + diagnostics
+ * distinguish AgentCore-targeted shipping from generic CloudWatch.
+ */
+export function agentcoreObservability(opts) {
+    return _buildCloudWatchObservability(opts, 'agentcore');
+}
+//# sourceMappingURL=agentcore.js.map

package/dist/esm/adapters/observability/agentcore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentcore.js","sourceRoot":"","sources":["../../../../src/adapters/observability/agentcore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAIH,OAAO,EACL,6BAA6B,GAE9B,MAAM,iBAAiB,CAAC;AAWzB;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAmC;IACxE,OAAO,6BAA6B,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;AAC1D,CAAC"}

package/dist/esm/adapters/observability/cloudwatch.js

@@ -0,0 +1,198 @@
+/**
+ * cloudwatchObservability — Generic AWS CloudWatch Logs adapter.
+ *
+ * Ships every `AgentfootprintEvent` to a CloudWatch Logs stream. Use
+ * when you want agent telemetry alongside the rest of your AWS
+ * observability stack — CloudWatch Insights queries, alarms,
+ * cross-service correlation. Same SDK as `agentcoreObservability`
+ * but **without** the AgentCore-specific defaults (log-stream
+ * convention, format opinions). Use this when:
+ *
+ *   1. You're shipping to CloudWatch but NOT running inside Bedrock
+ *      AgentCore (most common case).
+ *   2. You want full control over log group / stream / format and
+ *      don't need AgentCore's hosted-agent telemetry conventions.
+ *
+ * Subpath:  `agentfootprint/observability-providers`
+ * Peer dep: `@aws-sdk/client-cloudwatch-logs` (OPTIONAL — installed
+ *           only when this adapter is used; declared via
+ *           `peerDependenciesMeta.{name}.optional = true`).
+ *
+ * This module also exports the underlying base function used by
+ * `agentcoreObservability` — keeps the per-event hot path in one
+ * place so improvements (batching, retry, backpressure) flow to
+ * every CloudWatch-shaped adapter automatically.
+ *
+ * @example
+ * ```ts
+ * import { cloudwatchObservability } from 'agentfootprint/observability-providers';
+ * import { microtaskBatchDriver } from 'footprintjs/detach';
+ *
+ * agent.enable.observability({
+ *   strategy: cloudwatchObservability({
+ *     region: 'us-east-1',
+ *     logGroupName: '/myapp/agent-prod',
+ *     logStreamName: `${process.env.HOSTNAME}/${Date.now()}`,
+ *   }),
+ *   detach: { driver: microtaskBatchDriver, mode: 'forget' },
+ * });
+ * ```
+ */
+import { lazyRequire } from '../../lib/lazyRequire.js';
+// ─── Generic base — also used by agentcoreObservability ──────────────
+/**
+ * Internal: shared CloudWatch Logs base used by every adapter that
+ * ships to CWL. `cloudwatchObservability` is the public generic
+ * factory; `agentcoreObservability` calls this with AgentCore-flavored
+ * defaults.
+ *
+ * Exported for adapter authors only — consumers should call
+ * `cloudwatchObservability` or `agentcoreObservability` directly.
+ *
+ * @internal
+ */
+export function _buildCloudWatchObservability(opts, strategyName) {
+    if (!opts.logGroupName) {
+        throw new TypeError(`[${strategyName}Observability] \`logGroupName\` is required. ` +
+            `Pass an existing CloudWatch log group, e.g. '/myapp/agent-prod'.`);
+    }
+    const logStreamName = opts.logStreamName ?? 'agentfootprint';
+    const maxBatchEvents = opts.maxBatchEvents ?? 100;
+    const maxBatchBytes = opts.maxBatchBytes ?? 10_240;
+    const flushIntervalMs = opts.flushIntervalMs ?? 1000;
+    // Buffered batch — drained by `flush()` / size-trigger / time-trigger.
+    const buffer = [];
+    let bufferBytes = 0;
+    let lastFlushPromise = Promise.resolve();
+    let timer;
+    let stopped = false;
+    let onErrorHook;
+    // Lazy-resolved on first flush so consumers who never trigger a
+    // flush (because nothing was emitted) don't even hit the SDK.
+    let client = opts._client;
+    function ensureClient() {
+        if (client)
+            return client;
+        client = createCloudWatchClient(opts.region, strategyName);
+        return client;
+    }
+    function scheduleTimedFlush() {
+        if (timer || flushIntervalMs <= 0 || stopped)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            void doFlush();
+        }, flushIntervalMs);
+    }
+    async function doFlush() {
+        if (buffer.length === 0 || stopped)
+            return;
+        // Snapshot + clear so concurrent emits during the in-flight put
+        // accumulate into the next batch.
+        const batch = buffer.splice(0);
+        bufferBytes = 0;
+        try {
+            await ensureClient().putLogEvents({
+                logGroupName: opts.logGroupName,
+                logStreamName,
+                logEvents: batch,
+            });
+        }
+        catch (err) {
+            onErrorHook?.(err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    function enqueue(event) {
+        if (stopped)
+            return;
+        const message = JSON.stringify(event);
+        const bytes = Buffer.byteLength(message, 'utf8');
+        buffer.push({ timestamp: Date.now(), message });
+        bufferBytes += bytes;
+        if (buffer.length >= maxBatchEvents || bufferBytes >= maxBatchBytes) {
+            // Size trigger — flush immediately. Chain onto last to preserve
+            // CloudWatch's per-stream ordering requirement.
+            lastFlushPromise = lastFlushPromise.then(doFlush, doFlush);
+        }
+        else {
+            scheduleTimedFlush();
+        }
+    }
+    return {
+        name: strategyName,
+        capabilities: { events: true, logs: true },
+        exportEvent: enqueue,
+        async flush() {
+            // Drain anything pending. Awaits both an in-flight put AND any
+            // newly-buffered events that arrived during it.
+            while (buffer.length > 0 || lastFlushPromise !== Promise.resolve()) {
+                const before = lastFlushPromise;
+                await before;
+                if (buffer.length > 0) {
+                    lastFlushPromise = doFlush();
+                }
+                // Loop one more pass if the chained doFlush() queued more
+                // work, then bail.
+                if (lastFlushPromise === before && buffer.length === 0)
+                    break;
+            }
+        },
+        stop() {
+            stopped = true;
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+        },
+        _onError(err, event) {
+            // Capture for use inside doFlush (the strategy doesn't know what
+            // the consumer's error sink is unless they wire `_onError` via
+            // the strategy options. We store it on this hook so put-failures
+            // route correctly).
+            onErrorHook =
+                onErrorHook ??
+                    ((e) => {
+                        // eslint-disable-next-line no-console
+                        console.error(`[${strategyName}Observability] flush failed:`, e.message);
+                    });
+            onErrorHook(err, event);
+        },
+    };
+}
+// ─── Public factory: cloudwatchObservability ─────────────────────────
+/**
+ * Generic CloudWatch Logs observability adapter. See
+ * `CloudwatchObservabilityOptions` for the per-option contract.
+ *
+ * For AgentCore-specific conventions, use `agentcoreObservability`
+ * which thin-wraps this with AgentCore-flavored defaults.
+ */
+export function cloudwatchObservability(opts) {
+    return _buildCloudWatchObservability(opts, 'cloudwatch');
+}
+// ─── SDK client construction (lazy) ──────────────────────────────────
+function createCloudWatchClient(region, strategyName) {
+    let mod;
+    try {
+        mod = lazyRequire('@aws-sdk/client-cloudwatch-logs');
+    }
+    catch {
+        throw new Error(`[${strategyName}Observability] requires the \`@aws-sdk/client-cloudwatch-logs\` peer dependency.\n` +
+            `  Install:  npm install @aws-sdk/client-cloudwatch-logs\n` +
+            `  Or pass \`_client\` for test injection.`);
+    }
+    if (!mod.CloudWatchLogsClient || !mod.PutLogEventsCommand) {
+        throw new Error(`[${strategyName}Observability]: \`@aws-sdk/client-cloudwatch-logs\` is installed but ` +
+            `\`CloudWatchLogsClient\` / \`PutLogEventsCommand\` was not found. Update the SDK.`);
+    }
+    const sdkClient = new mod.CloudWatchLogsClient({ ...(region && { region }) });
+    return {
+        async putLogEvents(input) {
+            // Cast the SDK constructor to the call shape — same trick as
+            // the memory adapter to stay forward-compat with SDK shape drift.
+            const cmd = new mod.PutLogEventsCommand(input);
+            await sdkClient.send(cmd);
+        },
+    };
+}
+//# sourceMappingURL=cloudwatch.js.map

package/dist/esm/adapters/observability/cloudwatch.js.map

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

package/dist/esm/observability-providers.js

@@ -0,0 +1,38 @@
+/**
+ * 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
+ *   - cloudwatchObservability  ← v2.8.2 (this release)
+ *   - xrayObservability        ← v2.8.3
+ *   - otelObservability        ← v2.9.x
+ *   - datadogObservability     ← v2.9.x
+ */
+export { agentcoreObservability, } from './adapters/observability/agentcore.js';
+export { cloudwatchObservability, } from './adapters/observability/cloudwatch.js';
+//# sourceMappingURL=observability-providers.js.map

package/dist/esm/observability-providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability-providers.js","sourceRoot":"","sources":["../../src/observability-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EACL,sBAAsB,GAEvB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,uBAAuB,GAExB,MAAM,wCAAwC,CAAC"}

package/dist/esm/strategies/index.js

@@ -7,14 +7,28 @@
  *   - `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)
+ * 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';

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

@@ -1 +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"}
+{"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"}