@namzu/sdk 27.0.0 → 28.0.0

package/src/test-support/ids.ts

@@ -0,0 +1,117 @@
+/**
+ * Unchecked id constructors, for fixtures only.
+ *
+ * A test that needs three hundred distinct ids is not testing prefix
+ * validation, and paying a `startsWith` per literal to say `ses_1` buys it
+ * nothing. These are the cheap landing zone for that: same call shape as the
+ * `as*Id` constructors in `utils/id.ts`, no check.
+ *
+ * **Deliberately NOT exported from the package barrel.** The whole value of
+ * the checked constructors is that a malformed id cannot reach a store key,
+ * and an unchecked one on the public surface is a supported way around that.
+ * `test-support/` is reachable from inside this repo and nowhere else, which
+ * is exactly the reach this needs.
+ *
+ * Two shapes rather than forty functions, because a fixture wants brevity:
+ * `fixtureId.run('a')` reads at the call site, and `unchecked<RunId>(s)`
+ * covers anything the table misses.
+ */
+
+import { unsafeId } from '../types/ids/brand.js'
+import type {
+	ActivityId,
+	AdvisoryCallId,
+	AdvisoryId,
+	AgentId,
+	AuditEventId,
+	CheckpointId,
+	ChunkId,
+	ConnectorId,
+	ConnectorInstanceId,
+	CredentialId,
+	DeliverableId,
+	DocumentId,
+	EmergencySaveId,
+	EnvironmentId,
+	ExecutionContextId,
+	HandoffId,
+	KnowledgeBaseId,
+	KnowledgeBaseRef,
+	LockId,
+	MCPClientId,
+	MCPServerId,
+	MCPSessionId,
+	MemoryId,
+	MemoryStoreRef,
+	MessageId,
+	PlanId,
+	PluginId,
+	ProjectId,
+	RunId,
+	SandboxId,
+	SessionId,
+	SubSessionId,
+	SummaryId,
+	TaskId,
+	TenantId,
+	ToolCallId,
+	TopicId,
+	UserId,
+	VaultRef,
+	WorkspaceId,
+} from '../types/ids/index.js'
+
+/** Casts without checking. The name is the warning. */
+export function unchecked<T extends string>(value: string): T {
+	return unsafeId<T>(value)
+}
+
+/**
+ * One entry per prefixed id type, keyed by the bare concept rather than the
+ * type name — `fixtureId.run('a')`, not `fixtureId.RunId('a')`.
+ */
+export const fixtureId = {
+	run: (suffix: string): RunId => unsafeId<RunId>(`run_${suffix}`),
+	message: (suffix: string): MessageId => unsafeId<MessageId>(`msg_${suffix}`),
+	session: (suffix: string): SessionId => unsafeId<SessionId>(`ses_${suffix}`),
+	toolCall: (suffix: string): ToolCallId => unsafeId<ToolCallId>(`call_${suffix}`),
+	activity: (suffix: string): ActivityId => unsafeId<ActivityId>(`act_${suffix}`),
+	task: (suffix: string): TaskId => unsafeId<TaskId>(`task_${suffix}`),
+	plan: (suffix: string): PlanId => unsafeId<PlanId>(`plan_${suffix}`),
+	knowledgeBase: (suffix: string): KnowledgeBaseId => unsafeId<KnowledgeBaseId>(`kb_${suffix}`),
+	document: (suffix: string): DocumentId => unsafeId<DocumentId>(`doc_${suffix}`),
+	chunk: (suffix: string): ChunkId => unsafeId<ChunkId>(`chk_${suffix}`),
+	connector: (suffix: string): ConnectorId => unsafeId<ConnectorId>(`conn_${suffix}`),
+	connectorInstance: (suffix: string): ConnectorInstanceId =>
+		unsafeId<ConnectorInstanceId>(`ci_${suffix}`),
+	tenant: (suffix: string): TenantId => unsafeId<TenantId>(`tnt_${suffix}`),
+	credential: (suffix: string): CredentialId => unsafeId<CredentialId>(`cred_${suffix}`),
+	executionContext: (suffix: string): ExecutionContextId =>
+		unsafeId<ExecutionContextId>(`ectx_${suffix}`),
+	mCPServer: (suffix: string): MCPServerId => unsafeId<MCPServerId>(`mcp_${suffix}`),
+	mCPClient: (suffix: string): MCPClientId => unsafeId<MCPClientId>(`mcpc_${suffix}`),
+	mCPSession: (suffix: string): MCPSessionId => unsafeId<MCPSessionId>(`mcps_${suffix}`),
+	environment: (suffix: string): EnvironmentId => unsafeId<EnvironmentId>(`env_${suffix}`),
+	checkpoint: (suffix: string): CheckpointId => unsafeId<CheckpointId>(`cp_${suffix}`),
+	lock: (suffix: string): LockId => unsafeId<LockId>(`lock_${suffix}`),
+	advisory: (suffix: string): AdvisoryId => unsafeId<AdvisoryId>(`adv_${suffix}`),
+	advisoryCall: (suffix: string): AdvisoryCallId => unsafeId<AdvisoryCallId>(`advc_${suffix}`),
+	emergencySave: (suffix: string): EmergencySaveId => unsafeId<EmergencySaveId>(`esave_${suffix}`),
+	memory: (suffix: string): MemoryId => unsafeId<MemoryId>(`mem_${suffix}`),
+	plugin: (suffix: string): PluginId => unsafeId<PluginId>(`plg_${suffix}`),
+	sandbox: (suffix: string): SandboxId => unsafeId<SandboxId>(`sbx_${suffix}`),
+	auditEvent: (suffix: string): AuditEventId => unsafeId<AuditEventId>(`aud_${suffix}`),
+	user: (suffix: string): UserId => unsafeId<UserId>(`usr_${suffix}`),
+	agent: (suffix: string): AgentId => unsafeId<AgentId>(`agt_${suffix}`),
+	memoryStoreRef: (suffix: string): MemoryStoreRef => unsafeId<MemoryStoreRef>(`mms_${suffix}`),
+	vaultRef: (suffix: string): VaultRef => unsafeId<VaultRef>(`vlt_${suffix}`),
+	knowledgeBaseRef: (suffix: string): KnowledgeBaseRef =>
+		unsafeId<KnowledgeBaseRef>(`kbs_${suffix}`),
+	project: (suffix: string): ProjectId => unsafeId<ProjectId>(`prj_${suffix}`),
+	topic: (suffix: string): TopicId => unsafeId<TopicId>(`top_${suffix}`),
+	subSession: (suffix: string): SubSessionId => unsafeId<SubSessionId>(`sub_${suffix}`),
+	handoff: (suffix: string): HandoffId => unsafeId<HandoffId>(`hof_${suffix}`),
+	workspace: (suffix: string): WorkspaceId => unsafeId<WorkspaceId>(`wsp_${suffix}`),
+	summary: (suffix: string): SummaryId => unsafeId<SummaryId>(`sum_${suffix}`),
+	deliverable: (suffix: string): DeliverableId => unsafeId<DeliverableId>(`del_${suffix}`),
+} as const

