@namzu/sdk 0.1.1

package/src/runtime/decision/parser.ts

@@ -0,0 +1,150 @@
+import { type RoutingResponse, RoutingResponseSchema, type DecisionParserConfig, type DecisionParseResult } from '../../types/decision/index.js'
+import type { Logger } from '../../utils/logger.js'
+
+export class DecisionParser {
+  private config: DecisionParserConfig
+  private log: Logger
+
+  constructor(config: DecisionParserConfig, log: Logger) {
+    this.config = config
+    this.log = log
+  }
+
+  parse(rawContent: string | null): DecisionParseResult {
+    if (!rawContent || rawContent.trim().length === 0) {
+      return {
+        ok: true,
+        decision: {
+          agentId: this.config.fallbackAgentId,
+          confidence: 0,
+          reasoning: 'Empty LLM response',
+        },
+        source: 'fallback',
+        reason: 'empty_response',
+      }
+    }
+
+    const jsonStr = this.extractJson(rawContent)
+    if (!jsonStr) {
+      this.log.warn('Failed to extract JSON from LLM routing response', {
+        contentPreview: rawContent.slice(0, 200),
+      })
+      return {
+        ok: true,
+        decision: {
+          agentId: this.config.fallbackAgentId,
+          confidence: 0,
+          reasoning: `Could not extract JSON from response`,
+        },
+        source: 'fallback',
+        reason: 'json_extraction_failed',
+      }
+    }
+
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(jsonStr)
+    } catch (err) {
+      this.log.warn('Invalid JSON in routing response', {
+        error: String(err),
+        contentPreview: jsonStr.slice(0, 200),
+      })
+      return {
+        ok: true,
+        decision: {
+          agentId: this.config.fallbackAgentId,
+          confidence: 0,
+          reasoning: `JSON parse failed: ${String(err)}`,
+        },
+        source: 'fallback',
+        reason: 'json_parse_failed',
+      }
+    }
+
+    const validation = RoutingResponseSchema.safeParse(parsed)
+    if (!validation.success) {
+      const errors = validation.error.issues
+        .map((i) => `${i.path.join('.')}: ${i.message}`)
+        .join('; ')
+
+      this.log.warn('Routing response failed schema validation', { errors })
+
+      return {
+        ok: true,
+        decision: {
+          agentId: this.config.fallbackAgentId,
+          confidence: 0,
+          reasoning: `Schema validation failed: ${errors}`,
+        },
+        source: 'fallback',
+        reason: 'schema_validation_failed',
+      }
+    }
+
+    const response = validation.data
+
+    if (!this.config.validAgentIds.includes(response.agentId)) {
+      this.log.warn('LLM returned unknown agentId', {
+        agentId: response.agentId,
+        validIds: this.config.validAgentIds,
+      })
+
+      return {
+        ok: true,
+        decision: {
+          agentId: this.config.fallbackAgentId,
+          confidence: 0,
+          reasoning: `Unknown agentId "${response.agentId}", falling back`,
+        },
+        source: 'fallback',
+        reason: 'unknown_agent_id',
+      }
+    }
+
+    if (response.confidence < this.config.minConfidence) {
+      this.log.info('Routing confidence below threshold', {
+        confidence: response.confidence,
+        threshold: this.config.minConfidence,
+        agentId: response.agentId,
+      })
+
+      return {
+        ok: true,
+        decision: {
+          agentId: this.config.fallbackAgentId,
+          confidence: response.confidence,
+          reasoning: `Confidence ${response.confidence} below threshold ${this.config.minConfidence}`,
+        },
+        source: 'fallback',
+        reason: 'low_confidence',
+      }
+    }
+
+    return {
+      ok: true,
+      decision: response,
+      source: 'parsed',
+    }
+  }
+
+  private extractJson(content: string): string | null {
+    const trimmed = content.trim()
+
+    if (trimmed.startsWith('{')) {
+      return trimmed
+    }
+
+    const codeBlockMatch = trimmed.match(/```(?:json)?\s*\n?([\s\S]*?)\n?\s*```/)
+    if (codeBlockMatch?.[1]) {
+      return codeBlockMatch[1].trim()
+    }
+
+    const braceStart = trimmed.indexOf('{')
+    const braceEnd = trimmed.lastIndexOf('}')
+    if (braceStart !== -1 && braceEnd > braceStart) {
+      return trimmed.slice(braceStart, braceEnd + 1)
+    }
+
+    return null
+  }
+}

package/src/runtime/query/checkpoint.ts

