agentfootprint 11.3.0 → 11.5.0

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

@@ -173,6 +173,15 @@ export interface AgentTurnEndPayload {
      * dispatcher carries the agent's `turn_end` but not the `answer.*` domain.
      */
     readonly answerAssessment?: AnswerAssessmentPayload;
+    /**
+     * The app's words the appended standing line named calls in — registered
+     * tool name → the tool's declared `displayName`. Present ONLY when the line
+     * (`.answerLayer({ standingLine: true })`) named a reason's calls by a
+     * declared name, so every other turn emits the exact payload it always did.
+     * The words are the app's own, already in `finalContent`; the record keeps
+     * them so a reader rebuilds the very line from the record.
+     */
+    readonly standingLineNames?: Readonly<Record<string, string>>;
     /** Runtime-composed typed negatives, with verification and delivery kept separate. */
     readonly answerNegatives?: AnswerNegativesPayload;
     /**
@@ -2261,17 +2270,22 @@ export interface ToolsCodeRunPayload {
 /**
  * What one attempt of an MCP request came to.
  *
- *   - `'answered'` — a response arrived and no retry rule refused it. It is
- *     delivered as it came, WHATEVER its status: a 503 is `answered` with
+ *   - `'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`.
+ *     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. The only
- *     outcome that is ever retried. 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).
+ *     (`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). Never retried: the server may have run it.
+ *     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
@@ -2279,7 +2293,7 @@ export interface ToolsCodeRunPayload {
  *     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 an answer, so they carry `remote: 'unknown'`.
+ * 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
@@ -2296,7 +2310,7 @@ export type ToolRequestAttemptOutcome = 'answered' | 'refused' | 'failed' | 'tim
 export type ToolRequestOutcome = ToolRequestAttemptOutcome | 'cancelled';
 /**
  * Whether the server received and ran a request, when that is not known: the
- * attempt ended without an answer (`failed`, `timed-out`, `cut`), so 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.
  */
@@ -2304,24 +2318,81 @@ export type ToolRequestRemote = 'unknown';
 /**
  * Why the request went on after an attempt, or ended with it.
  *
- *   - `'retryable'` — refused; another attempt follows after `waitMs`. The
- *     only reason that is not an end.
+ *   - `'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'` — refused, and the request has made every attempt it may.
- *   - `'wait-limit'` — refused, and 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'` — refused, and the wait would pass the call's deadline;
- *     or the deadline cut a request or a wait.
- *   - `'not-replayable'` — refused, but the request's body cannot be sent twice.
- *   - `'not-retryable'` — the attempt failed in a way this retry never
- *     repeats: only a response the retry policy recognises as a refusal (a 429,
- *     a session-busy reply) is retried.
+ *   - `'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' | 'cancelled';
+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.
@@ -2364,13 +2435,22 @@ export interface ToolRequestAttempt {
     /** `failed` and `timed-out` only. */
     readonly error?: ToolRequestError;
     /**
-     * `'unknown'` when the attempt ended without an answer (`failed`,
+     * `'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 {
@@ -2397,17 +2477,47 @@ export interface ToolRequestEnd {
     /** `failed` and `timed-out` only. */
     readonly error?: ToolRequestError;
     /**
-     * `'unknown'` when the request ended on an attempt with no answer (`failed`,
-     * `timed-out`, `cut`): whether the server ran that request is not known.
+     * `'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 request ends — and at the moment of a cancellation, so a
+ * 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

package/dist/esm/lib/displayName.d.ts

@@ -0,0 +1,81 @@
+/**
+ * displayName — the ONE rule for a tool's `displayName` (the app's own words
+ * for what a call of the tool does, read by a person), and the ONE way the
+ * library names a set of calls in those words: the declared ones named, the
+ * rest counted.
+ *
+ * Pattern: two pure functions and one small reader, no state.
+ * Role:    Leaf. Asked for the RULE by `tools/tools.ts` · `defineTool` and by
+ *          the registration funnel (`core/agent/buildToolRegistry.ts`), and for
+ *          the NAMING by the two texts the library appends after an answer —
+ *          the standing line (`core/agent/assessment/compose.ts`) and the
+ *          limits block (`semantics/coverage/answer.ts`). Those two cannot
+ *          import each other, so the naming lives here and they cannot name
+ *          the same calls in two different ways.
+ * Emits:   N/A.
+ *
+ * ## Why only the app's words
+ *
+ * A tool's registered name is the MODEL's vocabulary (`load_attachment`), and
+ * an app may forbid showing it to the people it serves. This module never
+ * prints it: a call is named only by the words its tool declared, and a call
+ * whose tool declared none is counted ("and 1 other call"), never named. A
+ * caller that gets `undefined` back says what it always said. Not every
+ * surface asks this module yet — the time layer's limits lines and the
+ * answer account's rows still print the registered name (a known follow-up).
+ *
+ * ## Why the plain-line rule
+ *
+ * The words reach a person verbatim, after an answer, so they are held to the
+ * rule every declared label a report prints is held to (`lib/plainLine.ts` ·
+ * `plainLineProblem`: no control, line or paragraph separator, or invisible
+ * format character — a bidi override would reverse what the person reads),
+ * judged BEFORE the length, and capped at the 60 characters a skill's `title`
+ * and an account label are capped at.
+ */
+/** The longest display name a person reads — the cap every declared label a report prints has. */
+export declare const MAX_DISPLAY_NAME_CHARS = 60;
+/**
+ * At most this many declared names in one phrase; any further call is counted
+ * with the calls whose tools declared none. A line for a person, not a list.
+ */
+export declare const MAX_NAMED_CALLS = 3;
+/**
+ * Why `value` is not a display name, or `undefined` when it is — judged on the
+ * trimmed text (the text a person would read). `label` names the field in the
+ * sentence, so a refusal says where it was written.
+ */
+export declare function displayNameProblem(label: string, value: unknown): string | undefined;
+/**
+ * The display name a person may read — trimmed — or `undefined`. A value the
+ * rule refuses is never printed: a tool assembled by hand, or served by a
+ * ToolProvider after the agent was built, is read through this too.
+ */
+export declare function readDisplayName(value: unknown): string | undefined;
+/**
+ * The calls, named in the app's words — each distinct declared name once, in
+ * the calls' order, at most {@link MAX_NAMED_CALLS}; every other call counted,
+ * with `alsoUnnamed` (calls the record does not name at all). `calls` holds one
+ * entry per CALL (the caller has already said each call once), each with its
+ * tool's registered name — the key a declared name is looked up by, never
+ * printed:
+ *
+ * - `loading the attached data`
+ * - `loading the attached data and searching the catalog`
+ * - `loading the attached data and 1 other call`
+ *
+ * `undefined` when no call's tool declared a name: the caller then says what
+ * it always said — the registered name is never the fallback.
+ *
+ * @example
+ * ```ts
+ * namedCalls(
+ *   [{ toolCallId: 'c1', toolName: 'load_attachment' }, { toolCallId: 'c2', toolName: 'list_runs' }],
+ *   0,
+ *   (tool) => (tool === 'load_attachment' ? 'loading the attached data' : undefined),
+ * ); // 'loading the attached data and 1 other call'
+ * ```
+ */
+export declare function namedCalls(calls: readonly {
+    readonly toolName: string;
+}[], alsoUnnamed: number, displayNameOf: (toolName: string) => string | undefined): string | undefined;

package/dist/esm/lib/displayName.js

@@ -0,0 +1,119 @@
+/**
+ * displayName — the ONE rule for a tool's `displayName` (the app's own words
+ * for what a call of the tool does, read by a person), and the ONE way the
+ * library names a set of calls in those words: the declared ones named, the
+ * rest counted.
+ *
+ * Pattern: two pure functions and one small reader, no state.
+ * Role:    Leaf. Asked for the RULE by `tools/tools.ts` · `defineTool` and by
+ *          the registration funnel (`core/agent/buildToolRegistry.ts`), and for
+ *          the NAMING by the two texts the library appends after an answer —
+ *          the standing line (`core/agent/assessment/compose.ts`) and the
+ *          limits block (`semantics/coverage/answer.ts`). Those two cannot
+ *          import each other, so the naming lives here and they cannot name
+ *          the same calls in two different ways.
+ * Emits:   N/A.
+ *
+ * ## Why only the app's words
+ *
+ * A tool's registered name is the MODEL's vocabulary (`load_attachment`), and
+ * an app may forbid showing it to the people it serves. This module never
+ * prints it: a call is named only by the words its tool declared, and a call
+ * whose tool declared none is counted ("and 1 other call"), never named. A
+ * caller that gets `undefined` back says what it always said. Not every
+ * surface asks this module yet — the time layer's limits lines and the
+ * answer account's rows still print the registered name (a known follow-up).
+ *
+ * ## Why the plain-line rule
+ *
+ * The words reach a person verbatim, after an answer, so they are held to the
+ * rule every declared label a report prints is held to (`lib/plainLine.ts` ·
+ * `plainLineProblem`: no control, line or paragraph separator, or invisible
+ * format character — a bidi override would reverse what the person reads),
+ * judged BEFORE the length, and capped at the 60 characters a skill's `title`
+ * and an account label are capped at.
+ */
+import { plainLineProblem } from './plainLine.js';
+/** The longest display name a person reads — the cap every declared label a report prints has. */
+export const MAX_DISPLAY_NAME_CHARS = 60;
+/**
+ * At most this many declared names in one phrase; any further call is counted
+ * with the calls whose tools declared none. A line for a person, not a list.
+ */
+export const MAX_NAMED_CALLS = 3;
+/**
+ * Why `value` is not a display name, or `undefined` when it is — judged on the
+ * trimmed text (the text a person would read). `label` names the field in the
+ * sentence, so a refusal says where it was written.
+ */
+export function displayNameProblem(label, value) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        return (`${label} must be a non-empty string — the app's own words for what a call of this ` +
+            `tool does, read by a person (got ${typeof value === 'string' ? JSON.stringify(value) : typeof value}). Omit it to ` +
+            'leave the call unnamed.');
+    }
+    const text = value.trim();
+    const notPlain = plainLineProblem(label, text);
+    if (notPlain !== undefined)
+        return notPlain;
+    if (text.length > MAX_DISPLAY_NAME_CHARS) {
+        return `${label} is ${text.length} characters; the limit is ${MAX_DISPLAY_NAME_CHARS}.`;
+    }
+    return undefined;
+}
+/**
+ * The display name a person may read — trimmed — or `undefined`. A value the
+ * rule refuses is never printed: a tool assembled by hand, or served by a
+ * ToolProvider after the agent was built, is read through this too.
+ */
+export function readDisplayName(value) {
+    return displayNameProblem('displayName', value) === undefined
+        ? value.trim()
+        : undefined;
+}
+/**
+ * The calls, named in the app's words — each distinct declared name once, in
+ * the calls' order, at most {@link MAX_NAMED_CALLS}; every other call counted,
+ * with `alsoUnnamed` (calls the record does not name at all). `calls` holds one
+ * entry per CALL (the caller has already said each call once), each with its
+ * tool's registered name — the key a declared name is looked up by, never
+ * printed:
+ *
+ * - `loading the attached data`
+ * - `loading the attached data and searching the catalog`
+ * - `loading the attached data and 1 other call`
+ *
+ * `undefined` when no call's tool declared a name: the caller then says what
+ * it always said — the registered name is never the fallback.
+ *
+ * @example
+ * ```ts
+ * namedCalls(
+ *   [{ toolCallId: 'c1', toolName: 'load_attachment' }, { toolCallId: 'c2', toolName: 'list_runs' }],
+ *   0,
+ *   (tool) => (tool === 'load_attachment' ? 'loading the attached data' : undefined),
+ * ); // 'loading the attached data and 1 other call'
+ * ```
+ */
+export function namedCalls(calls, alsoUnnamed, displayNameOf) {
+    const named = [];
+    let rest = alsoUnnamed;
+    for (const call of calls) {
+        const words = displayNameOf(call.toolName);
+        if (words === undefined)
+            rest += 1;
+        else if (named.includes(words))
+            continue;
+        else if (named.length < MAX_NAMED_CALLS)
+            named.push(words);
+        else
+            rest += 1;
+    }
+    if (named.length === 0)
+        return undefined;
+    const parts = rest > 0 ? [...named, `${rest} other ${rest === 1 ? 'call' : 'calls'}`] : named;
+    return parts.length === 1
+        ? parts[0]
+        : `${parts.slice(0, -1).join(', ')} and ${parts[parts.length - 1]}`;
+}
+//# sourceMappingURL=displayName.js.map

