agentfootprint 6.43.0 → 6.45.0

package/dist/esm/security/PermissionPolicy.d.ts

@@ -0,0 +1,124 @@
+/**
+ * PermissionPolicy — data-driven role-based authorization for tool dispatch.
+ *
+ * Closes Neo gap #2 (of 8). Permissions are CROSS-CUTTING — they're not
+ * context engineering, they're a guard ON context-engineering operations
+ * (tool dispatch, skill activation, memory writes, output emission).
+ * That's why this lives in `agentfootprint/security`, parallel to the
+ * provider subpaths.
+ *
+ * Two surfaces, one primitive:
+ *   1. `PermissionPolicy.fromRoles({...}, activeRole)` — declarative,
+ *      data-driven, auditable. Production governance.
+ *   2. The PermissionPolicy instance satisfies BOTH:
+ *      - `PermissionChecker` interface (async check; consumed by Agent
+ *        constructor's `permissionChecker` field)
+ *      - sync `isAllowed(toolId)` method (consumed by `gatedTools(...)`
+ *        from `agentfootprint/tool-providers`)
+ *
+ * Pattern: Strategy (GoF) for the role-allowlist policy + Adapter
+ *          (matches `PermissionChecker` interface so it composes with
+ *          existing v2.4 Agent constructor).
+ *
+ * Role: Layer-3 cross-cutting guard. Not Injection. Not provider.
+ *       Lives in its own subpath (`agentfootprint/security`).
+ *
+ * @example  Read-only role for a support agent
+ *   const policy = PermissionPolicy.fromRoles(
+ *     {
+ *       readonly: ['lookup_order', 'get_status', 'list_skills', 'read_skill'],
+ *       support: ['lookup_order', 'get_status', 'process_refund', 'list_skills', 'read_skill'],
+ *     },
+ *     'readonly',
+ *   );
+ *
+ *   policy.isAllowed('lookup_order');     // → true
+ *   policy.isAllowed('process_refund');   // → false (not in readonly role)
+ *
+ *   // As a tool-dispatch gate (composes with gatedTools)
+ *   const provider = gatedTools(staticTools(allTools), (name) => policy.isAllowed(name));
+ *
+ *   // As an Agent permissionChecker (the v2.4 surface)
+ *   const agent = Agent.create({ provider, model, permissionChecker: policy }).build();
+ *
+ * @example  Per-identity role switching at runtime
+ *   const policy = PermissionPolicy.fromRoles({
+ *     readonly: [...],
+ *     admin: [...],
+ *   }, 'readonly');
+ *
+ *   const adminPolicy = policy.withActiveRole('admin');
+ *   // Same allowlist data; different active role.
+ */
+import type { PermissionChecker, PermissionRequest, PermissionDecision } from '../adapters/types.js';
+/**
+ * Map of role name → list of tool ids that role is allowed to invoke.
+ * The shape consumers extend over time as new tools / roles arrive.
+ */
+export type RoleAllowlist = Readonly<Record<string, readonly string[]>>;
+export interface PermissionPolicyOptions {
+    /**
+     * The role allowlist. Each role maps to the tool ids it can invoke.
+     * Tool ids match the `name` field of `Tool.schema.name` exactly.
+     */
+    readonly roles: RoleAllowlist;
+    /**
+     * Which role is active for this policy instance. Calls to
+     * `.isAllowed(toolId)` check against this role's allowlist.
+     * Use `.withActiveRole(name)` to derive a sibling policy with a
+     * different active role.
+     */
+    readonly activeRole: string;
+}
+/**
+ * Data-driven role-based permission policy. Satisfies the v2.4
+ * `PermissionChecker` interface AND exposes a sync `isAllowed` method
+ * for use with `gatedTools` from `agentfootprint/tool-providers`.
+ */
+export declare class PermissionPolicy implements PermissionChecker {
+    private readonly opts;
+    readonly name = "PermissionPolicy";
+    private constructor();
+    /**
+     * Factory: build a role-based policy from a role → tool-ids map and
+     * the role active for this instance.
+     *
+     * Throws if `activeRole` isn't a key in `roles` — fail loud at
+     * config time, not at first denied call.
+     */
+    static fromRoles(roles: RoleAllowlist, activeRole: string): PermissionPolicy;
+    /**
+     * Sync allowlist check. Use as a predicate with `gatedTools`:
+     *
+     *   gatedTools(staticTools(allTools), (toolId) => policy.isAllowed(toolId))
+     *
+     * Returns true iff `toolId` is in the active role's allowlist.
+     * Closes-fail by design: missing role membership = denied.
+     */
+    isAllowed(toolId: string): boolean;
+    /**
+     * Async check matching the `PermissionChecker` interface — consumed
+     * by `Agent.create({ permissionChecker })`. Wraps `isAllowed` with
+     * the structured `PermissionDecision` envelope (allow / deny + a
+     * `policyRuleId` so observability can trace which role decided).
+     *
+     * Today the policy only checks the tool name (request.target).
+     * Future work: also gate by capability ('memory_write', etc.) when
+     * the role allowlist is widened to capability-by-id.
+     */
+    check(request: PermissionRequest): Promise<PermissionDecision>;
+    /**
+     * Derive a sibling policy with a different active role. Same role
+     * map; different active role. Useful for per-identity routing
+     * (one policy instance per request, varying active role per caller).
+     *
+     * Returns a NEW PermissionPolicy — original is unchanged.
+     */
+    withActiveRole(activeRole: string): PermissionPolicy;
+    /** The role name currently active. Useful for observability. */
+    get activeRole(): string;
+    /** All defined role names. Stable order = registration order. */
+    get roles(): readonly string[];
+    /** All tool ids allowed under the current active role. */
+    allowedToolIds(): readonly string[];
+}

