fix(runtime): stop estimating context fit; the provider decides

The runtime no longer estimates whether a request fits a context window.
Every "does it fit" question is answered by a provider: the conversation
model's own context-length rejection is recovered by one compact-and-retry,
and the summarizer's provider answers for compaction input (input_too_large
retreats the fold by half). The chars/4 payload ruler, the signed delta
estimate, the 32,000-token fallback history budget, the quarter-window
reserve, the replacement-not-smaller and prefix-over-budget replay gates,
and the final-request rescue re-entry are removed.

Proactive compaction keeps one trigger: the previous accepted request's
real input plus output tokens, as the provider counted them, compared with
the context window the user declared for the model (a model-facts pin or a
relay profile). A provider's /models report and generated metadata are no
longer a threshold on their own. With no declaration there is no proactive
fold; the provider decides. A reply the provider cut at its output limit
(finishReason length) folds once before the next request.

The persisted last-request anchor becomes { inputTokens, outputTokens };
the retired payloadChars key still decodes so 0.2.0 sessions keep loading.
Summaries are capped at 8,000 output tokens with one shorter retry, and the
too-small-for-fold floor reads the summarizer call's real usage instead of
a chars/4 estimate. Two user-visible notes explain provider-side context
changes: context_provider_dropping (an append-only step whose usage did not
grow) and context_window_suggestion (a rejection at a proven-fit total,
with the number the user can declare).

Closes apache#4559
Refs apache#4458, apache#4486

Generated-by: Claude Code
Claude-Session: https://claude.ai/code/session_014ajaRxC4jydavY9nYUFj5J

Author: Joob1n

CHANGELOG.md

@@ -48,7 +48,7 @@
   owner, immutable request snapshots remain enforced at AgentRun acceptance and backend dispatch,
   and SessionEvent-to-RuntimeEvent conversion remains a pure mapper.
 - Retired the Task Ledger domain: SessionTodo is now the sole authority for in-session work items, and the operational-state schema drops the `workflow_task_ledger_events` table on first open. **Unfinished Tasks are not migrated and are permanently deleted.** This affects workspaces last opened by `v0.1.0` through `v0.1.11`, `cli-v0.1.0-beta.1`, `v0.2.0-incubating-rc1`, or a `v0.2.0-dev` build; those releases wrote Tasks to a table that no shipped build ever bridged into SessionTodo. Before opening such a workspace with this build, finish or export the Tasks you still need, or copy the workspace's `runtime.sqlite` aside — the migration removes the only live copy, so afterwards recovery requires a backup made in advance.
-- Let the provider decide whether a request fits, and anchored the estimate that decides when to compact on the last request the provider actually counted. `token_usage` records now persist that anchor under a new `lastRequestAnchor` key. **Sessions this build writes do not open in earlier releases:** those decode `token_usage` against a closed allowlist, so the unknown key fails the record and, with it, the Session that contains it. Downgrading therefore needs a copy of the workspace's `runtime.sqlite` taken before the upgrade. Retired with the local verdict: nothing produces the `context_budget_exhausted` stop reason any more — a request that really is too large is compacted and retried once, then reported as a `context_overflow` provider error — though sessions that already recorded it still decode and present. The Runtime Host compatibility epoch moves to 94.
+- Let the provider decide whether a request fits. Proactive compaction now uses only a user-declared Maka window and the previous accepted request's provider-reported `inputTokens + outputTokens`; no declaration means no proactive capacity threshold. `/models` and generated model metadata are display hints, not limits. `token_usage` records persist the last-request anchor under `lastRequestAnchor`; its new `{ inputTokens, outputTokens }` shape still decodes the retired `payloadChars` key from older sessions. Requests that are too large are compacted and retried once after a real provider rejection, then reported as a `context_overflow` provider error. New provider-dropping and context-window suggestion system notes explain provider-side context changes.
 - Unified context management under one Runtime-owned policy. `MAKA_CONTEXT_*` environment overrides no longer tune or disable compaction and Tool Result pruning; model-visible archive placeholders are read on demand through bounded `ArchiveRead` calls instead of eager hydration. Previously supported overrides are ignored on upgrade: if Tool Result pruning was set to `off`, pruning is re-enabled, and there is currently no supported replacement opt-out.
 - Moved Read image snapshots into the durable context-offload store with Runtime-owned
   lifecycle identity, exact branch and revision copying, recovery-safe cleanup, and bounded