@@ -0,0 +1,83 @@
+import type { RunPersistence } from '../../manager/run/persistence.js'
+import type { CheckpointId, IterationCheckpoint, CheckpointSummary, ActiveNodeInfo, BranchStackEntry } from '../../types/hitl/index.js'
+import type { RunDiskStore } from '../../store/run/disk.js'
+import type { AssistantMessage } from '../../types/message/index.js'
+import { generateCheckpointId } from '../../utils/id.js'
+import { buildToolResultHashes } from '../../utils/hash.js'
+
+export class CheckpointManager {
+  private store: RunDiskStore
+
+  constructor(store: RunDiskStore) {
+    this.store = store
+  }
+
+  async create(
+    sessionMgr: RunPersistence,
+    iteration: number,
+    extra?: {
+      toolResults?: Array<{ toolCallId: string; toolName: string; input: unknown; output: string }>
+      branchStack?: BranchStackEntry[]
+      activeNode?: ActiveNodeInfo
+    },
+  ): Promise<IterationCheckpoint> {
+    const checkpoint: IterationCheckpoint = {
+      id: generateCheckpointId(),
+      runId: sessionMgr.id,
+      iteration,
+      messages: [...sessionMgr.messages],
+      tokenUsage: { ...sessionMgr.tokenUsage },
+      costInfo: { ...sessionMgr.costInfo },
+      guardState: {
+        iterationCount: sessionMgr.currentIteration,
+        elapsedMs: Date.now() - (sessionMgr.getSession().startedAt ?? Date.now()),
+      },
+      createdAt: Date.now(),
+      toolResultHashes: extra?.toolResults ? buildToolResultHashes(extra.toolResults) : undefined,
+      branchStack: extra?.branchStack,
+      activeNode: extra?.activeNode,
+    }
+
+    await this.store.writeCheckpoint(checkpoint)
+    return checkpoint
+  }
+
+  async restore(checkpointId: CheckpointId): Promise<IterationCheckpoint> {
+    const checkpoint = await this.store.readCheckpoint(checkpointId)
+    if (!checkpoint) {
+      throw new Error(`Checkpoint not found: ${checkpointId}`)
+    }
+    return checkpoint
+  }
+
+  async list(): Promise<IterationCheckpoint[]> {
+    return this.store.listCheckpoints()
+  }
+
+  async prune(keepLast: number): Promise<void> {
+    const all = await this.list()
+    if (all.length <= keepLast) return
+
+    const toDelete = all
+      .sort((a, b) => a.createdAt - b.createdAt)
+      .slice(0, all.length - keepLast)
+
+    for (const cp of toDelete) {
+      await this.store.deleteCheckpoint(cp.id)
+    }
+  }
+
+  static buildSummary(sessionMgr: RunPersistence, iteration: number): CheckpointSummary {
+    const lastAssistant = [...sessionMgr.messages]
+      .reverse()
+      .find((m): m is AssistantMessage => m.role === 'assistant' && m.content !== null)
+
+    return {
+      iteration,
+      messageCount: sessionMgr.messages.length,
+      tokenUsage: { ...sessionMgr.tokenUsage },
+      costInfo: { ...sessionMgr.costInfo },
+      lastAssistantMessage: lastAssistant?.content ?? undefined,
+    }
+  }
+}

package/src/runtime/query/context-cache.ts

