agentfootprint 9.5.1 → 9.7.0

package/dist/adapters/llm/contextWindow.js

@@ -0,0 +1,284 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asContextWindowExceeded = exports.looksLikeContextWindowExceeded = exports.isContextWindowExceeded = exports.ContextWindowExceededError = exports.ERR_CONTEXT_WINDOW_EXCEEDED = void 0;
+/** Discriminator carried on the error — stable across releases. */
+exports.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 }))
+ *   }
+ * }
+ * ```
+ */
+class ContextWindowExceededError extends Error {
+    code = exports.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;
+    }
+}
+exports.ContextWindowExceededError = ContextWindowExceededError;
+/** `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. */
+function isContextWindowExceeded(err) {
+    return (err instanceof ContextWindowExceededError ||
+        (err instanceof Error && err.code === exports.ERR_CONTEXT_WINDOW_EXCEEDED));
+}
+exports.isContextWindowExceeded = isContextWindowExceeded;
+// ─── 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
+ */
+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));
+}
+exports.looksLikeContextWindowExceeded = looksLikeContextWindowExceeded;
+/**
+ * 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.
+ */
+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 }),
+    });
+}
+exports.asContextWindowExceeded = asContextWindowExceeded;
+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/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/core/Agent.js

@@ -44,6 +44,19 @@ const ResilienceRecorder_js_1 = require("../recorders/core/ResilienceRecorder.js
 const CheckInRecorder_js_1 = require("../recorders/core/CheckInRecorder.js");
 const CompactionMeter_js_1 = require("../recorders/core/CompactionMeter.js");
 const durabilityBarrier_js_1 = require("./durabilityBarrier.js");
+const toolSessions_js_1 = require("./toolSessions.js");
+const eventMeta_js_1 = require("../bridge/eventMeta.js");
+/**
+ * The pseudo-stage a tool-teardown event is stamped with.
+ *
+ * `session_closed` and `session_close_failed` fire after the run's last stage
+ * has committed — there is no runtimeStageId to inherit, and inventing one that
+ * looked like a real stage would put a fictitious node in every consumer's step
+ * strip. This says plainly where it came from, the way `'<stageId>#paused'`
+ * does at the pause boundary. Their two siblings, `session_started` and
+ * `session_reused`, happen inside a real stage and carry its real id.
+ */
+const TOOL_TEARDOWN_STAGE_ID = 'tool-teardown#0';
 const EmitBridge_js_1 = require("../recorders/core/EmitBridge.js");
 const window_js_1 = require("./agent/stages/window.js");
 const deliver_js_1 = require("./agent/stages/deliver.js");
@@ -295,6 +308,9 @@ class Agent extends RunnerBase_js_1.RunnerBase {
      *  default is derived from a runId, and storing that would pin a whole
      *  conversation to the id of the one run that started it. */
     lastRunIdentity;
+    /** How long ONE tool teardown may take before the runner stops waiting.
+     *  See `AgentOptions.toolTeardownTimeoutMs`. */
+    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. */
@@ -476,6 +492,8 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // 8.6.0 — default `'pause'`: consent is work waiting on a person, and the
         // model is the one party that cannot click a link.
         this.onAuthorizationRequired = opts.onAuthorizationRequired ?? 'pause';
+        // 9.7.0 — teardown is on the SIGTERM path, so it is bounded by default.
+        this.toolTeardownTimeoutMs = opts.toolTeardownTimeoutMs ?? toolSessions_js_1.TOOL_TEARDOWN_TIMEOUT_MS;
         if (reliabilityConfig !== undefined)
             this.reliabilityConfig = reliabilityConfig;
         // v2.14 — Resolve thinking handler. Three states:
@@ -793,9 +811,12 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             if (typeof finalized === 'string')
                 this.lastRunAnswer = finalized;
             this.recordPendingQuestion(finalized);
+            await this.endRunToolSessions(finalized);
             return finalized;
         }
         catch (cause) {
+            // A THROWN pause is still a pause — see `endRunToolSessions`.
+            await this.endRunToolSessions(cause);
             // Wrap recoverable errors with the last-known-good checkpoint.
             // Don't wrap intentional terminal signals — let them propagate as
             // their typed shapes so callers can `instanceof` them:
@@ -1108,12 +1129,48 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // The question this resume answered is settled; a resume that paused
             // AGAIN has asked a new one, and that one is outstanding from here.
             this.recordPendingQuestion(finalized);
+            await this.endRunToolSessions(finalized);
             return finalized;
         }
+        catch (cause) {
+            await this.endRunToolSessions(cause);
+            throw cause;
+        }
         finally {
             this.inFlightRunId = undefined;
         }
     }
