agentfootprint 2.8.1 → 2.8.2

package/dist/adapters/observability/agentcore.js

@@ -17,11 +17,12 @@
  *           only when this adapter is used; declared via
  *           `peerDependenciesMeta.{name}.optional = true`).
  *
- * Pattern: Adapter (GoF) — translates `AgentfootprintEvent` →
- *          CloudWatch Logs `PutLogEvents` payloads. Buffers in
- *          `exportEvent()` (sync, non-throwing); flushes in `flush()`
- *          (async batch). Default flush window: 1s OR 10 KB,
- *          whichever first — matches CloudWatch's own optimal batch.
+ * **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
@@ -49,140 +50,15 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.agentcoreObservability = void 0;
-const lazyRequire_js_1 = require("../../lib/lazyRequire.js");
-// ─── Strategy factory ────────────────────────────────────────────────
+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) {
-    if (!opts.logGroupName) {
-        throw new TypeError(`[agentcoreObservability] \`logGroupName\` is required. ` +
-            `Pass an existing CloudWatch log group, e.g. '/agentfootprint/my-agent'.`);
-    }
-    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);
-        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: 'agentcore',
-        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('[agentcoreObservability] flush failed:', e.message);
-                    });
-            onErrorHook(err, event);
-        },
-    };
+    return (0, cloudwatch_js_1._buildCloudWatchObservability)(opts, 'agentcore');
 }
 exports.agentcoreObservability = agentcoreObservability;
