@namzu/sdk 62.8.0 → 62.10.0

package/src/compaction/salience/score.ts

@@ -26,7 +26,7 @@ import type { AssistantMessage, Message, ToolMessage } from '../../types/message
 import { findRetainedIndices } from '../retention.js'
 import { estimateMessageTokens } from '../token-estimate.js'
 import { type Bm25Document, bm25Score, buildIndex, indexDocument } from './bm25.js'
-import { isEmptySignature, minhash, similarity } from './minhash.js'
+import { isEmptySignature, minhash, similarityAtLeast } from './minhash.js'
 import { tokenize } from './tokenize.js'
 
 export interface SalienceWeights {
@@ -119,6 +119,54 @@ function citable(tokens: readonly string[]): Set<string> {
 	return out
 }
 
+/**
+ * What the scorer derives from one message's text, and nothing that depends
+ * on the rest of the history: the term frequencies BM25 reads, the
+ * identifiers a later turn could cite, the MinHash signature and a key for
+ * "byte-identical signature".
+ *
+ * A pass scored every message from its raw text every time, and the text of
+ * a message that is already in the history does not change between passes.
+ * The cost of a pass was therefore proportional to every byte in the
+ * history, paid again on each pass, and the largest part of it was hashing
+ * shingles. Held per message OBJECT, a pass pays for the messages it has not
+ * seen and for the arithmetic that does depend on the whole history (the
+ * corpus statistics, recency, the redundancy comparison).
+ *
+ * Keyed by object identity and validated by the text it was computed from: a
+ * message that is replaced (a stub is a copy) is a different object, and one
+ * that is edited in place fails the text comparison, so a stale entry is
+ * never read. Weakly held: an entry goes with its message.
+ */
+interface MessageFeatures {
+	readonly text: string
+	readonly tokenCount: number
+	readonly document: Bm25Document
+	readonly citable: ReadonlySet<string>
+	readonly signature: Uint32Array
+	/** Equal keys mean equal signatures, so a similarity of exactly 1. */
+	readonly signatureKey: string
+}
+
+const FEATURES = new WeakMap<Message, MessageFeatures>()
+
+function featuresOf(message: Message, text: string): MessageFeatures {
+	const cached = FEATURES.get(message)
+	if (cached !== undefined && cached.text === text) return cached
+	const tokens = tokenize(text)
+	const signature = minhash(tokens)
+	const features: MessageFeatures = {
+		text,
+		tokenCount: tokens.length,
+		document: indexDocument(text, tokens),
+		citable: citable(tokens),
+		signature,
+		signatureKey: String.fromCharCode(...new Uint16Array(signature.buffer)),
+	}
+	FEATURES.set(message, features)
+	return features
+}
+
 export function scoreMessages(
 	messages: readonly Message[],
 	options: ScoreOptions,
@@ -129,12 +177,9 @@ export function scoreMessages(
 		weights: { ...DEFAULT_SALIENCE_WEIGHTS, ...options.config?.weights },
 	}
 	const n = messages.length
-	const texts = messages.map(messageText)
+	const features = messages.map((message) => featuresOf(message, messageText(message)))
 	const richContent = messages.map(hasRichContent)
-	const tokenLists = texts.map(tokenize)
-	const documents: Bm25Document[] = texts.map((text, i) =>
-		indexDocument(text, tokenLists[i] as string[]),
-	)
+	const documents: Bm25Document[] = features.map((f) => f.document)
 	const index = buildIndex(documents)
 	const goalTokens = tokenize(options.goal)
 
@@ -156,33 +201,64 @@ export function scoreMessages(
 	)
 
 	// Citation index: everything a LATER assistant turn or tool input names.
-	// Built once, suffix-wise, so each message asks "does anything after me
-	// cite my identifiers" in one lookup.
-	const citedAfter: Set<string>[] = new Array(n)
-	let running = new Set<string>()
-	for (let i = n - 1; i >= 0; i -= 1) {
-		citedAfter[i] = running
+	// For each identifier, the last message that names it: a message asks
+	// "does anything after me cite my identifiers" as "is the last citation
+	// of this identifier after me". The same answer as a set of everything
+	// after each message, without building n sets of up to n identifiers.
+	const lastCited = new Map<string, number>()
+	for (let i = 0; i < n; i += 1) {
 		const message = messages[i] as Message
-		if (message.role === 'assistant' || message.role === 'user') {
-			running = new Set([...running, ...citable(tokenLists[i] as string[])])
-		}
+		if (message.role !== 'assistant' && message.role !== 'user') continue
+		for (const token of (features[i] as MessageFeatures).citable) lastCited.set(token, i)
 	}
 
-	// Redundancy: the highest similarity to any later message of the same
-	// role, and a full demotion when a later assistant turn repeats this
-	// message's tool call exactly.
-	const signatures = tokenLists.map(minhash)
+	// A full demotion when a later assistant turn repeats this message's
+	// tool call exactly: for each call, the last message that makes it.
 	const callKeys = messages.map((m) =>
 		isAssistantWithCalls(m)
 			? (m.toolCalls ?? []).map((c) => `${c.function.name}:${c.function.arguments}`)
 			: [],
 	)
-	const laterCallKeys: Set<string>[] = new Array(n)
-	let calls = new Set<string>()
+	const lastCalled = new Map<string, number>()
+	for (let i = 0; i < n; i += 1) {
+		for (const key of callKeys[i] as string[]) lastCalled.set(key, i)
+	}
+
+	// Redundancy: the highest similarity to any later message of the same
+	// role. Walked from the end so the later messages of each role are the
+	// ones already seen; a signature identical to one of them is a
+	// similarity of exactly 1, the most there is, and ends the scan.
+	// Below the lower of one half and the duplicate threshold a similarity
+	// is read as none (see the redundancy step of the score), so the
+	// comparison need not finish it.
+	const floor = Math.min(0.5, config.duplicateThreshold)
+	const redundancyOf: number[] = new Array(n).fill(0)
+	const laterSignatures = new Map<Message['role'], Uint32Array[]>()
+	const laterKeys = new Map<Message['role'], Set<string>>()
 	for (let i = n - 1; i >= 0; i -= 1) {
-		laterCallKeys[i] = calls
-		if ((callKeys[i] as string[]).length > 0)
-			calls = new Set([...calls, ...(callKeys[i] as string[])])
+		const message = messages[i] as Message
+		// A caption or a repeated call cannot prove that two screenshots or
+		// documents contain the same evidence. The lexical scorer has no
+		// access to their meaning, so it must not call those messages duplicates.
+		if (richContent[i]) continue
+		const own = features[i] as MessageFeatures
+		const sameRole = laterSignatures.get(message.role) ?? []
+		const sameRoleKeys = laterKeys.get(message.role) ?? new Set<string>()
+		let redundancy = 0
+		if (!isEmptySignature(own.signature)) {
+			if (sameRoleKeys.has(own.signatureKey)) redundancy = 1
+			else {
+				for (const other of sameRole) {
+					const sim = similarityAtLeast(own.signature, other, floor)
+					if (sim > redundancy) redundancy = sim
+				}
+			}
+		}
+		redundancyOf[i] = redundancy
+		sameRole.push(own.signature)
+		sameRoleKeys.add(own.signatureKey)
+		laterSignatures.set(message.role, sameRole)
+		laterKeys.set(message.role, sameRoleKeys)
 	}
 
 	// Protection.
@@ -239,8 +315,8 @@ export function scoreMessages(
 			// An instruction is used by everything after it; an acknowledgment
 			// ("ok, go on") is not an instruction. The difference is whether it
 			// names anything or says more than a few words.
-			const tokens = tokenLists[i] as string[]
-			utility = citable(tokens).size > 0 || tokens.length >= 6 ? 1 : 0.2
+			const own = features[i] as MessageFeatures
+			utility = own.citable.size > 0 || own.tokenCount >= 6 ? 1 : 0.2
 		} else if (message.role === 'tool') {
 			// Used is used: one identifier from this result named by a later
 			// turn is the evidence, and a count would let the recency of
@@ -248,24 +324,17 @@ export function scoreMessages(
 			// for. The eval that placed the account id deep in an early dump
 			// and cited it later watched the salience pass clear it under a
 			// thirds rule.
-			const mine = citable(tokenLists[i] as string[])
-			let hits = 0
-			for (const token of mine) if ((citedAfter[i] as Set<string>).has(token)) hits += 1
-			utility = hits > 0 ? 1 : 0
+			let cited = false
+			for (const token of (features[i] as MessageFeatures).citable) {
+				if ((lastCited.get(token) ?? -1) > i) {
+					cited = true
+					break
+				}
+			}
+			utility = cited ? 1 : 0
 		} else if (isAssistantWithCalls(message)) utility = 0.5
 
-		let redundancy = 0
-		const signature = signatures[i] as Uint32Array
-		// A caption or a repeated call cannot prove that two screenshots or
-		// documents contain the same evidence. The lexical scorer has no
-		// access to their meaning, so it must not call those messages duplicates.
-		if (!richContent[i] && !isEmptySignature(signature)) {
-			for (let j = i + 1; j < n; j += 1) {
-				if (richContent[j] || (messages[j] as Message).role !== message.role) continue
-				const sim = similarity(signature, signatures[j] as Uint32Array)
-				if (sim > redundancy) redundancy = sim
-			}
-		}
+		let redundancy = redundancyOf[i] as number
 		if (redundancy < config.duplicateThreshold) redundancy = redundancy >= 0.5 ? redundancy : 0
 		else redundancy = 1
 		if (message.role === 'tool' && !richContent[i]) {
@@ -279,7 +348,7 @@ export function scoreMessages(
 				)
 				if (call) {
 					const key = `${call.function.name}:${call.function.arguments}`
-					if ((laterCallKeys[i] as Set<string>).has(key)) redundancy = 1
+					if ((lastCalled.get(key) ?? -1) > i) redundancy = 1
 					break
 				}
 			}

package/src/compaction/salience/working-set.ts

@@ -73,14 +73,18 @@ export function isStubbedNarration(content: unknown): boolean {
 	return typeof content === 'string' && content.includes(STUB_MARK)
 }
 
-export function planWorkingSet(
+/** What decides whether a message is something the pass may shed at all. */
+interface EvictionRules {
+	readonly minTool: number
+	readonly minNarration: number
+	readonly preserve: ReadonlySet<string>
+	readonly toolNameByCallId: ReadonlyMap<string, string>
+}
+
+function evictionRules(
 	messages: readonly Message[],
-	scored: readonly ScoredMessage[],
-	options: WorkingSetOptions,
-): WorkingSetPlan {
-	const minTool = options.minToolResultChars ?? 1_000
-	const minNarration = options.minNarrationChars ?? 240
-	const preserve = new Set(options.preserveTools ?? [])
+	options: Pick<WorkingSetOptions, 'minToolResultChars' | 'minNarrationChars' | 'preserveTools'>,
+): EvictionRules {
 	const toolNameByCallId = new Map<string, string>()
 	for (const m of messages) {
 		if (m.role !== 'assistant') continue
@@ -88,6 +92,87 @@ export function planWorkingSet(
 			toolNameByCallId.set(call.id, call.function.name)
 		}
 	}
+	return {
+		minTool: options.minToolResultChars ?? 1_000,
+		minNarration: options.minNarrationChars ?? 240,
+		preserve: new Set(options.preserveTools ?? []),
+		toolNameByCallId,
+	}
+}
+
+/**
+ * Whether the pass could clear or stub this message, ignoring only what
+ * protection decides (the floor, the recent turns, retained turns, a pair
+ * with a protected half) and what the score decides. The one place the
+ * eligibility rules live: {@link planWorkingSet} asks it of each unprotected
+ * message, and {@link hasEvictableMessage} asks it of every message.
+ */
+function evictionKind(m: Message, tokens: number, rules: EvictionRules): 'clear' | 'stub' | null {
+	if (tokens === 0) return null
+	if (m.role === 'tool') {
+		const tool = m as ToolMessage
+		if (tool.isError || isClearedToolResult(tool.content)) return null
+		if (rules.preserve.has(rules.toolNameByCallId.get(tool.toolCallId) ?? '')) return null
+		if (tokens * CHARS_PER_TOKEN < rules.minTool) return null
+		return 'clear'
+	}
+	if (m.role === 'assistant' && !Array.isArray((m as AssistantMessage).toolCalls)) {
+		const text = typeof m.content === 'string' ? m.content : ''
+		if (text.length < rules.minNarration || isStubbedNarration(text)) return null
+		return 'stub'
+	}
+	return null
+}
+
+/**
+ * A cheap count of whether anything at all is left for the pass to shed:
+ * false means {@link planWorkingSet} would return no action whatever the
+ * scores are, so scoring can be skipped. It leaves out the two protections
+ * that are only a position (the leading system run and the last
+ * `keepRecentMessages`); retained turns, tool-call pairs and the goal floor
+ * are not looked at. True is therefore only "go and look", and a false is
+ * exact.
+ */
+export function hasEvictableMessage(
+	messages: readonly Message[],
+	options: Pick<WorkingSetOptions, 'minToolResultChars' | 'minNarrationChars' | 'preserveTools'> & {
+		readonly keepRecentMessages: number
+	},
+): boolean {
+	const rules = evictionRules(messages, options)
+	let floorEnd = 0
+	while (floorEnd < messages.length && messages[floorEnd]?.role === 'system') floorEnd += 1
+	const end = Math.max(floorEnd, messages.length - options.keepRecentMessages)
+	for (let i = floorEnd; i < end; i += 1) {
+		const m = messages[i] as Message
+		if (evictionKind(m, estimateMessageTokens(m), rules) !== null) return true
+	}
+	return false
+}
+
+/** The plan of a pass that sheds nothing: every message as it was. */
+export function planNothingToShed(
+	messages: readonly Message[],
+	options: Pick<WorkingSetOptions, 'estimatedTokens' | 'targetTokens'>,
+): WorkingSetPlan {
+	return {
+		messages: [...messages],
+		actions: [],
+		clearedCount: 0,
+		stubbedCount: 0,
+		charsReclaimed: 0,
+		reclaimedTokens: 0,
+		reachedTarget: options.estimatedTokens - options.targetTokens <= 0,
+	}
+}
+
+export function planWorkingSet(
+	messages: readonly Message[],
+	scored: readonly ScoredMessage[],
+	options: WorkingSetOptions,
+): WorkingSetPlan {
+	const rules = evictionRules(messages, options)
+	const { toolNameByCallId } = rules
 
 	// Ordered by salience, not salience per token. Per token was the plan's
 	// first answer and it evicts the wrong thing: a large result the goal
@@ -104,31 +189,17 @@ export function planWorkingSet(
 	}
 	const candidates: Candidate[] = []
 	for (const s of scored) {
-		if (s.protected !== null || s.tokens === 0) continue
+		if (s.protected !== null) continue
 		const m = messages[s.index] as Message
-		if (m.role === 'tool') {
-			const tool = m as ToolMessage
-			if (tool.isError || isClearedToolResult(tool.content)) continue
-			if (preserve.has(toolNameByCallId.get(tool.toolCallId) ?? '')) continue
-			if (s.tokens * CHARS_PER_TOKEN < minTool) continue
-			candidates.push({
-				index: s.index,
-				kind: 'clear',
-				salience: s.salience,
-				tokens: s.tokens,
-				goalBound: s.relevance >= 0.5 || s.utility >= 1,
-			})
-		} else if (m.role === 'assistant' && !Array.isArray((m as AssistantMessage).toolCalls)) {
-			const text = typeof m.content === 'string' ? m.content : ''
-			if (text.length < minNarration || isStubbedNarration(text)) continue
-			candidates.push({
-				index: s.index,
-				kind: 'stub',
-				salience: s.salience,
-				tokens: s.tokens,
-				goalBound: s.relevance >= 0.5 || s.utility >= 1,
-			})
-		}
+		const kind = evictionKind(m, s.tokens, rules)
+		if (kind === null) continue
+		candidates.push({
+			index: s.index,
+			kind,
+			salience: s.salience,
+			tokens: s.tokens,
+			goalBound: s.relevance >= 0.5 || s.utility >= 1,
+		})
 	}
 	candidates.sort((a, b) => a.salience - b.salience || b.tokens - a.tokens || a.index - b.index)
 	const maxSalience = candidates.reduce((m, c) => Math.max(m, c.salience), Number.NEGATIVE_INFINITY)

package/src/config/runtime.ts

@@ -32,6 +32,20 @@ export const CompactionConfigSchema = z.object({
 	 * `triggerThreshold` summarises. The context is held around here.
 	 */
 	softTarget: z.number().min(0).max(1).optional(),
+	/**
+	 * `salience` only: how far below `softTarget`, as a fraction of the
+	 * window, a pass sheds. A pass still starts when the context reaches the
+	 * soft target, but it then keeps shedding until the context is
+	 * `softTargetHeadroom` of the window under it, so the next pass is needed
+	 * only after that headroom has been used instead of on the next turn.
+	 * Fewer passes, and the request is rewritten (a prompt cache's prefix
+	 * broken) once per headroom instead of once per turn; the cost is that
+	 * the context is held that much lower, so that much less history stays
+	 * whole. The messages shed are the same ones in the same order, only
+	 * earlier. Absent or `0`, the default, a pass sheds to the soft target
+	 * and no further, exactly as before.
+	 */
+	softTargetHeadroom: z.number().min(0).max(1).optional(),
 	/**
 	 * Optional model context-window size (tokens) the compaction trigger
 	 * measures the CURRENT window against. NO default: when omitted the

package/src/connector/http-operation.ts

@@ -1,4 +1,4 @@
-const MAX_TIMER_DELAY_MS = 2_147_483_647
+export const MAX_TIMER_DELAY_MS = 2_147_483_647
 const MAX_RESPONSE_BYTES = 2_147_483_647
 
 // These headers can change where an already-validated URL is routed. Connector

package/src/connector/mcp/adapter.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod'
 import type { WorkingStatePin } from '../../compaction/types.js'
+import { MCP_TOOL_DEADLINE_SLACK_MS } from '../../constants/mcp/index.js'
 import { zodToJsonSchema } from '../../registry/tool/json-schema.js'
 import { type UntrustedEnvelope, wrapUntrusted } from '../../tools/untrusted-envelope.js'
 import type {
@@ -9,6 +10,7 @@ import type {
 } from '../../types/connector/index.js'
 import type { ToolResultBlock, ToolResultContent } from '../../types/message/index.js'
 import type { ToolContext, ToolDefinition, ToolResult } from '../../types/tool/index.js'
+import { MAX_TIMER_DELAY_MS as MAX_MCP_TIMER_DELAY_MS } from '../http-operation.js'
 import { admitMcpAudioBatch } from './audio-admission.js'
 import type { MCPClient } from './client.js'
 import { MCPInputRequiredError, isMissingRequiredClientCapabilityError } from './errors.js'
@@ -503,6 +505,12 @@ export function mcpToolToToolDefinition(
 	maxRetries?: number,
 ): ToolDefinition {
 	const inputSchema = mcpJsonSchemaToZod(tool.inputSchema)
+	// A call the client keeps alive on progress must not be cut by the
+	// executor's own per-tool deadline (120 s unless the host says otherwise)
+	// first. Only with `resetTimeoutOnProgress`; otherwise no `timeoutMs`, so
+	// every existing host keeps the executor's default.
+	const callWindowMs =
+		typeof client.getToolCallWindowMs === 'function' ? client.getToolCallWindowMs() : undefined
 	const toolName = `mcp_${serverName}_${tool.name}`
 
 	// Everything the server's own annotations carry that `isReadOnly`/
@@ -544,6 +552,9 @@ export function mcpToolToToolDefinition(
 		category: 'network',
 		permissions: ['network_access'],
 		...(maxRetries === undefined ? {} : { maxRetries }),
+		...(callWindowMs === undefined
+			? {}
+			: { timeoutMs: Math.min(callWindowMs + MCP_TOOL_DEADLINE_SLACK_MS, MAX_MCP_TIMER_DELAY_MS) }),
 		// Reports what the SERVER said, faithfully. The outbound re-export
 		// and the destructive label a human is shown both need the server's
 		// own answer; whether a gate may act on it is decided separately,

package/src/connector/mcp/client.ts

@@ -34,7 +34,10 @@ import { generateMCPClientId } from '../../utils/id.js'
 import type { LogAttributes } from '../../utils/log/index.js'
 import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
 import { type Logger, resolveLogger } from '../../utils/logger.js'
-import { validateConnectorTimeoutMs } from '../http-operation.js'
+import {
+	MAX_TIMER_DELAY_MS as MAX_MCP_TIMER_DELAY_MS,
+	validateConnectorTimeoutMs,
+} from '../http-operation.js'
 import { buildEnvelope, decodeResult } from './envelope.js'
 import {
 	type McpEraProbeAnswer,
@@ -60,6 +63,7 @@ import { type McpParamHeaderBinding, validateMcpHeaderAnnotations } from './x-mc
 import {
 	DEFAULT_MCP_ERA_PROBE_TIMEOUT_MS,
 	DEFAULT_MCP_REQUEST_TIMEOUT_MS,
+	DEFAULT_MCP_TOTAL_TIMEOUT_FACTOR,
 	JSON_RPC_INVALID_PARAMS,
 	JSON_RPC_METHOD_NOT_FOUND,
 	MCP_DISCOVER_METHOD,
@@ -236,7 +240,12 @@ export class MCPClient {
 	private nextRequestId = 1
 	private progressRequests = new Map<
 		string,
-		{ onProgress: (update: MCPProgressUpdate) => void; lastProgress?: number }
+		{
+			onProgress: (update: MCPProgressUpdate) => void
+			/** Called when a progress value is accepted; re-arms the idle deadline. */
+			onAccepted?: () => void
+			lastProgress?: number
+		}
 	>()
 	private notificationHandlers: Array<(method: string, params?: Record<string, unknown>) => void> =
 		[]
@@ -251,6 +260,9 @@ export class MCPClient {
 	private log: Logger
 	private readonly config: MCPClientConfig
 	private readonly requestTimeoutMs: number
+	private readonly resetTimeoutOnProgress: boolean
+	/** Total cap for a progress-extended call; meaningful only when `resetTimeoutOnProgress`. */
+	private readonly maxTotalTimeoutMs: number
 	private readonly eraCache: MCPEraCache
 	private readonly eraCacheKey: string
 	private readonly eraProbeTimeoutMs: number
@@ -265,12 +277,36 @@ export class MCPClient {
 	 */
 	private toolParamHeaders: Map<string, readonly McpParamHeaderBinding[]> = new Map()
 
+	/**
+	 * The longest a `tools/call` can legitimately take on this client, or
+	 * `undefined` when it has only the fixed request deadline.
+	 *
+	 * Defined only with `resetTimeoutOnProgress`: the total cap. A layer that
+	 * bounds the call from outside (the executor's per-tool deadline) needs it
+	 * to avoid cutting a call this client would have kept alive.
+	 */
+	getToolCallWindowMs(): number | undefined {
+		return this.resetTimeoutOnProgress ? this.maxTotalTimeoutMs : undefined
+	}
+
 	constructor(config: MCPClientConfig) {
 		this.config = config
 		this.requestTimeoutMs = validateConnectorTimeoutMs(
 			config.requestTimeoutMs ?? DEFAULT_MCP_REQUEST_TIMEOUT_MS,
 			'MCPClient requestTimeoutMs',
 		)
+		this.resetTimeoutOnProgress = config.resetTimeoutOnProgress === true
+		const maxTotal = validateConnectorTimeoutMs(
+			config.maxTotalTimeoutMs ??
+				Math.min(this.requestTimeoutMs * DEFAULT_MCP_TOTAL_TIMEOUT_FACTOR, MAX_MCP_TIMER_DELAY_MS),
+			'MCPClient maxTotalTimeoutMs',
+		)
+		if (maxTotal < this.requestTimeoutMs) {
+			throw new Error(
+				`MCPClient maxTotalTimeoutMs must not be below requestTimeoutMs (${this.requestTimeoutMs}); received ${maxTotal}`,
+			)
+		}
+		this.maxTotalTimeoutMs = maxTotal
 		// Never longer than one round trip's deadline: a probe IS a request,
 		// and one that outlived the bound every other request is held to
 		// would be a connect that hangs past its own timeout.
@@ -1209,6 +1245,8 @@ export class MCPClient {
 		options?.signal?.throwIfAborted()
 		const id = this.nextRequestId++
 		const progressToken = method === 'tools/call' && options?.onProgress ? randomUUID() : undefined
+		// Only a call that can receive progress can have its deadline extended.
+		const extendable = this.resetTimeoutOnProgress && progressToken !== undefined
 		const requestParams =
 			progressToken === undefined
 				? params
@@ -1252,8 +1290,11 @@ export class MCPClient {
 		const onCallerAbort = (): void => {
 			settle('caller', options?.signal?.reason)
 		}
+		let idleTimer: ReturnType<typeof setTimeout> | undefined
+		let capTimer: ReturnType<typeof setTimeout> | undefined
 		const cleanup = (): void => {
-			clearTimeout(timer)
+			clearTimeout(idleTimer)
+			clearTimeout(capTimer)
 			options?.signal?.removeEventListener('abort', onCallerAbort)
 			if (this.pendingRequests.get(id) === entry) this.pendingRequests.delete(id)
 			if (progressToken !== undefined) this.progressRequests.delete(progressToken)
@@ -1304,21 +1345,40 @@ export class MCPClient {
 		}
 
 		this.pendingRequests.set(id, entry)
-		if (progressToken !== undefined && options?.onProgress) {
-			this.progressRequests.set(progressToken, { onProgress: options.onProgress })
-		}
-		const timer = setTimeout(() => {
-			const error = new Error(
-				`MCP request "${method}" to "${this.config.serverName}" timed out after ${this.requestTimeoutMs}ms`,
-			)
+		const expire = (deadline: 'request' | 'idle' | 'total_cap'): void => {
+			const limit = deadline === 'total_cap' ? this.maxTotalTimeoutMs : this.requestTimeoutMs
+			const what =
+				deadline === 'request'
+					? `timed out after ${limit}ms`
+					: deadline === 'idle'
+						? `timed out after ${limit}ms with no progress`
+						: `timed out at its total limit of ${limit}ms`
+			const error = new Error(`MCP request "${method}" to "${this.config.serverName}" ${what}`)
 			error.name = 'TimeoutError'
 			this.log.warn('MCP request timed out', {
 				'namzu.connector.server': this.config.serverName,
 				'namzu.connector.method': method,
-				'namzu.connector.timeout_ms': this.requestTimeoutMs,
+				'namzu.connector.timeout_ms': limit,
+				'namzu.connector.deadline': deadline,
 			})
 			settle('timeout', error)
-		}, this.requestTimeoutMs)
+		}
+		const armIdle = (): void => {
+			clearTimeout(idleTimer)
+			idleTimer = setTimeout(() => expire(extendable ? 'idle' : 'request'), this.requestTimeoutMs)
+		}
+		if (progressToken !== undefined && options?.onProgress) {
+			this.progressRequests.set(progressToken, {
+				onProgress: options.onProgress,
+				// A settled request has already cleared both timers and its
+				// registration, so a late notification cannot re-arm anything.
+				...(extendable ? { onAccepted: () => !settled && armIdle() } : {}),
+			})
+		}
+		armIdle()
+		if (extendable) {
+			capTimer = setTimeout(() => expire('total_cap'), this.maxTotalTimeoutMs)
+		}
 		options?.signal?.addEventListener('abort', onCallerAbort, { once: true })
 		// AbortSignal events are not replayed. This closes the listener-install
 		// race before the request is issued.
@@ -1685,6 +1745,9 @@ export class MCPClient {
 		if (typeof progress !== 'number' || !Number.isFinite(progress) || progress < 0) return
 		if (pending.lastProgress !== undefined && progress <= pending.lastProgress) return
 		pending.lastProgress = progress
+		// Re-arms before the callback runs, so a throwing `onProgress` still
+		// counts as progress; the total cap bounds that.
+		pending.onAccepted?.()
 		const total = params?.total
 		const message = progressMessage(params?.message)
 		const update: MCPProgressUpdate = {

package/src/constants/mcp/index.ts

@@ -70,6 +70,23 @@ export const MCP_SUPPORTED_PROTOCOL_VERSIONS: readonly string[] = [
  */
 export const DEFAULT_MCP_REQUEST_TIMEOUT_MS = 30_000
 
+/**
+ * How many request deadlines the total cap is when `resetTimeoutOnProgress`
+ * is on and the caller gave no `maxTotalTimeoutMs`: ten times
+ * `requestTimeoutMs` (5 minutes at the default), never above Node's maximum
+ * timer delay. Long enough for work that reports progress for minutes,
+ * short enough that a server which reports forever is still cut off.
+ */
+export const DEFAULT_MCP_TOTAL_TIMEOUT_FACTOR = 10
+
+/**
+ * Headroom added to the client's total cap when a bridged tool carries its
+ * own executor deadline, so the client's error (which names the deadline and
+ * sends the cancellation) is the one a caller sees rather than the
+ * executor's generic cut-off racing it.
+ */
+export const MCP_TOOL_DEADLINE_SLACK_MS = 5_000
+
 /** JSON-RPC 2.0 reserved code for parameters the receiver cannot accept. */
 export const JSON_RPC_INVALID_PARAMS = -32602