agentfootprint 9.5.1 → 9.7.0

package/dist/esm/adapters/llm/contextWindow.js

@@ -0,0 +1,277 @@
+/**
+ * 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 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 class ContextWindowExceededError extends Error {
+    code = ERR_CONTEXT_WINDOW_EXCEEDED;
+    /** Which adapter refused — `'openai'`, `'anthropic'`, `'bedrock'`, … */
+    provider;
+    /** The model's (or gateway's) ceiling in tokens, when the vendor said it. */
+    limitTokens;
+    /** What the request actually came to in tokens, when the vendor said it. */
+    actualTokens;
+    /** HTTP status, when there was one. Kept so retry policies still see a 4xx. */
+    status;
+    /** The provider's own error, unchanged. */
+    cause;
+    constructor(args) {
+        super(buildMessage(args));
+        this.name = 'ContextWindowExceededError';
+        this.provider = args.provider;
+        if (args.limitTokens !== undefined)
+            this.limitTokens = args.limitTokens;
+        if (args.actualTokens !== undefined)
+            this.actualTokens = args.actualTokens;
+        if (args.status !== undefined)
+            this.status = args.status;
+        if (args.cause !== undefined)
+            this.cause = args.cause;
+    }
+}
+/** `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 function isContextWindowExceeded(err) {
+    return (err instanceof ContextWindowExceededError ||
+        (err instanceof Error && err.code === ERR_CONTEXT_WINDOW_EXCEEDED));
+}
+// ─── Detection ───────────────────────────────────────────────────────
+/**
+ * The phrases that mean "your request was too big for the context window",
+ * as the four shipped wire vendors actually word them. Every one of these is
+ * unambiguous on its own — which is the bar for being on this list, because a
+ * pattern that also matches a rate limit or a `max_tokens` validation error
+ * would send callers to the wrong fix.
+ *
+ *   openai        This model's maximum context length is 8192 tokens. However,
+ *                 your messages resulted in 9000 tokens.
+ *   openai (code) context_length_exceeded
+ *   gateways      Input tokens exceed the configured limit of 272000 tokens.
+ *                 Your messages resulted in 879073 tokens.
+ *   anthropic     prompt is too long: 250000 tokens > 200000 maximum
+ *   anthropic     input length and `max_tokens` exceed context limit:
+ *                 195000 + 8192 > 200000
+ *   bedrock       Input is too long for requested model.
+ *   bedrock       (ValidationException carrying either anthropic phrase)
+ */
+const CONTEXT_PHRASES = [
+    /context_length_exceeded/i,
+    /maximum context length/i,
+    /prompt is too long/i,
+    /exceed(?:s)? context limit/i,
+    /input (?:is )?too long for (?:the )?requested model/i,
+    /input tokens exceed the configured limit/i,
+    // "input tokens" spelled out on purpose. A gateway saying "exceeds the
+    // maximum allowed number of tokens" with no side named could equally be an
+    // OUTPUT `max_tokens` cap, which has a different fix — and a pattern that
+    // cannot tell those apart sends callers to the wrong one.
+    /exceeds? the maximum (?:allowed )?(?:number of )?input tokens/i,
+];
+/** `"272,000"` → `272000`; anything unparseable → undefined. */
+function num(raw) {
+    if (raw === undefined)
+        return undefined;
+    const value = Number(raw.replace(/[,_\s]/g, ''));
+    return Number.isFinite(value) && value > 0 ? value : undefined;
+}
+/** Pull `{ limit, actual }` out of the vendor's sentence when it stated them. */
+function readNumbers(text) {
+    // anthropic: "prompt is too long: 250000 tokens > 200000 maximum"
+    const tooLong = /prompt is too long:\s*([\d,_]+)\s*tokens?\s*>\s*([\d,_]+)/i.exec(text);
+    if (tooLong) {
+        return { actualTokens: num(tooLong[1]), limitTokens: num(tooLong[2]) };
+    }
+    // anthropic / bedrock: "input length and `max_tokens` exceed context limit:
+    //                       195000 + 8192 > 200000"
+    const sum = /exceed(?:s)? context limit:\s*([\d,_]+)\s*\+\s*([\d,_]+)\s*>\s*([\d,_]+)/i.exec(text);
+    if (sum) {
+        const input = num(sum[1]);
+        const output = num(sum[2]);
+        return {
+            ...(input !== undefined && output !== undefined && { actualTokens: input + output }),
+            ...(num(sum[3]) !== undefined && { limitTokens: num(sum[3]) }),
+        };
+    }
+    const limit = num(/maximum context length is\s*([\d,_]+)/i.exec(text)?.[1]) ??
+        num(/configured limit of\s*([\d,_]+)/i.exec(text)?.[1]) ??
+        num(/limit of\s*([\d,_]+)\s*tokens/i.exec(text)?.[1]);
+    const actual = num(/resulted in\s*([\d,_]+)\s*tokens/i.exec(text)?.[1]) ??
+        num(/requested\s*([\d,_]+)\s*tokens/i.exec(text)?.[1]) ??
+        num(/you (?:sent|submitted|provided)\s*([\d,_]+)\s*tokens/i.exec(text)?.[1]);
+    return {
+        ...(limit !== undefined && { limitTokens: limit }),
+        ...(actual !== undefined && { actualTokens: actual }),
+    };
+}
+/** Every place a vendor hides its sentence, flattened into one string. */
+function textOf(err, extraText) {
+    const parts = [];
+    if (typeof extraText === 'string')
+        parts.push(extraText);
+    const seen = new Set();
+    let node = err;
+    for (let depth = 0; depth < 4 && node !== undefined && node !== null; depth++) {
+        if (seen.has(node))
+            break;
+        seen.add(node);
+        const record = node;
+        for (const value of [record.message, record.code, record.type, record.name]) {
+            if (typeof value === 'string')
+                parts.push(value);
+        }
+        node = record.error ?? record.cause;
+    }
+    return parts.join(' • ');
+}
+/** HTTP status from wherever the SDK put it. */
+function statusOf(err) {
+    const record = err;
+    for (const value of [
+        record?.status,
+        record?.statusCode,
+        record?.$metadata?.httpStatusCode,
+        record?.response?.status,
+    ]) {
+        if (typeof value === 'number' && Number.isFinite(value))
+            return value;
+    }
+    return undefined;
+}
+/**
+ * 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 function looksLikeContextWindowExceeded(err, bodyText) {
+    if (isContextWindowExceeded(err))
+        return true;
+    const text = textOf(err, bodyText);
+    return text.length > 0 && CONTEXT_PHRASES.some((pattern) => pattern.test(text));
+}
+/**
+ * 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 function asContextWindowExceeded(err, options) {
+    if (isContextWindowExceeded(err))
+        return err;
+    if (!looksLikeContextWindowExceeded(err, options.bodyText))
+        return undefined;
+    const text = textOf(err, options.bodyText);
+    const numbers = readNumbers(text);
+    // The status the SDK attached, else the one the adapter read off the
+    // response, else a leading `400` the vendor put in the message itself
+    // (several gateways do). Kept because retry policies classify on it, and a
+    // context overflow must never look retryable.
+    const status = statusOf(err) ?? options.status ?? num(/^\s*(4\d\d)\b/.exec(messageOf(err))?.[1]);
+    return new ContextWindowExceededError({
+        provider: options.provider,
+        providerMessage: messageOf(err) || options.bodyText || text,
+        ...numbers,
+        ...(status !== undefined && { status }),
+        ...(err instanceof Error && { cause: err }),
+    });
+}
+function messageOf(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (typeof err === 'string')
+        return err;
+    return '';
+}
+// ─── The message ─────────────────────────────────────────────────────
+function tokens(value) {
+    return value === undefined ? undefined : `${value.toLocaleString('en-US')} tokens`;
+}
+/**
+ * The teaching half. Three fixes, cheapest first, and the one thing about
+ * `.compaction()` that is not obvious until it fails: folding a span means
+ * SENDING that span to the summarizer, so compaction cannot rescue a single
+ * round that is already bigger than the window.
+ */
+function buildMessage(args) {
+    const sent = tokens(args.actualTokens);
+    const limit = tokens(args.limitTokens);
+    const size = sent && limit
+        ? ` — ${sent} sent against a limit of ${limit}`
+        : limit
+            ? ` — the limit is ${limit}`
+            : sent
+                ? ` — the request came to ${sent}`
+                : '';
+    return (`[${args.provider}] the request did not fit the context window${size}. ` +
+        `The provider refused it before the model saw it, so nothing was generated ` +
+        `and re-sending the same conversation fails the same way.\n` +
+        `  Fix 1 — cap oversized TOOL RESULTS where they are produced. One raw ` +
+        `database dump returned to the model is the usual whole overrun: return a ` +
+        `summary plus an id the model can ask about, not every row.\n` +
+        `  Fix 2 — .window(slidingWindow({ keepRecentTurns: 2 })) drops older ` +
+        `rounds before the request is assembled, so the conversation stops growing ` +
+        `without bound.\n` +
+        `  Fix 3 — .compaction() keeps a LONG conversation small, but it cannot ` +
+        `fold a span that is already bigger than the window: the summarizer call ` +
+        `sends that span, so it fails exactly as this call did. Fix the oversized ` +
+        `round first, then compact.\n` +
+        `  Provider said: ${args.providerMessage}`);
+}
+//# sourceMappingURL=contextWindow.js.map

