@aragon-agent/core 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -5,6 +5,50 @@ All notable changes to `@aragon-agent/core` are documented here. Entries at
 — those releases really were published under that name, so they are left as they
 were written.
 
+## Unreleased
+
+### Added
+
+- **`llm/output-limits.ts` — one authority for the output-token cap.**
+  `DEFAULT_MAX_OUTPUT_TOKENS` (64000), `MIN_MAX_OUTPUT_TOKENS`,
+  `SAFE_FALLBACK_MAX_OUTPUT_TOKENS`, `ABSOLUTE_MAX_OUTPUT_TOKENS`,
+  `THINKING_HEADROOM_TOKENS`, `CONTEXT_SAFETY_MARGIN_TOKENS`,
+  `resolveOutputTokens`, `staticCeilingFor`, `learnModelCeiling`,
+  `getLearnedCeiling`, `clearLearnedCeilings` and `estimatePromptTokens` are all
+  exported from the root barrel. The three provider adapters no longer carry
+  private copies of the default; they resolve through this module.
+
+  The resolver treats the default as an *ambition* and the model's real ceiling
+  as the law, ranking four sources — learned-from-error > discovery > a static
+  per-model table > the product default — so an over-large cap is clamped instead
+  of becoming an HTTP 400 that ends the run. It also reconciles Anthropic's
+  `max_tokens > thinking.budget_tokens` invariant, which `--thinking xhigh` broke
+  on every request.
+
+- **`llm/output-limit-recovery.ts` — one-shot self-healing.**
+  `classifyOutputLimitFailure`, `sendWithOutputLimitRecovery`, `learnTokenField`,
+  `getLearnedTokenField` and `clearLearnedTokenFields`. A 400 that names an
+  output-limit problem is repaired and re-sent **once** — never a loop — and what
+  was learned is remembered for the rest of the process. A 2xx is returned with
+  its body untouched, so streaming is unaffected. OpenAI's reasoning family,
+  which rejects `max_tokens` in favour of `max_completion_tokens`, is handled by
+  a heuristic plus this memo.
+
+- **`LLMRequest.modelLimits?: { maxOutputTokens?, contextWindow? }`** — optional
+  caller-supplied metadata. Supplying `contextWindow` enables the
+  `max_tokens + prompt <= context` guard on OpenAI. Every existing caller
+  compiles unchanged.
+
+### Changed
+
+- `ModelRegistry.buildRuntimeModel` defaults `maxOutputTokens` to
+  `DEFAULT_MAX_OUTPUT_TOKENS` rather than a private `16384`, the built-in
+  Anthropic catalog entries carry their real ceilings, and `registerDefaults` /
+  `discoverModels` seed the shared ceiling cache. `listModels` on the Anthropic
+  and OpenAI adapters now maps through the static table instead of asserting the
+  product default for every model — neither API reports an output ceiling, and
+  claiming otherwise outranked the correct value for every small model.
+
 ## 0.3.0
 
 ### Added

package/dist/index.d.ts

