@namzu/sdk 48.3.0 → 49.0.0

package/src/store/memory/markdown.ts

@@ -5,15 +5,16 @@ import { dirname, join, resolve } from 'node:path'
 import { NamzuError } from '../../types/errors/index.js'
 import type { MemoryId } from '../../types/ids/index.js'
 import type {
+	ConditionalMemoryStore,
 	CreateMemoryParams,
 	MemoryContent,
 	MemoryIndexEntry,
 	MemoryRecord,
 	MemorySearchParams,
 	MemorySearchResult,
-	MemoryStore,
 	MemoryType,
 	UpdateMemoryParams,
+	VersionedMemoryRecord,
 } from '../../types/memory/index.js'
 import { assertMemoryStatus, isMemoryType } from '../../types/memory/index.js'
 import { atomicWriteFile } from '../../utils/atomic-write.js'
@@ -47,6 +48,7 @@ import {
 	acquireMemoryOperationLock,
 	validateMemoryLockTimeout,
 } from './operation-lock.js'
+import { MemoryRevisionConflictError, assertMemoryRevision, memoryRevision } from './revision.js'
 
 /**
  * Versioned like every other record this SDK persists. A memory file carries
@@ -296,7 +298,7 @@ function decodeMemoryFile(
  * holds with {@link MemoryNameConflictError}, and derives a free one from the
  * title when none is given.
  */
-export class MarkdownMemoryStore implements MemoryStore {
+export class MarkdownMemoryStore implements ConditionalMemoryStore {
 	private readonly directory: string
 	private readonly log: Logger
 	private readonly lockTimeoutMs: number
@@ -587,6 +589,15 @@ export class MarkdownMemoryStore implements MemoryStore {
 		})
 	}
 
