@namzu/sdk 36.0.0 → 37.0.0

package/src/store/memory/index.ts

@@ -6,37 +6,85 @@ import type {
 	MemorySearchResult,
 } from '../../types/memory/index.js'
 
-export class InMemoryMemoryIndex implements MemoryIndex {
-	private entries = new Map<string, MemoryIndexEntry>()
-
-	search(params: MemorySearchParams): MemorySearchResult {
-		let results = Array.from(this.entries.values())
-
-		if (params.query) {
-			const q = params.query.toLowerCase()
-			results = results.filter(
-				(e) => e.title.toLowerCase().includes(q) || e.summary.toLowerCase().includes(q),
-			)
-		}
-
-		if (params.tags && params.tags.length > 0) {
-			const requiredTags = params.tags
-			results = results.filter((e) => requiredTags.every((tag) => e.tags.includes(tag)))
-		}
+function terms(text: string): Set<string> {
+	return new Set(
+		text
+			.normalize('NFKC')
+			.toLowerCase()
+			.match(/[\p{L}\p{N}]+/gu) ?? [],
+	)
+}
 
-		if (params.status) {
-			results = results.filter((e) => e.status === params.status)
-		}
+/** Exact normalized word membership; no substring, stemming or alias inference. */
+export function matchesMemoryIdentifier(text: string, identifiers: ReadonlySet<string>): boolean {
+	for (const match of text
+		.normalize('NFKC')
+		.toLowerCase()
+		.matchAll(/[\p{L}\p{N}_]+/gu)) {
+		if (identifiers.has(match[0])) return true
+	}
+	return false
+}
 
-		results.sort((a, b) => b.updatedAt - a.updatedAt)
+/** Shared lexical ranking; a caller-owned index can omit body content. */
+export function searchMemoryEntries(
+	entries: readonly MemoryIndexEntry[],
+	params: MemorySearchParams,
+	contentOf: (id: MemoryId) => string = () => '',
+): MemorySearchResult {
+	const query = terms(params.query ?? '')
+	const identifiers = new Set(
+		params.requiredIdentifiers?.map((id) => id.normalize('NFKC').toLowerCase()),
+	)
+	if (params.query?.trim() && query.size === 0) return { entries: [], totalCount: 0 }
+	const ranked = entries
+		.filter(
+			(entry) =>
+				(!params.status || entry.status === params.status) &&
+				(!params.tags?.length || params.tags.every((tag) => entry.tags.includes(tag))),
+		)
+		.filter(
+			(entry) =>
+				!identifiers.size ||
+				[entry.id, entry.title, entry.summary, contentOf(entry.id)].some((text) =>
+					matchesMemoryIdentifier(text, identifiers),
+				),
+		)
+		.map((entry) => {
+			let coverage = 0
+			let score = 0
+			if (query.size > 0) {
+				const title = terms(entry.title)
+				const summary = terms(entry.summary)
+				const body = terms(contentOf(entry.id))
+				for (const term of query) {
+					const weight =
+						(title.has(term) ? 8 : 0) + (summary.has(term) ? 4 : 0) + (body.has(term) ? 1 : 0)
+					if (weight > 0) coverage++
+					score += weight
+				}
+			}
+			return { entry, coverage, score }
+		})
+		.filter(({ coverage }) => query.size === 0 || coverage > 0)
+		.sort(
+			(a, b) =>
+				b.coverage - a.coverage ||
+				b.score - a.score ||
+				b.entry.updatedAt - a.entry.updatedAt ||
+				(a.entry.id < b.entry.id ? -1 : a.entry.id > b.entry.id ? 1 : 0),
+		)
+	return {
+		entries: ranked.slice(0, params.limit ?? ranked.length).map(({ entry }) => entry),
+		totalCount: ranked.length,
+	}
+}
 
-		const totalCount = results.length
-		const limit = params.limit ?? totalCount
+export class InMemoryMemoryIndex implements MemoryIndex {
+	private entries = new Map<string, MemoryIndexEntry>()
 
-		return {
-			entries: results.slice(0, limit),
-			totalCount,
-		}
+	search(params: MemorySearchParams): MemorySearchResult {
+		return searchMemoryEntries([...this.entries.values()], params)
 	}
 
 	getEntry(id: MemoryId): MemoryIndexEntry | undefined {

package/src/store/memory/memory.ts

@@ -3,12 +3,15 @@ import type {
 	CreateMemoryParams,
 	MemoryContent,
 	MemoryIndexEntry,
+	MemoryRecord,
 	MemorySearchParams,
 	MemorySearchResult,
 	MemoryStore,
+	UpdateMemoryParams,
 } from '../../types/memory/index.js'
+import { assertMemoryStatus } from '../../types/memory/index.js'
 import { generateMemoryId } from '../../utils/id.js'
-import { InMemoryMemoryIndex } from './index.js'
+import { InMemoryMemoryIndex, searchMemoryEntries } from './index.js'
 
 export class InMemoryMemoryStore implements MemoryStore {
 	private content = new Map<string, MemoryContent>()
@@ -47,10 +50,14 @@ export class InMemoryMemoryStore implements MemoryStore {
 		return this.content.get(id)
 	}
 
-	async update(
-		id: MemoryId,
-		updates: Partial<CreateMemoryParams>,
-	): Promise<MemoryIndexEntry | undefined> {
+	async getRecord(id: MemoryId): Promise<MemoryRecord | undefined> {
+		const entry = this.index.getEntry(id)
+		const content = this.content.get(id)
+		return entry && content ? structuredClone({ entry, content }) : undefined
+	}
+
+	async update(id: MemoryId, updates: UpdateMemoryParams): Promise<MemoryIndexEntry | undefined> {
+		if (updates.status !== undefined) assertMemoryStatus(updates.status)
 		const existing = this.index.getEntry(id)
 		if (!existing) return undefined
 
@@ -61,6 +68,7 @@ export class InMemoryMemoryStore implements MemoryStore {
 			title: updates.title ?? existing.title,
 			summary: updates.summary ?? existing.summary,
 			tags: updates.tags ? [...updates.tags] : existing.tags,
+			status: updates.status ?? existing.status,
 			updatedAt: now,
 		}
 
@@ -94,7 +102,11 @@ export class InMemoryMemoryStore implements MemoryStore {
 	}
 
 	async list(params?: MemorySearchParams): Promise<MemorySearchResult> {
-		return this.index.search(params ?? {})
+		return searchMemoryEntries(
+			this.index.allEntries(),
+			params ?? {},
+			(id) => this.content.get(id)?.content ?? '',
+		)
 	}
 
 	getIndex(): InMemoryMemoryIndex {

package/src/store/memory/operation-lock.ts

@@ -0,0 +1,99 @@
+import { randomUUID } from 'node:crypto'
+import { type FileHandle, lstat, open, readFile, unlink } from 'node:fs/promises'
+import { setTimeout as delay } from 'node:timers/promises'
+
+import { NamzuError } from '../../types/errors/index.js'
+
+/** Wait bound, not a lease: a slow or crashed owner is never silently replaced. */
+export const DEFAULT_MEMORY_LOCK_TIMEOUT_MS = 10_000
+
+export function validateMemoryLockTimeout(timeoutMs: number): void {
+	if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+		throw new NamzuError({
+			code: 'invalid_config',
+			message: 'DiskMemoryStore lockTimeoutMs must be a positive safe integer.',
+			retryable: false,
+		})
+	}
+}
+
+function lockError(path: string, reason: string, timeoutMs: number): NamzuError {
+	return new NamzuError({
+		code: 'storage_error',
+		message: `Memory operation lock ${path}: ${reason}. Stop all processes using this memory store and inspect the lock owner before removing a stale lock; it is never broken automatically.`,
+		details: { lockPath: path, timeoutMs },
+		retryable: false,
+	})
+}
+
+/**
+ * Local-filesystem exclusion for cooperating processes. Atomic rename of the
+ * index alone cannot serialize the index/content read-modify-write transaction.
+ * An abandoned lock fails closed; guessing a lease expired would permit two
+ * live writers to overwrite each other again.
+ */
+export async function acquireMemoryOperationLock(
+	path: string,
+	timeoutMs: number,
+): Promise<() => Promise<void>> {
+	const deadline = performance.now() + timeoutMs
+	let attempted = false
+	for (;;) {
+		if (attempted && performance.now() >= deadline) {
+			throw lockError(path, `acquisition timed out after ${timeoutMs} ms`, timeoutMs)
+		}
+		attempted = true
+		let handle: FileHandle
+		try {
+			handle = await open(path, 'wx', 0o600)
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+			const existing = await lstat(path).catch((statError: NodeJS.ErrnoException) => {
+				if (statError.code === 'ENOENT') return undefined
+				throw statError
+			})
+			if (!existing) continue
+			if (!existing.isFile() || existing.isSymbolicLink()) {
+				throw lockError(path, 'the occupied lock is not a regular file', timeoutMs)
+			}
+			if (performance.now() >= deadline) {
+				throw lockError(path, `acquisition timed out after ${timeoutMs} ms`, timeoutMs)
+			}
+			await delay(Math.min(25, Math.max(1, deadline - performance.now())))
+			continue
+		}
+
+		const owner = `${JSON.stringify({ pid: process.pid, token: randomUUID(), acquiredAt: Date.now() })}\n`
+		const identity = await handle.stat().catch(async (error: unknown) => {
+			await handle.close()
+			// Exclusive create happened, but ownership could not be established.
+			// Leave the path for explicit recovery rather than unlink an unknown inode.
+			throw error
+		})
+		try {
+			await handle.writeFile(owner, 'utf8')
+			await handle.sync()
+		} catch (error) {
+			await handle.close()
+			const current = await lstat(path).catch(() => undefined)
+			if (current?.dev === identity.dev && current.ino === identity.ino) {
+				await unlink(path).catch(() => undefined)
+			}
+			throw error
+		}
+		await handle.close()
+		return async () => {
+			const current = await lstat(path)
+			if (
+				!current.isFile() ||
+				current.isSymbolicLink() ||
+				current.dev !== identity.dev ||
+				current.ino !== identity.ino ||
+				(await readFile(path, 'utf8')) !== owner
+			) {
+				throw lockError(path, 'the lock owner changed before release', timeoutMs)
+			}
+			await unlink(path)
+		}
+	}
+}

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/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/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/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 {

package/src/tools/memory/search.ts

@@ -14,19 +14,26 @@ function defineSearchMemoryTool(search: SearchMemory): ToolDefinition {
 	return defineTool({
 		name: 'search_memory',
 		description:
-			'Search stored memories by query, tags, or status. Returns titles and summaries only — use read_memory for full content.',
+			'Search active stored memories by relevant words or tags. The built-in store ranks matches in titles, summaries and full content. Returns titles and summaries; use read_memory for evidence. Set status to archived to inspect obsolete records.',
 		inputSchema: z.object({
-			query: z.string().optional().describe('Search query to match against titles and summaries'),
+			query: z.string().optional().describe('Relevant words or identifiers to search'),
 			tags: z.array(z.string()).optional().describe('Filter by tags (all must match)'),
-			limit: z.number().positive().default(10).describe('Maximum results to return'),
+			status: z.enum(['active', 'archived']).default('active'),
+			limit: z
+				.number()
+				.int()
+				.min(1)
+				.max(50)
+				.default(10)
+				.describe('Maximum results to return (1–50)'),
 		}),
 		category: 'analysis',
 		permissions: [],
 		readOnly: true,
 		destructive: false,
 		concurrencySafe: true,
-		async execute({ query, tags, limit }) {
-			const result = await search({ query, tags, limit })
+		async execute({ query, tags, status, limit }) {
+			const result = await search({ query, tags, status, limit })
 
 			if (result.entries.length === 0) {
 				return {

package/src/tools/memory/update.ts

@@ -0,0 +1,50 @@
+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 buildUpdateMemoryTool(store: MemoryStore): ToolDefinition {
+	return defineTool({
+		name: 'update_memory',
+		description:
+			'Correct an existing memory in place, or archive an obsolete claim so it is no longer recalled. Use the ID from search_memory; current evidence should determine corrections.',
+		inputSchema: z.object({
+			id: z.string().describe('Memory ID to correct or archive'),
+			title: z.string().min(1).optional(),
+			summary: z.string().min(1).optional(),
+			content: z.string().min(1).optional(),
+			tags: z.array(z.string()).optional(),
+			status: z.enum(['active', 'archived']).optional(),
+		}),
+		category: 'custom',
+		permissions: [],
+		readOnly: false,
+		destructive: false,
+		concurrencySafe: true,
+		async execute({ id, ...updates }) {
+			if (Object.values(updates).every((value) => value === undefined)) {
+				return {
+					success: false,
+					output: 'Provide a correction or status to update.',
+					error: 'No memory update supplied',
+				}
+			}
+			const memoryId = asMemoryId(id)
+			// Patch only requested fields in one store operation. A read/merge of
+			// provenance here would overwrite metadata from a concurrent writer.
+			const entry = await store.update(memoryId, updates)
+			if (!entry)
+				return {
+					success: false,
+					output: `Memory ${id} no longer exists.`,
+					error: 'Memory not found',
+				}
+			return {
+				success: true,
+				output: `Memory updated: ${id} — ${entry.title} (${entry.status}).`,
+				data: { id, status: entry.status },
+			}
+		},
+	})
+}

package/src/types/agent/scheduler.ts

@@ -29,6 +29,12 @@ export interface TaskHandle {
 export type SiblingFailurePolicy = 'continue' | 'cancel-siblings'
 
 export interface CreateTaskOptions {
+	/**
+	 * Revalidate host authority at actual admission, including after a capacity wait.
+	 * Queue retries may invoke this more than once; checks must tolerate repeated calls.
+	 */
+	readonly beforeStart?: () => Promise<void>
+
 	/**
 	 * Observe events from this one delegated run when the scheduler can expose
 	 * them.