package/dist/esm/security/PolicyHaltError.d.ts

@@ -0,0 +1,72 @@
+/**
+ * PolicyHaltError — typed error thrown by `Agent.run()` when a
+ * `PermissionChecker.check()` returns `{ result: 'halt', ... }`.
+ *
+ * Pattern: Typed Error (parallel to `ReliabilityFailFastError`).
+ * Role:    Surface layer for sequence governance / security halts —
+ *          terminates the run cleanly with full forensic context so
+ *          callers can route alerts (PagerDuty / Slack / dashboard)
+ *          based on the rule that fired.
+ * Emits:   N/A (this file DEFINES the error class; the corresponding
+ *          observability event `agentfootprint.permission.halt` fires
+ *          from the toolCalls handler at the moment the halt resolves).
+ *
+ * Strict ordering on halt — the framework guarantees:
+ *   1. Synthetic `tool_result` (with `tellLLM` content) appended to
+ *      `scope.history` so the Anthropic / OpenAI tool_use ↔ tool_result
+ *      pairing protocol is satisfied.
+ *   2. `agentfootprint.permission.halt` event emitted.
+ *   3. Stage commits (commitLog has the entry; runtimeStageId is
+ *      complete).
+ *   4. THEN this error is thrown by `Agent.run()`.
+ *
+ * @example
+ *   try {
+ *     await agent.run({ message: 'help me with order #42' });
+ *   } catch (e) {
+ *     if (e instanceof PolicyHaltError) {
+ *       console.log(`HALT: rule='${e.reason}' iteration=${e.iteration}`);
+ *       console.log(`Sequence: ${e.sequence.map(c => c.name).join(' → ')}`);
+ *       if (e.reason.startsWith('security:')) {
+ *         await pagerDuty.notify(e);
+ *       }
+ *     } else {
+ *       throw e;
+ *     }
+ *   }
+ */
+import type { LLMMessage, ToolCallEntry, ToolResultContent } from '../adapters/types.js';
+export interface PolicyHaltContext {
+    /** Telemetry tag from the matched rule. Stable across versions. */
+    readonly reason: string;
+    /** Content delivered to the LLM as the synthetic tool_result. */
+    readonly tellLLM?: ToolResultContent;
+    /** Sequence of tool calls dispatched this run, including the proposed
+     *  call that triggered the halt (which did NOT execute). */
+    readonly sequence: readonly ToolCallEntry[];
+    /** ReAct iteration the halt fired on. */
+    readonly iteration: number;
+    /** Conversation history at halt time, including the synthetic tool_result. */
+    readonly history: readonly LLMMessage[];
+    /** The proposed tool call that triggered the halt (not executed). */
+    readonly proposed: {
+        readonly name: string;
+        readonly args: unknown;
+    };
+    /** Identifier of the PermissionChecker that returned `'halt'`. */
+    readonly checkerId?: string;
+}
+export declare class PolicyHaltError extends Error {
+    readonly code: "ERR_POLICY_HALT";
+    readonly reason: string;
+    readonly tellLLM?: ToolResultContent;
+    readonly sequence: readonly ToolCallEntry[];
+    readonly iteration: number;
+    readonly history: readonly LLMMessage[];
+    readonly proposed: {
+        readonly name: string;
+        readonly args: unknown;
+    };
+    readonly checkerId?: string;
+    constructor(ctx: PolicyHaltContext);
+}

