@namzu/sdk 62.9.0 → 62.11.0

package/src/compaction/manager.ts

@@ -123,6 +123,30 @@ export class WorkingStateManager {
 		while (restorable.skills.length > MAX_RESTORABLE_SKILLS) restorable.skills.shift()
 	}
 
+	/**
+	 * Take in skills the conversation shows that this manager did not see load
+	 * (a turn that began from a history, or a resumed one). They count as older
+	 * than anything this manager recorded itself, and never replace it.
+	 * `skills` is oldest first.
+	 */
+	adoptSkillBodies(skills: readonly { readonly name: string; readonly body: string }[]): void {
+		const missing = skills.filter(
+			(skill) =>
+				skill.name.trim().length > 0 &&
+				skill.body.trim().length > 0 &&
+				!this.state.restorable?.skills.some((held) => held.name === skill.name),
+		)
+		if (missing.length === 0) return
+		const restorable = this.restorableState()
+		restorable.skills.unshift(
+			...missing.map((skill) => ({
+				name: skill.name,
+				body: skill.body.slice(0, MAX_RESTORABLE_CHARS),
+			})),
+		)
+		while (restorable.skills.length > MAX_RESTORABLE_SKILLS) restorable.skills.shift()
+	}
+
 	/** Remember what a read returned so a compaction can put it back. */
 	recordFileText(path: string, text: string): void {
 		const key = normalizeRestorablePath(path)

package/src/compaction/manual.ts

@@ -15,6 +15,7 @@ import {
 	extractFromToolResult,
 	extractFromUserMessage,
 } from './extractor.js'
+import { adoptableSkills, handledSkillNames } from './loaded-skills.js'
 import { WorkingStateManager } from './manager.js'
 import {
 	type CompactionSummaryRouter,
@@ -156,6 +157,7 @@ function withRestoredContext(
 	body: string,
 	manager: WorkingStateManager,
 	input: CompactNowInput,
+	kept: readonly Message[],
 ): string {
 	const window = resolveContextWindow(
 		input.contextWindowTokens ?? input.config.contextWindowTokens,
@@ -163,6 +165,8 @@ function withRestoredContext(
 	)
 	const restored = renderRestoredContext(manager.getState(), {
 		contextWindowTokens: window.tokens,
+		// Instructions already whole in what the pass keeps are not put back twice.
+		wholeSkills: handledSkillNames(kept),
 		...(input.restoreNote ? { hostNote: input.restoreNote } : {}),
 	})
 	return restored ? `${body}\n\n${restored}` : body
@@ -175,6 +179,9 @@ function populateWorkingState(
 	config: CompactionConfig,
 ): void {
 	let firstUser = true
+	// Skills an earlier pass put back (an entry, or a summary's restored
+	// section) are not tool results, so they are read from the messages whole.
+	manager.adoptSkillBodies(adoptableSkills(messages))
 	const toolNames = new Map<string, string>()
 	const toolInputs = new Map<string, unknown>()
 
@@ -283,7 +290,11 @@ export async function compactNow(input: CompactNowInput): Promise<CompactionResu
 
 	const { messages, summary } = splice(
 		preservedSystem,
-		withRestoredContext(body, manager, input),
+		withRestoredContext(body, manager, input, [
+			...preservedSystem,
+			...retainedOlder,
+			...plan.recentMessages,
+		]),
 		retainedOlder,
 		plan.recentMessages,
 		input.recoveryNote,
@@ -379,7 +390,14 @@ export async function compactRegion(input: CompactRegionInput): Promise<Compacti
 	// Same cross-run ownership as compactNow: a selected region has been
 	// replaced outside a turn, so its only surviving account is pinned.
 	const summary = {
-		...buildCompactionMessage(withRestoredContext(body, manager, input), input.recoveryNote),
+		...buildCompactionMessage(
+			withRestoredContext(body, manager, input, [
+				...messages.slice(0, start),
+				...retainedSelected,
+				...messages.slice(end),
+			]),
+			input.recoveryNote,
+		),
 		retain: true,
 	}
 	const out = [...messages.slice(0, start), summary, ...retainedSelected, ...messages.slice(end)]

package/src/compaction/restore.ts

@@ -1,7 +1,18 @@
 import { resolve as resolvePath } from 'node:path'
 
 import { CHARS_PER_TOKEN } from '../constants/limits.js'
+import {
+	CARRY_MAX_SKILLS,
+	CARRY_SKILLS_TOTAL_TOKENS,
+	CARRY_SKILLS_WINDOW_SHARE,
+	CARRY_SKILL_TOKENS,
+	type RenderedSkills,
+	isForkedSkillReport,
+	renderLoadedSkills,
+	skillResultBody,
+} from './loaded-skills.js'
 import type { WorkingStateManager } from './manager.js'
+import { isClearedToolResult } from './tool-result-editing.js'
 import type { WorkingState } from './types.js'
 
 /**
@@ -16,11 +27,11 @@ import type { WorkingState } from './types.js'
  */
 
 /** Skills restored per pass, most recent first. */
-export const RESTORE_MAX_SKILLS = 8
+export const RESTORE_MAX_SKILLS = CARRY_MAX_SKILLS
 /** Tokens of one restored skill. */
-export const RESTORE_SKILL_TOKENS = 5_000
+export const RESTORE_SKILL_TOKENS = CARRY_SKILL_TOKENS
 /** Tokens of all restored skills together. */
-export const RESTORE_SKILLS_TOTAL_TOKENS = 25_000
+export const RESTORE_SKILLS_TOTAL_TOKENS = CARRY_SKILLS_TOTAL_TOKENS
 /** Files restored per pass, most recent first. */
 export const RESTORE_MAX_FILES = 5
 /** Tokens of one restored file. */
@@ -30,10 +41,9 @@ export const RESTORE_FILES_TOTAL_TOKENS = 50_000
 /** The share of the window all restored files may take. */
 export const RESTORE_FILES_WINDOW_SHARE = 0.1
 /** The share of the window all restored skills may take. */
-export const RESTORE_SKILLS_WINDOW_SHARE = 0.05
+export const RESTORE_SKILLS_WINDOW_SHARE = CARRY_SKILLS_WINDOW_SHARE
 
 const CUT_MARKER = '\n… [cut to fit the restore budget]'
-const SKILL_CONTINUATION = /\n\n\[More skill instructions remain\.[^\]]*\]/g
 
 function isInstructionPath(path: string): boolean {
 	const normal = path.replace(/\\/g, '/')
@@ -73,9 +83,13 @@ export function recordRestorable(
 	if (!input) return
 	if (call.toolName === 'skill') {
 		if (!call.success || typeof input.name !== 'string') return
+		// A cleared result is a placeholder, not the instructions.
+		if (isClearedToolResult(call.output)) return
+		// A delegated agent's report is not the skill's instructions.
+		if (isForkedSkillReport(call.output)) return
 		manager.recordSkillBody(
 			input.name,
-			call.output.replace(SKILL_CONTINUATION, ''),
+			skillResultBody(call.output),
 			typeof input.cursor === 'string' && input.cursor.length > 0,
 		)
 		return
@@ -105,6 +119,10 @@ export interface RestoreRenderOptions {
 	readonly contextWindowTokens?: number
 	/** A host's own line to carry across, such as where its plan file is. */
 	readonly hostNote?: string
+	/** Skills whose instructions are already whole in the messages that follow the summary; not shown again. */
+	readonly wholeSkills?: ReadonlySet<string>
+	/** Told which skills were put back, which were cut and which were left out. */
+	readonly onSkills?: (rendered: RenderedSkills) => void
 }
 
 /** The section to append after a summary, or `undefined` when there is nothing to put back. */
@@ -113,10 +131,6 @@ export function renderRestoredContext(
 	options: RestoreRenderOptions = {},
 ): string | undefined {
 	const window = options.contextWindowTokens
-	const skillsTotal =
-		window === undefined
-			? RESTORE_SKILLS_TOTAL_TOKENS
-			: Math.min(RESTORE_SKILLS_TOTAL_TOKENS, Math.floor(window * RESTORE_SKILLS_WINDOW_SHARE))
 	const filesTotal =
 		window === undefined
 			? RESTORE_FILES_TOTAL_TOKENS
@@ -124,14 +138,15 @@ export function renderRestoredContext(
 
 	const sections: string[] = []
 
-	let skillBudget = skillsTotal
-	const skills = [...(state.restorable?.skills ?? [])].reverse()
-	for (const skill of skills) {
-		if (sections.length >= RESTORE_MAX_SKILLS || skillBudget <= 0) break
-		const body = fit(skill.body, Math.min(RESTORE_SKILL_TOKENS, skillBudget))
-		skillBudget -= Math.ceil(body.length / CHARS_PER_TOKEN)
-		sections.push(`### Skill: ${skill.name}\n\n${body}`)
-	}
+	const toShow = (state.restorable?.skills ?? []).filter(
+		(skill) => !options.wholeSkills?.has(skill.name),
+	)
+	const skills = renderLoadedSkills(
+		toShow,
+		window === undefined ? {} : { contextWindowTokens: window },
+	)
+	options.onSkills?.(skills)
+	if (skills.text) sections.push(`### Skills loaded earlier\n\n${skills.text}`)
 
 	let fileBudget = filesTotal
 	let files = 0

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
 

package/src/contracts/session/api.ts

@@ -64,6 +64,7 @@ export type SessionStreamEventType =
 	| 'compaction.completed'
 	/** Oversized tool results were emptied instead of the history summarized. */
 	| 'compaction.tool_results_cleared'
+	| 'compaction.skills_carried'
 	| 'memory.consolidated'
 	| 'memory.recalled'
 	| 'background_job.exited'

package/src/execution/workflow/phases.ts

@@ -12,25 +12,51 @@ export interface PhaseRecord {
 	readonly declared: boolean
 }
 
+/**
+ * The entry of `entries` a title belongs to: one with exactly that title
+ * first; only when there is none, the first one whose title matches ignoring
+ * case. Two entries that differ only by case therefore stay two, because each
+ * matches itself exactly.
+ */
+function matchTitle<T extends { readonly title: string }>(
+	entries: Iterable<T>,
+	title: string,
+): T | undefined {
+	const lower = title.toLowerCase()
+	let loose: T | undefined
+	for (const entry of entries) {
+		if (entry.title === title) return entry
+		if (loose === undefined && entry.title.toLowerCase() === lower) loose = entry
+	}
+	return loose
+}
+
 /**
  * Phase titles of one run. A title is the only grouping key: the same title
- * is the same group. Indexes are 1-based first-seen order, declared titles
+ * is the same group. A title matches a registered one exactly first; only when
+ * none matches exactly does it match one ignoring case (the first registered
+ * wins, and its spelling is kept). Two declared titles that differ only by
+ * case stay two phases. Indexes are 1-based first-seen order, declared titles
  * first. `register` reports whether the title was announced just now.
  */
 export class PhaseRegistry {
-	private readonly byTitle = new Map<string, PhaseRecord>()
+	private readonly records: PhaseRecord[] = []
 
 	register(rawTitle: string, declared = false): { phase: PhaseRecord; isNew: boolean } {
 		const title = normalizePhaseTitle(rawTitle)
-		const existing = this.byTitle.get(title)
+		// A declared title is matched exactly only, so two declared titles that
+		// differ only by case each get their own phase.
+		const existing = declared
+			? this.records.find((record) => record.title === title)
+			: matchTitle(this.records, title)
 		if (existing) return { phase: existing, isNew: false }
-		const phase = { index: this.byTitle.size + 1, title, declared }
-		this.byTitle.set(title, phase)
+		const phase = { index: this.records.length + 1, title, declared }
+		this.records.push(phase)
 		return { phase, isNew: true }
 	}
 
 	all(): PhaseRecord[] {
-		return [...this.byTitle.values()]
+		return [...this.records]
 	}
 }
 
@@ -57,7 +83,7 @@ export function summarizeWorkflowPhases(
 	phases: readonly PhaseRecord[],
 	agents: readonly PhaseAgentView[],
 ): WorkflowPhaseSummary[] {
-	const detail = new Map(declared.map((p) => [normalizePhaseTitle(p.title), p.detail]))
+	const named = declared.map((p) => ({ title: normalizePhaseTitle(p.title), detail: p.detail }))
 	const summarize = (
 		index: number,
 		title: string,
@@ -82,7 +108,7 @@ export function summarizeWorkflowPhases(
 			p.index,
 			p.title,
 			agents.filter((a) => a.phaseIndex === p.index),
-			detail.get(p.title),
+			matchTitle(named, p.title)?.detail,
 		),
 	)
 	const ungrouped = agents.filter((a) => a.phaseIndex === undefined)