@namzu/sdk 0.1.3 → 0.1.4-rc.2

package/src/runtime/query/iteration/phases/tool-review.ts

@@ -1,12 +1,17 @@
 import { createUserMessage } from '../../../../types/message/index.js'
 import type { ChatCompletionResponse } from '../../../../types/provider/index.js'
 import type { RunEvent } from '../../../../types/run/index.js'
+import type { VerificationGate } from '../../../../verification/index.js'
 import type { IterationContext } from './context.js'
 
+interface VerificationAwareContext extends IterationContext {
+	readonly verificationGate?: VerificationGate
+}
+
 export type ToolReviewOutcome = 'executed' | 'rejected' | 'stop'
 
 export async function* runToolReview(
-	ctx: IterationContext,
+	ctx: VerificationAwareContext,
 	response: ChatCompletionResponse,
 	iterationNum: number,
 ): AsyncGenerator<RunEvent, ToolReviewOutcome> {
@@ -33,6 +38,52 @@ export async function* runToolReview(
 		}
 	})
 
+	if (ctx.verificationGate) {
+		const gate = ctx.verificationGate
+		const gateResults = toolCallSummaries.map((tc) => ({
+			toolCall: tc,
+			gateResult: gate.evaluate({
+				toolName: tc.name,
+				toolInput: tc.input,
+				toolDef: ctx.tools.get(tc.name),
+			}),
+		}))
+
+		const allAllowed = gateResults.every((gr) => gr.gateResult.decision === 'allow')
+		const allDenied = gateResults.every((gr) => gr.gateResult.decision === 'deny')
+
+		if (allAllowed) {
+			ctx.log.debug('Verification gate: all tool calls pre-approved', {
+				tools: gateResults.map((gr) => gr.toolCall.name),
+			})
+			const batch = await ctx.toolExecutor.executeBatch(response)
+			for (const msg of batch.messages) {
+				ctx.sessionMgr.pushMessage(msg)
+			}
+			return 'executed'
+		}
+
+		if (allDenied) {
+			const reasons = gateResults
+				.map((gr) => `${gr.toolCall.name}: ${gr.gateResult.reason}`)
+				.join('; ')
+			ctx.log.debug('Verification gate: all tool calls denied', {
+				tools: gateResults.map((gr) => gr.toolCall.name),
+			})
+			ctx.sessionMgr.pushMessage(
+				createUserMessage(`[SYSTEM] Tool calls blocked by verification gate: ${reasons}`),
+			)
+			return 'rejected'
+		}
+
+		ctx.log.debug('Verification gate: mixed decisions, proceeding to review', {
+			decisions: gateResults.map((gr) => ({
+				tool: gr.toolCall.name,
+				decision: gr.gateResult.decision,
+			})),
+		})
+	}
+
 	const reviewCheckpoint = await ctx.checkpointMgr.create(ctx.sessionMgr, iterationNum)
 
 	await ctx.emitEvent({

package/src/runtime/query/prompt.ts

@@ -5,6 +5,13 @@ import type { AgentContextLevel } from '../../types/agent/factory.js'
 import type { AgentPersona } from '../../types/persona/index.js'
 import type { Skill } from '../../types/skills/index.js'
 
+export interface PromptSegments {
+	/** Layers 1-6: basePrompt, persona identity/expertise/reflexes/skills/outputDiscipline. Stable within a session. */
+	readonly static: string
+	/** Layers 7-10: tools, tier guidance, env context, sessionContext. May change per run. */
+	readonly dynamic: string
+}
+
 export interface PromptBuilderConfig {
 	systemPrompt?: string
 
@@ -57,6 +64,11 @@ export class PromptBuilder {
 			if (toolSection) {
 				parts.push(toolSection)
 			}
+
+			const tierGuidance = this.config.tools.toTierGuidance()
+			if (tierGuidance) {
+				parts.push(tierGuidance)
+			}
 		}
 
 		if (
@@ -69,4 +81,56 @@ export class PromptBuilder {
 
 		return parts.join('\n\n---\n\n')
 	}
+
+	buildSegmented(
+		contextLevel: AgentContextLevel = 'full',
+		workingDirectory?: string,
+	): PromptSegments {
+		const separator = '\n\n---\n\n'
+		const staticParts: string[] = []
+		const dynamicParts: string[] = []
+
+		if (contextLevel === 'full' && this.config.basePrompt) {
+			staticParts.push(this.config.basePrompt)
+		}
+
+		if (this.config.systemPrompt) {
+			staticParts.push(this.config.systemPrompt)
+		} else if (this.config.persona) {
+			const personaWithoutSession: AgentPersona = {
+				...this.config.persona,
+				sessionContext: undefined,
+			}
+			staticParts.push(assembleSystemPrompt(personaWithoutSession, this.config.skills))
+
+			if (this.config.persona.sessionContext) {
+				dynamicParts.push(`## Session Context\n${this.config.persona.sessionContext.trim()}`)
+			}
+		}
+
+		if (contextLevel !== 'minimal') {
+			const toolSection = this.config.tools.toPromptSection(this.config.allowedTools)
+			if (toolSection) {
+				dynamicParts.push(toolSection)
+			}
+
+			const tierGuidance = this.config.tools.toTierGuidance()
+			if (tierGuidance) {
+				dynamicParts.push(tierGuidance)
+			}
+		}
+
+		if (
+			contextLevel !== 'minimal' &&
+			workingDirectory &&
+			hasFilesystemTools(this.config.tools, this.config.allowedTools)
+		) {
+			dynamicParts.push(buildEnvContext(workingDirectory))
+		}
+
+		return {
+			static: staticParts.join(separator),
+			dynamic: dynamicParts.join(separator),
+		}
+	}
 }

package/src/store/memory/disk.ts

@@ -0,0 +1,205 @@
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { MemoryId } from '../../types/ids/index.js'
+import type {
+	CreateMemoryParams,
+	MemoryContent,
+	MemoryIndexEntry,
+	MemorySearchParams,
+	MemorySearchResult,
+	MemoryStore,
+} from '../../types/memory/index.js'
+import { generateMemoryId } from '../../utils/id.js'
+import { type Logger, getRootLogger } from '../../utils/logger.js'
+import { InMemoryMemoryIndex } from './index.js'
+
+export interface DiskMemoryStoreConfig {
+	baseDir: string
+	logger?: Logger
+}
+
+export class DiskMemoryStore implements MemoryStore {
+	private baseDir: string
+	private log: Logger
+	private index = new InMemoryMemoryIndex()
+	private initialized = false
+
+	constructor(config: DiskMemoryStoreConfig) {
+		this.baseDir = join(config.baseDir, 'memory')
+		this.log = (config.logger ?? getRootLogger()).child({ component: 'DiskMemoryStore' })
+	}
+
+	private get indexPath(): string {
+		return join(this.baseDir, 'index.json')
+	}
+
+	private get contentDir(): string {
+		return join(this.baseDir, 'content')
+	}
+
+	private contentPath(id: MemoryId): string {
+		return join(this.contentDir, `${id}.json`)
+	}
+
+	private async ensureInit(): Promise<void> {
+		if (this.initialized) return
+
+		await mkdir(this.contentDir, { recursive: true })
+
+		try {
+			const raw = await readFile(this.indexPath, 'utf-8')
+			const entries = JSON.parse(raw) as MemoryIndexEntry[]
+			this.index.rebuild(entries)
+			this.log.info('Memory index loaded', { count: entries.length })
+		} catch (err) {
+			const isNotFound =
+				typeof err === 'object' && err !== null && (err as NodeJS.ErrnoException).code === 'ENOENT'
+			if (!isNotFound) {
+				this.log.warn('Failed to read memory index — starting fresh', {
+					error: String(err),
+				})
+			}
+		}
+
+		this.initialized = true
+	}
+
+	async create(
+		params: CreateMemoryParams,
+	): Promise<{ entry: MemoryIndexEntry; content: MemoryContent }> {
+		await this.ensureInit()
+
+		const id = generateMemoryId()
+		const now = Date.now()
+
+		const entry: MemoryIndexEntry = {
+			id,
+			title: params.title,
+			summary: params.summary,
+			tags: params.tags ? [...params.tags] : [],
+			status: 'active',
+			createdAt: now,
+			updatedAt: now,
+		}
+
+		const memoryContent: MemoryContent = {
+			id,
+			content: params.content,
+			format: params.format ?? 'text',
+			metadata: params.metadata ? { ...params.metadata } : undefined,
+		}
+
+		this.index.set(entry)
+		await this.persistIndex()
+		await atomicWriteJson(this.contentPath(id), memoryContent)
+
+		this.log.info('Memory created', { memoryId: id, title: params.title })
+
+		return { entry, content: memoryContent }
+	}
+
+	async get(id: MemoryId): Promise<MemoryContent | undefined> {
+		await this.ensureInit()
+
+		if (!this.index.getEntry(id)) return undefined
+
+		try {
+			const raw = await readFile(this.contentPath(id), 'utf-8')
+			return JSON.parse(raw) as MemoryContent
+		} catch {
+			this.log.warn('Failed to read memory content', { memoryId: id })
+			return undefined
+		}
+	}
+
+	async update(
+		id: MemoryId,
+		updates: Partial<CreateMemoryParams>,
+	): Promise<MemoryIndexEntry | undefined> {
+		await this.ensureInit()
+
+		const existing = this.index.getEntry(id)
+		if (!existing) return undefined
+
+		const now = Date.now()
+
+		const updated: MemoryIndexEntry = {
+			...existing,
+			title: updates.title ?? existing.title,
+			summary: updates.summary ?? existing.summary,
+			tags: updates.tags ? [...updates.tags] : existing.tags,
+			updatedAt: now,
+		}
+
+		this.index.set(updated)
+		await this.persistIndex()
+
+		if (
+			updates.content !== undefined ||
+			updates.format !== undefined ||
+			updates.metadata !== undefined
+		) {
+			try {
+				const raw = await readFile(this.contentPath(id), 'utf-8')
+				const existingContent = JSON.parse(raw) as MemoryContent
+
+				const updatedContent: MemoryContent = {
+					...existingContent,
+					content: updates.content ?? existingContent.content,
+					format: updates.format ?? existingContent.format,
+					metadata:
+						updates.metadata !== undefined ? { ...updates.metadata } : existingContent.metadata,
+				}
+
+				await atomicWriteJson(this.contentPath(id), updatedContent)
+			} catch {
+				this.log.warn('Failed to update memory content', { memoryId: id })
+			}
+		}
+
+		this.log.info('Memory updated', { memoryId: id })
+		return updated
+	}
+
+	async delete(id: MemoryId): Promise<boolean> {
+		await this.ensureInit()
+
+		const existed = this.index.remove(id)
+		if (!existed) return false
+
+		await this.persistIndex()
+		await unlink(this.contentPath(id)).catch(() => undefined)
+
+		this.log.info('Memory deleted', { memoryId: id })
+		return true
+	}
+
+	async list(params?: MemorySearchParams): Promise<MemorySearchResult> {
+		await this.ensureInit()
+		return this.index.search(params ?? {})
+	}
+
+	getIndex(): InMemoryMemoryIndex {
+		return this.index
+	}
+
+	private async persistIndex(): Promise<void> {
+		const entries = this.index.allEntries()
+		await atomicWriteJson(this.indexPath, entries)
+	}
+}
+
+async function atomicWriteFile(filePath: string, content: string): Promise<void> {
+	const tempPath = `${filePath}.tmp`
+	try {
+		await writeFile(tempPath, content, 'utf-8')
+		await rename(tempPath, filePath)
+	} catch (err) {
+		await unlink(tempPath).catch(() => undefined)
+		throw err
+	}
+}
+
+async function atomicWriteJson(filePath: string, value: unknown): Promise<void> {
+	await atomicWriteFile(filePath, JSON.stringify(value, null, 2))
+}

package/src/store/memory/index.ts

@@ -0,0 +1,68 @@
+import type { MemoryId } from '../../types/ids/index.js'
+import type {
+	MemoryIndex,
+	MemoryIndexEntry,
+	MemorySearchParams,
+	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)))
+		}
+
+		if (params.status) {
+			results = results.filter((e) => e.status === params.status)
+		}
+
+		results.sort((a, b) => b.updatedAt - a.updatedAt)
+
+		const totalCount = results.length
+		const limit = params.limit ?? totalCount
+
+		return {
+			entries: results.slice(0, limit),
+			totalCount,
+		}
+	}
+
+	getEntry(id: MemoryId): MemoryIndexEntry | undefined {
+		return this.entries.get(id)
+	}
+
+	allEntries(): readonly MemoryIndexEntry[] {
+		return Array.from(this.entries.values())
+	}
+
+	count(): number {
+		return this.entries.size
+	}
+
+	rebuild(entries: MemoryIndexEntry[]): void {
+		this.entries.clear()
+		for (const entry of entries) {
+			this.entries.set(entry.id, entry)
+		}
+	}
+
+	set(entry: MemoryIndexEntry): void {
+		this.entries.set(entry.id, entry)
+	}
+
+	remove(id: MemoryId): boolean {
+		return this.entries.delete(id)
+	}
+}

