@namzu/sdk 34.2.0 → 35.0.0

package/src/agents/budget.ts

@@ -0,0 +1,42 @@
+import { TokenBudget } from '../run/token-budget.js'
+import { openTokenBudget } from '../store/run/token-budget-disk.js'
+import type { AgentInput, BaseAgentConfig } from '../types/agent/base.js'
+import type { RunId } from '../types/ids/index.js'
+
+/** Resolve one authority before a composite agent constructs its scheduler. */
+export async function resolveAgentBudget(
+	input: AgentInput,
+	config: BaseAgentConfig,
+	runId: RunId,
+): Promise<TokenBudget> {
+	if (!Number.isSafeInteger(config.tokenBudget) || config.tokenBudget < 0) {
+		throw new Error('Agent token budget must be a nonnegative safe integer')
+	}
+	if (config.budget) {
+		config.budget.bindRun(runId)
+		if (
+			config.tokenBudget > 0 &&
+			(config.budget.limit === 0 || config.tokenBudget < config.budget.limit)
+		) {
+			config.budget.narrow(config.tokenBudget)
+		}
+		await config.budget.flush()
+		return config.budget
+	}
+	if (config.parentRunId) {
+		throw new Error('A delegated agent requires its inherited token budget authority')
+	}
+	const { tenantId, projectId, sessionId } = config
+	const budget =
+		tenantId && projectId && sessionId
+			? await openTokenBudget({
+					scope: { tenantId, projectId, sessionId, runId },
+					limit: config.tokenBudget,
+					pathBuilder: config.pathBuilder,
+					workingDirectory: input.workingDirectory,
+				})
+			: TokenBudget.create(config.tokenBudget, runId)
+	budget.bindRun(runId)
+	await budget.flush()
+	return budget
+}

package/src/agents/explore.ts

@@ -0,0 +1,29 @@
+/**
+ * The delegate that can only look.
+ *
+ * "Find where X is defined", "which files reference Y", "how does Z work" are
+ * the delegations a parent makes most, and a child built from the parent's
+ * whole working set answers them holding `write` and `bash` — so a lookup
+ * needs the same approvals as a change. A host that offers this delegate
+ * builds its roster with `filterReadOnlyTools` and its prompt from the text
+ * here; the two are exported separately because a host adds its own
+ * doctrine and environment around the prompt.
+ */
+
+export const EXPLORE_AGENT_ID = 'explore'
+
+export const EXPLORE_AGENT_DESCRIPTION =
+	'A read-only sub-agent for finding files, symbols and answers.'
+
+/**
+ * What an explore delegate is told. Names its limits in the first person so
+ * a model does not describe a change as made, and asks for file:line
+ * references because that is what the parent acts on.
+ */
+export const EXPLORE_AGENT_PROMPT = [
+	'You are a read-only sub-agent dispatched to find things out: where something is defined, which files reference it, how a piece of code works, what a directory contains.',
+	'You cannot see the parent conversation — work only from the prompt you were given.',
+	'You have reading and searching tools only. You cannot edit, write or run commands, and you must not describe a change as made.',
+	'Search broadly first, then read what matters. Report file paths with line numbers, quote the relevant lines, and say plainly what you did not find.',
+	'End with a concise answer the parent can act on; do not ask the parent questions.',
+].join('\n')

package/src/agents/file-definitions.ts

