@namzu/sdk 0.1.1

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

@@ -0,0 +1,177 @@
+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 { IterationContext } from "./context.js";
+
+export type ToolReviewOutcome = "executed" | "rejected" | "stop";
+
+export async function* runToolReview(
+	ctx: IterationContext,
+	response: ChatCompletionResponse,
+	iterationNum: number,
+): AsyncGenerator<RunEvent, ToolReviewOutcome> {
+	const toolCalls = response.message.toolCalls!;
+
+	const toolCallSummaries = toolCalls.map((tc) => {
+		let input: unknown;
+		try {
+			input = JSON.parse(tc.function.arguments);
+		} catch {
+			input = tc.function.arguments;
+		}
+		const tool = ctx.tools.get(tc.function.name);
+		const isDestructive = tool?.isDestructive
+			? tool.isDestructive(input)
+			: false;
+
+		return {
+			id: tc.id,
+			name: tc.function.name,
+			input,
+			isDestructive,
+		};
+	});
+
+	const reviewCheckpoint = await ctx.checkpointMgr.create(
+		ctx.sessionMgr,
+		iterationNum,
+	);
+
+	await ctx.emitEvent({
+		type: "tool_review_requested",
+		runId: ctx.sessionMgr.id,
+		toolCalls: toolCallSummaries,
+		iteration: iterationNum,
+	});
+	yield* ctx.drainPending();
+
+	const reviewDecision = await ctx.resumeHandler({
+		type: "tool_review",
+		runId: ctx.sessionMgr.id,
+		checkpointId: reviewCheckpoint.id,
+		toolCalls: toolCallSummaries,
+	});
+
+	switch (reviewDecision.action) {
+		case "reject_tools": {
+			await ctx.emitEvent({
+				type: "tool_review_completed",
+				runId: ctx.sessionMgr.id,
+				decision: "rejected",
+			});
+			yield* ctx.drainPending();
+
+			const feedback =
+				reviewDecision.feedback || "User rejected the tool calls";
+			ctx.sessionMgr.pushMessage(
+				createUserMessage(`[SYSTEM] Tool calls rejected: ${feedback}`),
+			);
+			return "rejected";
+		}
+
+		case "modify_tools": {
+			await ctx.emitEvent({
+				type: "tool_review_completed",
+				runId: ctx.sessionMgr.id,
+				decision: "modified",
+			});
+			yield* ctx.drainPending();
+
+			for (const mod of reviewDecision.modifications) {
+				if (mod.action === "modify" && mod.modifiedInput !== undefined) {
+					const tc = toolCalls.find((t) => t.id === mod.toolCallId);
+					if (tc) {
+						tc.function.arguments = JSON.stringify(mod.modifiedInput);
+					}
+				}
+			}
+
+			const deniedIds = new Set(
+				reviewDecision.modifications
+					.filter((m) => m.action === "deny")
+					.map((m) => m.toolCallId),
+			);
+			const filteredToolCalls = toolCalls.filter((tc) => !deniedIds.has(tc.id));
+
+			if (filteredToolCalls.length === 0) {
+				ctx.sessionMgr.pushMessage(
+					createUserMessage("[SYSTEM] All tool calls were denied by user"),
+				);
+				return "rejected";
+			}
+
+			const batch = await ctx.toolExecutor.executeBatch({
+				...response,
+				message: { ...response.message, toolCalls: filteredToolCalls },
+			});
+			for (const msg of batch.messages) {
+				ctx.sessionMgr.pushMessage(msg);
+			}
+			return "executed";
+		}
+
+		case "pause": {
+			await ctx.emitEvent({
+				type: "tool_review_completed",
+				runId: ctx.sessionMgr.id,
+				decision: "rejected",
+			});
+			await ctx.emitEvent({
+				type: "run_paused",
+				runId: ctx.sessionMgr.id,
+				checkpointId: reviewCheckpoint.id,
+				reason: reviewDecision.reason,
+			});
+			yield* ctx.drainPending();
+			ctx.sessionMgr.setStopReason("paused");
+			return "stop";
+		}
+
+		case "abort": {
+			await ctx.emitEvent({
+				type: "tool_review_completed",
+				runId: ctx.sessionMgr.id,
+				decision: "rejected",
+			});
+			yield* ctx.drainPending();
+			ctx.sessionMgr.setStopReason("cancelled");
+			ctx.sessionMgr.markCancelled();
+			return "stop";
+		}
+
+		case "approve_tools":
+		case "continue": {
+			await ctx.emitEvent({
+				type: "tool_review_completed",
+				runId: ctx.sessionMgr.id,
+				decision: "approved",
+			});
+			yield* ctx.drainPending();
+
+			const batch = await ctx.toolExecutor.executeBatch(response);
+			for (const msg of batch.messages) {
+				ctx.sessionMgr.pushMessage(msg);
+			}
+			return "executed";
+		}
+
+		case "approve_plan":
+		case "reject_plan": {
+			ctx.log.warn("Unexpected plan decision during tool review", {
+				action: reviewDecision.action,
+			});
+			const batch = await ctx.toolExecutor.executeBatch(response);
+			for (const msg of batch.messages) {
+				ctx.sessionMgr.pushMessage(msg);
+			}
+			return "executed";
+		}
+
+		default: {
+			const _exhaustive: never = reviewDecision;
+			throw new Error(
+				`Unhandled tool review decision: ${(_exhaustive as { action: string }).action}`,
+			);
+		}
+	}
+}

