@illuma-ai/agents 1.0.94 → 1.0.98

package/dist/cjs/common/constants.cjs

@@ -19,7 +19,32 @@ const MIN_THINKING_BUDGET = 1024;
  * compounding across multi-tool conversations (e.g., 10 tool calls).
  */
 const TOOL_TURN_THINKING_BUDGET = 1024;
+// ============================================================================
+// CONTEXT OVERFLOW MANAGEMENT
+//
+// Context overflow is handled mechanically — no token budget numbers are
+// exposed to the LLM. The system uses: pruning (Graph), summarization
+// (summarizeCallback), and auto-continuation (client.js max_tokens detection).
+//
+// See: docs/context-overflow-architecture.md
+// ============================================================================
+/**
+ * Minimum number of attached documents before the multi-document delegation
+ * hint is injected. Below this threshold, the agent processes documents
+ * directly within its own context.
+ */
+const MULTI_DOCUMENT_THRESHOLD = 3;
+/**
+ * Context utilization safety buffer multiplier (0-1).
+ * Applied as: effectiveMax = (maxContextTokens - maxOutputTokens) * CONTEXT_SAFETY_BUFFER
+ *
+ * Reserves headroom so the LLM doesn't hit hard token limits mid-generation.
+ * 0.9 = 10% reserved for safety.
+ */
+const CONTEXT_SAFETY_BUFFER = 0.9;
 
+exports.CONTEXT_SAFETY_BUFFER = CONTEXT_SAFETY_BUFFER;
 exports.MIN_THINKING_BUDGET = MIN_THINKING_BUDGET;
+exports.MULTI_DOCUMENT_THRESHOLD = MULTI_DOCUMENT_THRESHOLD;
 exports.TOOL_TURN_THINKING_BUDGET = TOOL_TURN_THINKING_BUDGET;
 //# sourceMappingURL=constants.cjs.map

package/dist/cjs/common/constants.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"constants.cjs","sources":["../../../src/common/constants.ts"],"sourcesContent":["// src/common/constants.ts\n\n/**\n * Minimum thinking budget allowed by the Anthropic API.\n * Extended thinking requires at least 1024 budget_tokens.\n * @see https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking\n */\nexport const MIN_THINKING_BUDGET = 1024;\n\n/**\n * Reduced thinking budget for subsequent ReAct iterations (tool-result turns).\n *\n * In a ReAct agent loop, the first LLM call processes the user's query and\n * may need deep reasoning. Subsequent iterations (after tool results return)\n * typically only need to decide \"call next tool\" or \"generate final response\"\n * — 1024 tokens is sufficient for this routing logic.\n *\n * This reduces wall-clock time per iteration from ~20-30s to ~5-10s,\n * compounding across multi-tool conversations (e.g., 10 tool calls).\n */\nexport const TOOL_TURN_THINKING_BUDGET = 1024;\n"],"names":[],"mappings":";;AAAA;AAEA;;;;AAIG;AACI,MAAM,mBAAmB,GAAG;AAEnC;;;;;;;;;;AAUG;AACI,MAAM,yBAAyB,GAAG;;;;;"}
+{"version":3,"file":"constants.cjs","sources":["../../../src/common/constants.ts"],"sourcesContent":["// src/common/constants.ts\n\n/**\n * Minimum thinking budget allowed by the Anthropic API.\n * Extended thinking requires at least 1024 budget_tokens.\n * @see https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking\n */\nexport const MIN_THINKING_BUDGET = 1024;\n\n/**\n * Reduced thinking budget for subsequent ReAct iterations (tool-result turns).\n *\n * In a ReAct agent loop, the first LLM call processes the user's query and\n * may need deep reasoning. Subsequent iterations (after tool results return)\n * typically only need to decide \"call next tool\" or \"generate final response\"\n * — 1024 tokens is sufficient for this routing logic.\n *\n * This reduces wall-clock time per iteration from ~20-30s to ~5-10s,\n * compounding across multi-tool conversations (e.g., 10 tool calls).\n */\nexport const TOOL_TURN_THINKING_BUDGET = 1024;\n\n// ============================================================================\n// CONTEXT OVERFLOW MANAGEMENT\n//\n// Context overflow is handled mechanically — no token budget numbers are\n// exposed to the LLM. The system uses: pruning (Graph), summarization\n// (summarizeCallback), and auto-continuation (client.js max_tokens detection).\n//\n// See: docs/context-overflow-architecture.md\n// ============================================================================\n\n/**\n * Minimum number of attached documents before the multi-document delegation\n * hint is injected. Below this threshold, the agent processes documents\n * directly within its own context.\n */\nexport const MULTI_DOCUMENT_THRESHOLD = 3;\n\n/**\n * Context utilization safety buffer multiplier (0-1).\n * Applied as: effectiveMax = (maxContextTokens - maxOutputTokens) * CONTEXT_SAFETY_BUFFER\n *\n * Reserves headroom so the LLM doesn't hit hard token limits mid-generation.\n * 0.9 = 10% reserved for safety.\n */\nexport const CONTEXT_SAFETY_BUFFER = 0.9;\n"],"names":[],"mappings":";;AAAA;AAEA;;;;AAIG;AACI,MAAM,mBAAmB,GAAG;AAEnC;;;;;;;;;;AAUG;AACI,MAAM,yBAAyB,GAAG;AAEzC;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AAEA;;;;AAIG;AACI,MAAM,wBAAwB,GAAG;AAExC;;;;;;AAMG;AACI,MAAM,qBAAqB,GAAG;;;;;;;"}