@@ -0,0 +1,237 @@
+/**
+ * Sub-agents defined in a Markdown file.
+ *
+ * Skills are defined this way one directory over (`skills/loader.ts`): YAML
+ * frontmatter for what the thing IS, a Markdown body for what it is told.
+ * An agent file is the same shape for a delegate — a name the `Agent` tool
+ * can be asked for, a description the model chooses by, and optionally a
+ * tool allowlist, a model and a read-only flag — so a repository can say
+ * "our reviewer uses these tools and this model" once, and every host that
+ * builds delegates from this kernel offers the same reviewer.
+ *
+ * ```md
+ * ---
+ * name: reviewer
+ * description: Reviews a diff for correctness and convention drift.
+ * tools: read, grep, glob          # optional allowlist, intersected with the parent's set
+ * model: claude-sonnet-4-5         # optional override
+ * readOnly: true                   # optional; keeps only read-only tools
+ * ---
+ * You review changes for this repository. Cite file:line for every finding …
+ * ```
+ *
+ * `tools` is one comma-separated line: this kernel's frontmatter reader
+ * refuses block lists and flow sequences by design, so there is no other
+ * form to accept.
+ *
+ * This module decides what a file MEANS. Where files live — which
+ * directories, in which order, which one shadows which — is the host's
+ * decision, passed in as an ordered list of roots; later roots win. A file
+ * that cannot be loaded is REPORTED with its path and reason rather than
+ * silently absent, and never takes the rest of the roster with it: an
+ * agent whose `tools` line failed to parse would otherwise run with the
+ * parent's whole set, which is the opposite of what the line was for.
+ */
+
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { parseFrontmatter } from '../utils/frontmatter.js'
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
+import { type Logger, resolveLogger } from '../utils/logger.js'
+
+/** Per-file character budget for the prompt body. */
+export const MAX_AGENT_FILE_CHARS = 32_000
+
+/** Bytes above which a file is not even read. */
+const MAX_AGENT_FILE_BYTES = 4 * 1024 * 1024
+
+/** The names a file may not claim by default: the delegate types a host ships. */
+export const DEFAULT_RESERVED_AGENT_NAMES: ReadonlySet<string> = new Set([
+	'general-purpose',
+	'explore',
+])
+
+const NAME_PATTERN = /^[a-z][a-z0-9-]{0,63}$/
+
+export interface AgentFileDefinition {
+	readonly name: string
+	readonly description: string
+	/** The system prompt: the file's body, already cut to the budget. */
+	readonly prompt: string
+	/** Tool names the agent may use; absent means the parent's working set. */
+	readonly tools?: readonly string[]
+	readonly model?: string
+	readonly readOnly: boolean
+	readonly path: string
+	/** The host's label for the root this file came from (`user`, `project`, …). */
+	readonly source: string
+}
+
+export interface SkippedAgentFile {
+	readonly path: string
+	readonly reason: string
+}
+
+export interface AgentDefinitionRoot {
+	readonly dir: string
+	readonly source: string
+}
+
+export interface DiscoveredAgentDefinitions {
+	/** In first-seen order; a later root's file replaces an earlier one's by name. */
+	readonly definitions: readonly AgentFileDefinition[]
+	readonly skipped: readonly SkippedAgentFile[]
+}
+
+export interface DiscoverAgentDefinitionsOptions {
+	/** Names refused in a file. Defaults to `DEFAULT_RESERVED_AGENT_NAMES`. */
+	readonly reserved?: ReadonlySet<string>
+	readonly log?: Logger
+}
+
+/**
+ * Every `*.md` in every root, later roots shadowing earlier ones by name.
+ * A root that is not there contributes nothing; a file that is there and
+ * wrong is reported.
+ */
+export async function discoverAgentDefinitions(
+	roots: readonly AgentDefinitionRoot[],
+	options: DiscoverAgentDefinitionsOptions = {},
+): Promise<DiscoveredAgentDefinitions> {
+	const logger = resolveLogger(options.log).child({ [SCOPE_ATTRIBUTE]: 'agents/file-definitions' })
+	const byName = new Map<string, AgentFileDefinition>()
+	const skipped: SkippedAgentFile[] = []
+	for (const root of roots) {
+		let files: string[]
+		try {
+			files = (await readdir(root.dir, { withFileTypes: true }))
+				.filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+				.map((entry) => entry.name)
+				.sort()
+		} catch {
+			logger.debug('agent definitions directory not found', { 'namzu.agents.dir': root.dir })
+			continue
+		}
+		for (const file of files) {
+			const found = await parseAgentFile(join(root.dir, file), root.source, options.reserved)
+			if ('reason' in found) skipped.push(found)
+			else byName.set(found.name, found)
+		}
+	}
+	return { definitions: [...byName.values()], skipped }
+}
+
+export async function parseAgentFile(
+	path: string,
+	source: string,
+	reserved: ReadonlySet<string> = DEFAULT_RESERVED_AGENT_NAMES,
+): Promise<AgentFileDefinition | SkippedAgentFile> {
+	let raw: string
+	try {
+		if ((await stat(path)).size > MAX_AGENT_FILE_BYTES) {
+			return { path, reason: 'is larger than 4 MiB, which no agent file is' }
+		}
+		raw = await readFile(path, 'utf8')
+	} catch (error) {
+		return {
+			path,
+			reason: `could not be read: ${error instanceof Error ? error.message : String(error)}`,
+		}
+	}
+	return parseAgentMarkdown(raw, path, source, reserved)
+}
+
+/** Pure: the file's text to a definition, or the reason it is refused. */
+export function parseAgentMarkdown(
+	raw: string,
+	path: string,
+	source: string,
+	reserved: ReadonlySet<string> = DEFAULT_RESERVED_AGENT_NAMES,
+): AgentFileDefinition | SkippedAgentFile {
+	if (!raw.trimStart().startsWith('---')) {
+		return { path, reason: 'has no frontmatter; an agent file starts with `---` and a `name:`' }
+	}
+	let parsed: ReturnType<typeof parseFrontmatter>
+	try {
+		parsed = parseFrontmatter(raw, path)
+	} catch (error) {
+		return {
+			path,
+			reason: `frontmatter did not parse: ${error instanceof Error ? error.message : String(error)}`,
+		}
+	}
+	const { values, body } = parsed
+
+	const name = scalar(values.name)
+	if (name === undefined) return { path, reason: 'has no `name:` in its frontmatter' }
+	if (!NAME_PATTERN.test(name)) {
+		return { path, reason: `\`name: ${name}\` is not a lower-case identifier (a-z, 0-9, -)` }
+	}
+	if (reserved.has(name)) {
+		return { path, reason: `\`name: ${name}\` is a built-in type and cannot be redefined` }
+	}
+	const description = scalar(values.description)
+	if (description === undefined || description.trim().length === 0) {
+		return { path, reason: 'has no `description:`; the model chooses an agent by it' }
+	}
+
+	let tools: readonly string[] | undefined
+	if (values.tools !== undefined) {
+		const list = stringList(values.tools)
+		if (list === undefined || list.length === 0) {
+			return { path, reason: '`tools:` must be a non-empty, comma-separated list of tool names' }
+		}
+		tools = list
+	}
+	const model = scalar(values.model)
+	if (values.model !== undefined && (model === undefined || model.trim().length === 0)) {
+		return { path, reason: '`model:` must be a model name' }
+	}
+	let readOnly = false
+	if (values.readOnly !== undefined) {
+		const flag = scalar(values.readOnly)
+		if (flag !== 'true' && flag !== 'false') {
+			return { path, reason: '`readOnly:` must be true or false' }
+		}
+		readOnly = flag === 'true'
+	}
+
+	const trimmed = body.trim()
+	if (trimmed.length === 0) {
+		return { path, reason: "has an empty body; the body is the agent's system prompt" }
+	}
+	const prompt =
+		trimmed.length > MAX_AGENT_FILE_CHARS
+			? `${trimmed.slice(0, MAX_AGENT_FILE_CHARS)}\n\n[namzu: this prompt was cut at ${MAX_AGENT_FILE_CHARS} characters; ${trimmed.length - MAX_AGENT_FILE_CHARS} were omitted]`
+			: trimmed
+
+	return {
+		name,
+		description: description.trim(),
+		prompt,
+		...(tools ? { tools } : {}),
+		...(model ? { model: model.trim() } : {}),
+		readOnly,
+		path,
+		source,
+	}
+}
+
+type FrontmatterValue = ReturnType<typeof parseFrontmatter>['values'][string]
+
+function scalar(value: FrontmatterValue | undefined): string | undefined {
+	return value?.kind === 'scalar' ? value.value : undefined
+}
+
+/** A comma-separated scalar; anything else is refused. */
+function stringList(value: FrontmatterValue): readonly string[] | undefined {
+	if (value.kind !== 'scalar') return undefined
+	const text = value.value.trim()
+	const inner = text.startsWith('[') && text.endsWith(']') ? text.slice(1, -1) : text
+	const items = inner
+		.split(',')
+		.map((item) => item.trim())
+		.filter((item) => item.length > 0)
+	return items.length > 0 ? items : undefined
+}

