@namzu/sdk 36.0.0 → 38.0.0

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

@@ -63,7 +63,7 @@ const pointModelInputSchema = {
 	additionalProperties: false,
 } as const
 
-const modelInputSchema: Record<string, unknown> = {
+const modelInputSchema = {
 	type: 'object',
 	properties: {
 		type: {
@@ -136,16 +136,17 @@ function requiredCapability(type: ComputerUseAction['type']): keyof ComputerUseC
 
 function buildDescription(host: ComputerUseHost): string {
 	const caps = host.capabilities
-	const available: string[] = []
-	if (caps.screenshot) available.push('screenshot')
-	if (caps.cursorPosition) available.push('cursor_position')
-	if (caps.mouse) available.push('mouse_move, mouse_click, mouse_drag, scroll')
-	if (caps.keyboard) available.push('type_text, key')
+	const available = availableActions(caps)
 	const unavailable: string[] = []
 	if (!caps.screenshot) unavailable.push('screenshot')
 	if (!caps.cursorPosition) unavailable.push('cursor_position')
 	if (!caps.mouse) unavailable.push('mouse')
 	if (!caps.keyboard) unavailable.push('keyboard')
+	if (caps.supportedActions) {
+		for (const action of actionSchema.options.map((option) => option.shape.type.value)) {
+			if (!available.includes(action)) unavailable.push(action)
+		}
+	}
 
 	const lines = [
 		`Controls the user's desktop on a ${caps.displayServer} host. Use to take screenshots and drive mouse/keyboard input for GUI tasks.`,
@@ -161,9 +162,42 @@ function buildDescription(host: ComputerUseHost): string {
 	lines.push(
 		'Coordinates are in logical pixels from the top-left of the primary display. Call getDisplayGeometry through screenshot output before clicking to confirm bounds.',
 	)
+	if (caps.mouseClickButtons && available.includes('mouse_click'))
+		lines.push(`Click buttons: ${caps.mouseClickButtons.join(', ') || 'none'}.`)
+	if (caps.mouseDragButtons && available.includes('mouse_drag'))
+		lines.push(`Drag buttons: ${caps.mouseDragButtons.join(', ') || 'none'}.`)
 	return lines.join(' ')
 }
 
+function availableActions(caps: ComputerUseCapabilities): ComputerUseAction['type'][] {
+	return actionSchema.options
+		.map((option) => option.shape.type.value)
+		.filter((action) => {
+			const required = requiredCapability(action)
+			return (
+				(required === null || caps[required] === true) &&
+				(caps.supportedActions === undefined || caps.supportedActions.includes(action)) &&
+				(action !== 'mouse_click' || caps.mouseClickButtons?.length !== 0) &&
+				(action !== 'mouse_drag' || caps.mouseDragButtons?.length !== 0)
+			)
+		})
+}
+
+function hostModelSchema(caps: ComputerUseCapabilities): Record<string, unknown> {
+	const schema = structuredClone(modelInputSchema)
+	const actions = availableActions(caps)
+	// An unavailable host remains a diagnostic tool. Avoid invalid empty enums
+	// on provider wires; every execution is still refused before host access.
+	if (actions.length > 0) schema.properties.type.enum = actions
+	const buttons = new Set<string>()
+	if (actions.includes('mouse_click'))
+		for (const button of caps.mouseClickButtons ?? ['left', 'right', 'middle']) buttons.add(button)
+	if (actions.includes('mouse_drag'))
+		for (const button of caps.mouseDragButtons ?? ['left', 'right', 'middle']) buttons.add(button)
+	if (buttons.size > 0) schema.properties.button.enum = [...buttons]
+	return schema
+}
+
 function pointLabel(point: { readonly x: number; readonly y: number }): string {
 	return `(${point.x}, ${point.y})`
 }
@@ -283,7 +317,7 @@ export function createComputerUseTool(host: ComputerUseHost): ToolDefinition<Act
 		name: COMPUTER_USE_TOOL_NAME,
 		description: buildDescription(host),
 		inputSchema: actionSchema,
-		modelInputSchema: structuredClone(modelInputSchema),
+		modelInputSchema: hostModelSchema(host.capabilities),
 		validationErrorHint:
 			'Action requirements: mouse_move needs "to"; mouse_click needs "at" and "button"; mouse_drag needs "from", "to", and "button"; scroll needs "at", "direction", and positive "amount"; type_text needs "text"; key needs "keys".',
 		category: 'custom',
@@ -310,6 +344,26 @@ export function createComputerUseTool(host: ComputerUseHost): ToolDefinition<Act
 					error: `computer_use: action "${input.type}" requires capability "${required}" which is not available on this host (displayServer=${host.capabilities.displayServer}).${host.capabilities.unavailableReason ? ` ${host.capabilities.unavailableReason} Do not retry; tell the user.` : ''}`,
 				}
 			}
+			if (!availableActions(host.capabilities).includes(input.type)) {
+				return {
+					success: false,
+					output: '',
+					error: `computer_use: action "${input.type}" is not supported on this host.`,
+				}
+			}
+			const buttons =
+				input.type === 'mouse_click'
+					? host.capabilities.mouseClickButtons
+					: input.type === 'mouse_drag'
+						? host.capabilities.mouseDragButtons
+						: undefined
+			if (buttons && 'button' in input && !buttons.includes(input.button)) {
+				return {
+					success: false,
+					output: '',
+					error: `computer_use: action "${input.type}" does not support button "${input.button}" on this host.`,
+				}
+			}
 			try {
 				const result = await host.execute(input as ComputerUseAction)
 				return resultToToolResult(result)

package/src/tools/builtins/edit.ts

@@ -362,12 +362,18 @@ export const EditTool = defineTool({
 		return withFileMutationLock(lockKey, async () => {
 			if (context.sandbox) {
 				const buffer = await context.sandbox.readFile(parsed.data.path)
-				const result = applyEdit(buffer.toString('utf-8'), normalized.operations)
+				const content = buffer.toString('utf-8')
+				const seen = context.fileReadTracker?.fingerprint?.(parsed.data.path)
+				if (seen !== undefined && seen !== fingerprintContent(content)) {
+					return { success: false as const, output: '', error: staleFileError(parsed.data.path) }
+				}
+				const result = applyEdit(content, normalized.operations)
 				if (!result.success) {
 					return { success: false as const, output: '', error: result.error }
 				}
 
 				await context.sandbox.writeFile(parsed.data.path, result.content)
+				context.fileReadTracker?.recordRead(parsed.data.path, result.content)
 				return {
 					success: true as const,
 					output: `Edited ${parsed.data.path}: ${result.replacements} replacement(s) [sandboxed]`,
@@ -378,33 +384,12 @@ export const EditTool = defineTool({
 			const hostPath = filePath as string
 			const content = await readFile(hostPath, 'utf-8')
 
-			const result = applyEdit(content, normalized.operations)
-			if (!result.success) {
-				// The anchor did not match what is on disk. Two very different
-				// situations produce that, and the difference is the whole
-				// value of the fingerprint:
-				//
-				// The file is as the agent left it, and the anchor is simply
-				// wrong — "not found, match the whitespace exactly" is the
-				// right thing to say.
-				//
-				// Or the file moved after the read — a person in an editor,
-				// another process, a second agent — and the same message is a
-				// lie that sends the agent to re-check text that was never the
-				// problem, so it retries the identical edit against the same
-				// moved file.
-				//
-				// Deliberately NOT a gate on the successful path. An anchor
-				// that still matches uniquely is well defined however much
-				// changed elsewhere in the file, and refusing there would
-				// reject safe edits every time anyone touched an unrelated
-				// line.
-				const seen = context.fileReadTracker?.fingerprint?.(hostPath)
-				if (seen !== undefined && seen !== fingerprintContent(content)) {
-					return { success: false as const, output: '', error: staleFileError(hostPath) }
-				}
-				return { success: false as const, output: '', error: result.error }
+			const seen = context.fileReadTracker?.fingerprint?.(hostPath)
+			if (seen !== undefined && seen !== fingerprintContent(content)) {
+				return { success: false as const, output: '', error: staleFileError(hostPath) }
 			}
+			const result = applyEdit(content, normalized.operations)
+			if (!result.success) return { success: false as const, output: '', error: result.error }
 
 			// Temp file, fsync, rename — a reader sees the old body or the new
 			// one, never a half-written one. A plain `writeFile` that fails

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

@@ -0,0 +1,84 @@
+import { createHash } from 'node:crypto'
+import type { ToolResult } from '../../types/tool/index.js'
+
+/** A final newline terminates a line; it does not add an empty line. */
+function lines(text: string): string[] {
+	if (text === '') return []
+	const result = text.split('\n')
+	if (result.at(-1) === '') result.pop()
+	return result
+}
+
+/** null means the backend could not establish the previous state. */
+export function fileWriteResult(
+	path: string,
+	before: string | undefined | null,
+	after: string,
+	sandboxed = false,
+): ToolResult {
+	const operation =
+		before === null
+			? 'write'
+			: before === undefined
+				? 'create'
+				: before === after
+					? 'unchanged'
+					: 'replace'
+	const oldLines = lines(before ?? '')
+	const newLines = lines(after)
+	let start = 0
+	let end = 0
+	if (typeof before === 'string') {
+		while (
+			start < oldLines.length &&
+			start < newLines.length &&
+			oldLines[start] === newLines[start]
+		)
+			start++
+		while (
+			end < oldLines.length - start &&
+			end < newLines.length - start &&
+			oldLines[oldLines.length - end - 1] === newLines[newLines.length - end - 1]
+		)
+			end++
+	}
+	const removed = oldLines.slice(start, oldLines.length - end)
+	const added = newLines.slice(start, newLines.length - end)
+	const bytes = Buffer.byteLength(after, 'utf8')
+	const label =
+		operation === 'create'
+			? 'Created'
+			: operation === 'replace'
+				? 'Updated'
+				: operation === 'unchanged'
+					? 'Unchanged'
+					: 'Wrote'
+	const newlineChanged =
+		typeof before === 'string' && before.endsWith('\n') !== after.endsWith('\n')
+	const summary = `${label} ${path}${before === null ? '' : ` (+${added.length} -${removed.length})`}${newlineChanged ? ' · final newline changed' : ''}`
+	return {
+		success: true,
+		output: `${summary} · ${bytes} bytes`,
+		data: {
+			path,
+			size: after.length,
+			...(sandboxed ? { sandboxed: true } : {}),
+			fileChange: {
+				operation,
+				...(before === null
+					? {}
+					: {
+							preview: {
+								before: removed.length ? `${removed.join('\n')}\n` : '',
+								after: added.length ? `${added.join('\n')}\n` : '',
+							},
+						}),
+				bytes,
+				sha256: createHash('sha256').update(after, 'utf8').digest('hex'),
+				...(before === null
+					? {}
+					: { added: added.length, removed: removed.length, newlineChanged }),
+			},
+		},
+	}
+}

package/src/tools/builtins/glob.ts

@@ -68,7 +68,13 @@ export const GlobTool = defineTool({
 	timeoutMs: 15_000,
 
 	presentCall(input) {
-		return { kind: 'generic', label: `${input.pattern} in ${input.path ?? '.'}` }
+		if (typeof input.pattern !== 'string') return undefined
+		return {
+			kind: 'generic',
+			label: `Find ${input.pattern} in ${input.path ?? '.'}`,
+			presentation: 'activity',
+			activity: 'exploration',
+		}
 	},
 
 	async execute(input, context) {

package/src/tools/builtins/grep.ts

@@ -98,6 +98,16 @@ export const GrepTool = defineTool({
 	readOnly: true,
 	destructive: false,
 	concurrencySafe: true,
+
+	presentCall(input) {
+		if (typeof input.pattern !== 'string') return undefined
+		return {
+			kind: 'generic',
+			label: `Search ${input.pattern} in ${input.path ?? '.'}`,
+			presentation: 'activity',
+			activity: 'exploration',
+		}
+	},
 	timeoutMs: 15_000,
 
 	async execute(input, context) {

package/src/tools/builtins/job.ts

@@ -54,6 +54,14 @@ export const JobTool = defineTool({
 	destructive: (input: JobInput) => input.action === 'kill',
 	concurrencySafe: true,
 
+	presentCall(input) {
+		const label =
+			input.action === 'list'
+				? 'List background jobs'
+				: `${input.action === 'kill' ? 'Stop background job' : 'Read background output'} · ${input.id ?? '(missing id)'}`
+		return { kind: 'generic', presentation: 'activity', label }
+	},
+
 	async execute(input, context) {
 		if (!context.backgroundJobs) {
 			return {

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

@@ -32,6 +32,16 @@ export const ReadFileTool = defineTool({
 	destructive: false,
 	concurrencySafe: true,
 
+	presentCall(input) {
+		if (typeof input.path !== 'string') return undefined
+		return {
+			kind: 'generic',
+			label: `Read ${input.path}`,
+			presentation: 'activity',
+			activity: 'exploration',
+		}
+	},
+
 	async execute(input, context) {
 		// Sandbox-aware: route through sandbox.readFile() when available
 		if (context.sandbox) {

package/src/tools/builtins/run-code.ts

@@ -49,6 +49,12 @@ export interface RunCodeToolOptions {
 	readonly runtime?: CodeRuntime
 	readonly timeoutMs?: number
 	readonly maxOutputBytes?: number
+	/**
+	 * What a successful `call()` resolves to. Default: `text` (ToolResult.output).
+	 * `structured` returns `{ output, data? }`, preserving JSON tool data for
+	 * local filtering. Failures still reject; authority and dispatch are unchanged.
+	 */
+	readonly toolResultMode?: 'text' | 'structured'
 }
 
 const DEFAULT_TIMEOUT_MS = 30_000
@@ -59,8 +65,11 @@ export function buildRunCodeTool(options: RunCodeToolOptions = {}) {
 
 	return defineTool({
 		name: RUN_CODE_TOOL_NAME,
-		description:
-			"Runs a short JavaScript program that can call this run's own tools in a loop. Use it when the same tool would otherwise be called many times in a row — filtering, retrying, fanning out — and not for a single call.",
+		description: `Runs a short JavaScript program that can call this run's own tools in a loop. Use it when the same tool would otherwise be called many times in a row — filtering, retrying, fanning out — and not for a single call. ${
+			options.toolResultMode === 'structured'
+				? 'Each successful call() returns { output: string, data?: JSON value }. Filter data locally and return only the needed result. Failed calls reject.'
+				: 'Each successful call() returns the tool output string. Failed calls reject.'
+		}`,
 		inputSchema,
 		category: 'custom',
 		permissions: [],
@@ -108,9 +117,19 @@ export function buildRunCodeTool(options: RunCodeToolOptions = {}) {
 							signal: operation.signal,
 							runtimeToolCallId: operation.runtimeToolCallId,
 						})
-						return toolResult.success
-							? { ok: true, value: toolResult.output }
-							: { ok: false, error: toolResult.error ?? 'the tool failed' }
+						if (!toolResult.success) {
+							return { ok: false, error: toolResult.error ?? 'the tool failed' }
+						}
+						return {
+							ok: true,
+							value:
+								options.toolResultMode === 'structured'
+									? {
+											output: toolResult.output,
+											...(toolResult.data !== undefined ? { data: toolResult.data } : {}),
+										}
+									: toolResult.output,
+						}
 					} catch (err) {
 						return {
 							ok: false,

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

@@ -38,8 +38,7 @@ export const SearchToolsTool = defineTool({
 			}
 		}
 
-		const allowed =
-			context.allowedTools && context.allowedTools.length > 0 ? new Set(context.allowedTools) : null
+		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.
 		const ranked = context.toolRegistry
@@ -47,9 +46,25 @@ export const SearchToolsTool = defineTool({
 			.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}". All matching tools are already active.`,
+				output: `No deferred tools matching "${input.query}". ${activeReceipt}`,
 			}
 		}
 

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

@@ -7,6 +7,7 @@ import { resolveWithinAnyReal, toolRoots } from '../paths.js'
 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'
 
 const inputSchema = z
 	.object({
@@ -81,40 +82,35 @@ export const WriteFileTool = defineTool({
 	destructive: true,
 	concurrencySafe: false,
 
-	/**
-	 * The whole file body, described by the tool.
-	 *
-	 * A `diff` with an EMPTY `before`, which is what a write actually is:
-	 * whatever was there is gone and this is what replaces it. `edit`
-	 * declines to do that for an insert — there, an empty `before` would
-	 * claim the whole file was added and it was not. Here it is true.
-	 *
-	 * A host with nothing to contrast against renders the `after` plainly
-	 * rather than as `+` lines, which is the row a reader wants: they are
-	 * approving a file, not reviewing a patch.
-	 */
+	// Input alone cannot establish whether this replaces an existing file.
 	presentCall(input: WriteInput) {
-		const content = input.content ?? input.newStr
-		if (typeof content !== 'string') return undefined
-		return {
-			kind: 'diff' as const,
-			...(input.path ? { path: input.path } : {}),
-			before: '',
-			after: content,
-		}
+		return { kind: 'generic' as const, label: input.path }
 	},
 
-	/**
-	 * A label, deliberately — which is what suppresses the detail block.
-	 *
-	 * The content was already shown under the CALL, where the user could
-	 * act on it. Repeating it under the result doubles the longest rows in
-	 * the transcript to say nothing new. A host used to decide this by
-	 * matching `name === 'write' || name === 'edit'`; it is the tool's to
-	 * say, and now it says it.
-	 */
+	/** The receipt names the observed operation; failures retain their error output. */
 	presentResult(_input: WriteInput, result: ToolResult) {
-		return { kind: 'generic' as const, label: result.output?.split('\n')[0] ?? '' }
+		const data = result.data as
+			| { fileChange?: { preview?: { before?: unknown; after?: unknown } } }
+			| undefined
+		const preview = data?.fileChange?.preview
+		if (
+			result.success &&
+			typeof preview?.before === 'string' &&
+			typeof preview.after === 'string'
+		) {
+			return {
+				kind: 'diff' as const,
+				path: _input.path,
+				label: result.output?.split('\n')[0],
+				before: preview.before,
+				after: preview.after,
+			}
+		}
+		return {
+			kind: 'generic' as const,
+			label: result.output?.split('\n')[0] ?? '',
+			...(result.success ? { presentation: 'activity' as const } : {}),
+		}
 	},
 
 	async execute(input: WriteInput, context) {
@@ -146,7 +142,7 @@ export const WriteFileTool = defineTool({
 		return withFileMutationLock(lockKey, async () => {
 			if (context.sandbox) {
 				const current = await readSandboxFileIfPresent(context, valid.path)
-				if (current !== undefined) {
+				if (current !== undefined && current !== null) {
 					const guard = enforceFreshOverwrite(context, valid.path, current.toString('utf-8'))
 					if (guard) return guard
 				}
@@ -155,11 +151,12 @@ export const WriteFileTool = defineTool({
 				// the boolean would leave an older content fingerprint in place and
 				// make the next same-run write refuse its own predecessor as drift.
 				context.fileReadTracker?.recordRead(valid.path, content)
-				return {
-					success: true as const,
-					output: `File written successfully: ${valid.path} (${content.length} chars) [sandboxed]`,
-					data: { path: valid.path, size: content.length, sandboxed: true },
-				}
+				return fileWriteResult(
+					valid.path,
+					current === null ? null : current?.toString('utf-8'),
+					content,
+					true,
+				)
 			}
 
 			const hostPath = filePath as string
@@ -176,11 +173,7 @@ export const WriteFileTool = defineTool({
 			await atomicWriteFile(hostPath, content)
 			context.fileReadTracker?.recordRead(hostPath, content)
 
-			return {
-				success: true as const,
-				output: `File written successfully: ${hostPath} (${content.length} chars)`,
-				data: { path: hostPath, size: content.length },
-			}
+			return fileWriteResult(hostPath, current, content)
 		})
 	},
 })
@@ -237,14 +230,16 @@ function isMissingFileError(error: unknown): boolean {
 async function readSandboxFileIfPresent(
 	context: ToolContext,
 	path: string,
-): Promise<Buffer | undefined> {
+): Promise<Buffer | undefined | null> {
 	if (!context.sandbox) return undefined
 	try {
 		return await context.sandbox.readFile(path)
-	} catch {
+	} catch (error) {
+		if (isMissingFileError(error)) return undefined
 		// `Sandbox` currently has no typed missing-file result. Preserve the
 		// existing create behavior for all backends; when a read succeeds, the
 		// exact body above is still a real admission-time freshness check.
-		return undefined
+		// An untyped read failure does not prove that the target was absent.
+		return null
 	}
 }

package/src/tools/defineTool.ts

@@ -20,6 +20,8 @@ export interface DefineToolOptions<S extends z.ZodType> {
 	readOnly: boolean
 	destructive: boolean | ((input: z.infer<S>) => boolean)
 	concurrencySafe: boolean
+	/** Batch ordering boundary; see {@link ToolDefinition.executionBarrier}. */
+	executionBarrier?: boolean
 	tier?: string
 	/**
 	 * How this tool's call and result should be shown; see
@@ -81,6 +83,9 @@ export function defineTool<S extends z.ZodType>(
 		...(options.presentResult ? { presentResult: options.presentResult } : {}),
 		...(options.outputSchema !== undefined ? { outputSchema: options.outputSchema } : {}),
 		...(options.terminal !== undefined ? { terminal: options.terminal } : {}),
+		...(options.executionBarrier !== undefined
+			? { executionBarrier: options.executionBarrier }
+			: {}),
 		category: options.category,
 		permissions: options.permissions,
 		isReadOnly: () => options.readOnly,

package/src/tools/file-read-tracker.ts

@@ -0,0 +1,16 @@
+import type { FileReadTracker } from '../types/tool/index.js'
+import { fingerprintContent } from './builtins/content-fingerprint.js'
+
+/** Host-owned observation ledger. Share only across turns of the same conversation and filesystem. */
+export function createFileReadTracker(): FileReadTracker {
+	const paths = new Set<string>()
+	const fingerprints = new Map<string, string>()
+	return {
+		recordRead(key, content) {
+			paths.add(key)
+			if (content !== undefined) fingerprints.set(key, fingerprintContent(content))
+		},
+		hasRead: (key) => paths.has(key),
+		fingerprint: (key) => fingerprints.get(key),
+	}
+}

package/src/tools/memory/delete.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod'
+import type { MemoryStore } from '../../types/memory/index.js'
+import type { ToolDefinition } from '../../types/tool/index.js'
+import { asMemoryId } from '../../utils/id.js'
+import { defineTool } from '../defineTool.js'
+
+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.',
+		inputSchema: z.object({
+			id: z.string().describe('Memory ID to permanently delete'),
+		}),
+		category: 'custom',
+		permissions: [],
+		readOnly: false,
+		destructive: true,
+		concurrencySafe: true,
+		async execute({ id }) {
+			const removed = await store.delete(asMemoryId(id))
+			return {
+				success: removed,
+				output: removed ? `Memory deleted: ${id}.` : `Memory ${id} not found.`,
+				...(removed ? {} : { error: 'Memory not found' }),
+			}
+		},
+	})
+}

package/src/tools/memory/index.ts

@@ -1,8 +1,10 @@
 import type { MemoryIndex, MemoryStore } from '../../types/memory/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
+import { buildDeleteMemoryTool } from './delete.js'
 import { buildReadMemoryTool } from './read.js'
 import { buildSaveMemoryTool } from './save.js'
 import { buildSearchMemoryTool, buildStoreSearchMemoryTool } from './search.js'
+import { buildUpdateMemoryTool } from './update.js'
 
 /**
  * Build memory tools over one authoritative store.
@@ -28,9 +30,13 @@ export function buildMemoryTools(store: MemoryStore, index?: MemoryIndex): ToolD
 		index ? buildSearchMemoryTool(index) : buildStoreSearchMemoryTool(store),
 		buildReadMemoryTool(store),
 		buildSaveMemoryTool(store),
+		buildUpdateMemoryTool(store),
+		buildDeleteMemoryTool(store),
 	]
 }
 
 export { buildSearchMemoryTool } from './search.js'
 export { buildReadMemoryTool } from './read.js'
 export { buildSaveMemoryTool } from './save.js'
+export { buildUpdateMemoryTool } from './update.js'
+export { buildDeleteMemoryTool } from './delete.js'

package/src/tools/memory/save.ts

@@ -6,7 +6,8 @@ import { defineTool } from '../defineTool.js'
 export function buildSaveMemoryTool(store: MemoryStore): ToolDefinition {
 	return defineTool({
 		name: 'save_memory',
-		description: 'Save a new memory with title, summary, and full content for future reference.',
+		description:
+			'Save a new historical claim for future reference. Include the actual useful fact and its evidence in the summary and content. For corrections to an existing record use update_memory instead of creating contradictory duplicates.',
 		inputSchema: z.object({
 			title: z.string().min(1).describe('Short descriptive title'),
 			summary: z.string().min(1).describe('Brief summary (1-2 sentences)'),
@@ -18,12 +19,13 @@ export function buildSaveMemoryTool(store: MemoryStore): ToolDefinition {
 		readOnly: false,
 		destructive: false,
 		concurrencySafe: true,
-		async execute({ title, summary, content, tags }) {
+		async execute({ title, summary, content, tags }, context) {
 			const { entry } = await store.create({
 				title,
 				summary,
 				content,
 				tags,
+				metadata: { source: 'agent-memory', runId: context.runId },
 			})
 
 			return {