@namzu/sdk 48.3.1 → 50.0.0

package/src/tools/coordinator/index.ts

@@ -3,7 +3,8 @@ import type { PlanManager } from '../../manager/plan/lifecycle.js'
 import type { PendingAnswers, QuestionParkRecorder } from '../../runtime/query/question-park.js'
 import type { CompletionInbox } from '../../scheduler/completion-inbox.js'
 import type { AgentRuntimeContext } from '../../types/agent/base.js'
-import type { TaskScheduler } from '../../types/agent/scheduler.js'
+import type { TaskHandle, TaskScheduler } from '../../types/agent/scheduler.js'
+import { isTerminalAgentTaskState } from '../../types/agent/task.js'
 import type { ResumeHandler } from '../../types/hitl/index.js'
 import type { SessionId, TaskId, TurnId } from '../../types/ids/index.js'
 import type { TaskStore } from '../../types/task/index.js'
@@ -402,6 +403,29 @@ function delegatedAnswer(
 	return result?.result
 }
 
+/** Keep an empty answer from hiding the worker's error on any result path. */
+function delegatedResultText(completed: Pick<TaskHandle, 'state' | 'result'>): {
+	resultText: string
+	outputText: string
+} {
+	const success = taskSucceeded(completed)
+	const answer = delegatedAnswer(completed.result)
+	const lastError = completed.result?.lastError
+	const outcomeText = `Task finished with outcome: ${failureLabel(completed)}`
+	const resultText =
+		(answer?.trim() ? answer : lastError) ||
+		(success ? `Task finished with state: ${completed.state}` : outcomeText)
+	const outputText =
+		success || resultText === outcomeText
+			? resultText
+			: [
+					outcomeText,
+					...(lastError && lastError !== resultText ? [`Error: ${lastError}`] : []),
+					resultText,
+				].join('\n')
+	return { resultText, outputText }
+}
+
 export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefinition[] {
 	const {
 		gateway,
@@ -451,6 +475,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 	 * here. That is the same rule, not an exception to it.
 	 */
 	const launchedHere = new Set<TaskId>()
+	const trackedCompletions = new Map<TaskId, Promise<TaskHandle>>()
 	void opts.onTaskLaunched
 
 	const agentIdEnum = delegateSchema(agentIds)
@@ -573,10 +598,12 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			// could report `failed` or stay `executing` forever but never
 			// `completed`.
 			const planStepId = plan_step_id
-			const planId = planStepId ? getPlanManager?.()?.active?.id : undefined
+			const planManager = planStepId ? getPlanManager?.() : undefined
+			const planId = planManager?.active?.id
 			const reportStep = (status: 'running' | 'completed' | 'failed', error?: string): void => {
-				if (!planStepId) return
-				getPlanManager?.()?.updateStepStatus(planStepId, status, error)
+				// A replacement plan may reuse step ids; it is not this worker's plan.
+				if (!planStepId || !planId || planManager?.active?.id !== planId) return
+				planManager.updateStepStatus(planStepId, status, error)
 			}
 			reportStep('running')
 
@@ -599,49 +626,6 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				}
 			}
 
-			const handle = await gateway.createTask({
-				agentId: agent_id,
-				prompt,
-				workingDirectory: cwd,
-				runtimeContext: opts.runtimeContext,
-				...(planStepId ? { planStepId } : {}),
-				...(planId ? { planId } : {}),
-				// Hang the child session off THIS tool's span, so the delegation
-				// shows up inside the turn that asked for it.
-				...(_context.parentSpan ? { parentSpan: _context.parentSpan } : {}),
-				// Same as the `Agent` tool: a delegate inherits the environment
-				// its parent was given, or it runs against different services
-				// than the turn that asked for the work — and the turn's screens,
-				// for the same reason: the child's executor installs the shipped
-				// default unless the spawn says otherwise, so a parent that
-				// turned them off had that decision revert behind every
-				// delegation. One merged `configOverrides`, because a second
-				// spread of the key would replace this one.
-				...(Object.keys(_context.env ?? {}).length > 0 || _context.toolResultGuardrails
-					? {
-							configOverrides: {
-								...(_context.env && Object.keys(_context.env).length > 0
-									? { env: _context.env }
-									: {}),
-								...(_context.toolResultGuardrails
-									? { toolResultGuardrails: _context.toolResultGuardrails }
-									: {}),
-							},
-						}
-					: {}),
-			})
-
-			// Whose task this is. The inbox ignores completions for anything it
-			// was not told about, because `onTaskCompleted` is a broadcast and a
-			// gateway shared between two supervisors would otherwise hand each
-			// of them the other's worker output. Said on BOTH paths: the
-			// blocking one needs it too, because the case the inbox exists for
-			// is exactly the blocking launch whose wait was abandoned.
-			completionInbox?.launched(handle.taskId)
-
-			// ...and whose it is for the READ side too. See `launchedHere`.
-			launchedHere.add(handle.taskId)
-
 			// A background launch asked for with nowhere to deliver it is
 			// REFUSED, not quietly turned into a blocking one.
 			//