@@ -0,0 +1,86 @@
+import type { ThreadId } from '../../types/ids/index.js'
+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 { PromptBuilder } from './prompt.js'
+import { memoizeAsync } from '../../utils/memoize.js'
+import { createHash } from 'node:crypto'
+
+export interface ContextCacheConfig {
+  agentId: string
+  threadId: ThreadId
+}
+
+export interface PromptCacheInput {
+  systemPrompt?: string
+  persona?: AgentPersona
+  skills?: Skill[]
+  basePrompt?: string
+  tools: ToolRegistry
+  allowedTools?: string[]
+}
+
+export class ContextCache {
+  readonly threadId: ThreadId
+  readonly agentId: string
+
+  private cachedPrompt: string | undefined
+  private cachedConfigHash: string | undefined
+
+  constructor(config: ContextCacheConfig) {
+    this.threadId = config.threadId
+    this.agentId = config.agentId
+  }
+
+  getSystemPrompt(input: PromptCacheInput): string {
+    const hash = this.computeConfigHash(input)
+
+    if (this.cachedPrompt && this.cachedConfigHash === hash) {
+      return this.cachedPrompt
+    }
+
+    const builder = new PromptBuilder({
+      systemPrompt: input.systemPrompt,
+      persona: input.persona,
+      skills: input.skills,
+      basePrompt: input.basePrompt,
+      tools: input.tools,
+      allowedTools: input.allowedTools,
+    })
+
+    this.cachedPrompt = builder.build()
+    this.cachedConfigHash = hash
+    return this.cachedPrompt
+  }
+
+  get configHash(): string | undefined {
+    return this.cachedConfigHash
+  }
+
+  needsRebuild(input: PromptCacheInput): boolean {
+    if (!this.cachedConfigHash) return true
+    return this.computeConfigHash(input) !== this.cachedConfigHash
+  }
+
+  invalidate(): void {
+    this.cachedPrompt = undefined
+    this.cachedConfigHash = undefined
+  }
+
+  private computeConfigHash(input: PromptCacheInput): string {
+    const parts: string[] = [
+      this.agentId,
+      input.systemPrompt ?? '',
+      input.persona?.identity?.role ?? '',
+      input.persona?.identity?.description ?? '',
+      input.basePrompt ?? '',
+      ...(input.skills?.map(s => s.metadata.name) ?? []),
+      ...(input.allowedTools ?? []),
+    ]
+
+    return createHash('sha256')
+      .update(parts.join('\0'))
+      .digest('hex')
+      .slice(0, 16)
+  }
+}

package/src/runtime/query/context.ts

@@ -0,0 +1,105 @@
+import type { AgentRunConfig } from '../../types/run/index.js'
+import type { LLMProvider } from '../../types/provider/index.js'
+import type { ModelPricing } from '../../utils/cost.js'
+import type { Message } from '../../types/message/index.js'
+import type { Logger } from '../../utils/logger.js'
+import type { RunId, ThreadId } from '../../types/ids/index.js'
+import type { PermissionMode } from '../../types/permission/index.js'
+import { type ActivityTrackingConfig, resolveActivityTracking } from '../../types/activity/index.js'
+import { RunPersistence } from '../../manager/run/persistence.js'
+import { ActivityStore } from '../../store/activity/memory.js'
+import { PlanManager } from '../../manager/plan/lifecycle.js'
+import { getRootLogger } from '../../utils/logger.js'
+import { generateRunId } from '../../utils/id.js'
+import { join } from 'node:path'
+
+export interface RunContextConfig {
+  agentId: string
+  agentName: string
+  sessionConfig: AgentRunConfig
+  provider: LLMProvider
+  workingDirectory?: string
+  pricing?: ModelPricing
+  enableActivityTracking?: boolean
+  messages: Message[]
+  signal?: AbortSignal
+
+  threadId: ThreadId
+
+  runId?: RunId
+
+  parentRunId?: RunId
+
+  depth?: number
+}
+
+export interface RunContext {
+  runId: RunId
+  threadId: ThreadId
+  sessionMgr: RunPersistence
+  activityStore: ActivityStore
+  planManager: PlanManager
+  abortController: AbortController
+  cwd: string
+  outputDir: string
+  permissionMode: PermissionMode
+  log: Logger
+  trackingConfig: ActivityTrackingConfig
+}
+
+export class RunContextFactory {
+  static build(config: RunContextConfig): RunContext {
+    const abortController = new AbortController()
+    if (config.signal) {
+      config.signal.addEventListener('abort', () => abortController.abort(), { once: true })
+    }
+
+    const cwd = config.workingDirectory ?? process.cwd()
+    const permissionMode = config.sessionConfig.permissionMode ?? 'auto'
+    const runId = config.runId ?? generateRunId()
+
+    if (!config.threadId) {
+      throw new Error('threadId is required for run persistence — all runs must belong to a thread')
+    }
+    const threadId: ThreadId = config.threadId
+    const outputDir = join(cwd, '.namzu', 'threads', threadId, 'runs')
+
+    const log = getRootLogger().child({
+      component: 'query',
+      agent: config.agentName,
+      runId,
+      threadId,
+    })
+
+    const sessionMgr = new RunPersistence({
+      runId,
+      agentId: config.agentId,
+      agentName: config.agentName,
+      sessionConfig: config.sessionConfig,
+      providerId: config.provider.id,
+      outputDir,
+      pricing: config.pricing,
+      log,
+      parentRunId: config.parentRunId,
+      depth: config.depth,
+    })
+
+    const trackingConfig = resolveActivityTracking(permissionMode, config.enableActivityTracking)
+    const activityStore = new ActivityStore(runId, trackingConfig)
+    const planManager = new PlanManager(runId)
+
+    return {
+      runId,
+      threadId,
+      sessionMgr,
+      activityStore,
+      planManager,
+      abortController,
+      cwd,
+      outputDir,
+      permissionMode,
+      log,
+      trackingConfig,
+    }
+  }
+}