package/src/runtime/query/prompt.ts

@@ -0,0 +1,73 @@
+import type { AgentPersona } from '../../types/persona/index.js'
+import type { Skill } from '../../types/skills/index.js'
+import type { ToolRegistry } from '../../registry/tool/execute.js'
+import type { AgentContextLevel } from '../../types/agent/factory.js'
+import { assembleSystemPrompt } from '../../persona/assembler.js'
+
+const FILESYSTEM_TOOLS = new Set(['glob', 'read_file', 'write_file', 'bash'])
+
+export interface PromptBuilderConfig {
+  systemPrompt?: string
+
+  persona?: AgentPersona
+
+  skills?: Skill[]
+
+  basePrompt?: string
+
+  tools: ToolRegistry
+  allowedTools?: string[]
+}
+
+function buildEnvContext(workingDirectory: string): string {
+  return `<env>
+Working directory: ${workingDirectory}
+Platform: ${process.platform}
+</env>
+
+IMPORTANT: Always use absolute paths based on the working directory above. Before reading a file, use the glob tool to discover actual file paths — never guess or hallucinate paths.`
+}
+
+function hasFilesystemTools(tools: ToolRegistry, allowedTools?: string[]): boolean {
+  const activeTools = allowedTools ?? tools.listNames()
+  return activeTools.some(name => FILESYSTEM_TOOLS.has(name))
+}
+
+export class PromptBuilder {
+  private config: PromptBuilderConfig
+
+  constructor(config: PromptBuilderConfig) {
+    this.config = config
+  }
+
+  build(contextLevel: AgentContextLevel = 'full', workingDirectory?: string): string {
+    const parts: string[] = []
+
+    if (contextLevel === 'full' && this.config.basePrompt) {
+      parts.push(this.config.basePrompt)
+    }
+
+    if (this.config.systemPrompt) {
+      parts.push(this.config.systemPrompt)
+    } else if (this.config.persona) {
+      parts.push(assembleSystemPrompt(this.config.persona, this.config.skills))
+    }
+
+    if (contextLevel !== 'minimal') {
+      const toolSection = this.config.tools.toPromptSection(this.config.allowedTools)
+      if (toolSection) {
+        parts.push(toolSection)
+      }
+    }
+
+    if (
+      contextLevel !== 'minimal' &&
+      workingDirectory &&
+      hasFilesystemTools(this.config.tools, this.config.allowedTools)
+    ) {
+      parts.push(buildEnvContext(workingDirectory))
+    }
+
+    return parts.join('\n\n---\n\n')
+  }
+}

package/src/runtime/query/result.ts

