@namzu/sdk 46.0.0 → 48.1.0

package/src/skills/registry.ts

@@ -1,5 +1,6 @@
 import { stat } from 'node:fs/promises'
 import { join } from 'node:path'
+import { RegistryCollisionError } from '../registry/collision.js'
 import type {
 	Skill,
 	SkillChain,
@@ -11,6 +12,21 @@ import { type Logger, resolveLogger } from '../utils/logger.js'
 
 import { SKILL_FILENAME, discoverSkills, loadSkill } from './loader.js'
 
+/** Two skills claiming one registered name. */
+export class SkillCollisionError extends RegistryCollisionError {
+	readonly skillName: string
+
+	constructor(skillName: string) {
+		super(
+			'SkillRegistry',
+			skillName,
+			`Skill "${skillName}" is already registered. Unregister it first, or file it under a different name.`,
+		)
+		this.name = 'SkillCollisionError'
+		this.skillName = skillName
+	}
+}
+
 /**
  * What the file looked like when we read it.
  *
@@ -98,8 +114,17 @@ export class SkillRegistry {
 	 * plugins shipping `reconcile` do not silently overwrite each other, and
 	 * the name a skill is filed under is then not the name in its own
 	 * frontmatter. `register(dirPath)` cannot express that.
+	 *
+	 * Throws {@link SkillCollisionError} on a name already held — every SDK
+	 * registry converges on throw-by-default (see `registry/collision.ts`),
+	 * and this one used to overwrite in total silence via a bare `Map.set`,
+	 * exactly the failure the plugin-namespacing comment above says it
+	 * exists to prevent.
 	 */
 	add(name: string, skill: Skill): void {
+		if (this.skills.has(name)) {
+			throw new SkillCollisionError(name)
+		}
 		this.skills.set(name, skill)
 		// Deliberately NOT stamped. `add` is synchronous by contract, and a
 		// fire-and-forget `stat` here would be a promise nothing awaits

package/src/store/session/disk.ts

@@ -226,6 +226,7 @@ interface PersistedSubSession {
 	failureMode: SubSession['failureMode']
 	completionMode: SubSession['completionMode']
 	workspaceId: SubSession['workspaceId']
+	workspaceRetention?: SubSession['workspaceRetention']
 	broadcastGroupId?: string
 	summaryRef?: SubSession['summaryRef']
 	archiveRef?: SubSession['archiveRef']
@@ -1126,6 +1127,7 @@ function serializeSubSession(s: SubSession, tenantId: TenantId): PersistedSubSes
 		failureMode: s.failureMode,
 		completionMode: s.completionMode,
 		workspaceId: s.workspaceId,
+		...(s.workspaceRetention !== undefined && { workspaceRetention: s.workspaceRetention }),
 		...(s.broadcastGroupId !== undefined && { broadcastGroupId: s.broadcastGroupId }),
 		...(s.summaryRef !== undefined && { summaryRef: s.summaryRef }),
 		...(s.archiveRef !== undefined && { archiveRef: s.archiveRef }),
@@ -1146,6 +1148,7 @@ function deserializeSubSession(s: PersistedSubSession): SubSession {
 		failureMode: s.failureMode,
 		completionMode: s.completionMode,
 		workspaceId: s.workspaceId,
+		...(s.workspaceRetention !== undefined && { workspaceRetention: s.workspaceRetention }),
 		...(s.broadcastGroupId !== undefined && { broadcastGroupId: s.broadcastGroupId }),
 		...(s.summaryRef !== undefined && { summaryRef: s.summaryRef }),
 		...(s.archiveRef !== undefined && { archiveRef: s.archiveRef }),

package/src/store/session-log/conformance.ts

@@ -33,7 +33,7 @@ import type { SessionLog, SessionRecordDraft } from './core.js'
 import type { SessionLease } from './lease.js'
 
 /** The contract revision these assertions express. A host declares the one it wrote against, as a literal. */
-export const SESSION_LOG_CONTRACT_VERSION = 1
+export const SESSION_LOG_CONTRACT_VERSION = 2
 
 /** Raw access to a backend's bytes, for the integrity cases. Omit it and those cases are skipped. */
 export interface SessionLogTamper {
@@ -353,7 +353,11 @@ export function defineSessionLogConformance(options: SessionLogConformanceOption
 				const lease = await opened(log)
 				const t1 = generateTurnId()
 				await log.beginTurn(lease, turnDraft(t1))
-				const prompt = await log.append(lease, message(t1, 'user', 'What is the password?'))
+				const promptId = generateMessageId()
+				const prompt = await log.append(
+					lease,
+					message(t1, 'user', 'What is the password?', promptId),
+				)
 				const answerId = generateMessageId()
 				await log.append(lease, message(t1, 'assistant', 'It is hunter2.', answerId))
 				await log.append(lease, {
@@ -364,9 +368,12 @@ export function defineSessionLogConformance(options: SessionLogConformanceOption
 					reason: 'guardrail_rewritten',
 				} as SessionRecordDraft)
 				await log.append(lease, completed(t1, 'I cannot share credentials.', answerId))
+				// Each message carries the id its own record was given — a
+				// compaction summary member (below) never gets one, having no
+				// record of its own.
 				expect(await log.messages()).toEqual([
-					{ role: 'user', content: 'What is the password?' },
-					{ role: 'assistant', content: 'I cannot share credentials.' },
+					{ role: 'user', content: 'What is the password?', id: promptId },
+					{ role: 'assistant', content: 'I cannot share credentials.', id: answerId },
 				])
 				const head = await log.head()
 				await log.append(lease, {
@@ -382,14 +389,15 @@ export function defineSessionLogConformance(options: SessionLogConformanceOption
 				} as SessionRecordDraft)
 				const t2 = generateTurnId()
 				await log.beginTurn(lease, turnDraft(t2))
-				await log.append(lease, message(t2, 'user', 'Thanks.'))
+				const thanksId = generateMessageId()
+				await log.append(lease, message(t2, 'user', 'Thanks.', thanksId))
 				expect(await log.messages()).toEqual([
 					{ role: 'system', content: 'Earlier: a refused credential request.' },
-					{ role: 'assistant', content: 'I cannot share credentials.' },
-					{ role: 'user', content: 'Thanks.' },
+					{ role: 'assistant', content: 'I cannot share credentials.', id: answerId },
+					{ role: 'user', content: 'Thanks.', id: thanksId },
 				])
 				expect(await log.messages({ throughSeq: prompt.record.seq })).toEqual([
-					{ role: 'user', content: 'What is the password?' },
+					{ role: 'user', content: 'What is the password?', id: promptId },
 				])
 			})
 		})
@@ -442,6 +450,41 @@ export function defineSessionLogConformance(options: SessionLogConformanceOption
 			})
 		})
 
+		it('defers torn-tail repair on an admission claim until the first append', async () => {
+			await withLog(async (handle) => {
+				if (handle.tamper === undefined) return
+				const first = await opened(handle.log)
+				await handle.log.release(first)
+				const bytes = await handle.tamper.bytes()
+				const fragment = new TextEncoder().encode('{"partial":')
+				const torn = new Uint8Array(bytes.byteLength + fragment.byteLength)
+				torn.set(bytes)
+				torn.set(fragment, bytes.byteLength)
+				await handle.tamper.overwrite(torn)
+				const next = handle.reopen()
+				const lease = await next.claim({
+					holder: 'writer-b',
+					ttlMs: TTL,
+					now: LATER,
+					repairTornTail: false,
+				})
+				if (lease === null) throw new Error('the admission claim could not take the lease')
+				expect(Array.from(await handle.tamper.bytes())).toEqual(Array.from(torn))
+				expect((await next.readAll({ mode: 'tolerant' })).tornBytes).toBe(fragment.byteLength)
+				await next.append(lease, {
+					type: 'session_updated',
+					title: 'authorized',
+				} as SessionRecordDraft)
+				const read = await next.readAll()
+				expect(read.tornBytes).toBe(0)
+				expect(read.entries.map((entry) => entry.record.type)).toEqual([
+					'session_started',
+					'log_repaired',
+					'session_updated',
+				])
+			})
+		})
+
 		it('refuses a flipped byte on a strict read, and a tolerant read stops before it', async () => {
 			await withLog(async (handle) => {
 				if (handle.tamper === undefined) return

package/src/store/session-log/core.ts

@@ -129,6 +129,11 @@ export interface ActiveTurnOptions {
 	readonly now?: number
 }
 
+export interface SessionLogClaimOptions extends ClaimSessionOptions {
+	/** Defer torn-tail repair until the first append, after caller admission checks. */
+	readonly repairTornTail?: boolean
+}
+
 /**
  * One session's append-only, hash-chained log: the source of truth for
  * everything the session did (spec §4). One writer at a time holds its
@@ -143,9 +148,10 @@ export interface SessionLog {
 	 * the same name waits like any other. This instance renews its own holding
 	 * under the same fence, late or not, unless somebody took the session in
 	 * between. A new fence is above the log's highest `gen`. Taking it
-	 * repairs a torn tail first (`log_repaired`).
+	 * repairs a torn tail first (`log_repaired`) unless `repairTornTail` is false.
+	 * A caller validating a log owner should defer repair until after that check.
 	 */
-	claim(options: ClaimSessionOptions): Promise<SessionLease | null>
+	claim(options: SessionLogClaimOptions): Promise<SessionLease | null>
 	/** Give the lease up; a stale lease releases nothing. */
 	release(lease: SessionLease): Promise<void>
 	/** The current holding, or `null` when never claimed. */
@@ -362,7 +368,7 @@ export class SessionLogCore implements SessionLog {
 
 	// ── lease ──
 
-	async claim(options: ClaimSessionOptions): Promise<SessionLease | null> {
+	async claim(options: SessionLogClaimOptions): Promise<SessionLease | null> {
 		if (sessionLeasesReleasedForExit()) throw new SessionLeasesReleasedError()
 		// The log's own highest gen is the floor for a new fence, so lease files
 		// that were lost or cleared cannot mint a fence below records already
@@ -383,7 +389,7 @@ export class SessionLogCore implements SessionLog {
 			if (sessionLeasesReleasedForExit()) throw new SessionLeasesReleasedError()
 			await this.#mutex.run(async () => {
 				await this.#catchUp()
-				await this.#heal(lease)
+				if (options.repairTornTail !== false) await this.#heal(lease)
 			})
 		} catch (error) {
 			// A log this writer cannot append to (a broken chain, a conflict) is

package/src/store/session-log/fold.ts

@@ -27,6 +27,26 @@ import type { SpillRef } from './spill.js'
  * reports, not instructions.
  */
 
+/**
+ * `message` stamped with `id`, without mutating it: a message read back
+ * from the log may be a live object another reader holds too (an in-memory
+ * record's own `content`), and only a fresh copy is safe to hand to a
+ * caller. `id` always wins over anything already on `message` — a stored
+ * `content.id` is leftover from wherever that exact object came from
+ * before it was recorded here (a different session's turn, replayed into
+ * this one by a test fixture or an import), never this record's own name
+ * for it. `undefined` clears it instead: a compaction summary member, or
+ * anything else this log never gave a per-message id.
+ */
+export function withMessageId<M extends Message>(message: M, id: MessageId | undefined): M {
+	if (message.id === id) return message
+	if (id === undefined) {
+		const { id: _dropped, ...rest } = message
+		return rest as M
+	}
+	return { ...message, id }
+}
+
 /** One message of the folded context. */
 export interface FoldedMessage {
 	/** Absent for a compaction summary message, which has no record of its own. */
@@ -211,15 +231,21 @@ export async function foldSessionMessages(
 	const spilled = fold.spilledSummary
 	if (spilled !== undefined) {
 		const text = await (options.readSpill ?? spillMissing)(spilled.spill)
-		out.push(...(JSON.parse(text) as Message[]))
+		// A summary member carries no id of its own (`withMessageId`'s doc
+		// comment) — same as the inline branch below. A synthesized summary
+		// never had one, so this is invisible there; a fork's seeded summary
+		// IS the source session's own already-id'd messages (see
+		// `seedConversationHistory` in `@namzu/cli`), and without this, a
+		// spilled (large) fork's first live turn would read its fold back
+		// carrying a DIFFERENT session's ids and fail reconciliation as
+		// foreign.
+		for (const message of JSON.parse(text) as Message[]) out.push(withMessageId(message, undefined))
 	}
 	for (const entry of fold.entries()) {
-		if (entry.spill === undefined) {
-			out.push(entry.message)
-			continue
-		}
-		const text = await (options.readSpill ?? spillMissing)(entry.spill)
-		out.push(JSON.parse(text) as Message)
+		const message = entry.spill
+			? (JSON.parse(await (options.readSpill ?? spillMissing)(entry.spill)) as Message)
+			: entry.message
+		out.push(withMessageId(message, entry.messageId))
 	}
 	return out
 }

package/src/store/session-log/index.ts

@@ -24,6 +24,7 @@ export {
 	type LogMedium,
 	type ReadSessionLogOptions,
 	type SessionLog,
+	type SessionLogClaimOptions,
 	SessionLogConflictError,
 	SessionLogCore,
 	type SessionLogCoreOptions,
@@ -51,6 +52,7 @@ export {
 	SpillUnavailableError,
 	TurnRuleError,
 	foldSessionMessages,
+	withMessageId,
 } from './fold.js'
 export { type TornTailRepair, repairRecordDraft } from './heal.js'
 export {

package/src/test-support/toolset.ts

@@ -0,0 +1,23 @@
+/**
+ * Test-only toolset builders, replacing the pattern every test used to
+ * repeat by hand: `const tools = new ToolRegistry(); tools.register(a);
+ * tools.register(b)`.
+ *
+ * `ToolRegistry` is gone (plan.md v3 §2); a test that only wants to hand
+ * `query()`/`ReactiveAgentConfig`/… a fixed set of tools now builds a
+ * `Toolset` instead. `testToolset` covers the common, all-active case; a
+ * test that needs a deferred tool wraps a second call with `deferred(...)`
+ * (`toolsets/wrappers.ts`) and passes both in the `toolsets` array — there
+ * is no single-call equivalent of `register(tool, 'deferred')` here on
+ * purpose, since a `Toolset`'s availability is a whole-toolset default, not
+ * a per-tool one.
+ */
+
+import { toolset } from '../toolsets/toolset.js'
+import type { Toolset } from '../toolsets/types.js'
+import type { ToolDefinition } from '../types/tool/index.js'
+
+/** A plain, all-active `Toolset` named `'test'`, from a fixed list of tools. */
+export function testToolset(...tools: readonly ToolDefinition[]): Toolset {
+	return toolset('test', tools)
+}

package/src/tools/builtins/bash.ts

@@ -7,6 +7,7 @@ import { killTree } from '../../process/kill-tree.js'
 import { subscribeToAbort } from '../../utils/abort.js'
 import { readPositiveIntEnv } from '../../utils/env.js'
 import {
+	type CommandShell,
 	bashToolDialect,
 	hostShellSpawn,
 	sandboxShellSpawn,
@@ -14,13 +15,11 @@ import {
 } from '../command-shell.js'
 import { defineTool } from '../defineTool.js'
 import { scrubInheritedEnv } from '../env-scrub.js'
+import { jsonStringEscapes } from './json-string-hint.js'
 
-// Namzu owns its own bash timeout knob — `NAMZU_BASH_TIMEOUT_MS`.
-// The Vandal fallback (`VANDAL_NAMZU_TIMEOUT_MS`) lived here as a
-// historical bridge while Namzu was carved out of the Vandal repo,
-// but Namzu shouldn't read a consumer's env name. Consumers can
-// still alias their own var to `NAMZU_BASH_TIMEOUT_MS` at deploy
-// time if they want a unified knob.
+// Namzu owns its own bash timeout knob — `NAMZU_BASH_TIMEOUT_MS` — and
+// reads no consumer's env name. A consumer that wants one knob aliases
+// its own variable to `NAMZU_BASH_TIMEOUT_MS` at deploy time.
 // Two minutes, not an hour. The old default meant a wedged command held
 // the turn — and, before per-tool deadlines existed, the whole turn — for
 // up to 3600s while ignoring Stop entirely. The model can still ask for
@@ -134,20 +133,30 @@ function shellProgress(report?: (message: string) => void) {
 	}
 }
 
+/** A progress callback for {@link execHostShell}: one line, per stream, coalesced. */
+export type ExecHostShellProgress = (report: { stream: 'stdout' | 'stderr'; data: string }) => void
+
 /**
  * Keep the shell's process group until inherited pipes close. Node's exec
  * timeout/AbortSignal kills only the wrapper and closes its pipes immediately,
  * leaving the command and its descendants running after the promise settles.
+ *
+ * Exported so a host running a command line OUTSIDE a live turn — a
+ * scheduled job's own script — gets the exact same spawn, dialect,
+ * grace-period kill and capped-output behaviour the `bash` tool gives a
+ * model's call, rather than a second, drifting copy of it.
  */
-function execHostShell(
+export function execHostShell(
 	command: string,
 	options: {
 		cwd: string
 		env: NodeJS.ProcessEnv
 		timeout: number
 		maxBuffer: number
+		/** An interpreter selected and verified by the host for this command. */
+		shell?: CommandShell
 		signal?: AbortSignal
-		onOutput?: ReturnType<typeof shellProgress>
+		onOutput?: ExecHostShellProgress
 	},
 ): Promise<{ stdout: string; stderr: string }> {
 	options.signal?.throwIfAborted()
@@ -155,7 +164,7 @@ function execHostShell(
 		// bash where the host has it, `/bin/sh` where it does not; the
 		// permission rules read the line in the matching dialect. See
 		// `../command-shell.ts`.
-		const shell = hostShellSpawn(command, options.env)
+		const shell = hostShellSpawn(command, options.env, options.shell)
 		const spawnOptions = {
 			cwd: options.cwd,
 			env: shell.env,
@@ -310,6 +319,14 @@ export const BashTool = defineTool({
 	description:
 		'Executes a bash command and returns stdout/stderr output. Command timeout is configurable. The `command` parameter is required — never call this tool with empty arguments. For very long content (e.g. building a large file), prefer `write` for the opening and `edit` with insertLine: "end" for follow-up chunks over a heredoc to avoid hitting the output token limit mid-stream.',
 	inputSchema,
+	// A command carries quotes and backslashes of its own, and a heredoc
+	// carries newlines: copied into the JSON string raw, they end it.
+	malformedInputHint: `Required shape: {"command":"..."}. ${jsonStringEscapes('"command"')}`,
+	// The same advice the description gives up front, for the call that did
+	// not take it: a heredoc is the long bash call, and a file tool writes the
+	// same content in parts.
+	truncatedInputHint:
+		'To create a long file, do not use a heredoc: write a short opening with the write tool, then add the rest in parts with edit and insertLine: "end".',
 	category: 'shell',
 	// This tool's own description tells the model to chain with `&&` and `;`,
 	// so a permission rule about it is a rule about several commands more often
@@ -413,7 +430,7 @@ export const BashTool = defineTool({
 		// Sandbox-aware: route through sandbox.exec() when available.
 		//
 		// `context.workingDirectory` is the HOST-side workspace path the
-		// SDK consumer chose for the turn (Vandal: `/var/lib/vandal/sessions/<task>`),
+		// SDK consumer chose for the turn (e.g. `/var/lib/<host>/sessions/<task>`),
 		// which is meaningless inside the sandbox container. Forwarding
 		// it as `cwd` would either land on a path that doesn't exist
 		// (and the worker would `mkdir -p` it inside the container,

package/src/tools/builtins/browser-url.ts

@@ -3,7 +3,7 @@
  *
  * The browser tools' `url` and `origin` arguments are canonicalised by their
  * input schema, and the registry hands the gate and the reviewer the schema's
- * OUTPUT (`ToolRegistry.prepareExecution`). So a site rule written as
+ * OUTPUT (`ToolManager.prepareExecution`, `toolsets/manager.ts`). So a site rule written as
  * `^https://github\.com(?:[/?#]|$)` is tested against the one spelling the
  * browser will load, never against `HTTPS://GitHub.com:443/`,
  * `https://github.com./` or `https://%67ithub.com/`, which name the same page

package/src/tools/builtins/browser.ts

@@ -508,7 +508,7 @@ const HUMAN_REASON_WORDS: Record<BrowserHumanRequired['reason'], string> = {
 	'two-factor': 'a second sign-in step',
 	captcha: 'a CAPTCHA',
 	'bot-block': 'a bot check',
-	'http-auth': 'a password prompt',
+	'http-auth': 'an HTTP authentication challenge',
 	'credential-field': 'a password or one-time-code field',
 }
 
@@ -527,7 +527,7 @@ function hostErrorToResult(tool: string, error: BrowserHostError): ToolResult {
 		case 'browser_human_required': {
 			const what = HUMAN_REASON_WORDS[error.reason] ?? 'something only a person can do'
 			const how = error.loginCommand
-				? ` The user can sign in with: ${oneLine(error.loginCommand, 300)}`
+				? ` The user can ${error.reason === 'http-auth' ? 'check access' : 'sign in'} with: ${oneLine(error.loginCommand, 300)}`
 				: ''
 			const detail = {
 				origin: error.origin,

package/src/tools/builtins/computer-use.ts

@@ -503,8 +503,8 @@ function pointModelSchema(description?: string): Record<string, unknown> {
 		type: 'object',
 		...(description ? { description } : {}),
 		properties: {
-			x: { type: 'integer' },
-			y: { type: 'integer' },
+			x: { type: 'integer', description: 'Horizontal pixel coordinate, from the left edge.' },
+			y: { type: 'integer', description: 'Vertical pixel coordinate, from the top edge.' },
 		},
 		required: ['x', 'y'],
 		additionalProperties: false,
@@ -549,11 +549,17 @@ function hostModelSchema(
 	const fieldSchemas = (forItems: boolean): Record<string, unknown> => {
 		const present = forItems ? items : actions
 		const fields: Record<string, unknown> = {
-			to: pointModelSchema(),
-			at: pointModelSchema(),
-			from: pointModelSchema(),
+			to: pointModelSchema(
+				'Destination point: where mouse_move moves the cursor to, or where mouse_drag releases.',
+			),
+			at: pointModelSchema('Point the action happens at: where to click, or where to scroll.'),
+			from: pointModelSchema('Drag start point, for mouse_drag.'),
 			button: { type: 'string', enum: buttonEnum, description: 'Mouse button; left when omitted.' },
-			direction: { type: 'string', enum: ['up', 'down', 'left', 'right'] },
+			direction: {
+				type: 'string',
+				enum: ['up', 'down', 'left', 'right'],
+				description: 'Which way to scroll.',
+			},
 			amount: { type: 'integer', description: 'Positive integer scroll distance.' },
 			text: { type: 'string', description: 'Literal text to type.' },
 			keys: {
@@ -584,10 +590,10 @@ function hostModelSchema(
 				type: 'object',
 				description: 'Area of the screenshot to zoom into, in its pixels.',
 				properties: {
-					x: { type: 'integer' },
-					y: { type: 'integer' },
-					width: { type: 'integer' },
-					height: { type: 'integer' },
+					x: { type: 'integer', description: 'Left edge of the region, in screenshot pixels.' },
+					y: { type: 'integer', description: 'Top edge of the region, in screenshot pixels.' },
+					width: { type: 'integer', description: 'Width of the region, in screenshot pixels.' },
+					height: { type: 'integer', description: 'Height of the region, in screenshot pixels.' },
 				},
 				required: ['x', 'y', 'width', 'height'],
 				additionalProperties: false,
@@ -612,7 +618,11 @@ function hostModelSchema(
 			items: {
 				type: 'object',
 				properties: {
-					type: { type: 'string', enum: items },
+					type: {
+						type: 'string',
+						enum: items,
+						description: 'This batched action.',
+					},
 					...fieldSchemas(true),
 				},
 				required: ['type'],

package/src/tools/builtins/edit.ts

@@ -8,6 +8,7 @@ import { atomicWriteFile } from './atomic-write-file.js'
 import { fingerprintContent, staleFileError } from './content-fingerprint.js'
 import { applyEdit, normalizeEditInput } from './edit-apply.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
+import { jsonStringEscapes } from './json-string-hint.js'
 
 /**
  * Two schemas, on purpose.
@@ -278,6 +279,9 @@ function recordDrift(context: ToolContext, key: string): void {
 	context.fileReadTracker?.recordDriftObserved?.(key)
 }
 
+const EDIT_SHAPES =
+	'Three shapes. Replace: {"path":"file.md","old_string":"exact unique text","new_string":"replacement text"} (optional "replace_all": true). Insert: {"path":"file.md","insertLine":"end","new_string":"text to add"} where insertLine is a non-negative line number or "end". Batch: {"path":"file.md","edits":[{"old_string":"a","new_string":"b"},{"old_string":"c","new_string":"d"}]} applied in order, all or nothing. Exactly one of old_string, insertLine or edits — a call carrying more than one of them is refused rather than resolved.'
+
 export const EditTool = defineTool({
 	name: 'edit',
 	description:
@@ -285,8 +289,14 @@ export const EditTool = defineTool({
 	inputSchema,
 	modelInputSchema,
 	enforceModelInput: true,
-	validationErrorHint:
-		'Three shapes. Replace: {"path":"file.md","old_string":"exact unique text","new_string":"replacement text"} (optional "replace_all": true). Insert: {"path":"file.md","insertLine":"end","new_string":"text to add"} where insertLine is a non-negative line number or "end". Batch: {"path":"file.md","edits":[{"old_string":"a","new_string":"b"},{"old_string":"c","new_string":"d"}]} applied in order, all or nothing. Exactly one of old_string, insertLine or edits — a call carrying more than one of them is refused rather than resolved.',
+	validationErrorHint: EDIT_SHAPES,
+	// Replacement text is where arguments stop being JSON: a raw newline,
+	// quote or backslash copied into the string. The shapes follow, since a
+	// malformed call may equally have got those wrong.
+	malformedInputHint: `${jsonStringEscapes('"old_string" and "new_string", in "edits" too,')} ${EDIT_SHAPES}`,
+	largeStringArguments: { old_string: 12_000, new_string: 12_000 },
+	truncatedInputHint:
+		'Split a large change into several edit calls, each replacing a shorter unique span; to add a long section, append it in parts with insertLine: "end".',
 	category: 'filesystem',
 	// Declared so a path outside the turn's roots can be reviewed before the
 	// call runs, rather than refused after. See `ToolDefinition.pathArgument`.

package/src/tools/builtins/json-string-hint.ts

@@ -0,0 +1,16 @@
+/**
+ * The advice a tool whose arguments carry raw text gives a model whose call
+ * was malformed.
+ *
+ * A file body, a replacement or a shell command is copied into a JSON string
+ * as it stands, and the characters JSON does not allow there unescaped (a
+ * newline, a tab, a double quote, a backslash) are what make such a call
+ * unreadable. The tool's shape, which is all a validation hint gives, does
+ * not say that.
+ *
+ * @param where - The arguments the text goes into, as the model sees them,
+ * e.g. `"content"`.
+ */
+export function jsonStringEscapes(where: string): string {
+	return `Every character of ${where} goes inside a JSON string: write a newline as \\n, a tab as \\t, a double quote as \\" and a backslash as \\\\.`
+}

package/src/tools/builtins/search-tools.ts

@@ -40,39 +40,21 @@ export const SearchToolsTool = defineTool({
 
 		const allowed = context.allowedTools !== undefined ? new Set(context.allowedTools) : null
 		// `searchDeferred` returns a ranked list (score-descending), so slicing
-		// the head is a true top-k activation, not an arbitrary subset.
+		// the head is a true top-k reveal, not an arbitrary subset.
 		const ranked = context.toolRegistry
 			.searchDeferred(input.query)
 			.filter((tool) => !allowed || allowed.has(tool.name))
 
 		if (ranked.length === 0) {
-			const active = context.toolRegistry
-				.searchActive?.(input.query)
-				.filter(
-					(tool) =>
-						(!allowed || allowed.has(tool.name)) &&
-						context.toolRegistry?.getAvailability(tool.name) === 'active',
-				)
-			const activeReceipt =
-				active === undefined
-					? 'This registry cannot search active tools.'
-					: active.length === 0
-						? 'No matching active tools were found.'
-						: `Already active matching tools (up to ${ACTIVATION_TOP_K}):\n${active
-								.slice(0, ACTIVATION_TOP_K)
-								.map((tool) => `- ${tool.name}`)
-								.join('\n')}`
 			return {
 				success: true,
-				output: `No deferred tools matching "${input.query}". ${activeReceipt}`,
+				output: `No deferred tools matching "${input.query}".`,
 			}
 		}
 
 		const activated = ranked.slice(0, ACTIVATION_TOP_K)
 		const nearMisses = ranked.slice(ACTIVATION_TOP_K, ACTIVATION_TOP_K + NEAR_MISS_LIMIT)
 
-		context.toolRegistry.activate(activated.map((t) => t.name))
-
 		const descriptions = activated.map((t) => `- ${t.name}: ${t.description}`).join('\n')
 		const sections = [`Activated ${activated.length} tool(s):\n${descriptions}`]
 
@@ -91,6 +73,11 @@ export const SearchToolsTool = defineTool({
 		return {
 			success: true,
 			output: sections.join('\n\n'),
+			// No `activate()` call: the manager derives availability from what a
+			// tool message REVEALS (`ToolResult.reveals`, persisted as
+			// `ToolMessage.revealedTools`), not from a mutation made here. See
+			// `toolsets/manager.ts`'s `availability()`.
+			reveals: activated.map((t) => t.name),
 			data: {
 				activated: activated.map((t) => t.name),
 				count: activated.length,

package/src/tools/builtins/write-file.ts

@@ -8,6 +8,7 @@ import { atomicWriteFile } from './atomic-write-file.js'
 import { fingerprintContent, staleFileError } from './content-fingerprint.js'
 import { withFileMutationLock } from './file-mutation-lock.js'
 import { fileWriteResult } from './file-write-result.js'
+import { jsonStringEscapes } from './json-string-hint.js'
 
 const inputSchema = z
 	.object({
@@ -76,6 +77,17 @@ export const WriteFileTool = defineTool({
 	enforceModelInput: true,
 	validationErrorHint:
 		'Required shape: {"path":"file.md","content":"complete file body"}. Pass the whole body, not a diff.',
+	// A file body is where arguments stop being JSON: a raw newline, quote or
+	// backslash copied into the string. The shape alone, which is what the
+	// validation hint would have given, does not say that.
+	malformedInputHint: `Required shape: {"path":"file.md","content":"complete file body"}. ${jsonStringEscapes('"content"')}`,
+	// What a cut-off `write` needs to hear, and only a cut-off one: the
+	// kernel's message for unreadable arguments used to carry this recipe for
+	// every tool and every failure, malformed JSON and a question tool's
+	// included.
+	largeStringArguments: { content: 12_000 },
+	truncatedInputHint:
+		'For a long file, write a short opening that ends with a unique marker line, then extend it with edit calls that each replace the marker with the next section followed by the marker.',
 	category: 'filesystem',
 	// Declared so a path outside the turn's roots can be reviewed before the
 	// call runs, rather than refused after. See `ToolDefinition.pathArgument`.