agentfootprint 6.44.0 → 6.45.0

package/dist/esm/adapters/memory/bedrockAgentMemory.d.ts

@@ -0,0 +1,95 @@
+/**
+ * BedrockAgentMemory — read the **auto-generated session-summary memory** of a
+ * (legacy) Amazon **Bedrock Agents** agent (peer-dep `@aws-sdk/client-bedrock-agent-runtime`).
+ *
+ *   import { BedrockAgentMemory } from 'agentfootprint/memory-providers';
+ *
+ *   const mem = new BedrockAgentMemory({ agentId, agentAliasId, region: 'us-west-2' });
+ *   const summaries = await mem.readSummaries(userMemoryId);   // string summaries Bedrock wrote
+ *
+ * **This is NOT a `MemoryStore`** — and intentionally so. Bedrock Agents *owns the writes*:
+ * the agent generates `SESSION_SUMMARY` records itself (`GetAgentMemory` reads them,
+ * `DeleteAgentMemory` clears them). There is no "put an arbitrary entry" operation, so wrapping
+ * it as a `defineMemory({ store })` would be a "store that can't store." Instead it's a small
+ * **reader** you use to *surface* Bedrock's built-in memory — e.g. inject the summaries as a
+ * Fact/context block into an agentfootprint agent.
+ *
+ * For a real read/write agent memory store on AWS, use `AgentCoreStore` (the newer
+ * Bedrock **AgentCore** platform) — that's the go-forward path; this targets the prior-gen
+ * Bedrock Agents product and exists for teams migrating off it.
+ *
+ * Role:   Outer ring. Lazy-requires the AWS SDK; zero cost when unused.
+ */
+/** One auto-generated session summary from Bedrock Agents memory. */
+export interface BedrockAgentSummary {
+    readonly sessionId: string;
+    readonly summaryText: string;
+    /** ISO timestamps (the SDK returns Date; serialized here for portability). */
+    readonly sessionStartTime?: string;
+    readonly sessionExpiryTime?: string;
+}
+/** Minimal surface the reader uses; tests inject a mock via `_client`. */
+export interface BedrockAgentMemoryLikeClient {
+    getSessionSummaries(input: {
+        agentId: string;
+        agentAliasId: string;
+        memoryId: string;
+        maxItems?: number;
+        nextToken?: string;
+    }): Promise<{
+        summaries: readonly BedrockAgentSummary[];
+        nextToken?: string;
+    }>;
+    deleteMemory(input: {
+        agentId: string;
+        agentAliasId: string;
+        memoryId: string;
+        sessionId?: string;
+    }): Promise<void>;
+}
+export interface BedrockAgentMemoryOptions {
+    /** The Bedrock Agent id whose memory to read. Required. */
+    readonly agentId: string;
+    /** The Bedrock Agent alias id. Required. */
+    readonly agentAliasId: string;
+    /** AWS region (when constructing the SDK client internally). */
+    readonly region?: string;
+    /** Pre-built client (shares one SDK config across the host app). */
+    readonly client?: BedrockAgentMemoryLikeClient;
+    /** Default page size for `readSummaries`. Default 20. */
+    readonly maxItems?: number;
+    /** @internal Test injection — skips the SDK require. */
+    readonly _client?: BedrockAgentMemoryLikeClient;
+    /** @internal Test injection — the AWS SDK module. */
+    readonly _sdk?: BedrockAgentRuntimeSdkModule;
+}
+/**
+ * Read-only reader for Bedrock Agents' auto session-summary memory.
+ *
+ * @throws when `@aws-sdk/client-bedrock-agent-runtime` is not installed and no
+ *         `_client`/`_sdk` is supplied.
+ */
+export declare class BedrockAgentMemory {
+    private readonly client;
+    private readonly agentId;
+    private readonly agentAliasId;
+    private readonly maxItems;
+    constructor(options: BedrockAgentMemoryOptions);
+    /** All session summaries Bedrock generated for `memoryId` (paginated). */
+    readSummaries(memoryId: string, opts?: {
+        maxItems?: number;
+    }): Promise<BedrockAgentSummary[]>;
+    /** The concatenated summary text — handy to inject as a single context/Fact block. */
+    readText(memoryId: string): Promise<string>;
+    /** Clear Bedrock's memory for `memoryId` (optionally a single `sessionId`). */
+    forget(memoryId: string, sessionId?: string): Promise<void>;
+}
+export interface BedrockAgentRuntimeSdkModule {
+    readonly BedrockAgentRuntimeClient?: new (config: {
+        region?: string;
+    }) => {
+        send(cmd: unknown): Promise<unknown>;
+    };
+    readonly GetAgentMemoryCommand?: new (input: unknown) => unknown;
+    readonly DeleteAgentMemoryCommand?: new (input: unknown) => unknown;
+}

