agentfootprint 10.3.0 → 10.3.1

package/dist/tool-providers/types.js

@@ -1,54 +0,0 @@
-"use strict";
-/**
- * ToolProvider — abstraction over tool dispatch.
- *
- * v2.4 shipped tools as a flat array on the agent (registered via
- * `agent.tool(t)` / `agent.tools(arr)`). That model breaks down once
- * production agents need:
- *   1. Permission gating per-tool, per-caller (read-only roles, etc.)
- *   2. Per-skill tool gating (only show the active skill's tools to
- *      the LLM each turn)
- *   3. Composable filters (a `withReadonly` decorator over a `withSkill`
- *      decorator over the base tool list)
- *
- * `ToolProvider` is the answer: a chainable abstraction over "what
- * tools does the LLM see right now?". The agent asks the provider
- * each iteration; the provider returns the visible tool set computed
- * from whatever predicates / role gates / skill filters the consumer
- * composed.
- *
- * Pattern: Strategy (GoF) — each ToolProvider is a strategy for
- *          "compute the visible tool list given current context".
- *          Decorator (GoF) — `gatedTools(inner, predicate)` wraps any
- *          provider with an additional filter, mirroring how `withRetry`
- *          / `withFallback` decorate `LLMProvider`.
- * Role:    Layer-3 tool-dispatch primitive. Agent calls `provider.list(ctx)`
- *          each iteration to compute the visible tool set.
- * Emits:   N/A (pure compute; permission denials emit elsewhere via the
- *          permission subsystem).
- *
- * @example  Static tool list (90% case — what `.tools(arr)` does today)
- *   const provider = staticTools([weather, lookupOrder]);
- *
- * @example  Read-only enforcement (role-based gate)
- *   const readOnlyProvider = gatedTools(
- *     staticTools([weather, lookupOrder, processRefund]),
- *     (toolName) => policy.isAllowed(toolName),
- *   );
- *
- * @example  Skill-gated dispatch (only active skill's tools visible)
- *   const skillGated = gatedTools(
- *     staticTools(allTools),
- *     (toolName, ctx) => ctx.activeSkillId
- *       ? skillsToolMap[ctx.activeSkillId].includes(toolName)
- *       : alwaysVisible.includes(toolName),
- *   );
- *
- * @example  Stack: read-only over skill-gated
- *   const provider = gatedTools(
- *     gatedTools(staticTools(allTools), readOnlyPredicate),
- *     skillGatePredicate,
- *   );
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=types.js.map

package/dist/tool-providers/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tool-providers/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG"}

package/dist/types/adapters/forcedToolChoice.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"forcedToolChoice.d.ts","sourceRoot":"","sources":["../../../src/adapters/forcedToolChoice.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,yBAAyB,GAAG,0BAA0B,CAAC,EACnF,KAAK,EAAE,MAAM,GACZ,OAAO,CAMT;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,SAAS;gBAEf,IAAI,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE;CAUxE"}

package/dist/types/adapters/llm/contextWindow.d.ts

@@ -1,112 +0,0 @@
-/**
- * ContextWindowExceededError — "the request did not fit" as a typed error
- * that names the fixes (9.6.0).
- *
- * Every vendor refuses an over-long request in its own words, and until now
- * every one of them reached the caller as an opaque provider error:
- *
- *   [openai] 400 Input tokens exceed the configured limit of 272000 tokens.
- *   Your messages resulted in 879073 tokens.
- *
- * That is the message a production field deployment spent a day on. It is a
- * true sentence and a useless one: it does not say which of the framework's
- * dials moves that number, and it looks exactly like a transient 400 — so the
- * natural next move is to retry, which re-sends the same oversized history and
- * fails identically, forever.
- *
- * So the adapters translate it, ONCE, into an error whose message contains the
- * three fixes in the order they are worth trying, and which carries the two
- * numbers (limit, actual) when the vendor stated them.
- *
- * **Detection is deliberately conservative.** Only unmistakable phrases and
- * vendor codes translate; everything else passes through untouched as the
- * provider error it always was. In particular a RATE limit ("rate limit
- * reached … tokens per min") is a different failure with a different fix and
- * must never land here — which is why no pattern matches on "too many tokens".
- *
- * @see ../../core/runCheckpoint.ts  where this class makes `resumeOnError`
- *                                   stop advertising a resume that cannot work
- */
-/** Discriminator carried on the error — stable across releases. */
-export declare const ERR_CONTEXT_WINDOW_EXCEEDED: "ERR_CONTEXT_WINDOW_EXCEEDED";
-/**
- * Thrown by an LLM adapter when the provider refused the request because the
- * prompt did not fit the model's context window.
- *
- * A refusal, not a failure of the model: nothing was generated and nothing was
- * charged for output. Retrying the identical request is deterministic — it
- * fails the same way — so this is one of the classes
- * {@link canResume} reports as not resumable.
- *
- * @example
- * ```ts
- * import { ContextWindowExceededError } from 'agentfootprint';
- *
- * try {
- *   await agent.run({ message: 'summarise the fabric inventory' });
- * } catch (err) {
- *   if (err instanceof ContextWindowExceededError) {
- *     console.error(`sent ${err.actualTokens} against ${err.limitTokens}`);
- *     // …cap the tool result, or add .window(slidingWindow({ keepRecentTurns: 2 }))
- *   }
- * }
- * ```
- */
-export declare class ContextWindowExceededError extends Error {
-    readonly code: "ERR_CONTEXT_WINDOW_EXCEEDED";
-    /** Which adapter refused — `'openai'`, `'anthropic'`, `'bedrock'`, … */
-    readonly provider: string;
-    /** The model's (or gateway's) ceiling in tokens, when the vendor said it. */
-    readonly limitTokens?: number;
-    /** What the request actually came to in tokens, when the vendor said it. */
-    readonly actualTokens?: number;
-    /** HTTP status, when there was one. Kept so retry policies still see a 4xx. */
-    readonly status?: number;
-    /** The provider's own error, unchanged. */
-    readonly cause?: Error;
-    constructor(args: {
-        provider: string;
-        providerMessage: string;
-        limitTokens?: number;
-        actualTokens?: number;
-        status?: number;
-        cause?: Error;
-    });
-}
-/** `true` for the typed error, including across a `structuredClone`-free
- *  boundary where `instanceof` still holds. Kept as a function so callers do
- *  not have to import the class to ask the question. */
-export declare function isContextWindowExceeded(err: unknown): err is ContextWindowExceededError;
-export interface ContextWindowTranslation {
-    /** Which adapter is asking — appears in the message prefix. */
-    readonly provider: string;
-    /**
-     * Extra text to search — the HTTP body, for adapters that read the response
-     * themselves instead of going through a vendor SDK.
-     */
-    readonly bodyText?: string;
-    /** Status the adapter already knows (browser adapters read it off `Response`). */
-    readonly status?: number;
-}
-/**
- * Does this error SAY it is a context overflow, whoever produced it?
- *
- * The same conservative phrase test the adapters translate on, asked without
- * building anything — for code that has to classify an error it did not
- * catch at an adapter boundary. A custom `LLMProvider`, a gateway wrapper or
- * a proxy in front of a vendor produces the vendor's sentence without ever
- * passing through `wrapError`, and a caller reading that error deserves the
- * same answer an adapter would have given.
- *
- * @see ../../core/runCheckpoint.ts — the caller this exists for
- */
-export declare function looksLikeContextWindowExceeded(err: unknown, bodyText?: string): boolean;
-/**
- * Translate a provider error into {@link ContextWindowExceededError} — or
- * return `undefined`, which means "not this failure, leave it alone".
- *
- * Already-translated errors are returned as they are, so an adapter that
- * wraps another adapter cannot double-wrap.
- */
-export declare function asContextWindowExceeded(err: unknown, options: ContextWindowTranslation): ContextWindowExceededError | undefined;
-//# sourceMappingURL=contextWindow.d.ts.map