@@ -0,0 +1,95 @@
+import type { AgentRun, RunEvent } from '../../types/run/index.js'
+import type { RunPersistence } from '../../manager/run/persistence.js'
+import type { PlanManager } from '../../manager/plan/lifecycle.js'
+import type { ActivityStore } from '../../store/activity/memory.js'
+import type { Logger } from '../../utils/logger.js'
+import type { EmitEvent } from './events.js'
+import { SpanStatusCode } from '@opentelemetry/api'
+import { toErrorMessage } from '../../utils/error.js'
+import { GENAI, NAMZU } from '../../telemetry/attributes.js'
+import type { Span } from '@opentelemetry/api'
+
+export interface ResultAssemblerConfig {
+  sessionMgr: RunPersistence
+  planManager: PlanManager
+  activityStore: ActivityStore
+  log: Logger
+  emitEvent: EmitEvent
+  drainPending: () => Generator<RunEvent>
+}
+
+export class ResultAssembler {
+  private config: ResultAssemblerConfig
+
+  constructor(config: ResultAssemblerConfig) {
+    this.config = config
+  }
+
+  async *completeRun(rootSpan: Span): AsyncGenerator<RunEvent> {
+    const { sessionMgr, activityStore, log, emitEvent, drainPending } = this.config
+
+    if (sessionMgr.status === 'running') {
+      sessionMgr.markCompleted(sessionMgr.stopReason)
+    }
+
+    await emitEvent({
+      type: 'run_completed',
+      runId: sessionMgr.id,
+      result: sessionMgr.getRun().result ?? '',
+    })
+    yield* drainPending()
+
+    rootSpan.setAttributes({
+      [NAMZU.SESSION_STATUS]: sessionMgr.stopReason ?? 'completed',
+      [NAMZU.ITERATION]: sessionMgr.currentIteration,
+      [GENAI.USAGE_INPUT_TOKENS]: sessionMgr.tokenUsage.promptTokens,
+      [GENAI.USAGE_OUTPUT_TOKENS]: sessionMgr.tokenUsage.completionTokens,
+    })
+    rootSpan.setStatus({ code: SpanStatusCode.OK })
+
+    log.info('Query completed', {
+      runId: sessionMgr.id,
+      iterations: sessionMgr.currentIteration,
+      stopReason: sessionMgr.stopReason,
+      activityStats: activityStore.enabled ? activityStore.stats() : undefined,
+    })
+  }
+
+  async *completeSession(rootSpan: Span): AsyncGenerator<RunEvent> {
+    yield* this.completeRun(rootSpan)
+  }
+
+  async *handleError(err: unknown, rootSpan: Span): AsyncGenerator<RunEvent> {
+    const { sessionMgr, planManager, log, emitEvent, drainPending } = this.config
+    const errorMessage = toErrorMessage(err)
+    sessionMgr.markFailed(errorMessage)
+
+    if (planManager.isActive) {
+      planManager.failPlan(errorMessage)
+    }
+
+    await emitEvent({
+      type: 'run_failed',
+      runId: sessionMgr.id,
+      error: errorMessage,
+    })
+    yield* drainPending()
+
+    rootSpan.setAttributes({
+      [NAMZU.SESSION_STATUS]: 'error',
+      [NAMZU.ITERATION]: sessionMgr.currentIteration,
+    })
+    rootSpan.setStatus({ code: SpanStatusCode.ERROR, message: errorMessage })
+    rootSpan.recordException(err instanceof Error ? err : new Error(errorMessage))
+
+    log.error('Query failed', {
+      runId: sessionMgr.id,
+      error: errorMessage,
+    })
+  }
+
+  async finalize(): Promise<AgentRun> {
+    await this.config.sessionMgr.persist()
+    return this.config.sessionMgr.getRun()
+  }
+}

package/src/runtime/query/tooling.ts

@@ -0,0 +1,41 @@
+import type { PermissionMode } from '../../types/permission/index.js'
+import type { RunEvent } from '../../types/run/index.js'
+import type { RunId } from '../../types/ids/index.js'
+import type { ToolRegistry } from '../../registry/tool/execute.js'
+import type { ActivityStore } from '../../store/activity/memory.js'
+import type { Logger } from '../../utils/logger.js'
+import { ToolExecutor } from './executor.js'
+
+export type EmitEvent = (event: RunEvent) => Promise<void>
+
+export interface ToolingBootstrapConfig {
+  tools: ToolRegistry
+  runId: RunId
+  workingDirectory: string
+  permissionMode: PermissionMode
+  env: Record<string, string>
+  abortSignal: AbortSignal
+}
+
+export class ToolingBootstrap {
+  static init(
+    config: ToolingBootstrapConfig,
+    activityStore: ActivityStore,
+    emitEvent: EmitEvent,
+    log: Logger,
+  ): ToolExecutor {
+    return new ToolExecutor(
+      {
+        tools: config.tools,
+        runId: config.runId,
+        workingDirectory: config.workingDirectory,
+        permissionMode: config.permissionMode,
+        env: config.env,
+        abortSignal: config.abortSignal,
+      },
+      activityStore,
+      emitEvent,
+      log,
+    )
+  }
+}

package/src/skills/index.ts

@@ -0,0 +1,2 @@
+export { loadSkill, discoverSkills } from './loader.js'
+export { SkillRegistry, resolveSkillChain } from './registry.js'

package/src/skills/loader.ts

