agentfootprint 6.44.0 → 6.45.0

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

@@ -0,0 +1,761 @@
+/**
+ * Event payload types — the 45 typed event payloads across 13 domains.
+ *
+ * Pattern: Discriminated Union (Gang of Four inspired, TS-native).
+ * Role:    Contract layer of Event-Driven Hexagonal Architecture.
+ * Emits:   (types only).
+ */
+import type { CompositionKind, ContextLifetime, ContextRecency, ContextRole, ContextSlot, ContextSource, LLMProviderName, ToolProtocol } from './types.js';
+import type { ThinkingBlock } from '../thinking/types.js';
+export interface CompositionEnterPayload {
+    readonly kind: CompositionKind;
+    readonly id: string;
+    readonly name: string;
+    readonly childCount: number;
+}
+export interface CompositionExitPayload {
+    readonly kind: CompositionKind;
+    readonly id: string;
+    /** Display name supplied at composition build time (e.g., the
+     *  `Sequence.create({ name: 'IntakePipeline' })` arg). Mirrors the
+     *  `name` field on `CompositionEnterPayload` so consumers narrating
+     *  the exit moment can reference the same human-readable identity
+     *  used at entry — no name-cache required across the start/stop
+     *  pair. Optional for back-compat with pre-v2.14.5 emitters. */
+    readonly name?: string;
+    readonly status: 'ok' | 'err' | 'break' | 'budget_exhausted';
+    readonly durationMs: number;
+}
+export interface ParallelForkStartPayload {
+    readonly parentId: string;
+    readonly branches: readonly {
+        id: string;
+        name: string;
+    }[];
+}
+export interface ParallelBranchCompletePayload {
+    readonly parentId: string;
+    readonly branchId: string;
+    readonly status: 'ok' | 'err';
+    readonly durationMs: number;
+}
+export interface ParallelMergeEndPayload {
+    readonly parentId: string;
+    /**
+     * Which merge strategy ran. `'fn'` = `mergeWithFn` (strict, plain
+     * results map). `'llm'` = `mergeWithLLM` (strict, LLM synthesis).
+     * `'outcomes-fn'` = `mergeOutcomesWithFn` (tolerant, full
+     * `BranchOutcome` map). Distinct values so consumers can render
+     * tolerant vs strict merges differently in dashboards.
+     */
+    readonly strategy: 'llm' | 'fn' | 'outcomes-fn';
+    readonly resultSummary: string;
+    /** Number of branches whose result FED the merge — i.e., succeeded
+     *  (or, in tolerant mode, those the merge fn actually consumed as
+     *  `{ok: true}`). Failing branches are counted in `totalBranchCount
+     *  - mergedBranchCount`. */
+    readonly mergedBranchCount: number;
+    /** Total number of branches declared on the Parallel — equals
+     *  `mergedBranchCount` on all-success runs, larger on partial. */
+    readonly totalBranchCount: number;
+}
+export interface ConditionalRouteDecidedPayload {
+    readonly conditionalId: string;
+    readonly chosen: string;
+    readonly rationale?: string;
+    readonly evidence?: unknown;
+}
+export interface LoopIterationStartPayload {
+    readonly loopId: string;
+    readonly iteration: number;
+}
+export interface LoopIterationExitPayload {
+    readonly loopId: string;
+    readonly iteration: number;
+    readonly reason: 'budget' | 'guard_false' | 'break' | 'body_complete';
+}
+export interface AgentTurnStartPayload {
+    readonly turnIndex: number;
+    readonly userPrompt: string;
+}
+export interface AgentTurnEndPayload {
+    readonly turnIndex: number;
+    readonly finalContent: string;
+    readonly totalInputTokens: number;
+    readonly totalOutputTokens: number;
+    readonly iterationCount: number;
+    readonly durationMs: number;
+}
+export interface AgentIterationStartPayload {
+    readonly turnIndex: number;
+    readonly iterIndex: number;
+}
+export interface AgentIterationEndPayload {
+    readonly turnIndex: number;
+    readonly iterIndex: number;
+    readonly toolCallCount: number;
+    /** Conversation history (LLM messages) at the END of this
+     *  iteration. Captured by `agent.run()` for fault-tolerant
+     *  resume — `RunCheckpointError.checkpoint` snapshots this so
+     *  `agent.resumeOnError(...)` can replay from the last good
+     *  iteration. Optional for back-compat with v2.x recorders that
+     *  subscribed without expecting this field. */
+    readonly history?: ReadonlyArray<unknown>;
+}
+export interface AgentRouteDecidedPayload {
+    readonly turnIndex: number;
+    readonly iterIndex: number;
+    readonly chosen: 'tool-calls' | 'final';
+    readonly rationale?: string;
+}
+export interface AgentHandoffPayload {
+    readonly fromAgentId: string;
+    readonly toAgentId: string;
+    readonly reason?: string;
+    readonly viaProtocol?: 'native' | 'mcp' | 'http';
+}
+export interface LLMStartPayload {
+    readonly iteration: number;
+    readonly provider: LLMProviderName;
+    readonly model: string;
+    readonly systemPromptChars: number;
+    readonly messagesCount: number;
+    readonly toolsCount: number;
+    /**
+     * The tool CATALOG the model saw for this call — what was at its disposal when
+     * it chose (the menu behind its tool-selection reasoning). One `{ name,
+     * description }` per tool sent to the provider, in request order. Absent when
+     * the call had no tools. The structured "what the model saw" payload: pair it
+     * with the iteration's reasoning to debug WHY a tool was (or wasn't) picked.
+     * Names + descriptions only — full input schemas live in the snapshot.
+     */
+    readonly tools?: readonly {
+        readonly name: string;
+        readonly description?: string;
+    }[];
+    readonly estimatedPromptTokens?: number;
+    readonly temperature?: number;
+    readonly providerRequestRef?: string;
+}
+export interface LLMEndPayload {
+    readonly iteration: number;
+    readonly content: string;
+    readonly toolCallCount: number;
+    readonly usage: {
+        readonly input: number;
+        readonly output: number;
+        readonly cacheRead?: number;
+        readonly cacheWrite?: number;
+    };
+    readonly stopReason: string;
+    readonly durationMs: number;
+    readonly providerResponseRef?: string;
+}
+export interface LLMTokenPayload {
+    readonly iteration: number;
+    readonly tokenIndex: number;
+    readonly content: string;
+}
+export interface ToolStartPayload {
+    readonly toolName: string;
+    readonly toolCallId: string;
+    readonly args: Readonly<Record<string, unknown>>;
+    readonly parallelCount?: number;
+    readonly protocol?: ToolProtocol;
+}
+export interface ToolEndPayload {
+    readonly toolCallId: string;
+    readonly result: unknown;
+    readonly error?: boolean;
+    readonly durationMs: number;
+}
+export interface ContextInjectedPayload {
+    readonly contentSummary: string;
+    readonly contentHash: string;
+    readonly rawContent?: string;
+    readonly slot: ContextSlot;
+    readonly asRole?: ContextRole;
+    readonly asRecency?: ContextRecency;
+    readonly position?: number;
+    readonly sectionTag?: string;
+    readonly source: ContextSource;
+    readonly sourceId?: string;
+    readonly upstreamRef?: string;
+    readonly reason: string;
+    readonly retrievalScore?: number;
+    readonly rankPosition?: number;
+    readonly threshold?: number;
+    readonly budgetSpent?: {
+        readonly tokens: number;
+        readonly fractionOfCap: number;
+    };
+    readonly expiresAfter?: ContextLifetime;
+}
+export interface ContextEvictedPayload {
+    readonly slot: ContextSlot;
+    readonly contentHash: string;
+    readonly reason: 'budget' | 'stale' | 'low_score' | 'policy' | 'user_revoked';
+    readonly survivalMs: number;
+}
+export interface ContextSlotComposedPayload {
+    readonly slot: ContextSlot;
+    readonly iteration: number;
+    readonly budget: {
+        readonly cap: number;
+        readonly used: number;
+        readonly headroomChars: number;
+    };
+    readonly sourceBreakdown: Readonly<Partial<Record<ContextSource, {
+        readonly chars: number;
+        readonly count: number;
+    }>>>;
+    readonly orderingStrategy?: string;
+    readonly droppedCount: number;
+    readonly droppedSummaries: readonly string[];
+}
+export interface ContextBudgetPressurePayload {
+    readonly slot: ContextSlot;
+    readonly capTokens: number;
+    readonly projectedTokens: number;
+    readonly overflowBy: number;
+    readonly planAction: 'evict' | 'summarize' | 'abort';
+}
+/**
+ * Fired once per iteration by the Injection Engine after it evaluates every
+ * Injection's trigger — BEFORE the Context fork routes the survivors into the
+ * three slots. This is the "what was considered, what won, what was skipped
+ * and why" signal; `context.slot_composed` is its downstream counterpart
+ * ("what actually landed in each slot"). Pure observability — no flow stage
+ * reads it.
+ */
+export interface ContextEvaluatedPayload {
+    readonly iteration: number;
+    /** Number of injections active this iteration. */
+    readonly activeCount: number;
+    /** Number skipped (predicate false counts as neither — only errors/unknown land here). */
+    readonly skippedCount: number;
+    /** Total injections evaluated (the full declared list). */
+    readonly evaluatedTotal: number;
+    /** Ids of the active injections, in evaluation order. */
+    readonly activeIds: readonly string[];
+    /** Why each skipped injection was skipped (errors / unknown trigger kinds). */
+    readonly skippedDetails: readonly {
+        readonly id: string;
+        readonly reason: 'predicate-threw' | 'unknown-trigger-kind';
+        readonly error?: string;
+    }[];
+    /** Count of active injections by trigger kind (always / rule / on-tool-return / llm-activated). */
+    readonly triggerKindCounts: Readonly<Record<string, number>>;
+    /**
+     * The Skill CATALOG the LLM was offered this turn — every registered Skill's
+     * `id` + `description` (the same text that lands in the `read_skill` tool
+     * description). Lets observers pair "what was offered" against "what the LLM
+     * chose" (`read_skill` → `activatedInjectionIds`) when debugging a missed or
+     * wrong activation. Empty when no Skills are registered. Static across turns.
+     */
+    readonly skillCatalog: readonly {
+        readonly id: string;
+        readonly description: string;
+    }[];
+    /**
+     * Routing PROVENANCE for the active injections that came from a `skillGraph()`
+     * — *why* each was reached. One entry per active skill-graph injection (a
+     * decision-tree leaf, a flat entry, or a route edge); absent when no active
+     * injection carries skill-graph metadata. The structured counterpart to the
+     * `context.routed` commentary line — lets the lens show the decision path, the
+     * matched predicate, and the tools a route unlocked. Structural shape (mirrors
+     * `SkillRouting` from the injection engine; events stay decoupled from it).
+     */
+    readonly routing?: readonly {
+        readonly injectionId: string;
+        readonly flavor: string;
+        /** `'tree' | 'entry' | 'route' | 'model'`. */
+        readonly via: string;
+        /** Decision path (tree only): predicates root→leaf + branch taken. */
+        readonly path?: readonly {
+            readonly label: string;
+            readonly branch: string;
+        }[];
+        /** Entry/route edge caption. */
+        readonly label?: string;
+        /** Source skill id (route only). */
+        readonly from?: string;
+        /** Compiled trigger kind for a route. */
+        readonly triggerKind?: string;
+        /** Tool names this injection unlocked. */
+        readonly tools?: readonly string[];
+    }[];
+}
+export interface ErrorFatalPayload {
+    readonly error: string;
+    readonly stage: string;
+    readonly scope: string;
+}
+export interface PauseRequestPayload {
+    readonly reason: string;
+    readonly questionPayload: Readonly<Record<string, unknown>>;
+}
+export interface PauseResumePayload {
+    readonly resumeInput: Readonly<Record<string, unknown>>;
+    readonly pausedDurationMs: number;
+}
+export interface MemoryStrategyAppliedPayload {
+    readonly strategyId: string;
+    readonly strategyKind: 'sliding-window' | 'summarizing' | 'semantic' | 'fact-extraction' | 'hybrid';
+    readonly reason: string;
+    readonly scoreEvidence?: Readonly<Record<string, unknown>>;
+    readonly inputMemoryCount: number;
+    readonly outputMemoryCount: number;
+    readonly droppedIds: readonly string[];
+    readonly addedIds: readonly string[];
+}
+export interface MemoryAttachedPayload {
+    readonly memoryId: string;
+    readonly contentSummary: string;
+    readonly score?: number;
+    readonly rank?: number;
+    readonly source: 'store' | 'auto-extract' | 'manual';
+    readonly retriever?: 'pinecone' | 'weaviate' | 'qdrant' | 'chroma' | 'custom';
+}
+export interface MemoryDetachedPayload {
+    readonly memoryId: string;
+    readonly reason: 'stale' | 'budget' | 'score_low' | 'policy';
+}
+export interface MemoryWrittenPayload {
+    readonly memoryId: string;
+    readonly contentSummary: string;
+    readonly source: 'auto' | 'manual';
+    readonly actor?: string;
+}
+export interface ToolsOfferedPayload {
+    readonly availableIds: readonly string[];
+    readonly withheldIds: readonly string[];
+    readonly withheldReasons: Readonly<Record<string, 'permission' | 'skill_inactive' | 'gated' | 'cost_guard'>>;
+    readonly reason: string;
+}
+export interface ToolsActivatedPayload {
+    readonly toolId: string;
+    readonly reason: 'skill_activated' | 'autoActivate' | 'permission_granted';
+    readonly source?: string;
+}
+export interface ToolsDeactivatedPayload {
+    readonly toolId: string;
+    readonly reason: 'skill_deactivated' | 'permission_revoked';
+}
+/**
+ * Emitted at the start of a `ToolProvider.list(ctx)` call inside the
+ * Discover stage. Pairs with `tools.discovery_completed` (success) or
+ * `tools.discovery_failed` (error). Use the pair to measure async-
+ * provider latency per iteration without joining stages by hand.
+ */
+export interface ToolsDiscoveryStartedPayload {
+    readonly providerId: string | undefined;
+    readonly iteration: number;
+}
+/**
+ * Emitted when `ToolProvider.list(ctx)` resolves successfully. The
+ * `durationMs` is the wall-clock between `tools.discovery_started` and
+ * resolution; `toolCount` is the size of the returned tool list. For
+ * sync providers `durationMs` is ~0; for async hub-backed providers
+ * this is your observability hook for catalog-fetch latency.
+ */
+export interface ToolsDiscoveryCompletedPayload {
+    readonly providerId: string | undefined;
+    readonly iteration: number;
+    readonly durationMs: number;
+    readonly toolCount: number;
+}
+/**
+ * Emitted when a custom `ToolProvider.list(ctx)` throws or rejects.
+ * The iteration is aborted; a configured `reliability` rule decides
+ * whether to retry, fall back, or fail-fast. `providerId` lets
+ * consumers route alerts to the right hub adapter (rube / mcp /
+ * custom-discovery). `durationMs` measures how long the failed call
+ * spent before throwing, so timeouts vs immediate rejections are
+ * distinguishable.
+ */
+export interface ToolsDiscoveryFailedPayload {
+    readonly providerId: string | undefined;
+    readonly error: string;
+    readonly errorName: string;
+    readonly iteration: number;
+    readonly durationMs: number;
+}
+/**
+ * Emitted when LLM-produced tool args fail validation against the tool's
+ * declared `inputSchema` (backlog #9). Fires for BOTH modes that validate:
+ * `enforced: true` means the call was rejected before dispatch and the
+ * model received a structured retry message as the tool result;
+ * `enforced: false` ('warn' mode) means the tool executed anyway.
+ * `issues` name paths, expectations, and received TYPES — never the
+ * supplied values (they can carry PII / injection payloads).
+ */
+export interface ValidationArgsInvalidPayload {
+    readonly toolName: string;
+    readonly toolCallId: string;
+    readonly iteration: number;
+    readonly issues: ReadonlyArray<{
+        readonly path: string;
+        readonly expected: string;
+        readonly got: string;
+    }>;
+    readonly enforced: boolean;
+}
+export interface SkillActivatedPayload {
+    readonly skillId: string;
+    readonly reason: 'autoActivate' | 'read_skill_result' | 'manual';
+    readonly injectedTools?: readonly string[];
+    readonly injectedSystemPromptChars?: number;
+}
+export interface SkillDeactivatedPayload {
+    readonly skillId: string;
+    readonly reason: string;
+}
+/**
+ * Fired by the skill-graph read_skill GATE when the model tries to `read_skill`
+ * a skill that is NOT reachable from the current cursor. The jump is rejected
+ * (cursor/activations unchanged); the model gets a synthetic re-prompt naming
+ * `allowed`. Powers the lens / Why-panel "it tried to leave the graph here".
+ */
+export interface SkillRejectedPayload {
+    /** The skill id the model requested via `read_skill`. */
+    readonly requestedId: string;
+    /** The cursor it was at (undefined = cold start, before any entry resolved). */
+    readonly currentSkillId?: string;
+    /** The reachable set it was bounded to (what the re-prompt offered). */
+    readonly allowed: readonly string[];
+    /** The ReAct iteration the rejection fired on. */
+    readonly iteration: number;
+}
+export interface PermissionCheckPayload {
+    readonly capability: 'tool_call' | 'memory_read' | 'memory_write' | 'external_net' | 'user_data';
+    readonly actor: string;
+    readonly target?: string;
+    readonly result: 'allow' | 'deny' | 'halt' | 'gate_open';
+    readonly policyEngine?: 'opa' | 'cerbos' | 'custom';
+    readonly policyRuleId?: string;
+    readonly rationale?: string;
+    /** v2.12 — telemetry tag carried through from PermissionDecision.reason. */
+    readonly reason?: string;
+}
+export interface PermissionGateOpenedPayload {
+    readonly gateId: string;
+    readonly openedBy: string;
+    readonly expiresAt?: number;
+}
+/** A tool's declared credential is being resolved before invocation. */
+export interface CredentialRequestedPayload {
+    readonly service: string;
+    readonly mode?: 'machine' | 'user';
+}
+/** A credential was issued. Carries the `kind` only — NEVER the token/secret. */
+export interface CredentialAcquiredPayload {
+    readonly service: string;
+    readonly kind: string;
+    readonly expiresAt?: number;
+}
+/** 3-legged consent is required (the tool is not run until the user authorizes).
+ *  Carries `sessionId` for correlation, NOT the authorization URL. */
+export interface CredentialAuthorizationRequiredPayload {
+    readonly service: string;
+    readonly sessionId: string;
+}
+/** Credential resolution failed (the tool is not run). Carries the reason only. */
+export interface CredentialFailedPayload {
+    readonly service: string;
+    readonly reason: string;
+}
+export interface PermissionGateClosedPayload {
+    readonly gateId: string;
+    readonly reason: string;
+}
+/**
+ * Emitted (v2.12) when a `PermissionChecker.check()` returns
+ * `{ result: 'halt', ... }`. Pairs with the typed `PolicyHaltError`
+ * thrown by `Agent.run()` — the event is the OBSERVABILITY signal,
+ * the error is the RUNTIME signal. Both carry the same `reason` for
+ * routing (e.g. `'security:exfiltration'` → PagerDuty).
+ *
+ * Fires AFTER the synthetic tool_result has been written to scope.history
+ * but BEFORE the run terminates, so observability adapters see the
+ * halt while the conversation history is consistent for downstream
+ * audit/replay.
+ */
+export interface PermissionHaltPayload {
+    readonly checkerId?: string;
+    readonly target: string;
+    readonly reason: string;
+    readonly tellLLM?: string;
+    readonly iteration: number;
+    readonly sequenceLength: number;
+}
+export interface RiskFlaggedPayload {
+    readonly severity: 'low' | 'medium' | 'high' | 'critical';
+    readonly category: 'pii' | 'prompt_injection' | 'runaway_loop' | 'cost_overrun' | 'hallucination_flag';
+    readonly detector: 'nemo_guardrails' | 'llama_guard' | 'custom' | 'heuristic';
+    readonly evidence: Readonly<Record<string, unknown>>;
+    readonly action: 'warn' | 'redact' | 'abort';
+}
+export interface FallbackTriggeredPayload {
+    readonly kind: 'provider' | 'tool' | 'skill';
+    readonly primary: string;
+    readonly fallback: string;
+    readonly reason: string;
+}
+export interface CostTickPayload {
+    readonly scope: 'iteration' | 'turn' | 'run';
+    readonly tokensInput: number;
+    readonly tokensOutput: number;
+    readonly estimatedUsd: number;
+    readonly cumulative: {
+        readonly tokensInput: number;
+        readonly tokensOutput: number;
+        readonly estimatedUsd: number;
+    };
+}
+export interface CostLimitHitPayload {
+    readonly kind: 'max_tokens' | 'max_cost' | 'max_iterations' | 'max_wallclock';
+    readonly limit: number;
+    readonly actual: number;
+    readonly action: 'abort' | 'warn' | 'degrade';
+}
+export interface EvalScorePayload {
+    readonly metricId: string;
+    readonly value: number;
+    readonly threshold?: number;
+    readonly target: 'iteration' | 'turn' | 'run' | 'toolCall';
+    readonly targetRef: string;
+    readonly evaluator?: 'llm' | 'fn' | 'heuristic';
+    readonly evidence?: Readonly<Record<string, unknown>>;
+}
+export interface EvalThresholdCrossedPayload {
+    readonly metricId: string;
+    readonly direction: 'above' | 'below';
+    readonly value: number;
+    readonly threshold: number;
+    readonly actionTaken?: string;
+}
+/**
+ * Emitted (v2.13) when the agent's final answer fails the agent's
+ * configured `outputSchema` (the parser passed to
+ * `Agent.create({...}).outputSchema(parser)`).
+ *
+ * Scope: ONLY agent-level final-answer validation. Tool-input validation
+ * (`LLMToolSchema.inputSchema`) is a different concern handled by
+ * provider-side type checks; this event does NOT fire for tool-arg
+ * validation failures.
+ *
+ * Lives in the `agent.*` domain (parallel to `agent.turn_end`) because
+ * final-answer validation is a turn-level concern, not a generic
+ * evaluation metric.
+ *
+ * Pairs with `agentfootprint.error.retried` (when a reliability rule
+ * routes the failure to retry with feedback) or
+ * `agentfootprint.reliability.fail_fast` (when retries are exhausted).
+ *
+ * The event is the OBSERVABILITY signal — it fires on EVERY validation
+ * failure, regardless of whether retries are configured. Use the
+ * `attempt` + `cumulativeRetries` fields to drive operator dashboards
+ * for retry-rate trending (a leading indicator for model drift).
+ *
+ * Fires BEFORE PostDecide rules evaluate, so observability sees the
+ * failure even if a buggy rule routes to fail-fast or swallows it.
+ */
+export interface AgentOutputSchemaValidationFailedPayload {
+    /** Validation error message (from Zod / parser). */
+    readonly message: string;
+    /** Validation stage — JSON parse vs schema validate. Lets dashboards
+     *  distinguish "model emitted prose" (`json-parse`) from "model emitted
+     *  JSON but wrong shape" (`schema-validate`); they trend differently
+     *  under model drift. */
+    readonly stage: 'json-parse' | 'schema-validate';
+    /** Failing field path when the parser exposes one (e.g. `'amount.currency'`).
+     *  Only set when `stage === 'schema-validate'`. */
+    readonly path?: string;
+    /** The raw string output that failed — useful for narrative entries showing
+     *  "what the model actually said" alongside the validation error. */
+    readonly rawOutput?: string;
+    /** 1-indexed attempt counter. `1` for the first failure, `2` for the
+     *  retry that also failed, etc. */
+    readonly attempt: number;
+    /** Total output-schema failures in this gate execution. Same as
+     *  `validationErrorHistory.length`. Distinct from `attempt` because a
+     *  gate can also retry on non-validation errors (5xx, etc.) — this
+     *  counts ONLY the schema-driven failures. */
+    readonly cumulativeRetries: number;
+}
+export interface ErrorRetriedPayload {
+    readonly attempt: number;
+    readonly maxAttempts: number;
+    readonly lastError: string;
+    readonly backoffMs: number;
+    readonly reason: string;
+}
+export interface ErrorRecoveredPayload {
+    readonly attempt: number;
+    readonly totalDurationMs: number;
+}
+/**
+ * Fired when the rules loop (or the reliability gate chart) gives up via
+ * a `fail-fast` decision. Superset shape: `phase`/`kind`/`attempt` are
+ * always present; the remaining fields are populated by whichever site
+ * emits (the loop carries `label`/`providerUsed`/`errorKind`; the gate
+ * chart carries `reason`).
+ */
+export interface ReliabilityFailFastPayload {
+    readonly phase: 'pre-check' | 'post-decide';
+    /** The matched rule's `kind` (machine-readable bucket). */
+    readonly kind: string;
+    /** 1-indexed attempt counter at the point of failure. */
+    readonly attempt: number;
+    /** Human-readable label of the matched rule (loop sites). */
+    readonly label?: string;
+    /** Free-form reason string (gate-chart sites). */
+    readonly reason?: string;
+    /** Provider in use when the loop failed fast. */
+    readonly providerUsed?: string;
+    /** Classification of the failure being failed-fast on. */
+    readonly errorKind?: string;
+    /** Originating error message, when present. */
+    readonly errorMessage?: string;
+}
+/**
+ * Fired each time the rules loop decides to RETRY after a failed attempt
+ * — `action` distinguishes a same-provider retry from a provider failover.
+ */
+export interface ReliabilityRetriedPayload {
+    /** 1-indexed counter of the attempt that just FAILED and is being retried. */
+    readonly attempt: number;
+    /** `retry` = same provider again; `retry-other` = switch provider. */
+    readonly action: 'retry' | 'retry-other';
+    /** Classification of the failure being retried. */
+    readonly errorKind: string;
+    /** Originating error message, when present. */
+    readonly errorMessage?: string;
+    /** Provider that just failed. */
+    readonly fromProvider: string;
+    /** Provider the NEXT attempt will use (equals `fromProvider` for `retry`). */
+    readonly toProvider: string;
+}
+/**
+ * Fired when the rules loop produces a successful response AFTER one or
+ * more failed attempts (self-healed). `recoveredVia` names the mechanism
+ * of the final successful step.
+ */
+export interface ReliabilityRecoveredPayload {
+    /** 1-indexed attempt number that finally succeeded. */
+    readonly attempt: number;
+    /** How recovery happened. */
+    readonly recoveredVia: 'retry' | 'retry-other' | 'fallback';
+    /** How many attempts failed before this success. */
+    readonly priorFailures: number;
+    /** Classification of the LAST failure before recovery. */
+    readonly errorKind: string;
+}
+export interface EmbeddingGeneratedPayload {
+    readonly model: string;
+    readonly provider: 'openai' | 'cohere' | 'voyage' | 'local' | 'custom';
+    readonly inputKind: 'query' | 'document';
+    readonly dimension: number;
+    readonly count: number;
+    readonly durationMs: number;
+    readonly tokensSpent?: number;
+}
+/**
+ * Emitted (v2.14) per provider chunk that carries thinking-content
+ * tokens. Lives in `stream.*` domain — parallel to `stream.token` for
+ * visible-content tokens.
+ *
+ * **Provider behavior:**
+ * - Anthropic: fires for every `content_block_delta` with
+ *   `delta.type === 'thinking_delta'`. May fire 100s of times per turn.
+ * - OpenAI o1/o3: NEVER fires (OpenAI doesn't stream reasoning content
+ *   as of early 2026). Only `thinking_end` fires at response completion.
+ * - Custom providers: fire when `ThinkingHandler.parseChunk()` returns
+ *   a non-empty `thinkingDelta`.
+ *
+ * **Default consumer behavior:** thinking_delta events are emitted but
+ * not surfaced to end users unless a consumer explicitly subscribes to
+ * this event (e.g. for reasoning-as-it-streams UIs).
+ *
+ * **Sensitive data:** `content` is raw model thinking text. Use
+ * `RedactionPolicy.thinkingPatterns` (Phase 3) to scrub before audit-log
+ * adapters fire. Same risk profile as `stream.token`.
+ */
+export interface StreamThinkingDeltaPayload {
+    readonly iteration: number;
+    readonly tokenIndex: number;
+    /** Per-chunk delta text, NOT accumulated. ~10–50 chars typical. */
+    readonly content: string;
+}
+/**
+ * Emitted (v2.14) once per LLM call where thinking blocks were
+ * produced. Pairs with the leading `stream.thinking_delta` events when
+ * streaming, OR fires standalone for non-streaming providers (OpenAI).
+ *
+ * Use this event for live per-iteration UIs (chat-bubble reasoning
+ * pills, retry-rate dashboards, telemetry). The `blocks` field carries
+ * the same content that lands on `LLMMessage.thinkingBlocks` — read it
+ * here for live display instead of post-walking `scope.history` after
+ * the run completes (the framework's "collect during traversal" rule).
+ *
+ * **`tokens` field population:**
+ * - Anthropic: `undefined` currently — Anthropic's `response.usage`
+ *   doesn't break out thinking tokens (bundled in `output_tokens`).
+ *   May change in future Anthropic API revisions.
+ * - OpenAI o1/o3: populated from
+ *   `response.usage.completion_tokens_details.reasoning_tokens`.
+ * - Custom providers: populated when handler computes it during
+ *   `normalize()`.
+ *
+ * **Sensitive data:** the `blocks` field carries reasoning content.
+ * Same risk profile as `stream.token` — wildcard (`*`) recorders
+ * piping to external sinks (Datadog, CloudWatch, OTel) will see this.
+ * Treat thinking content with the same redaction posture you give
+ * visible response tokens. `providerMeta` is already stripped by the
+ * framework before persistence (Phase 6 invariant), so the blocks
+ * here match the audit-log surface bytes-exactly.
+ */
+export interface StreamThinkingEndPayload {
+    readonly iteration: number;
+    readonly blockCount: number;
+    readonly totalChars: number;
+    readonly tokens?: number;
+    /**
+     * v2.14+ — the normalized thinking blocks for this LLM call.
+     *
+     * Same data the framework persists to `LLMMessage.thinkingBlocks`
+     * (post-`providerMeta` strip). Lets live consumers render the
+     * model's chain-of-thought per iteration without scope-walking
+     * after the run.
+     *
+     * Empty / undefined when no thinking content was produced this
+     * call (handler returned `[]`). Non-empty when at least one
+     * thinking or redacted_thinking block landed.
+     */
+    readonly blocks?: readonly ThinkingBlock[];
+}
+/**
+ * Emitted (v2.14) when a `ThinkingHandler.normalize()` call throws.
+ * The framework catches the throw, drops the thinking blocks (they
+ * don't land on `LLMMessage.thinkingBlocks`), and continues the agent
+ * run. Same graceful-failure pattern as v2.11.6
+ * `tools.discovery_failed`.
+ *
+ * Lives in `agent.*` domain (NOT `stream.*`) because parse failure is
+ * a turn-level error concern — recovery happens at the agent loop
+ * level, not at the SDK call level.
+ *
+ * **Anti-pattern (provider authors):** sanitize error messages before
+ * throwing. NEVER include raw unparsed thinking content in the error
+ * — the message ends up in audit logs and can leak reasoning content
+ * the consumer expected to be redacted. Same guidance as
+ * `tools.discovery_failed.error`.
+ */
+export interface AgentThinkingParseFailedPayload {
+    readonly providerName: string;
+    readonly subflowId: string;
+    readonly error: string;
+    readonly errorName: string;
+    readonly iteration: number;
+}