package/dist/cjs/events.cjs

@@ -32,10 +32,6 @@ class ModelEndHandler {
         if (metadata.ls_provider === 'FakeListChatModel') {
             return handlers.handleToolCalls(data?.output?.tool_calls, metadata, graph);
         }
-        console.log(`====== ${event.toUpperCase()} ======`);
-        console.dir({
-            usage,
-        }, { depth: null });
         const agentContext = graph.getAgentContext(metadata);
         if (agentContext.provider !== _enum.Providers.GOOGLE &&
             agentContext.provider !== _enum.Providers.BEDROCK) {

package/dist/cjs/events.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"events.cjs","sources":["../../src/events.ts"],"sourcesContent":["/* eslint-disable no-console */\n// src/events.ts\nimport type {\n  BaseMessageFields,\n  UsageMetadata,\n} from '@langchain/core/messages';\nimport type { MultiAgentGraph, StandardGraph } from '@/graphs';\nimport type { Logger } from 'winston';\nimport type * as t from '@/types';\nimport { handleToolCalls } from '@/tools/handlers';\nimport { Constants, Providers } from '@/common';\n\nexport class HandlerRegistry {\n  private handlers: Map<string, t.EventHandler> = new Map();\n\n  register(eventType: string, handler: t.EventHandler): void {\n    this.handlers.set(eventType, handler);\n  }\n\n  getHandler(eventType: string): t.EventHandler | undefined {\n    return this.handlers.get(eventType);\n  }\n}\n\nexport class ModelEndHandler implements t.EventHandler {\n  collectedUsage?: UsageMetadata[];\n  constructor(collectedUsage?: UsageMetadata[]) {\n    if (collectedUsage && !Array.isArray(collectedUsage)) {\n      throw new Error('collectedUsage must be an array');\n    }\n    this.collectedUsage = collectedUsage;\n  }\n\n  async handle(\n    event: string,\n    data: t.ModelEndData,\n    metadata?: Record<string, unknown>,\n    graph?: StandardGraph | MultiAgentGraph\n  ): Promise<void> {\n    if (!graph || !metadata) {\n      console.warn(`Graph or metadata not found in ${event} event`);\n      return;\n    }\n\n    const usage = data?.output?.usage_metadata;\n    if (usage != null && this.collectedUsage != null) {\n      this.collectedUsage.push(usage);\n    }\n\n    if (metadata.ls_provider === 'FakeListChatModel') {\n      return handleToolCalls(data?.output?.tool_calls, metadata, graph);\n    }\n\n    console.log(`====== ${event.toUpperCase()} ======`);\n    console.dir(\n      {\n        usage,\n      },\n      { depth: null }\n    );\n\n    const agentContext = graph.getAgentContext(metadata);\n\n    if (\n      agentContext.provider !== Providers.GOOGLE &&\n      agentContext.provider !== Providers.BEDROCK\n    ) {\n      return;\n    }\n\n    await handleToolCalls(data?.output?.tool_calls, metadata, graph);\n  }\n}\n\nexport class ToolEndHandler implements t.EventHandler {\n  private callback?: t.ToolEndCallback;\n  private logger?: Logger;\n  constructor(callback?: t.ToolEndCallback, logger?: Logger) {\n    this.callback = callback;\n    this.logger = logger;\n  }\n\n  /**\n   * Handles on_tool_end events from the for-await stream consumer.\n   *\n   * This handler is now purely a consumer callback — tool completion\n   * (ON_RUN_STEP_COMPLETED dispatch + session context storage) is handled\n   * in graph context by ToolNode directly, eliminating the race between\n   * the stream consumer and graph execution.\n   */\n  async handle(\n    event: string,\n    data: t.StreamEventData | undefined,\n    metadata?: Record<string, unknown>,\n    graph?: StandardGraph | MultiAgentGraph\n  ): Promise<void> {\n    try {\n      if (!graph || !metadata) {\n        if (this.logger) {\n          this.logger.warn(`Graph or metadata not found in ${event} event`);\n        } else {\n          console.warn(`Graph or metadata not found in ${event} event`);\n        }\n        return;\n      }\n\n      const toolEndData = data as t.ToolEndData | undefined;\n      if (!toolEndData?.output) {\n        if (this.logger) {\n          this.logger.warn('No output found in tool_end event');\n        } else {\n          console.warn('No output found in tool_end event');\n        }\n        return;\n      }\n\n      if (metadata[Constants.PROGRAMMATIC_TOOL_CALLING] === true) {\n        return;\n      }\n\n      if (this.callback) {\n        await this.callback(toolEndData, metadata);\n      }\n    } catch (error) {\n      if (this.logger) {\n        this.logger.error('Error handling tool_end event:', error);\n      } else {\n        console.error('Error handling tool_end event:', error);\n      }\n    }\n  }\n}\n\nexport class TestLLMStreamHandler implements t.EventHandler {\n  handle(event: string, data: t.StreamEventData | undefined): void {\n    const chunk = data?.chunk;\n    const isMessageChunk = !!(chunk && 'message' in chunk);\n    const msg = isMessageChunk ? chunk.message : undefined;\n    if (msg && msg.tool_call_chunks && msg.tool_call_chunks.length > 0) {\n      console.log(msg.tool_call_chunks);\n    } else if (msg && msg.content) {\n      if (typeof msg.content === 'string') {\n        process.stdout.write(msg.content);\n      }\n    }\n  }\n}\n\nexport class TestChatStreamHandler implements t.EventHandler {\n  handle(event: string, data: t.StreamEventData | undefined): void {\n    const chunk = data?.chunk;\n    const isContentChunk = !!(chunk && 'content' in chunk);\n    const content = isContentChunk && chunk.content;\n\n    if (!content || !isContentChunk) {\n      return;\n    }\n\n    if (chunk.tool_call_chunks && chunk.tool_call_chunks.length > 0) {\n      console.dir(chunk.tool_call_chunks, { depth: null });\n    }\n\n    if (typeof content === 'string') {\n      process.stdout.write(content);\n    } else {\n      console.dir(content, { depth: null });\n    }\n  }\n}\n\nexport class LLMStreamHandler implements t.EventHandler {\n  handle(\n    event: string,\n    data: t.StreamEventData | undefined,\n    metadata?: Record<string, unknown>\n  ): void {\n    const chunk = data?.chunk;\n    const isMessageChunk = !!(chunk && 'message' in chunk);\n    const msg = isMessageChunk && chunk.message;\n    if (metadata) {\n      console.log(metadata);\n    }\n    if (msg && msg.tool_call_chunks && msg.tool_call_chunks.length > 0) {\n      console.log(msg.tool_call_chunks);\n    } else if (msg && msg.content) {\n      if (typeof msg.content === 'string') {\n        // const text_delta = msg.content;\n        // dispatchCustomEvent(GraphEvents.CHAT_MODEL_STREAM, { chunk }, config);\n        process.stdout.write(msg.content);\n      }\n    }\n  }\n}\n\nexport const createMetadataAggregator = (\n  _collected?: Record<\n    string,\n    NonNullable<BaseMessageFields['response_metadata']>\n  >[]\n): t.MetadataAggregatorResult => {\n  const collected = _collected || [];\n\n  const handleLLMEnd: t.HandleLLMEnd = (output) => {\n    const { generations } = output;\n    const lastMessageOutput = (\n      generations[generations.length - 1] as\n        | (t.StreamGeneration | undefined)[]\n        | undefined\n    )?.[0];\n    if (!lastMessageOutput) {\n      return;\n    }\n    const { message } = lastMessageOutput;\n    if (message?.response_metadata) {\n      collected.push(message.response_metadata);\n    }\n  };\n\n  return { handleLLMEnd, collected };\n};\n"],"names":["handleToolCalls","Providers","Constants"],"mappings":"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"}
+{"version":3,"file":"events.cjs","sources":["../../src/events.ts"],"sourcesContent":["/* eslint-disable no-console */\n// src/events.ts\nimport type {\n  BaseMessageFields,\n  UsageMetadata,\n} from '@langchain/core/messages';\nimport type { MultiAgentGraph, StandardGraph } from '@/graphs';\nimport type { Logger } from 'winston';\nimport type * as t from '@/types';\nimport { handleToolCalls } from '@/tools/handlers';\nimport { Constants, Providers } from '@/common';\n\nexport class HandlerRegistry {\n  private handlers: Map<string, t.EventHandler> = new Map();\n\n  register(eventType: string, handler: t.EventHandler): void {\n    this.handlers.set(eventType, handler);\n  }\n\n  getHandler(eventType: string): t.EventHandler | undefined {\n    return this.handlers.get(eventType);\n  }\n}\n\nexport class ModelEndHandler implements t.EventHandler {\n  collectedUsage?: UsageMetadata[];\n  constructor(collectedUsage?: UsageMetadata[]) {\n    if (collectedUsage && !Array.isArray(collectedUsage)) {\n      throw new Error('collectedUsage must be an array');\n    }\n    this.collectedUsage = collectedUsage;\n  }\n\n  async handle(\n    event: string,\n    data: t.ModelEndData,\n    metadata?: Record<string, unknown>,\n    graph?: StandardGraph | MultiAgentGraph\n  ): Promise<void> {\n    if (!graph || !metadata) {\n      console.warn(`Graph or metadata not found in ${event} event`);\n      return;\n    }\n\n    const usage = data?.output?.usage_metadata;\n    if (usage != null && this.collectedUsage != null) {\n      this.collectedUsage.push(usage);\n    }\n\n    if (metadata.ls_provider === 'FakeListChatModel') {\n      return handleToolCalls(data?.output?.tool_calls, metadata, graph);\n    }\n\n    const agentContext = graph.getAgentContext(metadata);\n\n    if (\n      agentContext.provider !== Providers.GOOGLE &&\n      agentContext.provider !== Providers.BEDROCK\n    ) {\n      return;\n    }\n\n    await handleToolCalls(data?.output?.tool_calls, metadata, graph);\n  }\n}\n\nexport class ToolEndHandler implements t.EventHandler {\n  private callback?: t.ToolEndCallback;\n  private logger?: Logger;\n  constructor(callback?: t.ToolEndCallback, logger?: Logger) {\n    this.callback = callback;\n    this.logger = logger;\n  }\n\n  /**\n   * Handles on_tool_end events from the for-await stream consumer.\n   *\n   * This handler is now purely a consumer callback — tool completion\n   * (ON_RUN_STEP_COMPLETED dispatch + session context storage) is handled\n   * in graph context by ToolNode directly, eliminating the race between\n   * the stream consumer and graph execution.\n   */\n  async handle(\n    event: string,\n    data: t.StreamEventData | undefined,\n    metadata?: Record<string, unknown>,\n    graph?: StandardGraph | MultiAgentGraph\n  ): Promise<void> {\n    try {\n      if (!graph || !metadata) {\n        if (this.logger) {\n          this.logger.warn(`Graph or metadata not found in ${event} event`);\n        } else {\n          console.warn(`Graph or metadata not found in ${event} event`);\n        }\n        return;\n      }\n\n      const toolEndData = data as t.ToolEndData | undefined;\n      if (!toolEndData?.output) {\n        if (this.logger) {\n          this.logger.warn('No output found in tool_end event');\n        } else {\n          console.warn('No output found in tool_end event');\n        }\n        return;\n      }\n\n      if (metadata[Constants.PROGRAMMATIC_TOOL_CALLING] === true) {\n        return;\n      }\n\n      if (this.callback) {\n        await this.callback(toolEndData, metadata);\n      }\n    } catch (error) {\n      if (this.logger) {\n        this.logger.error('Error handling tool_end event:', error);\n      } else {\n        console.error('Error handling tool_end event:', error);\n      }\n    }\n  }\n}\n\nexport class TestLLMStreamHandler implements t.EventHandler {\n  handle(event: string, data: t.StreamEventData | undefined): void {\n    const chunk = data?.chunk;\n    const isMessageChunk = !!(chunk && 'message' in chunk);\n    const msg = isMessageChunk ? chunk.message : undefined;\n    if (msg && msg.tool_call_chunks && msg.tool_call_chunks.length > 0) {\n      console.log(msg.tool_call_chunks);\n    } else if (msg && msg.content) {\n      if (typeof msg.content === 'string') {\n        process.stdout.write(msg.content);\n      }\n    }\n  }\n}\n\nexport class TestChatStreamHandler implements t.EventHandler {\n  handle(event: string, data: t.StreamEventData | undefined): void {\n    const chunk = data?.chunk;\n    const isContentChunk = !!(chunk && 'content' in chunk);\n    const content = isContentChunk && chunk.content;\n\n    if (!content || !isContentChunk) {\n      return;\n    }\n\n    if (chunk.tool_call_chunks && chunk.tool_call_chunks.length > 0) {\n      console.dir(chunk.tool_call_chunks, { depth: null });\n    }\n\n    if (typeof content === 'string') {\n      process.stdout.write(content);\n    } else {\n      console.dir(content, { depth: null });\n    }\n  }\n}\n\nexport class LLMStreamHandler implements t.EventHandler {\n  handle(\n    event: string,\n    data: t.StreamEventData | undefined,\n    metadata?: Record<string, unknown>\n  ): void {\n    const chunk = data?.chunk;\n    const isMessageChunk = !!(chunk && 'message' in chunk);\n    const msg = isMessageChunk && chunk.message;\n    if (metadata) {\n      console.log(metadata);\n    }\n    if (msg && msg.tool_call_chunks && msg.tool_call_chunks.length > 0) {\n      console.log(msg.tool_call_chunks);\n    } else if (msg && msg.content) {\n      if (typeof msg.content === 'string') {\n        // const text_delta = msg.content;\n        // dispatchCustomEvent(GraphEvents.CHAT_MODEL_STREAM, { chunk }, config);\n        process.stdout.write(msg.content);\n      }\n    }\n  }\n}\n\nexport const createMetadataAggregator = (\n  _collected?: Record<\n    string,\n    NonNullable<BaseMessageFields['response_metadata']>\n  >[]\n): t.MetadataAggregatorResult => {\n  const collected = _collected || [];\n\n  const handleLLMEnd: t.HandleLLMEnd = (output) => {\n    const { generations } = output;\n    const lastMessageOutput = (\n      generations[generations.length - 1] as\n        | (t.StreamGeneration | undefined)[]\n        | undefined\n    )?.[0];\n    if (!lastMessageOutput) {\n      return;\n    }\n    const { message } = lastMessageOutput;\n    if (message?.response_metadata) {\n      collected.push(message.response_metadata);\n    }\n  };\n\n  return { handleLLMEnd, collected };\n};\n"],"names":["handleToolCalls","Providers","Constants"],"mappings":"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"}

package/dist/cjs/graphs/Graph.cjs

@@ -24,6 +24,7 @@ require('ai-tokenizer');
 require('../utils/toonFormat.cjs');
 var contextAnalytics = require('../utils/contextAnalytics.cjs');
 require('zod-to-json-schema');
+var contextPressure = require('../utils/contextPressure.cjs');
 var providers = require('../llm/providers.cjs');
 var ToolNode = require('../tools/ToolNode.cjs');
 var index = require('../llm/openai/index.cjs');
@@ -950,36 +951,12 @@ class StandardGraph extends Graph {
             let messagesToUse = messages$1;
             // ====================================================================
             // PRE-PRUNING DELEGATION CHECK
-            // Before pruning strips messages (losing context), check if we should
-            // delegate instead. If context would be pruned AND the agent has the
-            // task tool, inject a delegation hint and SKIP pruning — preserving
-            // the content for the LLM to understand what to delegate.
             // ====================================================================
-            let delegationInjectedPrePrune = false;
-            const hasTaskToolPrePrune = agentContext.tools?.some((tool) => {
-                const toolName = typeof tool === 'object' && 'name' in tool
-                    ? tool.name
-                    : '';
-                return toolName === 'task';
-            });
-            if (hasTaskToolPrePrune === true &&
-                agentContext.tokenCounter &&
-                agentContext.maxContextTokens != null) {
-                // Estimate total tokens in messages BEFORE pruning
-                let prePruneTokens = 0;
-                for (const msg of messages$1) {
-                    prePruneTokens += agentContext.tokenCounter(msg);
-                }
-                // Add instruction tokens (system prompt)
-                prePruneTokens += agentContext.instructionTokens;
-                const prePruneUtilization = (prePruneTokens / agentContext.maxContextTokens) * 100;
-                if (prePruneUtilization > 70) {
-                    console.warn(`[Graph] PRE-PRUNE delegation check: ${prePruneUtilization.toFixed(1)}% utilization ` +
-                        `(${prePruneTokens}/${agentContext.maxContextTokens} tokens). ` +
-                        'Injecting delegation hint INSTEAD of pruning.');
-                    delegationInjectedPrePrune = true;
-                }
-            }
+            // Context management is now fully mechanical:
+            // - Pruning always runs when needed (no delegation-based skip)
+            // - Auto-continuation in client.js handles max_tokens finish reason
+            // - LLM never sees raw token numbers (prevents voluntary bail-out)
+            // ====================================================================
             if (!agentContext.pruneMessages &&
                 agentContext.tokenCounter &&
                 agentContext.maxContextTokens != null &&
@@ -1002,8 +979,8 @@ class StandardGraph extends Graph {
                     indexTokenCountMap: agentContext.indexTokenCountMap,
                 });
             }
-            if (agentContext.pruneMessages && !delegationInjectedPrePrune) {
-                console.info(`[Graph:ContextMgmt] Pruning messages | inputCount=${messages$1.length} | maxTokens=${agentContext.maxContextTokens}`);
+            if (agentContext.pruneMessages) {
+                console.debug(`[Graph:ContextMgmt] Pruning messages | inputCount=${messages$1.length} | maxTokens=${agentContext.maxContextTokens}`);
                 const { context, indexTokenCountMap, messagesToRefine } = agentContext.pruneMessages({
                     messages: messages$1,
                     usageMetadata: agentContext.currentUsage,
@@ -1011,14 +988,16 @@ class StandardGraph extends Graph {
                 });
                 agentContext.indexTokenCountMap = indexTokenCountMap;
                 messagesToUse = context;
-                console.info(`[Graph:ContextMgmt] Pruned | kept=${context.length} | discarded=${messagesToRefine.length} | originalCount=${messages$1.length}`);
+                console.debug(`[Graph:ContextMgmt] Pruned | kept=${context.length} | discarded=${messagesToRefine.length} | originalCount=${messages$1.length}`);
                 // Summarize discarded messages if callback provided
+                let hasSummary = false;
                 if (messagesToRefine.length > 0 && agentContext.summarizeCallback) {
-                    console.info(`[Graph:ContextMgmt] Summarizing ${messagesToRefine.length} discarded messages`);
+                    console.debug(`[Graph:ContextMgmt] Summarizing ${messagesToRefine.length} discarded messages`);
                     try {
                         const summary = await agentContext.summarizeCallback(messagesToRefine);
-                        console.info(`[Graph:ContextMgmt] Summary received | len=${summary?.length ?? 0} | hasContent=${summary != null && summary !== ''}`);
+                        console.debug(`[Graph:ContextMgmt] Summary received | len=${summary?.length ?? 0} | hasContent=${summary != null && summary !== ''}`);
                         if (summary != null && summary !== '') {
+                            hasSummary = true;
                             const summaryMsg = new messages.SystemMessage(`[Conversation Summary]\n${summary}`);
                             // Insert after system message (if present), before conversation messages
                             const systemIdx = messagesToUse[0]?.getType() === 'system' ? 1 : 0;
@@ -1027,16 +1006,22 @@ class StandardGraph extends Graph {
                                 summaryMsg,
                                 ...messagesToUse.slice(systemIdx),
                             ];
-                            console.info(`[Graph:ContextMgmt] Summary injected at index ${systemIdx} | finalMsgCount=${messagesToUse.length}`);
+                            console.debug(`[Graph:ContextMgmt] Summary injected at index ${systemIdx} | finalMsgCount=${messagesToUse.length}`);
                         }
                     }
                     catch (err) {
                         console.error('[Graph] Summarization callback failed:', err);
                     }
                 }
-            }
-            else if (delegationInjectedPrePrune) {
-                console.info('[Graph] Skipping pruning — delegation will handle context pressure');
+                // Post-prune context note: inform the LLM that context was compressed
+                // without exposing token numbers (prevents voluntary bail-out)
+                if (messagesToRefine.length > 0 && contextPressure.hasTaskTool(agentContext.tools)) {
+                    const postPruneNote = contextPressure.buildPostPruneNote(messagesToRefine.length, hasSummary);
+                    if (postPruneNote) {
+                        messagesToUse = [...messagesToUse, new messages.SystemMessage(postPruneNote)];
+                        console.debug(`[Graph:ContextMgmt] Post-prune note injected | hasSummary=${hasSummary} | discarded=${messagesToRefine.length}`);
+                    }
+                }
             }
             let finalMessages = messagesToUse;
             if (agentContext.useLegacyContent) {
@@ -1149,125 +1134,30 @@ class StandardGraph extends Graph {
                 analytics: contextAnalytics$1,
             }, config);
             // ====================================================================
-            // CONTEXT PRESSURE AWARENESS — Intelligent Sub-Agent Delegation
-            //
-            // Two triggers for delegation hints:
-            // 1. DOCUMENT COUNT: When 3+ documents are detected in the conversation,
-            //    inject a delegation hint on the FIRST iteration (before the LLM
-            //    has called any tools). This ensures the agent delegates upfront
-            //    rather than trying to process all documents itself.
-            // 2. TOKEN UTILIZATION: At EVERY iteration, if context is filling up
-            //    (70%/85%), inject escalating hints to delegate remaining work.
+            // MULTI-DOCUMENT DELEGATION (task-driven, not budget-driven)
             //
-            // This runs mid-chain — so even if tool responses push context up
-            // after the first LLM call, subsequent iterations get the hint.
+            // Token-based pressure hints have been removed — the LLM never sees
+            // raw token numbers. Context overflow is handled mechanically by
+            // pruning (Graph) + auto-continuation (client.js max_tokens detection).
+            // See: docs/context-overflow-architecture.md
             // ====================================================================
-            const hasTaskToolInContext = agentContext.tools?.some((tool) => {
-                const toolName = typeof tool === 'object' && 'name' in tool
-                    ? tool.name
-                    : '';
-                return toolName === 'task';
-            });
-            if (hasTaskToolInContext === true &&
-                contextAnalytics$1.utilizationPercent != null &&
-                contextAnalytics$1.maxContextTokens != null) {
-                const utilization = contextAnalytics$1.utilizationPercent;
-                const totalTokens = contextAnalytics$1.totalTokens;
-                const maxTokens = contextAnalytics$1.maxContextTokens;
-                const remainingTokens = maxTokens - totalTokens;
-                // Count attached documents by scanning for document patterns in HumanMessages:
-                // 1. # "filename" headers in "Attached document(s):" blocks (text content)
-                // 2. **filename1, filename2** in "The user has attached:" blocks (embedded files)
-                // 3. Filenames in file_search tool results
-                let documentCount = 0;
-                const documentNames = [];
-                for (const msg of finalMessages) {
-                    const content = typeof msg.content === 'string'
-                        ? msg.content
-                        : Array.isArray(msg.content)
-                            ? msg.content
-                                .map((p) => {
-                                const part = p;
-                                return String(part.text ?? part.content ?? '');
-                            })
-                                .join(' ')
-                            : '';
-                    // Pattern 1: # "filename" headers in attached document blocks
-                    const docMatches = content.match(/# "([^"]+)"/g);
-                    if (docMatches) {
-                        for (const match of docMatches) {
-                            const name = match.replace(/# "/, '').replace(/"$/, '');
-                            if (!documentNames.includes(name)) {
-                                documentNames.push(name);
-                                documentCount++;
-                            }
-                        }
-                    }
-                    // Pattern 2: "The user has attached: **file1, file2**" (embedded files)
-                    const attachedMatch = content.match(/user has attached:\s*\*\*([^*]+)\*\*/i);
-                    if (attachedMatch) {
-                        const names = attachedMatch[1]
-                            .split(',')
-                            .map((n) => n.trim())
-                            .filter(Boolean);
-                        for (const name of names) {
-                            if (!documentNames.includes(name)) {
-                                documentNames.push(name);
-                                documentCount++;
-                            }
-                        }
-                    }
+            if (contextPressure.hasTaskTool(agentContext.tools)) {
+                const { count: documentCount, names: documentNames } = contextPressure.detectDocuments(finalMessages);
+                // Observability log (no token numbers exposed to LLM)
+                if (contextAnalytics$1.utilizationPercent != null) {
+                    console.debug(`[Graph] Context utilization: ${contextAnalytics$1.utilizationPercent.toFixed(1)}% | ` +
+                        `messages: ${finalMessages.length} | docs: ${documentCount}`);
                 }
-                // BASELINE LOG: Always fires so we can verify this code path runs
-                console.info(`[Graph] Context utilization: ${utilization.toFixed(1)}% ` +
-                    `(${totalTokens}/${maxTokens} tokens, ${remainingTokens} remaining) | ` +
-                    `hasTaskTool: true | messages: ${finalMessages.length} | docs: ${documentCount}`);
-                // TRIGGER 1: Multi-document delegation (3+ documents detected)
-                // Only inject on first iteration (no AI messages yet = agent hasn't responded)
+                // Multi-document delegation: first iteration only (before AI has responded)
                 const hasAiResponse = finalMessages.some((m) => m._getType() === 'ai' || m._getType() === 'tool');
-                if (documentCount >= 3 && !hasAiResponse) {
+                if (contextPressure.shouldInjectMultiDocHint(documentCount, hasAiResponse)) {
                     const pressureMsg = new messages.HumanMessage({
-                        content: `[MULTI-DOCUMENT PROCESSING — ${documentCount} documents detected]\n` +
-                            `Documents: ${documentNames.join(', ')}\n\n` +
-                            `You have ${documentCount} documents attached. For thorough analysis, use the "task" tool ` +
-                            'to delegate each document (or group of related documents) to a sub-agent.\n' +
-                            'Each sub-agent has its own fresh context window and can use file_search to retrieve the full document content.\n' +
-                            'After all sub-agents complete, synthesize their results into a comprehensive response.\n\n' +
-                            'This approach ensures each document gets full attention without context limitations.',
+                        content: contextPressure.buildMultiDocHintContent(documentCount, documentNames),
                     });
                     finalMessages = [...finalMessages, pressureMsg];
                     console.info(`[Graph] Multi-document delegation hint injected for ${documentCount} documents: ` +
                         `${documentNames.join(', ')}`);
                 }
-                // TRIGGER 2: Token utilization thresholds (mid-chain safety net)
-                // Also fires when we skipped pruning due to delegationInjectedPrePrune
-                if (utilization > 85 ||
-                    (delegationInjectedPrePrune && utilization > 50)) {
-                    // CRITICAL: Context is high — MANDATE delegation
-                    const pressureMsg = new messages.HumanMessage({
-                        content: `[CONTEXT BUDGET CRITICAL — ${utilization.toFixed(0)}% used]\n` +
-                            `You have used ${totalTokens} of ${maxTokens} tokens (${remainingTokens} remaining).\n` +
-                            'Your context is very large. You MUST use the "task" tool to delegate work to sub-agents.\n' +
-                            'Each sub-agent runs in its own fresh context window and can use file_search to access documents.\n' +
-                            'Do NOT attempt to process documents directly — delegate each document to a sub-agent, then synthesize results.',
-                    });
-                    finalMessages = [...finalMessages, pressureMsg];
-                    console.warn(`[Graph] Context pressure CRITICAL (${utilization.toFixed(0)}%): ` +
-                        `Injected mandatory delegation hint. ${remainingTokens} tokens remaining. ` +
-                        `prePruneSkipped: ${delegationInjectedPrePrune}`);
-                }
-                else if (utilization > 70) {
-                    // WARNING: Context filling up — suggest delegation
-                    const pressureMsg = new messages.HumanMessage({
-                        content: `[CONTEXT BUDGET WARNING — ${utilization.toFixed(0)}% used]\n` +
-                            `You have used ${totalTokens} of ${maxTokens} tokens (${remainingTokens} remaining).\n` +
-                            'Your context is filling up. Consider using the "task" tool to delegate complex operations to sub-agents.\n' +
-                            "Sub-agents run in fresh context windows and won't consume your remaining budget.",
-                    });
-                    finalMessages = [...finalMessages, pressureMsg];
-                    console.info(`[Graph] Context pressure WARNING (${utilization.toFixed(0)}%): ` +
-                        `Injected delegation suggestion. ${remainingTokens} tokens remaining.`);
-                }
             }
             // Structured output mode: when the agent has NO tools, produce structured JSON immediately.
             // When the agent HAS tools, we defer structured output until after tool use completes
@@ -1661,7 +1551,7 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
                 reducer: (a, b) => {
                     if (!a.length) {
                         this.startIndex = a.length + b.length;
-                        console.info(`[Graph:Reducer] Initial messages | startIndex=${this.startIndex} | inputMsgCount=${b.length}`);
+                        console.debug(`[Graph:Reducer] Initial messages | startIndex=${this.startIndex} | inputMsgCount=${b.length}`);
                     }
                     else {
                         console.debug(`[Graph:Reducer] Appending messages | existing=${a.length} | new=${b.length} | startIndex=${this.startIndex}`);