-// ─── SDK client construction (lazy) ──────────────────────────────────
-function createCloudWatchClient(region) {
-    let mod;
-    try {
-        mod = (0, lazyRequire_js_1.lazyRequire)('@aws-sdk/client-cloudwatch-logs');
-    }
-    catch {
-        throw new Error('agentcoreObservability 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('agentcoreObservability: `@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=agentcore.js.map

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

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

@@ -16,11 +16,12 @@
  *           only when this adapter is used; declared via
  *           `peerDependenciesMeta.{name}.optional = true`).
  *
- * Pattern: Adapter (GoF) — translates `AgentfootprintEvent` →
- *          CloudWatch Logs `PutLogEvents` payloads. Buffers in
- *          `exportEvent()` (sync, non-throwing); flushes in `flush()`
- *          (async batch). Default flush window: 1s OR 10 KB,
- *          whichever first — matches CloudWatch's own optimal batch.
+ * **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
@@ -46,139 +47,14 @@
  * });
  * ```
  */
-import { lazyRequire } from '../../lib/lazyRequire.js';
-// ─── Strategy factory ────────────────────────────────────────────────
+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) {
-    if (!opts.logGroupName) {
-        throw new TypeError(`[agentcoreObservability] \`logGroupName\` is required. ` +
-            `Pass an existing CloudWatch log group, e.g. '/agentfootprint/my-agent'.`);
-    }
-    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);
-        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: 'agentcore',
-        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('[agentcoreObservability] flush failed:', e.message);
-                    });
-            onErrorHook(err, event);
-        },
-    };
-}
-// ─── SDK client construction (lazy) ──────────────────────────────────
-function createCloudWatchClient(region) {
-    let mod;
-    try {
-        mod = lazyRequire('@aws-sdk/client-cloudwatch-logs');
-    }
-    catch {
-        throw new Error('agentcoreObservability 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('agentcoreObservability: `@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);
-        },
-    };
+    return _buildCloudWatchObservability(opts, 'agentcore');
 }
 //# sourceMappingURL=agentcore.js.map

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

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

@@ -27,11 +27,12 @@
  * ```
  *
  * Roadmap:
- *   - agentcoreObservability   ← v2.8.1 (this release)
- *   - cloudwatchObservability  ← v2.8.2
+ *   - 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

@@ -1 +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"}
+{"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/observability-providers.js

@@ -28,14 +28,16 @@
  * ```
  *
  * Roadmap:
- *   - agentcoreObservability   ← v2.8.1 (this release)
- *   - cloudwatchObservability  ← v2.8.2
+ *   - agentcoreObservability   ← v2.8.1
+ *   - cloudwatchObservability  ← v2.8.2 (this release)
  *   - xrayObservability        ← v2.8.3
  *   - otelObservability        ← v2.9.x
  *   - datadogObservability     ← v2.9.x
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.agentcoreObservability = void 0;
+exports.cloudwatchObservability = 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; } });
+var cloudwatch_js_1 = require("./adapters/observability/cloudwatch.js");
+Object.defineProperty(exports, "cloudwatchObservability", { enumerable: true, get: function () { return cloudwatch_js_1.cloudwatchObservability; } });
 //# sourceMappingURL=observability-providers.js.map

package/dist/observability-providers.js.map

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

package/dist/types/adapters/observability/agentcore.d.ts

@@ -16,11 +16,12 @@
  *           only when this adapter is used; declared via
  *           `peerDependenciesMeta.{name}.optional = true`).
  *
- * Pattern: Adapter (GoF) — translates `AgentfootprintEvent` →
- *          CloudWatch Logs `PutLogEvents` payloads. Buffers in
- *          `exportEvent()` (sync, non-throwing); flushes in `flush()`
- *          (async batch). Default flush window: 1s OR 10 KB,
- *          whichever first — matches CloudWatch's own optimal batch.
+ * **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
@@ -47,40 +48,20 @@
  * ```
  */
 import type { ObservabilityStrategy } from '../../strategies/types.js';
-export interface AgentcoreObservabilityOptions {
-    /** AWS region. Falls back to AWS_REGION / AWS_DEFAULT_REGION env. */
-    readonly region?: string;
-    /** CloudWatch Logs log group. **Required.** Must exist or your IAM
-     *  role must allow `logs:CreateLogGroup`. */
-    readonly logGroupName: string;
-    /** CloudWatch Logs log stream within the group. Conventionally
-     *  `<host>/<startTime>` so multi-instance deployments don't collide.
-     *  Created on first put if it doesn't exist (or your role must
-     *  allow `logs:CreateLogStream`). Defaults to `agentfootprint`. */
-    readonly logStreamName?: string;
-    /** Max events buffered before forced flush. Default 100. */
-    readonly maxBatchEvents?: number;
-    /** Max payload bytes (UTF-8) buffered before forced flush. Default
-     *  10240 (10 KB). CloudWatch hard caps at 1 MB / batch but we keep
-     *  the default low so latency stays bounded. */
-    readonly maxBatchBytes?: number;
-    /** Forced-flush interval when traffic is sparse. Default 1000ms.
-     *  `0` disables time-based flush — only size triggers fire. */
-    readonly flushIntervalMs?: number;
-    /** Test injection — bypasses SDK lazy-require entirely. When set,
-     *  `region` / IAM are ignored. */
-    readonly _client?: CloudWatchLikeClient;
-}
-interface CloudWatchLikeClient {
-    putLogEvents(input: {
-        logGroupName: string;
-        logStreamName: string;
-        logEvents: ReadonlyArray<{
-            timestamp: number;
-            message: string;
-        }>;
-    }): Promise<unknown>;
-}
+import { type CloudwatchObservabilityOptions } from './cloudwatch.js';
+/**
+ * AgentCore-specific options. Currently identical to the generic
+ * `CloudwatchObservabilityOptions` — kept as a separate type for
+ * future-proofing (AgentCore-specific knobs like
+ * `agentcoreSessionId` propagation could land here without a
+ * breaking change).
+ */
+export type AgentcoreObservabilityOptions = CloudwatchObservabilityOptions;
+/**
+ * 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 declare function agentcoreObservability(opts: AgentcoreObservabilityOptions): ObservabilityStrategy;
-export {};
 //# sourceMappingURL=agentcore.d.ts.map

package/dist/types/adapters/observability/agentcore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agentcore.d.ts","sourceRoot":"","sources":["../../../../src/adapters/observability/agentcore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAIvE,MAAM,WAAW,6BAA6B;IAC5C,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;iDAC6C;IAC7C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;uEAGmE;IACnE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;oDAEgD;IAChD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;mEAC+D;IAC/D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;sCACkC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB,CAAC;CACzC;AAID,UAAU,oBAAoB;IAC5B,YAAY,CAAC,KAAK,EAAE;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,aAAa,CAAC;YAAE,SAAS,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAClE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtB;AAUD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,6BAA6B,GAAG,qBAAqB,CA8GjG"}
+{"version":3,"file":"agentcore.d.ts","sourceRoot":"","sources":["../../../../src/adapters/observability/agentcore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,OAAO,EAEL,KAAK,8BAA8B,EACpC,MAAM,iBAAiB,CAAC;AAEzB;;;;;;GAMG;AACH,MAAM,MAAM,6BAA6B,GAAG,8BAA8B,CAAC;AAE3E;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,6BAA6B,GAAG,qBAAqB,CAEjG"}

package/dist/types/adapters/observability/cloudwatch.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 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 type { ObservabilityStrategy } from '../../strategies/types.js';
+export interface CloudwatchObservabilityOptions {
+    /** AWS region. Falls back to AWS_REGION / AWS_DEFAULT_REGION env. */
+    readonly region?: string;
+    /** CloudWatch Logs log group. **Required.** Must exist or your IAM
+     *  role must allow `logs:CreateLogGroup`. */
+    readonly logGroupName: string;
+    /** CloudWatch Logs log stream within the group. Conventionally
+     *  `<host>/<startTime>` so multi-instance deployments don't
+     *  collide. Created on first put if it doesn't exist (or your
+     *  role must allow `logs:CreateLogStream`). Defaults to
+     *  `agentfootprint`. */
+    readonly logStreamName?: string;
+    /** Max events buffered before forced flush. Default 100. */
+    readonly maxBatchEvents?: number;
+    /** Max payload bytes (UTF-8) buffered before forced flush. Default
+     *  10240 (10 KB). CloudWatch hard caps at 1 MB / batch but we keep
+     *  the default low so latency stays bounded. */
+    readonly maxBatchBytes?: number;
+    /** Forced-flush interval when traffic is sparse. Default 1000ms.
+     *  `0` disables time-based flush — only size triggers fire. */
+    readonly flushIntervalMs?: number;
+    /** Test injection — bypasses SDK lazy-require entirely. When set,
+     *  `region` / IAM are ignored. */
+    readonly _client?: CloudWatchLikeClient;
+}
+export interface CloudWatchLikeClient {
+    putLogEvents(input: {
+        logGroupName: string;
+        logStreamName: string;
+        logEvents: ReadonlyArray<{
+            timestamp: number;
+            message: string;
+        }>;
+    }): Promise<unknown>;
+}
+/**
+ * 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 declare function _buildCloudWatchObservability(opts: CloudwatchObservabilityOptions, strategyName: string): ObservabilityStrategy;
+/**
+ * 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 declare function cloudwatchObservability(opts: CloudwatchObservabilityOptions): ObservabilityStrategy;
+//# sourceMappingURL=cloudwatch.d.ts.map

package/dist/types/adapters/observability/cloudwatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudwatch.d.ts","sourceRoot":"","sources":["../../../../src/adapters/observability/cloudwatch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAIvE,MAAM,WAAW,8BAA8B;IAC7C,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;iDAC6C;IAC7C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;4BAIwB;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;oDAEgD;IAChD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;mEAC+D;IAC/D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;sCACkC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB,CAAC;CACzC;AAID,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,KAAK,EAAE;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,aAAa,CAAC;YAAE,SAAS,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KAClE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACtB;AAUD;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,8BAA8B,EACpC,YAAY,EAAE,MAAM,GACnB,qBAAqB,CA8GvB;AAID;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,8BAA8B,GACnC,qBAAqB,CAEvB"}

package/dist/types/observability-providers.d.ts

@@ -27,11 +27,12 @@
  * ```
  *
  * Roadmap:
- *   - agentcoreObservability   ← v2.8.1 (this release)
- *   - cloudwatchObservability  ← v2.8.2
+ *   - agentcoreObservability   ← v2.8.1
+ *   - cloudwatchObservability  ← v2.8.2 (this release)
  *   - xrayObservability        ← v2.8.3
  *   - otelObservability        ← v2.9.x
  *   - datadogObservability     ← v2.9.x
  */
 export { agentcoreObservability, type AgentcoreObservabilityOptions, } from './adapters/observability/agentcore.js';
+export { cloudwatchObservability, type CloudwatchObservabilityOptions, } from './adapters/observability/cloudwatch.js';
 //# sourceMappingURL=observability-providers.d.ts.map

package/dist/types/observability-providers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observability-providers.d.ts","sourceRoot":"","sources":["../../src/observability-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EACL,sBAAsB,EACtB,KAAK,6BAA6B,GACnC,MAAM,uCAAuC,CAAC"}
+{"version":3,"file":"observability-providers.d.ts","sourceRoot":"","sources":["../../src/observability-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EACL,sBAAsB,EACtB,KAAK,6BAA6B,GACnC,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,uBAAuB,EACvB,KAAK,8BAA8B,GACpC,MAAM,wCAAwC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "2.8.1",
+  "version": "2.8.2",
   "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",