agentfootprint 13.0.0 → 14.0.0

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

@@ -0,0 +1,327 @@
+/**
+ * One use of an `mcpClientPool` in a run — a listing (`at: 'list'`, filed by the
+ * tools slot after `list(ctx)`) or a tool call (`at: 'call'`, filed by the
+ * dispatch loop for that call). Ids, digests, evidence and outcomes only: never
+ * an identity value, a remote session id or handle, a header value, an
+ * argument, a result, a definition or a server's error text. Rides the
+ * `agentfootprint.tools.` prefix: a new domain would need a new bridge and
+ * wildcard (see the `tools.session_*` note above).
+ */
+export interface ToolsMcpClientPayload {
+    /** The pool's name, which `Tool.source` also carries. */
+    readonly server: string;
+    readonly at: 'list' | 'call';
+    /** At `'call'`. */
+    readonly toolCallId?: string;
+    /**
+     * The tool-session digest of the conversation's key (`hashSessionKey`):
+     * enough to join two rows, not enough to name anyone. Absent when the caller
+     * named no identity, so there was no key.
+     */
+    readonly keyHash?: string;
+    /** The pool's own random id for the client touched; absent when none was. */
+    readonly clientId?: string;
+    /** 1 = the key's first client, 2 = its first replacement, … */
+    readonly generation?: number;
+    /** What happened to the conversation's client. */
+    readonly client: 'opened' | 'joined' | 'reused' | 'not-needed' | 'refused' | 'expired' | 'handle-lost';
+    /** Why the key's previous client left, when this use opened its replacement. */
+    readonly previous?: 'idle' | 'evicted' | 'expired' | 'handle-lost' | 'terminated';
+    /** With `'expired'` or `'handle-lost'`: what proves it. */
+    readonly evidence?: 'server-404' | 'transport-forgot-handle';
+    readonly refusal?: 'pool-full' | 'principal-full' | 'ending-full' | 'init-timeout' | 'init-failed' | 'no-identity' | 'incomplete-identity' | 'identity-mismatch' | 'stale-tools' | 'binding-changed' | 'request-unmatched' | 'lease-expired' | 'operations-full' | 'closed';
+    /** Opened or joined: how long the open took. */
+    readonly initMs?: number;
+    /** At `'list'`: a shared entry, or the conversation's own client's list. */
+    readonly definitions?: 'shared' | 'listed';
+    /** When shared: the entry's age. */
+    readonly definitionsAgeMs?: number;
+    /** At `'call'`: the call met a replacement client and was checked against its fresh list. */
+    readonly revalidated?: 'kept' | 'refused';
+}
+/**
+ * What one attempt of an MCP request came to.
+ *
+ *   - `'answered'` — an HTTP response arrived and no retry rule refused it. It
+ *     is delivered as it came, WHATEVER its status: a 503 is `answered` with
+ *     `status: 503`. A response received is not an operation that succeeded,
+ *     so nothing here is called success; read `status`. Nor is it the MCP
+ *     call's answer: it records the HTTP exchange. A `202 Accepted`, or a
+ *     stream that closes before the call's result, is `answered`, and the
+ *     JSON-RPC answer may still never come — the end's `mayHaveRun` says when
+ *     the call failed that way.
+ *   - `'refused'` — a response the retry policy recognises as a refusal
+ *     (`kind`): HTTP 429, or AgentCore Runtime's session-busy reply. It records
+ *     the response the server sent, not proof that nothing ran: a 429 says the
+ *     request was rate-limited, nothing more (RFC 6585 §4). `effect` says what
+ *     is known; `permission` says what allowed asking again.
+ *   - `'failed'` — the request threw before an answer arrived (a dropped
+ *     connection, a DNS failure). The server may have run it, so it is asked
+ *     again only when the app declared that for this tool (`replay`).
+ *   - `'timed-out'` — the call's deadline (`maxElapsedMs`) cut the request
+ *     while it was in flight.
+ *   - `'cut'` — the call was cancelled while the request was in flight: the
+ *     run's or the client's signal, the MCP SDK giving it up (its own timeout),
+ *     or the call settling first. The request WAS sent; the server may already
+ *     have received it and run it. A cut is never a "not run".
+ *
+ * The last three never had a response, so they carry `remote: 'unknown'`.
+ *
+ * Every request the series sent is a row, or is counted in `omitted`: the rows
+ * and `omitted` together are the requests the series sent. A request that was
+ * never sent — the next attempt after a cancelled wait, or anything after a
+ * signal that was already aborted — has no row.
+ */
+export type ToolRequestAttemptOutcome = 'answered' | 'refused' | 'failed' | 'timed-out' | 'cut';
+/**
+ * How an MCP request ended: its last attempt's outcome — or `'cancelled'`, when
+ * the call was cancelled with NO request in flight: while it waited to ask
+ * again, or before its first request. Nothing more was sent; every request
+ * that was sent has its own row and its own outcome.
+ */
+export type ToolRequestOutcome = ToolRequestAttemptOutcome | 'cancelled';
+/**
+ * Whether the server received and ran a request, when that is not known: the
+ * attempt ended without a response (`failed`, `timed-out`, `cut`), so the
+ * request may have reached the server and run there, or not. The library never
+ * records such a request as not run.
+ */
+export type ToolRequestRemote = 'unknown';
+/**
+ * Why the request went on after an attempt, or ended with it.
+ *
+ *   - `'retryable'` — another attempt follows after `waitMs`; `permission`
+ *     says what allowed it. The only reason that is not an end.
+ *   - `'answered'` — answered; the response is delivered.
+ *   - `'exhausted'` — the request has made every attempt it may.
+ *   - `'wait-limit'` — the wait would pass the call's total waiting budget
+ *     (`maxWaitMs`). A stated `Retry-After` is never shortened to fit: the
+ *     refusal is delivered instead.
+ *   - `'no-time-left'` — the wait would pass the call's deadline; or the
+ *     deadline cut a request or a wait.
+ *   - `'not-replayable'` — the request's body cannot be sent twice.
+ *   - `'not-retryable'` — the attempt failed without an answer, and nothing
+ *     permits asking again after that failure: the app declared no repeat of
+ *     this tool on it (`replay`), or it is not a kind the series repeats.
+ *   - `'not-permitted'` — refused with a 429, and the policy in force does not
+ *     permit asking this tool again on it. Under `'app-authorized'`, only the
+ *     app's declaration does: a generic 429 does not prove the server ran
+ *     nothing.
+ *   - `'changes-without-key'` — the app declared this tool as making changes,
+ *     and the call carries no key the server is declared to deduplicate by. It
+ *     is never asked again automatically, under any policy.
+ *   - `'cancelled'` — the caller's signal ended the request.
+ */
+export type ToolRequestReason = 'retryable' | 'answered' | 'exhausted' | 'wait-limit' | 'no-time-left' | 'not-replayable' | 'not-retryable' | 'not-permitted' | 'changes-without-key' | 'cancelled';
+/** The refusals a retry rule recognises: HTTP 429, and AgentCore Runtime's session-busy reply. */
+export type ToolRequestRefusalKind = 'throttle' | 'session-busy';
+/**
+ * What is known about whether an attempt took effect on the server —
+ * footprintjs's effect law (`AttemptEffect`), read for an MCP request:
+ *
+ *   - `'none'` — it ran nothing, and that is established: the request was
+ *     never sent (an `end` whose `attempts` is `0`). No reply establishes it.
+ *     A 429 says the request was rate-limited, and AgentCore's session-busy
+ *     body is matched by its code and words — a server behind the runtime can
+ *     answer with the same error after it ran the call.
+ *   - `'unknown'` — anything sent that did not complete: a 429, a session-busy
+ *     reply, a lost connection or a timeout after the request was sent, a cut,
+ *     a 5xx, a JSON-RPC error, a tool error (one can follow a write that
+ *     succeeded).
+ *   - `'applied'` — the call completed: the server answered it, and not with
+ *     an error. It is never proof that anything was written.
+ */
+export type ToolRequestEffect = 'none' | 'unknown' | 'applied';
+/** The failure kinds the app may declare a tool repeatable on (`replay.tools[name].on`). */
+export type ToolRequestReplayKind = 'throttle' | 'network';
+/**
+ * What allowed the next attempt — present exactly when `reason` is
+ * `'retryable'`. Permission and effect are separate facts: neither is ever
+ * read from the other.
+ *
+ *   - `by: 'declaration'` — the app's entry for this tool names the failure
+ *     kind (`on`).
+ *   - `by: 'adapter'` — the adapter the app chose retries this refusal as its
+ *     own policy: AgentCore Runtime's session-busy reply, which AWS documents
+ *     as a retryable conflict while a session starts or stops. It says what
+ *     it assumes in doing so (`assumes`).
+ *   - `by: 'compatibility'` — the compatibility policy, today's default: it
+ *     repeats a 429 for every tool, and says what it assumes in doing so
+ *     (`assumes`).
+ *
+ * An assumption is a policy, never evidence: the row's `effect` stays
+ * `'unknown'`.
+ */
+export interface ToolRequestPermission {
+    readonly by: 'declaration' | 'adapter' | 'compatibility';
+    /** `declaration` only — the failure kind the app's entry names. */
+    readonly on?: ToolRequestReplayKind;
+    /** `adapter` and `compatibility` only — what the policy assumes of the refusal it repeats. */
+    readonly assumes?: 'refused-before-execution';
+    /**
+     * The app declared this tool as making changes, so it was asked again only
+     * because the server is declared to deduplicate by a key this call carries.
+     * The key protects only if the server uses it.
+     */
+    readonly deduplicated?: true;
+}
+/**
+ * footprintjs's failure categories (`AttemptCategory`) — the one fixed set
+ * every attempt record uses, so a saved request groups with every other.
+ */
+export type ToolRequestFailureCategory = 'timeout' | 'rate-limited' | 'server' | 'network' | 'auth' | 'permanent' | 'unknown';
+/**
+ * A failure as the record keeps it: a fixed sentence and a code. The thrown
+ * error's own message, name and fields are NEVER kept — a network or SDK
+ * error's text can carry a URL with a token in it, a host's internal name or
+ * a server's reply, and none of that is the library's to store.
+ */
+export interface ToolRequestError {
+    readonly message: 'The request failed before an answer arrived. Its error is not kept.' | 'The call ran out of time before an answer arrived.';
+    /** The failure's category — the same word as `failure`. */
+    readonly code: ToolRequestFailureCategory;
+}
+/** One attempt of an MCP request, as its retry series recorded it. */
+export interface ToolRequestAttempt {
+    /** 1-based. */
+    readonly attempt: number;
+    readonly outcome: ToolRequestAttemptOutcome;
+    readonly reason: ToolRequestReason;
+    /** The response's HTTP status — present when one arrived (`answered`, `refused`). */
+    readonly status?: number;
+    /** Which refusal a retry rule recognised — `refused` only. */
+    readonly kind?: ToolRequestRefusalKind;
+    /**
+     * The failure's category (footprintjs's `AttemptCategory`) — absent for
+     * `answered`. Named `failure`, not `category`: that key belongs to a retired
+     * contract the redaction rule no longer treats as the library's own.
+     */
+    readonly failure?: ToolRequestFailureCategory;
+    /** The wait before the next attempt, in ms — present exactly when `reason` is `'retryable'`. */
+    readonly waitMs?: number;
+    /**
+     * The wait the server stated in `Retry-After`, in ms — when it stated one.
+     * Absent beside a `waitMs` means that wait was the library's own backoff.
+     */
+    readonly retryAfterMs?: number;
+    /** `failed` and `timed-out` only. */
+    readonly error?: ToolRequestError;
+    /**
+     * `'unknown'` when the attempt ended without a response (`failed`,
+     * `timed-out`, `cut`): it was sent, and whether the server received and ran
+     * it is not known. Absent when a response arrived: the record keeps what the
+     * server answered (`status`) — for a `refused` attempt that is the server's
+     * own refusal, not proof that nothing ran.
+     */
+    readonly remote?: ToolRequestRemote;
+    /**
+     * What is known about whether this attempt took effect (see
+     * {@link ToolRequestEffect}). On every attempt the library files.
+     */
+    readonly effect?: ToolRequestEffect;
+    /** What allowed the next attempt — present exactly when `reason` is `'retryable'`. */
+    readonly permission?: ToolRequestPermission;
+    /** How long the attempt took, in ms, from sending to its end. On every attempt the library files. */
+    readonly durationMs?: number;
+}
+/** How an MCP request ended. */
+export interface ToolRequestEnd {
+    readonly outcome: ToolRequestOutcome;
+    readonly reason: ToolRequestReason;
+    /** The delivered response's HTTP status — `answered` and `refused`. */
+    readonly status?: number;
+    /** The refusal that was delivered — `refused` only. */
+    readonly kind?: ToolRequestRefusalKind;
+    /** The failure's category, as on an attempt. */
+    readonly failure?: ToolRequestFailureCategory;
+    /**
+     * Present when the request was CUT, and says what it was doing then.
+     * `'request'` — its LAST attempt was in flight (`cut`, `timed-out`): that
+     * attempt was sent and is the last row, or, past 100 attempts, the last one
+     * counted in `omitted`; whether the server ran it is unknown. `'wait'` — it
+     * was waiting to ask again, so no request was in flight and the next one was
+     * never sent: a cancellation cut the wait (`cancelled`), or the deadline left
+     * no time to finish it and the last refusal was delivered (`refused`,
+     * `no-time-left`). Absent when nothing was cut — and when the request was
+     * cancelled before its first attempt, so that nothing was sent.
+     */
+    readonly during?: 'request' | 'wait';
+    /** `failed` and `timed-out` only. */
+    readonly error?: ToolRequestError;
+    /**
+     * `'unknown'` when the request ended on an attempt with no response
+     * (`failed`, `timed-out`, `cut`): whether the server ran that request is not
+     * known.
+     */
+    readonly remote?: ToolRequestRemote;
+    /**
+     * How many requests the series sent: `attempts.length + omitted`. On every
+     * end the library files.
+     */
+    readonly attempts?: number;
+    /**
+     * What is known about the series' effect as a whole. Uncertainty survives:
+     * once any attempt's effect is `'unknown'`, so is the series' — a later
+     * proven refusal does not resolve it, and a later success does not prove the
+     * operation happened only once. `'applied'` only when the call completed and
+     * no attempt's effect is unknown; `'none'` only when every attempt is proven
+     * to have run nothing (or none was sent). On every end the library files.
+     */
+    readonly effect?: ToolRequestEffect;
+    /**
+     * The call failed as "may have run" (footprintjs's `UnknownEffectError`, its
+     * final error — a later refusal's, or the timeout — as the `cause`): under
+     * the `'app-authorized'` policy, the call genuinely lacked an answer
+     * somewhere and did not complete. Lacking an answer is not an unknown
+     * effect: it is an attempt that got no response at all (`remote:
+     * 'unknown'`), or a request accepted over HTTP (an `answered` 2xx) whose
+     * JSON-RPC answer never came. A received refusal or error IS an answer —
+     * its effect unknown, delivered as the server sent it — so a call whose
+     * every attempt received one has no `mayHaveRun`. Absent under
+     * `'compatibility'`, where the caller sees the error it always did, and
+     * for a call its caller cancelled, which ends with the caller's reason.
+     */
+    readonly mayHaveRun?: true;
+}
+/**
+ * What one MCP request's retry series did: every attempt it made, why it went
+ * on or stopped after each, how long it waited, and how the request ended.
+ *
+ * Filed by `mcpClient`'s retry series for a call the agent dispatched, ONCE per
+ * request, when the call settles — so the last attempt's `effect` can say
+ * whether the call completed — and at the moment of a cancellation, so a
+ * run cancelled during a wait still carries it when it is saved. A call that
+ * settles before its series (the MCP SDK's own timeout, say) cancels the series
+ * there and then, inside the call, so it is never filed after its run, and no
+ * request is sent after it. The framework stamps `toolCallId`, `toolName` and
+ * `iteration` from the dispatch, so two calls, or two runs, sharing one MCP
+ * connection never mix their attempts.
+ *
+ * ALLOW-LISTED, field by field: numbers, the library's own words, the
+ * endpoint label the app declared, or else the endpoint's origin. Never the
+ * URL's path, query or credentials, the call's arguments, the server's answer
+ * or an error's text.
+ *
+ * Only a transport `mcpClient` builds runs a series that files this; with
+ * retry off (`retryOnThrottle: false` on a plain transport) there is no series
+ * and no event.
+ */
+export interface ToolsRequestAttemptsPayload {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly iteration: number;
+    /** The `endpointLabel` the app declared for this endpoint, when it declared one. */
+    readonly endpoint?: string;
+    /** Otherwise the endpoint's ORIGIN — scheme, host and port, nothing else. */
+    readonly origin?: string;
+    /**
+     * The attempts, in order — at most 100. Every request the series sent is
+     * here or counted in `omitted`, a cut one included: `attempts.length +
+     * omitted` is the number of requests the series sent. A request it never
+     * sent has no row.
+     */
+    readonly attempts: readonly ToolRequestAttempt[];
+    /** Attempts made past the first 100, counted and not listed. `0` when every attempt is listed. */
+    readonly omitted: number;
+    readonly end: ToolRequestEnd;
+}