@@ -0,0 +1,164 @@
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { join, basename } from 'node:path'
+import type { Skill, SkillMetadata, SkillDisclosureLevel, SkillLoadResult } from '../types/skills/index.js'
+import { getRootLogger } from '../utils/logger.js'
+
+const logger = getRootLogger().child({ component: 'SkillLoader' })
+
+const SKILL_FILENAME = 'SKILL.md'
+const FRONTMATTER_DELIMITER = '---'
+
+interface ParsedSkillMd {
+  metadata: SkillMetadata
+  body: string
+}
+
+function parseSkillMd(raw: string, dirPath: string): ParsedSkillMd {
+  const trimmed = raw.trimStart()
+
+  if (!trimmed.startsWith(FRONTMATTER_DELIMITER)) {
+    throw new Error(`SKILL.md at "${dirPath}" has no YAML frontmatter`)
+  }
+
+  const endIdx = trimmed.indexOf(FRONTMATTER_DELIMITER, FRONTMATTER_DELIMITER.length)
+  if (endIdx === -1) {
+    throw new Error(`SKILL.md at "${dirPath}" has unclosed frontmatter`)
+  }
+
+  const frontmatterRaw = trimmed.slice(FRONTMATTER_DELIMITER.length, endIdx).trim()
+  const body = trimmed.slice(endIdx + FRONTMATTER_DELIMITER.length).trim()
+
+  const metadata = parseFlatYaml(frontmatterRaw, dirPath)
+
+  return { metadata, body }
+}
+
+function parseFlatYaml(raw: string, dirPath: string): SkillMetadata {
+  const lines = raw.split('\n')
+  const kv: Record<string, string> = {}
+
+  for (const line of lines) {
+    const colonIdx = line.indexOf(':')
+    if (colonIdx === -1) continue
+    const key = line.slice(0, colonIdx).trim()
+    const value = line.slice(colonIdx + 1).trim()
+
+    kv[key] = value.replace(/^["']|["']$/g, '')
+  }
+
+  if (!kv['name']) {
+    throw new Error(`SKILL.md at "${dirPath}" missing required field: name`)
+  }
+  if (!kv['description']) {
+    throw new Error(`SKILL.md at "${dirPath}" missing required field: description`)
+  }
+
+  validateSkillName(kv['name'], dirPath)
+  validateDescription(kv['description'], dirPath)
+
+  const metadata: SkillMetadata = {
+    name: kv['name'],
+    description: kv['description'],
+  }
+
+  if (kv['compatibility']) {
+    if (kv['compatibility'].length > 500) {
+      throw new Error(`SKILL.md at "${dirPath}": compatibility exceeds 500 characters`)
+    }
+    metadata.compatibility = kv['compatibility']
+  }
+
+  return metadata
+}
+
+const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+function validateSkillName(name: string, dirPath: string): void {
+  if (name.length > 64) {
+    throw new Error(`SKILL.md at "${dirPath}": name exceeds 64 characters`)
+  }
+  if (!SKILL_NAME_PATTERN.test(name)) {
+    throw new Error(
+      `SKILL.md at "${dirPath}": name "${name}" must be lowercase alphanumeric with hyphens, ` +
+      `no leading/trailing hyphens, no consecutive hyphens`,
+    )
+  }
+  const expectedName = basename(dirPath)
+  if (name !== expectedName) {
+    throw new Error(
+      `SKILL.md at "${dirPath}": name "${name}" must match directory name "${expectedName}"`,
+    )
+  }
+}
+
+function validateDescription(description: string, dirPath: string): void {
+  if (description.length === 0) {
+    throw new Error(`SKILL.md at "${dirPath}": description must not be empty`)
+  }
+  if (description.length > 1024) {
+    throw new Error(`SKILL.md at "${dirPath}": description exceeds 1024 characters`)
+  }
+}
+
+const CHARS_PER_TOKEN = 4
+
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / CHARS_PER_TOKEN)
+}
+
+export async function loadSkill(
+  dirPath: string,
+  level: SkillDisclosureLevel = 'metadata',
+): Promise<SkillLoadResult> {
+  const skillMdPath = join(dirPath, SKILL_FILENAME)
+  const raw = await readFile(skillMdPath, 'utf-8')
+  const parsed = parseSkillMd(raw, dirPath)
+
+  const skill: Skill = {
+    metadata: parsed.metadata,
+    dirPath,
+  }
+
+  if (level === 'full' || level === 'assets') {
+    skill.body = parsed.body
+  }
+
+  const metadataTokens = estimateTokens(`${parsed.metadata.name}: ${parsed.metadata.description}`)
+  const bodyTokens = skill.body ? estimateTokens(skill.body) : 0
+
+  logger.debug('Loaded skill', {
+    name: parsed.metadata.name,
+    level,
+    tokens: metadataTokens + bodyTokens,
+  })
+
+  return {
+    skill,
+    disclosureLevel: level,
+    tokenEstimate: metadataTokens + bodyTokens,
+  }
+}
+
+export async function discoverSkills(parentDir: string): Promise<string[]> {
+  const dirs: string[] = []
+
+  try {
+    const entries = await readdir(parentDir)
+    for (const entry of entries) {
+      if (entry.startsWith('.') || entry.startsWith('_')) continue
+      const fullPath = join(parentDir, entry)
+      const s = await stat(fullPath)
+      if (!s.isDirectory()) continue
+
+      const skillMdPath = join(fullPath, SKILL_FILENAME)
+      try {
+        await stat(skillMdPath)
+        dirs.push(fullPath)
+      } catch {}
+    }
+  } catch {
+    logger.debug('Skills directory not found', { parentDir })
+  }
+
+  return dirs
+}