+    /**
+     * 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.
+     */
+    async endRunToolSessions(outcome) {
+        if (!this.toolSessionTier)
+            return;
+        if ((0, pause_js_1.isPaused)(outcome))
+            return;
+        if (outcome instanceof Error && outcome.name === 'PauseSignal')
+            return;
+        await this.toolSessionTier.fireRun();
+    }
     /**
      * The conversation this agent's LAST completed run leaves behind, packed as
      * the same `AgentRunCheckpoint` that `resumeOnError(...)` accepts. Store it,
@@ -1333,6 +1390,74 @@ class Agent extends RunnerBase_js_1.RunnerBase {
      * 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.
+     */
+    toolRunFacts() {
+        return {
+            runId: this.currentRunContext.runId,
+            ...(this.currentRunContext.sessionId !== undefined && {
+                sessionId: this.currentRunContext.sessionId,
+            }),
+            ...(this.lastRunIdentity !== undefined && { identity: this.lastRunIdentity }),
+        };
+    }
+    /**
+     * 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.
+     */
+    toolSessions() {
+        if (!this.toolSessionTier) {
+            this.toolSessionTier = new toolSessions_js_1.ToolSessionTier({
+                timeoutMs: this.toolTeardownTimeoutMs,
+                report: (report) => this.emitToolSessionReport(report),
+            });
+        }
+        return this.toolSessionTier;
+    }
+    /**
+     * 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.
+     */
+    emitToolSessionReport(report) {
+        const type = report.kind === 'closed'
+            ? 'agentfootprint.tools.session_closed'
+            : 'agentfootprint.tools.session_close_failed';
+        const dispatcher = this.getDispatcher();
+        if (!dispatcher.hasListenersFor(type))
+            return;
+        const { kind: _kind, ...payload } = report;
+        dispatcher.dispatch({
+            type,
+            payload,
+            meta: (0, eventMeta_js_1.buildEventMeta)({ runtimeStageId: TOOL_TEARDOWN_STAGE_ID }, this.currentRunContext),
+        });
+    }
     openSkillIds() {
         return this.injections
             .filter((i) => i.flavor === 'skill' &&
@@ -1856,6 +1981,13 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // toolSchemas is finalized further down; pass a getter that reads
         // the eventual const at stage-execution time.
         let toolSchemasResolved = [];
+        // The stores the conversation itself is kept in — the durable anchor seed
+        // resolves the turn number against. Deduplicated (several memories over
+        // one store is the common shape) and reference-stable, so the scan runs
+        // once per store per run.
+        const conversationStores = Array.from(new Set(this.memories
+            .filter((m) => m.write !== undefined && m.corpus === undefined && m.store !== undefined)
+            .map((m) => m.store)));
         const seed = (0, seed_js_1.buildSeedStage)({
             maxIterations,
             cachingDisabled,
@@ -1874,6 +2006,12 @@ class Agent extends RunnerBase_js_1.RunnerBase {
                 return f;
             },
             getCurrentRunId: () => this.currentRunContext?.runId,
+            // WHICH TURN THIS IS (9.6.0). Only memories that WRITE the conversation
+            // are consulted: they are the ones whose entry ids are turn-stamped, and
+            // a corpus (`.rag(...)`, which reads under its own namespace) has no
+            // turns at all. Empty list → seed stays synchronous and makes no store
+            // call, so an agent without memory is unchanged.
+            ...(conversationStores.length > 0 && { conversationStores }),
             // The `'input'` half of the message chain, run BEFORE `userMessage` and
             // `history` are committed — see SeedStageDeps.messageMiddleware.
             ...(this.messageMiddleware.length > 0 && { messageMiddleware: this.messageMiddleware }),
@@ -2038,6 +2176,13 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             // later, so a direct field read here would be stale forever. Answers
             // `undefined` — no await, no microtask — until one is installed.
             awaitDurable: () => (0, durabilityBarrier_js_1.pendingDurableWrite)(this),
+            // 9.7.0 — run/session identity and the teardown registrar. BOTH are
+            // accessors for the reason `awaitDurable` is one: the chart is built once
+            // at construction, and a captured value would be run #1's forever. The
+            // tier one is lazy on top of that — an agent whose tools hold no sessions
+            // never allocates it.
+            currentRun: () => this.toolRunFacts(),
+            toolSessions: () => this.toolSessions(),
             // 8.6.0 — what a run does when a declared credential needs 3LO consent.
             onAuthorizationRequired: this.onAuthorizationRequired,
             // The `'tell-model'` consent record travels OFF tracked state (a tracked