@@ -9,6 +9,10 @@ export type { ContentPart, TextContentPart, ImageContentPart, ContentBlock, Text
 export { THINKING_BUDGET } from './llm/types.js';
 export type { LLMProvider, LLMRequest, LLMErrorType, } from './llm/provider.js';
 export { LLMError, classifyHttpError, wrapFetchError, } from './llm/provider.js';
+export { DEFAULT_MAX_OUTPUT_TOKENS, MIN_MAX_OUTPUT_TOKENS, SAFE_FALLBACK_MAX_OUTPUT_TOKENS, ABSOLUTE_MAX_OUTPUT_TOKENS, THINKING_HEADROOM_TOKENS, CONTEXT_SAFETY_MARGIN_TOKENS, resolveOutputTokens, staticCeilingFor, learnModelCeiling, getLearnedCeiling, clearLearnedCeilings, estimatePromptTokens, } from './llm/output-limits.js';
+export type { OutputLimitInput, OutputLimitResolution, CeilingSource, } from './llm/output-limits.js';
+export { classifyOutputLimitFailure, sendWithOutputLimitRecovery, learnTokenField, getLearnedTokenField, clearLearnedTokenFields, } from './llm/output-limit-recovery.js';
+export type { OutputLimitFailure, RecoveryAttempt, RecoveryOptions, TokenField, } from './llm/output-limit-recovery.js';
 export type { SSEEvent } from './llm/stream-utils.js';
 export { parseSSEStream, consumeStream, } from './llm/stream-utils.js';
 export { ProviderRegistry, initProviders, getProviderRegistry, setProviderRegistry, streamLLM, completeLLM, } from './llm/providers/index.js';

package/dist/index.js

@@ -7,6 +7,12 @@
  */
 export { THINKING_BUDGET } from './llm/types.js';
 export { LLMError, classifyHttpError, wrapFetchError, } from './llm/provider.js';
+// ---------------------------------------------------------------------------
+// Output-token limits — the authority for "how many tokens may this model
+// produce". Every adapter resolves through here; nothing else spells 64000.
+// ---------------------------------------------------------------------------
+export { DEFAULT_MAX_OUTPUT_TOKENS, MIN_MAX_OUTPUT_TOKENS, SAFE_FALLBACK_MAX_OUTPUT_TOKENS, ABSOLUTE_MAX_OUTPUT_TOKENS, THINKING_HEADROOM_TOKENS, CONTEXT_SAFETY_MARGIN_TOKENS, resolveOutputTokens, staticCeilingFor, learnModelCeiling, getLearnedCeiling, clearLearnedCeilings, estimatePromptTokens, } from './llm/output-limits.js';
+export { classifyOutputLimitFailure, sendWithOutputLimitRecovery, learnTokenField, getLearnedTokenField, clearLearnedTokenFields, } from './llm/output-limit-recovery.js';
 export { parseSSEStream, consumeStream, } from './llm/stream-utils.js';
 // ---------------------------------------------------------------------------
 // Provider registry

package/dist/llm/model-registry.js

@@ -6,6 +6,7 @@
  * discovery logic mirrors `server/services/model-detection.ts`, but uses the
  * new LLMProvider interface for API queries.
  */
+import { DEFAULT_MAX_OUTPUT_TOKENS, learnModelCeiling } from './output-limits.js';
 /** Cache TTL: 5 minutes. */
 const CACHE_TTL_MS = 5 * 60 * 1000;
 // ---------------------------------------------------------------------------
@@ -56,6 +57,26 @@ export class ModelRegistry {
             return [];
         try {
             const models = await provider.listModels(apiKey, baseUrl);
+            // Discovery outranks the static table (§4.1.2). The adapters that can
+            // report a REAL ceiling already learn it themselves; this feeds anything
+            // reached through the registry, including third-party providers.
+            //
+            // A ceiling that is EXACTLY the product default is skipped, because that
+            // is precisely what `listModels` returns when it has nothing to report —
+            // neither the Anthropic nor the OpenAI models endpoint carries an output
+            // ceiling, so both fall back to it (see the notes in their adapters).
+            // Learning it here at `'discovery'` rank would launder that placeholder
+            // into an assertion that outranks the static table, and would collapse the
+            // distinction `staticCeilingFor`'s `undefined` return exists to keep:
+            // "unknown" would become "capped at 64000", silently clamping an explicit
+            // larger request the user is entitled to make against a proxy. Skipping it
+            // costs nothing — AUTO tops out at the default anyway, and a genuinely
+            // over-large request is repaired by `output-limit-recovery.ts`.
+            for (const model of models) {
+                if (model.maxOutputTokens === DEFAULT_MAX_OUTPUT_TOKENS)
+                    continue;
+                learnModelCeiling(providerId, model.id, model.maxOutputTokens, 'discovery');
+            }
             this.discoveryCache.set(cacheKey, { models, timestamp: Date.now() });
             return models;
         }
@@ -87,7 +108,10 @@ export class ModelRegistry {
             name: modelId,
             provider: providerId,
             contextWindow: 128_000,
-            maxOutputTokens: 16_384,
+            // The PRODUCT DEFAULT, not a private guess. An unknown model that claims a
+            // ceiling nothing else agrees with is how one part of the system clamps
+            // output the rest of it never asked for.
+            maxOutputTokens: DEFAULT_MAX_OUTPUT_TOKENS,
             supportsThinking: false,
             supportsTools: true,
             supportsImages: false,
@@ -108,10 +132,25 @@ export class ModelRegistry {
         this.builtinModels.set('google', GOOGLE_MODELS);
         this.builtinModels.set('xai', XAI_MODELS);
         this.builtinModels.set('groq', GROQ_MODELS);
+        // Seed the shared ceiling cache at the LOWEST rank, so discovery and
+        // recovery both override it. Without this the catalog's per-model knowledge
+        // is never consulted when a request body is built — the table is read by the
+        // model picker and by nothing else.
+        for (const models of this.builtinModels.values()) {
+            for (const model of models) {
+                learnModelCeiling(model.provider, model.id, model.maxOutputTokens, 'catalog');
+            }
+        }
     }
 }
 // ---------------------------------------------------------------------------
 // Builtin model lists
+//
+// `maxOutputTokens` here MUST agree with `CEILING_TABLE` in `output-limits.ts`.
+// The two are consulted by different code paths — this one by the model picker,
+// that one when a request body is built — and a disagreement shows up as
+// "the picker says 64000 but my answers stop at 8192", which is unattributable
+// from a transcript.
 // ---------------------------------------------------------------------------
 const ANTHROPIC_MODELS = [
     {
@@ -119,7 +158,7 @@ const ANTHROPIC_MODELS = [
         name: 'Claude Sonnet 4.5',
         provider: 'anthropic',
         contextWindow: 200_000,
-        maxOutputTokens: 8192,
+        maxOutputTokens: 64_000,
         supportsThinking: true,
         supportsTools: true,
         supportsImages: true,
@@ -130,7 +169,7 @@ const ANTHROPIC_MODELS = [
         name: 'Claude Opus 4.6',
         provider: 'anthropic',
         contextWindow: 200_000,
-        maxOutputTokens: 32_000,
+        maxOutputTokens: 64_000,
         supportsThinking: true,
         supportsTools: true,
         supportsImages: true,
@@ -141,7 +180,7 @@ const ANTHROPIC_MODELS = [
         name: 'Claude Haiku 4.5',
         provider: 'anthropic',
         contextWindow: 200_000,
-        maxOutputTokens: 8192,
+        maxOutputTokens: 64_000,
         supportsThinking: true,
         supportsTools: true,
         supportsImages: true,

package/dist/llm/output-limit-recovery.d.ts

@@ -0,0 +1,86 @@
+/**
+ * One-shot self-healing for a request the provider rejected because of the
+ * output-token cap.
+ *
+ * The static table in `output-limits.ts` makes the common case correct without a
+ * round trip; this module makes the UNCOMMON case survivable — a proxy, a model
+ * that shipped last week, a dialect the heuristic guessed wrong. It reads the
+ * true ceiling out of the provider's own error text, repairs the request, sends
+ * it EXACTLY ONCE more, and teaches `output-limits.ts` what it learned so the
+ * rest of the process gets it right on the first try.
+ *
+ * TWO CONTRACTS THAT BREAK LOUDLY IF IGNORED:
+ *
+ *   1. A `Response` body can be read once. `RecoveryAttempt.bodyText` carries the
+ *      already-consumed error body; callers MUST pass it on rather than calling
+ *      `response.text()` again, which throws `TypeError: Body is unusable`. On
+ *      the success path the body is NEVER touched — a streaming response has to
+ *      reach the SSE parser intact.
+ *
+ *   2. Exactly one retry, structurally: `send` is called at most twice and there
+ *      is no loop construct in this file. A recovery loop doubles every user's
+ *      bill.
+ *
+ * TEST HYGIENE: `learnTokenField` writes a module-level map with process
+ * lifetime. Any test that memoizes a dialect MUST call `clearLearnedTokenFields()`
+ * from `afterEach`.
+ */
+export type OutputLimitFailure = {
+    kind: 'exceeds_ceiling';
+    ceiling?: number;
+} | {
+    kind: 'context_sum';
+    contextWindow?: number;
+    promptTokens?: number;
+} | {
+    kind: 'unsupported_field';
+    expected: 'max_tokens' | 'max_completion_tokens';
+} | {
+    kind: 'thinking_conflict';
+};
+/** The wire name of the field carrying the cap. Google's is a dotted path. */
+export type TokenField = 'max_tokens' | 'max_completion_tokens' | 'generationConfig.maxOutputTokens';
+/**
+ * Decide whether a provider rejection was about the output-token cap.
+ *
+ * ONLY `status === 400` is inspected — every other status is somebody else's
+ * problem and repairing the cap would just spend a second round trip to fail the
+ * same way.
+ */
+export declare function classifyOutputLimitFailure(providerId: string, status: number, body: string): OutputLimitFailure | undefined;
+type OpenAiTokenField = 'max_tokens' | 'max_completion_tokens';
+/**
+ * Remember which parameter name this `provider:model` actually accepts.
+ *
+ * The heuristic in `openai.ts` is only the first guess; a proxy fronting an
+ * o-series model under a `gpt-` alias disagrees with it. One round trip corrects
+ * that, permanently for the life of the process.
+ */
+export declare function learnTokenField(providerId: string, modelId: string, field: OpenAiTokenField): void;
+export declare function getLearnedTokenField(providerId: string, modelId: string): OpenAiTokenField | undefined;
+/** Test hook. MUST be called from `afterEach` in every test that memoizes a dialect. */
+export declare function clearLearnedTokenFields(): void;
+export interface RecoveryAttempt {
+    response: Response;
+    /** The 400 body, ALREADY CONSUMED. Callers must not call `response.text()`. */
+    bodyText: string;
+    adjustment?: {
+        from: number;
+        to: number;
+        reason: OutputLimitFailure['kind'];
+    };
+}
+export interface RecoveryOptions {
+    providerId: string;
+    modelId: string;
+    body: Record<string, unknown>;
+    tokenField: TokenField;
+    send: (body: Record<string, unknown>) => Promise<Response>;
+}
+/**
+ * Send a request, and on an output-limit 400 repair it and send it once more.
+ *
+ * The hot path is untouched: a 2xx returns immediately with an unread body.
+ */
+export declare function sendWithOutputLimitRecovery(opts: RecoveryOptions): Promise<RecoveryAttempt>;
+export {};

package/dist/llm/output-limit-recovery.js

@@ -0,0 +1,263 @@
+/**
+ * One-shot self-healing for a request the provider rejected because of the
+ * output-token cap.
+ *
+ * The static table in `output-limits.ts` makes the common case correct without a
+ * round trip; this module makes the UNCOMMON case survivable — a proxy, a model
+ * that shipped last week, a dialect the heuristic guessed wrong. It reads the
+ * true ceiling out of the provider's own error text, repairs the request, sends
+ * it EXACTLY ONCE more, and teaches `output-limits.ts` what it learned so the
+ * rest of the process gets it right on the first try.
+ *
+ * TWO CONTRACTS THAT BREAK LOUDLY IF IGNORED:
+ *
+ *   1. A `Response` body can be read once. `RecoveryAttempt.bodyText` carries the
+ *      already-consumed error body; callers MUST pass it on rather than calling
+ *      `response.text()` again, which throws `TypeError: Body is unusable`. On
+ *      the success path the body is NEVER touched — a streaming response has to
+ *      reach the SSE parser intact.
+ *
+ *   2. Exactly one retry, structurally: `send` is called at most twice and there
+ *      is no loop construct in this file. A recovery loop doubles every user's
+ *      bill.
+ *
+ * TEST HYGIENE: `learnTokenField` writes a module-level map with process
+ * lifetime. Any test that memoizes a dialect MUST call `clearLearnedTokenFields()`
+ * from `afterEach`.
+ */
+import { CONTEXT_SAFETY_MARGIN_TOKENS, MIN_MAX_OUTPUT_TOKENS, MIN_THINKING_BUDGET_TOKENS, SAFE_FALLBACK_MAX_OUTPUT_TOKENS, THINKING_HEADROOM_TOKENS, learnModelCeiling, normalizeModelId, } from './output-limits.js';
+const UNSUPPORTED_FIELD_PATTERNS = [
+    /unsupported parameter:?\s*'?max_tokens'?/i,
+    /use\s+'?max_completion_tokens'?/i,
+];
+const THINKING_CONFLICT_PATTERN = /max_tokens must be greater than (?:thinking\.)?budget_tokens/i;
+/** Numeric ceiling captures, in priority order; group 1 is the real ceiling. */
+const CEILING_PATTERNS = [
+    /max_tokens:\s*\d+\s*>\s*(\d+),\s*which is the maximum/i,
+    /supports at most (\d+) completion tokens/i,
+    /exceeds the model limit of (\d+)/i,
+];
+const CONTEXT_SUM_PATTERN = /maximum context length is (\d+) tokens.*?you requested \d+ tokens \((\d+) in the messages/is;
+/** Last resort: the provider named the field but gave us no number to work with. */
+const GENERIC_LIMIT_PATTERN = /max(?:imum)?[_ ](?:output|completion)[_ ]tokens/i;
+function parseCount(raw) {
+    if (raw === undefined)
+        return undefined;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+/**
+ * Decide whether a provider rejection was about the output-token cap.
+ *
+ * ONLY `status === 400` is inspected — every other status is somebody else's
+ * problem and repairing the cap would just spend a second round trip to fail the
+ * same way.
+ */
+export function classifyOutputLimitFailure(providerId, status, body) {
+    if (status !== 400 || typeof body !== 'string' || body.length === 0)
+        return undefined;
+    void providerId; // the patterns are provider-specific but mutually exclusive
+    if (UNSUPPORTED_FIELD_PATTERNS.some((p) => p.test(body))) {
+        return { kind: 'unsupported_field', expected: 'max_completion_tokens' };
+    }
+    if (THINKING_CONFLICT_PATTERN.test(body))
+        return { kind: 'thinking_conflict' };
+    for (const pattern of CEILING_PATTERNS) {
+        const match = pattern.exec(body);
+        if (match) {
+            const ceiling = parseCount(match[1]);
+            return ceiling === undefined ? { kind: 'exceeds_ceiling' } : { kind: 'exceeds_ceiling', ceiling };
+        }
+    }
+    const ctx = CONTEXT_SUM_PATTERN.exec(body);
+    if (ctx) {
+        return {
+            kind: 'context_sum',
+            ...(parseCount(ctx[1]) !== undefined ? { contextWindow: parseCount(ctx[1]) } : {}),
+            ...(parseCount(ctx[2]) !== undefined ? { promptTokens: parseCount(ctx[2]) } : {}),
+        };
+    }
+    if (GENERIC_LIMIT_PATTERN.test(body))
+        return { kind: 'exceeds_ceiling' };
+    return undefined;
+}
+const learnedTokenFields = new Map();
+function fieldKey(providerId, modelId) {
+    return `${String(providerId ?? '').toLowerCase()}:${normalizeModelId(modelId)}`;
+}
+/**
+ * Remember which parameter name this `provider:model` actually accepts.
+ *
+ * The heuristic in `openai.ts` is only the first guess; a proxy fronting an
+ * o-series model under a `gpt-` alias disagrees with it. One round trip corrects
+ * that, permanently for the life of the process.
+ */
+export function learnTokenField(providerId, modelId, field) {
+    learnedTokenFields.set(fieldKey(providerId, modelId), field);
+}
+export function getLearnedTokenField(providerId, modelId) {
+    return learnedTokenFields.get(fieldKey(providerId, modelId));
+}
+/** Test hook. MUST be called from `afterEach` in every test that memoizes a dialect. */
+export function clearLearnedTokenFields() {
+    learnedTokenFields.clear();
+}
+// ---------------------------------------------------------------------------
+// Body field access (Google's field is a dotted path)
+// ---------------------------------------------------------------------------
+function readTokenValue(body, field) {
+    if (field !== 'generationConfig.maxOutputTokens') {
+        const v = body[field];
+        return typeof v === 'number' ? v : undefined;
+    }
+    const nested = body.generationConfig;
+    const v = nested?.maxOutputTokens;
+    return typeof v === 'number' ? v : undefined;
+}
+function withTokenValue(body, field, value) {
+    if (field !== 'generationConfig.maxOutputTokens') {
+        return { ...body, [field]: value };
+    }
+    const nested = (body.generationConfig ?? {});
+    return { ...body, generationConfig: { ...nested, maxOutputTokens: value } };
+}
+function readThinkingBudget(body) {
+    const thinking = body.thinking;
+    const v = thinking?.budget_tokens;
+    return typeof v === 'number' ? v : undefined;
+}
+function repairCeiling(ctx, current, ceiling) {
+    const target = Math.max(MIN_MAX_OUTPUT_TOKENS, ceiling ?? Math.min(current, SAFE_FALLBACK_MAX_OUTPUT_TOKENS));
+    if (target >= current)
+        return undefined;
+    learnModelCeiling(ctx.providerId, ctx.modelId, target, 'error');
+    return {
+        body: withTokenValue(ctx.body, ctx.field, target),
+        from: current,
+        to: target,
+        summary: `output cap ${current} -> ${target}`,
+    };
+}
+function repairContextSum(ctx, current, failure) {
+    const window = failure.contextWindow;
+    const prompt = failure.promptTokens;
+    if (window === undefined || prompt === undefined)
+        return undefined;
+    // NOT learned: a context-sum failure is conversation-specific, not a property
+    // of the model, and recording it as a ceiling would cap every later turn.
+    const target = Math.max(MIN_MAX_OUTPUT_TOKENS, window - prompt - CONTEXT_SAFETY_MARGIN_TOKENS);
+    if (target >= current)
+        return undefined;
+    return {
+        body: withTokenValue(ctx.body, ctx.field, target),
+        from: current,
+        to: target,
+        summary: `output cap ${current} -> ${target} to fit the context window`,
+    };
+}
+function repairThinkingConflict(ctx, current) {
+    const budget = readThinkingBudget(ctx.body);
+    if (budget === undefined || budget <= 0)
+        return undefined;
+    const raised = budget + THINKING_HEADROOM_TOKENS;
+    if (raised > current) {
+        return {
+            body: withTokenValue(ctx.body, ctx.field, raised),
+            from: current,
+            to: raised,
+            summary: `output cap ${current} -> ${raised} to clear the thinking budget`,
+        };
+    }
+    // The ceiling forbids raising the cap, so lower the budget instead.
+    const lowered = Math.max(MIN_THINKING_BUDGET_TOKENS, current - THINKING_HEADROOM_TOKENS);
+    if (lowered >= current)
+        return undefined;
+    const thinking = ctx.body.thinking;
+    return {
+        body: { ...ctx.body, thinking: { ...thinking, budget_tokens: lowered } },
+        from: budget,
+        to: lowered,
+        // `from`/`to` are the BUDGET here, not the cap — the cap is what could not
+        // move. Saying "output cap" would name the wrong number.
+        summary: `thinking budget ${budget} -> ${lowered}`,
+    };
+}
+function planRepair(opts, failure) {
+    const current = readTokenValue(opts.body, opts.tokenField);
+    const ctx = {
+        providerId: opts.providerId,
+        modelId: opts.modelId,
+        body: opts.body,
+        field: opts.tokenField,
+    };
+    if (failure.kind === 'unsupported_field') {
+        if (opts.tokenField === 'generationConfig.maxOutputTokens')
+            return undefined;
+        if (opts.tokenField === failure.expected)
+            return undefined;
+        learnTokenField(opts.providerId, opts.modelId, failure.expected);
+        const renamed = { ...opts.body };
+        delete renamed[opts.tokenField];
+        // The reasoning family rejects `temperature` for the same reason it rejects
+        // `max_tokens`; leaving it behind just buys a second 400 on a different key.
+        delete renamed.temperature;
+        renamed[failure.expected] = current ?? MIN_MAX_OUTPUT_TOKENS;
+        return {
+            body: renamed,
+            from: current ?? 0,
+            to: current ?? 0,
+            summary: `token parameter ${opts.tokenField} -> ${failure.expected}`,
+        };
+    }
+    if (current === undefined)
+        return undefined;
+    if (failure.kind === 'thinking_conflict')
+        return repairThinkingConflict(ctx, current);
+    if (failure.kind === 'context_sum')
+        return repairContextSum(ctx, current, failure);
+    return repairCeiling(ctx, current, failure.ceiling);
+}
+/**
+ * Send a request, and on an output-limit 400 repair it and send it once more.
+ *
+ * The hot path is untouched: a 2xx returns immediately with an unread body.
+ */
+export async function sendWithOutputLimitRecovery(opts) {
+    const first = await opts.send(opts.body);
+    // The body is NOT read here — a streaming response must reach the SSE parser
+    // intact, and `bodyUsed` would already be true if we peeked.
+    if (first.ok)
+        return { response: first, bodyText: '' };
+    const bodyText = await first.text().catch(() => '');
+    const failure = classifyOutputLimitFailure(opts.providerId, first.status, bodyText);
+    if (!failure)
+        return { response: first, bodyText };
+    const plan = planRepair(opts, failure);
+    if (!plan)
+        return { response: first, bodyText };
+    const second = await opts.send(plan.body);
+    const adjustment = { from: plan.from, to: plan.to, reason: failure.kind };
+    if (!second.ok) {
+        // A second failure surfaces exactly as it would have without recovery.
+        return { response: second, bodyText: await second.text().catch(() => ''), adjustment };
+    }
+    warnAdjusted(opts.providerId, opts.modelId, plan.summary, failure.kind);
+    return { response: second, bodyText: '', adjustment };
+}
+/** Display names for the adapters this package ships; `Openai` reads as a typo. */
+const PROVIDER_LABELS = {
+    anthropic: 'Anthropic',
+    openai: 'OpenAI',
+    google: 'Google',
+};
+/**
+ * Core has no logger and must not acquire one (that would be host coupling), so
+ * this is `console.warn` — exactly what `anthropic.ts` already does for a
+ * malformed tool call. In the CLI it reaches the transcript through the console
+ * bridge; in a headless embedder it is a plain warning.
+ */
+function warnAdjusted(providerId, modelId, summary, reason) {
+    const key = String(providerId ?? '').toLowerCase();
+    const name = PROVIDER_LABELS[key] ?? providerId.charAt(0).toUpperCase() + providerId.slice(1);
+    console.warn(`[${name}] adjusted ${summary} (${reason}) for ${modelId}`);
+}

package/dist/llm/output-limits.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Output-token authority — the single source of truth for "how many tokens may
+ * this model produce", and the resolver every provider adapter consults before
+ * putting a number on the wire.
+ *
+ * Why this module exists at all: sending a generous `max_tokens` unconditionally
+ * is only safe for models whose ceiling is at least that generous. Anthropic,
+ * OpenAI and Google all answer an over-large cap with an HTTP 400, and a 400
+ * during the agent loop ends the turn with a raw provider string in the
+ * transcript. So the product default is the AMBITION and the model's real
+ * ceiling is the LAW, with the gap closed silently rather than by a failed run.
+ *
+ * Four ranked ceiling sources feed one resolver:
+ *
+ *   learned-from-error  >  discovery (API-reported)  >  static table  >  default
+ *
+ * TEST HYGIENE: `learnModelCeiling` writes a MODULE-LEVEL map that lives for the
+ * whole process. Any test that learns MUST call `clearLearnedCeilings()` from
+ * `afterEach`, or a learned 8192 leaks into the next test file and produces a
+ * failure whose cause is not in the failing file.
+ */
+import type { Message } from './types.js';
+/** The product default. THE single source of truth; nothing else may spell 64000. */
+export declare const DEFAULT_MAX_OUTPUT_TOKENS = 64000;
+/** Below this a turn cannot produce a usable tool call; never clamp under it. */
+export declare const MIN_MAX_OUTPUT_TOKENS = 256;
+/**
+ * Every model in the supported set accepts at least this. Used when recovery
+ * cannot parse a real ceiling out of the provider's error.
+ */
+export declare const SAFE_FALLBACK_MAX_OUTPUT_TOKENS = 8192;
+/** Anthropic requires max_tokens > thinking.budget_tokens; this is the margin. */
+export declare const THINKING_HEADROOM_TOKENS = 4096;
+/** Sanity ceiling for a hand-edited config file. */
+export declare const ABSOLUTE_MAX_OUTPUT_TOKENS = 200000;
+/** Subtracted from a context-window computation so the estimate may be wrong. */
+export declare const CONTEXT_SAFETY_MARGIN_TOKENS = 1024;
+/**
+ * Anthropic's floor for `thinking.budget_tokens`. A downgrade that lands below
+ * it is illegal, so the resolver returns `thinkingBudget: 0` instead and the
+ * adapter omits the block entirely.
+ */
+export declare const MIN_THINKING_BUDGET_TOKENS = 1024;
+/** Lowercase and strip Google's `models/` prefix so one key shape is used everywhere. */
+export declare function normalizeModelId(modelId: string): string;
+/**
+ * The statically known output ceiling for a model, or `undefined`.
+ *
+ * A MISS RETURNS `undefined`, NOT A NUMBER. "Unknown" and "small" must stay
+ * distinguishable: an unknown model gets the product default and, if that is
+ * wrong, recovery fixes it. Baking a pessimistic 8192 into every unrecognised id
+ * would silently halve the output of every proxy user.
+ */
+export declare function staticCeilingFor(providerId: string, modelId: string): number | undefined;
+export type CeilingSource = 'catalog' | 'discovery' | 'error';
+interface LearnedCeiling {
+    ceiling: number;
+    source: CeilingSource;
+}
+/** Record a ceiling. A lower-ranked source never overwrites a higher-ranked one. */
+export declare function learnModelCeiling(providerId: string, modelId: string, ceiling: number, source: CeilingSource): void;
+export declare function getLearnedCeiling(providerId: string, modelId: string): LearnedCeiling | undefined;
+/** Test hook. MUST be called from `afterEach` in every test that learns. */
+export declare function clearLearnedCeilings(): void;
+export interface OutputLimitInput {
+    providerId: string;
+    modelId: string;
+    /** The user's explicit setting. `undefined` means AUTO. */
+    requested?: number;
+    /** Caller-supplied metadata (optional; see `LLMRequest.modelLimits`). */
+    modelLimits?: {
+        maxOutputTokens?: number;
+        contextWindow?: number;
+    };
+    /** Resolved thinking budget for this request; 0/undefined when off. */
+    thinkingBudget?: number;
+    /** Rough prompt size, for providers where max + prompt <= context. */
+    estimatedPromptTokens?: number;
+}
+export interface OutputLimitResolution {
+    /** The value to put on the wire. Always >= MIN_MAX_OUTPUT_TOKENS. */
+    value: number;
+    /** The ceiling that was applied, if any was known. */
+    ceiling?: number;
+    /** Where `value` came from before clamping. */
+    source: 'requested' | 'auto';
+    /** Which rule reduced it, if any — drives the one-time warning. */
+    clampedBy?: 'ceiling' | 'context' | 'absolute';
+    /** Adjusted thinking budget when the cap could not accommodate the original. */
+    thinkingBudget?: number;
+}
+/**
+ * Resolve the output-token cap for one request.
+ *
+ * Pure apart from reading the learned map. Never throws, never returns `NaN`,
+ * `0` or a negative.
+ */
+export declare function resolveOutputTokens(input: OutputLimitInput): OutputLimitResolution;
+/**
+ * Deliberately crude: ~4 chars/token plus per-message framing. Used ONLY to keep
+ * `max_tokens + prompt <= context` on OpenAI, where being 20 % wrong is absorbed
+ * by `CONTEXT_SAFETY_MARGIN_TOKENS` and, failing that, by `context_sum` recovery.
+ *
+ * No tokenizer dependency is added on purpose — this is a guard rail, not an
+ * accounting function.
+ */
+export declare function estimatePromptTokens(messages: Message[], systemPrompt?: string): number;
+export {};

package/dist/llm/output-limits.js

@@ -0,0 +1,274 @@
+/**
+ * Output-token authority — the single source of truth for "how many tokens may
+ * this model produce", and the resolver every provider adapter consults before
+ * putting a number on the wire.
+ *
+ * Why this module exists at all: sending a generous `max_tokens` unconditionally
+ * is only safe for models whose ceiling is at least that generous. Anthropic,
+ * OpenAI and Google all answer an over-large cap with an HTTP 400, and a 400
+ * during the agent loop ends the turn with a raw provider string in the
+ * transcript. So the product default is the AMBITION and the model's real
+ * ceiling is the LAW, with the gap closed silently rather than by a failed run.
+ *
+ * Four ranked ceiling sources feed one resolver:
+ *
+ *   learned-from-error  >  discovery (API-reported)  >  static table  >  default
+ *
+ * TEST HYGIENE: `learnModelCeiling` writes a MODULE-LEVEL map that lives for the
+ * whole process. Any test that learns MUST call `clearLearnedCeilings()` from
+ * `afterEach`, or a learned 8192 leaks into the next test file and produces a
+ * failure whose cause is not in the failing file.
+ */
+// ---------------------------------------------------------------------------
+// Constants — nothing else in this package may spell these numbers
+// ---------------------------------------------------------------------------
+/** The product default. THE single source of truth; nothing else may spell 64000. */
+export const DEFAULT_MAX_OUTPUT_TOKENS = 64_000;
+/** Below this a turn cannot produce a usable tool call; never clamp under it. */
+export const MIN_MAX_OUTPUT_TOKENS = 256;
+/**
+ * Every model in the supported set accepts at least this. Used when recovery
+ * cannot parse a real ceiling out of the provider's error.
+ */
+export const SAFE_FALLBACK_MAX_OUTPUT_TOKENS = 8_192;
+/** Anthropic requires max_tokens > thinking.budget_tokens; this is the margin. */
+export const THINKING_HEADROOM_TOKENS = 4_096;
+/** Sanity ceiling for a hand-edited config file. */
+export const ABSOLUTE_MAX_OUTPUT_TOKENS = 200_000;
+/** Subtracted from a context-window computation so the estimate may be wrong. */
+export const CONTEXT_SAFETY_MARGIN_TOKENS = 1_024;
+/**
+ * Anthropic's floor for `thinking.budget_tokens`. A downgrade that lands below
+ * it is illegal, so the resolver returns `thinkingBudget: 0` instead and the
+ * adapter omits the block entirely.
+ */
+export const MIN_THINKING_BUDGET_TOKENS = 1_024;
+/**
+ * Ordered; FIRST MATCH WINS. Matched against the model id lowercased with any
+ * `models/` prefix stripped (Google returns `models/gemini-1.5-pro`).
+ *
+ * ORDER IS LOAD-BEARING, not cosmetic: `claude-3-7-sonnet` also matches the
+ * broad `^claude-3(-|\.)` rule, so the specific 3.7 entry has to come first or
+ * it is dead code and every 3.7 request is clamped to 8192 (see the design's
+ * "Issues found during implementation" note).
+ */
+const CEILING_TABLE = {
+    anthropic: [
+        { pattern: /^claude-3-7-sonnet/, ceiling: 64_000 },
+        { pattern: /^claude-3-5-sonnet/, ceiling: 8_192 },
+        { pattern: /^claude-3(-|\.)/, ceiling: 8_192 },
+        { pattern: /^claude-opus-4-(0|1)\b/, ceiling: 32_000 },
+        { pattern: /^claude-(sonnet|haiku|opus)-4/, ceiling: 64_000 },
+    ],
+    openai: [
+        { pattern: /^(o1|o3|o4)-mini/, ceiling: 65_536 },
+        { pattern: /^(o1|o3|o4)\b/, ceiling: 100_000 },
+        { pattern: /^gpt-5/, ceiling: 128_000 },
+        { pattern: /^gpt-4\.1/, ceiling: 32_768 },
+        { pattern: /^gpt-4o/, ceiling: 16_384 },
+        { pattern: /^gpt-4(-turbo)?$/, ceiling: 4_096 },
+        { pattern: /^gpt-3\.5/, ceiling: 4_096 },
+    ],
+    google: [
+        { pattern: /^gemini-1\.5/, ceiling: 8_192 },
+        { pattern: /^gemini-2\.0-flash/, ceiling: 8_192 },
+        { pattern: /^gemini-2\.5/, ceiling: 65_536 },
+    ],
+};
+/** Lowercase and strip Google's `models/` prefix so one key shape is used everywhere. */
+export function normalizeModelId(modelId) {
+    return String(modelId ?? '').trim().toLowerCase().replace(/^models\//, '');
+}
+/**
+ * The statically known output ceiling for a model, or `undefined`.
+ *
+ * A MISS RETURNS `undefined`, NOT A NUMBER. "Unknown" and "small" must stay
+ * distinguishable: an unknown model gets the product default and, if that is
+ * wrong, recovery fixes it. Baking a pessimistic 8192 into every unrecognised id
+ * would silently halve the output of every proxy user.
+ */
+export function staticCeilingFor(providerId, modelId) {
+    const rules = CEILING_TABLE[String(providerId ?? '').toLowerCase()];
+    if (!rules)
+        return undefined;
+    const id = normalizeModelId(modelId);
+    if (id.length === 0)
+        return undefined;
+    for (const rule of rules) {
+        if (rule.pattern.test(id))
+            return rule.ceiling;
+    }
+    return undefined;
+}
+/** `'error'` outranks everything because it came from the API itself. */
+const RANK = { catalog: 1, discovery: 2, error: 3 };
+/** Process-lifetime only; never persisted. Key: `${providerId}:${normalizedModelId}`. */
+const learnedCeilings = new Map();
+function ceilingKey(providerId, modelId) {
+    return `${String(providerId ?? '').toLowerCase()}:${normalizeModelId(modelId)}`;
+}
+/** Record a ceiling. A lower-ranked source never overwrites a higher-ranked one. */
+export function learnModelCeiling(providerId, modelId, ceiling, source) {
+    if (!Number.isFinite(ceiling) || ceiling <= 0)
+        return;
+    const key = ceilingKey(providerId, modelId);
+    if (key.endsWith(':'))
+        return; // no model id — nothing worth remembering
+    const existing = learnedCeilings.get(key);
+    if (existing && RANK[existing.source] > RANK[source])
+        return;
+    learnedCeilings.set(key, { ceiling: Math.floor(ceiling), source });
+}
+export function getLearnedCeiling(providerId, modelId) {
+    return learnedCeilings.get(ceilingKey(providerId, modelId));
+}
+/** Test hook. MUST be called from `afterEach` in every test that learns. */
+export function clearLearnedCeilings() {
+    learnedCeilings.clear();
+}
+/** OpenAI charges `max_tokens` against the context window; the others do not. */
+function providerUsesContextSum(providerId) {
+    return String(providerId ?? '').toLowerCase() === 'openai';
+}
+/** Step 1: the strongest ceiling anyone knows about, or `undefined`. */
+function resolveCeiling(input) {
+    const learned = getLearnedCeiling(input.providerId, input.modelId);
+    if (learned)
+        return learned.ceiling;
+    const declared = input.modelLimits?.maxOutputTokens;
+    if (typeof declared === 'number' && Number.isFinite(declared) && declared > 0) {
+        return Math.floor(declared);
+    }
+    return staticCeilingFor(input.providerId, input.modelId);
+}
+/** Step 4: `max_tokens + prompt <= context` on the providers that enforce it. */
+function contextBound(input) {
+    if (!providerUsesContextSum(input.providerId))
+        return undefined;
+    const window = input.modelLimits?.contextWindow;
+    const prompt = input.estimatedPromptTokens;
+    if (typeof window !== 'number' || !Number.isFinite(window) || window <= 0)
+        return undefined;
+    if (typeof prompt !== 'number' || !Number.isFinite(prompt) || prompt < 0)
+        return undefined;
+    return window - prompt - CONTEXT_SAFETY_MARGIN_TOKENS;
+}
+/**
+ * Step 6: keep Anthropic's `max_tokens > thinking.budget_tokens` invariant.
+ *
+ * Returns the (possibly raised) cap and the budget to send. A returned budget of
+ * `0` means "omit the thinking block entirely" — `budget_tokens` has a hard floor
+ * of 1024 and sending less is illegal, so refusing to think is the only legal
+ * move left on a model whose ceiling cannot house both.
+ */
+function fitThinking(value, thinkingBudget, ceiling) {
+    if (thinkingBudget <= 0 || value > thinkingBudget)
+        return { value };
+    const raised = Math.min(ceiling ?? Number.POSITIVE_INFINITY, thinkingBudget + THINKING_HEADROOM_TOKENS);
+    if (raised > thinkingBudget)
+        return { value: raised };
+    const lowered = Math.max(MIN_THINKING_BUDGET_TOKENS, raised - THINKING_HEADROOM_TOKENS);
+    if (lowered < raised)
+        return { value: raised, thinkingBudget: lowered };
+    return { value: raised, thinkingBudget: 0 };
+}
+/**
+ * Resolve the output-token cap for one request.
+ *
+ * Pure apart from reading the learned map. Never throws, never returns `NaN`,
+ * `0` or a negative.
+ */
+export function resolveOutputTokens(input) {
+    const ceiling = resolveCeiling(input);
+    const requested = typeof input.requested === 'number' && Number.isFinite(input.requested) && input.requested > 0
+        ? Math.floor(input.requested)
+        : undefined;
+    // AUTO NEVER EXCEEDS THE PRODUCT DEFAULT, even when the model would allow
+    // 100000: on OpenAI `max_tokens` is charged against the context window, so an
+    // AUTO of 100000 would make long conversations fail with a context error. An
+    // explicit `requested` may exceed 64000 up to the ceiling — the user's call.
+    //
+    // The AMBITION is kept separate from the clamp on purpose. Folding the ceiling
+    // into the AUTO base (`min(DEFAULT, ceiling)`) yields the same number but
+    // leaves `clampedBy` unset, and `clampedBy` is what the settings preview and
+    // the one-time warning are built on: the user would see a bare
+    // `Effective: 16384` with nothing saying where the other 47616 went.
+    const ambition = requested ?? DEFAULT_MAX_OUTPUT_TOKENS;
+    let value = ambition;
+    let clampedBy;
+    if (ceiling !== undefined && ceiling < value) {
+        value = ceiling;
+        clampedBy = 'ceiling';
+    }
+    const bound = contextBound(input);
+    if (bound !== undefined && bound < value) {
+        value = bound;
+        clampedBy = 'context';
+    }
+    if (value > ABSOLUTE_MAX_OUTPUT_TOKENS) {
+        value = ABSOLUTE_MAX_OUTPUT_TOKENS;
+        clampedBy = 'absolute';
+    }
+    const fitted = fitThinking(value, input.thinkingBudget ?? 0, ceiling);
+    value = Math.floor(Math.max(fitted.value, MIN_MAX_OUTPUT_TOKENS));
+    return {
+        value,
+        ...(ceiling !== undefined ? { ceiling } : {}),
+        source: requested !== undefined ? 'requested' : 'auto',
+        ...(clampedBy ? { clampedBy } : {}),
+        ...(fitted.thinkingBudget !== undefined ? { thinkingBudget: fitted.thinkingBudget } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// Prompt estimation
+// ---------------------------------------------------------------------------
+/** Average characters per token across the model families this package speaks to. */
+const CHARS_PER_TOKEN = 4;
+/** Role markers, separators and tool-call scaffolding, per message. */
+const PER_MESSAGE_OVERHEAD_TOKENS = 4;
+function partLength(content) {
+    if (typeof content === 'string')
+        return content.length;
+    if (!Array.isArray(content))
+        return 0;
+    let total = 0;
+    for (const part of content) {
+        if (typeof part?.text === 'string')
+            total += part.text.length;
+        // Base64 image payloads are counted at a flat rate rather than by length:
+        // their character count says nothing useful about their token cost.
+        else if (part?.type === 'image')
+            total += CHARS_PER_TOKEN * 256;
+    }
+    return total;
+}
+function messageLength(message) {
+    if (message.role === 'assistant') {
+        let total = 0;
+        for (const block of message.content) {
+            if (block.type === 'text' || block.type === 'thinking')
+                total += block.text.length;
+            else if (block.type === 'tool_call')
+                total += JSON.stringify(block.args ?? {}).length;
+        }
+        return total;
+    }
+    return partLength(message.content);
+}
+/**
+ * Deliberately crude: ~4 chars/token plus per-message framing. Used ONLY to keep
+ * `max_tokens + prompt <= context` on OpenAI, where being 20 % wrong is absorbed
+ * by `CONTEXT_SAFETY_MARGIN_TOKENS` and, failing that, by `context_sum` recovery.
+ *
+ * No tokenizer dependency is added on purpose — this is a guard rail, not an
+ * accounting function.
+ */
+export function estimatePromptTokens(messages, systemPrompt) {
+    let chars = systemPrompt ? systemPrompt.length : 0;
+    let overhead = 0;
+    for (const message of messages ?? []) {
+        chars += messageLength(message);
+        overhead += PER_MESSAGE_OVERHEAD_TOKENS;
+    }
+    return Math.ceil(chars / CHARS_PER_TOKEN) + overhead;
+}

package/dist/llm/provider.d.ts

@@ -18,7 +18,27 @@ export interface LLMRequest {
     /** Abort signal for cancellation. */
     signal?: AbortSignal;
     temperature?: number;
+    /**
+     * The user's explicit output-token cap. `undefined` means AUTO — the adapter
+     * asks `resolveOutputTokens()` for a per-model value instead.
+     *
+     * An explicit value is still CLAMPED DOWN to the model's real ceiling: this is
+     * an ambition, not a promise, and a value the model cannot accept is an HTTP
+     * 400 that ends the turn.
+     */
     maxTokens?: number;
+    /**
+     * What the caller knows about this model's limits, if anything.
+     *
+     * Optional and additive: every existing caller compiles unchanged, and an
+     * absent value simply leaves the resolver with the static table. Supplying
+     * `contextWindow` is what enables the `max_tokens + prompt <= context` guard
+     * on OpenAI.
+     */
+    modelLimits?: {
+        maxOutputTokens?: number;
+        contextWindow?: number;
+    };
     /** Anthropic extended thinking level. Ignored by non-Anthropic providers. */
     thinkingLevel?: ThinkingLevel;
     /** Explicit thinking budget (tokens).  Overrides thinkingLevel if both are set. */

package/dist/llm/providers/anthropic.js

@@ -13,6 +13,8 @@
  */
 import { THINKING_BUDGET } from '../types.js';
 import { LLMError, classifyHttpError, wrapFetchError } from '../provider.js';
+import { DEFAULT_MAX_OUTPUT_TOKENS, resolveOutputTokens, staticCeilingFor, } from '../output-limits.js';
+import { sendWithOutputLimitRecovery } from '../output-limit-recovery.js';
 import { parseSSEStream } from '../stream-utils.js';
 import { consumeStream } from '../stream-utils.js';
 // ---------------------------------------------------------------------------
@@ -20,7 +22,6 @@ import { consumeStream } from '../stream-utils.js';
 // ---------------------------------------------------------------------------
 const DEFAULT_BASE_URL = 'https://api.anthropic.com';
 const ANTHROPIC_VERSION = '2023-06-01';
-const DEFAULT_MAX_TOKENS = 16384;
 // ---------------------------------------------------------------------------
 // Anthropic provider
 // ---------------------------------------------------------------------------
@@ -36,25 +37,34 @@ export class AnthropicProvider {
         const url = `${baseUrl}/v1/messages`;
         const body = buildRequestBody(request);
         let response;
+        let errorBody = '';
         try {
-            response = await fetch(url, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    'x-api-key': request.apiKey,
-                    'anthropic-version': ANTHROPIC_VERSION,
-                },
-                body: JSON.stringify(body),
-                signal: request.signal,
+            const attempt = await sendWithOutputLimitRecovery({
+                providerId: this.id,
+                modelId: request.model,
+                body,
+                tokenField: 'max_tokens',
+                send: (payload) => fetch(url, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'x-api-key': request.apiKey,
+                        'anthropic-version': ANTHROPIC_VERSION,
+                    },
+                    body: JSON.stringify(payload),
+                    signal: request.signal,
+                }),
             });
+            response = attempt.response;
+            errorBody = attempt.bodyText;
         }
         catch (err) {
             yield { type: 'error', error: wrapFetchError(err, this.id) };
             return;
         }
         if (!response.ok) {
-            const text = await response.text().catch(() => '');
-            yield { type: 'error', error: classifyHttpError(response.status, text, this.id) };
+            // `errorBody` is the ALREADY-CONSUMED body; re-reading it would throw.
+            yield { type: 'error', error: classifyHttpError(response.status, errorBody, this.id) };
             return;
         }
         if (!response.body) {
@@ -270,12 +280,16 @@ export class AnthropicProvider {
             if (!res.ok)
                 return [];
             const data = await res.json();
+            // The Anthropic models endpoint does NOT report an output ceiling, so this
+            // maps through the static table and deliberately does NOT call
+            // `learnModelCeiling`: asserting 64000 here is how `claude-3-5-haiku` ends
+            // up with a "discovered" ceiling that outranks its correct table entry.
             return (data.data || []).map((m) => ({
                 id: String(m.id || ''),
                 name: String(m.display_name || m.id || ''),
                 provider: this.id,
                 contextWindow: 200_000,
-                maxOutputTokens: 8192,
+                maxOutputTokens: staticCeilingFor(this.id, String(m.id || '')) ?? DEFAULT_MAX_OUTPUT_TOKENS,
                 supportsThinking: /claude-(sonnet-4|opus-4)/i.test(String(m.id)),
                 supportsTools: true,
                 supportsImages: true,
@@ -291,11 +305,24 @@ export class AnthropicProvider {
 // Internal: request body builder
 // ---------------------------------------------------------------------------
 function buildRequestBody(request) {
+    // Requested thinking budget FIRST: the cap and the budget are resolved
+    // together because Anthropic requires `max_tokens > budget_tokens`, and
+    // `--thinking xhigh` (65536) against the 64000 default is otherwise a
+    // guaranteed 400 on every single request.
+    const requestedBudget = request.thinkingBudget
+        ?? (request.thinkingLevel ? THINKING_BUDGET[request.thinkingLevel] : 0);
+    const resolution = resolveOutputTokens({
+        providerId: 'anthropic',
+        modelId: request.model,
+        ...(request.maxTokens !== undefined ? { requested: request.maxTokens } : {}),
+        ...(request.modelLimits ? { modelLimits: request.modelLimits } : {}),
+        thinkingBudget: requestedBudget,
+    });
     const body = {
         model: request.model,
         messages: convertMessages(request.messages),
         stream: true,
-        max_tokens: request.maxTokens ?? DEFAULT_MAX_TOKENS,
+        max_tokens: resolution.value,
     };
     if (request.systemPrompt) {
         body.system = request.systemPrompt;
@@ -309,9 +336,10 @@ function buildRequestBody(request) {
     if (request.stopSequences && request.stopSequences.length > 0) {
         body.stop_sequences = request.stopSequences;
     }
-    // Extended thinking
-    const thinkingBudget = request.thinkingBudget
-        ?? (request.thinkingLevel ? THINKING_BUDGET[request.thinkingLevel] : 0);
+    // Extended thinking. A resolved budget of 0 means the cap cannot legally house
+    // a `budget_tokens` at all, so the block is omitted entirely — and `temperature`
+    // is therefore NOT deleted, because nothing is enabled that forbids it.
+    const thinkingBudget = resolution.thinkingBudget ?? requestedBudget;
     if (thinkingBudget > 0) {
         body.thinking = {
             type: 'enabled',

package/dist/llm/providers/google.js

@@ -12,6 +12,8 @@
  */
 import { randomUUID } from 'node:crypto';
 import { LLMError, classifyHttpError, wrapFetchError } from '../provider.js';
+import { DEFAULT_MAX_OUTPUT_TOKENS, learnModelCeiling, resolveOutputTokens, } from '../output-limits.js';
+import { sendWithOutputLimitRecovery } from '../output-limit-recovery.js';
 import { parseSSEStream } from '../stream-utils.js';
 import { consumeStream } from '../stream-utils.js';
 // ---------------------------------------------------------------------------
@@ -33,21 +35,30 @@ export class GoogleProvider {
         const url = `${baseUrl}/v1beta/models/${request.model}:streamGenerateContent?alt=sse&key=${encodeURIComponent(request.apiKey)}`;
         const body = buildRequestBody(request);
         let response;
+        let errorBody = '';
         try {
-            response = await fetch(url, {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify(body),
-                signal: request.signal,
+            const attempt = await sendWithOutputLimitRecovery({
+                providerId: this.id,
+                modelId: request.model,
+                body,
+                tokenField: 'generationConfig.maxOutputTokens',
+                send: (payload) => fetch(url, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(payload),
+                    signal: request.signal,
+                }),
             });
+            response = attempt.response;
+            errorBody = attempt.bodyText;
         }
         catch (err) {
             yield { type: 'error', error: wrapFetchError(err, this.id) };
             return;
         }
         if (!response.ok) {
-            const text = await response.text().catch(() => '');
-            yield { type: 'error', error: classifyHttpError(response.status, text, this.id) };
+            // `errorBody` is the ALREADY-CONSUMED body; re-reading it would throw.
+            yield { type: 'error', error: classifyHttpError(response.status, errorBody, this.id) };
             return;
         }
         if (!response.body) {
@@ -159,12 +170,19 @@ export class GoogleProvider {
             })
                 .map((m) => {
                 const id = String(m.name || '').replace(/^models\//, '');
+                // Google is the ONE provider of the three that reports a real
+                // per-model output ceiling, so its answer is worth remembering: it
+                // outranks the static table for every later request in this process.
+                const reported = m.outputTokenLimit;
+                if (typeof reported === 'number' && reported > 0) {
+                    learnModelCeiling(this.id, id, reported, 'discovery');
+                }
                 return {
                     id,
                     name: String(m.displayName || id),
                     provider: this.id,
                     contextWindow: m.inputTokenLimit || 128_000,
-                    maxOutputTokens: m.outputTokenLimit || 8192,
+                    maxOutputTokens: reported || DEFAULT_MAX_OUTPUT_TOKENS,
                     supportsThinking: false,
                     supportsTools: true,
                     supportsImages: true,
@@ -197,10 +215,15 @@ function buildRequestBody(request) {
         ];
     }
     // Generation config
-    const genConfig = {};
-    if (request.maxTokens) {
-        genConfig.maxOutputTokens = request.maxTokens;
-    }
+    const resolution = resolveOutputTokens({
+        providerId: 'google',
+        modelId: request.model,
+        ...(request.maxTokens !== undefined ? { requested: request.maxTokens } : {}),
+        ...(request.modelLimits ? { modelLimits: request.modelLimits } : {}),
+    });
+    const genConfig = {
+        maxOutputTokens: resolution.value,
+    };
     if (request.temperature !== undefined) {
         genConfig.temperature = request.temperature;
     }

package/dist/llm/providers/openai.d.ts

@@ -12,6 +12,15 @@
  */
 import type { AssistantMessage, ModelInfo, StreamEvent } from '../types.js';
 import type { LLMProvider, LLMRequest } from '../provider.js';
+/**
+ * Which parameter name carries the cap for this model.
+ *
+ * A HEURISTIC, and only the first guess: a proxy fronting an o-series model
+ * under a `gpt-` alias disagrees with it. `unsupported_field` recovery renames
+ * the parameter after one round trip and memoizes the answer, which is why the
+ * learned dialect is consulted first.
+ */
+export declare function openAiTokenField(modelId: string): 'max_tokens' | 'max_completion_tokens';
 export declare class OpenAIProvider implements LLMProvider {
     readonly id = "openai";
     readonly displayName = "OpenAI";

package/dist/llm/providers/openai.js

@@ -11,13 +11,16 @@
  * - The `[DONE]` sentinel terminates the SSE stream.
  */
 import { LLMError, classifyHttpError, wrapFetchError } from '../provider.js';
+import { DEFAULT_MAX_OUTPUT_TOKENS, estimatePromptTokens, normalizeModelId, resolveOutputTokens, staticCeilingFor, } from '../output-limits.js';
+import { getLearnedTokenField, sendWithOutputLimitRecovery } from '../output-limit-recovery.js';
 import { parseSSEStream } from '../stream-utils.js';
 import { consumeStream } from '../stream-utils.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
-const DEFAULT_MAX_TOKENS = 16384;
+/** Reasoning-family models reject `max_tokens` in favour of `max_completion_tokens`. */
+const REASONING_MODEL_PATTERN = /^(o1|o3|o4|gpt-5)/;
 // Model ID patterns to filter out non-chat models
 const NON_CHAT_PATTERNS = [
     /^text-embedding/i,
@@ -38,6 +41,22 @@ const NON_CHAT_PATTERNS = [
 function isChatModel(id) {
     return !NON_CHAT_PATTERNS.some((pat) => pat.test(id));
 }
+/**
+ * Which parameter name carries the cap for this model.
+ *
+ * A HEURISTIC, and only the first guess: a proxy fronting an o-series model
+ * under a `gpt-` alias disagrees with it. `unsupported_field` recovery renames
+ * the parameter after one round trip and memoizes the answer, which is why the
+ * learned dialect is consulted first.
+ */
+export function openAiTokenField(modelId) {
+    const learned = getLearnedTokenField('openai', modelId);
+    if (learned)
+        return learned;
+    return REASONING_MODEL_PATTERN.test(normalizeModelId(modelId))
+        ? 'max_completion_tokens'
+        : 'max_tokens';
+}
 // ---------------------------------------------------------------------------
 // OpenAI provider
 // ---------------------------------------------------------------------------
@@ -53,24 +72,33 @@ export class OpenAIProvider {
         const url = `${baseUrl}/chat/completions`;
         const body = buildRequestBody(request);
         let response;
+        let errorBody = '';
         try {
-            response = await fetch(url, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/json',
-                    'Authorization': `Bearer ${request.apiKey}`,
-                },
-                body: JSON.stringify(body),
-                signal: request.signal,
+            const attempt = await sendWithOutputLimitRecovery({
+                providerId: this.id,
+                modelId: request.model,
+                body,
+                tokenField: openAiTokenField(request.model),
+                send: (payload) => fetch(url, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Authorization': `Bearer ${request.apiKey}`,
+                    },
+                    body: JSON.stringify(payload),
+                    signal: request.signal,
+                }),
             });
+            response = attempt.response;
+            errorBody = attempt.bodyText;
         }
         catch (err) {
             yield { type: 'error', error: wrapFetchError(err, this.id) };
             return;
         }
         if (!response.ok) {
-            const text = await response.text().catch(() => '');
-            yield { type: 'error', error: classifyHttpError(response.status, text, this.id) };
+            // `errorBody` is the ALREADY-CONSUMED body; re-reading it would throw.
+            yield { type: 'error', error: classifyHttpError(response.status, errorBody, this.id) };
             return;
         }
         if (!response.body) {
@@ -214,6 +242,10 @@ export class OpenAIProvider {
             if (!res.ok)
                 return [];
             const data = await res.json();
+            // The OpenAI models endpoint does NOT report an output ceiling, so this
+            // maps through the static table and deliberately does NOT call
+            // `learnModelCeiling` — claiming knowledge we do not have would outrank
+            // the (correct) table entry for every small model.
             return (data.data || [])
                 .filter((m) => isChatModel(String(m.id || '')))
                 .map((m) => ({
@@ -221,7 +253,7 @@ export class OpenAIProvider {
                 name: String(m.id || ''),
                 provider: this.id,
                 contextWindow: 128_000,
-                maxOutputTokens: 16_384,
+                maxOutputTokens: staticCeilingFor(this.id, String(m.id || '')) ?? DEFAULT_MAX_OUTPUT_TOKENS,
                 supportsThinking: false,
                 supportsTools: true,
                 supportsImages: /gpt-4|o1|o3/i.test(String(m.id)),
@@ -244,10 +276,24 @@ function buildRequestBody(request) {
         stream: true,
         stream_options: { include_usage: true },
     };
-    if (request.maxTokens) {
-        body.max_tokens = request.maxTokens;
-    }
-    if (request.temperature !== undefined) {
+    const tokenField = openAiTokenField(request.model);
+    // The prompt estimate is only ever consumed when the caller told us the
+    // context window, so it is computed only then — walking every message on a
+    // hot path that cannot use the result would be pure waste.
+    const contextWindow = request.modelLimits?.contextWindow;
+    const resolution = resolveOutputTokens({
+        providerId: 'openai',
+        modelId: request.model,
+        ...(request.maxTokens !== undefined ? { requested: request.maxTokens } : {}),
+        ...(request.modelLimits ? { modelLimits: request.modelLimits } : {}),
+        ...(contextWindow !== undefined
+            ? { estimatedPromptTokens: estimatePromptTokens(request.messages, request.systemPrompt) }
+            : {}),
+    });
+    body[tokenField] = resolution.value;
+    // The reasoning family rejects `temperature` alongside `max_tokens`; sending
+    // it would just buy a second 400 on a different key.
+    if (request.temperature !== undefined && tokenField === 'max_tokens') {
         body.temperature = request.temperature;
     }
     if (request.stopSequences && request.stopSequences.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/core",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "AragonAgent core engine — LLM provider adapters, streaming, tool registry/execution, steering, idle watchdog, and an optional isolated-vm sandbox.",
   "license": "MIT",
   "author": "AragonAgent contributors",