package/src/testing.ts

@@ -0,0 +1,40 @@
+/**
+ * Contracts a host or a driver package runs against its own implementation.
+ *
+ * Published at `@namzu/sdk/testing` — a separate subpath rather than the
+ * root, so importing a conformance suite is a deliberate act and the main
+ * entry stays free of anything shaped like a test.
+ *
+ * Every suite here takes its `describe`/`it`/`expect` as arguments. That is
+ * what lets this ship without the SDK gaining a test dependency, and it
+ * buys the property that separates a contract from decoration: a caller
+ * can pass RECORDING functions and run the whole suite as ordinary code,
+ * which is how each one is shown to fail a deliberately wrong
+ * implementation.
+ *
+ * This barrel exists because the subpath used to point straight at the
+ * checkpoint-store file. A second suite would have had to either move that
+ * file's export or claim a subpath of its own, and neither is a decision a
+ * consumer should absorb.
+ */
+
+export {
+	CHECKPOINT_STORE_CONTRACT_VERSION,
+	defineCheckpointStoreConformance,
+} from './store/run/conformance.js'
+export type {
+	CheckpointStoreCapabilities,
+	CheckpointStoreConformanceOptions,
+	CheckpointStoreHandle,
+	ConformanceAssertion,
+	ConformanceDescribe,
+	ConformanceExpect,
+	ConformanceIt,
+	MakeCheckpointStore,
+} from './store/run/conformance.js'
+
+export {
+	PROVIDER_DRIVER_CONTRACT_VERSION,
+	defineProviderDriverConformance,
+} from './provider/conformance.js'
+export type { ProviderDriverConformanceOptions } from './provider/conformance.js'