package/dist/esm/security/extractSequence.d.ts

@@ -0,0 +1,46 @@
+/**
+ * extractSequence — derive the in-flight tool-call sequence from
+ * `scope.history` for `PermissionChecker.check()`.
+ *
+ * Pattern: Pure function over conversation history.
+ * Role:    Single source of truth — sequence is reconstructed on
+ *          demand from `LLMMessage[]` instead of maintained as
+ *          parallel state in scope. Survives `agent.resumeOnError`
+ *          correctly because the history IS the durable artifact.
+ * Emits:   N/A (pure compute).
+ *
+ * The sequence reads the assistant turns' `toolCalls` blocks in order.
+ * Calls that were denied at the gate (synthetic tool_results in history
+ * but no `tool.execute()` invocation) are NOT included — the sequence
+ * reflects what actually dispatched, not what was attempted.
+ *
+ * Detection of "did this call dispatch?" — we look at the matching
+ * `tool` message and check its content. Synthetic deny messages match
+ * a known prefix; everything else is a real dispatch. This pairs the
+ * sender (assistant.toolCalls[i].id) with the receiver (tool.toolCallId).
+ */
+import type { LLMMessage, ToolCallEntry } from '../adapters/types.js';
+/** Prefix the framework writes on synthetic deny tool_results. Used to
+ *  distinguish "denied but in history" from "actually dispatched". */
+export declare const SYNTHETIC_DENY_PREFIX = "[permission denied:";
+export interface ExtractSequenceOptions {
+    /**
+     * Resolver: tool name → providerId. When the tool was registered via
+     * `staticTools(...)` / `.tool(...)`, returns `'local'` (or the resolver's
+     * choice). When registered via a `discoveryProvider`, returns the
+     * provider's `id`. Lets policies match cross-hub patterns.
+     */
+    readonly resolveProviderId?: (toolName: string) => string | undefined;
+}
+/**
+ * Walk `history` in order, collect each dispatched tool call into the
+ * sequence. Only calls that produced a non-denied tool_result are
+ * included.
+ *
+ * @param history Conversation history at check time.
+ * @param iteration Current ReAct iteration (used to tag the proposed
+ *                  call's iteration if you append it).
+ * @param options Optional resolver for `providerId`.
+ * @returns The dispatched-call sequence, in chronological order.
+ */
+export declare function extractSequence(history: readonly LLMMessage[], iteration: number, options?: ExtractSequenceOptions): ToolCallEntry[];

package/dist/esm/security/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * agentfootprint/security — cross-cutting authorization + governance.
+ *
+ * Permissions are NOT context engineering — they're a guard ON
+ * context-engineering operations (tool dispatch, skill activation,
+ * memory writes, output emission). That's why this lives in its own
+ * subpath, parallel to `agentfootprint/tool-providers` and the
+ * `agentfootprint/memory-*` and `agentfootprint/providers` subpaths.
+ *
+ * Today's surface is small and data-driven on purpose: one role
+ * allowlist primitive that satisfies BOTH the v2.4 `PermissionChecker`
+ * interface AND a sync `isAllowed(toolId)` predicate for use with
+ * `gatedTools` from `agentfootprint/tool-providers`.
+ *
+ * Future additions (capability gating, gate_open flows, audit logs)
+ * land here without expanding the public root barrel.
+ *
+ * @example
+ *   import { PermissionPolicy } from 'agentfootprint/security';
+ *   import { gatedTools, staticTools } from 'agentfootprint/tool-providers';
+ *
+ *   const policy = PermissionPolicy.fromRoles(
+ *     {
+ *       readonly: ['lookup', 'list_skills', 'read_skill'],
+ *       admin:    ['lookup', 'list_skills', 'read_skill', 'write', 'delete'],
+ *     },
+ *     'readonly',
+ *   );
+ *
+ *   const provider = gatedTools(
+ *     staticTools(allTools),
+ *     (name) => policy.isAllowed(name),
+ *   );
+ *
+ *   const agent = Agent.create({ provider, model, permissionChecker: policy }).build();
+ */
+export { PermissionPolicy } from './PermissionPolicy.js';
+export type { RoleAllowlist, PermissionPolicyOptions } from './PermissionPolicy.js';
+export { PolicyHaltError } from './PolicyHaltError.js';
+export type { PolicyHaltContext } from './PolicyHaltError.js';
+export { extractSequence, SYNTHETIC_DENY_PREFIX } from './extractSequence.js';
+export type { ExtractSequenceOptions } from './extractSequence.js';
+export { redactThinkingBlocks, REDACTED_PLACEHOLDER } from './thinkingRedaction.js';
+export type { PermissionChecker, PermissionRequest, PermissionDecision, ToolCallEntry, ToolResultContent, } from '../adapters/types.js';