docs/architecture/llm-compaction-events-log-projection-draft.md

@@ -24,28 +24,33 @@ import { decodeCanonicalMessage } from '../session.js';
 
 const usage = { input: 370, output: 60 };
 
-test('a last-request anchor is only valid as a complete positive pair', () => {
+test('a last-request anchor accepts the new usage shape and retired payload key', () => {
+  assert.equal(isLastRequestAnchor({ inputTokens: 120, outputTokens: 30 }), true);
+  assert.equal(isLastRequestAnchor({ inputTokens: 120 }), true);
   assert.equal(isLastRequestAnchor({ inputTokens: 120, payloadChars: 4_000 }), true);
-  assert.equal(isLastRequestAnchor({ inputTokens: 120 }), false);
   assert.equal(isLastRequestAnchor({ payloadChars: 4_000 }), false);
   assert.equal(isLastRequestAnchor({ inputTokens: 0, payloadChars: 4_000 }), false);
-  assert.equal(isLastRequestAnchor({ inputTokens: 120, payloadChars: 0 }), false);
-  assert.equal(
-    isLastRequestAnchor({ inputTokens: 120, payloadChars: 4_000, stepNumber: 2 }),
-    false,
-  );
+  assert.equal(isLastRequestAnchor({ inputTokens: 120, outputTokens: -1 }), false);
+  assert.equal(isLastRequestAnchor({ inputTokens: 120, foo: 1 }), false);
 });
 
 test('token-usage fields carry the anchor and reject a broken one', () => {
   assert.equal(
-    isTokenUsageFields({ ...usage, lastRequestAnchor: { inputTokens: 120, payloadChars: 4_000 } }),
+    isTokenUsageFields({ ...usage, lastRequestAnchor: { inputTokens: 120, outputTokens: 30 } }),
     true,
   );
   assert.equal(isTokenUsageFields(usage), true);
-  assert.equal(isTokenUsageFields({ ...usage, lastRequestAnchor: { inputTokens: 120 } }), false);
+  assert.equal(
+    isTokenUsageFields({ ...usage, lastRequestAnchor: { inputTokens: 120, payloadChars: 4_000 } }),
+    true,
+  );
+  assert.equal(
+    isTokenUsageFields({ ...usage, lastRequestAnchor: { inputTokens: 120, foo: 1 } }),
+    false,
+  );
 });
 
-test('a half-written anchor fails the whole token_usage message decode', () => {
+test('an invalid anchor fails the whole token_usage message decode', () => {
   const message = {
     type: 'token_usage',
     id: 'usage-1',
@@ -56,11 +61,11 @@ test('a half-written anchor fails the whole token_usage message decode', () => {
   assert.deepEqual(
     decodeCanonicalMessage({
       ...message,
-      lastRequestAnchor: { inputTokens: 120, payloadChars: 4_000 },
+      lastRequestAnchor: { inputTokens: 120, outputTokens: 30 },
     }),
-    { ...message, lastRequestAnchor: { inputTokens: 120, payloadChars: 4_000 } },
+    { ...message, lastRequestAnchor: { inputTokens: 120, outputTokens: 30 } },
   );
   assert.throws(() =>
-    decodeCanonicalMessage({ ...message, lastRequestAnchor: { payloadChars: 4_000 } }),
+    decodeCanonicalMessage({ ...message, lastRequestAnchor: { inputTokens: 0 } }),
   );
 });

docs/architecture/llm-compaction-events-log-projection-draft.zh-CN.md

@@ -268,6 +268,39 @@ export function relayModelProfile(
   return normalizeRelayModelProfile(connection.relayModelProfiles?.[modelId]);
 }
 
+/** The connection fields the declared-window rule reads; structural so runtime and UI projections both fit. */
+export interface DeclaredContextWindowContext extends ConnectionThinkingContext {
+  readonly models?: readonly {
+    readonly id: string;
+    readonly contextWindow?: number;
+    readonly inputLimit?: number;
+    readonly factOverriddenFields?: readonly string[];
+  }[];
+}
+
+/**
+ * The context window the USER declared for a model — the Maka window: the
+ * proactive compaction target, and nothing else. Exactly two sources count as
+ * a declaration: a model-facts pin (`factOverriddenFields` includes
+ * `contextWindow`, narrowest of window/input limit) and a relay model profile.
+ * A provider's `/models` report and generated metadata describe the model and
+ * are shown as a hint; they never become a threshold on their own. This is the
+ * single owner of that rule for runtime and UI (#4559).
+ */
+export function declaredContextWindow(
+  connection: DeclaredContextWindowContext,
+  modelId: string,
+): number | undefined {
+  const model = connection.models?.find((candidate) => candidate.id === modelId);
+  if (model?.factOverriddenFields?.includes('contextWindow')) {
+    const values = [model.contextWindow, model.inputLimit].filter(
+      (value): value is number => typeof value === 'number' && Number.isFinite(value) && value > 0,
+    );
+    return values.length > 0 ? Math.min(...values) : undefined;
+  }
+  return relayModelProfile(connection, modelId)?.contextWindow;
+}
+
 /**
  * Mirrors @ai-sdk/openai@4.0.42 priority-processing detection. The UI and
  * runtime share this gate so a saved Fast declaration always reaches the wire.

packages/core/src/__tests__/usage-record-last-request-anchor.test.ts

@@ -792,6 +792,8 @@ export function userFacingText(message: Pick<UserMessage, 'text' | 'displayText'
 const USER_VISIBLE_SESSION_SYSTEM_NOTES = new Set([
   'context_compacted',
   'context_compaction_failed_open',
+  'context_provider_dropping',
+  'context_window_suggestion',
   'step_limit',
 ]);
 
@@ -1072,6 +1074,8 @@ export interface SystemNoteMessage {
     | 'model_change'
     | 'context_compacted'
     | 'context_compaction_failed_open'
+    | 'context_provider_dropping'
+    | 'context_window_suggestion'
     | 'step_limit'
     | 'error'
     | 'abort';
@@ -1276,6 +1280,8 @@ const SYSTEM_NOTE_KINDS = new Set([
   'model_change',
   'context_compacted',
   'context_compaction_failed_open',
+  'context_provider_dropping',
+  'context_window_suggestion',
   'step_limit',
   'error',
   'abort',

packages/core/src/model-thinking.ts

@@ -82,7 +82,6 @@ const CURRENT_CONTEXT_BUDGET_SHAPE = defineObjectShape<ContextBudgetDiagnostic>(
   ],
   [
     'policyName',
-    'maxHistoryEstimatedTokens',
     'prunedToolResults',
     'prunedToolResultEstimatedTokensBefore',
     'prunedToolResultEstimatedTokensAfter',
@@ -105,6 +104,7 @@ const CURRENT_CONTEXT_BUDGET_SHAPE = defineObjectShape<ContextBudgetDiagnostic>(
  * produce them through ContextBudgetDiagnostic.
  */
 const RETIRED_CONTEXT_BUDGET_KEYS = [
+  'maxHistoryEstimatedTokens',
   'maxHistoryTurns',
   'semanticCompactEnabled',
   'semanticCompactMode',
@@ -285,38 +285,49 @@ export interface TokenUsageFields {
   providerRequestTraceId?: string;
   /**
    * The send's LAST provider request, as a pair: the input tokens the provider
-   * reported for it, and the wire payload chars the runtime measured for that
-   * same request. `input` above is the send's sum across steps and cannot
-   * anchor anything; this pair can, so the next turn estimates its first
-   * request from real usage instead of guessing the whole payload at char/4.
-   *
-   * Only the pair means anything — an anchor taken from one request and a
-   * baseline from another is off by a whole step's growth — so the two numbers
-   * live in one object that is written and read together. Absent means no
-   * anchor, and the estimate falls back to the cold start.
+   * reported for it, and its output tokens. `input` above is the send's sum
+   * across steps and cannot anchor anything; the last step's real input and
+   * output can, so the next turn judges its first request from real usage.
+   * Absent means no anchor, and the next turn has no proactive fold until its
+   * first accepted request.
    */
   lastRequestAnchor?: LastRequestAnchor;
 }
 
-/** Real input tokens of one provider request, paired with its measured payload chars. */
+/**
+ * The last provider request of a send, as the provider counted it: its real
+ * input tokens and its real output tokens. Together they are the baseline the
+ * next request is judged from — everything the model produced is re-sent as
+ * input — with no local measure involved (#4559).
+ *
+ * `payloadChars` is a retired key from the 0.2.0 anchor, which paired the input
+ * count with a locally measured payload size. It is still accepted on decode so
+ * sessions written by that build keep loading, and ignored.
+ */
 export interface LastRequestAnchor {
   inputTokens: number;
-  payloadChars: number;
+  outputTokens?: number;
 }
 
 const LAST_REQUEST_ANCHOR_SHAPE = defineObjectShape<LastRequestAnchor>()(
-  ['inputTokens', 'payloadChars'],
-  [],
+  ['inputTokens'],
+  ['outputTokens'],
 );
+const RETIRED_LAST_REQUEST_ANCHOR_KEYS = ['payloadChars'] as const;
+const LAST_REQUEST_ANCHOR_DECODE_SHAPE = {
+  required: LAST_REQUEST_ANCHOR_SHAPE.required,
+  allowed: new Set([...LAST_REQUEST_ANCHOR_SHAPE.allowed, ...RETIRED_LAST_REQUEST_ANCHOR_KEYS]),
+};
 
 export function isLastRequestAnchor(value: unknown): value is LastRequestAnchor {
   return (
     isRecord(value) &&
-    hasExactShape(value, LAST_REQUEST_ANCHOR_SHAPE) &&
+    hasExactShape(value, LAST_REQUEST_ANCHOR_DECODE_SHAPE) &&
     isFiniteNumber(value.inputTokens) &&
-    isFiniteNumber(value.payloadChars) &&
     value.inputTokens > 0 &&
-    value.payloadChars > 0
+    (value.outputTokens === undefined ||
+      (isFiniteNumber(value.outputTokens) && value.outputTokens >= 0)) &&
+    (value.payloadChars === undefined || isFiniteNumber(value.payloadChars))
   );
 }
 

packages/core/src/session.ts

@@ -284,7 +284,6 @@ export interface CompactionDecisionDiagnostic {
 export interface ContextBudgetDiagnostic {
   enabled: boolean;
   policyName?: string;
-  maxHistoryEstimatedTokens?: number;
   estimatedTokensBefore: number;
   estimatedTokensAfter: number;
   keptTurns: number;

packages/core/src/usage-record-schema.ts

@@ -1779,6 +1779,16 @@ test('production Host executes a canonical ai-sdk Session against a real provide
     });
     assert.equal(configured.kind, 'committed');
     await publishConnectionModel(policy, connection.connectionId, MODEL_ID);
+    // The fetched /models value is metadata only. This explicit model-facts
+    // declaration is the Maka compaction target used by the long-session flow.
+    await writeFile(
+      join(root, 'model-facts.json'),
+      JSON.stringify({
+        schemaVersion: 1,
+        overrides: { [`moonshot:${MODEL_ID}`]: { contextWindow: 3_072 } },
+      }),
+      'utf8',
+    );
     let policySnapshot = await policy.runtimePolicy.getSnapshot();
     const personalized = await policy.runtimePolicy.mutate({
       expectedRevision: policySnapshot.revision,
@@ -1860,8 +1870,8 @@ test('production Host executes a canonical ai-sdk Session against a real provide
     assert.equal(remembered.result.kind, 'committed');
 
     const turnIds: string[] = [];
-    // Cross the history high-water without making the text-only compact input
-    // exceed this fixture's 2,304-token summarizer budget.
+    // Cross the explicitly declared Maka window without making the text-only
+    // compact input exceed this fixture's 2,304-token summarizer budget.
     for (let index = 0; index < 5; index += 1) {
       const turnId = randomUUID();
       turnIds.push(turnId);

packages/core/src/usage-stats/types.ts

@@ -392,7 +392,7 @@ async function buildHostAiSdkBackend(
           : {}),
         ...(!input.context.tools && input.childAgents ? input.childAgents : {}),
         providerOptions,
-        contextBudget: buildDefaultContextBudgetPolicy(target.connection, {
+        contextBudget: buildDefaultContextBudgetPolicy({
           name: 'runtime-host-default-history-budget',
           modelId: target.model,
         }),