package/dist/esm/adapters/memory/redis.d.ts

@@ -0,0 +1,127 @@
+/**
+ * RedisStore — Redis-backed `MemoryStore` adapter (peer-dep `ioredis`).
+ *
+ * Import from the canonical subpath (the `agentfootprint/memory-redis` alias
+ * was removed in 4.0.0):
+ *
+ *   import { RedisStore } from 'agentfootprint/memory-providers';
+ *
+ *   const store = new RedisStore({ url: 'redis://localhost:6379' });
+ *
+ * Pattern: Adapter (GoF) — translates the `MemoryStore` interface onto
+ *          Redis primitives (key/value for entries, set for signatures,
+ *          hash for feedback aggregates).
+ * Role:    Outer ring. Lazy-requires `ioredis`; no runtime cost when
+ *          another adapter is in use.
+ * Emits:   N/A (storage adapters don't emit; recorders observe the
+ *          memory pipeline that calls them).
+ *
+ * Vector search (`search()`) is NOT implemented in this adapter — RedisSearch
+ * is a separate Redis module with its own API surface. A `RedisSearchStore`
+ * may ship in a future release. RAG users with v2.3 should use
+ * `InMemoryStore` until the search-capable adapter lands.
+ *
+ * Concurrency model:
+ *   - `put` / `putMany` use simple SET / pipelined SET (last-write-wins).
+ *   - `putIfVersion` uses a small Lua script for atomic version compare-and-swap.
+ *   - Multi-writer correctness ⇒ prefer `putIfVersion` in stage code.
+ */
+import type { ListOptions, ListResult, MemoryStore, PutIfVersionResult } from '../../memory/store/types.js';
+import type { MemoryEntry } from '../../memory/entry/index.js';
+import type { MemoryIdentity } from '../../memory/identity/index.js';
+/**
+ * Minimal `ioredis` client surface this adapter needs. Defined locally so
+ * we don't take a hard import on `ioredis` (lazy peer-dep) and tests can
+ * inject a mock implementation via `_client`.
+ */
+export interface RedisLikeClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ...args: ReadonlyArray<string | number>): Promise<unknown>;
+    del(...keys: ReadonlyArray<string>): Promise<number>;
+    sadd(key: string, ...members: ReadonlyArray<string>): Promise<number>;
+    srem(key: string, ...members: ReadonlyArray<string>): Promise<number>;
+    sismember(key: string, member: string): Promise<number>;
+    smembers(key: string): Promise<readonly string[]>;
+    hgetall(key: string): Promise<Record<string, string>>;
+    hset(key: string, ...args: ReadonlyArray<string | number>): Promise<number>;
+    scan(cursor: string, match: 'MATCH', pattern: string, count: 'COUNT', n: number): Promise<readonly [string, readonly string[]]>;
+    eval(script: string, numKeys: number, ...args: ReadonlyArray<string | number>): Promise<unknown>;
+    pipeline(): RedisLikePipeline;
+    quit(): Promise<unknown>;
+}
+export interface RedisLikePipeline {
+    set(key: string, value: string, ...args: ReadonlyArray<string | number>): RedisLikePipeline;
+    sadd(key: string, ...members: ReadonlyArray<string>): RedisLikePipeline;
+    exec(): Promise<unknown>;
+}
+export interface RedisStoreOptions {
+    /**
+     * Connection URL (e.g. `redis://default:password@host:6379/0`). Required
+     * unless `_client` is supplied.
+     */
+    readonly url?: string;
+    /**
+     * Pre-built `ioredis` client. Use this when the host app already manages
+     * a Redis connection pool. Adapter does NOT call `quit()` on a borrowed
+     * client — caller owns the lifecycle.
+     */
+    readonly client?: RedisLikeClient;
+    /** Key prefix for namespace isolation across apps sharing one Redis. Default `'agentfootprint'`. */
+    readonly prefix?: string;
+    /**
+     * SCAN page size when iterating keys. Default 100. Larger = fewer
+     * round-trips but more memory per response. Adapter never uses `KEYS *`
+     * (which blocks Redis).
+     */
+    readonly scanCount?: number;
+    /**
+     * @internal Test injection point. When provided, skips the SDK require.
+     */
+    readonly _client?: RedisLikeClient;
+}
+/**
+ * Redis-backed `MemoryStore`. Implements every method except `search()`.
+ *
+ * @throws when `ioredis` is not installed and no `_client` is supplied.
+ */
+export declare class RedisStore implements MemoryStore {
+    private readonly client;
+    private readonly prefix;
+    private readonly scanCount;
+    private readonly ownsClient;
+    private closed;
+    constructor(options?: RedisStoreOptions);
+    private nsKey;
+    private entryKey;
+    private indexKey;
+    private sigKey;
+    private feedbackKey;
+    get<T = unknown>(identity: MemoryIdentity, id: string): Promise<MemoryEntry<T> | null>;
+    put<T = unknown>(identity: MemoryIdentity, entry: MemoryEntry<T>): Promise<void>;
+    putMany<T = unknown>(identity: MemoryIdentity, entries: readonly MemoryEntry<T>[]): Promise<void>;
+    /**
+     * Optimistic concurrency via a small Lua script — atomic
+     * compare-and-swap on the JSON-encoded `version` field.
+     */
+    putIfVersion<T = unknown>(identity: MemoryIdentity, entry: MemoryEntry<T>, expectedVersion: number): Promise<PutIfVersionResult>;
+    list<T = unknown>(identity: MemoryIdentity, options?: ListOptions): Promise<ListResult<T>>;
+    delete(identity: MemoryIdentity, id: string): Promise<void>;
+    seen(identity: MemoryIdentity, signature: string): Promise<boolean>;
+    recordSignature(identity: MemoryIdentity, signature: string): Promise<void>;
+    feedback(identity: MemoryIdentity, id: string, usefulness: number): Promise<void>;
+    getFeedback(identity: MemoryIdentity, id: string): Promise<{
+        average: number;
+        count: number;
+    } | null>;
+    /**
+     * GDPR — drop every key under this identity's namespace.
+     */
+    forget(identity: MemoryIdentity): Promise<void>;
+    /**
+     * Close the underlying Redis connection — only when this adapter
+     * owns it. Borrowed clients (passed via `client` option) are left to
+     * the caller. Idempotent.
+     */
+    close(): Promise<void>;
+    private ensureOpen;
+}

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