package/dist/esm/security/thinkingRedaction.d.ts

@@ -0,0 +1,50 @@
+/**
+ * thinkingRedaction — content scrubbing for ThinkingBlock[] before
+ * persistence + audit-log adapters fire.
+ *
+ * Pattern: Pure function. Same shape as the v2.4 RedactionPolicy.scope-
+ * patterns / emit-patterns helpers — regex match + replace.
+ *
+ * Mental model — TWO-LAYER persistence:
+ *   - LLMMessage.thinkingBlocks IS persisted to scope.history (required
+ *     for Anthropic signature round-trip).
+ *   - Audit-log adapters (CloudWatch, Datadog OTel, etc.) read from
+ *     scope.history. Sensitive reasoning (PII in chain-of-thought,
+ *     internal IDs the model worked through) lands there too.
+ *   - This helper scrubs content patterns BEFORE the assistant message
+ *     pushes to scope.history, so the audit-log surface only sees
+ *     redacted content while the LLM still sees the unredacted reasoning
+ *     for round-trip integrity.
+ *
+ * The signature field is NEVER touched by redaction — Anthropic's
+ * server-side signature is bound to the original content; modifying
+ * content here would invalidate the signature. Resolution: signature
+ * survives byte-exact, content gets scrubbed. This means the Anthropic
+ * API will reject the next turn IF the consumer wired thinkingPatterns
+ * AND uses Anthropic with extended-thinking-plus-tools. Document.
+ *
+ * Recommended use:
+ *   - DON'T wire thinkingPatterns when using Anthropic extended thinking
+ *     + tool calls (signature breaks).
+ *   - DO wire thinkingPatterns when using OpenAI o1/o3 (no signature,
+ *     no round-trip requirement) or for offline log scrubbing.
+ *   - For Anthropic + sensitive reasoning, prefer audit-log-side
+ *     redaction (filter in your CloudWatch / Datadog adapter rather
+ *     than the framework's persistence point).
+ */
+import type { ThinkingBlock } from '../thinking/types.js';
+/** Sentinel string used in place of redacted content. */
+export declare const REDACTED_PLACEHOLDER = "[REDACTED]";
+/**
+ * Return a copy of `blocks` with each block's `content` field scrubbed
+ * by every pattern in `patterns`. Returns the input array unchanged
+ * when `patterns` is undefined, empty, or no block content matches.
+ *
+ * Signature + summary + providerMeta fields are preserved BYTE-EXACT
+ * — only `content` is touched.
+ *
+ * Anthropic signature warning: scrubbing content invalidates the
+ * Anthropic server-side signature. Round-trip will fail with HTTP 400
+ * on the next turn. Document this in the consumer recipe.
+ */
+export declare function redactThinkingBlocks(blocks: readonly ThinkingBlock[], patterns: readonly RegExp[] | undefined): readonly ThinkingBlock[];

package/dist/esm/status.d.ts