package/dist/esm/lib/displayName.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"displayName.js","sourceRoot":"","sources":["../../../src/lib/displayName.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD,kGAAkG;AAClG,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAEzC;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AAEjC;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAa,EAAE,KAAc;IAC9D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3D,OAAO,CACL,GAAG,KAAK,4EAA4E;YACpF,oCACE,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,KAC7D,gBAAgB;YAChB,yBAAyB,CAC1B,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC1B,MAAM,QAAQ,GAAG,gBAAgB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IAC/C,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAC5C,IAAI,IAAI,CAAC,MAAM,GAAG,sBAAsB,EAAE,CAAC;QACzC,OAAO,GAAG,KAAK,OAAO,IAAI,CAAC,MAAM,6BAA6B,sBAAsB,GAAG,CAAC;IAC1F,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,kBAAkB,CAAC,aAAa,EAAE,KAAK,CAAC,KAAK,SAAS;QAC3D,CAAC,CAAE,KAAgB,CAAC,IAAI,EAAE;QAC1B,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,UAAU,CACxB,KAA+C,EAC/C,WAAmB,EACnB,aAAuD;IAEvD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,IAAI,GAAG,WAAW,CAAC;IACvB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC3C,IAAI,KAAK,KAAK,SAAS;YAAE,IAAI,IAAI,CAAC,CAAC;aAC9B,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,SAAS;aACpC,IAAI,KAAK,CAAC,MAAM,GAAG,eAAe;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;;YACtD,IAAI,IAAI,CAAC,CAAC;IACjB,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACzC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,EAAE,GAAG,IAAI,UAAU,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAC9F,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;QACvB,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;QACV,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;AACxE,CAAC"}