package/dist/types/adapters/llm/contextWindow.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"contextWindow.d.ts","sourceRoot":"","sources":["../../../../src/adapters/llm/contextWindow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,mEAAmE;AACnE,eAAO,MAAM,2BAA2B,+BAAyC,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,IAAI,gCAA+B;IAE5C,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB,2CAA2C;IAC3C,SAAkB,KAAK,CAAC,EAAE,KAAK,CAAC;gBAEpB,IAAI,EAAE;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,eAAe,EAAE,MAAM,CAAC;QACxB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,KAAK,CAAC;KACf;CASF;AAED;;wDAEwD;AACxD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,0BAA0B,CAKvF;AAoJD,MAAM,WAAW,wBAAwB;IACvC,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAIvF;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,wBAAwB,GAChC,0BAA0B,GAAG,SAAS,CAoBxC"}

package/dist/types/adapters/nativeOutputSchema.d.ts

@@ -1,67 +0,0 @@
-/**
- * nativeOutputSchema — whether a provider puts a structured-output format
- * (`LLMRequest.outputFormat`) on its wire FOR A MODEL, and the one error for
- * a model or adapter that does not.
- *
- * Pattern: capability declaration + its one reader (the `forcedToolChoice.ts`
- *          twin). The adapter declares `LLMProvider.carriesNativeOutputSchema`
- *          plus `supportsNativeOutputSchema(model)`, and everything that sends
- *          `LLMRequest.outputFormat` asks HERE with the model it will call:
- *          the agent's `'native'` output strategy at run start and again at
- *          request assembly.
- * Role:    Port-level, beside `types.ts`.
- *
- * Why per model: Anthropic's structured outputs are available on the models
- * its page lists — Claude Haiku 4.5, Sonnet 4.5, Opus 4.5 and every later
- * model — and not on Opus 4.1 and earlier
- * (https://platform.claude.com/docs/en/build-with-claude/structured-outputs).
- * The per-model facts are the `nativeOutputSchema` column of
- * `llm/anthropicModels.ts · ANTHROPIC_MODELS`.
- *
- * @example
- * ```ts
- * import { anthropic, nativeOutputSchemaFor } from 'agentfootprint/providers';
- *
- * nativeOutputSchemaFor(anthropic(), 'claude-haiku-4-5'); // true
- * nativeOutputSchemaFor(anthropic(), 'claude-opus-4-1');  // false
- * ```
- */
-import type { LLMProvider } from './types.js';
-/**
- * Whether `provider` puts a structured-output format on its wire for `model`.
- * Absence — or anything but `true` — means NO: a format that quietly vanishes
- * costs the guarantee it was asked for.
- */
-export declare function nativeOutputSchemaFor(provider: Pick<LLMProvider, 'carriesNativeOutputSchema' | 'supportsNativeOutputSchema'>, model: string): boolean;
-/**
- * UnsupportedNativeOutputError — a structured-output format for a model or
- * adapter that does not take one, refused by name BEFORE anything is sent.
- *
- * Asking again sends the same request: `retryable: false`, which `withRetry`'s
- * default policy honours; `withFallback` does not move the call to its other
- * side and `withCircuitBreaker` does not count it (`requestRefusal.ts`).
- *
- * @example
- * ```ts
- * import { UnsupportedNativeOutputError } from 'agentfootprint/providers';
- *
- * try {
- *   await agent.run('…');
- * } catch (err) {
- *   if (err instanceof UnsupportedNativeOutputError) console.error(err.provider, err.model);
- * }
- * ```
- */
-export declare class UnsupportedNativeOutputError extends Error {
-    /** The provider that answered for the model — `'anthropic'`, `'bedrock'`, … */
-    readonly provider: string;
-    /** The model the request named. */
-    readonly model: string;
-    /** Asking again cannot mend it — read by `withRetry`'s default predicate. */
-    readonly retryable = false;
-    constructor(args: {
-        readonly provider: string;
-        readonly model: string;
-    });
-}
-//# sourceMappingURL=nativeOutputSchema.d.ts.map

package/dist/types/adapters/nativeOutputSchema.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"nativeOutputSchema.d.ts","sourceRoot":"","sources":["../../../src/adapters/nativeOutputSchema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,2BAA2B,GAAG,4BAA4B,CAAC,EACvF,KAAK,EAAE,MAAM,GACZ,OAAO,CAMT;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,SAAS;gBAEf,IAAI,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE;CAWxE"}

package/dist/types/adapters/requestRefusal.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"requestRefusal.d.ts","sourceRoot":"","sources":["../../../src/adapters/requestRefusal.ts"],"names":[],"mappings":"AAMA,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAOxD"}