package/src/store/memory/memory.ts

@@ -0,0 +1,103 @@
+import type { MemoryId } from '../../types/ids/index.js'
+import type {
+	CreateMemoryParams,
+	MemoryContent,
+	MemoryIndexEntry,
+	MemorySearchParams,
+	MemorySearchResult,
+	MemoryStore,
+} from '../../types/memory/index.js'
+import { generateMemoryId } from '../../utils/id.js'
+import { InMemoryMemoryIndex } from './index.js'
+
+export class InMemoryMemoryStore implements MemoryStore {
+	private content = new Map<string, MemoryContent>()
+	private index = new InMemoryMemoryIndex()
+
+	async create(
+		params: CreateMemoryParams,
+	): Promise<{ entry: MemoryIndexEntry; content: MemoryContent }> {
+		const id = generateMemoryId()
+		const now = Date.now()
+
+		const entry: MemoryIndexEntry = {
+			id,
+			title: params.title,
+			summary: params.summary,
+			tags: params.tags ? [...params.tags] : [],
+			status: 'active',
+			createdAt: now,
+			updatedAt: now,
+		}
+
+		const memoryContent: MemoryContent = {
+			id,
+			content: params.content,
+			format: params.format ?? 'text',
+			metadata: params.metadata ? { ...params.metadata } : undefined,
+		}
+
+		this.index.set(entry)
+		this.content.set(id, memoryContent)
+
+		return { entry, content: memoryContent }
+	}
+
+	async get(id: MemoryId): Promise<MemoryContent | undefined> {
+		return this.content.get(id)
+	}
+
+	async update(
+		id: MemoryId,
+		updates: Partial<CreateMemoryParams>,
+	): Promise<MemoryIndexEntry | undefined> {
+		const existing = this.index.getEntry(id)
+		if (!existing) return undefined
+
+		const now = Date.now()
+
+		const updated: MemoryIndexEntry = {
+			...existing,
+			title: updates.title ?? existing.title,
+			summary: updates.summary ?? existing.summary,
+			tags: updates.tags ? [...updates.tags] : existing.tags,
+			updatedAt: now,
+		}
+
+		this.index.set(updated)
+
+		if (
+			updates.content !== undefined ||
+			updates.format !== undefined ||
+			updates.metadata !== undefined
+		) {
+			const existingContent = this.content.get(id)
+			if (existingContent) {
+				const updatedContent: MemoryContent = {
+					...existingContent,
+					content: updates.content ?? existingContent.content,
+					format: updates.format ?? existingContent.format,
+					metadata:
+						updates.metadata !== undefined ? { ...updates.metadata } : existingContent.metadata,
+				}
+				this.content.set(id, updatedContent)
+			}
+		}
+
+		return updated
+	}
+
+	async delete(id: MemoryId): Promise<boolean> {
+		const existed = this.index.remove(id)
+		this.content.delete(id)
+		return existed
+	}
+
+	async list(params?: MemorySearchParams): Promise<MemorySearchResult> {
+		return this.index.search(params ?? {})
+	}
+
+	getIndex(): InMemoryMemoryIndex {
+		return this.index
+	}
+}