package/dist/esm/events/payloads/mcpRequests.js

@@ -0,0 +1,3 @@
+// ─── tools.mcp_client — one use of an MCP client pool ────────────────────────
+export {};
+//# sourceMappingURL=mcpRequests.js.map

package/dist/esm/events/payloads/mcpRequests.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpRequests.js","sourceRoot":"","sources":["../../../../src/events/payloads/mcpRequests.ts"],"names":[],"mappings":"AAAA,gFAAgF"}

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

@@ -0,0 +1,117 @@
+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[];
+}
+/**
+ * One piece of stored content reached the prompt.
+ *
+ * Emitted once per admitted chunk by the memory formatter (8.8.0 — the
+ * payload was declared in 2.x and nothing emitted it until then).
+ * `memoryId` is the STORE ENTRY's id, which for an indexed corpus is the
+ * chunk id you can cite. Which retriever produced it is
+ * `meta.runtimeStageId` (`sf-memory-read-<id>/format-default#N`) — the
+ * house rule is that events correlate by runtime stage id, not by
+ * duplicating the owner into every payload.
+ */
+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';
+}
+/** One candidate a retrieval considered, admitted or not. */
+export interface RetrievedCandidatePayload {
+    readonly id: string;
+    readonly score: number;
+    readonly rank: number;
+    readonly admitted: boolean;
+    /**
+     * Why it did not reach the prompt. `'over-char-budget'` (8.19.0) means it
+     * cleared the score floor and the count rule, and the retriever's
+     * `maxChars` budget was already spent by better-ranked passages.
+     */
+    readonly reason?: 'below-threshold' | 'over-budget' | 'over-max-entries' | 'over-char-budget';
+    readonly docUri?: string;
+    readonly page?: number;
+    readonly heading?: string;
+}
+/**
+ * A retrieval happened — here is everything it considered (8.8.0).
+ *
+ * The event that makes "why did the agent NOT read that passage"
+ * answerable. Until 8.8.0 the quality floor was applied inside the store,
+ * so a rejected candidate never came back and a retrieval that injected
+ * nothing left no trace of what it nearly injected.
+ *
+ * `candidates` absent means the store could not tell us (see
+ * `candidatesOmittedReason`) — it never means there were none. That case
+ * is `candidates: []` with `consideredCount: 0` and `corpusEmpty: true`.
+ */
+export interface MemoryRetrievedPayload {
+    /**
+     * Which rule ruled — the `RetrievalStrategy.name` that produced the verdicts
+     * below, e.g. `'top-k'`. The port promises its name "appears in the
+     * recording"; this is where. Without it a shipped `topK` and a consumer's own
+     * re-ranker leave records that are identical except for the numbers they
+     * disagree about.
+     */
+    readonly strategy: string;
+    /** Stable hash of the query text. The text itself is already in the recording once. */
+    readonly queryHash: string;
+    /** How many chunks the retriever was willing to admit. */
+    readonly k: number;
+    /** The quality floor, when the retriever set one. */
+    readonly threshold?: number;
+    /**
+     * The character budget the admitted passages were spent against (8.19.0),
+     * when the retriever set one. A count bound (`k`) is not a size bound;
+     * this is the size bound, and the candidates it dropped carry
+     * `reason: 'over-char-budget'`.
+     */
+    readonly maxChars?: number;
+    /**
+     * Passage characters the admitted set spends. Present exactly when
+     * `maxChars` is. Passage text only — the `<source …>` wrapper and the
+     * block header are added later by the formatter.
+     */
+    readonly charsUsed?: number;
+    readonly embedderId?: string;
+    /** Length of the query vector. */
+    readonly dimensions?: number;
+    readonly consideredCount: number;
+    readonly admittedCount: number;
+    readonly rejectedCount: number;
+    readonly candidates?: readonly RetrievedCandidatePayload[];
+    /**
+     * Whether `candidates` is every candidate that existed, or only as far
+     * as the requested pool reached. `false` never weakens the ADMITTED
+     * set — only the rejected list is then a sample.
+     */
+    readonly candidatesComplete: boolean;
+    readonly candidatesOmittedReason?: string;
+    /**
+     * The namespace held nothing at all. Almost always means the corpus was
+     * indexed under a different identity than the one being queried.
+     */
+    readonly corpusEmpty: boolean;
+    /** The namespace that was searched. */
+    readonly namespace?: string;
+}
+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;
+}