@@ -0,0 +1,48 @@
+/**
+ * agentfootprint/status — chat-bubble status surface.
+ *
+ * Pattern: pure projection. `selectStatus` walks the typed
+ *          event log forward, tracking active pause / tool / LLM state,
+ *          and returns the CURRENT thinking state (or null when the
+ *          bubble should hide).
+ * Role:    Outer ring. Consumers (Lens, custom chat UIs, embedded
+ *          widgets) call this to drive a "what is the agent doing
+ *          right now?" indicator. Output feeds `renderStatusLine`
+ *          which resolves a template + variables to a final string.
+ *
+ * Why a subpath:
+ *   - Consistent with `agentfootprint/observe` and
+ *     `agentfootprint/locales` — every observability surface gets its
+ *     own entry point.
+ *   - Self-documenting at the import line: `from 'agentfootprint/status'`
+ *     vs an opaque main-export grab.
+ *   - Future home for extended-thinking primitives (Anthropic
+ *     `thinking_delta` / `redacted_thinking` blocks). Adding them here
+ *     is non-breaking; consumers already importing from
+ *     `agentfootprint/status` get the new state surface for free.
+ *
+ * Back-compat: every export here is also re-exported from the main
+ * `agentfootprint` entry. Migrating consumers is mechanical (rewrite
+ * the import path); both paths work.
+ *
+ * State machine (4 states + null):
+ *
+ *      ┌──────────┐  llm.start, no tools yet
+ *  ────┤  idle    ├────────────────────────────► "Thinking…"
+ *      └──────────┘
+ *
+ *      ┌──────────┐  stream.token chunks accumulate
+ *  ────┤streaming ├────────────────────────────► "{{partial}}"
+ *      └──────────┘
+ *
+ *      ┌──────────┐  tool.start, no tool.end yet
+ *  ────┤   tool   ├────────────────────────────► "Working on `weather`…"
+ *      └──────────┘                               (or per-tool override)
+ *
+ *      ┌──────────┐  pause.request, no resume yet
+ *  ────┤  paused  ├────────────────────────────► "Waiting on you: …"
+ *      └──────────┘
+ *
+ *      (null)        run done / between calls   → bubble hidden
+ */
+export { defaultStatusTemplates, selectStatus, renderStatusLine, type StatusState, type StatusKind, type StatusTemplates, type StatusContext, } from './recorders/observability/status/statusTemplates.js';

package/dist/esm/strategies/attach.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Wire each grouped strategy to its data source on the dispatcher /
+ * recorder substrate. These are the 4 `enable.*` facades' actual
+ * implementations; `RunnerBase.enable` calls them with the right
+ * dispatcher / attach handle.
+ *
+ * Pattern: every facade follows the same shape:
+ *
+ *   1. Resolve strategy (consumer-supplied OR default)
+ *   2. Run `strategy.validate?()` — early-fail on misconfig (New Relic
+ *      panel review)
+ *   3. Set up subscription / projection
+ *   4. Apply per-strategy event-type filter (`relevantEventTypes`)
+ *   5. Apply per-call sample rate
+ *   6. Wrap calls in try/catch — route errors to `_onError` (passive
+ *      recorder rule: never throw to caller)
+ *   7. Return Unsubscribe (or handle for lens)
+ */
+import type { EventDispatcher, Unsubscribe } from '../events/dispatcher.js';
+import type { ObservabilityStrategy, CostStrategy, LiveStatusStrategy, CommonStrategyOptions, ObservabilityTier } from './types.js';
+import { type StatusTemplates } from '../recorders/observability/status/statusTemplates.js';
+export interface ObservabilityEnableOptions extends CommonStrategyOptions {
+    /** Cost-of-on knob. `'minimal'` → only error + lifecycle events.
+     *  `'standard'` → most domains. `'firehose'` → every event including
+     *  per-token streams. Default `'standard'`. */
+    readonly tier?: ObservabilityTier;
+    readonly strategy?: ObservabilityStrategy;
+}
+export declare function attachObservabilityStrategy(dispatcher: EventDispatcher, opts?: ObservabilityEnableOptions): Unsubscribe;
+export interface CostEnableOptions extends CommonStrategyOptions {
+    readonly strategy?: CostStrategy;
+}
+/**
+ * Subscribe to `agentfootprint.cost.tick` events, project payload into
+ * the canonical `CostTick` shape, hand to strategy.
+ */
+export declare function attachCostStrategy(dispatcher: EventDispatcher, opts?: CostEnableOptions): Unsubscribe;
+export interface LiveStatusEnableOptions extends CommonStrategyOptions {
+    readonly strategy: LiveStatusStrategy;
+    /** Override the bundled English thinking templates with locale /
+     *  per-tool / per-skill overrides. Same shape as
+     *  `agent.thinkingTemplates(...)`. */
+    readonly templates?: StatusTemplates;
+    /** App name woven into `{{appName}}` template var. */
+    readonly appName?: string;
+}
+export declare function attachLiveStatusStrategy(dispatcher: EventDispatcher, opts: LiveStatusEnableOptions): Unsubscribe;