package/dist/esm/mcp/callLifetime.d.ts

@@ -15,35 +15,78 @@
  *      the call. The link is undone when the call settles: the SDK keeps its
  *      abort listener on the signal it was given, and a link that outlived the
  *      call would cancel a request that had already finished.
- *   2. ITS TICKET is issued, when the call carries the run's evidence port and
- *      the connection has a ledger, keyed by the request's params object.
+ *   2. ITS MARKER is issued when the connection has a ledger, with its ticket
+ *      when the call carries the run's evidence port: a library-private string
+ *      in the request's `_meta` (`callMarker.ts`), which ties the request to
+ *      the call even when the SDK copies the params, and which the transport
+ *      takes out before anything is sent.
  *   3. ITS SETTLING ENDS ITS SERIES. However `callTool` settles — answered,
  *      failed, or given up by the SDK (its own timeout) — a retry series still
  *      sending the request is cut there and then, inside the call: it files
  *      `cancelled` before the call's result is read, and sends nothing more.
+ *   4. ITS VERDICT REACHES ITS RECORD. A series that has ended waits for the
+ *      call to settle before it files, because only the call can say whether
+ *      the answer completed — a 200 can carry a tool error. The call leaves its
+ *      verdict in the request's shared replay facts (`replay.ts` ·
+ *      `RequestReplay`) before it settles the series' wait.
+ *   5. "MAY HAVE RUN" IS RAISED HERE — footprintjs's law, under the
+ *      `'app-authorized'` policy (`replay.ts` · `RequestReplay`, its
+ *      `uncertain`). A received refusal or error is preserved: a 429, a 503,
+ *      a JSON-RPC or tool error — or a chain in which every attempt received
+ *      one — keeps the server's error as it came, its effect still `unknown`.
+ *      A call that genuinely lacked an answer somewhere — an attempt with no
+ *      response at all, or a request the HTTP layer accepted whose JSON-RPC
+ *      answer never came — and then fails, fails with footprintjs's
+ *      `UnknownEffectError`, its final error (a later refusal's, or the
+ *      timeout) as the `cause`: that error alone would read as "failed, try
+ *      again". A call that completes returns normally. Under `'compatibility'`
+ *      the caller sees the error it always did; the record still says the
+ *      effect is unknown. A cancellation never raises it: a call its caller
+ *      cancelled ends with the caller's reason, as it always did.
  *