package/src/runtime/query/events.ts

@@ -0,0 +1,141 @@
+import type { RunEvent } from '../../types/run/index.js'
+import type { RunId } from '../../types/ids/index.js'
+import type { RunPersistence } from '../../manager/run/persistence.js'
+import { type ActivityEvent, type ActivityStore } from '../../store/activity/memory.js'
+import type { PlanEvent, PlanManager } from '../../manager/plan/lifecycle.js'
+import type { TaskEvent, TaskStore } from '../../types/task/index.js'
+
+export type EmitEvent = (event: RunEvent) => Promise<void>
+
+export class EventTranslator {
+  private pendingEvents: RunEvent[] = []
+  private sessionMgr: RunPersistence
+
+  constructor(sessionMgr: RunPersistence) {
+    this.sessionMgr = sessionMgr
+  }
+
+  readonly emitEvent: EmitEvent = async (event: RunEvent): Promise<void> => {
+    this.pendingEvents.push(event)
+    await this.sessionMgr.getRunStore().appendEvent(event)
+  }
+
+  *drainPending(): Generator<RunEvent> {
+    while (this.pendingEvents.length > 0) {
+      yield this.pendingEvents.shift()!
+    }
+  }
+
+  wireActivityStore(activityStore: ActivityStore, runId: RunId): void {
+    activityStore.on((event: ActivityEvent) => {
+      const activity = event.activity
+      if (event.type === 'activity.created') {
+        this.emitEvent({
+          type: 'activity_created',
+          runId,
+          activityId: activity.id,
+          activityType: activity.type,
+          description: activity.description,
+        })
+      } else {
+        this.emitEvent({
+          type: 'activity_updated',
+          runId,
+          activityId: activity.id,
+          status: activity.status,
+          output: activity.output,
+          error: activity.error,
+        })
+      }
+    })
+  }
+
+  wireTaskStore(taskStore: TaskStore, runId: RunId): () => void {
+    const unsubscribe = taskStore.on((event: TaskEvent) => {
+      const task = event.task
+
+      if (task.runId !== runId) return
+      switch (event.type) {
+        case 'task.created':
+          this.emitEvent({
+            type: 'task_created',
+            runId,
+            taskId: task.id,
+            subject: task.subject,
+            status: task.status,
+          })
+          break
+        case 'task.updated':
+        case 'task.claimed':
+        case 'task.deleted':
+          this.emitEvent({
+            type: 'task_updated',
+            runId,
+            taskId: task.id,
+            subject: task.subject,
+            status: task.status,
+            owner: task.owner,
+          })
+          break
+        default: {
+          const _exhaustive: never = event.type
+          throw new Error(`Unhandled task event type: ${_exhaustive}`)
+        }
+      }
+    })
+    return unsubscribe
+  }
+
+  wirePlanManager(planManager: PlanManager, runId: RunId): void {
+    planManager.on((event: PlanEvent) => {
+      const plan = event.plan
+      switch (event.type) {
+        case 'plan.ready':
+          this.emitEvent({
+            type: 'plan_ready',
+            runId,
+            planId: plan.id,
+            title: plan.title,
+            steps: plan.steps,
+            summary: plan.summary,
+          })
+          break
+        case 'plan.approved':
+          this.emitEvent({
+            type: 'plan_approved',
+            runId,
+            planId: plan.id,
+          })
+          break
+        case 'plan.rejected':
+          this.emitEvent({
+            type: 'plan_rejected',
+            runId,
+            planId: plan.id,
+            reason: plan.rejectionReason,
+          })
+          break
+        case 'plan.step_updated':
+          if (event.step) {
+            this.emitEvent({
+              type: 'plan_step_updated',
+              runId,
+              planId: plan.id,
+              stepId: event.step.id,
+              status: event.step.status,
+            })
+          }
+          break
+        case 'plan.generating':
+        case 'plan.executing':
+        case 'plan.completed':
+        case 'plan.failed':
+          break
+        default: {
+          const _exhaustive: never = event.type
+          throw new Error(`Unhandled plan event type: ${_exhaustive}`)
+        }
+      }
+    })
+  }
+}