package/src/agents/index.ts

@@ -17,3 +17,18 @@ export {
 	DEFAULT_TOKEN_BUDGET,
 } from './runAgent.js'
 export type { AgentIdentity, RunAgentOptions, RunAgentResult } from './runAgent.js'
+export {
+	DEFAULT_RESERVED_AGENT_NAMES,
+	MAX_AGENT_FILE_CHARS,
+	discoverAgentDefinitions,
+	parseAgentFile,
+	parseAgentMarkdown,
+} from './file-definitions.js'
+export type {
+	AgentDefinitionRoot,
+	AgentFileDefinition,
+	DiscoverAgentDefinitionsOptions,
+	DiscoveredAgentDefinitions,
+	SkippedAgentFile,
+} from './file-definitions.js'
+export { EXPLORE_AGENT_DESCRIPTION, EXPLORE_AGENT_ID, EXPLORE_AGENT_PROMPT } from './explore.js'

package/src/bridge/a2a/mapper.ts

@@ -245,6 +245,12 @@ const MAPPING: {
 	// strategies fired is a property of how it manages its own window, and a
 	// peer modelling a task lifecycle can act on none of them.
 	compaction_tool_results_cleared: null,
+	// What the run wrote to its own memory store is this runtime's business;
+	// a peer sees the task's outcome, not its housekeeping.
+	memory_consolidated: null,
+	// A job's exit is housekeeping of this runtime's host; the peer sees the
+	// task's outcome.
+	background_job_exited: null,
 	// Compaction, succeeded or declined, is a property of how this runtime
 	// manages its own context. A peer models a task lifecycle and cannot act on
 	// either outcome.

package/src/bridge/sse/mapper.ts

@@ -133,6 +133,28 @@ const MAPPING: {
 	// dominate the stream it rides on.
 	request_envelope: null,
 
+	background_job_exited: {
+		wire: 'background_job.exited',
+		transform: (e, runId) => ({
+			run_id: runId,
+			job_id: e.jobId,
+			command: e.command,
+			status: e.status,
+			...(e.exitCode !== undefined ? { exit_code: e.exitCode } : {}),
+			...(e.signal ? { signal: e.signal } : {}),
+		}),
+	},
+	memory_consolidated: {
+		wire: 'memory.consolidated',
+		transform: (e, runId) => ({
+			run_id: runId,
+			memory_id: e.memoryId,
+			title: e.title,
+			decisions: e.decisions,
+			discoveries: e.discoveries,
+			failures: e.failures,
+		}),
+	},
 	compaction_tool_results_cleared: {
 		wire: 'compaction.tool_results_cleared',
 		transform: (e, runId) => ({

package/src/bus/lock.ts

@@ -42,16 +42,7 @@ export class FileLockManager {
 	}
 
 	private generateLockId(): LockId {
-		// Through `asLockId` rather than returning the template directly: the
-		// return TYPE alone accepts any `lock_`-shaped string today, and will
-		// stop accepting one the moment the id types go nominal (NZ-SURF-11).
-		//
-		// The UUID stays, and `utils/id.ts` deliberately does not gain a
-		// `generateLockId`. Every generator there mints 12 base-36 characters;
-		// moving this one would change the shape of a value `FileLockManager`
-		// writes to disk, which is a behaviour change wearing a refactor's
-		// clothes. What this task is about is the constructor, not the entropy.
-		return asLockId(`lock_${randomUUID()}`)
+		return asLockId(randomUUID())
 	}
 
 	private getAgentLockSet(owner: RunId): Set<string> {

package/src/compaction/consolidation.ts

@@ -0,0 +1,79 @@
+/**
+ * Consolidation: what a run learned, written down where the next run can
+ * find it.
+ *
+ * The working state is episodic memory — what happened in THIS run: the
+ * decisions taken, the discoveries made, the failures met and how. It
+ * dies with the run, and the semantic store behind `search_memory` only
+ * ever received what a model chose to `save_memory` mid-task, which is
+ * rarely the thing a later run needed. Consolidation is the bridge: at
+ * the end of a run, the entries that can outlive it become one memory
+ * entry, tagged so a later run can search for what was learned rather
+ * than what was done. What is deliberately NOT carried: the tool
+ * results, the plan, the requirements — those describe the task, not a
+ * lesson. Pure: the caller writes the entry, this only says what it is.
+ */
+
+import type { CreateMemoryParams } from '../types/memory/index.js'
+import type { WorkingState } from './types.js'
+
+export const CONSOLIDATION_TAG = 'learning'
+
+export interface ConsolidationMeta {
+	readonly runId: string
+	/** Milliseconds since the epoch, for the entry's metadata. */
+	readonly at: number
+}
+
+const MAX_TASK_IN_TITLE = 72
+
+function head(text: string, max: number): string {
+	const line = text.split('\n')[0]?.trim() ?? ''
+	return line.length <= max ? line : `${line.slice(0, max - 1)}…`
+}
+
+/**
+ * The memory entry a run's state consolidates to, or `null` when the run
+ * learned nothing worth a later run's attention — no decisions, no
+ * discoveries, no failures. A run that only read and edited leaves no
+ * entry rather than an empty one.
+ */
+export function consolidationEntry(
+	state: WorkingState,
+	meta: ConsolidationMeta,
+): CreateMemoryParams | null {
+	const decisions = state.decisions.filter((d) => d.trim().length > 0)
+	const discoveries = state.discoveries.filter((d) => d.trim().length > 0)
+	const failures = state.failures.filter((f) => f.trim().length > 0)
+	if (decisions.length + discoveries.length + failures.length === 0) return null
+
+	const task = state.task.trim()
+	const files = [...state.files.values()]
+		.filter((slot) => slot.actions.some((a) => a.type !== 'read'))
+		.map((slot) => slot.path)
+	const section = (name: string, items: readonly string[]): string[] =>
+		items.length === 0 ? [] : [`## ${name}`, '', ...items.map((item) => `- ${item}`), '']
+	const content = [
+		task ? `Task: ${task}` : 'Task: (not stated)',
+		'',
+		...section('Decisions', decisions),
+		...section('Discoveries', discoveries),
+		...section('Failures and what was done about them', failures),
+		...(files.length ? ['## Files changed', '', ...files.map((f) => `- \`${f}\``), ''] : []),
+	].join('\n')
+	const counts = [
+		decisions.length ? `${decisions.length} decision${decisions.length === 1 ? '' : 's'}` : '',
+		discoveries.length
+			? `${discoveries.length} discover${discoveries.length === 1 ? 'y' : 'ies'}`
+			: '',
+		failures.length ? `${failures.length} failure${failures.length === 1 ? '' : 's'}` : '',
+	].filter((part) => part.length > 0)
+	return {
+		title: task ? `Learned: ${head(task, MAX_TASK_IN_TITLE)}` : `Learned in run ${meta.runId}`,
+		summary: `${counts.join(', ')} from run ${meta.runId}.`,
+		content,
+		format: 'markdown',
+		tags: [CONSOLIDATION_TAG, `run:${meta.runId}`],
+		metadata: { runId: meta.runId, consolidatedAt: meta.at, kind: 'consolidation' },
+	}
+}

package/src/compaction/factory.ts

@@ -33,6 +33,9 @@ export function createConversationManager(
 ): ConversationManager {
 	switch (strategy) {
 		case 'structured':
+		case 'salience':
+			// The salience pass changes what is evicted, not how the state
+			// slots are kept; the structured manager owns those for both.
 			return new StructuredCompactionManager(config)
 		case 'sliding-window':
 			return new SlidingWindowManager({

package/src/compaction/index.ts

@@ -1,10 +1,12 @@
 export type {
-	WorkingState,
-	PlanSlot,
-	FileSlot,
+	CompactionStrategy,
 	FileAction,
+	FileSlot,
+	PinSlot,
+	PlanSlot,
 	ToolResultSlot,
-	CompactionStrategy,
+	WorkingState,
+	WorkingStatePin,
 } from './types.js'
 
 export type {
@@ -70,3 +72,31 @@ export type { ToolResultEditConfig, ToolResultEditOutcome } from './tool-result-
 export { compactNow, compactRegion } from './manual.js'
 export type { CompactionResult, CompactNowInput, CompactRegionInput } from './manual.js'
 export { COMPACTION_HEADER, buildCompactionMessage, isCompactionMessage } from './summary.js'
+
+// The salience-scored working set: every message scored, the least salient
+// evicted first. See `docs/sdk/salience-working-set.md`.
+export {
+	DEFAULT_SALIENCE_CONFIG,
+	DEFAULT_SALIENCE_WEIGHTS,
+	buildGoal,
+	isStubbedNarration,
+	messageText,
+	planWorkingSet,
+	scoreMessages,
+} from './salience/index.js'
+export type {
+	GoalSources,
+	ProtectedReason,
+	SalienceConfig,
+	SalienceWeights,
+	ScoreOptions,
+	ScoredMessage,
+	WorkingSetAction,
+	WorkingSetOptions,
+	WorkingSetPlan,
+} from './salience/index.js'
+export { DEFAULT_SOFT_TARGET, planSalienceWorkingSet } from './plan.js'
+
+// Episodic → semantic: what a run learned, as the entry a later run searches.
+export { CONSOLIDATION_TAG, consolidationEntry } from './consolidation.js'
+export type { ConsolidationMeta } from './consolidation.js'

package/src/compaction/manager.ts

@@ -1,10 +1,23 @@
 import type { CompactionConfig } from '../config/runtime.js'
-import type { FileAction, FileSlot, PlanSlot, ToolResultSlot, WorkingState } from './types.js'
+import type {
+	FileAction,
+	FileSlot,
+	PinSlot,
+	PlanSlot,
+	ToolResultSlot,
+	WorkingState,
+} from './types.js'
+
+/** Pins kept at most; the oldest is dropped past this, and the drop is counted. */
+export const MAX_PINS = 40
+/** Characters one pin may carry; a pin is a fact, not a document. */
+export const MAX_PIN_CHARS = 600
 
 function createEmptyState(): WorkingState {
 	return {
 		task: '',
 		plan: [],
+		pins: new Map<string, PinSlot>(),
 		files: new Map<string, FileSlot>(),
 		decisions: [],
 		failures: [],
@@ -34,6 +47,30 @@ export class WorkingStateManager {
 		this.state.plan = plan
 	}
 
+	/** Pin a fact under `key`, replacing what that key held; empty text unpins. */
+	pin(key: string, text: string, source: string): void {
+		const k = key.trim()
+		if (k.length === 0) return
+		const body = text.trim().slice(0, MAX_PIN_CHARS)
+		if (body.length === 0) {
+			this.state.pins?.delete(k)
+			return
+		}
+		if (!this.state.pins) this.state.pins = new Map()
+		this.state.pins.delete(k)
+		this.state.pins.set(k, { key: k, text: body, source, updatedAt: Date.now() })
+		while (this.state.pins.size > MAX_PINS) {
+			const oldest = [...this.state.pins.values()].sort((a, b) => a.updatedAt - b.updatedAt)[0]
+			if (!oldest) break
+			this.state.pins.delete(oldest.key)
+			this.state.evicted.pins = (this.state.evicted.pins ?? 0) + 1
+		}
+	}
+
+	unpin(key: string): void {
+		this.state.pins?.delete(key.trim())
+	}
+
 	trackFile(path: string, action: FileAction): void {
 		const existing = this.state.files.get(path)
 		if (existing) {
@@ -116,6 +153,7 @@ export class WorkingStateManager {
 		let count = 0
 		if (this.state.task) count++
 		count += this.state.plan.length
+		count += this.state.pins?.size ?? 0
 		count += this.state.files.size
 		count += this.state.decisions.length
 		count += this.state.failures.length