package/dist/esm/events/payloads/memory.js

@@ -0,0 +1,3 @@
+// ─── Tier 3: Observability Layers (recorder-emitted, opt-in) ──────────
+export {};
+//# sourceMappingURL=memory.js.map

package/dist/esm/events/payloads/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../../../src/events/payloads/memory.ts"],"names":[],"mappings":"AAAA,yEAAyE"}

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

@@ -0,0 +1,149 @@
+export interface ErrorRetriedPayload {
+    readonly attempt: number;
+    readonly maxAttempts: number;
+    readonly lastError: string;
+    /** How long the decorator waited before the attempt. */
+    readonly backoffMs: number;
+    readonly reason: string;
+    /**
+     * The wait the failure STATED (Retry-After, a gateway's "try again in N
+     * seconds"), in ms. Absent when it stated none; `backoffMs` is max(the
+     * schedule, this), capped by `maxDelayMs`.
+     */
+    readonly statedWaitMs?: number;
+}
+export interface ErrorRecoveredPayload {
+    readonly attempt: number;
+    readonly totalDurationMs: number;
+}
+/**
+ * v9.32 — `withCircuitBreaker` moved between states.
+ *
+ * The gap this fills, named: until 9.32 the breaker reported nothing at all
+ * through the in-run channel. `onStateChange` was the only way to see a trip,
+ * and that is a consumer-level callback where a run's correlation ids are not
+ * available — so a breaker that opened mid-run was invisible in the trace
+ * beside the tool calls it stopped. An independent reviewer (2026-08-13, on a
+ * local harness of scripted failures) watched a breaker open after two
+ * failures, serve the next request from fallback, half-open after cooldown and
+ * close after two probes: every step correct, every step off the record.
+ *
+ * Transitions ONLY. A hundred requests rejected while the breaker is already
+ * open produce zero events — a re-entry into the same state is not a change,
+ * and reporting it would turn a state log into a request log.
+ *
+ * On the `error.*` domain because that is where the provider decorators
+ * already report; `reliability.*` is the separate rules-based loop.
+ */
+export interface ErrorCircuitChangedPayload {
+    /** The state entered. */
+    readonly state: 'closed' | 'open' | 'half-open';
+    /**
+     * WHY, in the breaker's own words — `'3 consecutive failures'`,
+     * `'cooldown elapsed'`, `'2 probe successes'`, `'half-open probe failed'`.
+     *
+     * Never an error's message: the failure that tripped it is reported by
+     * whoever threw it, and copying it here would attribute one vendor's text to
+     * a state machine that only counted.
+     */
+    readonly reason: string;
+    /** WHICH provider this breaker wraps — `inner.name`, not a composite chain
+     *  name. Two breakers under one fallback produce one stream, and this is
+     *  what tells them apart. */
+    readonly providerName: string;
+}
+/**
+ * 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. Absent for a schema failure
+     *  under an output policy — the parser's message can quote the draft. */
+    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. Absent for a schema failure
+     *  under an output policy — the parser's message can quote the draft. */
+    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;
+}
+/**
+ * Tier 2 engaged: `parseOutput()` / `runTyped()` could not validate the
+ * model's answer against `outputSchema`, and the consumer-supplied
+ * `fallback` function is about to run. Fires BEFORE the fallback executes,
+ * so it is a record of degradation starting — not of it succeeding.
+ */
+export interface ResilienceOutputFallbackTriggeredPayload {
+    /** Which half of validation failed: bad JSON, or good JSON of the wrong shape. */
+    readonly stage: 'json-parse' | 'schema-validate';
+    /** First 200 chars of the model's raw answer. Truncated by construction —
+     *  never the whole output. */
+    readonly rawOutputPreview: string;
+    /** Message of the `OutputSchemaError` that opened the ladder. */
+    readonly primaryErrorMessage: string;
+    /** Corrective re-asks this run already paid for before the answer reached
+     *  the ladder (the `outputAttempts` ledger minus the first attempt).
+     *  ABSENT when the caller parsed a string that did not come from this
+     *  agent's last run — absent means unknown, never zero. */
+    readonly retriesSpent?: number;
+}
+/**
+ * Tier 3 engaged: the fallback function itself failed (threw, or returned a
+ * value that also failed the schema) and the static `canned` value is being
+ * returned instead. This is the event that says a run billed real tokens and
+ * ended in a constant — with `canned` configured, `runTyped()` is
+ * structurally unable to throw, so this event is the ONLY signal.
+ */
+export interface ResilienceOutputCannedUsedPayload {
+    /** First 200 chars of the model's raw answer. Truncated by construction. */
+    readonly rawOutputPreview: string;
+    /** Why tier 2 did not hold — the fallback's own throw, or the validation
+     *  error its return value produced. */
+    readonly fallbackErrorMessage: string;
+    /** Corrective re-asks this run already paid for. ABSENT when unknown. */
+    readonly retriesSpent?: number;
+}

package/dist/esm/events/payloads/reliability.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=reliability.js.map

package/dist/esm/events/payloads/reliability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reliability.js","sourceRoot":"","sources":["../../../../src/events/payloads/reliability.ts"],"names":[],"mappings":""}