- * In dev mode, a ticket that no request was bound to by the time the call
- * settled, when a `tools/call` request DID go out, is named once per connection: the SDK copied
- * the params, so the call's attempts could not be matched to it. Its
- * cancellation still reached the request (1, and the ledger's own watch on
- * `notifications/cancelled`).
+ * In dev mode, a ticket that no request was matched to by the time the call
+ * settled, when a `tools/call` request DID go out, is named once per
+ * connection: the SDK rebuilt the params without the marker, so the call's
+ * attempts could not be matched to it. Its cancellation still reached the
+ * request (1, and the ledger's own watch on `notifications/cancelled`). Under
+ * `'app-authorized'` such a request is never sent at all
+ * (`replayUnavailable.ts`).
  */
+import type { CallVerdict } from './replay.js';
 import type { RequestLedger } from './requestLedger.js';
-/** A call that has been opened: the signal its SDK request runs under, and how to close it. */
-export interface OpenCall {
+/** A call that has been opened: the params to send, the signal its SDK request runs under, and how to close it. */
+export interface OpenCall<P extends object = object> {
+    /**
+     * What to hand the SDK: the call's params, with its private marker in
+     * `_meta` when a ledger watches the connection (`callMarker.ts`). The
+     * transport takes the marker out again: the server never sees it.
+     */
+    readonly params: P;
     /** What cancels the SDK request — absent when nothing can. */
     readonly signal?: AbortSignal;
-    /** The call settled: undo the link, cut a series still sending, check the ticket was bound. */
-    close(): void;
+    /**
+     * The call failed with `error` (`verdict` says how far it got): the error it
+     * fails with — `error` itself, or, under `'app-authorized'`, footprintjs's
+     * `UnknownEffectError` with `error` as its `cause` when the call genuinely
+     * lacked an answer somewhere (see 5 above).
+     */
+    failed(error: unknown, verdict: CallVerdict): unknown;
+    /**
+     * The call settled with `verdict`: leave it for the record, settle it in the
+     * ledger (its answer is no longer awaited), undo the link, cut a series
+     * still sending, check its request was matched.
+     */
+    close(verdict: CallVerdict): void;
 }
 /**
  * Open one call.
  *
- * @param params the request's params object — the SDK hands this very object to
- *   the transport, which is how the ledger knows the request is this call's.
+ * @param params the request's params. The call sends them marked
+ *   (`OpenCall.params`): the marker, not the object, is how the ledger knows
+ *   the request is this call's — it survives an SDK that copies the params.
  * @param ctx the call's context: its signal, and the run's evidence port if any.
  * @param clientSignal the client's own `signal` (`McpClientOptions.signal`).
  * @param ledger the connection's ledger, when the library built its transport.
  * @param server the client's name, for the dev-mode note.
  */
-export declare function openCall(params: object, ctx: unknown, clientSignal: AbortSignal | undefined, ledger: RequestLedger | undefined, server: string): OpenCall;
+export declare function openCall<P extends object>(params: P, ctx: unknown, clientSignal: AbortSignal | undefined, ledger: RequestLedger | undefined, server: string): OpenCall<P>;