@librechat/agents 3.4.6 → 3.5.0

package/dist/cjs/agents/AgentContext.cjs

@@ -12,13 +12,7 @@ const require_schema$1 = require("../tools/schema.cjs");
 let _langchain_core_runnables = require("@langchain/core/runnables");
 let _langchain_core_messages = require("@langchain/core/messages");
 //#region src/agents/AgentContext.ts
-/**
-* Encapsulates agent-specific state that can vary between agents in a multi-agent system
-*/
 var AgentContext = class AgentContext {
-	/**
-	* Create an AgentContext from configuration with token accounting initialization
-	*/
 	static fromConfig(agentConfig, tokenCounter, indexTokenCountMap) {
 		const { agentId, name, provider, clientOptions, langfuse, tools, toolMap, toolEnd, toolRegistry, toolDefinitions, instructions, additional_instructions, streamBuffer, maxContextTokens, reasoningKey, useLegacyContent, discoveredTools, summarizationEnabled, summarizationConfig, initialSummary, contextPruningConfig, maxToolResultChars, toolSchemaTokens, subagentConfigs, maxSubagentDepth, graphTools } = agentConfig;
 		const agentContext = new AgentContext({
@@ -49,11 +43,6 @@ var AgentContext = class AgentContext {
 		agentContext._sourceInputs = agentConfig;
 		agentContext.subagentConfigs = subagentConfigs;
 		agentContext.maxSubagentDepth = maxSubagentDepth;
-		/**
-		* Host-supplied direct tools (see `AgentInputs.graphTools`). Copied — never
-		* aliased — because the SDK later pushes graph-managed tools (handoff /
-		* subagent) into this same array and must not mutate the host's input.
-		*/
 		if (graphTools && graphTools.length > 0) agentContext.graphTools = [...graphTools];
 		if (initialSummary?.text != null && initialSummary.text !== "") agentContext.setInitialSummary(initialSummary.text, initialSummary.tokenCount);
 		if (tokenCounter) {
@@ -62,7 +51,6 @@ var AgentContext = class AgentContext {
 			agentContext.baseIndexTokenCountMap = { ...tokenMap };
 			agentContext.indexTokenCountMap = tokenMap;
 			if (toolSchemaTokens != null && toolSchemaTokens > 0) {
-				/** Use pre-computed (cached) tool schema tokens — skip calculateInstructionTokens */
 				agentContext.toolSchemaTokens = toolSchemaTokens;
 				agentContext.tokenCalculationPromise = Promise.resolve();
 				agentContext.updateTokenMapWithInstructions(tokenMap);
@@ -77,60 +65,30 @@ var AgentContext = class AgentContext {
 		}
 		return agentContext;
 	}
-	/** Agent identifier */
 	agentId;
-	/** Human-readable name for this agent (used in handoff context). Falls back to agentId if not provided. */
 	name;
-	/** Provider for this specific agent */
 	provider;
-	/** Client options for this agent */
 	clientOptions;
-	/** Per-agent Langfuse tracing configuration. */
 	langfuse;
-	/** Token count map indexed by message position */
 	indexTokenCountMap = {};
-	/** Canonical pre-run token map used to restore token accounting on reset */
 	baseIndexTokenCountMap = {};
-	/** Maximum context tokens for this agent */
 	maxContextTokens;
-	/** Current usage metadata for this agent */
 	currentUsage;
-	/**
-	* Usage from the most recent LLM call only (not accumulated).
-	* Used for accurate provider calibration in pruning.
-	*/
 	lastCallUsage;
-	/**
-	* Whether totalTokens data is fresh (set true when provider usage arrives,
-	* false at the start of each turn before the LLM responds).
-	* Prevents stale token data from driving pruning/trigger decisions.
-	*/
 	totalTokensFresh = false;
-	/** Context pruning configuration. */
 	contextPruningConfig;
 	maxToolResultChars;
-	/** Prune messages function configured for this agent */
 	pruneMessages;
-	/** Token counter function for this agent */
 	tokenCounter;
-	/** Token count for the system message (instructions text). */
 	systemMessageTokens = 0;
-	/** Token count for instruction text emitted outside the system message. */
 	dynamicInstructionTokens = 0;
-	/** Token count for tool schemas only. */
 	toolSchemaTokens = 0;
-	/** Per-tool schema token counts (post-multiplier), keyed by tool name.
-	*  `undefined` when not calculated (e.g. cached aggregate schema tokens). */
 	toolTokenCounts;
-	/** Names of counted tools that are deferred (`defer_loading`) and discovered. */
 	deferredToolNames = [];
-	/** Running calibration ratio from the pruner — persisted across runs via contextMeta. */
 	calibrationRatio = 1;
-	/** Provider-observed instruction overhead from the pruner's best-variance turn. */
 	resolvedInstructionOverhead;
 	_pendingOriginalToolContent;
 	pendingOriginalToolContentChars = 0;
-	/** Pre-masking tool content keyed by message index, consumed by the summarize node. */
 	get pendingOriginalToolContent() {
 		return this._pendingOriginalToolContent;
 	}
@@ -142,117 +100,45 @@ var AgentContext = class AgentContext {
 			this.enforcePendingOriginalContentCap();
 		}
 	}
-	/** Total instruction overhead: system message + tool schemas + pending summary. */
 	get instructionTokens() {
 		const summaryOverhead = this._summaryLocation === "user_message" ? this.summaryTokenCount : 0;
 		return this.systemMessageTokens + this.dynamicInstructionTokens + this.toolSchemaTokens + summaryOverhead;
 	}
-	/** The amount of time that should pass before another consecutive API call */
 	streamBuffer;
-	/** Last stream call timestamp for rate limiting */
 	lastStreamCall;
-	/** Tools available to this agent */
 	tools;
-	/** Graph-managed tools (e.g., handoff tools created by MultiAgentGraph) that bypass event-driven dispatch */
 	graphTools;
-	/** Tool map for this agent */
 	toolMap;
-	/**
-	* Tool definitions registry (includes deferred and programmatic tool metadata).
-	* Used for tool search and programmatic tool calling.
-	*/
 	toolRegistry;
-	/**
-	* Serializable tool definitions for event-driven execution.
-	* When provided, ToolNode operates in event-driven mode.
-	*/
 	toolDefinitions;
-	/** Set of tool names discovered via tool search (to be loaded) */
 	discoveredToolNames = /* @__PURE__ */ new Set();
-	/** Original AgentInputs used to create this context — used for self-spawn subagent resolution. */
 	_sourceInputs;
-	/** Subagent configurations for hierarchical delegation. */
 	subagentConfigs;
-	/** Maximum subagent nesting depth. */
 	maxSubagentDepth;
-	/** Instructions for this agent */
 	instructions;
-	/** Additional instructions for this agent */
 	additionalInstructions;
-	/** Reasoning key for this agent */
 	reasoningKey = "reasoning_content";
-	/** Last token for reasoning detection */
 	lastToken;
-	/** Token type switch state */
 	tokenTypeSwitch;
-	/** Tracks how many reasoning→text transitions have occurred (ensures unique post-reasoning step keys) */
 	reasoningTransitionCount = 0;
-	/** Current token type being processed */
 	currentTokenType = "text";
-	/** Whether tools should end the workflow */
 	toolEnd = false;
-	/** Cached system runnable (created lazily) */
 	cachedSystemRunnable;
-	/** Whether system runnable needs rebuild (set when discovered tools change) */
 	systemRunnableStale = true;
-	/** Promise for token calculation initialization */
 	tokenCalculationPromise;
-	/** Format content blocks as strings (for legacy compatibility) */
 	useLegacyContent = false;
-	/** Enables graph-level summarization for this agent */
 	summarizationEnabled;
-	/** Summarization runtime settings used by graph pruning hooks */
 	summarizationConfig;
-	/** Current summary text produced by the summarize node, integrated into system message */
 	summaryText;
-	/** Token count of the current summary (tracked for token accounting) */
 	summaryTokenCount = 0;
-	/**
-	* Where the summary should be injected:
-	* - `'system_prompt'`: cross-run summary, included in the dynamic system tail
-	* - `'user_message'`: mid-run compaction, injected as HumanMessage on clean slate
-	* - `'none'`: no summary present
-	*/
 	_summaryLocation = "none";
-	/**
-	* Durable summary that survives reset() calls. Set from initialSummary
-	* during fromConfig() and updated by setSummary() so that the latest
-	* summary (whether cross-run or intra-run) is always restored after
-	* processStream's resetValues() cycle.
-	*/
 	_durableSummaryText;
 	_durableSummaryTokenCount = 0;
-	/** Number of summarization cycles that have occurred for this agent context */
 	_summaryVersion = 0;
-	/**
-	* Message count at the time summarization was last triggered.
-	* Used to prevent re-summarizing the same unchanged message set.
-	* Summarization is allowed to fire again only when new messages appear.
-	*/
 	_lastSummarizationMsgCount = 0;
-	/**
-	* Forced compactions performed after a provider rejected a prompt as too
-	* large. Bounds the recovery loop so a model that keeps refusing cannot
-	* make the run compact indefinitely.
-	*/
 	_overflowRecoveryAttempts = 0;
-	/**
-	* Budget in force before the first overflow correction of the current run.
-	* Recorded so `reset()` can undo the correction for the next run without
-	* disturbing a `maxContextTokens` that no correction ever touched.
-	*/
 	_preOverflowMaxContextTokens;
-	/**
-	* Prompt size, normalized into the local counter's uncalibrated units, at
-	* the last overflow correction. Keeping both measurements in the same units
-	* lets a later overflow prove whether compaction changed anything even when
-	* the provider observation updated calibration between attempts.
-	*/
 	_lastOverflowPromptTokens;
-	/**
-	* Handoff context when this agent receives control via handoff.
-	* Contains source and parallel execution info for system message context.
-	*/
 	handoffContext;
 	constructor({ agentId, name, provider, clientOptions, langfuse, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, toolDefinitions, instructions, additionalInstructions, reasoningKey, toolEnd, instructionTokens, useLegacyContent, discoveredTools, summarizationEnabled, summarizationConfig, contextPruningConfig, maxToolResultChars }) {
 		this.agentId = agentId;
@@ -279,15 +165,6 @@ var AgentContext = class AgentContext {
 		this.maxToolResultChars = maxToolResultChars;
 		if (discoveredTools && discoveredTools.length > 0) for (const toolName of discoveredTools) this.discoveredToolNames.add(toolName);
 	}
-	/**
-	* Builds instructions text for tools that are ONLY callable via programmatic code execution.
-	* These tools cannot be called directly by the LLM but are available through the
-	* configured programmatic tool.
-	*
-	* Includes:
-	* - Code_execution-only tools that are NOT deferred
-	* - Code_execution-only tools that ARE deferred but have been discovered via tool search
-	*/
 	buildProgrammaticOnlyToolsInstructions() {
 		if (!this.toolRegistry) return "";
 		const programmaticOnlyTools = [];
@@ -332,12 +209,6 @@ The following tools are available exclusively through the \`${programmaticTool.n
 		if (this.toolMap?.has(name) === true) return true;
 		return this.toolRegistry?.has(name) === true;
 	}
-	/**
-	* Gets the system runnable, creating it lazily if needed.
-	* Includes stable instructions, dynamic additional instructions, and
-	* programmatic-only tools documentation.
-	* Only rebuilds when marked stale (via markToolsAsDiscovered).
-	*/
 	get systemRunnable() {
 		if (!this.systemRunnableStale && this.cachedSystemRunnable !== void 0) return this.cachedSystemRunnable;
 		this.cachedSystemRunnable = this.buildSystemRunnable({
@@ -347,10 +218,6 @@ The following tools are available exclusively through the \`${programmaticTool.n
 		this.systemRunnableStale = false;
 		return this.cachedSystemRunnable;
 	}
-	/**
-	* Explicitly initializes the system runnable.
-	* Call this before async token calculation to ensure system message tokens are counted first.
-	*/
 	initializeSystemRunnable() {
 		if (this.systemRunnableStale || this.cachedSystemRunnable === void 0) {
 			this.cachedSystemRunnable = this.buildSystemRunnable({
@@ -360,10 +227,6 @@ The following tools are available exclusively through the \`${programmaticTool.n
 			this.systemRunnableStale = false;
 		}
 	}
-	/**
-	* Builds the cacheable instructions string (without creating SystemMessage).
-	* Includes agent identity preamble and handoff context when available.
-	*/
 	buildStableInstructionsString() {
 		const parts = [];
 		const identityPreamble = this.buildIdentityPreamble();
@@ -373,21 +236,12 @@ The following tools are available exclusively through the \`${programmaticTool.n
 		if (programmaticToolsDoc) parts.push(programmaticToolsDoc);
 		return parts.join("\n\n");
 	}
-	/**
-	* Builds the dynamic system-tail string (without creating SystemMessage).
-	* Keep this out of prompt-cache-marked content so volatile context does not
-	* invalidate the stable prefix.
-	*/
 	buildDynamicInstructionsString() {
 		const parts = [];
 		if (this.additionalInstructions != null && this.additionalInstructions !== "") parts.push(this.additionalInstructions);
 		if (this._summaryLocation === "system_prompt" && this.summaryText != null && this.summaryText !== "") parts.push("## Conversation Summary\n\n" + this.summaryText);
 		return parts.join("\n\n");
 	}
-	/**
-	* Builds the agent identity preamble including handoff context if present.
-	* This helps the agent understand its role in the multi-agent workflow.
-	*/
 	buildIdentityPreamble() {
 		if (!this.handoffContext) return "";
 		const displayName = this.name ?? this.agentId;
@@ -400,10 +254,6 @@ The following tools are available exclusively through the \`${programmaticTool.n
 		lines.push("Execute only tasks relevant to your role. Routing is already handled if requested, unless you can route further.");
 		return lines.join("\n");
 	}
-	/**
-	* Build system runnable from pre-built instructions string.
-	* Only called when content has actually changed.
-	*/
 	buildSystemRunnable({ stableInstructions, dynamicInstructions }) {
 		const hasMidRunSummary = this._summaryLocation === "user_message" && this.summaryText != null && this.summaryText !== "";
 		if (!stableInstructions && !dynamicInstructions && !hasMidRunSummary) {
@@ -486,20 +336,10 @@ The following tools are available exclusively through the \`${programmaticTool.n
 		if (this.provider !== "bedrock") return false;
 		return this.clientOptions?.promptCache === true;
 	}
-	/**
-	* Resolved TTL for the active prompt-cache provider (Anthropic or OpenRouter).
-	* Both expose `promptCacheTtl` and use the Anthropic `cache_control` format, so
-	* the configured value resolves the same way (default `'1h'` extended cache).
-	*/
 	getPromptCacheTtl(provider) {
 		if (provider == null) return;
 		return require_cache.resolvePromptCacheTtl(this.clientOptions?.promptCacheTtl);
 	}
-	/**
-	* Resolved TTL for Bedrock prompt-cache checkpoints (default `'1h'` on Claude).
-	* Claude models downgrade an unsupported 1h to 5m server-side; non-Claude
-	* models (Nova) reject the extended TTL, so they are clamped to 5m.
-	*/
 	getBedrockPromptCacheTtl() {
 		const bedrockOptions = this.clientOptions;
 		return require_cache.resolveBedrockPromptCacheTtl(bedrockOptions?.promptCacheTtl, bedrockOptions?.model);
@@ -538,9 +378,6 @@ The following tools are available exclusively through the \`${programmaticTool.n
 		}
 		return new _langchain_core_messages.SystemMessage([stableInstructions, dynamicInstructions].filter((part) => part !== "").join("\n\n"));
 	}
-	/**
-	* Reset context for a new run
-	*/
 	reset(options) {
 		this.systemMessageTokens = 0;
 		this.dynamicInstructionTokens = 0;
@@ -577,82 +414,26 @@ The following tools are available exclusively through the \`${programmaticTool.n
 			});
 		} else this.tokenCalculationPromise = void 0;
 	}
-	/**
-	* Update the token count map from a base map.
-	*
-	* Previously this inflated index 0 with instructionTokens to indirectly
-	* reserve budget for the system prompt.  That approach was imprecise: with
-	* large tool-schema overhead (e.g. 26 MCP tools ~5 000 tokens) the first
-	* conversation message appeared enormous and was always pruned, while the
-	* real available budget was never explicitly computed.
-	*
-	* Now instruction tokens are passed to getMessagesWithinTokenLimit via
-	* the `getInstructionTokens` factory param so the pruner subtracts them
-	* from the budget directly.  The token map contains only real per-message
-	* token counts.
-	*/
 	updateTokenMapWithInstructions(baseTokenMap) {
 		this.indexTokenCountMap = { ...baseTokenMap };
 	}
-	/** Active tool definitions for token accounting (excludes deferred-and-undiscovered entries). */
 	getActiveToolDefinitions() {
 		if (!this.toolDefinitions) return [];
-		/**
-		* Mirror `getEventDrivenToolsForBinding`'s gate: a definition is only
-		* bound to the model when its `allowed_callers` include `'direct'` and
-		* (if deferred) it has been discovered. Filtering by `defer_loading`
-		* alone left programmatic-only definitions counted in
-		* `toolSchemaTokens` even though they were never bound.
-		*/
 		return this.toolDefinitions.filter((def) => {
 			if (!(def.allowed_callers ?? ["direct"]).includes("direct")) return false;
 			return def.defer_loading !== true || this.discoveredToolNames.has(def.name);
 		});
 	}
-	/**
-	* Single source of truth for "which entries of `this.tools` should be
-	* treated as actually bound". Callers:
-	*   - `getToolsForBinding` (non-event-driven branch)
-	*   - `getEventDrivenToolsForBinding` (appends instance tools alongside
-	*     schema-only definitions)
-	*   - `calculateInstructionTokens` (counts schema bytes for accounting)
-	*
-	* In event-driven mode (`toolDefinitions` present) instance tools are
-	* appended unfiltered; outside event-driven mode they pass through
-	* `filterToolsForBinding`. Centralizing the decision here prevents the
-	* accounting/binding paths from drifting apart, which was the root
-	* cause of the original miscount.
-	*/
 	getEffectiveInstanceTools() {
 		if (!this.tools) return;
 		if ((this.toolDefinitions?.length ?? 0) > 0 || !this.toolRegistry) return this.tools;
 		return this.filterToolsForBinding(this.tools);
 	}
-	/**
-	* Calculate tool tokens and add to instruction tokens
-	* Note: System message tokens are calculated during systemRunnable creation
-	*/
 	async calculateInstructionTokens(tokenCounter) {
 		let toolTokens = 0;
 		const countedToolNames = /* @__PURE__ */ new Set();
-		/** Prototype-free: external tool names like `toString` must not hit
-		*  inherited properties during accumulation */
 		const rawToolTokenCounts = Object.create(null);
 		const deferredCountedNames = /* @__PURE__ */ new Set();
-		/**
-		* Iterate both `tools` (user-provided instance tools) and `graphTools`
-		* (graph-managed tools like handoff + subagent). `graphTools` is often
-		* populated after `fromConfig()` kicks off the initial calculation, so
-		* callers that mutate `graphTools` must re-trigger this method to
-		* refresh `toolSchemaTokens`.
-		*
-		* Use `getEffectiveInstanceTools()` so accounting reflects exactly the
-		* subset that `getToolsForBinding` would emit — preventing the
-		* worst-case-ceiling miscount that triggered spurious `empty_messages`
-		* preflight rejections at low `maxContextTokens`. Deferred and
-		* non-`'direct'` `toolDefinitions` are excluded by
-		* `getActiveToolDefinitions()` below.
-		*/
 		const instanceTools = [...this.getEffectiveInstanceTools() ?? [], ...this.graphTools ?? []];
 		if (instanceTools.length > 0) for (const tool of instanceTools) {
 			const genericTool = tool;
@@ -685,32 +466,18 @@ The following tools are available exclusively through the \`${programmaticTool.n
 		}
 		const toolTokenMultiplier = this.provider !== "bedrock" && (this.provider === "anthropic" || /anthropic|claude/i.test(String(this.clientOptions?.model ?? ""))) ? require_constants.ANTHROPIC_TOOL_TOKEN_MULTIPLIER : require_constants.DEFAULT_TOOL_TOKEN_MULTIPLIER;
 		this.toolSchemaTokens = Math.ceil(toolTokens * toolTokenMultiplier);
-		/** Largest-remainder apportionment keeps the per-tool counts summing
-		*  exactly to the aggregate despite per-entry rounding */
 		const toolTokenCounts = require_tokens.apportionTokenCounts(rawToolTokenCounts, toolTokenMultiplier, this.toolSchemaTokens);
 		const deferredToolNames = [];
 		for (const name of Object.keys(rawToolTokenCounts)) if (deferredCountedNames.has(name) || this.toolRegistry?.get(name)?.defer_loading === true) deferredToolNames.push(name);
 		this.toolTokenCounts = toolTokenCounts;
 		this.deferredToolNames = deferredToolNames;
 	}
-	/**
-	* Gets the tool registry for deferred tools (for tool search).
-	* @param onlyDeferred If true, only returns tools with defer_loading=true
-	* @returns LCToolRegistry with tool definitions
-	*/
 	getDeferredToolRegistry(onlyDeferred = true) {
 		const registry = /* @__PURE__ */ new Map();
 		if (!this.toolRegistry) return registry;
 		for (const [name, toolDef] of this.toolRegistry) if (!onlyDeferred || toolDef.defer_loading === true) registry.set(name, toolDef);
 		return registry;
 	}
-	/**
-	* Sets the handoff context for this agent.
-	* Call this when the agent receives control via handoff from another agent.
-	* Marks system runnable as stale to include handoff context in system message.
-	* @param sourceAgentName - Name of the agent that transferred control
-	* @param parallelSiblings - Names of other agents executing in parallel with this one
-	*/
 	setHandoffContext(sourceAgentName, parallelSiblings) {
 		this.handoffContext = {
 			sourceAgentName,
@@ -718,10 +485,6 @@ The following tools are available exclusively through the \`${programmaticTool.n
 		};
 		this.systemRunnableStale = true;
 	}
-	/**
-	* Clears any handoff context.
-	* Call this when resetting the agent or when handoff context is no longer relevant.
-	*/
 	clearHandoffContext() {
 		if (this.handoffContext) {
 			this.handoffContext = void 0;
@@ -738,7 +501,6 @@ The following tools are available exclusively through the \`${programmaticTool.n
 		this.systemRunnableStale = true;
 		this.pruneMessages = void 0;
 	}
-	/** Sets a cross-run summary that is injected into the system prompt. */
 	setInitialSummary(text, tokenCount) {
 		this.summaryText = text;
 		this.summaryTokenCount = tokenCount;
@@ -748,11 +510,6 @@ The following tools are available exclusively through the \`${programmaticTool.n
 		this._summaryVersion += 1;
 		this.systemRunnableStale = true;
 	}
-	/**
-	* Replaces the indexTokenCountMap with a fresh map keyed to the surviving
-	* context messages after summarization.  Called by the summarize node after
-	* it emits RemoveMessage operations that shift message indices.
-	*/
 	rebuildTokenMapAfterSummarization(newTokenMap) {
 		this.indexTokenCountMap = newTokenMap;
 		this.baseIndexTokenCountMap = { ...newTokenMap };
@@ -764,7 +521,6 @@ The following tools are available exclusively through the \`${programmaticTool.n
 	hasSummary() {
 		return this.summaryText != null && this.summaryText !== "";
 	}
-	/** True when a mid-run compaction summary is ready to be injected as a HumanMessage. */
 	hasPendingCompactionSummary() {
 		return this._summaryLocation === "user_message" && this.hasSummary();
 	}
@@ -774,19 +530,9 @@ The following tools are available exclusively through the \`${programmaticTool.n
 	get summaryVersion() {
 		return this._summaryVersion;
 	}
-	/**
-	* Returns true when the message count hasn't changed since the last
-	* summarization — re-summarizing would produce an identical result.
-	* Oversized individual messages are handled by fit-to-budget truncation
-	* in the pruner, which keeps them in context without triggering overflow.
-	*/
 	shouldSkipSummarization(currentMsgCount) {
 		return this._lastSummarizationMsgCount > 0 && currentMsgCount <= this._lastSummarizationMsgCount;
 	}
-	/**
-	* Records the message count at which summarization was triggered,
-	* so subsequent calls with the same count are suppressed.
-	*/
 	markSummarizationTriggered(msgCount) {
 		this._lastSummarizationMsgCount = msgCount;
 	}
@@ -796,7 +542,6 @@ The following tools are available exclusively through the \`${programmaticTool.n
 	shouldSummarizeOverflow() {
 		return this.summarizationEnabled === true && (this.tokenCounter == null || this.maxContextTokens == null || this._overflowRecoveryAttempts > 0);
 	}
-	/** Preserves the earliest full tool output recorded for each message index. */
 	preserveOriginalToolContent(originalToolContent) {
 		if (originalToolContent == null || originalToolContent.size === 0) return;
 		if (this.pendingOriginalToolContent == null) this.pendingOriginalToolContent = /* @__PURE__ */ new Map();
@@ -817,16 +562,6 @@ The following tools are available exclusively through the \`${programmaticTool.n
 			pending.delete(oldest.value);
 		}
 	}
-	/**
-	* Retargets the context budget after a provider rejected the prompt as too
-	* large, and clears the memoized pruner so the next call is planned against
-	* the corrected budget rather than the one that was evidently wrong.
-	*
-	* Also clears the "already summarized at this message count" guard: that
-	* guard exists to stop redundant summarization of an unchanged history, but
-	* here the history has not changed and compaction is exactly what is
-	* needed.
-	*/
 	applyContextBudgetCorrection(budgetTokens, promptTokens) {
 		if (this._overflowRecoveryAttempts === 0) this._preOverflowMaxContextTokens = this.maxContextTokens;
 		if (budgetTokens != null) this.maxContextTokens = budgetTokens;
@@ -835,17 +570,10 @@ The following tools are available exclusively through the \`${programmaticTool.n
 		this._lastOverflowPromptTokens = promptTokens != null ? this.normalizePromptTokens(promptTokens) : promptTokens;
 		this._overflowRecoveryAttempts += 1;
 	}
-	/** Applies token calibration only when the observation came from this provider. */
 	applyObservedOverflowCalibration(provider, observedCalibrationRatio) {
 		if (provider !== this.provider || observedCalibrationRatio == null || observedCalibrationRatio <= 0) return;
 		this.calibrationRatio = require_prune.clampCalibrationRatio(observedCalibrationRatio);
 	}
-	/**
-	* True when a previous correction failed to make the prompt any smaller —
-	* the signature of a state nothing can compact further (an emptied message
-	* list carrying its content in an injected summary, for example). Retrying
-	* from there resends a byte-identical prompt, so the caller should stop.
-	*/
 	overflowRecoveryStalled(currentPromptTokens) {
 		const previous = this._lastOverflowPromptTokens;
 		if (previous == null || currentPromptTokens == null || !Number.isFinite(currentPromptTokens)) return false;
@@ -856,14 +584,6 @@ The following tools are available exclusively through the \`${programmaticTool.n
 		const messageTokens = Math.max(0, promptTokens - this.instructionTokens);
 		return this.instructionTokens + messageTokens / this.calibrationRatio;
 	}
-	/**
-	* Undoes overflow corrections so a reused context starts the next run with
-	* the budget it was configured with and a fresh recovery allowance.
-	*
-	* Without this, a single overflow would permanently shrink the budget for
-	* every later turn, and two would exhaust the per-run allowance for the
-	* lifetime of the context.
-	*/
 	restoreContextBudgetAfterOverflow() {
 		if (this._overflowRecoveryAttempts === 0) return;
 		this.maxContextTokens = this._preOverflowMaxContextTokens;
@@ -881,30 +601,12 @@ The following tools are available exclusively through the \`${programmaticTool.n
 			this.systemRunnableStale = true;
 		}
 	}
-	/**
-	* Returns a structured breakdown of how the context token budget is consumed.
-	* Useful for diagnostics when context overflow or pruning issues occur.
-	*
-	* Note: `markToolsAsDiscovered` re-triggers `calculateInstructionTokens`,
-	* so `toolSchemaTokens`/`toolTokenCounts` refresh before the next call.
-	*/
 	getTokenBudgetBreakdown(messages) {
 		const maxContextTokens = this.maxContextTokens ?? 0;
-		/**
-		* Derive `toolCount` from `getToolsForBinding()` so the diagnostic stays
-		* aligned with what is actually bound to the model — and with what
-		* `calculateInstructionTokens` counts into `toolSchemaTokens`. Using raw
-		* `this.tools.length` would inflate the count whenever the registry
-		* marks instance tools as deferred-undiscovered or non-`'direct'`,
-		* producing the same misleading "N tools" diagnostic this fix is meant
-		* to eliminate.
-		*/
 		const toolCount = this.getToolsForBinding()?.length ?? 0;
 		const messageCount = messages?.length ?? 0;
 		let messageTokens = 0;
 		if (messages != null) for (let i = 0; i < messages.length; i++) messageTokens += this.indexTokenCountMap[i] ?? 0;
-		/** Mirror the pruner's reserve math so availableForMessages agrees
-		*  with the contextBudget computed during pruning */
 		const reserveRatio = this.summarizationConfig?.reserveRatio ?? .05;
 		const reserveTokens = reserveRatio > 0 && reserveRatio < 1 ? Math.round(maxContextTokens * reserveRatio) : 0;
 		const availableForMessages = Math.max(0, maxContextTokens - reserveTokens - this.instructionTokens);
@@ -923,10 +625,6 @@ The following tools are available exclusively through the \`${programmaticTool.n
 			deferredToolNames: this.deferredToolNames.length > 0 ? [...this.deferredToolNames] : void 0
 		};
 	}
-	/**
-	* Returns a human-readable string of the token budget breakdown
-	* for inclusion in error messages and diagnostics.
-	*/
 	formatTokenBudgetBreakdown(messages) {
 		const b = this.getTokenBudgetBreakdown(messages);
 		return [
@@ -938,38 +636,10 @@ The following tools are available exclusively through the \`${programmaticTool.n
 			`  availableForMessages: ${b.availableForMessages}`
 		].join("\n");
 	}
-	/**
-	* Projects the context-usage snapshot for an arbitrary message set WITHOUT
-	* invoking the model — the pre-send / page-load / window-switch counterpart to
-	* the live `ON_CONTEXT_USAGE` snapshot. Runs the same pruner + budget math the
-	* graph uses (`createPruneMessages` → `getTokenBudgetBreakdown` →
-	* `syncBudgetDerivedFields`) so projected numbers match a real call. Returns
-	* null when the context lacks the tokenizer or window needed to prune. Omits
-	* the live post-format reconciliation (provider-specific, invoke-time) — a
-	* small, acceptable delta for a pre-send estimate.
-	*
-	* Safe to call off the hot path: the supplied `messages` are never mutated
-	* (each is passed as a clone — the pruner both replaces tool-result slots and
-	* unshifts reasoning blocks into AI content arrays in place), and this
-	* context's own state is untouched apart from refreshing stale instruction
-	* counts (idempotent, exactly what a real call does). Token counts are
-	* recounted for the supplied messages (the context's `indexTokenCountMap` is
-	* keyed to the live run's branch and would missum an arbitrary branch) unless
-	* the caller passes a map it guarantees matches. Calibration is NOT re-derived
-	* from this context's live usage (a fresh pruner would compare the prior
-	* call's provider input against the whole projected branch); the learned
-	* `calibrationRatio` is applied as a static seed, and callers may override it
-	* with a persisted ratio via `opts.calibrationRatio`.
-	*/
 	projectContextUsage(messages, opts) {
 		const tokenCounter = this.tokenCounter;
 		if (tokenCounter == null || this.maxContextTokens == null) return null;
-		/** Refresh stale system overhead (handoff/summary changes) so instruction
-		*  tokens match the prompt a real call would send. */
 		this.initializeSystemRunnable();
-		/** Clone array-content messages: the pruner unshifts reasoning blocks into
-		*  AI content arrays in place, which would otherwise corrupt the caller's
-		*  history. (Slot replacements land on the mapped array, not the caller's.) */
 		const projected = messages.map((message) => Array.isArray(message.content) ? require_cache.cloneMessage(message, [...message.content]) : message);
 		let indexTokenCountMap = opts?.indexTokenCountMap;
 		if (indexTokenCountMap == null) {
@@ -1010,10 +680,6 @@ The following tools are available exclusively through the \`${programmaticTool.n
 		require_budget.syncBudgetDerivedFields(usage);
 		return usage;
 	}
-	/**
-	* Updates the last-call usage with data from the most recent LLM response.
-	* Unlike `currentUsage` which accumulates, this captures only the single call.
-	*/
 	updateLastCallUsage(usage) {
 		const baseInputTokens = Number(usage.input_tokens) || 0;
 		const cacheCreation = Number(usage.input_token_details?.cache_creation) || 0;
@@ -1030,21 +696,12 @@ The following tools are available exclusively through the \`${programmaticTool.n
 		};
 		this.totalTokensFresh = true;
 	}
-	/** Marks token data as stale before a new LLM call. */
 	markTokensStale() {
 		this.totalTokensFresh = false;
 	}
-	/** Returns a snapshot of the deferred tools discovered in this context. */
 	getDiscoveredTools() {
 		return Array.from(this.discoveredToolNames);
 	}
-	/**
-	* Marks tools as discovered via tool search.
-	* Discovered tools will be included in the next model binding.
-	* Only marks system runnable stale if NEW tools were actually added.
-	* @param toolNames - Array of discovered tool names
-	* @returns true if any new tools were discovered
-	*/
 	markToolsAsDiscovered(toolNames) {
 		let hasNewDiscoveries = false;
 		for (const name of toolNames) if (!this.discoveredToolNames.has(name)) {
@@ -1053,28 +710,16 @@ The following tools are available exclusively through the \`${programmaticTool.n
 		}
 		if (hasNewDiscoveries) {
 			this.systemRunnableStale = true;
-			/** Refresh schema token accounting so the next call's budget and
-			*  per-tool breakdown include the newly discovered tools; awaited
-			*  via tokenCalculationPromise before the next model call */
 			if (this.tokenCounter) this.tokenCalculationPromise = this.calculateInstructionTokens(this.tokenCounter);
 		}
 		return hasNewDiscoveries;
 	}
-	/**
-	* Gets tools that should be bound to the LLM.
-	* In event-driven mode (toolDefinitions present, tools empty), creates schema-only tools.
-	* Otherwise filters tool instances based on:
-	* 1. Non-deferred tools with allowed_callers: ['direct']
-	* 2. Discovered tools (from tool search)
-	* @returns Array of tools to bind to model
-	*/
 	getToolsForBinding() {
 		if (this.toolDefinitions && this.toolDefinitions.length > 0) return this.getEventDrivenToolsForBinding();
 		const filtered = this.getEffectiveInstanceTools();
 		if (this.graphTools && this.graphTools.length > 0) return [...filtered ?? [], ...this.graphTools];
 		return filtered;
 	}
-	/** Creates schema-only tools from toolDefinitions for event-driven mode, merged with native tools */
 	getEventDrivenToolsForBinding() {
 		if (!this.toolDefinitions) return this.graphTools ?? [];
 		const allTools = [...require_schema$1.createSchemaOnlyTools(this.getActiveToolDefinitions())];
@@ -1083,7 +728,6 @@ The following tools are available exclusively through the \`${programmaticTool.n
 		if (instanceTools && instanceTools.length > 0) allTools.push(...instanceTools);
 		return allTools;
 	}
-	/** Filters tool instances for binding based on registry config */
 	filterToolsForBinding(tools) {
 		return tools.filter((tool) => {
 			if (!("name" in tool)) return true;