package/dist/esm/adapters/llm/contextWindow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextWindow.js","sourceRoot":"","sources":["../../../../src/adapters/llm/contextWindow.ts"],"names":[],"mappings":"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"}

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

@@ -584,3 +584,90 @@ export interface PricingTable {
     /** USD per ONE token for the given model+kind. */
     pricePerToken(model: string, kind: TokenKind): number;
 }
+/**
+ * A service that runs code in an isolated session — a managed code
+ * interpreter, a container pool, a subprocess.
+ *
+ * **The shape is Start → Execute ×N → Stop**, because that is what every real
+ * one is, and the middle is the part a framework has to make possible. Paying
+ * session start-up on every call is the honest cheap version; holding the
+ * session in a module-level map is the fast version that hands one live sandbox
+ * to whoever calls next. `ctx.onTeardown` + {@link ToolExecutionContext.runId}
+ * are what let a tool do neither.
+ *
+ * ── Why this port exists at all: "summarize prose, compute data" ────────────
+ * A tool that returns 40MB of rows does not need a bigger context window; it
+ * needs to not put the rows in one. The motivating failure is a real production
+ * request of 879,073 tokens — a tool result pasted straight into the prompt.
+ * With a code runner, the model writes the aggregation, the RUNNER holds the
+ * data, and what comes back is the answer. Prose gets summarized; data gets
+ * computed. `CodeResult.truncated` exists so the second half of that promise
+ * cannot quietly break.
+ *
+ * Implement it for your own backend; ship it to `codeRunnerTool({ runner })`.
+ */
+export interface CodeRunner {
+    /** Stable id — reported on every `agentfootprint.tools.session_*` event so a
+     *  row names its backend, not just its tool. */
+    readonly id: string;
+    /**
+     * Open a session.
+     *
+     * `key` is the ISOLATION key the caller derived (see `toolSessionKey`). An
+     * adapter may use it to name the remote session; it must never widen it.
+     */
+    start(req: {
+        readonly key: string;
+        readonly language?: string;
+        readonly signal?: AbortSignal;
+    }): Promise<CodeSession>;
+}
+/** One live session. `stop()` is idempotent and tolerates "already gone". */
+export interface CodeSession {
+    /** The backend's own id for this session, when it has one. */
+    readonly id: string;
+    execute(req: {
+        readonly code: string;
+        readonly language?: string;
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<CodeResult>;
+    /**
+     * Release the session.
+     *
+     * Must tolerate a session the far side already reaped — an idle timeout is
+     * the reality on every managed backend, and a `Stop` on a dead session is a
+     * no-op, not an error.
+     */
+    stop(): Promise<void>;
+}
+/** What one execution produced. */
+export interface CodeResult {
+    /** Did the code run to completion without an error exit? */
+    readonly ok: boolean;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode?: number;
+    /** Files the run produced, described rather than inlined — the whole point is
+     *  that big data does not enter the window. */
+    readonly artifacts?: readonly {
+        readonly name: string;
+        readonly bytes: number;
+        readonly uri?: string;
+    }[];
+    /**
+     * Present IFF output was cut, and then it says by how much.
+     *
+     * Load-bearing, not politeness. A runner exists so big data is computed
+     * outside the context window instead of pasted into it; a runner that
+     * quietly slices its own output to fit is the same bug wearing a different
+     * hat, and the model would go on to reason over a truncated table it was
+     * never told was truncated. An unstated slice is a silent success.
+     */
+    readonly truncated?: {
+        readonly stdout?: boolean;
+        readonly stderr?: boolean;
+        /** The pre-truncation length, in characters, of whichever stream was cut. */
+        readonly ofChars?: number;
+    };
+}

package/dist/esm/core/Agent.d.ts

@@ -286,6 +286,9 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      *  default is derived from a runId, and storing that would pin a whole
      *  conversation to the id of the one run that started it. */
     private lastRunIdentity?;
+    /** How long ONE tool teardown may take before the runner stops waiting.
+     *  See `AgentOptions.toolTeardownTimeoutMs`. */
+    private readonly toolTeardownTimeoutMs;
     /** The run in flight, by id — the whole of the one-turn-at-a-time guard.
      *  Set before the executor is built and cleared in `finally`, so a run that
      *  throws does not leave the agent permanently refusing. */
@@ -611,6 +614,29 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      */
     private installCheckpointTracker;
     resume(checkpoint: FlowchartCheckpoint, input?: unknown, options?: AgentRunOptions): Promise<AgentOutput | RunnerPauseOutcome>;
+    /**
+     * Fire `'run'`-scoped tool teardown — IF this run really ended.
+     *
+     * **Not on `finally`, and that is the whole point.** `finally` runs on every
+     * exit including a pause, and a pause exits TWO ways: a returned
+     * `RunnerPauseOutcome` and a thrown `PauseSignal`. A check-in on a
+     * code-interpreter call pauses the run so a person can approve the code —
+     * tearing the sandbox down there destroys the exact state the resume needs,
+     * and it fails QUIETLY, as a resumed run that "just re-ran everything".
+     * Both shapes are discriminated here and both are skipped.
+     *
+     * An error IS a terminal: the run is over, nobody is coming back, and a
+     * sandbox held by a run that crashed is the clearest kind of leak. Only a
+     * pause survives.
+     *
+     * Fired for the TURN, not for `currentRunContext.runId` — `resume()` mints a
+     * fresh run id, so a pause and its resume are one turn across two runs, and
+     * filtering on the id would leave everything a paused turn opened alive
+     * forever. See `ToolSessionTier.fireRun`.
+     *
+     * @param outcome what `run()`/`resume()` is about to return, or about to throw.
+     */
+    private endRunToolSessions;
     /**
      * The conversation this agent's LAST completed run leaves behind, packed as
      * the same `AgentRunCheckpoint` that `resumeOnError(...)` accepts. Store it,
@@ -761,6 +787,45 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
      * An open pick ACTIVATES but never moves the cursor — see the tool-calls gate.
      * Computed once per chart build; the injection list is fixed at construction.
      */
+    /**
+     * The identity facts this run hands `tool.execute` (9.7.0).
+     *
+     * Read through an ACCESSOR from the chart (see `ToolCallsHandlerDeps.currentRun`)
+     * because the chart is built once and this changes every run.
+     *
+     * `identity` is `lastRunIdentity` — what the CALLER passed — and deliberately
+     * NOT `scope.runIdentity`, which is always populated and defaults to
+     * `{ conversationId: '<runId>' }`. Handing a tool a synthesized conversation
+     * as "the identity" would let it key an isolated session on a fiction, and
+     * would make "absent" unrepresentable at exactly the layer that most needs to
+     * see it.
+     */
+    private toolRunFacts;
+    /**
+     * The teardown tier, built on FIRST registration.
+     *
+     * An agent whose tools never hold a session never allocates one, and its
+     * terminals stay a single `undefined` check.
+     */
+    private toolSessions;
+    /**
+     * Turn one TEARDOWN report into a typed `agentfootprint.tools.session_*` event.
+     *
+     * Only the two closing events come through here. A start and a reuse happen
+     * inside `tool.execute`, where the dispatch loop still holds the scope, so
+     * those ride the ordinary emit channel and carry the stage they really
+     * happened in. These two fire after the run's last stage committed, and this
+     * is the one place that has to answer "from where?" without a stage to point
+     * at.
+     *
+     * **Built with `buildEventMeta`, never `minimalMeta()`.** `minimalMeta()`
+     * hardcodes `runId: 'consumer-scope'`, and a teardown event stamped that way
+     * cannot be joined to the run that OPENED the session — the exact
+     * unjoinability 9.4.0 spent a release fixing for credential events. So the
+     * meta comes from `currentRunContext`, with a STATED pseudo-stage, the same
+     * move as the `'<stageId>#paused'` stamp at the pause boundary.
+     */
+    private emitToolSessionReport;
     private openSkillIds;
     /**
      * The per-iteration `read_skill` offer builder — or `undefined` to leave the tool