package/src/skills/registry.ts

@@ -0,0 +1,102 @@
+import type { Skill, SkillChain, SkillDisclosureLevel, SkillLoadResult } from '../types/skills/index.js'
+import { discoverSkills, loadSkill } from './loader.js'
+import { getRootLogger } from '../utils/logger.js'
+
+const logger = getRootLogger().child({ component: 'SkillRegistry' })
+
+export class SkillRegistry {
+  private skills = new Map<string, Skill>()
+
+  async register(dirPath: string, level: SkillDisclosureLevel = 'metadata'): Promise<Skill> {
+    const result = await loadSkill(dirPath, level)
+    this.skills.set(result.skill.metadata.name, result.skill)
+    return result.skill
+  }
+
+  async registerAll(parentDir: string, level: SkillDisclosureLevel = 'metadata'): Promise<Skill[]> {
+    const dirs = await discoverSkills(parentDir)
+    const results: Skill[] = []
+
+    for (const dir of dirs) {
+      const skill = await this.register(dir, level)
+      results.push(skill)
+    }
+
+    logger.debug('Registered skills from directory', {
+      parentDir,
+      count: results.length,
+      names: results.map((s) => s.metadata.name),
+    })
+
+    return results
+  }
+
+  get(name: string): Skill | undefined {
+    return this.skills.get(name)
+  }
+
+  async load(name: string, level: SkillDisclosureLevel = 'full'): Promise<SkillLoadResult | undefined> {
+    const existing = this.skills.get(name)
+    if (!existing) return undefined
+
+    if (level === 'metadata' || existing.body) {
+      return {
+        skill: existing,
+        disclosureLevel: existing.body ? 'full' : 'metadata',
+        tokenEstimate: 0,
+      }
+    }
+
+    const result = await loadSkill(existing.dirPath, level)
+    this.skills.set(name, result.skill)
+    return result
+  }
+
+  list(): Skill[] {
+    return [...this.skills.values()]
+  }
+
+  get size(): number {
+    return this.skills.size
+  }
+
+  has(name: string): boolean {
+    return this.skills.has(name)
+  }
+}
+
+export async function resolveSkillChain(
+  categorySkillsDir: string | undefined,
+  agentSkillsDir: string | undefined,
+  level: SkillDisclosureLevel = 'metadata',
+): Promise<SkillChain> {
+  const categoryRegistry = new SkillRegistry()
+  const agentRegistry = new SkillRegistry()
+
+  const inherited = categorySkillsDir
+    ? await categoryRegistry.registerAll(categorySkillsDir, level)
+    : []
+
+  const own = agentSkillsDir
+    ? await agentRegistry.registerAll(agentSkillsDir, level)
+    : []
+
+  const resolvedMap = new Map<string, Skill>()
+
+  for (const skill of inherited) {
+    resolvedMap.set(skill.metadata.name, skill)
+  }
+  for (const skill of own) {
+    resolvedMap.set(skill.metadata.name, skill)
+  }
+
+  const resolved = [...resolvedMap.values()]
+
+  logger.debug('Resolved skill chain', {
+    inherited: inherited.map((s) => s.metadata.name),
+    own: own.map((s) => s.metadata.name),
+    resolved: resolved.map((s) => s.metadata.name),
+  })
+
+  return { inherited, own, resolved }
+}