+	async getVersionedRecord(id: MemoryId): Promise<VersionedMemoryRecord | undefined> {
+		return this.withLoaded(async (_dir, loaded) => {
+			const memory = loaded.get(id)
+			if (!memory) return undefined
+			const record = structuredClone({ entry: memory.entry, content: memory.content })
+			return { ...record, revision: memoryRevision(record) }
+		})
+	}
+
 	/** The current record held under `name`, archived included, or `undefined`. */
 	async getByName(name: string): Promise<MemoryRecord | undefined> {
 		return this.withLoaded(async (_dir, loaded) => {
@@ -603,10 +614,35 @@ export class MarkdownMemoryStore implements MemoryStore {
 	}
 
 	async update(id: MemoryId, updates: UpdateMemoryParams): Promise<MemoryIndexEntry | undefined> {
+		return this.updateInternal(id, updates)
+	}
+
+	async updateIfRevision(
+		id: MemoryId,
+		updates: UpdateMemoryParams,
+		expectedRevision: string,
+	): Promise<MemoryIndexEntry> {
+		const updated = await this.updateInternal(id, updates, expectedRevision)
+		if (!updated) throw new MemoryRevisionConflictError(id)
+		return updated
+	}
+
+	private async updateInternal(
+		id: MemoryId,
+		updates: UpdateMemoryParams,
+		expectedRevision?: string,
+	): Promise<MemoryIndexEntry | undefined> {
 		if (updates.status !== undefined) assertMemoryStatus(updates.status)
 		assertOptionalMemoryFields(updates)
 		return this.mutate(async (dir, loaded) => {
 			const existing = loaded.get(id)
+			if (expectedRevision !== undefined) {
+				assertMemoryRevision(
+					id,
+					existing ? { entry: existing.entry, content: existing.content } : undefined,
+					expectedRevision,
+				)
+			}
 			if (!existing) return undefined
 			const entries = this.entries(loaded)
 			if (updates.name !== undefined) {
@@ -645,8 +681,24 @@ export class MarkdownMemoryStore implements MemoryStore {
 	}
 
 	async delete(id: MemoryId): Promise<boolean> {
+		return this.deleteInternal(id)
+	}
+
+	async deleteIfRevision(id: MemoryId, expectedRevision: string): Promise<void> {
+		const deleted = await this.deleteInternal(id, expectedRevision)
+		if (!deleted) throw new MemoryRevisionConflictError(id)
+	}
+
+	private async deleteInternal(id: MemoryId, expectedRevision?: string): Promise<boolean> {
 		return this.mutate(async (dir, loaded) => {
 			const existing = loaded.get(id)
+			if (expectedRevision !== undefined) {
+				assertMemoryRevision(
+					id,
+					existing ? { entry: existing.entry, content: existing.content } : undefined,
+					expectedRevision,
+				)
+			}
 			if (!existing) return false
 			try {
 				await unlink(existing.path)

package/src/store/memory/memory.ts

@@ -1,13 +1,14 @@
 import type { MemoryId } from '../../types/ids/index.js'
 import type {
+	ConditionalMemoryStore,
 	CreateMemoryParams,
 	MemoryContent,
 	MemoryIndexEntry,
 	MemoryRecord,
 	MemorySearchParams,
 	MemorySearchResult,
-	MemoryStore,
 	UpdateMemoryParams,
+	VersionedMemoryRecord,
 } from '../../types/memory/index.js'
 import { assertMemoryStatus } from '../../types/memory/index.js'
 import { generateMemoryId } from '../../utils/id.js'
@@ -18,8 +19,9 @@ import {
 	nameHolder,
 	withOptionalFields,
 } from './naming.js'
+import { assertMemoryRevision, memoryRevision } from './revision.js'
 
-export class InMemoryMemoryStore implements MemoryStore {
+export class InMemoryMemoryStore implements ConditionalMemoryStore {
 	private content = new Map<string, MemoryContent>()
 	private index = new InMemoryMemoryIndex()
 
@@ -70,10 +72,45 @@ export class InMemoryMemoryStore implements MemoryStore {
 		return entry && content ? structuredClone({ entry, content }) : undefined
 	}
 
+	async getVersionedRecord(id: MemoryId): Promise<VersionedMemoryRecord | undefined> {
+		const entry = this.index.getEntry(id)
+		const content = this.content.get(id)
+		if (!entry || !content) return undefined
+		const record = structuredClone({ entry, content })
+		return { ...record, revision: memoryRevision(record) }
+	}
+
 	async update(id: MemoryId, updates: UpdateMemoryParams): Promise<MemoryIndexEntry | undefined> {
+		return this.updateNow(id, updates)
+	}
+
+	async updateIfRevision(
+		id: MemoryId,
+		updates: UpdateMemoryParams,
+		expectedRevision: string,
+	): Promise<MemoryIndexEntry> {
+		// No await between the check and mutation: one in-memory operation turn.
+		const entry = this.updateNow(id, updates, expectedRevision)
+		if (!entry) throw new Error('A conditional memory update unexpectedly found no record.')
+		return entry
+	}
+
+	private updateNow(
+		id: MemoryId,
+		updates: UpdateMemoryParams,
+		expectedRevision?: string,
+	): MemoryIndexEntry | undefined {
 		if (updates.status !== undefined) assertMemoryStatus(updates.status)
 		assertOptionalMemoryFields(updates)
 		const existing = this.index.getEntry(id)
+		if (expectedRevision !== undefined) {
+			const content = this.content.get(id)
+			assertMemoryRevision(
+				id,
+				existing && content ? { entry: existing, content } : undefined,
+				expectedRevision,
+			)
+		}
 		if (!existing) return undefined
 		if (updates.name !== undefined) {
 			const holder = nameHolder(this.index.allEntries(), updates.name, id)
@@ -118,6 +155,19 @@ export class InMemoryMemoryStore implements MemoryStore {
 	}
 
 	async delete(id: MemoryId): Promise<boolean> {
+		return this.deleteNow(id)
+	}
+
+	async deleteIfRevision(id: MemoryId, expectedRevision: string): Promise<void> {
+		this.deleteNow(id, expectedRevision)
+	}
+
+	private deleteNow(id: MemoryId, expectedRevision?: string): boolean {
+		if (expectedRevision !== undefined) {
+			const entry = this.index.getEntry(id)
+			const content = this.content.get(id)
+			assertMemoryRevision(id, entry && content ? { entry, content } : undefined, expectedRevision)
+		}
 		const existed = this.index.remove(id)
 		this.content.delete(id)
 		return existed

package/src/store/memory/revision.ts

@@ -0,0 +1,158 @@
+import { createHash } from 'node:crypto'
+import { NamzuError } from '../../types/errors/index.js'
+import type { MemoryId } from '../../types/ids/index.js'
+import type { MemoryRecord } from '../../types/memory/index.js'
+
+/** A record can be read, but its metadata cannot be fingerprinted synchronously. */
+export class MemoryRevisionUnavailableError extends Error {
+	constructor() {
+		super('This memory contains metadata that cannot be revision-checked.')
+		this.name = 'MemoryRevisionUnavailableError'
+	}
+}
+
+/**
+ * Encode the same structured-clone snapshot `getRecord` returns. Type tags,
+ * object references and sorted plain-object keys preserve values JSON loses:
+ * BigInt, undefined, Map/Set contents, Date, typed arrays and cycles. Map and
+ * Set order is kept because it is observable. Unknown host objects (notably
+ * Blob, whose bytes need asynchronous reading) fail closed rather than hash as
+ * `{}` and allow a stale conditional write.
+ */
+function canonicalRecord(record: MemoryRecord): string {
+	let snapshot: MemoryRecord
+	try {
+		snapshot = structuredClone(record)
+	} catch {
+		throw new MemoryRevisionUnavailableError()
+	}
+	const seen = new WeakMap<object, number>()
+	let nextId = 0
+
+	function encode(value: unknown): unknown {
+		if (value === null) return ['null']
+		switch (typeof value) {
+			case 'undefined':
+				return ['undefined']
+			case 'string':
+				return ['string', value]
+			case 'boolean':
+				return ['boolean', value]
+			case 'bigint':
+				return ['bigint', value.toString()]
+			case 'number':
+				return ['number', Object.is(value, -0) ? '-0' : String(value)]
+			case 'function':
+			case 'symbol':
+				throw new MemoryRevisionUnavailableError()
+			case 'object':
+				break
+		}
+
+		const object = value as object
+		const previous = seen.get(object)
+		if (previous !== undefined) return ['ref', previous]
+		const id = nextId++
+		seen.set(object, id)
+		if (Array.isArray(object)) {
+			return [
+				'array',
+				id,
+				object.length,
+				Object.keys(object)
+					.sort()
+					.map((key) => [key, encode((object as unknown as Record<string, unknown>)[key])]),
+			]
+		}
+		if (object instanceof Map) {
+			return ['map', id, [...object].map(([key, item]) => [encode(key), encode(item)])]
+		}
+		if (object instanceof Set) return ['set', id, [...object].map(encode)]
+		if (object instanceof Date) return ['date', id, encode(object.getTime())]
+		if (object instanceof RegExp)
+			return ['regexp', id, object.source, object.flags, object.lastIndex]
+		if (object instanceof ArrayBuffer) {
+			const buffer = object as ArrayBuffer & {
+				readonly maxByteLength?: number
+				readonly resizable?: boolean
+			}
+			return [
+				'array-buffer',
+				id,
+				buffer.byteLength,
+				buffer.maxByteLength,
+				buffer.resizable,
+				Buffer.from(buffer).toString('hex'),
+			]
+		}
+		if (ArrayBuffer.isView(object)) {
+			// A view exposes its entire backing buffer through `.buffer`, even
+			// when its visible slice is one byte. Structured cloning keeps that
+			// backing and preserves aliases between multiple views.
+			if (
+				(typeof SharedArrayBuffer !== 'undefined' && object.buffer instanceof SharedArrayBuffer) ||
+				(object.buffer instanceof ArrayBuffer &&
+					(object.buffer as ArrayBuffer & { readonly resizable?: boolean }).resizable === true)
+			)
+				throw new MemoryRevisionUnavailableError()
+			return [
+				'array-buffer-view',
+				id,
+				object.constructor.name,
+				object.byteOffset,
+				object.byteLength,
+				encode(object.buffer),
+			]
+		}
+		if (object instanceof Error) {
+			return ['error', id, object.name, object.message, object.stack, encode(object.cause)]
+		}
+		if (object instanceof Number || object instanceof String || object instanceof Boolean)
+			return ['boxed', id, object.constructor.name, encode(object.valueOf())]
+		if (typeof SharedArrayBuffer !== 'undefined' && object instanceof SharedArrayBuffer)
+			throw new MemoryRevisionUnavailableError()
+		const prototype = Object.getPrototypeOf(object)
+		if (prototype !== Object.prototype && prototype !== null)
+			throw new MemoryRevisionUnavailableError()
+		return [
+			'object',
+			id,
+			Object.keys(object as Record<string, unknown>)
+				.sort()
+				.map((key) => [key, encode((object as Record<string, unknown>)[key])]),
+		]
+	}
+
+	return JSON.stringify(encode(snapshot))
+}
+
+/** A content-derived token; it includes metadata as well as the body. */
+export function memoryRevision(record: MemoryRecord): string {
+	return `m2:${createHash('sha256').update(canonicalRecord(record)).digest('hex')}`
+}
+
+/** The record changed or disappeared after its revision was read. */
+export class MemoryRevisionConflictError extends NamzuError {
+	readonly memoryId: MemoryId
+
+	constructor(memoryId: MemoryId) {
+		super({
+			code: 'storage_error',
+			message: `Memory ${memoryId} changed since it was read. Read it again before changing it.`,
+			details: { memoryId, reason: 'revision_conflict' },
+			retryable: false,
+		})
+		this.name = 'MemoryRevisionConflictError'
+		this.memoryId = memoryId
+	}
+}
+
+export function assertMemoryRevision(
+	id: MemoryId,
+	record: MemoryRecord | undefined,
+	expectedRevision: string,
+): asserts record is MemoryRecord {
+	if (!record || memoryRevision(record) !== expectedRevision) {
+		throw new MemoryRevisionConflictError(id)
+	}
+}

package/src/tools/builtins/wait-for-job-bounds.ts

@@ -1,4 +1,5 @@
 import type { BackgroundJobRegistryRef } from '../../types/tool/index.js'
+import { subscribeToAbort } from '../../utils/abort.js'
 
 /**
  * Waiting on a background job, bounded by two different questions — the
@@ -42,6 +43,8 @@ interface JobWaitProgress {
 	readonly output: string
 	readonly nextOffset: number
 	readonly droppedBytes: number
+	/** Earlier bytes omitted from this wait's own bounded output, separately from registry loss. */
+	readonly omittedOutputBytes: number
 }
 
 export type JobWaitOutcome =
@@ -67,12 +70,27 @@ export type JobWaitOutcome =
  */
 const POLL_INTERVAL_MS = 1_000
 
+/** Leave room for the status and recovery instructions inside the tool-result budget. */
+const MAX_WAIT_OUTPUT_BYTES = 32 * 1024
+
+function boundedTail(value: string): { output: string; omittedBytes: number } {
+	const bytes = Buffer.from(value, 'utf8')
+	if (bytes.length <= MAX_WAIT_OUTPUT_BYTES) return { output: value, omittedBytes: 0 }
+	let start = bytes.length - MAX_WAIT_OUTPUT_BYTES
+	// The cap is in bytes, but the displayed tail must begin at a UTF-8 character.
+	while (start < bytes.length && ((bytes[start] ?? 0) & 0xc0) === 0x80) start++
+	return {
+		output: bytes.subarray(start).toString('utf8'),
+		omittedBytes: start,
+	}
+}
+
 /**
- * Await a job under both bounds, accumulating its output as it goes.
+ * Await a job under both bounds, retaining a bounded tail as it goes.
  *
- * Returns the output gathered so far either way: a completed wait has all
- * of it, and a timed-out one has everything read up to the moment it gave
- * up, so the caller never has to throw away a partial answer.
+ * A completed or timed-out wait returns the bytes it observed up to its
+ * absolute cursor. If the displayed tail could not hold all of them, its
+ * omitted-byte count keeps that gap visible to the caller.
  */
 export async function waitForJobWithBounds(
 	jobs: Pick<BackgroundJobRegistryRef, 'read' | 'waitForExit'>,
@@ -90,7 +108,16 @@ export async function waitForJobWithBounds(
 	let cursor = options.fromOffset ?? 0
 	let output = ''
 	let droppedBytes = 0
+	let omittedOutputBytes = 0
 	let settled = false
+	let poll: ReturnType<typeof setInterval> | undefined
+	// Each bounded wait owns its exit subscription. A timeout must release that
+	// subscription even when the job itself runs forever.
+	const waitAbort = new AbortController()
+	const forwardAbort = (): void => waitAbort.abort(options.signal?.reason)
+	let disposeCallerAbort = () => {}
+	if (options.signal?.aborted) forwardAbort()
+	else if (options.signal) disposeCallerAbort = subscribeToAbort(options.signal, forwardAbort)
 
 	/** Read whatever is new since `cursor`, and count it as progress if it is. */
 	const drain = (): void => {
@@ -98,11 +125,15 @@ export async function waitForJobWithBounds(
 		if (chunk.droppedBytes > 0) droppedBytes += chunk.droppedBytes
 		if (chunk.nextOffset > cursor) lastProgressAt = now()
 		cursor = chunk.nextOffset
-		if (chunk.chunk) output += chunk.chunk
+		if (chunk.chunk) {
+			const bounded = boundedTail(output + chunk.chunk)
+			output = bounded.output
+			omittedOutputBytes += bounded.omittedBytes
+		}
 	}
 
 	try {
-		const exited = waitForExit(id, { signal: options.signal }).then((job): JobWaitOutcome => {
+		const exited = waitForExit(id, { signal: waitAbort.signal }).then((job): JobWaitOutcome => {
 			// One last read: the job can exit between ticks, and the bytes
 			// it wrote in its final moment are exactly the ones a caller
 			// most wants — the error, the summary line, the exit trace.
@@ -114,6 +145,7 @@ export async function waitForJobWithBounds(
 				output,
 				nextOffset: cursor,
 				droppedBytes,
+				omittedOutputBytes,
 			}
 		})
 
@@ -135,6 +167,7 @@ export async function waitForJobWithBounds(
 						output,
 						nextOffset: cursor,
 						droppedBytes,
+						omittedOutputBytes,
 					})
 					return
 				}
@@ -149,10 +182,12 @@ export async function waitForJobWithBounds(
 							output,
 							nextOffset: cursor,
 							droppedBytes,
+							omittedOutputBytes,
 						})
 					}
 				}
 			}, POLL_INTERVAL_MS)
+			poll = tick
 			// Never the reason a process stays alive — this races a real
 			// exit promise, so the wait is held open by work that is
 			// genuinely outstanding rather than by this timer.
@@ -162,6 +197,9 @@ export async function waitForJobWithBounds(
 		return await Promise.race([exited, expiry])
 	} finally {
 		settled = true
+		if (poll !== undefined) clearInterval(poll)
+		disposeCallerAbort()
+		waitAbort.abort(new Error('Job wait finished'))
 	}
 }
 
@@ -171,7 +209,7 @@ export function describeJobWaitTimeout(
 	outcome: Extract<JobWaitOutcome, { kind: 'timeout' }>,
 ): string {
 	const seconds = Math.round(outcome.elapsedMs / 1000)
-	const resume = `call wait_for_job again, or job read with from_offset ${outcome.nextOffset}, to see what it does next`
+	const resume = `call wait_for_job or job read with from_offset ${outcome.nextOffset} to see only what comes next`
 	if (outcome.cause === 'idle') {
 		return `Job ${id} went quiet: no new output for a while, after ${seconds}s. It has not been stopped and may still be working — ${resume}.`
 	}

package/src/tools/builtins/wait-for-job.ts

@@ -35,6 +35,12 @@ const MAX_WAIT_MS = readPositiveIntEnv('NAMZU_JOB_WAIT_MAX_MS', 60 * 60 * 1000)
 
 const inputSchema = z.object({
 	id: z.string().describe('The job id, as returned by bash with run_in_background.'),
+	from_offset: z
+		.number()
+		.int()
+		.nonnegative()
+		.optional()
+		.describe('Resume after a previous wait: pass its next_offset to receive only new output.'),
 	timeout_ms: z
 		.number()
 		.int()
@@ -60,7 +66,7 @@ type WaitForJobInput = z.infer<typeof inputSchema>
 export const WaitForJobTool = defineTool({
 	name: 'wait_for_job',
 	description:
-		'Block until a background job started by bash with run_in_background ends, and return its accumulated output in one call. Use this instead of calling job with action "read" in a loop: it costs one call and no waiting turns. Gives up — WITHOUT stopping the job — if it runs too long or goes quiet for too long; either outcome says so, and the job keeps running either way.',
+		'Block until a background job started by bash with run_in_background ends, and return its bounded output in one call. Use this instead of calling job with action "read" in a loop: it costs one call and no waiting turns. A wait that runs too long or goes quiet returns its output and next_offset without stopping the job; pass that offset as from_offset on the next wait to avoid repeats.',
 	inputSchema,
 	category: 'shell',
 	permissions: ['shell_execute'],
@@ -128,6 +134,7 @@ export const WaitForJobTool = defineTool({
 			outcome = await waitForJobWithBounds(jobs, input.id, {
 				wallMs: input.timeout_ms ?? DEFAULT_TIMEOUT_MS,
 				idleMs: input.idle_timeout_ms ?? DEFAULT_IDLE_TIMEOUT_MS,
+				...(input.from_offset === undefined ? {} : { fromOffset: input.from_offset }),
 				signal: context.abortSignal,
 			})
 		} catch {
@@ -144,26 +151,32 @@ export const WaitForJobTool = defineTool({
 			}
 		}
 
+		const notices = [
+			...(outcome.droppedBytes > 0
+				? [`[${outcome.droppedBytes} bytes were dropped by the job's output retention cap]`]
+				: []),
+			...(outcome.omittedOutputBytes > 0
+				? [`[${outcome.omittedOutputBytes} earlier bytes omitted from this bounded wait result]`]
+				: []),
+		]
+		const observed = `${notices.length > 0 ? `${notices.join('\n')}\n` : ''}${outcome.output || '(no new output)'}`
+
 		if (outcome.kind === 'timeout') {
 			return {
-				success: false,
-				output: describeJobWaitTimeout(input.id, outcome),
+				// The wait observed a bound, not a failed command. A tool error
+				// would also be promoted as a durable failure by the turn's memory.
+				success: true,
+				output: `${describeJobWaitTimeout(input.id, outcome)}\n\n${observed}\n\n[next_offset ${outcome.nextOffset}]`,
 				data: {
 					jobId: input.id,
 					timedOut: outcome.cause,
 					nextOffset: outcome.nextOffset,
 					droppedBytes: outcome.droppedBytes,
+					omittedOutputBytes: outcome.omittedOutputBytes,
 				},
 			}
 		}
 
-		// The dropped count is stated, never absorbed — same rule `job read`
-		// follows, for the same reason: a job whose middle vanished quietly
-		// reads as a complete result that happens to be short.
-		const notice =
-			outcome.droppedBytes > 0
-				? `[${outcome.droppedBytes} bytes were dropped before this point — the job produced output faster than the retention cap holds]\n`
-				: ''
 		const status =
 			outcome.exitCode === undefined
 				? outcome.status
@@ -171,12 +184,13 @@ export const WaitForJobTool = defineTool({
 
 		return {
 			success: true,
-			output: `${notice}${outcome.output || '(no output)'}\n\n[job ${input.id} is ${status}; next_offset ${outcome.nextOffset}]`,
+			output: `${observed}\n\n[job ${input.id} is ${status}; next_offset ${outcome.nextOffset}]`,
 			data: {
 				jobId: input.id,
 				status: outcome.status,
 				nextOffset: outcome.nextOffset,
 				droppedBytes: outcome.droppedBytes,
+				omittedOutputBytes: outcome.omittedOutputBytes,
 				...(outcome.exitCode === undefined ? {} : { exitCode: outcome.exitCode }),
 			},
 		}

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

@@ -69,6 +69,7 @@ export async function waitForTaskWithBounds(
 	const startedAt = now()
 	let lastProgressAt = startedAt
 	let settled = false
+	let poll: ReturnType<typeof setInterval> | undefined
 
 	const detach = gateway.onTaskProgress?.((id) => {
 		if (id === taskId) lastProgressAt = now()
@@ -107,6 +108,7 @@ export async function waitForTaskWithBounds(
 					}
 				}
 			}, POLL_INTERVAL_MS)
+			poll = tick
 			// Never the reason a process stays alive. This one is safe to unref
 			// where the park recorder was not, because nothing AWAITS it alone:
 			// it races a real completion promise, so the wait is held open by
@@ -117,6 +119,7 @@ export async function waitForTaskWithBounds(
 		return await Promise.race([completion, expiry])
 	} finally {
 		settled = true
+		if (poll !== undefined) clearInterval(poll)
 		detach?.()
 	}
 }

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.`,