package/src/tools/builtins/bash.ts

@@ -3,6 +3,7 @@ import { promisify } from 'node:util'
 import { z } from 'zod'
 import { DANGEROUS_PATTERNS } from '../../constants/tools/index.js'
 import { defineTool } from '../defineTool.js'
+import { scrubInheritedEnv } from '../env-scrub.js'
 
 const execAsync = promisify(exec)
 // Namzu owns its own bash timeout knob — `NAMZU_BASH_TIMEOUT_MS`.
@@ -54,7 +55,13 @@ const inputSchema = z.object({
 			z.number().positive().max(MAX_BASH_TIMEOUT_MS).default(DEFAULT_BASH_TIMEOUT_MS),
 		)
 		.describe(
-			`Command timeout in milliseconds. Default: ${DEFAULT_BASH_TIMEOUT_MS}, maximum: ${MAX_BASH_TIMEOUT_MS}. For work that legitimately runs longer than the maximum, start it in the background and poll, rather than holding the turn open.`,
+			`Command timeout in milliseconds. Default: ${DEFAULT_BASH_TIMEOUT_MS}, maximum: ${MAX_BASH_TIMEOUT_MS}. For work that legitimately runs longer than the maximum, set run_in_background and poll with the \`job\` tool, rather than holding the turn open.`,
+		),
+	run_in_background: z
+		.boolean()
+		.optional()
+		.describe(
+			'Start the command as a background job and return its id immediately, instead of waiting. The turn is not held open; read its output with the `job` tool. Use for watchers, dev servers and long builds. Do NOT write `cmd &` yourself — under the sandbox the shell that backgrounds it exits immediately and takes the job with it.',
 		),
 })
 
@@ -111,6 +118,43 @@ export const BashTool = defineTool({
 			}
 		}
 
+		if (input.run_in_background) {
+			// Refused, not degraded to `cmd &`. The fallback is not a lesser
+			// version of this: under the local sandbox's `linux-namespace` tier
+			// the wrapping `sh` is PID 1 of a fresh PID namespace, so the
+			// backgrounded grandchild dies the moment that shell exits — on the
+			// successful path, in milliseconds, looking like it worked. Telling
+			// the model its watcher is running when it is already dead is worse
+			// than telling it backgrounding is unavailable here.
+			if (!context.backgroundJobs) {
+				return {
+					success: false,
+					output: '',
+					error:
+						'run_in_background was requested, but this host provides no background job registry. Run the command in the foreground, or raise `timeout` up to the tool maximum.',
+				}
+			}
+			try {
+				const job = context.backgroundJobs.start({
+					command: input.command,
+					workingDirectory: context.workingDirectory,
+				})
+				return {
+					success: true,
+					output: `Started background job ${job.id}. Read its output with the \`job\` tool: {"action":"read","id":"${job.id}"}.`,
+					data: { jobId: job.id, background: true },
+				}
+			} catch (err) {
+				// The per-owner cap, most likely. A refusal that names the limit
+				// is actionable; a generic failure sends the model round again.
+				return {
+					success: false,
+					output: '',
+					error: err instanceof Error ? err.message : String(err),
+				}
+			}
+		}
+
 		// Sandbox-aware: route through sandbox.exec() when available.
 		//
 		// `context.workingDirectory` is the HOST-side workspace path the