package/src/tools/advisory/index.ts

@@ -0,0 +1,157 @@
+import { z } from 'zod'
+import type { AdvisoryContext } from '../../advisory/context.js'
+import type { ToolDefinition } from '../../types/tool/index.js'
+import { defineTool } from '../defineTool.js'
+
+export interface AdvisoryToolsOptions {
+	readonly advisoryCtx: AdvisoryContext
+}
+
+export function buildAdvisoryTools(opts: AdvisoryToolsOptions): ToolDefinition[] {
+	const { advisoryCtx } = opts
+
+	const listAdvisors = defineTool({
+		name: 'list_advisors',
+		description:
+			'List all available advisory agents with their domains of expertise and current budget status. Use this to discover which advisors are available before consulting one.',
+		inputSchema: z.object({}),
+		category: 'analysis',
+		permissions: [],
+		readOnly: true,
+		destructive: false,
+		concurrencySafe: true,
+		async execute() {
+			const advisors = advisoryCtx.registry.listAll()
+			const budget = advisoryCtx.getBudgetStatus()
+
+			const lines = advisors.map((a) => {
+				const domains = a.domains && a.domains.length > 0 ? a.domains.join(', ') : 'general'
+				return `- ${a.id}: ${a.name} [domains: ${domains}]`
+			})
+
+			const budgetLine =
+				budget.total !== undefined
+					? `Budget: ${budget.used}/${budget.total} calls used (${budget.remaining} remaining)`
+					: `Budget: ${budget.used} calls used (unlimited)`
+
+			return {
+				success: true,
+				output:
+					advisors.length === 0
+						? 'No advisors configured.'
+						: `${advisors.length} advisor(s) available:\n${lines.join('\n')}\n\n${budgetLine}`,
+				data: {
+					advisors: advisors.map((a) => ({
+						id: a.id,
+						name: a.name,
+						domains: a.domains ?? [],
+						model: a.model,
+					})),
+					budget,
+				},
+			}
+		},
+	})
+
+	const consultAdvisor = defineTool({
+		name: 'consult_advisor',
+		description:
+			'Consult an advisory agent for guidance. Resolves the advisor by explicit ID, domain match, or falls back to the default advisor. Checks budget before calling. Returns structured advice with optional warnings and decisions.',
+		inputSchema: z.object({
+			advisor_id: z.string().optional().describe('Explicit advisor ID to consult'),
+			question: z.string().describe('The question or situation to get advice on'),
+			domain: z
+				.string()
+				.optional()
+				.describe('Domain to match an advisor (e.g. "security", "architecture")'),
+			urgency: z
+				.enum(['low', 'normal', 'high'])
+				.optional()
+				.describe('How urgent the advisory need is'),
+			include_context: z
+				.boolean()
+				.optional()
+				.describe('Whether to include conversation context in the advisory call'),
+		}),
+		category: 'analysis',
+		permissions: [],
+		readOnly: true,
+		destructive: false,
+		concurrencySafe: true,
+		async execute({ advisor_id, question, domain, urgency, include_context }) {
+			const budgetCheck = advisoryCtx.checkBudget()
+			if (!budgetCheck.allowed) {
+				return {
+					success: false,
+					output: budgetCheck.reason ?? 'Advisory budget exhausted',
+					error: budgetCheck.reason,
+				}
+			}
+
+			const advisor = advisoryCtx.registry.resolve(advisor_id, domain)
+			if (!advisor) {
+				return {
+					success: false,
+					output: advisor_id
+						? `Advisor not found: ${advisor_id}`
+						: domain
+							? `No advisor found for domain: ${domain}`
+							: 'No advisors configured',
+					error: 'Advisor resolution failed',
+				}
+			}
+
+			const executionResult = await advisoryCtx.executor.consult(
+				advisor,
+				{ advisorId: advisor.id, question, domain, urgency, includeContext: include_context },
+				{ messages: [], iteration: 0 },
+			)
+
+			advisoryCtx.recordCall({
+				advisorId: advisor.id,
+				request: {
+					advisorId: advisor.id,
+					question,
+					domain,
+					urgency,
+					includeContext: include_context,
+				},
+				result: executionResult.result,
+				usage: executionResult.usage,
+				cost: executionResult.cost,
+				durationMs: executionResult.durationMs,
+				iteration: 0,
+				timestamp: Date.now(),
+			})
+
+			const sections: string[] = []
+
+			sections.push(`## Advice from ${advisor.name}\n\n${executionResult.result.advice}`)
+
+			if (executionResult.result.warnings && executionResult.result.warnings.length > 0) {
+				sections.push(
+					`## Warnings\n\n${executionResult.result.warnings.map((w) => `- ${w}`).join('\n')}`,
+				)
+			}
+
+			if (executionResult.result.decisions && executionResult.result.decisions.length > 0) {
+				sections.push(
+					`## Decisions\n\n${executionResult.result.decisions.map((d) => `- ${d}`).join('\n')}`,
+				)
+			}
+
+			return {
+				success: true,
+				output: sections.join('\n\n'),
+				data: {
+					advisorId: advisor.id,
+					result: executionResult.result,
+					usage: executionResult.usage,
+					durationMs: executionResult.durationMs,
+				},
+			}
+		},
+	})
+
+	return [listAdvisors, consultAdvisor]
+}

package/src/tools/defineTool.ts

@@ -16,6 +16,7 @@ export interface DefineToolOptions<S extends z.ZodType> {
 	readOnly: boolean
 	destructive: boolean | ((input: z.infer<S>) => boolean)
 	concurrencySafe: boolean
+	tier?: string
 	execute(input: z.infer<S>, context: ToolContext): Promise<ToolResult>
 }
 
@@ -28,6 +29,7 @@ export function defineTool<S extends z.ZodType>(
 		name: options.name,
 		description: options.description,
 		inputSchema: options.inputSchema,
+		tier: options.tier,
 		category: options.category,
 		permissions: options.permissions,
 		isReadOnly: () => options.readOnly,