@@ -0,0 +1,67 @@
+/**
+ * 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({
+ *   logGroupName: '/agentfootprint/test',
+ *   _client: {
+ *     putLogEvents: async (input) => { capturedBatches.push(input); },
+ *   },
+ * });
+ * ```
+ */
+import type { ObservabilityStrategy } from '../../strategies/types.js';
+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;

package/dist/esm/adapters/observability/audit.d.ts

@@ -0,0 +1,254 @@
+/**
+ * auditExport — tamper-evident audit bundle (backlog #20, compliance
+ * wedge item 2; pairs with #19's `otelObservability` GenAI spans).
+ *
+ * Consumes the typed `agentfootprint.*` event stream and accumulates an
+ * append-only, HASH-CHAINED record log: every record carries the SHA-256
+ * of its own canonical serialization plus the hash of the previous
+ * record. Flipping a single byte anywhere in an exported bundle makes
+ * `verifyAuditBundle` name the exact record that broke — the
+ * record-keeping shape EU AI Act Art. 12 asks for (events the system
+ * logged, in order, demonstrably unmodified since capture).
+ *
+ * Pattern: Observability strategy (one purpose — chain accumulation)
+ *          + pure offline verifier.
+ * Role:    Outer ring (Hexagonal). Attach via
+ *          `agent.enable.observability({ strategy: auditExport() })`.
+ * Emits:   nothing — terminal sink.
+ *
+ * ## What lands in the chain
+ *
+ * One record per typed event, in dispatch order: decisions
+ * (`agent.route_decided`, `composition.route_decided` incl. decide()
+ * evidence), tool calls (`stream.tool_start/_end`), validation
+ * rejections (#9), permission verdicts and halts, credential lifecycle,
+ * costs, errors, skill/memory/context activity. Each new `meta.runId`
+ * is anchored by a GENESIS record (`audit.genesis`) carrying the runId,
+ * the agent identity, and library versions — runs chain back-to-back in
+ * one log, so silently DROPPING a whole run breaks the chain too.
+ *
+ * High-volume content deltas (`stream.token`, `stream.thinking_delta`)
+ * are excluded by default (`includeTokenEvents: true` to include).
+ *
+ * ## Record / bundle schema
+ *
+ * ```
+ * AuditRecord  = { seq, timestamp, eventType, payload, meta, prevHash, hash }
+ *   hash       = SHA-256 hex over canonicalJson(record minus `hash`)
+ *   prevHash   = previous record's `hash` (ZERO_HASH at chain start)
+ * AuditBundle  = { header, records, finalHash }
+ *   header     = { format, hashAlgorithm, canonicalization, chainHead,
+ *                  firstSeq, recordCount, exportedAt, library }
+ * ```
+ *
+ * Canonicalization is `afp-cjson/1` (see `lib/canonicalJson.ts` — those
+ * rules ARE the contract; the header names them so independent
+ * verifiers can re-implement byte-exactly).
+ *
+ * ## Persistence + long runs
+ *
+ * Persistence is the CONSUMER's job — the bundle is plain JSON
+ * (`JSON.stringify(strategy.bundle())`, store anywhere). For long runs,
+ * `drain()` returns the records accumulated since the last drain while
+ * keeping the chain intact ACROSS drains: each segment's
+ * `header.chainHead` equals the previous segment's `finalHash`, so
+ * `verifyAuditBundle([seg1, seg2, ...])` re-verifies the concatenation
+ * end-to-end.
+ *
+ * ## PII discipline (mirrors #19's otelObservability)
+ *
+ * Payloads enter records through a bounding layer — by default
+ * (`payloadMode: 'bounded'`) record payloads NEVER carry raw runtime
+ * values that can echo PII:
+ *
+ *   - tool args             → `'[keys: …]'` (top-level key NAMES only)
+ *   - tool results          → `'[type: …]'` (typeof only)
+ *   - userPrompt / LLM content / thinking blocks / history
+ *                           → `'[N chars]'` / `'[N messages]'` markers
+ *   - content PREVIEWS (`contentSummary` on context/memory events,
+ *     `rawContent`, `resultSummary`, `droppedSummaries`) → markers
+ *     (for short content a preview IS the content; `contentHash`
+ *     stays — it links identical content without echoing it)
+ *   - error MESSAGE strings (`error`, `errorMessage`, `lastError`,
+ *     `rawOutput`)          → `'[N chars]'` (messages can echo values)
+ *   - free-form Records (`questionPayload`, `resumeInput`, risk/eval
+ *     `evidence`, memory `scoreEvidence`) → `'[keys: …]'`
+ *
+ * Everything else is embedded as the registry payload (sanitized:
+ * strings capped at 256 chars, lists at 32 items, cycles broken) —
+ * those payloads are bounded by construction: identifiers, counts,
+ * enums, decide() evidence (engine-bounded + redaction-aware),
+ * validation issues (paths/TYPES per #9), credential events (no
+ * secrets by contract).
+ *
+ * `payloadMode: 'verbatim'` embeds full payloads (still
+ * JSON-sanitized). For Art. 12 completeness on an access-controlled
+ * store that is often the point — but the bundle then carries prompts,
+ * tool args/results and model output. Treat it as PII-bearing, and
+ * remember the Agent sets NO footprintjs RedactionPolicy by default
+ * (policies you do set redact the emit channel UPSTREAM of this
+ * strategy, so redacted events arrive here already redacted).
+ *
+ * ## Tamper-EVIDENT, not tamper-PROOF (honest threat model)
+ *
+ * The chain proves INTERNAL consistency: any partial modification —
+ * edit, insert, delete, reorder, drop-a-run — is detected and named.
+ * It does NOT prove provenance: an adversary holding the only copy can
+ * recompute every hash from the mutation onward and present a
+ * self-consistent forgery. For non-repudiation, anchor `finalHash`
+ * externally as part of your retention process (write-once/WORM store,
+ * signed log, RFC 3161 timestamping, or simply a second party) — then
+ * a whole-suffix recomputation no longer matches the anchor.
+ *
+ * ## Runtime requirements
+ *
+ * Hashing uses `node:crypto` (`createHash('sha256')`) — zero new
+ * dependencies, imported lazily at first use (same gating as the
+ * optional vendor SDKs in this folder, so merely importing this module
+ * stays browser-safe). `auditExport` and `verifyAuditBundle` therefore
+ * run anywhere `node:crypto` exists: Node ≥ 20, Bun, Deno,
+ * edge runtimes with Node compat (e.g. Cloudflare `nodejs_compat`).
+ * In a browser there is no SYNC SHA-256 (WebCrypto is async-only), so
+ * both throw a descriptive error — verify server-side, or re-implement
+ * verification from the documented contract (it is pure: recompute
+ * SHA-256 over `afp-cjson/1` canonicalization and walk the chain).
+ *
+ * @example Capture → export → verify
+ * ```ts
+ * import { auditExport, verifyAuditBundle } from 'agentfootprint/observability-providers';
+ *
+ * const audit = auditExport({ agent: 'loan-officer' });
+ * const stop = agent.enable.observability({ strategy: audit });
+ * await agent.run({ message: 'assess application A-17' });
+ * stop();
+ *
+ * const bundle = audit.bundle();            // JSON-serializable
+ * await fs.writeFile('run.audit.json', JSON.stringify(bundle));
+ *
+ * const check = verifyAuditBundle(bundle);  // offline — no agent needed
+ * // check.valid === true; tamper with one byte → { valid: false, brokenAt: <seq> }
+ * ```
+ */
+import { CANONICAL_JSON_VERSION } from '../../lib/canonicalJson.js';
+import type { ObservabilityStrategy } from '../../strategies/types.js';
+/** SHA-256 of "nothing" — the `prevHash` of the first record in a
+ *  chain and the `chainHead` of a chain's first segment. */
+export declare const AUDIT_ZERO_HASH: string;
+/** `eventType` of the per-run genesis record. Deliberately OUTSIDE the
+ *  `agentfootprint.*` registry namespace — it is a chain-level record,
+ *  not a dispatched event (#20 ships zero new typed events). */
+export declare const AUDIT_GENESIS_EVENT_TYPE = "audit.genesis";
+/** Format identifier carried on every bundle header. */
+export declare const AUDIT_BUNDLE_FORMAT = "agentfootprint.audit/1";
+/**
+ * One link of the hash chain.
+ *
+ * `hash` = SHA-256 hex over `canonicalJson` of the record WITHOUT the
+ * `hash` field (i.e. `{ seq, timestamp, eventType, payload, meta,
+ * prevHash }` — canonical key order makes field order irrelevant).
+ * Because the preimage is "everything but `hash`", ADDING a field to a
+ * record is detected exactly like mutating one.
+ */
+export interface AuditRecord {
+    /** 0-based position in the chain (monotonic across drains). */
+    readonly seq: number;
+    /** Wall-clock ms of the source event (`meta.wallClockMs`). */
+    readonly timestamp: number;
+    /** Registry event name verbatim, or {@link AUDIT_GENESIS_EVENT_TYPE}. */
+    readonly eventType: string;
+    /** Bounded / sanitized event payload (see module PII docs). */
+    readonly payload: unknown;
+    /** Sanitized event meta (runId, runtimeStageId, paths, indices). */
+    readonly meta: {
+        readonly runId: string;
+    } & Readonly<Record<string, unknown>>;
+    /** `hash` of the previous record ({@link AUDIT_ZERO_HASH} at chain start). */
+    readonly prevHash: string;
+    /** SHA-256 hex of this record's canonical preimage. */
+    readonly hash: string;
+}
+export interface AuditBundleHeader {
+    readonly format: typeof AUDIT_BUNDLE_FORMAT;
+    readonly hashAlgorithm: 'sha-256';
+    readonly canonicalization: typeof CANONICAL_JSON_VERSION;
+    /** `prevHash` of `records[0]` — {@link AUDIT_ZERO_HASH} for the first
+     *  segment, the previous segment's `finalHash` after a `drain()`. */
+    readonly chainHead: string;
+    /** `seq` of `records[0]` (continues across drains). */
+    readonly firstSeq: number;
+    readonly recordCount: number;
+    /** Wall-clock ms when `bundle()` / `drain()` produced this export. */
+    readonly exportedAt: number;
+    readonly library: {
+        readonly name: 'agentfootprint';
+        readonly version: string;
+    };
+}
+/** JSON-serializable export of the chain (or one drained segment). */
+export interface AuditBundle {
+    readonly header: AuditBundleHeader;
+    readonly records: readonly AuditRecord[];
+    /** `hash` of the last record (= `chainHead` when `records` is empty).
+     *  The next drained segment's `chainHead` equals this value. */
+    readonly finalHash: string;
+}
+export interface AuditVerifyResult {
+    readonly valid: boolean;
+    /** Records whose hashes were recomputed and matched. */
+    readonly recordsChecked: number;
+    /** `seq` of the first record that fails (or the expected seq at the
+     *  failure point, when the stored seq itself was tampered). */
+    readonly brokenAt?: number;
+    /** Human-readable cause — names the failed check. */
+    readonly reason?: string;
+}
+export interface AuditExportOptions {
+    /** Agent identity recorded in every run's genesis record (service /
+     *  agent name as your compliance review knows it). */
+    readonly agent?: string;
+    /**
+     * `'bounded'` (default) — payloads pass the PII bounding layer (see
+     * module docs). `'verbatim'` — full payloads, JSON-sanitized only.
+     *
+     * @remarks Verbatim bundles carry prompts, tool args/results and
+     * model output. Treat the store as PII-bearing; the Agent applies NO
+     * RedactionPolicy by default.
+     */
+    readonly payloadMode?: 'bounded' | 'verbatim';
+    /** Include `stream.token` / `stream.thinking_delta` events (high
+     *  volume; content still bounded under `payloadMode: 'bounded'`).
+     *  Default `false`. */
+    readonly includeTokenEvents?: boolean;
+    /** Extra version pins for the genesis record (your app, model
+     *  config revision, policy bundle hash, …). */
+    readonly versions?: Readonly<Record<string, string>>;
+}
+/** The strategy returned by {@link auditExport}. */
+export interface AuditExportStrategy extends ObservabilityStrategy {
+    /** Snapshot the retained records WITHOUT draining. Safe mid-run. */
+    bundle(): AuditBundle;
+    /** Return the records accumulated since the last drain and clear
+     *  them from memory. Chain state persists — consecutive drained
+     *  segments re-verify end-to-end via `verifyAuditBundle([...])`. */
+    drain(): AuditBundle;
+    /** Records currently retained (since last drain). */
+    recordCount(): number;
+}
+export declare function auditExport(opts?: AuditExportOptions): AuditExportStrategy;
+/**
+ * Recompute the hash chain of a bundle (or of consecutive drained
+ * segments, in order) and report the exact record where integrity
+ * breaks. Pure function over JSON data — runs offline, long after the
+ * run, with no agent and no strategy instance.
+ *
+ * Checks, in order, per segment:
+ *   1. header format / algorithm / canonicalization are supported
+ *   2. `recordCount` matches `records.length`
+ *   3. segment continuity (`chainHead`/`firstSeq` extend the previous
+ *      segment's `finalHash`/seq range)
+ *   4. per record: `seq` is contiguous, `prevHash` links the previous
+ *      record, and SHA-256 over the canonical preimage (the record
+ *      minus `hash` — so ADDED fields are caught too) matches `hash`
+ *   5. `finalHash` equals the last record's hash
+ */
+export declare function verifyAuditBundle(input: AuditBundle | readonly AuditBundle[]): AuditVerifyResult;

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

@@ -0,0 +1,96 @@
+/**
+ * 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;