agentfootprint 11.2.0 → 11.3.0

package/dist/types/tools/requestEvidence.d.ts

@@ -0,0 +1,79 @@
+/**
+ * requestEvidence — the door a tool call's REQUEST attempts enter its run by.
+ *
+ * Pattern: a per-dispatch port (the `LLMCallHooks` precedent) + one allow-list.
+ * Role:    The seam between a retry series that runs BELOW a tool — inside
+ *          `mcpClient`'s transport, built before any run existed — and the run
+ *          that dispatched the call. The dispatcher builds the port for each
+ *          call (`requestEvidenceFor`) and puts it on the call's context under
+ *          an internal symbol; the MCP tool hands it down to the series that
+ *          sends its request (`mcp/requestLedger.ts`); the series files ONE
+ *          record when the request ends. Nothing here retries anything.
+ * Emits:   agentfootprint.tools.request_attempts
+ *
+ * Why a port and not a scope: a decorator constructed by the consumer before
+ * any run exists can never reach a scope (`resilienceHooks` says the same of
+ * the provider decorators). The call is the one thing both sides share, so the
+ * port rides the call — and the identity on the event (`toolCallId`,
+ * `toolName`, `iteration`, the run's ids in the meta) is stamped HERE, from the
+ * dispatch, never by whatever files: a filing cannot claim another call.
+ *
+ * Why an internal symbol and not a public `ctx` field: this is the evidence
+ * path for the library's own retry series, not a retry API. A public member
+ * would invite every tool to file attempts the library cannot vouch for. The
+ * symbol is enumerable, so a wrapper that copies the context (`{ ...ctx }`)
+ * keeps it; a filing from anyone else still passes the allow-list below.
+ *
+ * The port only FILES. What cancels a call is the call's own context signal
+ * (`ctx.signal`), read by the MCP tool whether or not a port rides along — a
+ * cancellation must never depend on evidence being attributable.
+ *
+ * THE ALLOW-LIST is the whole record: numbers, the library's own words, the
+ * endpoint label the app declared or else the endpoint's ORIGIN. A filing with
+ * anything else in it — a field nobody listed, a word outside its set, a URL
+ * with a path, an array that is not a plain one — is refused whole, never
+ * trimmed into something it did not say. Values are read as DATA, through own
+ * property descriptors, so no getter, `toJSON` or array subclass a filing
+ * carries ever runs or reaches the record.
+ */
+import type { ToolsRequestAttemptsPayload } from '../events/payloads.js';
+import { type EmitableScope } from '../recorders/core/typedEmit.js';
+/** At most this many attempts are listed per request; the rest are counted (`omitted`). */
+export declare const MAX_REQUEST_ATTEMPT_ROWS = 100;
+/** What a request's series files: the event's payload, less the identity the dispatcher stamps. */
+export type RequestEvidence = Omit<ToolsRequestAttemptsPayload, 'toolCallId' | 'toolName' | 'iteration'>;
+/** Where one dispatched call's request evidence goes. */
+export interface RequestEvidenceSink {
+    /** File the request's record. Never throws; a filing outside the allow-list is refused whole. */
+    file(evidence: RequestEvidence): void;
+}
+/** @internal The context key the dispatcher puts a call's sink under. */
+export declare const REQUEST_EVIDENCE: unique symbol;
+/** What the dispatcher spreads into a call's context. */
+export interface RequestEvidencePort {
+    readonly [REQUEST_EVIDENCE]: RequestEvidenceSink;
+}
+/** The call the sink files for — the dispatch's own identity. */
+export interface RequestEvidenceCall {
+    readonly toolName: string;
+    readonly toolCallId: string;
+    readonly iteration: number;
+}
+/**
+ * The port for one dispatch: files `agentfootprint.tools.request_attempts`
+ * mid-stage through `typedEmit` (so the run's redaction rule serves it, and the
+ * meta carries the real `runtimeStageId`), stamped with `call`.
+ */
+export declare function requestEvidenceFor(scope: EmitableScope, call: RequestEvidenceCall): RequestEvidencePort;
+/**
+ * The sink a call's context carries, or `undefined` — a context from a door with
+ * no run (`mcpServe`, a direct `execute`), or one a wrapper rebuilt without it.
+ * Never throws, whatever `ctx` is.
+ */
+export declare function requestEvidenceOf(ctx: unknown): RequestEvidenceSink | undefined;
+/**
+ * `raw` rebuilt from allow-listed fields — a fresh plain object — or
+ * `undefined` when anything in it is outside the list.
+ */
+export declare function servedRequestEvidence(raw: unknown): RequestEvidence | undefined;
+//# sourceMappingURL=requestEvidence.d.ts.map

package/dist/types/tools/requestEvidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestEvidence.d.ts","sourceRoot":"","sources":["../../../src/tools/requestEvidence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAIH,OAAO,KAAK,EAIV,2BAA2B,EAC5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAa,KAAK,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAE/E,2FAA2F;AAC3F,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C,mGAAmG;AACnG,MAAM,MAAM,eAAe,GAAG,IAAI,CAChC,2BAA2B,EAC3B,YAAY,GAAG,UAAU,GAAG,WAAW,CACxC,CAAC;AAEF,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,iGAAiG;IACjG,IAAI,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;CACvC;AAED,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,EAAE,OAAO,MAAkD,CAAC;AAEzF,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,mBAAmB,CAAC;CAClD;AAED,iEAAiE;AACjE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,aAAa,EACpB,IAAI,EAAE,mBAAmB,GACxB,mBAAmB,CAsBrB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,mBAAmB,GAAG,SAAS,CAiB/E;AA0ED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAiB/E"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "11.2.0",
+  "version": "11.3.0",
   "description": "The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.",
   "license": "MIT",
   "type": "commonjs",