@namzu/sdk 42.0.2 → 44.0.0

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

@@ -10,7 +10,7 @@ import type { TaskId } from '../../types/ids/index.js'
  * The same number cannot be both "how long is too long" and "how quiet is too
  * quiet", so this keeps them apart:
  *
- *  - the **run bound** counts elapsed time and is never refreshed. It exists
+ *  - the **wall-clock bound** counts elapsed time and is never refreshed. It exists
  *    for a worker that stays busy forever.
  *  - the **idle bound** counts time since the worker last did anything, and
  *    resets whenever it does. It exists for a worker that stopped.
@@ -32,7 +32,7 @@ export type WaitOutcome =
 	| {
 			readonly kind: 'timeout'
 			/** Which clock ran out. */
-			readonly cause: 'idle' | 'run'
+			readonly cause: 'idle' | 'wall'
 			readonly elapsedMs: number
 			/** False when the gateway cannot report progress, so only the wall clock applied. */
 			readonly idleBoundArmed: boolean
@@ -40,11 +40,11 @@ export type WaitOutcome =
 
 export interface WaitBounds {
 	/** Elapsed-time ceiling, never refreshed. */
-	readonly runMs: number
+	readonly wallMs: number
 	/**
 	 * Time-without-progress ceiling, refreshed on every progress signal.
 	 *
-	 * Omit to bound by the run clock alone.
+	 * Omit to bound by the turn clock alone.
 	 */
 	readonly idleMs?: number
 }
@@ -94,9 +94,9 @@ export async function waitForTaskWithBounds(
 			const tick = setInterval(() => {
 				if (settled) return
 				const elapsed = now() - startedAt
-				if (elapsed >= bounds.runMs) {
+				if (elapsed >= bounds.wallMs) {
 					clearInterval(tick)
-					resolve({ kind: 'timeout', cause: 'run', elapsedMs: elapsed, idleBoundArmed })
+					resolve({ kind: 'timeout', cause: 'wall', elapsedMs: elapsed, idleBoundArmed })
 					return
 				}
 				if (idleBoundArmed && bounds.idleMs !== undefined) {

package/src/tools/defineTool.ts

@@ -49,7 +49,7 @@ export interface DefineToolOptions<S extends z.ZodType> {
 	maxRetries?: number
 	/** Return shape shown to the model; see {@link ToolDefinition.outputSchema}. */
 	outputSchema?: Record<string, unknown>
-	/** Settle the run with this tool's output; see {@link ToolDefinition.terminal}. */
+	/** Settle the turn with this tool's output; see {@link ToolDefinition.terminal}. */
 	terminal?: boolean
 	/**
 	 * The argument holding a shell command line; see
@@ -61,6 +61,10 @@ export interface DefineToolOptions<S extends z.ZodType> {
 	 * hand-written definitions can use.
 	 */
 	commandArgument?: string
+	/** The argument holding a filesystem path; see {@link ToolDefinition.pathArgument}. */
+	pathArgument?: string
+	/** The argument asking to leave the sandbox; see {@link ToolDefinition.sandboxEscapeArgument}. */
+	sandboxEscapeArgument?: string
 	execute(input: z.infer<S>, context: ToolContext): Promise<ToolResult>
 }
 
@@ -80,6 +84,10 @@ export function defineTool<S extends z.ZodType>(
 		...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
 		...(options.maxRetries !== undefined ? { maxRetries: options.maxRetries } : {}),
 		...(options.commandArgument !== undefined ? { commandArgument: options.commandArgument } : {}),
+		...(options.pathArgument !== undefined ? { pathArgument: options.pathArgument } : {}),
+		...(options.sandboxEscapeArgument !== undefined
+			? { sandboxEscapeArgument: options.sandboxEscapeArgument }
+			: {}),
 		...(options.presentCall ? { presentCall: options.presentCall } : {}),
 		...(options.presentResult ? { presentResult: options.presentResult } : {}),
 		...(options.outputSchema !== undefined ? { outputSchema: options.outputSchema } : {}),

package/src/tools/env-scrub.ts

@@ -35,7 +35,7 @@
  * a build script dumping config on failure — therefore returned the operator's
  * API keys as tool output. That output is not ephemeral: it is appended to the
  * durable transcript, persisted by the session store, and re-sent to the model
- * provider as history on every later turn of the run. One incidental `env` in
+ * provider as history on every later turn of the turn. One incidental `env` in
  * a build script converted a local secret into a permanently recorded one that
  * had also been transmitted to a third party.
  *

package/src/tools/goal/index.ts

@@ -2,20 +2,24 @@ import { z } from 'zod'
 
 import { GoalNotFoundError, type SessionGoalStore, StaleGoalError } from '../../store/goal/index.js'
 import type { GoalRoundAuthority, SessionGoal } from '../../types/goal/index.js'
-import type { RunId } from '../../types/ids/index.js'
+import type { TurnId } from '../../types/ids/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 
 export const SESSION_GOAL_TOOL_NAMES = ['get_goal', 'update_goal'] as const
 export const MIN_GOAL_BLOCK_ROUND = 3
 
-/** Resolve authority captured for one caller-reserved run id. */
-export type ResolveGoalRoundAuthority = (runId: RunId) => GoalRoundAuthority | null | undefined
+/**
+ * Resolve the authority captured for one caller-reserved turn id. Each goal
+ * round is its own turn (`origin.kind: 'goal-round'`), so the turn id names
+ * exactly one admitted round.
+ */
+export type ResolveGoalRoundAuthority = (turnId: TurnId) => GoalRoundAuthority | null | undefined
 
-/** A goal tool was reached outside the one run whose admission authorized it. */
+/** A goal tool was reached outside the one turn whose admission authorized it. */
 export class GoalRoundAuthorityError extends Error {
-	constructor(runId: RunId) {
-		super(`Run ${runId} has no admitted goal-round authority.`)
+	constructor(turnId: TurnId) {
+		super(`Turn ${turnId} has no admitted goal-round authority.`)
 		this.name = 'GoalRoundAuthorityError'
 	}
 }
@@ -38,15 +42,15 @@ async function currentGoal(
 
 function authorityFor(
 	resolveAuthority: ResolveGoalRoundAuthority,
-	runId: RunId,
+	turnId: TurnId,
 ): GoalRoundAuthority {
-	const authority = resolveAuthority(runId)
-	if (!authority) throw new GoalRoundAuthorityError(runId)
+	const authority = resolveAuthority(turnId)
+	if (!authority) throw new GoalRoundAuthorityError(turnId)
 	return authority
 }
 
 /**
- * Run-scoped tools for an admitted SessionGoal round.
+ * Turn-scoped tools for an admitted SessionGoal round.
  *
  * Registration is not authorization. A host must also withhold these names
  * from every non-goal provider request and executor allow-list.
@@ -66,7 +70,7 @@ export function buildSessionGoalTools(
 		destructive: false,
 		concurrencySafe: true,
 		async execute(_input, context) {
-			const authority = authorityFor(resolveAuthority, context.runId)
+			const authority = authorityFor(resolveAuthority, context.turnId)
 			const goal = await currentGoal(store, authority)
 			return {
 				success: true,
@@ -101,7 +105,7 @@ export function buildSessionGoalTools(
 		destructive: false,
 		concurrencySafe: false,
 		async execute({ status, reasonCode, reason }, context) {
-			const authority = authorityFor(resolveAuthority, context.runId)
+			const authority = authorityFor(resolveAuthority, context.turnId)
 			await currentGoal(store, authority)
 			const ref = { id: authority.id, revision: authority.revision }
 			if (status === 'complete') {

package/src/tools/memory/fields.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod'
+import { MEMORY_NAME_MAX_LENGTH } from '../../store/memory/naming.js'
+
+/** The optional typed fields save_memory and update_memory both take. */
+export const memoryFieldsSchema = {
+	name: z
+		.string()
+		.max(MEMORY_NAME_MAX_LENGTH)
+		.regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
+		.optional()
+		.describe(
+			'Unique kebab-case slug, e.g. "deploys-need-a-changeset"; other memories link to it as [[name]]',
+		),
+	description: z
+		.string()
+		.max(300)
+		.regex(/^[^\r\n]*$/)
+		.optional()
+		.describe('One line saying what this memory is for, used to decide whether to read it'),
+	type: z
+		.enum(['user', 'feedback', 'project', 'reference'])
+		.optional()
+		.describe(
+			'user, feedback, project or reference; stores that require a type use project when omitted',
+		),
+}

package/src/tools/memory/read.ts

@@ -1,15 +1,26 @@
 import { z } from 'zod'
-import type { MemoryStore } from '../../types/memory/index.js'
+import {
+	MEMORY_VERIFY_NOTICE,
+	describeMemoryAge,
+	memoryLinkNames,
+} from '../../store/memory/links.js'
+import type { MemoryId } from '../../types/ids/index.js'
+import type { MemoryContent, MemoryIndexEntry, 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'
+import { allMemoryEntries, resolveMemoryReference } from './resolve.js'
 
 export function buildReadMemoryTool(store: MemoryStore): ToolDefinition {
 	return defineTool({
 		name: 'read_memory',
-		description: 'Read the full content of a specific memory by its ID.',
+		description:
+			'Read the full content of a specific memory by its ID or its name. For a text or Markdown memory the result ends with how old the memory is and resolves any [[name]] links it contains.',
 		inputSchema: z.object({
-			id: z.string().describe('Opaque memory ID returned by a memory search or save'),
+			id: z
+				.string()
+				.describe(
+					'Opaque memory ID returned by a memory search or save, or the memory name from the index',
+				),
 		}),
 		category: 'analysis',
 		permissions: [],
@@ -17,9 +28,28 @@ export function buildReadMemoryTool(store: MemoryStore): ToolDefinition {
 		destructive: false,
 		concurrencySafe: true,
 		async execute({ id }) {
-			// Validate model-authored input before using it as a store key.
-			const memoryId = asMemoryId(id)
-			const content = await store.get(memoryId)
+			// Validate model-authored input before using it as a store key. A name
+			// is resolved through the store's own listing, never used as a key.
+			const reference = await resolveMemoryReference(store, id)
+			if (!reference.found) {
+				return {
+					success: false,
+					output: `No memory is named ${id}.`,
+					error: `Memory ${id} not found`,
+				}
+			}
+			const memoryId: MemoryId = reference.id
+			let entries: readonly MemoryIndexEntry[] | undefined = reference.entries
+
+			let entry: MemoryIndexEntry | undefined
+			let content: MemoryContent | undefined
+			if (store.getRecord) {
+				const record = await store.getRecord(memoryId)
+				entry = record?.entry
+				content = record?.content
+			} else {
+				content = await store.get(memoryId)
+			}
 
 			if (!content) {
 				return {
@@ -29,13 +59,50 @@ export function buildReadMemoryTool(store: MemoryStore): ToolDefinition {
 				}
 			}
 
+			const notes: string[] = []
+			if (entry) {
+				const age = describeMemoryAge(entry.updatedAt)
+				notes.push(
+					`Last updated ${new Date(entry.updatedAt).toISOString().slice(0, 10)} (${age})${
+						entry.type ? `; type ${entry.type}` : ''
+					}${entry.status === 'archived' ? '; archived' : ''}.`,
+				)
+				if (age !== 'today') notes.push(MEMORY_VERIFY_NOTICE)
+			}
+			const links = memoryLinkNames(content.content)
+			const resolved: { name: string; id?: MemoryId; description?: string }[] = []
+			if (links.length > 0) {
+				entries ??= await allMemoryEntries(store)
+				notes.push('Linked memories:')
+				for (const name of links) {
+					const target = entries.find((candidate) => candidate.name === name)
+					resolved.push({
+						name,
+						...(target ? { id: target.id } : {}),
+						...(target ? { description: target.description ?? target.summary } : {}),
+					})
+					notes.push(
+						target
+							? `- [[${name}]] → ${target.id}${target.status === 'archived' ? ' (archived)' : ''} — ${target.description ?? target.summary}`
+							: `- [[${name}]] → no memory has this name`,
+					)
+				}
+			}
+
+			// 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'
 			return {
 				success: true,
-				output: content.content,
+				output: annotate ? `${content.content}\n\n---\n${notes.join('\n')}` : content.content,
 				data: {
 					id: content.id,
 					format: content.format,
 					metadata: content.metadata,
+					...(entry?.name !== undefined ? { name: entry.name } : {}),
+					...(entry?.type !== undefined ? { type: entry.type } : {}),
+					...(entry ? { updatedAt: entry.updatedAt } : {}),
+					...(resolved.length > 0 ? { links: resolved } : {}),
 				},
 			}
 		},

package/src/tools/memory/resolve.ts

@@ -0,0 +1,37 @@
+import { isMemoryName } from '../../store/memory/naming.js'
+import type { MemoryId } from '../../types/ids/index.js'
+import type { MemoryIndexEntry, MemoryStore } from '../../types/memory/index.js'
+import { asMemoryId, isEntityId } from '../../utils/id.js'
+
+/** Every record, archived included, for resolving names. One store read. */
+export async function allMemoryEntries(store: MemoryStore): Promise<readonly MemoryIndexEntry[]> {
+	return (await store.list({})).entries
+}
+
+export type MemoryReference =
+	| {
+			readonly found: true
+			readonly id: MemoryId
+			/** The listing read to resolve a name, reused by a caller that needs it. */
+			readonly entries?: readonly MemoryIndexEntry[]
+	  }
+	| { readonly found: false; readonly name: string }
+
+/**
+ * What a model-authored `id` refers to: a UUID is taken as an id, a memory
+ * name — what the prompt's index shows — is looked up through the store's own
+ * listing, never used as a key. Anything else goes through `asMemoryId`, which
+ * refuses it.
+ */
+export async function resolveMemoryReference(
+	store: MemoryStore,
+	reference: string,
+): Promise<MemoryReference> {
+	if (isEntityId(reference, 'memory')) return { found: true, id: asMemoryId(reference) }
+	if (isMemoryName(reference)) {
+		const entries = await allMemoryEntries(store)
+		const named = entries.find((entry) => entry.name === reference)
+		return named ? { found: true, id: named.id, entries } : { found: false, name: reference }
+	}
+	return { found: true, id: asMemoryId(reference) }
+}

package/src/tools/memory/save.ts

@@ -1,41 +1,77 @@
 import { z } from 'zod'
+import { MemoryContentRejectedError, MemoryNameConflictError } from '../../store/memory/naming.js'
+import { AGENT_MEMORY_SOURCE } from '../../store/memory/origin.js'
 import type { MemoryStore } from '../../types/memory/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
+import { memoryFieldsSchema } from './fields.js'
 
 export function buildSaveMemoryTool(store: MemoryStore): ToolDefinition {
 	return defineTool({
 		name: 'save_memory',
-		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.',
+		description: [
+			'Save a new memory for future sessions: something true now that a later session could not work out from the code, the git history or the files themselves. Do not save what those already say.',
+			'Choose a type: user (who the user is and how they like to work), feedback (a rule the user gave about how to work), project (a fact or decision about the work), reference (where to look for something).',
+			'For feedback and project memories, write the rule or fact first, then a line starting "Why:" and a line starting "How to apply:".',
+			'Link a related memory by writing [[its-name]] in the content.',
+			'If a memory on this already exists, use update_memory instead: a name another memory holds is refused.',
+		].join(' '),
 		inputSchema: z.object({
 			title: z.string().min(1).describe('Short descriptive title'),
 			summary: z.string().min(1).describe('Brief summary (1-2 sentences)'),
 			content: z.string().min(1).describe('Full content to store'),
 			tags: z.array(z.string()).optional().describe('Tags for categorization'),
+			...memoryFieldsSchema,
 		}),
 		category: 'custom',
 		permissions: [],
 		readOnly: false,
 		destructive: false,
 		concurrencySafe: true,
-		async execute({ title, summary, content, tags }, context) {
-			const { entry } = await store.create({
-				title,
-				summary,
-				content,
-				tags,
-				metadata: { source: 'agent-memory', runId: context.runId },
-			})
+		async execute({ title, summary, content, tags, name, description, type }, context) {
+			try {
+				const { entry } = await store.create({
+					title,
+					summary,
+					content,
+					tags,
+					...(name !== undefined ? { name } : {}),
+					...(description !== undefined ? { description } : {}),
+					...(type !== undefined ? { type } : {}),
+					metadata: {
+						source: AGENT_MEMORY_SOURCE,
+						sessionId: context.sessionId,
+						turnId: context.turnId,
+					},
+				})
 
-			return {
-				success: true,
-				output: `Memory saved: ${entry.id} — "${title}"`,
-				data: {
-					id: entry.id,
-					title: entry.title,
-					tags: entry.tags,
-				},
+				return {
+					success: true,
+					output: `Memory saved: ${entry.id} — "${title}"${entry.name ? ` as ${entry.name}` : ''}`,
+					data: {
+						id: entry.id,
+						title: entry.title,
+						tags: entry.tags,
+						...(entry.name !== undefined ? { name: entry.name } : {}),
+						...(entry.type !== undefined ? { type: entry.type } : {}),
+					},
+				}
+			} catch (error) {
+				if (error instanceof MemoryContentRejectedError) {
+					return {
+						success: false,
+						output: error.message,
+						error: 'Memory content rejected',
+						data: { reason: error.reason },
+					}
+				}
+				if (!(error instanceof MemoryNameConflictError)) throw error
+				return {
+					success: false,
+					output: `A memory named "${error.memoryName}" already exists (${error.existingId}). Read it with read_memory and correct it with update_memory instead of saving a duplicate.`,
+					error: 'Memory name already exists',
+					data: { existingId: error.existingId, name: error.memoryName },
+				}
 			}
 		},
 	})

package/src/tools/memory/search.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { describeMemoryAge } from '../../store/memory/links.js'
 import type {
 	MemoryIndex,
 	MemorySearchParams,
@@ -14,7 +15,7 @@ function defineSearchMemoryTool(search: SearchMemory): ToolDefinition {
 	return defineTool({
 		name: 'search_memory',
 		description:
-			'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.',
+			'Search active stored memories by relevant words or tags. The built-in store ranks matches in names, titles, descriptions, summaries and full content. Returns the title, name, type, age and description of each match; use read_memory for evidence. Set status to archived to inspect obsolete records.',
 		inputSchema: z.object({
 			query: z.string().optional().describe('Relevant words or identifiers to search'),
 			tags: z.array(z.string()).optional().describe('Filter by tags (all must match)'),
@@ -43,10 +44,13 @@ function defineSearchMemoryTool(search: SearchMemory): ToolDefinition {
 				}
 			}
 
-			const lines = result.entries.map(
-				(e, i) =>
-					`${i + 1}. [${e.id}] ${e.title} — ${e.summary}${e.tags.length > 0 ? ` [${e.tags.join(', ')}]` : ''}`,
-			)
+			const now = Date.now()
+			const lines = result.entries.map((e, i) => {
+				const kind = [e.name, e.type, describeMemoryAge(e.updatedAt, now)]
+					.filter(Boolean)
+					.join(', ')
+				return `${i + 1}. [${e.id}] ${e.title} (${kind}) — ${e.description ?? e.summary}${e.tags.length > 0 ? ` [${e.tags.join(', ')}]` : ''}`
+			})
 
 			const output =
 				result.totalCount > result.entries.length

package/src/tools/memory/update.ts

@@ -1,21 +1,26 @@
 import { z } from 'zod'
+import { MemoryContentRejectedError, MemoryNameConflictError } from '../../store/memory/naming.js'
 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'
+import { memoryFieldsSchema } from './fields.js'
+import { resolveMemoryReference } from './resolve.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.',
+			'Correct an existing memory in place, or archive an obsolete claim so it is no longer recalled. Prefer this to saving a second memory about the same thing. Identify it by the ID from search_memory or by its name from the memory index; current evidence should determine corrections.',
 		inputSchema: z.object({
-			id: z.string().describe('Memory ID to correct or archive'),
+			id: z
+				.string()
+				.describe('Memory ID, or the memory name from the index, 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(),
+			...memoryFieldsSchema,
 		}),
 		category: 'custom',
 		permissions: [],
@@ -30,10 +35,37 @@ export function buildUpdateMemoryTool(store: MemoryStore): ToolDefinition {
 					error: 'No memory update supplied',
 				}
 			}
-			const memoryId = asMemoryId(id)
+			const reference = await resolveMemoryReference(store, id)
+			if (!reference.found) {
+				return {
+					success: false,
+					output: `No memory is named ${id}. Find it with search_memory, or save it with save_memory if it does not exist.`,
+					error: 'Memory not found',
+				}
+			}
+			const memoryId = reference.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)
+			let entry: Awaited<ReturnType<MemoryStore['update']>>
+			try {
+				entry = await store.update(memoryId, updates)
+			} catch (error) {
+				if (error instanceof MemoryContentRejectedError) {
+					return {
+						success: false,
+						output: error.message,
+						error: 'Memory content rejected',
+						data: { reason: error.reason },
+					}
+				}
+				if (!(error instanceof MemoryNameConflictError)) throw error
+				return {
+					success: false,
+					output: `Another memory is already named "${error.memoryName}" (${error.existingId}). Choose a different name, or update that memory instead.`,
+					error: 'Memory name already exists',
+					data: { existingId: error.existingId, name: error.memoryName },
+				}
+			}
 			if (!entry)
 				return {
 					success: false,
@@ -42,8 +74,12 @@ export function buildUpdateMemoryTool(store: MemoryStore): ToolDefinition {
 				}
 			return {
 				success: true,
-				output: `Memory updated: ${id} — ${entry.title} (${entry.status}).`,
-				data: { id, status: entry.status },
+				output: `Memory updated: ${memoryId}${entry.name ? ` (${entry.name})` : ''} — ${entry.title} (${entry.status}).`,
+				data: {
+					id: memoryId,
+					status: entry.status,
+					...(entry.name ? { name: entry.name } : {}),
+				},
 			}
 		},
 	})