@aexol/spectral 0.9.260 → 0.9.263

package/dist/agent/index.d.ts

@@ -31,6 +31,7 @@
  *     `compact_context`, and `subagent` remain excluded
  */
 import type { AgentEvent, AgentTool } from "../sdk/agent-core/index.js";
+import type { AgentMessage } from "../sdk/agent-core/index.js";
 import { type ExtensionAPI, type ExtensionContext } from "../sdk/coding-agent/index.js";
 import { type AgentConfig } from "./agents.js";
 import type { ServerEvent } from "../server/wire.ts";
@@ -91,6 +92,31 @@ export declare function resolveSubagentMaxAttempts(explicit: number | undefined,
     enabled?: boolean;
     maxRetries?: number;
 } | undefined): number;
+/**
+ * Deterministic compact-and-retry for a subagent context overflow.
+ *
+ * Builds a compacted message state from the child transcript: a deterministic
+ * DCP-lite summary of the older history plus a kept recent tail. The latest
+ * user message (the task prompt) is pinned so it survives verbatim. Returns the
+ * new message state, or `undefined` when there is nothing meaningful to
+ * compact (e.g. the transcript is just the task prompt) or the cut cannot be
+ * computed.
+ *
+ * No LLM calls — this is pure `prepareCompaction` + `compactDcpLite` over a
+ * synthetic session-entry list, so it is safe to run inline in the retry loop.
+ */
+export declare function compactMessagesForOverflow(messages: AgentMessage[], contextWindow: number): AgentMessage[] | undefined;
+/**
+ * Deterministic single-message size guard.
+ *
+ * If a SINGLE message's estimated tokens exceed ~50% of the model context
+ * window, its text content is truncated to a safe cap and a marker note is
+ * appended. This keeps the provider request sub-window even when one oversized
+ * message (e.g. a giant file read) would otherwise push the request over the
+ * limit and yield a silent 400. Purely local — no LLM calls. Returns the
+ * original array unchanged when no message needs truncation.
+ */
+export declare function guardOversizedMessages(messages: AgentMessage[], contextWindow: number): AgentMessage[];
 export default function subagentExtension(ext: ExtensionAPI, opts?: {
     disabledAgents?: string[];
     emitSubagentEvent?: (event: ServerEvent) => void;

package/dist/agent/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAEX,UAAU,EAEV,SAAS,EAET,MAAM,4BAA4B,CAAC;AAoBpC,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAKrB,MAAM,8BAA8B,CAAC;AAItC,OAAO,EACN,KAAK,WAAW,EAQhB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAGN,KAAK,cAAc,EACnB,MAAM,uCAAuC,CAAC;AAS/C,OAAO,KAAK,EAAE,sBAAsB,EAAgB,MAAM,6CAA6C,CAAC;AAyGxG;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACxC,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAC,GACpF,MAAM,CAYR;AAyND;;;GAGG;AACH,wBAAgB,oCAAoC,CACnD,cAAc,EAAE,gBAAgB,CAAC,gBAAgB,CAAC,GAChD,IAAI,CAAC,sBAAsB,EAAE,WAAW,GAAG,cAAc,CAAC,CAe5D;AAgCD,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,gBAAgB,EACrB,SAAS,CAAC,EAAE,MAAM,GAChB,SAAS,EAAE,CAkDb;AAyBD;;;;;;;;;;GAUG;AACH;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACxC,IAAI,EAAE,uBAAuB,CAAC;IAC9B,6EAA6E;IAC7E,GAAG,EAAE,cAAc,CAAC;CACpB;AAED,8EAA8E;AAC9E,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,wBAAwB,CAAC;AAqF1E,2FAA2F;AAC3F,wBAAgB,+BAA+B,CAC9C,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GACtD,IAAI,CAEN;AAmBD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACzC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,QAAQ,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAC9D,MAAM,CAiBR;AAwnBD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACxC,GAAG,EAAE,YAAY,EACjB,IAAI,CAAC,EAAE;IACN,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,wBAAwB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CAC3D,GACC,IAAI,CAwbN"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAEX,UAAU,EAEV,SAAS,EAET,MAAM,4BAA4B,CAAC;AAOpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAwB/D,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,gBAAgB,EAKrB,MAAM,8BAA8B,CAAC;AAItC,OAAO,EACN,KAAK,WAAW,EAQhB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAGN,KAAK,cAAc,EACnB,MAAM,uCAAuC,CAAC;AAS/C,OAAO,KAAK,EAAE,sBAAsB,EAAgB,MAAM,6CAA6C,CAAC;AA+HxG;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACxC,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAC,GACpF,MAAM,CAeR;AAyND;;;GAGG;AACH,wBAAgB,oCAAoC,CACnD,cAAc,EAAE,gBAAgB,CAAC,gBAAgB,CAAC,GAChD,IAAI,CAAC,sBAAsB,EAAE,WAAW,GAAG,cAAc,CAAC,CAe5D;AAgCD,wBAAgB,oBAAoB,CACnC,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,YAAY,EACjB,GAAG,EAAE,gBAAgB,EACrB,SAAS,CAAC,EAAE,MAAM,GAChB,SAAS,EAAE,CAkDb;AAyBD;;;;;;;;;;GAUG;AACH;;;;;;GAMG;AACH,MAAM,WAAW,wBAAwB;IACxC,IAAI,EAAE,uBAAuB,CAAC;IAC9B,6EAA6E;IAC7E,GAAG,EAAE,cAAc,CAAC;CACpB;AAED,8EAA8E;AAC9E,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,wBAAwB,CAAC;AAqF1E,2FAA2F;AAC3F,wBAAgB,+BAA+B,CAC9C,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GACtD,IAAI,CAEN;AAmBD;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACzC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,QAAQ,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GAC9D,MAAM,CAiBR;AAsBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CACzC,QAAQ,EAAE,YAAY,EAAE,EACxB,aAAa,EAAE,MAAM,GACnB,YAAY,EAAE,GAAG,SAAS,CAyE5B;AASD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACrC,QAAQ,EAAE,YAAY,EAAE,EACxB,aAAa,EAAE,MAAM,GACnB,YAAY,EAAE,CAchB;AA8tBD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CACxC,GAAG,EAAE,YAAY,EACjB,IAAI,CAAC,EAAE;IACN,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,wBAAwB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CAC3D,GACC,IAAI,CAwbN"}

package/dist/agent/index.js

@@ -32,6 +32,9 @@
  */
 import { agentLoop, agentLoopContinue, } from "../sdk/agent-core/index.js";
 import { buildIsolatedRequestTimePrunedMessagesResult, COMPACT_CONTEXT_TOOL_NAME, } from "../memory/tools/compact-context.js";
+import { compactDcpLite, prepareCompaction, DEFAULT_COMPACTION_SETTINGS, } from "../sdk/coding-agent/core/compaction/index.js";
+import { estimateTokens } from "../sdk/coding-agent/core/compaction/tokens.js";
+import { createCompactionSummaryMessage, convertToLlm, } from "../sdk/coding-agent/core/messages.js";
 import { isRateLimitError, isTransientApiError, isContextOverflow, isPaymentRequiredError, streamSimple, } from "../sdk/ai/index.js";
 import { RETRY_DEFAULT_BASE_DELAY_MS, RETRY_DEFAULT_MAX_RETRIES, RETRY_MAX_BACKOFF_DELAY_MS, } from "../sdk/coding-agent/index.js";
 import { mutateSystemPrompt } from "../sdk/coding-agent/core/system-prompt-mutator.js";
@@ -136,6 +139,25 @@ function compactProgressMessage(value) {
     return value === undefined ? undefined : "Tool progress updated";
 }
 const PRIMARY_AGENT_BLOCK_RE = /(?:^|\n)(?:# Primary Agent: [^\n]*\n(?:\n[^\n]*)*?)(?:\n\n---\n\n|$)/;
+/**
+ * Strip `compact_context` tool-description lines from a base system prompt.
+ *
+ * Subagents exclude the `compact_context` tool (see SUBAGENT_EXCLUDED_TOOL_NAMES),
+ * so its promptSnippet (an "Available tools" bullet) and its promptGuidelines
+ * ("Guidelines" bullets) must not leak into the subagent's prompt — they would
+ * describe a tool the subagent cannot call. Both are `- ` bullets that mention
+ * the tool name, so a line-based filter is a clean deterministic anchor. Only
+ * the subagent base prompt is touched; the main-session prompt is unaffected.
+ */
+function stripCompactContextFromPrompt(prompt) {
+    if (!prompt.includes(COMPACT_CONTEXT_TOOL_NAME))
+        return prompt;
+    return prompt
+        .split("\n")
+        .filter((line) => !(line.trimStart().startsWith("- ") &&
+        line.includes(COMPACT_CONTEXT_TOOL_NAME)))
+        .join("\n");
+}
 /**
  * Build the system prompt for a subagent session.
  *
@@ -151,10 +173,13 @@ export function buildSubagentSystemPrompt(baseSystemPrompt, agent) {
         agentMetadataBlock(agent);
     if (!baseSystemPrompt)
         return subagentBlock;
-    const stripped = baseSystemPrompt.replace(PRIMARY_AGENT_BLOCK_RE, "");
-    if (stripped === baseSystemPrompt) {
+    // Drop the excluded compact_context tool's description lines before any
+    // further shaping, so the subagent never sees a tool it cannot call.
+    const base = stripCompactContextFromPrompt(baseSystemPrompt);
+    const stripped = base.replace(PRIMARY_AGENT_BLOCK_RE, "");
+    if (stripped === base) {
         // No existing primary block: inject the subagent block below the base.
-        return `${baseSystemPrompt}\n\n---\n\n${subagentBlock}`;
+        return `${base}\n\n---\n\n${subagentBlock}`;
     }
     const remainder = stripped.replace(/^\n+|\n+$/g, "");
     return remainder ? `${remainder}\n\n---\n\n${subagentBlock}` : subagentBlock;
@@ -477,6 +502,147 @@ export function resolveSubagentMaxAttempts(explicit, settings) {
     return 1 + retries;
 }
 // ---------------------------------------------------------------------------
+// Overflow recovery — deterministic DCP-lite compact-and-retry
+// ---------------------------------------------------------------------------
+/**
+ * Max compact-and-retry attempts on a context overflow. This budget is
+ * SEPARATE from the transient-error retry budget (`maxSegments`): an overflow
+ * is not a transient provider failure, so recovering it must not consume the
+ * transient retries (and vice versa).
+ */
+const MAX_OVERFLOW_COMPACT_RETRIES = 2;
+/**
+ * Recent-tail keep budget for an overflow compaction: `max(12_000, 10% of the
+ * model context window)` tokens, mirroring the main session's auto
+ * older-history keep-recent floor.
+ */
+const OVERFLOW_KEEP_RECENT_TOKENS_FLOOR = 12_000;
+const OVERFLOW_KEEP_RECENT_WINDOW_RATIO = 0.1;
+/**
+ * Deterministic compact-and-retry for a subagent context overflow.
+ *
+ * Builds a compacted message state from the child transcript: a deterministic
+ * DCP-lite summary of the older history plus a kept recent tail. The latest
+ * user message (the task prompt) is pinned so it survives verbatim. Returns the
+ * new message state, or `undefined` when there is nothing meaningful to
+ * compact (e.g. the transcript is just the task prompt) or the cut cannot be
+ * computed.
+ *
+ * No LLM calls — this is pure `prepareCompaction` + `compactDcpLite` over a
+ * synthetic session-entry list, so it is safe to run inline in the retry loop.
+ */
+export function compactMessagesForOverflow(messages, contextWindow) {
+    // Drop trailing failed assistant message(s) so the compaction summarizes
+    // real history, not the overflow error turn the child just produced.
+    const working = [...messages];
+    while (working.length > 0 &&
+        working[working.length - 1].role === "assistant") {
+        working.pop();
+    }
+    // Need at least a summarizable prefix plus a kept tail to be useful.
+    if (working.length < 2)
+        return undefined;
+    const entries = working.map((message, index) => ({
+        type: "message",
+        id: `subagent-compact-${index}`,
+        parentId: index > 0 ? `subagent-compact-${index - 1}` : null,
+        timestamp: new Date(index).toISOString(),
+        message,
+    }));
+    const keepRecentTokens = Math.max(OVERFLOW_KEEP_RECENT_TOKENS_FLOOR, Math.floor((contextWindow ?? 0) * OVERFLOW_KEEP_RECENT_WINDOW_RATIO));
+    const settings = {
+        ...DEFAULT_COMPACTION_SETTINGS,
+        keepRecentTokens,
+    };
+    // No `pinLatestUserMessage`: in a subagent the task prompt is the FIRST (and
+    // usually only) user message, so pinning it would pull the cut to the start
+    // and summarize nothing. The task prompt is preserved verbatim below instead.
+    const preparation = prepareCompaction(entries, settings, {
+        phaseBoundary: false,
+    });
+    if (!preparation)
+        return undefined;
+    // Nothing to summarize (the whole transcript is the recent tail) → the
+    // compaction would not shrink the request, so there is nothing to recover.
+    // A split-turn cut summarizes via `turnPrefixMessages` instead of
+    // `messagesToSummarize`, so both must be empty to be a true no-op.
+    if (preparation.messagesToSummarize.length === 0 &&
+        preparation.turnPrefixMessages.length === 0) {
+        return undefined;
+    }
+    const compactResult = compactDcpLite(preparation);
+    const firstKeptIndex = entries.findIndex((entry) => entry.id === compactResult.firstKeptEntryId);
+    const keptTail = working.slice(firstKeptIndex >= 0 ? firstKeptIndex : 0);
+    if (keptTail.length === 0)
+        return undefined;
+    const summaryMessage = createCompactionSummaryMessage(compactResult.summary, compactResult.tokensBefore, new Date().toISOString());
+    // Preserve the task prompt (first user message) verbatim if the cut
+    // summarized it away — the DCP-lite summary only keeps a bounded excerpt,
+    // and the goal must survive compaction intact.
+    const firstUserIndex = working.findIndex((m) => m.role === "user");
+    const taskPrompt = firstUserIndex >= 0 && firstKeptIndex > firstUserIndex
+        ? working[firstUserIndex]
+        : undefined;
+    return taskPrompt
+        ? [taskPrompt, summaryMessage, ...keptTail]
+        : [summaryMessage, ...keptTail];
+}
+/** Fraction of the window a single message may occupy before the guard cuts it. */
+const MAX_SINGLE_MESSAGE_WINDOW_RATIO = 0.5;
+/** Target size (fraction of the window) a truncated message is cut to. */
+const TRUNCATED_MESSAGE_TARGET_WINDOW_RATIO = 0.4;
+/** Rough chars-per-token heuristic for turning a token budget into a char cap. */
+const CHARS_PER_TOKEN = 4;
+/**
+ * Deterministic single-message size guard.
+ *
+ * If a SINGLE message's estimated tokens exceed ~50% of the model context
+ * window, its text content is truncated to a safe cap and a marker note is
+ * appended. This keeps the provider request sub-window even when one oversized
+ * message (e.g. a giant file read) would otherwise push the request over the
+ * limit and yield a silent 400. Purely local — no LLM calls. Returns the
+ * original array unchanged when no message needs truncation.
+ */
+export function guardOversizedMessages(messages, contextWindow) {
+    if (!Number.isFinite(contextWindow) || contextWindow <= 0)
+        return messages;
+    const thresholdTokens = contextWindow * MAX_SINGLE_MESSAGE_WINDOW_RATIO;
+    const targetChars = Math.floor(contextWindow * TRUNCATED_MESSAGE_TARGET_WINDOW_RATIO * CHARS_PER_TOKEN);
+    let changed = false;
+    const guarded = messages.map((message) => {
+        if (estimateTokens(message) <= thresholdTokens)
+            return message;
+        changed = true;
+        return truncateMessageToSafeCap(message, targetChars);
+    });
+    return changed ? guarded : messages;
+}
+/**
+ * Truncate a message's text content to `targetChars`, appending a marker note.
+ * Non-text parts (images, tool calls) are preserved. Returns the message
+ * unchanged when its text is already within the cap.
+ */
+function truncateMessageToSafeCap(message, targetChars) {
+    const rawContent = message.content;
+    const parts = Array.isArray(rawContent)
+        ? rawContent
+        : typeof rawContent === "string"
+            ? [{ type: "text", text: rawContent }]
+            : [];
+    const textParts = parts.filter((part) => part.type === "text" && typeof part.text === "string");
+    const totalText = textParts.map((part) => part.text).join("\n");
+    if (totalText.length <= targetChars)
+        return message;
+    const omitted = totalText.length - targetChars;
+    const truncatedText = totalText.slice(0, targetChars) +
+        `\n[spectral: truncated ${omitted} chars to fit context window]`;
+    const nonTextParts = parts.filter((part) => part.type !== "text");
+    return {
+        ...message,
+        content: [{ type: "text", text: truncatedText }, ...nonTextParts],
+    };
+}
+// ---------------------------------------------------------------------------
 // Core — run a single subagent in-process via agentLoop
 // ---------------------------------------------------------------------------
 async function runSingleAgent(defaultCwd, agents, activePrimary, agentName, task, cwd, step, signal, onUpdate, makeDetails, parentToolCallId, onInternalEvent, ext, ctx, maxRetries) {
@@ -662,23 +828,39 @@ async function runSingleAgent(defaultCwd, agents, activePrimary, agentName, task
             model,
             apiKey: auth.apiKey,
             headers: auth.headers,
-            convertToLlm: (msgs) => msgs.filter((m) => m.role === "user" || m.role === "assistant" || m.role === "toolResult"),
+            // Full converter so a compact-and-retry's `compactionSummary` message
+            // is sent to the LLM (the old role filter would have silently dropped
+            // it, defeating the compaction). Standard user/assistant/toolResult
+            // messages pass through unchanged.
+            convertToLlm: (msgs) => convertToLlm(msgs),
             toolExecution: "parallel",
             transformContext: async (messages) => {
                 // Pure request-time DCP adapter: policy-derived, invocation-local, and
                 // never connected to the parent Runtime or SessionManager.
+                let transformed = messages;
                 try {
                     const pruned = buildIsolatedRequestTimePrunedMessagesResult(messages, undefined, undefined, isolatedPruneFrozen, model.contextWindow);
                     isolatedPruneFrozen = pruned.frozen;
-                    return pruned.messages;
+                    transformed = pruned.messages;
+                }
+                catch {
+                    transformed = messages;
+                }
+                // Deterministic single-message guard: if one message is ~50%+ of
+                // the window, truncate it so the provider gets a sub-window request
+                // instead of a silent 400. Request-time only (no mutation, no LLM).
+                try {
+                    transformed = guardOversizedMessages(transformed, model.contextWindow);
                 }
                 catch {
-                    return messages;
+                    // Leave the (already pruned) messages as-is on an unexpected
+                    // guard failure — never block the request on the guard.
                 }
+                return transformed;
             },
             afterToolCall: async ({ toolCall, args, result, isError }) => {
                 try {
-                    const content = compressSubagentToolResult(toolCall.name, args, result, ctx);
+                    const content = compressSubagentToolResult(toolCall.name, args, result, ctx, isError);
                     return content ? { content, details: result.details, isError, terminate: result.terminate } : undefined;
                 }
                 catch {
@@ -702,6 +884,10 @@ async function runSingleAgent(defaultCwd, agents, activePrimary, agentName, task
         const collectedMessages = [];
         let hadError = false;
         let segments = 0;
+        // Compact-and-retry budget for context overflow. Separate from the
+        // transient-error retry budget (`maxSegments`) so recovering an overflow
+        // does not consume transient retries (and vice versa).
+        let overflowCompactions = 0;
         // Per-LLM-round timing stamps (TPS contract), mirroring the bridge's
         // main-session `pending` stamps: message_start opens the round, the
         // first text/thinking delta ends the TTFT window, message_end closes it.
@@ -854,8 +1040,6 @@ async function runSingleAgent(defaultCwd, agents, activePrimary, agentName, task
                 // Stream result error — already handled by message events
             }
             // ── Run-level retry decision (mirrors AgentSession._prepareRetry) ──
-            if (segments >= maxSegments)
-                break;
             if (currentResult.stopReason !== "error")
                 break;
             // Abort after a completed segment (parent stop or budget timeout):
@@ -867,13 +1051,55 @@ async function runSingleAgent(defaultCwd, agents, activePrimary, agentName, task
             // Explicit for parity with AgentSession._isRetryableError.
             if (isPaymentRequiredError(errorMessage))
                 break;
-            // Context overflow is a hard failure, not transient. It must be
-            // checked before the classifiers because overflow messages can
-            // contain bare status-code-like numerals (e.g. "501234 tokens >
-            // 500000 maximum").
+            // Context overflow is NOT transient — it is recovered with a
+            // deterministic DCP-lite compact-and-retry on a SEPARATE budget
+            // (`overflowCompactions`), so it does not consume the transient
+            // retry budget (`maxSegments`). Checked before the transient
+            // classifiers because overflow messages can contain bare
+            // status-code-like numerals (e.g. "501234 tokens > 500000 maximum").
             if (isContextOverflow(buildOverflowProbe(errorMessage), model.contextWindow)) {
-                break;
+                if (overflowCompactions >= MAX_OVERFLOW_COMPACT_RETRIES) {
+                    // Second overflow after compaction: recovery is exhausted.
+                    currentResult.stopReason = "error";
+                    const message = "Context overflow recovery failed after compact-and-retry attempts. Try reducing context or switching to a larger-context model.";
+                    currentResult.errorMessage = message;
+                    currentResult.stderr = message;
+                    break;
+                }
+                let compacted;
+                try {
+                    compacted = compactMessagesForOverflow(collectedMessages, model.contextWindow);
+                }
+                catch (err) {
+                    console.error(`[subagent] overflow compaction failed: ${err instanceof Error ? err.message : String(err)}`);
+                    compacted = undefined;
+                }
+                if (!compacted) {
+                    // Nothing compactable (e.g. only the task prompt) or the cut
+                    // could not be computed: hard-fail with a clear message.
+                    currentResult.stopReason = "error";
+                    const message = "Context overflow: no compactable history to summarize. Try reducing context or switching to a larger-context model.";
+                    currentResult.errorMessage = message;
+                    currentResult.stderr = message;
+                    break;
+                }
+                // Apply the compacted state and resume on the next iteration via
+                // agentLoopContinue (the last kept message is a toolResult/user).
+                collectedMessages.length = 0;
+                for (const msg of compacted)
+                    collectedMessages.push(msg);
+                currentResult.messages = [...collectedMessages];
+                // Reset the frozen request-time prune so the new (smaller)
+                // prefix re-freezes and stays byte-stable within the resumed run.
+                isolatedPruneFrozen = null;
+                overflowCompactions += 1;
+                continue;
             }
+            // Transient provider error: bounded by the maxSegments retry budget.
+            // Compact-and-retry segments are excluded so overflow recovery does
+            // not consume the transient budget.
+            if (segments - overflowCompactions >= maxSegments)
+                break;
             if (!isRateLimitError(errorMessage) && !isTransientApiError(errorMessage)) {
                 break;
             }

package/dist/generated/zeus/const.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"const.d.ts","sourceRoot":"","sources":["../../../src/generated/zeus/const.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAC,GAAG,CA47B5C,CAAA;AAED,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAC,GAAG,CA24C1C,CAAA;AAED,eAAO,MAAM,GAAG;;;;CAIf,CAAA"}
+{"version":3,"file":"const.d.ts","sourceRoot":"","sources":["../../../src/generated/zeus/const.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAC,GAAG,CA47B5C,CAAA;AAED,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAC,GAAG,CAg5C1C,CAAA;AAED,eAAO,MAAM,GAAG;;;;CAIf,CAAA"}

package/dist/generated/zeus/const.js

@@ -91,8 +91,8 @@ export const AllTypesProps = {
     UpdateLeadInput: {
         leadType: "LeadType"
     },
-    IngestCloudDocumentInput: {},
     UpdateCloudDocumentInput: {},
+    RequestCloudDocumentUploadInput: {},
     InferenceStatus: "enum",
     RegisterInput: {},
     LoginInput: {},
@@ -319,8 +319,8 @@ export const AllTypesProps = {
             input: "GenerateAexolFromTextInput"
         },
         cancelFromTask: {},
-        ingestCloudDocument: {
-            input: "IngestCloudDocumentInput"
+        requestCloudDocumentUpload: {
+            input: "RequestCloudDocumentUploadInput"
         },
         updateCloudDocument: {
             input: "UpdateCloudDocumentInput"
@@ -967,6 +967,11 @@ export const ReturnTypes = {
         score: "Float",
         content: "String"
     },
+    CloudDocumentUpload: {
+        id: "ID",
+        putUrl: "String",
+        expiresAt: "DateTime"
+    },
     TokenUsage: {
         inputTokens: "Long",
         outputTokens: "Long",
@@ -1199,7 +1204,7 @@ export const ReturnTypes = {
         deleteProjectFile: "Boolean",
         generateAexolFromText: "FromTask",
         cancelFromTask: "Boolean",
-        ingestCloudDocument: "CloudDocument",
+        requestCloudDocumentUpload: "CloudDocumentUpload",
         updateCloudDocument: "CloudDocument",
         deleteCloudDocument: "Boolean",
         cleanupOrphanCloudChunks: "Int",

package/dist/generated/zeus/index.d.ts

@@ -940,15 +940,6 @@ export type ValueTypes = {
         __typename?: boolean | `@${string}`;
         ['...on CloudSearchResult']?: Omit<ValueTypes["CloudSearchResult"], "...on CloudSearchResult">;
     }>;
-    ["IngestCloudDocumentInput"]: {
-        teamId: ValueTypes["ID"] | Variable<any, string>;
-        projectId: ValueTypes["ID"] | Variable<any, string>;
-        name: string | Variable<any, string>;
-        contentType: string | Variable<any, string>;
-        content: string | Variable<any, string>;
-        metadata?: string | undefined | null | Variable<any, string>;
-        tags?: string | undefined | null | Variable<any, string>;
-    };
     ["UpdateCloudDocumentInput"]: {
         name?: string | undefined | null | Variable<any, string>;
         contentType?: string | undefined | null | Variable<any, string>;
@@ -956,6 +947,22 @@ export type ValueTypes = {
         metadata?: string | undefined | null | Variable<any, string>;
         tags?: string | undefined | null | Variable<any, string>;
     };
+    ["RequestCloudDocumentUploadInput"]: {
+        teamId: ValueTypes["ID"] | Variable<any, string>;
+        projectId: ValueTypes["ID"] | Variable<any, string>;
+        name: string | Variable<any, string>;
+        contentType: string | Variable<any, string>;
+        contentLength?: number | undefined | null | Variable<any, string>;
+        metadata?: string | undefined | null | Variable<any, string>;
+        tags?: string | undefined | null | Variable<any, string>;
+    };
+    ["CloudDocumentUpload"]: AliasType<{
+        id?: boolean | `@${string}`;
+        putUrl?: boolean | `@${string}`;
+        expiresAt?: boolean | `@${string}`;
+        __typename?: boolean | `@${string}`;
+        ['...on CloudDocumentUpload']?: Omit<ValueTypes["CloudDocumentUpload"], "...on CloudDocumentUpload">;
+    }>;
     ["InferenceStatus"]: InferenceStatus;
     ["TokenUsage"]: AliasType<{
         inputTokens?: boolean | `@${string}`;
@@ -1627,9 +1634,9 @@ export type ValueTypes = {
         cancelFromTask?: [{
             taskId: ValueTypes["ID"] | Variable<any, string>;
         }, boolean | `@${string}`];
-        ingestCloudDocument?: [{
-            input: ValueTypes["IngestCloudDocumentInput"] | Variable<any, string>;
-        }, ValueTypes["CloudDocument"]];
+        requestCloudDocumentUpload?: [{
+            input: ValueTypes["RequestCloudDocumentUploadInput"] | Variable<any, string>;
+        }, ValueTypes["CloudDocumentUpload"]];
         updateCloudDocument?: [{
             id: ValueTypes["ID"] | Variable<any, string>;
             teamId: ValueTypes["ID"] | Variable<any, string>;
@@ -3767,15 +3774,6 @@ export type ResolverInputTypes = {
         content?: boolean | `@${string}`;
         __typename?: boolean | `@${string}`;
     }>;
-    ["IngestCloudDocumentInput"]: {
-        teamId: ResolverInputTypes["ID"];
-        projectId: ResolverInputTypes["ID"];
-        name: string;
-        contentType: string;
-        content: string;
-        metadata?: string | undefined | null;
-        tags?: string | undefined | null;
-    };
     ["UpdateCloudDocumentInput"]: {
         name?: string | undefined | null;
         contentType?: string | undefined | null;
@@ -3783,6 +3781,21 @@ export type ResolverInputTypes = {
         metadata?: string | undefined | null;
         tags?: string | undefined | null;
     };
+    ["RequestCloudDocumentUploadInput"]: {
+        teamId: ResolverInputTypes["ID"];
+        projectId: ResolverInputTypes["ID"];
+        name: string;
+        contentType: string;
+        contentLength?: number | undefined | null;
+        metadata?: string | undefined | null;
+        tags?: string | undefined | null;
+    };
+    ["CloudDocumentUpload"]: AliasType<{
+        id?: boolean | `@${string}`;
+        putUrl?: boolean | `@${string}`;
+        expiresAt?: boolean | `@${string}`;
+        __typename?: boolean | `@${string}`;
+    }>;
     ["InferenceStatus"]: InferenceStatus;
     ["TokenUsage"]: AliasType<{
         inputTokens?: boolean | `@${string}`;
@@ -4441,9 +4454,9 @@ export type ResolverInputTypes = {
         cancelFromTask?: [{
             taskId: ResolverInputTypes["ID"];
         }, boolean | `@${string}`];
-        ingestCloudDocument?: [{
-            input: ResolverInputTypes["IngestCloudDocumentInput"];
-        }, ResolverInputTypes["CloudDocument"]];
+        requestCloudDocumentUpload?: [{
+            input: ResolverInputTypes["RequestCloudDocumentUploadInput"];
+        }, ResolverInputTypes["CloudDocumentUpload"]];
         updateCloudDocument?: [{
             id: ResolverInputTypes["ID"];
             teamId: ResolverInputTypes["ID"];
@@ -6476,21 +6489,26 @@ export type ModelTypes = {
         score: number;
         content: string;
     };
-    ["IngestCloudDocumentInput"]: {
+    ["UpdateCloudDocumentInput"]: {
+        name?: string | undefined | null;
+        contentType?: string | undefined | null;
+        content?: string | undefined | null;
+        metadata?: string | undefined | null;
+        tags?: string | undefined | null;
+    };
+    ["RequestCloudDocumentUploadInput"]: {
         teamId: ModelTypes["ID"];
         projectId: ModelTypes["ID"];
         name: string;
         contentType: string;
-        content: string;
+        contentLength?: number | undefined | null;
         metadata?: string | undefined | null;
         tags?: string | undefined | null;
     };
-    ["UpdateCloudDocumentInput"]: {
-        name?: string | undefined | null;
-        contentType?: string | undefined | null;
-        content?: string | undefined | null;
-        metadata?: string | undefined | null;
-        tags?: string | undefined | null;
+    ["CloudDocumentUpload"]: {
+        id: ModelTypes["ID"];
+        putUrl: string;
+        expiresAt?: ModelTypes["DateTime"] | undefined | null;
     };
     ["InferenceStatus"]: InferenceStatus;
     ["TokenUsage"]: {
@@ -6787,7 +6805,7 @@ export type ModelTypes = {
         deleteProjectFile: boolean;
         generateAexolFromText: ModelTypes["FromTask"];
         cancelFromTask: boolean;
-        ingestCloudDocument: ModelTypes["CloudDocument"];
+        requestCloudDocumentUpload: ModelTypes["CloudDocumentUpload"];
         updateCloudDocument: ModelTypes["CloudDocument"];
         deleteCloudDocument: boolean;
         cleanupOrphanCloudChunks: number;
@@ -8548,21 +8566,28 @@ export type GraphQLTypes = {
         content: string;
         ['...on CloudSearchResult']: Omit<GraphQLTypes["CloudSearchResult"], "...on CloudSearchResult">;
     };
-    ["IngestCloudDocumentInput"]: {
+    ["UpdateCloudDocumentInput"]: {
+        name?: string | undefined | null;
+        contentType?: string | undefined | null;
+        content?: string | undefined | null;
+        metadata?: string | undefined | null;
+        tags?: string | undefined | null;
+    };
+    ["RequestCloudDocumentUploadInput"]: {
         teamId: GraphQLTypes["ID"];
         projectId: GraphQLTypes["ID"];
         name: string;
         contentType: string;
-        content: string;
+        contentLength?: number | undefined | null;
         metadata?: string | undefined | null;
         tags?: string | undefined | null;
     };
-    ["UpdateCloudDocumentInput"]: {
-        name?: string | undefined | null;
-        contentType?: string | undefined | null;
-        content?: string | undefined | null;
-        metadata?: string | undefined | null;
-        tags?: string | undefined | null;
+    ["CloudDocumentUpload"]: {
+        __typename: "CloudDocumentUpload";
+        id: GraphQLTypes["ID"];
+        putUrl: string;
+        expiresAt?: GraphQLTypes["DateTime"] | undefined | null;
+        ['...on CloudDocumentUpload']: Omit<GraphQLTypes["CloudDocumentUpload"], "...on CloudDocumentUpload">;
     };
     ["InferenceStatus"]: InferenceStatus;
     ["TokenUsage"]: {
@@ -8886,7 +8911,7 @@ export type GraphQLTypes = {
         deleteProjectFile: boolean;
         generateAexolFromText: GraphQLTypes["FromTask"];
         cancelFromTask: boolean;
-        ingestCloudDocument: GraphQLTypes["CloudDocument"];
+        requestCloudDocumentUpload: GraphQLTypes["CloudDocumentUpload"];
         updateCloudDocument: GraphQLTypes["CloudDocument"];
         deleteCloudDocument: boolean;
         cleanupOrphanCloudChunks: number;
@@ -10307,8 +10332,8 @@ type ZEUS_VARIABLES = {
     ["UpdateLeadStatusInput"]: ValueTypes["UpdateLeadStatusInput"];
     ["CreateLeadInput"]: ValueTypes["CreateLeadInput"];
     ["UpdateLeadInput"]: ValueTypes["UpdateLeadInput"];
-    ["IngestCloudDocumentInput"]: ValueTypes["IngestCloudDocumentInput"];
     ["UpdateCloudDocumentInput"]: ValueTypes["UpdateCloudDocumentInput"];
+    ["RequestCloudDocumentUploadInput"]: ValueTypes["RequestCloudDocumentUploadInput"];
     ["InferenceStatus"]: ValueTypes["InferenceStatus"];
     ["RegisterInput"]: ValueTypes["RegisterInput"];
     ["LoginInput"]: ValueTypes["LoginInput"];