agentfootprint 6.44.0 → 6.45.0

package/dist/esm/events/registry.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Event registry — every typed `agentfootprint.*` event (see ALL_EVENT_TYPES;
+ * the event/domain counts in the docs are asserted against this file by
+ * test/events/unit/registry.test.ts, so don't hardcode counts here).
+ *
+ * Pattern: Discriminated Union + Typed Factory (Gang of Four adapted for TS).
+ * Role:    The stable public event contract — the "ports" of the hexagonal
+ *          architecture (Cockburn, 2005).
+ * Emits:   N/A — this file DEFINES event types and factory helpers.
+ *
+ * Consumers subscribe via `.on(type, listener)`. Emitters construct events
+ * via typed helpers (e.g. `makeContextInjected(payload)`) rather than raw
+ * strings — compile-time safety prevents typos and payload drift.
+ *
+ * Events are additive within a major version; breaking changes require a
+ * major bump. See agentfootprint_v2_detailed_design.md for rules.
+ */
+import type { AgentfootprintEventEnvelope } from './types.js';
+import type { AgentHandoffPayload, AgentIterationEndPayload, AgentIterationStartPayload, AgentRouteDecidedPayload, AgentTurnEndPayload, AgentTurnStartPayload, CompositionEnterPayload, CompositionExitPayload, ConditionalRouteDecidedPayload, ContextBudgetPressurePayload, ContextEvaluatedPayload, ContextEvictedPayload, ContextInjectedPayload, ContextSlotComposedPayload, CostLimitHitPayload, CostTickPayload, EmbeddingGeneratedPayload, ErrorFatalPayload, ErrorRecoveredPayload, ErrorRetriedPayload, EvalScorePayload, EvalThresholdCrossedPayload, AgentOutputSchemaValidationFailedPayload, AgentThinkingParseFailedPayload, StreamThinkingDeltaPayload, StreamThinkingEndPayload, FallbackTriggeredPayload, LLMEndPayload, LLMStartPayload, LLMTokenPayload, LoopIterationExitPayload, LoopIterationStartPayload, MemoryAttachedPayload, MemoryDetachedPayload, MemoryStrategyAppliedPayload, MemoryWrittenPayload, ParallelBranchCompletePayload, ParallelForkStartPayload, ParallelMergeEndPayload, PauseRequestPayload, PauseResumePayload, PermissionCheckPayload, PermissionGateClosedPayload, PermissionHaltPayload, PermissionGateOpenedPayload, CredentialRequestedPayload, CredentialAcquiredPayload, CredentialAuthorizationRequiredPayload, CredentialFailedPayload, ReliabilityFailFastPayload, ReliabilityRetriedPayload, ReliabilityRecoveredPayload, RiskFlaggedPayload, SkillActivatedPayload, SkillDeactivatedPayload, SkillRejectedPayload, ToolEndPayload, ToolsActivatedPayload, ToolsDeactivatedPayload, ToolsDiscoveryStartedPayload, ToolsDiscoveryCompletedPayload, ToolsDiscoveryFailedPayload, ToolsOfferedPayload, ToolStartPayload, ValidationArgsInvalidPayload } from './payloads.js';
+export declare const EVENT_NAMES: {
+    readonly composition: {
+        readonly enter: "agentfootprint.composition.enter";
+        readonly exit: "agentfootprint.composition.exit";
+        readonly forkStart: "agentfootprint.composition.fork_start";
+        readonly branchComplete: "agentfootprint.composition.branch_complete";
+        readonly mergeEnd: "agentfootprint.composition.merge_end";
+        readonly routeDecided: "agentfootprint.composition.route_decided";
+        readonly iterationStart: "agentfootprint.composition.iteration_start";
+        readonly iterationExit: "agentfootprint.composition.iteration_exit";
+    };
+    readonly agent: {
+        readonly turnStart: "agentfootprint.agent.turn_start";
+        readonly turnEnd: "agentfootprint.agent.turn_end";
+        readonly iterationStart: "agentfootprint.agent.iteration_start";
+        readonly iterationEnd: "agentfootprint.agent.iteration_end";
+        readonly routeDecided: "agentfootprint.agent.route_decided";
+        readonly handoff: "agentfootprint.agent.handoff";
+        readonly outputSchemaValidationFailed: "agentfootprint.agent.output_schema_validation_failed";
+        readonly thinkingParseFailed: "agentfootprint.agent.thinking_parse_failed";
+    };
+    readonly stream: {
+        readonly llmStart: "agentfootprint.stream.llm_start";
+        readonly llmEnd: "agentfootprint.stream.llm_end";
+        readonly token: "agentfootprint.stream.token";
+        readonly toolStart: "agentfootprint.stream.tool_start";
+        readonly toolEnd: "agentfootprint.stream.tool_end";
+        readonly thinkingDelta: "agentfootprint.stream.thinking_delta";
+        readonly thinkingEnd: "agentfootprint.stream.thinking_end";
+    };
+    readonly context: {
+        readonly injected: "agentfootprint.context.injected";
+        readonly evicted: "agentfootprint.context.evicted";
+        readonly slotComposed: "agentfootprint.context.slot_composed";
+        readonly budgetPressure: "agentfootprint.context.budget_pressure";
+        readonly evaluated: "agentfootprint.context.evaluated";
+    };
+    readonly memory: {
+        readonly strategyApplied: "agentfootprint.memory.strategy_applied";
+        readonly attached: "agentfootprint.memory.attached";
+        readonly detached: "agentfootprint.memory.detached";
+        readonly written: "agentfootprint.memory.written";
+    };
+    readonly tools: {
+        readonly offered: "agentfootprint.tools.offered";
+        readonly activated: "agentfootprint.tools.activated";
+        readonly deactivated: "agentfootprint.tools.deactivated";
+        readonly discoveryStarted: "agentfootprint.tools.discovery_started";
+        readonly discoveryCompleted: "agentfootprint.tools.discovery_completed";
+        readonly discoveryFailed: "agentfootprint.tools.discovery_failed";
+    };
+    readonly skill: {
+        readonly activated: "agentfootprint.skill.activated";
+        readonly deactivated: "agentfootprint.skill.deactivated";
+        readonly rejected: "agentfootprint.skill.rejected";
+    };
+    readonly validation: {
+        readonly argsInvalid: "agentfootprint.validation.args_invalid";
+    };
+    readonly permission: {
+        readonly check: "agentfootprint.permission.check";
+        readonly gateOpened: "agentfootprint.permission.gate_opened";
+        readonly gateClosed: "agentfootprint.permission.gate_closed";
+        readonly halt: "agentfootprint.permission.halt";
+    };
+    readonly credential: {
+        readonly requested: "agentfootprint.credential.requested";
+        readonly acquired: "agentfootprint.credential.acquired";
+        readonly authorizationRequired: "agentfootprint.credential.authorization_required";
+        readonly failed: "agentfootprint.credential.failed";
+    };
+    readonly risk: {
+        readonly flagged: "agentfootprint.risk.flagged";
+    };
+    readonly fallback: {
+        readonly triggered: "agentfootprint.fallback.triggered";
+    };
+    readonly cost: {
+        readonly tick: "agentfootprint.cost.tick";
+        readonly limitHit: "agentfootprint.cost.limit_hit";
+    };
+    readonly eval: {
+        readonly score: "agentfootprint.eval.score";
+        readonly thresholdCrossed: "agentfootprint.eval.threshold_crossed";
+    };
+    readonly error: {
+        readonly retried: "agentfootprint.error.retried";
+        readonly recovered: "agentfootprint.error.recovered";
+        readonly fatal: "agentfootprint.error.fatal";
+    };
+    readonly reliability: {
+        readonly failFast: "agentfootprint.reliability.fail_fast";
+        readonly retried: "agentfootprint.reliability.retried";
+        readonly recovered: "agentfootprint.reliability.recovered";
+    };
+    readonly pause: {
+        readonly request: "agentfootprint.pause.request";
+        readonly resume: "agentfootprint.pause.resume";
+    };
+    readonly embedding: {
+        readonly generated: "agentfootprint.embedding.generated";
+    };
+};
+export interface AgentfootprintEventMap {
+    'agentfootprint.composition.enter': AgentfootprintEventEnvelope<'agentfootprint.composition.enter', CompositionEnterPayload>;
+    'agentfootprint.composition.exit': AgentfootprintEventEnvelope<'agentfootprint.composition.exit', CompositionExitPayload>;
+    'agentfootprint.composition.fork_start': AgentfootprintEventEnvelope<'agentfootprint.composition.fork_start', ParallelForkStartPayload>;
+    'agentfootprint.composition.branch_complete': AgentfootprintEventEnvelope<'agentfootprint.composition.branch_complete', ParallelBranchCompletePayload>;
+    'agentfootprint.composition.merge_end': AgentfootprintEventEnvelope<'agentfootprint.composition.merge_end', ParallelMergeEndPayload>;
+    'agentfootprint.composition.route_decided': AgentfootprintEventEnvelope<'agentfootprint.composition.route_decided', ConditionalRouteDecidedPayload>;
+    'agentfootprint.composition.iteration_start': AgentfootprintEventEnvelope<'agentfootprint.composition.iteration_start', LoopIterationStartPayload>;
+    'agentfootprint.composition.iteration_exit': AgentfootprintEventEnvelope<'agentfootprint.composition.iteration_exit', LoopIterationExitPayload>;
+    'agentfootprint.agent.turn_start': AgentfootprintEventEnvelope<'agentfootprint.agent.turn_start', AgentTurnStartPayload>;
+    'agentfootprint.agent.turn_end': AgentfootprintEventEnvelope<'agentfootprint.agent.turn_end', AgentTurnEndPayload>;
+    'agentfootprint.agent.iteration_start': AgentfootprintEventEnvelope<'agentfootprint.agent.iteration_start', AgentIterationStartPayload>;
+    'agentfootprint.agent.iteration_end': AgentfootprintEventEnvelope<'agentfootprint.agent.iteration_end', AgentIterationEndPayload>;
+    'agentfootprint.agent.route_decided': AgentfootprintEventEnvelope<'agentfootprint.agent.route_decided', AgentRouteDecidedPayload>;
+    'agentfootprint.agent.handoff': AgentfootprintEventEnvelope<'agentfootprint.agent.handoff', AgentHandoffPayload>;
+    'agentfootprint.agent.output_schema_validation_failed': AgentfootprintEventEnvelope<'agentfootprint.agent.output_schema_validation_failed', AgentOutputSchemaValidationFailedPayload>;
+    'agentfootprint.agent.thinking_parse_failed': AgentfootprintEventEnvelope<'agentfootprint.agent.thinking_parse_failed', AgentThinkingParseFailedPayload>;
+    'agentfootprint.stream.llm_start': AgentfootprintEventEnvelope<'agentfootprint.stream.llm_start', LLMStartPayload>;
+    'agentfootprint.stream.llm_end': AgentfootprintEventEnvelope<'agentfootprint.stream.llm_end', LLMEndPayload>;
+    'agentfootprint.stream.token': AgentfootprintEventEnvelope<'agentfootprint.stream.token', LLMTokenPayload>;
+    'agentfootprint.stream.tool_start': AgentfootprintEventEnvelope<'agentfootprint.stream.tool_start', ToolStartPayload>;
+    'agentfootprint.stream.tool_end': AgentfootprintEventEnvelope<'agentfootprint.stream.tool_end', ToolEndPayload>;
+    'agentfootprint.stream.thinking_delta': AgentfootprintEventEnvelope<'agentfootprint.stream.thinking_delta', StreamThinkingDeltaPayload>;
+    'agentfootprint.stream.thinking_end': AgentfootprintEventEnvelope<'agentfootprint.stream.thinking_end', StreamThinkingEndPayload>;
+    'agentfootprint.context.injected': AgentfootprintEventEnvelope<'agentfootprint.context.injected', ContextInjectedPayload>;
+    'agentfootprint.context.evicted': AgentfootprintEventEnvelope<'agentfootprint.context.evicted', ContextEvictedPayload>;
+    'agentfootprint.context.slot_composed': AgentfootprintEventEnvelope<'agentfootprint.context.slot_composed', ContextSlotComposedPayload>;
+    'agentfootprint.context.budget_pressure': AgentfootprintEventEnvelope<'agentfootprint.context.budget_pressure', ContextBudgetPressurePayload>;
+    'agentfootprint.context.evaluated': AgentfootprintEventEnvelope<'agentfootprint.context.evaluated', ContextEvaluatedPayload>;
+    'agentfootprint.memory.strategy_applied': AgentfootprintEventEnvelope<'agentfootprint.memory.strategy_applied', MemoryStrategyAppliedPayload>;
+    'agentfootprint.memory.attached': AgentfootprintEventEnvelope<'agentfootprint.memory.attached', MemoryAttachedPayload>;
+    'agentfootprint.memory.detached': AgentfootprintEventEnvelope<'agentfootprint.memory.detached', MemoryDetachedPayload>;
+    'agentfootprint.memory.written': AgentfootprintEventEnvelope<'agentfootprint.memory.written', MemoryWrittenPayload>;
+    'agentfootprint.tools.offered': AgentfootprintEventEnvelope<'agentfootprint.tools.offered', ToolsOfferedPayload>;
+    'agentfootprint.tools.activated': AgentfootprintEventEnvelope<'agentfootprint.tools.activated', ToolsActivatedPayload>;
+    'agentfootprint.tools.deactivated': AgentfootprintEventEnvelope<'agentfootprint.tools.deactivated', ToolsDeactivatedPayload>;
+    'agentfootprint.tools.discovery_started': AgentfootprintEventEnvelope<'agentfootprint.tools.discovery_started', ToolsDiscoveryStartedPayload>;
+    'agentfootprint.tools.discovery_completed': AgentfootprintEventEnvelope<'agentfootprint.tools.discovery_completed', ToolsDiscoveryCompletedPayload>;
+    'agentfootprint.tools.discovery_failed': AgentfootprintEventEnvelope<'agentfootprint.tools.discovery_failed', ToolsDiscoveryFailedPayload>;
+    'agentfootprint.skill.activated': AgentfootprintEventEnvelope<'agentfootprint.skill.activated', SkillActivatedPayload>;
+    'agentfootprint.skill.deactivated': AgentfootprintEventEnvelope<'agentfootprint.skill.deactivated', SkillDeactivatedPayload>;
+    'agentfootprint.skill.rejected': AgentfootprintEventEnvelope<'agentfootprint.skill.rejected', SkillRejectedPayload>;
+    'agentfootprint.validation.args_invalid': AgentfootprintEventEnvelope<'agentfootprint.validation.args_invalid', ValidationArgsInvalidPayload>;
+    'agentfootprint.permission.check': AgentfootprintEventEnvelope<'agentfootprint.permission.check', PermissionCheckPayload>;
+    'agentfootprint.permission.gate_opened': AgentfootprintEventEnvelope<'agentfootprint.permission.gate_opened', PermissionGateOpenedPayload>;
+    'agentfootprint.permission.gate_closed': AgentfootprintEventEnvelope<'agentfootprint.permission.gate_closed', PermissionGateClosedPayload>;
+    'agentfootprint.permission.halt': AgentfootprintEventEnvelope<'agentfootprint.permission.halt', PermissionHaltPayload>;
+    'agentfootprint.credential.requested': AgentfootprintEventEnvelope<'agentfootprint.credential.requested', CredentialRequestedPayload>;
+    'agentfootprint.credential.acquired': AgentfootprintEventEnvelope<'agentfootprint.credential.acquired', CredentialAcquiredPayload>;
+    'agentfootprint.credential.authorization_required': AgentfootprintEventEnvelope<'agentfootprint.credential.authorization_required', CredentialAuthorizationRequiredPayload>;
+    'agentfootprint.credential.failed': AgentfootprintEventEnvelope<'agentfootprint.credential.failed', CredentialFailedPayload>;
+    'agentfootprint.risk.flagged': AgentfootprintEventEnvelope<'agentfootprint.risk.flagged', RiskFlaggedPayload>;
+    'agentfootprint.fallback.triggered': AgentfootprintEventEnvelope<'agentfootprint.fallback.triggered', FallbackTriggeredPayload>;
+    'agentfootprint.cost.tick': AgentfootprintEventEnvelope<'agentfootprint.cost.tick', CostTickPayload>;
+    'agentfootprint.cost.limit_hit': AgentfootprintEventEnvelope<'agentfootprint.cost.limit_hit', CostLimitHitPayload>;
+    'agentfootprint.eval.score': AgentfootprintEventEnvelope<'agentfootprint.eval.score', EvalScorePayload>;
+    'agentfootprint.eval.threshold_crossed': AgentfootprintEventEnvelope<'agentfootprint.eval.threshold_crossed', EvalThresholdCrossedPayload>;
+    'agentfootprint.error.retried': AgentfootprintEventEnvelope<'agentfootprint.error.retried', ErrorRetriedPayload>;
+    'agentfootprint.error.recovered': AgentfootprintEventEnvelope<'agentfootprint.error.recovered', ErrorRecoveredPayload>;
+    'agentfootprint.error.fatal': AgentfootprintEventEnvelope<'agentfootprint.error.fatal', ErrorFatalPayload>;
+    'agentfootprint.reliability.fail_fast': AgentfootprintEventEnvelope<'agentfootprint.reliability.fail_fast', ReliabilityFailFastPayload>;
+    'agentfootprint.reliability.retried': AgentfootprintEventEnvelope<'agentfootprint.reliability.retried', ReliabilityRetriedPayload>;
+    'agentfootprint.reliability.recovered': AgentfootprintEventEnvelope<'agentfootprint.reliability.recovered', ReliabilityRecoveredPayload>;
+    'agentfootprint.pause.request': AgentfootprintEventEnvelope<'agentfootprint.pause.request', PauseRequestPayload>;
+    'agentfootprint.pause.resume': AgentfootprintEventEnvelope<'agentfootprint.pause.resume', PauseResumePayload>;
+    'agentfootprint.embedding.generated': AgentfootprintEventEnvelope<'agentfootprint.embedding.generated', EmbeddingGeneratedPayload>;
+}
+/** Union of every typed event. Consumers use this for exhaustive `switch`. */
+export type AgentfootprintEvent = AgentfootprintEventMap[keyof AgentfootprintEventMap];
+/** Every known event-type string, useful for runtime lookups / lints. */
+export type AgentfootprintEventType = keyof AgentfootprintEventMap;
+/**
+ * Complete list of every registered event type, for lint / runtime validation.
+ * A new event MUST be added here or the exhaustiveness tests fail.
+ */
+export declare const ALL_EVENT_TYPES: readonly AgentfootprintEventType[];

package/dist/esm/events/types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * EventMeta + shared event vocabulary.
+ *
+ * Pattern: Domain-Driven Design value objects (Evans, 2003).
+ * Role:    Shared vocabulary for the typed events in registry.ts.
+ * Emits:   (types only — no runtime behavior here).
+ */
+export type ContextSlot = 'system-prompt' | 'messages' | 'tools';
+/**
+ * The origin / flavor of a context injection.
+ *
+ * BASELINE sources (regular LLM-API flow — NOT context engineering):
+ *   - `user`        → the user's message (current turn or history replay)
+ *   - `tool-result` → tool return for a tool call (current or history)
+ *   - `assistant`   → prior-turn assistant output replayed as history
+ *   - `base`        → static system prompt configured at build time
+ *   - `registry`    → static tool registry configured at build time
+ *
+ * ENGINEERED sources (context engineering flavors — the teaching layer):
+ *   - `rag`          → retrieval-augmented injection
+ *   - `skill`        → skill activation (LLM-guided via read_skill)
+ *   - `memory`       → memory strategy re-injection
+ *   - `instructions` → rule-based behavior guidance
+ *   - `steering`     → always-on policy / persona / format rule
+ *   - `fact`         → developer-supplied data (user profile, env, …)
+ *   - `custom`       → consumer-defined (anything bespoke)
+ *
+ * Adding a new source is NOT a breaking change; removing one IS.
+ */
+export type ContextSource = 'rag' | 'skill' | 'memory' | 'instructions' | 'steering' | 'fact' | 'custom' | 'user' | 'tool-result' | 'assistant' | 'base' | 'registry';
+export type ContextRole = 'system' | 'user' | 'assistant' | 'tool';
+export type ContextRecency = 'latest' | 'earlier';
+export type ContextLifetime = 'iteration' | 'turn' | 'run' | 'persistent';
+export type LLMProviderName = 'anthropic' | 'openai' | 'google' | 'cohere' | 'local' | 'custom' | 'mock' | (string & {});
+export type ToolProtocol = 'native' | 'mcp' | 'http' | 'python-fn';
+export type CompositionKind = 'Sequence' | 'Parallel' | 'Conditional' | 'Loop';
+/**
+ * Metadata attached by the dispatcher to every event. Consumers never
+ * construct this manually — the dispatcher fills it in.
+ */
+export interface EventMeta {
+    /** Wall-clock ms — for external correlation / dashboards. */
+    readonly wallClockMs: number;
+    /** ms since run start — deterministic replay. */
+    readonly runOffsetMs: number;
+    /** footprintjs universal stage key. */
+    readonly runtimeStageId: string;
+    /** Subflow path parsed from runtimeStageId. */
+    readonly subflowPath: readonly string[];
+    /** Composition ancestry — e.g. ['Sequence:pipeline','Agent:ethics']. */
+    readonly compositionPath: readonly string[];
+    /** Turn index (Agent context only). */
+    readonly turnIndex?: number;
+    /** Iteration index (Agent context only). */
+    readonly iterIndex?: number;
+    /** OTEL trace id (when env.traceId is set). */
+    readonly traceId?: string;
+    /** OTEL span id for the current composition boundary. */
+    readonly spanId?: string;
+    /** Domain correlation id — ties retrieval → injection → LLM. */
+    readonly correlationId?: string;
+    /** Run id — demultiplex concurrent runs sharing one dispatcher. */
+    readonly runId: string;
+}
+/** Discriminated-union envelope every event implements. */
+export interface AgentfootprintEventEnvelope<TType extends string, TPayload> {
+    readonly type: TType;
+    readonly payload: TPayload;
+    readonly meta: EventMeta;
+}

package/dist/esm/identity/kinds.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Built-in credential kinds — small strategies implementing the {@link Credential}
+ * protocol. Each is a factory returning `{ kind, ...rawFields, toHeaders() }`.
+ *
+ * The framework + tools only ever call `cred.toHeaders()` (generic — no `kind`
+ * switching); the raw fields are there for the rare non-HTTP case. A custom kind
+ * is any object implementing `Credential` — no library change needed.
+ */
+import type { Credential } from './types.js';
+export interface BearerCredential extends Credential {
+    readonly kind: 'bearer';
+    readonly token: string;
+}
+/** OAuth / bearer token → `Authorization: Bearer <token>`. */
+export declare function bearer(token: string): BearerCredential;
+export interface ApiKeyCredential extends Credential {
+    readonly kind: 'apiKey';
+    readonly key: string;
+    readonly headerName: string;
+}
+/** API key → a single header (default `x-api-key`). */
+export declare function apiKey(key: string, headerName?: string): ApiKeyCredential;
+export interface BasicCredential extends Credential {
+    readonly kind: 'basic';
+    readonly username: string;
+    readonly password: string;
+}
+/** HTTP Basic auth → `Authorization: Basic base64(user:pass)`. */
+export declare function basic(username: string, password: string): BasicCredential;
+export interface HeadersCredential extends Credential {
+    readonly kind: 'headers';
+    readonly headers: Readonly<Record<string, string>>;
+}
+/** The universal escape: arbitrary auth headers. Any scheme reduces to this, so
+ *  a provider with no matching typed kind can always return `headers(...)`. */
+export declare function headers(map: Readonly<Record<string, string>>): HeadersCredential;

package/dist/esm/identity/staticTokens.d.ts

@@ -0,0 +1,28 @@
+/**
+ * staticTokens — a dev/test {@link CredentialProvider} backed by canned credentials.
+ *
+ * No network, no SDK. Use it to develop tools that need credentials without
+ * standing up AgentCore Identity (or any IdP). Production swaps it for
+ * `agentCoreIdentity()` — the tool code never changes.
+ *
+ *   // a plain string is treated as a bearer token (the common case):
+ *   const credentials = staticTokens({ github: 'ghp_dev_xxx' });
+ *   // …or give an explicit kind:
+ *   const credentials = staticTokens({ internal: apiKey('k', 'x-internal-key') });
+ *
+ *   const r = await credentials.getCredential({ service: 'github' });
+ *   if (isCredentialIssued(r)) callGithub({ headers: r.credential.toHeaders() });
+ */
+import type { Credential, CredentialProvider } from './types.js';
+export interface StaticTokensOptions {
+    /** Optional id (defaults to 'static-tokens'). */
+    readonly id?: string;
+    /** Optional fixed expiry (unix seconds) applied to every credential. */
+    readonly expiresAt?: number;
+}
+/**
+ * Build a {@link CredentialProvider} from a `service → credential` map. A plain
+ * string value is treated as a bearer token; a {@link Credential} is used as-is.
+ * Always 2-legged (issues directly); throws if a requested service has none.
+ */
+export declare function staticTokens(creds: Readonly<Record<string, string | Credential>>, options?: StaticTokensOptions): CredentialProvider;

package/dist/esm/identity/types.d.ts

@@ -0,0 +1,113 @@
+/**
+ * agentfootprint/identity — the CredentialProvider port.
+ *
+ * OUTBOUND auth: vend a credential/token so a tool can call a downstream service
+ * (GitHub, Slack, Google…) on behalf of the agent or the end user. This is
+ * DISTINCT from `agentfootprint/security` (authorization — "is this tool
+ * allowed"); identity answers "get me a token to call X".
+ *
+ * Pattern: Port (Hexagonal). Vendors plug in as adapters:
+ *   - `agentCoreIdentity()` — AWS Bedrock AgentCore Identity (token vault + OAuth)
+ *   - `staticTokens()`      — dev/test (canned tokens, no network)
+ *
+ * Two flows, mirroring OAuth (and AgentCore's `M2M` vs `USER_FEDERATION`):
+ *   - `mode: 'machine'` (2-legged) — client-credentials; returns a token directly.
+ *   - `mode: 'user'`    (3-legged) — user-delegated; may need consent. When it
+ *     does, the provider returns `authorization-required` with a URL; the agent
+ *     surfaces it to the human (e.g. via pause/resume) and retries after consent.
+ *     (Most calls skip consent — providers cache refresh tokens.)
+ *
+ * **Security invariant:** a vended token is a SECRET. Callers MUST use it locally
+ * (e.g. as an HTTP header inside a tool's `execute`) and MUST NOT write it to
+ * tracked scope (`setValue`) — tracked writes flow to the commit log, recorders,
+ * and observability exporters, which would leak the token into the trace. Pair
+ * with `RedactionPolicy` for defence in depth.
+ */
+/** What a tool/agent asks for. `service` ↔ the provider's downstream service id. */
+export interface CredentialRequest {
+    /** Downstream service id, e.g. 'github', 'slack', 'google'. */
+    readonly service: string;
+    /** OAuth scopes to request. */
+    readonly scopes?: readonly string[];
+    /** `machine` = 2-legged (M2M); `user` = 3-legged (on behalf of a user). Default `machine`. */
+    readonly mode?: 'machine' | 'user';
+    /** The principal/tenant the token is for (the agent + end-user identity). */
+    readonly identity?: {
+        readonly principal?: string;
+        readonly tenant?: string;
+    };
+    /** Force a fresh authorization, bypassing any cached/refresh token. */
+    readonly forceReauth?: boolean;
+}
+/**
+ * A credential, ready to apply to a downstream request. It carries its `kind`
+ * (so you can read the raw value when you must) AND a **universal applicator**
+ * `toHeaders()` — the way to USE it without switching on `kind`. Built-in kinds
+ * (`bearer`/`apiKey`/`basic`/`headers`) live in `./kinds`; a custom kind is any
+ * object implementing this protocol — so new credential types plug in with no
+ * library change.
+ *
+ * **SECRET.** Use it locally (e.g. `headers: cred.toHeaders()`) inside a tool;
+ * never write it to tracked scope. It is a live object (carries `toHeaders`),
+ * so it is intentionally NOT serializable — credentials are used immediately
+ * and never persisted/traced.
+ */
+export interface Credential {
+    /** Discriminator: 'bearer' | 'apiKey' | 'basic' | 'headers' | <your kind>. */
+    readonly kind: string;
+    /** The auth header(s) to add to a downstream HTTP request. Universal across kinds. */
+    toHeaders(): Record<string, string>;
+}
+/** The provider issued a credential (the 2-legged / refreshed-3-legged happy path). */
+export interface CredentialIssued {
+    readonly status: 'issued';
+    readonly credential: Credential;
+    /** Unix seconds when it expires, if known. */
+    readonly expiresAt?: number;
+}
+/** 3-legged consent is required: surface `authorizationUrl` to the user, then
+ *  retry `getCredential` after they authorize (`sessionId` correlates the flow). */
+export interface CredentialAuthorizationRequired {
+    readonly status: 'authorization-required';
+    readonly authorizationUrl: string;
+    readonly sessionId: string;
+}
+export type CredentialResult = CredentialIssued | CredentialAuthorizationRequired;
+/**
+ * The port. An adapter implements this against a specific identity backend.
+ *
+ * **Security contract for implementers:** a thrown error's `message` is surfaced
+ * to the LLM (as the tool result) AND emitted on `agentfootprint.credential.failed`
+ * — so a provider MUST NOT include the secret/token (or an `Authorization` header)
+ * in thrown error messages. (Some OAuth/HTTP SDKs echo request details into 401/403
+ * text — scrub those before throwing.) Defence in depth: consumers can also apply
+ * footprintjs `RedactionPolicy.emitPatterns: [/credential\.failed/]`.
+ */
+export interface CredentialProvider {
+    /** Stable id (for logging / "which provider vended this"). */
+    readonly id: string;
+    getCredential(req: CredentialRequest): Promise<CredentialResult>;
+}
+/** Narrow a {@link CredentialResult} to the issued-credential branch. */
+export declare function isCredentialIssued(r: CredentialResult): r is CredentialIssued;
+/**
+ * What a tool DECLARES it needs (declare-and-push). The framework resolves this
+ * with the attached provider BEFORE invoking the tool, and injects the result as
+ * `ctx.credential`. `credential` is the service id the provider understands.
+ */
+export interface CredentialNeed {
+    readonly credential: string;
+    readonly scopes?: readonly string[];
+    /** `machine` = 2-legged/M2M; `user` = 3-legged on-behalf-of-user (consent).
+     *  **Omitted → `machine`** — declare `mode: 'user'` explicitly for delegated
+     *  access, or you'll silently get a machine token. */
+    readonly mode?: 'machine' | 'user';
+}
+/**
+ * A fail-closed {@link CredentialProvider} used when none is attached. Every call
+ * throws loudly — so `ctx.credentials` is never `undefined` (no silent
+ * optional-chaining bypass), and a tool that needs a credential without one
+ * configured fails LOUD, not open. Use `ctx.hasCredentials` to branch when a tool
+ * intentionally supports a no-credential (degraded) mode.
+ */
+export declare function unconfiguredCredentialProvider(): CredentialProvider;

package/dist/esm/identity/withCredentialRetry.d.ts

@@ -0,0 +1,64 @@
+/**
+ * withCredentialRetry — CredentialProvider decorator that retries transient
+ * `getCredential` failures with exponential backoff.
+ *
+ * Pattern: Decorator (GoF) — the credential twin of `withRetry` (resilience)
+ *          for LLM providers. SAME option vocabulary (`maxAttempts` /
+ *          `initialDelayMs` / `backoffFactor` / `maxDelayMs` / `shouldRetry` /
+ *          `onRetry`) and the SAME default transience policy (the shared
+ *          `defaultShouldRetry`: skip AbortError + 4xx except 429; retry 5xx,
+ *          network errors, unknown shapes). AgentCore's documented transient
+ *          errors (`InternalServerException` 500, `ThrottlingException` 429)
+ *          retry out of the box.
+ *
+ * Why a decorator and not a reliability rule: the rules-based reliability
+ * subsystem (`Agent.create(...).reliability({...})`) is LLM-call-scoped —
+ * `ReliabilityScope` carries `request: LLMRequest` and the gate chart loops
+ * around the CallLLM stage with provider failover. Credential resolution
+ * happens at a different boundary (the tool-dispatch loop, declare-and-push);
+ * promoting it to a chart-level gate is the deferred `sf-credential` node.
+ * Until that exists, retry is a TRANSPORT property of the credential provider
+ * — exactly like `withRetry` is for LLM transports.
+ *
+ * Semantics:
+ *   • Only THROWN errors retry. Both result branches return immediately:
+ *     `issued` is success; `authorization-required` is a HUMAN flow (3LO
+ *     consent), not a transient fault — retrying it would hammer the IdP
+ *     without the user having authorized anything.
+ *   • After retries exhaust, the LAST error is rethrown — the call site
+ *     behaves byte-identically to an unwrapped provider (fail-closed:
+ *     `agentfootprint.credential.failed` emit + error tool result; the tool
+ *     does NOT run).
+ *   • Visibility: the agent trace brackets the whole retried resolution with
+ *     `credential.requested` → `credential.acquired` / `credential.failed`.
+ *     Per-attempt visibility is consumer-wired via `onRetry` — the established
+ *     decorator contract (same as `withRetry`; the `agentfootprint.error.*`
+ *     event family is reserved for these decorators, see events/payloads.ts).
+ *     No new event types.
+ *
+ * @example
+ *   import { agentCoreIdentity, withCredentialRetry } from 'agentfootprint/identity';
+ *
+ *   const credentials = withCredentialRetry(agentCoreIdentity({ region: 'us-east-1' }), {
+ *     maxAttempts: 3,
+ *     onRetry: (err, attempt, ms) => console.warn(`credential retry ${attempt} in ${ms}ms`, err),
+ *   });
+ *   const agent = Agent.create({ provider, model, credentials }).tools([...]).build();
+ */
+import { type WithRetryOptions } from '../resilience/withRetry.js';
+import type { CredentialProvider } from './types.js';
+/**
+ * Same vocabulary as the LLM-provider `withRetry` — one retry language across
+ * both decorators. `shouldRetry` sees only THROWN errors (never an
+ * `authorization-required` result, which returns immediately).
+ */
+export type WithCredentialRetryOptions = WithRetryOptions;
+/**
+ * Wrap a {@link CredentialProvider} so transient `getCredential` failures
+ * retry with exponential backoff before failing closed.
+ *
+ * Defaults mirror `withRetry`: 3 attempts total, 200ms → 400ms → 800ms
+ * backoff capped at 10s, retry on 5xx/429/network/unknown, never on
+ * AbortError or other 4xx.
+ */
+export declare function withCredentialRetry(provider: CredentialProvider, options?: WithCredentialRetryOptions): CredentialProvider;

package/dist/esm/identity.d.ts

@@ -0,0 +1,31 @@
+/**
+ * agentfootprint/identity — outbound credential vending for agent tools.
+ *
+ * The {@link CredentialProvider} port + adapters. A tool calls
+ * `provider.getCredential({ service })` to get a token for a downstream service;
+ * `agentCoreIdentity()` backs it with AWS Bedrock AgentCore Identity, or
+ * `staticTokens()` for dev/test.
+ *
+ * SECURITY: a vended token is a secret — use it locally inside a tool's
+ * `execute` (e.g. an HTTP header); never write it to tracked scope. See
+ * `./identity/types` for the full invariant.
+ *
+ * @example
+ * ```ts
+ * import { agentCoreIdentity } from 'agentfootprint/identity';
+ *
+ * const credentials = agentCoreIdentity({ region: 'us-east-1' });
+ * const r = await credentials.getCredential({ service: 'github', mode: 'user', scopes: ['repo'] });
+ * if (r.status === 'authorization-required') {
+ *   // surface r.authorizationUrl to the user (e.g. pause the run), then retry.
+ * } else {
+ *   callGitHub({ headers: r.credential.toHeaders() }); // universal applicator
+ * }
+ * ```
+ */
+export type { Credential, CredentialProvider, CredentialRequest, CredentialResult, CredentialIssued, CredentialAuthorizationRequired, CredentialNeed, } from './identity/types.js';
+export { isCredentialIssued, unconfiguredCredentialProvider } from './identity/types.js';
+export { bearer, apiKey, basic, headers, type BearerCredential, type ApiKeyCredential, type BasicCredential, type HeadersCredential, } from './identity/kinds.js';
+export { staticTokens, type StaticTokensOptions } from './identity/staticTokens.js';
+export { withCredentialRetry, type WithCredentialRetryOptions, } from './identity/withCredentialRetry.js';
+export { agentCoreIdentity, type AgentCoreIdentityOptions, type AgentCoreIdentityClientLike, type AgentCoreOauthResponse, } from './adapters/identity/agentcore.js';

package/dist/esm/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * agentfootprint — public barrel.
+ *
+ * Pattern: Facade (GoF) over the typed sublayers.
+ * Role:    Single entry point consumers import from.
+ * Emits:   N/A.
+ */
+import './cache/strategies/AnthropicCacheStrategy.js';
+import './cache/strategies/OpenAICacheStrategy.js';
+import './cache/strategies/BedrockCacheStrategy.js';
+export type { CombinedRecorder, ScopeRecorder, FlowRecorder, EmitRecorder, WriteEvent, ReadEvent, CommitEvent, StageEvent, ErrorEvent, FlowStageEvent, FlowNextEvent, FlowDecisionEvent, FlowForkEvent, FlowSelectedEvent, FlowSubflowEvent, FlowSubflowRegisteredEvent, FlowLoopEvent, FlowBreakEvent, FlowErrorEvent, TraversalContext, EmitEvent, RedactionPolicy, RedactionReport, } from 'footprintjs';
+export * from './events/types.js';
+export type * as Payloads from './events/payloads.js';
+export { EVENT_NAMES, ALL_EVENT_TYPES, type AgentfootprintEvent, type AgentfootprintEventMap, type AgentfootprintEventType, } from './events/registry.js';
+export { EventDispatcher, type EventListener, type WildcardListener, type ListenOptions, type Unsubscribe, type DomainWildcard, type AllWildcard, type WildcardSubscription, } from './events/dispatcher.js';
+export * from './adapters/types.js';
+export { INJECTION_KEYS, injectionKeyForSlot, isInjectionKey, type InjectionKey, stageRole, type StageRole, milestoneFor, type Milestone, type MilestoneKind, } from './conventions.js';
+export { COMPOSITION_KEYS, type BudgetPressureRecord, type CompositionKey, type EvictionRecord, type InjectionRecord, type SlotComposition, } from './recorders/core/types.js';
+export { buildEventMeta, parseSubflowPath, type RunContext } from './bridge/eventMeta.js';
+export { contextEngineering, isEngineeredSource, isBaselineSource, ENGINEERED_SOURCES, BASELINE_SOURCES, type ContextEngineeringHandle, type ContextEngineeringUnsubscribe, type ContextInjectedEvent, type ContextInjectedListener, } from './recorders/core/contextEngineering.js';
+export { EmitBridge, type EmitBridgeOptions } from './recorders/core/EmitBridge.js';
+export { typedEmit } from './recorders/core/typedEmit.js';
+export type { EmittedEvent, EnableNamespace, Runner } from './core/runner.js';
+export { RunnerBase, makeRunId } from './core/RunnerBase.js';
+export type { GroupKind, GroupMember, GroupMetadata, GroupTranslator } from './core/translator.js';
+export { pauseHere, askHuman, isPauseRequest, isPaused, type RunnerPauseOutcome, } from './core/pause.js';
+export type { FlowchartHandle, FlowchartOptions, } from './recorders/observability/FlowchartRecorder.js';
+export { defaultCommentaryTemplates, extractAgentName, extractCommentaryVars, renderCommentary, selectCommentaryKey, type CommentaryContext, type CommentaryTemplates, } from './recorders/observability/commentary/commentaryTemplates.js';
+export { defaultStatusTemplates, selectStatus, renderStatusLine, type StatusContext, type StatusState, type StatusKind, type StatusTemplates, } from './recorders/observability/status/statusTemplates.js';
+export { LLMCall, LLMCallBuilder, type LLMCallInput, type LLMCallOptions, type LLMCallOutput, } from './core/LLMCall.js';
+export { buildMessageApiChart, type MessageApiChartDeps, } from './core/agent/buildMessageApiChart.js';
+export { buildAgentMessageApiChart, type AgentMessageApiChartDeps, } from './core/agent/buildAgentMessageApiChart.js';
+export { Agent, AgentBuilder, type AgentInput, type AgentOptions, type AgentOutput, type ObserverDeliveryOptions, } from './core/Agent.js';
+export type { SelfExplainOptions } from './lib/trace-toolpack/selfExplain.js';
+export type { ObserverDrainResult, ObserverStats } from 'footprintjs';
+export type { ToolArgValidationMode } from './core/agent/toolArgsValidation.js';
+export type { ReadSummaryMarker, ReadTrackingMode } from 'footprintjs';
+export { OutputSchemaError, applyOutputSchema, buildDefaultInstruction, type OutputSchemaParser, type OutputSchemaOptions, } from './core/outputSchema.js';
+export { type OutputFallbackOptions, type OutputFallbackFn } from './core/outputFallback.js';
+export { RunCheckpointError, type AgentRunCheckpoint } from './core/runCheckpoint.js';
+export { flowchartAsTool, type FlowchartAsToolOptions, type FlowchartResultMapper, type FlowchartToolSnapshot, } from './core/flowchartAsTool.js';
+export type { Tool, ToolExecutionContext, ToolRegistryEntry, DefineToolOptions, } from './core/tools.js';
+export { defineTool, assertValidToolName, warnIfInvalidToolName } from './core/tools.js';
+export { toolContractCheckup, formatToolContractCheckup, type ToolContractCheckup, type ToolContractProblem, type ToolContractCode, type ServerToolEntry, } from './core/toolContract.js';
+export { Sequence, SequenceBuilder, type SequenceInput, type SequenceOptions, type SequenceOutput, } from './core-flow/Sequence.js';
+export { Parallel, ParallelBuilder, type BranchOutcome, type MergeFn, type MergeOutcomesFn, type MergeWithLLMOptions, type ParallelBranchOptions, type ParallelInput, type ParallelOptions, type ParallelOutput, } from './core-flow/Parallel.js';
+export { Conditional, ConditionalBuilder, type ConditionalInput, type ConditionalOptions, type ConditionalOutput, type Predicate, } from './core-flow/Conditional.js';
+export { Loop, LoopBuilder, type LoopInput, type LoopOptions, type LoopOutput, type UntilGuard, } from './core-flow/Loop.js';
+export { MockProvider, mock, type MockProviderOptions, type MockReply, } from './adapters/llm/MockProvider.js';
+export { browserAnthropic, BrowserAnthropicProvider, type BrowserAnthropicProviderOptions, } from './adapters/llm/BrowserAnthropicProvider.js';
+export { browserOpenai, BrowserOpenAIProvider, type BrowserOpenAIProviderOptions, browserAzureOpenai, BrowserAzureOpenAIProvider, type BrowserAzureOpenAIProviderOptions, } from './adapters/llm/BrowserOpenAIProvider.js';
+export { createProvider, providerFromEnv, type ProviderKind, type CreateProviderOptions, type ProviderFromEnv, } from './adapters/llm/createProvider.js';
+export { toSSE, SSEFormatter, encodeSSE, type ToSSEOptions } from './stream.js';
+export { type Injection, type InjectionTrigger, type InjectionContent, type InjectionContext, type InjectionEvaluation, evaluateInjections, buildInjectionEngineSubflow, projectActiveInjection, type InjectionEngineConfig, type ActiveInjection, defineInstruction, type DefineInstructionOptions, defineRelevanceHint, type RelevanceHintOptions, defineSkill, resolveSurfaceMode, SkillRegistry, type SkillRegistryOptions, buildListSkillsTool, buildReadSkillTool, type SkillToolPair, type DefineSkillOptions, type SurfaceMode, type RefreshPolicy, type AutoActivateMode, defineSteering, type DefineSteeringOptions, defineFact, type DefineFactOptions, defineInjection, type DefineInjectionOptions, type InjectionFlavor, skillGraph, decide, SKILL_GRAPH_METADATA_KEY, type SkillGraph, type SkillGraphBuilder, type SkillRouteOptions, type SkillEntryOptions, type TreeOptions, type SkillEdge, type SkillEdgeKind, type SkillNode, type DecisionNode, type SkillRouting, type SkillRoutingStep, type EntryScore, type EntryScoring, type SkillGraphConfig, type BuildOptions, type GraphCheckMode, type GraphCheckup, type GraphProblem, type GraphProblemCode, keywordScorer, embeddingScorer, rankEntries, type EntryScorer, type EntryScorerInput, type EntryCandidate, checkSkillContract, checkSkillContracts, skillToolNames, } from './lib/injection-engine/index.js';
+export * from './patterns/index.js';
+export { defaultPipeline, ephemeralPipeline, factPipeline, narrativePipeline, semanticPipeline, autoPipeline, } from './memory/pipeline/index.js';
+export { heuristicExtractor, llmExtractor, } from './memory/beats/index.js';
+export { patternFactExtractor, llmFactExtractor, } from './memory/facts/index.js';
+export { defineMemory, MEMORY_TYPES, MEMORY_STRATEGIES, MEMORY_TIMING, SNAPSHOT_PROJECTIONS, type MemoryType, type MemoryStrategyKind, type MemoryTiming, type SnapshotProjection, type Strategy, type MemoryDefinition, type DefineMemoryOptions, InMemoryStore, mockEmbedder, identityNamespace, type MemoryIdentity, type Embedder, } from './memory/index.js';
+export { defineRAG, type DefineRAGOptions, indexDocuments, type IndexDocumentsOptions, type RagDocument, } from './lib/rag/index.js';
+export { mcpClient, mockMcpClient, type McpClient, type McpClientOptions, type McpHttpTransport, type McpStdioTransport, type McpTransport, type McpSdkClient, type MockMcpClientOptions, type MockMcpTool, } from './lib/mcp/index.js';
+export { staticTools, gatedTools, skillScopedTools, type ToolProvider, type ToolDispatchContext, type ToolGatePredicate, } from './tool-providers/index.js';
+export { PermissionPolicy, PolicyHaltError, type PolicyHaltContext, type RoleAllowlist, type PermissionPolicyOptions, } from './security/index.js';
+export { defaultCommentaryMessages, defaultThinkingMessages, composeMessages, validateMessages, type MessageCatalog, } from './locales/index.js';

package/dist/esm/index.js

@@ -136,6 +136,8 @@ defineInstruction, defineRelevanceHint, defineSkill, resolveSurfaceMode, SkillRe
 defineInjection, 
 // Declarative skill graph (proposal 002)
 skillGraph, decide, SKILL_GRAPH_METADATA_KEY, 
+// Pluggable entry-relevance scorer strategy + built-ins (keyword / embedding)
+keywordScorer, embeddingScorer, rankEntries, 
 // Proposal 009 Tier 1 — skill-body ↔ tool-contract consistency check
 checkSkillContract, checkSkillContracts, skillToolNames, } from './lib/injection-engine/index.js';
 // Patterns — factory functions composing primitives + core-flow into