@@ -206,11 +250,18 @@ export const BashTool = defineTool({
 		// branch above already reports all of it; this branch did not, so the
 		// same command told the model two different amounts depending on where
 		// it happened to run.
+		// The inherited half is scrubbed; `context.env` is not. Inheritance is
+		// implicit — nobody decided this command should see `process.env` — while
+		// a `context.env` key is one a host wrote on purpose. See
+		// `../env-scrub.ts` for why this is a denylist here and an allowlist in
+		// the sandbox, and for what it therefore does not catch.
+		const inherited = scrubInheritedEnv()
+
 		try {
 			const { stdout, stderr } = await execAsync(input.command, {
 				cwd: context.workingDirectory,
 				timeout: input.timeout,
-				env: { ...process.env, ...context.env },
+				env: { ...inherited.env, ...context.env },
 				maxBuffer: DEFAULT_BASH_MAX_BUFFER_BYTES,
 				signal: context.abortSignal,
 			})
@@ -237,7 +288,16 @@ export const BashTool = defineTool({
 			// from "exited 1".
 			const timedOut = failure.killed === true && failure.signal === 'SIGTERM'
 			const exitCode = typeof failure.code === 'number' ? failure.code : undefined
-			const output = formatShellOutput(failure.stdout, failure.stderr)
+			// Only on the failure path. A successful command did not need to know,
+			// and appending this to every result would make the common case noisy
+			// to buy nothing. A failing one is exactly where "authentication
+			// failed" has to be distinguishable from "the variable was withheld".
+			const output = [
+				formatShellOutput(failure.stdout, failure.stderr),
+				describeWithheldEnv(inherited.dropped),
+			]
+				.filter(Boolean)
+				.join('\n\n')
 
 			return {
 				success: false,
@@ -269,6 +329,25 @@ function formatShellOutput(stdout: string | undefined, stderr: string | undefine
 		.join('\n\n')
 }
 
+/** How many withheld names to print before summarising the rest. */
+const WITHHELD_ENV_PREVIEW = 10
+
+/**
+ * Name the credential-shaped variables this command did not inherit.
+ *
+ * Names only, never values. A command that failed because it wanted
+ * `FOO_TOKEN` otherwise reports an authentication error pointing nowhere; the
+ * next move — have the host pass it explicitly through `context.env` — is only
+ * available to a reader who knows it was withheld rather than unset.
+ */
+function describeWithheldEnv(dropped: readonly string[]): string {
+	if (dropped.length === 0) return ''
+	const shown = dropped.slice(0, WITHHELD_ENV_PREVIEW).join(', ')
+	const rest = dropped.length - WITHHELD_ENV_PREVIEW
+	const names = rest > 0 ? `${shown}, and ${rest} more` : shown
+	return `NOTE: ${dropped.length} credential-shaped environment variable(s) were withheld from this command and are unset rather than empty: ${names}. A host that means this command to have one passes it explicitly.`
+}
+
 function readPositiveIntEnv(key: string, fallback: number): number {
 	const value = process.env[key]?.trim()
 	if (!value) return fallback

package/src/tools/builtins/edit.ts

@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises'
 
 import { z } from 'zod'
+import type { ToolResult } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
 import { resolveWithinReal } from '../paths.js'
 import { atomicWriteFile } from './atomic-write-file.js'
@@ -184,6 +185,41 @@ export const EditTool = defineTool({
 	destructive: false,
 	concurrencySafe: false,
 
+	/**
+	 * The diff this tool is about to make, described by the tool.
+	 *
+	 * A host used to reconstruct this by matching `name === 'edit'` and
+	 * reaching into the arguments — which worked for exactly two builtin
+	 * names and left every MCP or plugin tool that patches something with a
+	 * truncated string. The knowledge of what an edit IS belongs here.
+	 *
+	 * `undefined` for an INSERT: there is no `before` text to diff against,
+	 * and inventing an empty one would render as "the whole file was
+	 * added". No opinion is the honest answer, and the host's generic label
+	 * is a better one than a wrong diff.
+	 */
+	presentCall(input: EditInput) {
+		const before = input.old_string ?? input.oldStr
+		const after = input.new_string ?? input.newStr
+		if (typeof before !== 'string' || typeof after !== 'string') return undefined
+		return {
+			kind: 'diff' as const,
+			...(input.path ? { path: input.path } : {}),
+			before,
+			after,
+		}
+	},
+
+	/**
+	 * A label, for the same reason `write` gives one: the diff was already
+	 * shown under the call, and repeating it under the result doubles the
+	 * longest rows in a transcript to say nothing new. The host used to
+	 * decide this by matching two names.
+	 */
+	presentResult(_input: EditInput, result: ToolResult) {
+		return { kind: 'generic' as const, label: result.output?.split('\n')[0] ?? '' }
+	},
+
 	async execute(input: EditInput, context) {
 		// Re-validated here rather than trusted from the registry: `execute` is
 		// reachable directly, and the closed contract is only closed if the

package/src/tools/builtins/index.ts

@@ -3,7 +3,18 @@ export { WriteFileTool } from './write-file.js'
 export { EditTool } from './edit.js'
 export { BashTool } from './bash.js'
 export { GlobTool } from './glob.js'
+export { LSP_TOOL_NAME, LspTool, getCodeNavigationTools } from './lsp.js'
 export { GrepTool } from './grep.js'
+export { JobTool } from './job.js'
+export { SKILL_TOOL_NAME, SkillTool, parseAllowedTools } from './skill.js'
+export {
+	WEB_FETCH_TOOL_NAME,
+	WEB_SEARCH_TOOL_NAME,
+	WebFetchTool,
+	WebSearchTool,
+} from './web.js'
+export { WEB_GUIDANCE_CONTRIBUTION_ID, webGuidanceContribution } from './web-guidance.js'
+export { RUN_CODE_TOOL_NAME, buildRunCodeTool } from './run-code.js'
 export { LsTool } from './ls.js'
 export { SearchToolsTool } from './search-tools.js'
 export { VerifyOutputsTool } from './verify-outputs.js'
@@ -15,6 +26,7 @@ import { BashTool } from './bash.js'
 import { EditTool } from './edit.js'
 import { GlobTool } from './glob.js'
 import { GrepTool } from './grep.js'
+import { JobTool } from './job.js'
 import { ReadFileTool } from './read-file.js'
 import { VerifyOutputsTool } from './verify-outputs.js'
 import { WriteFileTool } from './write-file.js'
@@ -31,5 +43,21 @@ import { WriteFileTool } from './write-file.js'
 // Hosts that genuinely want LS/search can still register them explicitly.
 
 export function getBuiltinTools(): ToolDefinition[] {
-	return [BashTool, EditTool, GlobTool, GrepTool, ReadFileTool, VerifyOutputsTool, WriteFileTool]
+	// `job` ships alongside `bash` rather than being opt-in, because the two
+	// are one capability. `bash run_in_background` returns an id, and an id
+	// with no tool that reads it is the exact shape of the suggestion that
+	// was removed from bash's schema for being unbacked.
+	//
+	// It costs nothing where the host provides no registry: the tool refuses
+	// and says so, which is a truthful answer rather than a missing one.
+	return [
+		BashTool,
+		EditTool,
+		GlobTool,
+		GrepTool,
+		JobTool,
+		ReadFileTool,
+		VerifyOutputsTool,
+		WriteFileTool,
+	]
 }

package/src/tools/builtins/job.ts

@@ -0,0 +1,133 @@
+import { z } from 'zod'
+
+import { defineTool } from '../defineTool.js'
+
+/**
+ * Read, list and stop the work `bash run_in_background` started.
+ *
+ * The half that was missing. The previous schema told the model to "start it
+ * in the background and poll" and there was nothing to poll with: no job id,
+ * no way to read output, no cleanup. That sentence was removed rather than
+ * honoured, because a suggestion with no mechanism behind it is worse than
+ * silence — the model follows it and gets a lie back.
+ *
+ * One tool with an `action` rather than three, because these are three views
+ * of one object and a model choosing between `read_job` / `list_jobs` /
+ * `kill_job` has three chances to pick the wrong name for the same idea.
+ */
+
+const inputSchema = z.object({
+	action: z
+		.enum(['read', 'list', 'kill'])
+		.describe(
+			'read: output since `from_offset`. list: every background job this run started, with status. kill: stop a job and everything it forked.',
+		),
+	id: z
+		.string()
+		.optional()
+		.describe(
+			'The job id, as returned by bash with run_in_background. Required for read and kill.',
+		),
+	from_offset: z
+		.number()
+		.int()
+		.nonnegative()
+		.optional()
+		.describe(
+			'Byte offset to read from; pass back the `next_offset` of your previous read to get only what is new. Omit to read from the start of what is retained.',
+		),
+})
+
+type JobInput = z.infer<typeof inputSchema>
+
+export const JobTool = defineTool({
+	name: 'job',
+	description:
+		'Reads, lists and stops background jobs started by bash with run_in_background. Poll a job with action "read", passing the previous call\'s next_offset to see only new output.',
+	inputSchema,
+	category: 'shell',
+	permissions: ['shell_execute'],
+	// `read` and `list` observe; `kill` stops work. The tool as a whole is not
+	// read-only, and claiming otherwise would let a read-only permission
+	// preset hand the model a way to terminate a running process.
+	readOnly: false,
+	destructive: (input: JobInput) => input.action === 'kill',
+	concurrencySafe: true,
+
+	async execute(input, context) {
+		if (!context.backgroundJobs) {
+			return {
+				success: false,
+				output: '',
+				error:
+					'This host provides no background job registry, so there are no background jobs to report on.',
+			}
+		}
+		const jobs = context.backgroundJobs
+
+		if (input.action === 'list') {
+			const all = jobs.list()
+			if (all.length === 0) return { success: true, output: 'No background jobs.' }
+			return {
+				success: true,
+				output: all.map((job) => `${job.id}  ${job.status.padEnd(8)}  ${job.command}`).join('\n'),
+				data: { jobs: all },
+			}
+		}
+
+		if (!input.id) {
+			return {
+				success: false,
+				output: '',
+				error: `action "${input.action}" needs an id. Use action "list" to see the jobs this run has started.`,
+			}
+		}
+
+		try {
+			if (input.action === 'kill') {
+				const killed = await jobs.kill(input.id)
+				return {
+					success: true,
+					output: `Job ${killed.id} is ${killed.status}.`,
+					data: { jobId: killed.id, status: killed.status },
+				}
+			}
+
+			const read = jobs.read(input.id, {
+				...(input.from_offset === undefined ? {} : { fromOffset: input.from_offset }),
+			})
+			// The dropped count is stated, never absorbed. A job whose middle
+			// vanished quietly reads as a complete result that happens to be
+			// short, and the model concludes the build passed.
+			const notice =
+				read.droppedBytes > 0
+					? `[${read.droppedBytes} bytes were dropped before this point — the job produced output faster than the retention cap holds]\n`
+					: ''
+			const status =
+				read.status === 'running'
+					? 'still running'
+					: `${read.status}${read.exitCode === undefined ? '' : ` with code ${read.exitCode}`}`
+
+			return {
+				success: true,
+				output: `${notice}${read.chunk || '(no new output)'}\n\n[job ${input.id} is ${status}; next_offset ${read.nextOffset}]`,
+				data: {
+					jobId: input.id,
+					status: read.status,
+					nextOffset: read.nextOffset,
+					droppedBytes: read.droppedBytes,
+					...(read.exitCode === undefined ? {} : { exitCode: read.exitCode }),
+				},
+			}
+		} catch (err) {
+			// An id from another run reads as unknown here, because the
+			// owner-bound view refuses it. That is the intended answer: a run
+			// should not be able to confirm another run's job exists.
+			return {
+				success: false,
+				output: '',
+				error: err instanceof Error ? err.message : String(err),
+			}
+		}
+	},
+})