package/dist/esm/strategies/compose.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `compose([...])` — fan-out combinator.
+ *
+ * Pattern: Composite. Same shape as React's children array, RxJS's
+ *          `merge`, OTel's `MultiSpanProcessor`. Pass an array of
+ *          strategies; get back a single strategy that fan-outs each
+ *          call to every child.
+ *
+ * Use when:
+ *   - Multi-vendor pipelines (`compose([datadog(), otel(), console()])`)
+ *   - Test instrumentation alongside production sink
+ *     (`compose([inMemorySink(), stripeBilling()])`) so test assertions
+ *     can read ticks while production also ships
+ *   - Tier-staging — local dev mirrors what production sees
+ *
+ * Per-child error isolation: if one child's `exportEvent` throws, the
+ * other children still receive the event. The throwing child's
+ * `_onError` is called (if present); otherwise the error is logged
+ * via `console.warn` once. One bad sink never breaks the chain.
+ *
+ * Capabilities are OR-ed across children — if any child supports a
+ * capability, the composite reports it as supported. The dispatcher
+ * uses this to decide whether to bother building event objects at all.
+ *
+ * Idempotent operations:
+ *   - `flush()` — calls every child's `flush()` (sync or async)
+ *     concurrently, awaits all
+ *   - `stop()` — calls every child's `stop()` once, in order; failures
+ *     in one child don't block the others
+ */
+import type { ObservabilityStrategy, CostStrategy, LiveStatusStrategy, LensStrategy } from './types.js';
+/**
+ * Compose multiple ObservabilityStrategies into a single fan-out.
+ *
+ * @example
+ *   const all = composeObservability([
+ *     consoleObservability(),
+ *     cloudwatchObservability({ logGroupName: '/agent/prod' }),
+ *     otelObservability({ serviceName: 'my-agent-prod' }),
+ *   ]);
+ */
+export declare function composeObservability(children: readonly ObservabilityStrategy[]): ObservabilityStrategy;
+/** Compose CostStrategies. */
+export declare function composeCost(children: readonly CostStrategy[]): CostStrategy;
+/** Compose LiveStatusStrategies. */
+export declare function composeLiveStatus(children: readonly LiveStatusStrategy[]): LiveStatusStrategy;
+/** Compose LensStrategies. */
+export declare function composeLens(children: readonly LensStrategy[]): LensStrategy;

