agentfootprint 2.8.1 → 2.8.3

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/adapters/observability/xray.d.ts

@@ -0,0 +1,83 @@
+/**
+ * xrayObservability — AWS X-Ray distributed-tracing adapter.
+ *
+ * Maps agentfootprint's event taxonomy onto AWS X-Ray segment trees:
+ *
+ *     agent.turn_start          ↦  root segment (one trace per turn)
+ *     agent.turn_end            ↦  close root segment + flush
+ *     agent.iteration_start     ↦  push subsegment under root
+ *     agent.iteration_end       ↦  close iteration subsegment
+ *     stream.llm_start          ↦  push leaf subsegment (model call)
+ *     stream.llm_end            ↦  close llm subsegment
+ *     stream.tool_start         ↦  push leaf subsegment (tool call)
+ *     stream.tool_end           ↦  close tool subsegment
+ *
+ * The result in the X-Ray Trace Map: a hierarchical timeline of every
+ * agent run — turn → iteration → llm-call/tool-call — queryable in
+ * X-Ray Insights, joinable with the rest of your AWS distributed
+ * trace via `AWSTraceHeader` propagation (consumer's responsibility
+ * to wire upstream/downstream IDs).
+ *
+ * Subpath:  `agentfootprint/observability-providers`
+ * Peer dep: `@aws-sdk/client-xray` (OPTIONAL — installed only when
+ *           this adapter is used).
+ *
+ * Sampling:
+ *   By default every turn produces one trace. Pass `sampleRate: 0.1`
+ *   to sample 10% of turns — sampling decisions are made at
+ *   `turn_start` and persist for the whole turn (so partial traces
+ *   never reach X-Ray).
+ *
+ * @example
+ * ```ts
+ * import { xrayObservability } from 'agentfootprint/observability-providers';
+ * import { microtaskBatchDriver } from 'footprintjs/detach';
+ *
+ * agent.enable.observability({
+ *   strategy: xrayObservability({
+ *     region: 'us-east-1',
+ *     serviceName: 'my-agent',
+ *     sampleRate: 0.1,                    // 10% sampling
+ *   }),
+ *   detach: { driver: microtaskBatchDriver, mode: 'forget' },
+ * });
+ * ```
+ *
+ * @example Test injection
+ * ```ts
+ * xrayObservability({
+ *   serviceName: 'test',
+ *   _client: {
+ *     putTraceSegments: async (input) => { capturedDocs.push(input); },
+ *   },
+ * });
+ * ```
+ */
+import type { ObservabilityStrategy } from '../../strategies/types.js';
+export interface XrayObservabilityOptions {
+    /** AWS region. Falls back to AWS_REGION / AWS_DEFAULT_REGION env. */
+    readonly region?: string;
+    /** Service name on every emitted segment. Surfaces in X-Ray's
+     *  service map. Required. */
+    readonly serviceName: string;
+    /** 0..1 — fraction of turns to sample. Default `1.0` (every turn).
+     *  Decisions are made at `turn_start` and persist for the whole
+     *  turn so partial traces never reach X-Ray. */
+    readonly sampleRate?: number;
+    /** Max segments buffered before forced flush. X-Ray's
+     *  `PutTraceSegments` API accepts up to 50 segments per call;
+     *  default 25 keeps latency tight. */
+    readonly maxBatchSegments?: number;
+    /** Forced flush window for low-traffic agents. Default 1000ms.
+     *  `0` disables time-based flush. */
+    readonly flushIntervalMs?: number;
+    /** Test injection — bypasses SDK lazy-require entirely. */
+    readonly _client?: XRayLikeClient;
+}
+export interface XRayLikeClient {
+    putTraceSegments(input: {
+        TraceSegmentDocuments: ReadonlyArray<string>;
+    }): Promise<unknown>;
+}
+export declare function xrayObservability(opts: XrayObservabilityOptions): ObservabilityStrategy;
+//# sourceMappingURL=xray.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"xray.d.ts","sourceRoot":"","sources":["../../../../src/adapters/observability/xray.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAIvE,MAAM,WAAW,wBAAwB;IACvC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;iCAC6B;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;oDAEgD;IAChD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;0CAEsC;IACtC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;yCACqC;IACrC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;CACnC;AAID,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,KAAK,EAAE;QAAE,qBAAqB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7F;AA6BD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,qBAAqB,CAuQvF"}

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

@@ -27,11 +27,13 @@
  * ```
  *
  * Roadmap:
- *   - agentcoreObservability   ← v2.8.1 (this release)
+ *   - agentcoreObservability   ← v2.8.1
  *   - cloudwatchObservability  ← v2.8.2
- *   - xrayObservability        ← v2.8.3
+ *   - xrayObservability        ← v2.8.3 (this release)
  *   - 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';
+export { xrayObservability, type XrayObservabilityOptions, type XRayLikeClient, } from './adapters/observability/xray.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;AAChD,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,GACpB,MAAM,kCAAkC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "2.8.1",
+  "version": "2.8.3",
   "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -171,6 +171,7 @@
     "@aws-sdk/client-bedrock-agent-runtime": "*",
     "@aws-sdk/client-bedrock-runtime": "*",
     "@aws-sdk/client-cloudwatch-logs": "*",
+    "@aws-sdk/client-xray": "*",
     "@modelcontextprotocol/sdk": "*",
     "footprintjs": ">=4.17.1",
     "ioredis": "*",
@@ -193,6 +194,9 @@
     "@aws-sdk/client-cloudwatch-logs": {
       "optional": true
     },
+    "@aws-sdk/client-xray": {
+      "optional": true
+    },
     "@modelcontextprotocol/sdk": {
       "optional": true
     },