@namzu/sdk 1.0.0 → 1.2.0

package/src/runtime/query/replay/list.ts

@@ -1,8 +1,9 @@
 import { RunDiskStore } from '../../../store/run/disk.js'
 import type { RunId } from '../../../types/ids/index.js'
+import type { CheckpointRunScope, CheckpointStore } from '../../../types/run/checkpoint-store.js'
 import type { CheckpointListEntry } from '../../../types/run/replay.js'
 import type { Logger } from '../../../utils/logger.js'
-import { CheckpointManager } from '../checkpoint.js'
+import { toCheckpointListEntry } from '../checkpoint.js'
 
 export interface ListCheckpointsInput {
 	/** Directory that contains `<runId>/` for the target run. */
@@ -10,6 +11,15 @@ export interface ListCheckpointsInput {
 	/** Run whose checkpoints should be listed. */
 	runId: RunId
 	logger?: Logger
+	/**
+	 * Optional store override (host-injected, e.g. Postgres). When set,
+	 * `scope` is required — a scope-keyed backend cannot be addressed by
+	 * `baseDir` — and `baseDir` is ignored. Absent ⇒ the disk layout under
+	 * `baseDir` is read, exactly as before.
+	 */
+	checkpointStore?: CheckpointStore
+	/** Run scope for `checkpointStore`. Required when it is set. */
+	scope?: CheckpointRunScope
 }
 
 /**
@@ -19,14 +29,38 @@ export interface ListCheckpointsInput {
  * pick a fork point — not the full `IterationCheckpoint` payload.
  *
  * Entries are returned in the order the underlying store returns them
- * (disk store sorts by `createdAt` ascending). Callers that want a
+ * (stores sort by `createdAt` ascending). Callers that want a
  * specific order should sort client-side.
  *
  * See ses_005-deterministic-replay/design.md §3.1.
  */
 export async function listCheckpoints(input: ListCheckpointsInput): Promise<CheckpointListEntry[]> {
+	const checkpoints = await listRawCheckpoints(input)
+	return checkpoints.map(toCheckpointListEntry)
+}
+
+async function listRawCheckpoints(input: ListCheckpointsInput) {
+	if (input.checkpointStore) {
+		return input.checkpointStore.listCheckpoints(requireScope(input.scope, 'listCheckpoints'))
+	}
 	const store = new RunDiskStore({ baseDir: input.baseDir, logger: input.logger })
 	await store.initRun(input.runId)
-	const mgr = new CheckpointManager(store)
-	return mgr.listEntries()
+	return store.listCheckpoints()
+}
+
+/**
+ * Guard shared by the replay entry points: an injected {@link
+ * CheckpointStore} is scope-keyed, so the caller must say which run —
+ * across the full five-layer attribution — it is asking about.
+ */
+export function requireScope(
+	scope: CheckpointRunScope | undefined,
+	caller: string,
+): CheckpointRunScope {
+	if (!scope) {
+		throw new Error(
+			`${caller}: \`checkpointStore\` was provided without \`scope\` — an injected store is keyed by tenantId/projectId/sessionId/runId, not by baseDir.`,
+		)
+	}
+	return scope
 }

package/src/runtime/query/replay/prepare.ts

@@ -4,9 +4,11 @@ import { RunDiskStore } from '../../../store/run/disk.js'
 import type { CheckpointId, IterationCheckpoint } from '../../../types/hitl/index.js'
 import type { RunId } from '../../../types/ids/index.js'
 import type { Message } from '../../../types/message/index.js'
+import type { CheckpointRunScope, CheckpointStore } from '../../../types/run/checkpoint-store.js'
 import type { Mutation, ReplayAttribution } from '../../../types/run/replay.js'
 import type { Logger } from '../../../utils/logger.js'
 import { projectEmergencyToCheckpoint } from '../checkpoint.js'
+import { requireScope } from './list.js'
 import { applyMutations } from './mutate.js'
 
 export type CheckpointSelector = CheckpointId | 'latest' | 'emergency'
@@ -27,6 +29,15 @@ export interface PrepareReplayInput {
 	 */
 	emergencyDir?: string
 	logger?: Logger
+	/**
+	 * Optional store override (host-injected, e.g. Postgres). When set,
+	 * `scope` is required and `baseDir` is ignored for checkpoint reads.
+	 * The `'emergency'` selector still reads the on-disk dump under
+	 * `emergencyDir` — emergency saves are process-local by nature.
+	 */
+	checkpointStore?: CheckpointStore
+	/** Run scope for `checkpointStore`. Required when it is set. */
+	scope?: CheckpointRunScope
 }
 
 export interface PreparedReplayState {
@@ -80,24 +91,46 @@ async function resolveCheckpoint(input: PrepareReplayInput): Promise<IterationCh
 	if (input.fromCheckpoint === 'emergency') {
 		return resolveEmergency(input)
 	}
-	const store = new RunDiskStore({ baseDir: input.baseDir, logger: input.logger })
-	await store.initRun(input.runId)
+
+	const reader = await bindCheckpointReader(input)
 
 	if (input.fromCheckpoint === 'latest') {
-		const all = await store.listCheckpoints()
+		const all = await reader.list()
 		if (all.length === 0) {
 			throw new Error(`No checkpoints found for run ${input.runId} in ${input.baseDir}`)
 		}
 		return [...all].sort((a, b) => b.iteration - a.iteration)[0] as IterationCheckpoint
 	}
 
-	const checkpoint = await store.readCheckpoint(input.fromCheckpoint)
+	const checkpoint = await reader.read(input.fromCheckpoint)
 	if (!checkpoint) {
 		throw new Error(`Checkpoint ${input.fromCheckpoint} not found for run ${input.runId}`)
 	}
 	return checkpoint
 }
 
+interface CheckpointReader {
+	list(): Promise<IterationCheckpoint[]>
+	read(id: CheckpointId): Promise<IterationCheckpoint | null>
+}
+
+async function bindCheckpointReader(input: PrepareReplayInput): Promise<CheckpointReader> {
+	if (input.checkpointStore) {
+		const store = input.checkpointStore
+		const scope = requireScope(input.scope, 'prepareReplayState')
+		return {
+			list: () => store.listCheckpoints(scope),
+			read: (id) => store.readCheckpoint(scope, id),
+		}
+	}
+	const store = new RunDiskStore({ baseDir: input.baseDir, logger: input.logger })
+	await store.initRun(input.runId)
+	return {
+		list: () => store.listCheckpoints(),
+		read: (id) => store.readCheckpoint(id),
+	}
+}
+
 async function resolveEmergency(input: PrepareReplayInput): Promise<IterationCheckpoint> {
 	if (!input.emergencyDir) {
 		throw new Error(

package/src/session/workspace/__tests__/shared-run.test.ts

@@ -148,7 +148,7 @@ describe('SharedRunWorkspace', () => {
 			runtimeRoot: '/mnt/user-data/outputs/_work',
 		})
 
-		const big = '# Task Context\n\n' + 'A'.repeat(40_000)
+		const big = `# Task Context\n\n${'A'.repeat(40_000)}`
 		const path = await workspace.writeTaskContext(big)
 		expect(path).toBe('/mnt/user-data/outputs/_work/01_task_context.md')
 		expect(workspace.refs().taskContextPath).toBe(path)

package/src/session/workspace/shared-run.ts

@@ -295,6 +295,7 @@ function ensureTrailingNewline(value: string): string {
 }
 
 async function writeJsonAtomic(path: string, value: unknown): Promise<void> {
+	await mkdir(dirnameFor(path), { recursive: true })
 	const tmpPath = `${path}.${process.pid}.${Date.now()}.tmp`
 	await writeFile(tmpPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8')
 	await rename(tmpPath, path)

package/src/skills/loader.test.ts

@@ -16,11 +16,11 @@ describe('Agent Skills loader', () => {
 		const root = await mkdtemp(join(tmpdir(), 'namzu-skills-'))
 		const dir = await writeSkill(
 			root,
-			'project-documents',
+			'delivery-briefing',
 			[
 				'---',
-				'name: project-documents',
-				'description: Draft and edit grounded project documents.',
+				'name: delivery-briefing',
+				'description: Draft and edit grounded delivery briefings.',
 				'license: MIT',
 				'compatibility: Requires filesystem tools',
 				'allowed-tools: read write edit',
@@ -36,8 +36,8 @@ describe('Agent Skills loader', () => {
 		const result = await loadSkill(dir, 'metadata')
 
 		expect(result.skill.metadata).toEqual({
-			name: 'project-documents',
-			description: 'Draft and edit grounded project documents.',
+			name: 'delivery-briefing',
+			description: 'Draft and edit grounded delivery briefings.',
 			license: 'MIT',
 			compatibility: 'Requires filesystem tools',
 			allowedTools: 'read write edit',
@@ -53,11 +53,11 @@ describe('Agent Skills loader', () => {
 		const root = await mkdtemp(join(tmpdir(), 'namzu-skills-'))
 		const dir = await writeSkill(
 			root,
-			'long-form-files',
+			'structured-file-authoring',
 			[
 				'---',
-				'name: long-form-files',
-				'description: Create long files with bounded edit chunks.',
+				'name: structured-file-authoring',
+				'description: Create structured files with bounded edit chunks.',
 				'---',
 				'Use skeleton-first writes.',
 				'',

package/src/store/index.ts

@@ -2,6 +2,7 @@ export { InMemoryStore } from './InMemoryStore.js'
 export type { Identifiable, Timestamped } from './InMemoryStore.js'
 
 export { RunDiskStore } from './run/disk.js'
+export { DiskCheckpointStore } from './run/checkpoint-disk.js'
 
 export { ActivityStore } from './activity/memory.js'
 export type { ActivityEvent, ActivityEventListener } from './activity/memory.js'

package/src/store/run/checkpoint-disk.ts

@@ -0,0 +1,67 @@
+import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
+import type { RunId } from '../../types/ids/index.js'
+import type { CheckpointRunScope, CheckpointStore } from '../../types/run/checkpoint-store.js'
+import type { RunStoreConfig } from '../../types/run/index.js'
+import { RunDiskStore } from './disk.js'
+
+/**
+ * Disk conformance layer for {@link CheckpointStore}: adapts the existing
+ * {@link RunDiskStore} checkpoint methods (which are bound to a single run
+ * directory via `initRun`) to the scope-keyed store contract.
+ *
+ * Path-addressed: `baseDir` already encodes project/session (it is the
+ * session's `runs/` directory), so only `scope.runId` / `scope.parentRunId`
+ * participate in directory resolution — `tenantId`/`projectId`/`sessionId`
+ * exist for backends that key by attribution instead of path.
+ *
+ * One `RunDiskStore` is bound (and its run directory created) per distinct
+ * `runId`, then cached, so repeated checkpoint operations against the same
+ * run don't re-run `initRun`.
+ */
+export class DiskCheckpointStore implements CheckpointStore {
+	private readonly config: RunStoreConfig
+	private readonly bound = new Map<RunId, Promise<RunDiskStore>>()
+
+	constructor(config: RunStoreConfig) {
+		this.config = config
+	}
+
+	private bind(scope: CheckpointRunScope): Promise<RunDiskStore> {
+		const cached = this.bound.get(scope.runId)
+		if (cached) return cached
+		const promise = (async () => {
+			const store = new RunDiskStore(this.config)
+			await store.initRun(scope.runId, scope.parentRunId)
+			return store
+		})()
+		this.bound.set(scope.runId, promise)
+		// A failed bind must not poison the cache — the next call retries.
+		promise.catch(() => {
+			this.bound.delete(scope.runId)
+		})
+		return promise
+	}
+
+	async writeCheckpoint(scope: CheckpointRunScope, checkpoint: IterationCheckpoint): Promise<void> {
+		const store = await this.bind(scope)
+		await store.writeCheckpoint(checkpoint)
+	}
+
+	async readCheckpoint(
+		scope: CheckpointRunScope,
+		checkpointId: CheckpointId,
+	): Promise<IterationCheckpoint | null> {
+		const store = await this.bind(scope)
+		return store.readCheckpoint(checkpointId)
+	}
+
+	async listCheckpoints(scope: CheckpointRunScope): Promise<IterationCheckpoint[]> {
+		const store = await this.bind(scope)
+		return store.listCheckpoints()
+	}
+
+	async deleteCheckpoint(scope: CheckpointRunScope, checkpointId: CheckpointId): Promise<void> {
+		const store = await this.bind(scope)
+		await store.deleteCheckpoint(checkpointId)
+	}
+}

package/src/streaming/coalesce.test.ts

@@ -117,14 +117,14 @@ describe('coalesce()', () => {
 	})
 
 	it('emits new event after window expires', async () => {
-		const events: RunEvent[] = [
+		const events: [RunEvent, RunEvent] = [
 			{ type: 'text_delta', runId: RID, iteration: 0, messageId: MID, text: 'a' },
 			{ type: 'text_delta', runId: RID, iteration: 0, messageId: MID, text: 'b' },
 		]
 		const stream: AsyncIterable<RunEvent> = (async function* () {
-			yield events[0]!
+			yield events[0]
 			await new Promise((r) => setTimeout(r, 30))
-			yield events[1]!
+			yield events[1]
 		})()
 		const result = await drain(coalesce(stream, { windowMs: 16 }))
 		expect(result).toHaveLength(2)

package/src/tools/builtins/__tests__/payload-budget.test.ts

@@ -1,4 +1,8 @@
+import { mkdtempSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
+import type { ToolContext } from '../../../types/tool/index.js'
 import { EditTool } from '../edit.js'
 import { getBuiltinTools } from '../index.js'
 import { WriteFileTool } from '../write-file.js'
@@ -26,4 +30,63 @@ describe('filesystem tool payload budgeting', () => {
 		expect(names).toContain('edit')
 		expect(names).not.toContain('append')
 	})
+
+	it('assembles long documents with bounded write plus edit insert chunks', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-long-doc-'))
+		const ctx: ToolContext = {
+			runId: 'run_test' as ToolContext['runId'],
+			workingDirectory: dir,
+			abortSignal: new AbortController().signal,
+			env: {},
+			log: () => {},
+		}
+		const opening = '# Long document regression\n\n{{BODY}}\n'
+		const chunks = Array.from({ length: 6 }, (_, sectionIndex) => {
+			const lines = Array.from({ length: 45 }, (_, lineIndex) => {
+				const section = sectionIndex + 1
+				const line = lineIndex + 1
+				return `Section ${section}.${line}: this bounded paragraph proves long-form output grows through edit insertions rather than one oversized JSON tool argument.`
+			})
+			const chunk = [`## Section ${sectionIndex + 1}`, ...lines, ''].join('\n')
+			expect(chunk.length).toBeLessThan(12_000)
+			return chunk
+		})
+
+		const writeResult = await WriteFileTool.execute(
+			{ path: 'outputs/regression-long-document.md', content: opening },
+			ctx,
+		)
+		expect(writeResult.success).toBe(true)
+
+		const firstEdit = await EditTool.execute(
+			{
+				path: 'outputs/regression-long-document.md',
+				oldStr: '{{BODY}}',
+				newStr: chunks[0],
+				replace_all: false,
+			},
+			ctx,
+		)
+		expect(firstEdit.success).toBe(true)
+
+		for (const chunk of chunks.slice(1)) {
+			const result = await EditTool.execute(
+				{
+					path: 'outputs/regression-long-document.md',
+					insertLine: 'end',
+					newStr: chunk,
+					replace_all: false,
+				},
+				ctx,
+			)
+			expect(result.success).toBe(true)
+		}
+
+		const final = readFileSync(join(dir, 'outputs/regression-long-document.md'), 'utf-8')
+		expect(final).not.toContain('{{BODY}}')
+		expect(final.split('\n').length).toBeGreaterThan(250)
+		expect(final).toContain('## Section 1')
+		expect(final).toContain('## Section 6')
+		expect(final).toContain('Section 6.45')
+	})
 })

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

@@ -28,4 +28,16 @@ describe('ReadFileTool', () => {
 		expect(result.success).toBe(true)
 		expect(result.output).toBe('2\ttwo\n3\tthree')
 	})
+
+	it('guides binary Office documents through extractor tooling', async () => {
+		const dir = mkdtempSync(join(tmpdir(), 'namzu-read-'))
+		writeFileSync(join(dir, 'transcript.docx'), Buffer.from('PK\x03\x04binary-docx'))
+
+		const result = await ReadFileTool.execute({ path: 'transcript.docx' }, makeContext(dir))
+
+		expect(result.success).toBe(false)
+		expect(result.output).toContain('DOCX document package')
+		expect(result.output).toContain('python-docx')
+		expect(result.data).toMatchObject({ binary: true })
+	})
 })

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

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises'
-import { resolve } from 'node:path'
+import { extname, resolve } from 'node:path'
 import { z } from 'zod'
 import { defineTool } from '../defineTool.js'
 
@@ -35,6 +35,18 @@ export const ReadFileTool = defineTool({
 		// Sandbox-aware: route through sandbox.readFile() when available
 		if (context.sandbox) {
 			const buffer = await context.sandbox.readFile(input.path)
+			const binaryGuidance = describeStructuredBinaryRead(input.path, buffer)
+			if (binaryGuidance) {
+				return {
+					success: false,
+					output: binaryGuidance,
+					data: {
+						path: input.path,
+						sandboxed: true,
+						binary: true,
+					},
+				}
+			}
 			const content = buffer.toString('utf-8')
 			const lines = content.split('\n')
 
@@ -58,7 +70,19 @@ export const ReadFileTool = defineTool({
 		}
 
 		const filePath = resolve(context.workingDirectory, input.path)
-		const content = await readFile(filePath, 'utf-8')
+		const buffer = await readFile(filePath)
+		const binaryGuidance = describeStructuredBinaryRead(filePath, buffer)
+		if (binaryGuidance) {
+			return {
+				success: false,
+				output: binaryGuidance,
+				data: {
+					path: filePath,
+					binary: true,
+				},
+			}
+		}
+		const content = buffer.toString('utf-8')
 		const lines = content.split('\n')
 
 		const { start, end } = resolveReadWindow(input, lines.length)
@@ -80,6 +104,30 @@ export const ReadFileTool = defineTool({
 	},
 })
 
+function describeStructuredBinaryRead(path: string, buffer: Buffer): string | null {
+	const ext = extname(path).toLowerCase()
+	if (ext === '.docx') return buildStructuredBinaryGuidance(path, 'DOCX', 'python-docx')
+	if (ext === '.pptx') return buildStructuredBinaryGuidance(path, 'PPTX', 'python-pptx')
+	if (ext === '.xlsx') return buildStructuredBinaryGuidance(path, 'XLSX', 'openpyxl')
+	if (ext === '.pdf' || startsWithPdfHeader(buffer)) {
+		return buildStructuredBinaryGuidance(path, 'PDF', 'pdftotext or PyMuPDF')
+	}
+	return null
+}
+
+function startsWithPdfHeader(buffer: Buffer): boolean {
+	return buffer.length >= 4 && buffer.subarray(0, 4).toString('utf8') === '%PDF'
+}
+
+function buildStructuredBinaryGuidance(path: string, format: string, extractor: string): string {
+	return [
+		`The file "${path}" is a ${format} document package, not UTF-8 text.`,
+		'Do not use the read/cat tools as evidence for this raw file.',
+		`Extract its text with shell/Python tooling already available in the sandbox (${extractor}), write the extracted text or summary under scratch, then read that text file.`,
+		'If extraction fails, report the exact filename and extraction error instead of claiming the attachment is unavailable.',
+	].join('\n')
+}
+
 function resolveReadWindow(
 	input: z.infer<typeof inputSchema>,
 	totalLines: number,

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

@@ -1,10 +1,22 @@
 import { z } from 'zod'
+import { toolDiscoveryHint } from '../../registry/tool/execute.js'
 import { defineTool } from '../defineTool.js'
 
 const inputSchema = z.object({
 	query: z.string().describe('Tool name or capability keyword to search for'),
 })
 
+// Activate only the best-ranked matches. Top-5 is the literature's sweet
+// spot (retrieval at k=5 matches oracle toolsets) and bounds how much
+// schema weight a single search can add to every subsequent iteration —
+// each activation also busts the prompt-cache prefix once.
+const ACTIVATION_TOP_K = 5
+
+// Near-misses are reported name+hint WITHOUT activating, so a retrieval
+// miss becomes one cheap re-query instead of a dead end (the fixed-top-k
+// hard-tail failure mode: the right tool ranked 6th-10th).
+const NEAR_MISS_LIMIT = 5
+
 export const SearchToolsTool = defineTool({
 	name: 'search_tools',
 	description:
@@ -28,27 +40,46 @@ export const SearchToolsTool = defineTool({
 
 		const allowed =
 			context.allowedTools && context.allowedTools.length > 0 ? new Set(context.allowedTools) : null
-		const matches = context.toolRegistry
+		// `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
 			.searchDeferred(input.query)
 			.filter((tool) => !allowed || allowed.has(tool.name))
 
-		if (matches.length === 0) {
+		if (ranked.length === 0) {
 			return {
 				success: true,
 				output: `No deferred tools matching "${input.query}". All matching tools are already active.`,
 			}
 		}
 
-		context.toolRegistry.activate(matches.map((t) => t.name))
+		const activated = ranked.slice(0, ACTIVATION_TOP_K)
+		const nearMisses = ranked.slice(ACTIVATION_TOP_K, ACTIVATION_TOP_K + NEAR_MISS_LIMIT)
+
+		context.toolRegistry.activate(activated.map((t) => t.name))
 
-		const descriptions = matches.map((t) => `- ${t.name}: ${t.description}`).join('\n')
+		const descriptions = activated.map((t) => `- ${t.name}: ${t.description}`).join('\n')
+		const sections = [`Activated ${activated.length} tool(s):\n${descriptions}`]
+
+		if (nearMisses.length > 0) {
+			const hints = nearMisses
+				.map((t) => {
+					const hint = toolDiscoveryHint(t.description)
+					return hint.length > 0 ? `- ${t.name}: ${hint}` : `- ${t.name}`
+				})
+				.join('\n')
+			sections.push(
+				`Also matched but NOT loaded (search again with a more specific query, e.g. the tool name, to load one of these):\n${hints}`,
+			)
+		}
 
 		return {
 			success: true,
-			output: `Activated ${matches.length} tool(s):\n${descriptions}`,
+			output: sections.join('\n\n'),
 			data: {
-				activated: matches.map((t) => t.name),
-				count: matches.length,
+				activated: activated.map((t) => t.name),
+				count: activated.length,
+				nearMisses: nearMisses.map((t) => t.name),
 			},
 		}
 	},