package/dist/esm/strategies/defaults/chatBubbleLiveStatus.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `chatBubbleLiveStatus()` — default LiveStatusStrategy.
+ *
+ * Pattern: Strategy. Adapter for a consumer-supplied callback.
+ * Role:    The "every chat UI" sink. Wraps a `(line: string) => void`
+ *          callback so the consumer just hands us the function their
+ *          chat-bubble component needs and we drive it on every
+ *          rendered status update.
+ *
+ * Use when:
+ *   - Building a chat UI (Neo, Lens, embedded widget) where the
+ *     consumer owns rendering but not state derivation
+ *   - Tier-1 of compose chains (`compose([chatBubble(setLine), stdout()])`
+ *     so dev console mirrors what the user sees)
+ *
+ * The callback runs on EVERY status transition. Consumer can debounce
+ * / coalesce per their needs (we don't impose UI policy).
+ */
+import type { LiveStatusStrategy } from '../types.js';
+export interface ChatBubbleLiveStatusOptions {
+    /**
+     * Required — called per status update with the rendered line.
+     * Pass `setStatus` from your React component, or any function
+     * whose job is "show this line in the chat bubble."
+     *
+     * NOTE: this is INTENTIONALLY the only callback. If you need access
+     * to the underlying `StatusState` (for color-per-state, animation
+     * triggers, etc.), build your own `LiveStatusStrategy` directly OR
+     * use `compose([chatBubbleLiveStatus({onLine}), customStrategy])`.
+     * We don't surface `StatusState` here because it's an INTERNAL
+     * shape — exposing it would couple consumer UIs to changes in the
+     * state machine.
+     */
+    readonly onLine: (line: string) => void;
+}
+export declare function chatBubbleLiveStatus(opts: ChatBubbleLiveStatusOptions): LiveStatusStrategy;

package/dist/esm/strategies/defaults/consoleObservability.d.ts

@@ -0,0 +1,42 @@
+/**
+ * `consoleObservability()` — default ObservabilityStrategy.
+ *
+ * Pattern: Strategy. Adapter for `globalThis.console`. Used when no
+ *          vendor-specific strategy is configured (zero-config dev
+ *          experience). Same role as `NoOpCacheStrategy` is for the
+ *          cache layer.
+ * Role:    Tier-1 fallback — print every event to the console with a
+ *          one-line type+payload summary. Vendor-neutral, dependency-
+ *          free, works in browser + Node + Deno + Bun.
+ *
+ * Use when:
+ *   - Local development (`agent.enable.observability()` with no opts)
+ *   - CI logs ("what events fired during this test?")
+ *   - Tier-1 of compose chains (`compose([console(), datadog()])`)
+ *
+ * Don't use when: production. Console output is unstructured + can't
+ * be queried; switch to a vendor strategy (Datadog, OTel, CloudWatch).
+ */
+import type { AgentfootprintEvent } from '../../events/registry.js';
+import type { ObservabilityStrategy } from '../types.js';
+export interface ConsoleObservabilityOptions {
+    /**
+     * Where to write. Defaults to `globalThis.console`. Override for
+     * tests or to wrap with a custom sink (browser DevTools' grouped
+     * console, a Node.js stream, etc.).
+     */
+    readonly logger?: {
+        log(...args: unknown[]): void;
+    };
+    /**
+     * Custom line formatter. Receives the typed event; returns the line.
+     * Defaults to `[type] payload-as-JSON`. Override to colorize, filter
+     * fields, or pretty-print.
+     */
+    readonly format?: (event: AgentfootprintEvent) => string;
+}
+/**
+ * Factory. Returns a fresh ObservabilityStrategy each call so multiple
+ * agents in the same process get independent instances.
+ */
+export declare function consoleObservability(opts?: ConsoleObservabilityOptions): ObservabilityStrategy;

package/dist/esm/strategies/defaults/inMemorySinkCost.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `inMemorySinkCost()` — default CostStrategy.
+ *
+ * Pattern: Strategy. In-process accumulator. Same role as InMemoryStore
+ *          for memory-providers.
+ * Role:    Tier-1 fallback — accumulate cost ticks in a process-local
+ *          array. Consumer reads via `getTicks()` or hooks `onRecord`
+ *          for streaming. Vendor-free.
+ *
+ * Use when:
+ *   - Tests / CI ("what cost did this run accrue?")
+ *   - Local dev before billing integration
+ *   - Tier-1 of compose chains (`compose([inMemorySink(), stripeBilling()])`
+ *     so test assertions can read ticks while production also ships)
+ *
+ * Don't use when: process is long-running with high cost-tick volume —
+ * the buffer grows unbounded. Add a `maxTicks` cap (drops oldest) or
+ * pair with a streaming strategy (`stripeBilling`, `webhook`).
+ */
+import type { CostStrategy, CostTick } from '../types.js';
+export interface InMemorySinkCostOptions {
+    /**
+     * Optional streaming hook called per tick. Useful for piping the
+     * accumulator into a custom sink without writing a full strategy.
+     */
+    readonly onRecord?: (tick: CostTick) => void;
+    /**
+     * Maximum ticks to retain in the buffer. When exceeded, the OLDEST
+     * tick is dropped (FIFO). Default `Infinity` — no cap.
+     */
+    readonly maxTicks?: number;
+}
+/**
+ * Extended interface — the in-memory sink also exposes the buffer
+ * for read-back. Strategies aren't required to do this; this one
+ * does because that IS its purpose (accumulate for inspection).
+ */
+export interface InMemorySinkCostStrategy extends CostStrategy {
+    /** Snapshot of the buffered ticks. O(n) per call — for cheap
+     *  polling use `getTicksCount()` + `getTicksSince(idx)`. */
+    readonly getTicks: () => readonly CostTick[];
+    /** Cheap O(1) read for "did anything new arrive?" polling. */
+    readonly getTicksCount: () => number;
+    /** Incremental read — returns ticks WITH index >= `idx`. Lets a
+     *  dashboard poll cheaply by tracking its last-seen index. */
+    readonly getTicksSince: (idx: number) => readonly CostTick[];
+    /** Drop all buffered ticks. */
+    readonly clear: () => void;
+}
+export declare function inMemorySinkCost(opts?: InMemorySinkCostOptions): InMemorySinkCostStrategy;

package/dist/esm/strategies/defaults/index.d.ts

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