@@ -677,6 +661,111 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				}
 			}
 
+			let handle: TaskHandle
+			try {
+				handle = await gateway.createTask({
+					agentId: agent_id,
+					prompt,
+					workingDirectory: cwd,
+					runtimeContext: opts.runtimeContext,
+					...(planStepId ? { planStepId } : {}),
+					...(planId ? { planId } : {}),
+					// Hang the child session off THIS tool's span, so the delegation
+					// shows up inside the turn that asked for it.
+					...(_context.parentSpan ? { parentSpan: _context.parentSpan } : {}),
+					// Same as the `Agent` tool: a delegate inherits the environment
+					// its parent was given, or it runs against different services
+					// than the turn that asked for the work — and the turn's screens,
+					// for the same reason: the child's executor installs the shipped
+					// default unless the spawn says otherwise, so a parent that
+					// turned them off had that decision revert behind every
+					// delegation. One merged `configOverrides`, because a second
+					// spread of the key would replace this one.
+					...(Object.keys(_context.env ?? {}).length > 0 || _context.toolResultGuardrails
+						? {
+								configOverrides: {
+									...(_context.env && Object.keys(_context.env).length > 0
+										? { env: _context.env }
+										: {}),
+									...(_context.toolResultGuardrails
+										? { toolResultGuardrails: _context.toolResultGuardrails }
+										: {}),
+								},
+							}
+						: {}),
+				})
+			} catch (launchError) {
+				// No handle means admission failed from this caller's perspective.
+				// A host scheduler may have dispatched before losing its response;
+				// neither a missing worker nor a safe retry is established here.
+				const failure = `Delegation admission failed: ${toErrorMessage(launchError)}. No task handle was returned; the worker dispatch outcome is not established.`
+				reportStep('failed', failure)
+				if (resolvedPlanTaskId && taskStore) {
+					try {
+						const updated = await taskStore.update(asTaskId(resolvedPlanTaskId), {
+							status: 'failed',
+							description: failure,
+						})
+						if (!updated)
+							throw new Error(
+								`Planning task ${resolvedPlanTaskId} disappeared during failed admission`,
+							)
+					} catch (trackingError) {
+						throw new AggregateError(
+							[launchError, trackingError],
+							`${failure} Planning settlement failed: ${toErrorMessage(trackingError)}`,
+							{ cause: launchError },
+						)
+					}
+				}
+				throw launchError
+			}
+
+			// Whose task this is. The inbox ignores completions for anything it
+			// was not told about, because `onTaskCompleted` is a broadcast and a
+			// gateway shared between two supervisors would otherwise hand each
+			// of them the other's worker output. Said on BOTH paths: the
+			// blocking one needs it too, because the case the inbox exists for
+			// is exactly the blocking launch whose wait was abandoned.
+			completionInbox?.launched(handle.taskId)
+
+			// ...and whose it is for the READ side too. See `launchedHere`.
+			launchedHere.add(handle.taskId)
+
+			// Own one completion for both delivery paths. Neither a background
+			// return nor an abandoned bounded wait discards these tracking writes.
+			if ((resolvedPlanTaskId && taskStore) || (planStepId && planId)) {
+				// A fast worker may already be terminal and forgotten by the gateway.
+				// The returned handle is the exact outcome; do not fetch it again.
+				const workerCompletion = isTerminalAgentTaskState(handle.state)
+					? Promise.resolve(handle)
+					: gateway.waitForTask(handle.taskId)
+				const completion = workerCompletion.then(async (completed) => {
+					const success = taskSucceeded(completed)
+					const { outputText } = delegatedResultText(completed)
+					if (resolvedPlanTaskId && taskStore) {
+						const updated = await taskStore.update(asTaskId(resolvedPlanTaskId), {
+							status: success ? 'completed' : 'failed',
+							description: success ? undefined : `Failed: ${outputText.substring(0, 200)}`,
+						})
+						if (!updated)
+							throw new Error(
+								`Planning task ${resolvedPlanTaskId} disappeared before worker settlement`,
+							)
+					}
+					reportStep(
+						success ? 'completed' : 'failed',
+						success ? undefined : outputText.slice(0, 200),
+					)
+					return completed
+				})
+				trackedCompletions.set(handle.taskId, completion)
+				completionInbox?.deferDelivery(
+					handle.taskId,
+					completion.then(() => {}),
+				)
+			}
+
 			if (background) {
 				// Tell the inbox to hold the turn open for this. Without it the
 				// supervisor could launch a worker, answer, and settle the turn
@@ -716,6 +805,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			const outcome = await waitForTaskWithBounds(gateway, handle.taskId, {
 				wallMs: DELEGATION_TIMEOUT_MS,
 				idleMs: DELEGATION_IDLE_MS,
+				completion: trackedCompletions.get(handle.taskId),
 			})
 			if (outcome.kind === 'timeout') {
 				return {
@@ -752,27 +842,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			// `isError: false`, while writing the plan task closed as though
 			// the work had been done.
 			const success = taskSucceeded(completed)
-			const resultText =
-				delegatedAnswer(completed.result) ??
-				completed.result?.lastError ??
-				`Task finished with state: ${failureLabel(completed)}`
-
-			if (resolvedPlanTaskId && taskStore) {
-				// The status carries the outcome now, rather than `completed`
-				// with the failure written into prose. A reader scanning
-				// statuses saw work that had been done; only a reader of every
-				// description saw otherwise — and a dependent unit had no way
-				// to tell at all.
-				await taskStore.update(asTaskId(resolvedPlanTaskId), {
-					status: success ? 'completed' : 'failed',
-					description: success ? undefined : `Failed: ${resultText.substring(0, 200)}`,
-				})
-			}
-
-			// The step reports the same outcome, from the same two authorities.
-			// This is the only point in a delegated launch where the answer is
-			// actually known.
-			reportStep(success ? 'completed' : 'failed', success ? undefined : resultText.slice(0, 200))
+			const { resultText, outputText } = delegatedResultText(completed)
 
 			return {
 				success,
@@ -797,7 +867,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 						attributes: { agent: agent_id, task: handle.taskId },
 						provenance: `This is the output of the delegated agent "${agent_id}", not this agent's own work.`,
 					},
-					resultText,
+					outputText,
 				),
 				data: {
 					task_id: handle.taskId,
@@ -870,6 +940,7 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			const outcome = await waitForTaskWithBounds(gateway, taskId, {
 				wallMs: DELEGATION_TIMEOUT_MS,
 				idleMs: DELEGATION_IDLE_MS,
+				completion: trackedCompletions.get(taskId),
 			})
 			if (outcome.kind === 'timeout') {
 				return {
@@ -888,11 +959,11 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 			}
 			completionInbox?.claim(taskId)
 
-			const success = completed.state === 'completed'
-			const resultText =
-				delegatedAnswer(completed.result) ??
-				completed.result?.lastError ??
-				`Task finished with state: ${completed.state}`
+			// Finishing the invocation does not prove the worker succeeded. Use
+			// the same two-authority check as the call that launched this task.
+			const success = taskSucceeded(completed)
+			const lastError = completed.result?.lastError
+			const { resultText, outputText } = delegatedResultText(completed)
 			return {
 				success,
 				output: wrapUntrusted(
@@ -901,12 +972,16 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 						attributes: { agent: completed.agentId, task: completed.taskId },
 						provenance: `This is the output of the delegated agent "${completed.agentId}", not this agent's own work.`,
 					},
-					resultText,
+					outputText,
 				),
 				data: {
 					task_id,
 					agent_id: completed.agentId,
 					state: completed.state,
+					...(completed.result?.status === undefined
+						? {}
+						: { turn_status: completed.result.status }),
+					...(lastError === undefined || lastError === null ? {} : { last_error: lastError }),
 					result: resultText,
 				},
 			}

package/src/tools/coordinator/wait-with-idle-bound.ts

@@ -47,6 +47,8 @@ export interface WaitBounds {
 	 * Omit to bound by the turn clock alone.
 	 */
 	readonly idleMs?: number
+	/** Reuse the launch's completion, including its tracking settlement. */
+	readonly completion?: Promise<TaskHandle>
 }
 
 /**
@@ -77,7 +79,7 @@ export async function waitForTaskWithBounds(
 	const idleBoundArmed = detach !== undefined && bounds.idleMs !== undefined
 
 	try {
-		const completion = gateway.waitForTask(taskId).then(
+		const completion = (bounds.completion ?? gateway.waitForTask(taskId)).then(
 			(handle): WaitOutcome => ({ kind: 'completed', handle }),
 			// A gateway that rejects has answered the question; let it through
 			// rather than reporting a timeout that did not happen.

package/src/tools/defineTool.ts

@@ -7,6 +7,7 @@ import type {
 } from '../types/tool/index.js'
 import type { ToolPresentation } from '../types/tool/presentation.js'
 import { toErrorMessage } from '../utils/error.js'
+import { failureFactsFromError } from './failure-facts.js'
 
 export interface DefineToolOptions<S extends z.ZodType> {
 	name: string
@@ -183,10 +184,13 @@ export function defineTool<S extends z.ZodType>(
 				return await options.execute(input, context)
 			} catch (err) {
 				const message = toErrorMessage(err)
+				const facts = failureFactsFromError(err)
 				return {
 					success: false,
 					output: '',
 					error: `${options.name} failed: ${message}`,
+					// The kind of failure, from the error's own code, for the person's view.
+					...(facts ? { facts } : {}),
 				}
 			}
 		},

package/src/tools/failure-facts.ts

@@ -0,0 +1,24 @@
+import type { ToolFacts } from '../types/tool/presentation.js'
+
+/**
+ * The kind of failure a thrown filesystem error is, as typed facts for the
+ * person's view. Read from the error's `code` and `path`, which Node sets
+ * structurally, and never from its message.
+ */
+export function failureFactsFromError(err: unknown): ToolFacts | undefined {
+	if (!err || typeof err !== 'object') return undefined
+	const { code, path } = err as { code?: unknown; path?: unknown }
+	const subject = typeof path === 'string' ? path : undefined
+	const reason =
+		code === 'ENOENT'
+			? 'not_found'
+			: code === 'EACCES' || code === 'EPERM'
+				? 'permission_denied'
+				: code === 'EISDIR' || code === 'ENOTDIR'
+					? 'not_a_file'
+					: code === 'EEXIST'
+						? 'already_exists'
+						: undefined
+	if (!reason) return undefined
+	return { kind: 'failure', reason, ...(subject ? { subject } : {}) }
+}

package/src/tools/host-output.ts

@@ -0,0 +1,136 @@
+import { execFileSync } from 'node:child_process'
+import { StringDecoder } from 'node:string_decoder'
+
+import { OEM_UPPER_HALF } from './oem-code-pages.js'
+
+/**
+ * Decodes the bytes a host command writes.
+ *
+ * Off Windows that is UTF-8. On Windows, cmd and console programs write the
+ * console's OEM code page (850 on Western installs, 857 on Turkish ones), not
+ * UTF-8, so a strict UTF-8 decode turns `ç` into U+FFFD. PowerShell and Node
+ * children do write UTF-8. So a stream starts as strict UTF-8 and falls back
+ * to the code page for good the first time it holds bytes that are not UTF-8.
+ */
+export interface HostOutputDecoder {
+	write(chunk: Buffer): string
+	end(): string
+}
+
+export interface HostOutputDecoderOptions {
+	readonly platform?: NodeJS.Platform
+	/** Windows only: the OEM code page. Default: probed once with `chcp`. */
+	readonly codePage?: number | undefined
+}
+
+let probedCodePage: number | null | undefined
+
+/** The console's active code page on Windows, probed once; null when unknown. */
+export function probeOemCodePage(): number | null {
+	if (probedCodePage !== undefined) return probedCodePage
+	try {
+		const out = execFileSync('cmd.exe', ['/d', '/s', '/c', 'chcp'], {
+			encoding: 'latin1',
+			windowsHide: true,
+			stdio: ['ignore', 'pipe', 'ignore'],
+			timeout: 5000,
+		})
+		const match = /(\d{3,5})\s*$/.exec(out.trim())
+		probedCodePage = match ? Number(match[1]) : null
+	} catch {
+		probedCodePage = null
+	}
+	return probedCodePage
+}
+
+/** A decoder for one non-UTF-8 console code page, or undefined when none is known. */
+function legacyDecoder(codePage: number | undefined): HostOutputDecoder | undefined {
+	if (codePage === undefined || codePage === 65001) return undefined
+	const table = OEM_UPPER_HALF[codePage]
+	if (table !== undefined) {
+		// Single-byte: no state between chunks.
+		return {
+			write(chunk) {
+				let text = ''
+				for (const byte of chunk)
+					text += byte < 0x80 ? String.fromCharCode(byte) : table[byte - 0x80]
+				return text
+			},
+			end: () => '',
+		}
+	}
+	// The WHATWG labels Node knows: Windows ANSI pages and IBM866.
+	const label =
+		codePage >= 1250 && codePage <= 1258
+			? `windows-${codePage}`
+			: codePage === 866
+				? 'ibm866'
+				: undefined
+	if (label === undefined) return undefined
+	try {
+		const decoder = new TextDecoder(label)
+		return {
+			write: (chunk) => decoder.decode(chunk, { stream: true }),
+			end: () => decoder.decode(),
+		}
+	} catch {
+		return undefined
+	}
+}
+
+/** The trailing bytes of `bytes` that start a UTF-8 character it does not finish. */
+function incompleteUtf8Tail(bytes: Buffer): Buffer {
+	for (let back = 1; back <= Math.min(3, bytes.length); back++) {
+		const byte = bytes[bytes.length - back] as number
+		if ((byte & 0xc0) === 0x80) continue
+		const needed = byte >= 0xf0 ? 4 : byte >= 0xe0 ? 3 : byte >= 0xc0 ? 2 : 1
+		return needed > back ? bytes.subarray(bytes.length - back) : Buffer.alloc(0)
+	}
+	return Buffer.alloc(0)
+}
+
+export function createHostOutputDecoder(options: HostOutputDecoderOptions = {}): HostOutputDecoder {
+	const platform = options.platform ?? process.platform
+	if (platform !== 'win32') return new StringDecoder('utf8')
+	const legacy = legacyDecoder(
+		'codePage' in options ? options.codePage : (probeOemCodePage() ?? undefined),
+	)
+	if (legacy === undefined) return new StringDecoder('utf8')
+	let utf8: InstanceType<typeof TextDecoder> | undefined = new TextDecoder('utf-8', { fatal: true })
+	// The bytes of a character cut by the last chunk, which the UTF-8 decoder
+	// holds internally and cannot hand back when the stream turns out not to
+	// be UTF-8: the legacy decoder must start from them, not lose them.
+	let tail: Buffer = Buffer.alloc(0)
+	return {
+		write(chunk) {
+			if (utf8 !== undefined) {
+				try {
+					const text = utf8.decode(chunk, { stream: true })
+					tail = incompleteUtf8Tail(chunk.length >= 3 ? chunk : Buffer.concat([tail, chunk]))
+					return text
+				} catch {
+					utf8 = undefined
+					return legacy.write(Buffer.concat([tail, chunk]))
+				}
+			}
+			return legacy.write(chunk)
+		},
+		end() {
+			if (utf8 !== undefined) {
+				try {
+					return utf8.decode()
+				} catch {
+					utf8 = undefined
+					return legacy.write(tail) + legacy.end()
+				}
+			}
+			return legacy.end()
+		},
+	}
+}
+
+/** Decode a whole captured buffer. */
+export function decodeHostOutput(bytes: Buffer, options: HostOutputDecoderOptions = {}): string {
+	const decoder = createHostOutputDecoder(options)
+	return decoder.write(bytes) + decoder.end()
+}

package/src/tools/memory/delete.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod'
+import { MemoryRevisionConflictError } from '../../store/memory/revision.js'
 import type { MemoryStore } from '../../types/memory/index.js'
+import { hasConditionalMemoryWrites } from '../../types/memory/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { asMemoryId } from '../../utils/id.js'
 import { defineTool } from '../defineTool.js'
@@ -8,17 +10,45 @@ export function buildDeleteMemoryTool(store: MemoryStore): ToolDefinition {
 	return defineTool({
 		name: 'delete_memory',
 		description:
-			'Permanently delete a stored memory by ID. Use update_memory with status archived when the record should remain available for inspection. Deletion does not erase past conversation transcripts.',
+			'Permanently delete a stored memory by ID. Use update_memory with status archived when the record should remain available for inspection. Deletion does not erase past conversation transcripts. Pass the revision from read_memory when available to refuse a stale deletion.',
 		inputSchema: z.object({
 			id: z.string().describe('Memory ID to permanently delete'),
+			revision: z
+				.string()
+				.min(1)
+				.optional()
+				.describe('Opaque revision from read_memory; refuse deletion if the record changed'),
 		}),
 		category: 'custom',
 		permissions: [],
 		readOnly: false,
 		destructive: true,
 		concurrencySafe: true,
-		async execute({ id }) {
-			const removed = await store.delete(asMemoryId(id))
+		async execute({ id, revision }) {
+			if (revision !== undefined && !hasConditionalMemoryWrites(store)) {
+				return {
+					success: false,
+					output: 'This memory store does not support revision-checked deletion.',
+					error: 'Conditional memory deletion unavailable',
+				}
+			}
+			let removed: boolean
+			try {
+				if (revision === undefined) {
+					removed = await store.delete(asMemoryId(id))
+				} else if (hasConditionalMemoryWrites(store)) {
+					await store.deleteIfRevision(asMemoryId(id), revision)
+					removed = true
+				} else throw new Error('Conditional memory support changed during the deletion.')
+			} catch (error) {
+				if (!(error instanceof MemoryRevisionConflictError)) throw error
+				return {
+					success: false,
+					output: error.message,
+					error: 'Memory changed since read',
+					data: { reason: 'revision_conflict' },
+				}
+			}
 			return {
 				success: removed,
 				output: removed ? `Memory deleted: ${id}.` : `Memory ${id} not found.`,

package/src/tools/memory/read.ts

@@ -4,8 +4,10 @@ import {
 	describeMemoryAge,
 	memoryLinkNames,
 } from '../../store/memory/links.js'
+import { MemoryRevisionUnavailableError } from '../../store/memory/revision.js'
 import type { MemoryId } from '../../types/ids/index.js'
 import type { MemoryContent, MemoryIndexEntry, MemoryStore } from '../../types/memory/index.js'
+import { hasConditionalMemoryWrites } from '../../types/memory/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import { allMemoryEntries, resolveMemoryReference } from './resolve.js'
@@ -43,7 +45,22 @@ export function buildReadMemoryTool(store: MemoryStore): ToolDefinition {
 
 			let entry: MemoryIndexEntry | undefined
 			let content: MemoryContent | undefined
-			if (store.getRecord) {
+			let revision: string | undefined
+			if (hasConditionalMemoryWrites(store)) {
+				try {
+					const record = await store.getVersionedRecord(memoryId)
+					entry = record?.entry
+					content = record?.content
+					revision = record?.revision
+				} catch (error) {
+					if (!(error instanceof MemoryRevisionUnavailableError)) throw error
+					// Legacy in-memory records may hold cloneable host objects with
+					// inaccessible bytes. Read them without claiming CAS support.
+					const record = await store.getRecord?.(memoryId)
+					entry = record?.entry
+					content = record?.content ?? (await store.get(memoryId))
+				}
+			} else if (store.getRecord) {
 				const record = await store.getRecord(memoryId)
 				entry = record?.entry
 				content = record?.content
@@ -92,9 +109,24 @@ export function buildReadMemoryTool(store: MemoryStore): ToolDefinition {
 			// A JSON body stays exactly the stored text, parseable as it was
 			// before these notes existed; its age and links are in `data`.
 			const annotate = notes.length > 0 && content.format !== 'json'
+			const output = annotate ? `${content.content}\n\n---\n${notes.join('\n')}` : content.content
 			return {
 				success: true,
-				output: annotate ? `${content.content}\n\n---\n${notes.join('\n')}` : content.content,
+				output,
+				// The executor sends output or content to the model, not data. Keep
+				// output byte-compatible (including JSON) while exposing the token
+				// in a separate model-visible text block.
+				...(revision !== undefined
+					? {
+							content: [
+								{ type: 'text' as const, text: output },
+								{
+									type: 'text' as const,
+									text: `Memory revision: ${revision}. Pass it as revision to update_memory or delete_memory to reject stale changes.`,
+								},
+							],
+						}
+					: {}),
 				data: {
 					id: content.id,
 					format: content.format,
@@ -102,6 +134,7 @@ export function buildReadMemoryTool(store: MemoryStore): ToolDefinition {
 					...(entry?.name !== undefined ? { name: entry.name } : {}),
 					...(entry?.type !== undefined ? { type: entry.type } : {}),
 					...(entry ? { updatedAt: entry.updatedAt } : {}),
+					...(revision !== undefined ? { revision } : {}),
 					...(resolved.length > 0 ? { links: resolved } : {}),
 				},
 			}