@namzu/sdk 0.1.1

package/src/store/InMemoryStore.ts

@@ -0,0 +1,72 @@
+import type { PaginationParams, PaginatedResponse } from '../contracts/index.js'
+
+export interface Identifiable {
+  id: string
+}
+
+export interface Timestamped {
+  created_at: string
+}
+
+export class InMemoryStore<T extends Identifiable & Timestamped> {
+  protected items: Map<string, T> = new Map()
+
+  get(id: string): T | undefined {
+    return this.items.get(id)
+  }
+
+  has(id: string): boolean {
+    return this.items.has(id)
+  }
+
+  set(item: T): void {
+    this.items.set(item.id, item)
+  }
+
+  delete(id: string): boolean {
+    return this.items.delete(id)
+  }
+
+  size(): number {
+    return this.items.size
+  }
+
+  all(): T[] {
+    return Array.from(this.items.values())
+  }
+
+  paginate(
+    items: T[],
+    params: PaginationParams = {},
+  ): PaginatedResponse<T> {
+    const { limit = 20, order = 'desc', after, before } = params
+
+    let sorted = [...items]
+    sorted.sort((a, b) => {
+      const cmp = a.created_at.localeCompare(b.created_at)
+      return order === 'desc' ? -cmp : cmp
+    })
+
+    if (after) {
+      const idx = sorted.findIndex((item) => item.id === after)
+      if (idx !== -1) sorted = sorted.slice(idx + 1)
+    }
+    if (before) {
+      const idx = sorted.findIndex((item) => item.id === before)
+      if (idx !== -1) sorted = sorted.slice(0, idx)
+    }
+
+    const sliced = sorted.slice(0, Math.min(limit, 100))
+
+    return {
+      data: sliced,
+      has_more: sorted.length > sliced.length,
+      first_id: sliced[0]?.id ?? null,
+      last_id: sliced[sliced.length - 1]?.id ?? null,
+    }
+  }
+
+  list(params: PaginationParams = {}): PaginatedResponse<T> {
+    return this.paginate(this.all(), params)
+  }
+}

package/src/store/activity/memory.ts

@@ -0,0 +1,221 @@
+import type { ActivityId, RunId } from '../../types/ids/index.js'
+import type {
+  Activity,
+  ActivityType,
+  ActivityStatus,
+  ActivityProgress,
+  ActivityTrackingConfig,
+} from '../../types/activity/index.js'
+import { isTerminalActivityStatus } from '../../types/activity/index.js'
+import { generateActivityId } from '../../utils/id.js'
+
+export interface ActivityEvent {
+  type: 'activity.created' | 'activity.started' | 'activity.progress' | 'activity.completed' | 'activity.failed' | 'activity.cancelled'
+  activity: Activity
+}
+
+export type ActivityEventListener = (event: ActivityEvent) => void
+
+export class ActivityStore {
+  private activities = new Map<ActivityId, Activity>()
+  private runId: RunId
+  private config: ActivityTrackingConfig
+  private listeners: ActivityEventListener[] = []
+
+  constructor(runId: RunId, config: ActivityTrackingConfig) {
+    this.runId = runId
+    this.config = config
+  }
+
+  get enabled(): boolean {
+    return this.config.enabled
+  }
+
+  on(listener: ActivityEventListener): () => void {
+    this.listeners.push(listener)
+    return () => {
+      this.listeners = this.listeners.filter((l) => l !== listener)
+    }
+  }
+
+  private emit(event: ActivityEvent): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(event)
+      } catch {
+      }
+    }
+  }
+
+  create(params: {
+    type: ActivityType
+    description: string
+    input?: unknown
+    parentActivityId?: ActivityId
+    toolName?: string
+    toolCallId?: string
+    blockedBy?: ActivityId[]
+  }): Activity | null {
+    if (!this.config.enabled) return null
+    if (params.type === 'tool_call' && !this.config.trackToolCalls) return null
+    if (params.type === 'llm_turn' && !this.config.trackLlmTurns) return null
+
+    const activity: Activity = {
+      id: generateActivityId(),
+      runId: this.runId,
+      type: params.type,
+      status: 'pending',
+      description: params.description,
+      input: params.input,
+      parentActivityId: params.parentActivityId,
+      toolName: params.toolName,
+      toolCallId: params.toolCallId,
+      blockedBy: params.blockedBy ?? [],
+      blocks: [],
+      createdAt: Date.now(),
+    }
+
+    this.activities.set(activity.id, activity)
+
+    if (params.blockedBy) {
+      for (const blockerId of params.blockedBy) {
+        const blocker = this.activities.get(blockerId)
+        if (blocker) {
+          blocker.blocks.push(activity.id)
+        }
+      }
+    }
+
+    this.emit({ type: 'activity.created', activity })
+    return activity
+  }
+
+  start(activityId: ActivityId): Activity | null {
+    const activity = this.activities.get(activityId)
+    if (!activity || activity.status !== 'pending') return null
+
+    const unblockedDeps = activity.blockedBy.filter((depId) => {
+      const dep = this.activities.get(depId)
+      return dep && !isTerminalActivityStatus(dep.status)
+    })
+
+    if (unblockedDeps.length > 0) return null
+
+    activity.status = 'running'
+    activity.startedAt = Date.now()
+    this.emit({ type: 'activity.started', activity })
+    return activity
+  }
+
+  updateProgress(activityId: ActivityId, progress: Omit<ActivityProgress, 'updatedAt'>): Activity | null {
+    const activity = this.activities.get(activityId)
+    if (!activity || activity.status !== 'running') return null
+
+    activity.progress = { ...progress, updatedAt: Date.now() }
+    this.emit({ type: 'activity.progress', activity })
+    return activity
+  }
+
+  complete(activityId: ActivityId, output?: unknown): Activity | null {
+    const activity = this.activities.get(activityId)
+    if (!activity || isTerminalActivityStatus(activity.status)) return null
+
+    activity.status = 'completed'
+    activity.output = output
+    activity.completedAt = Date.now()
+    activity.durationMs = activity.startedAt ? activity.completedAt - activity.startedAt : 0
+    this.emit({ type: 'activity.completed', activity })
+    return activity
+  }
+
+  fail(activityId: ActivityId, error: string): Activity | null {
+    const activity = this.activities.get(activityId)
+    if (!activity || isTerminalActivityStatus(activity.status)) return null
+
+    activity.status = 'failed'
+    activity.error = error
+    activity.completedAt = Date.now()
+    activity.durationMs = activity.startedAt ? activity.completedAt - activity.startedAt : 0
+    this.emit({ type: 'activity.failed', activity })
+    return activity
+  }
+
+  cancel(activityId: ActivityId): Activity | null {
+    const activity = this.activities.get(activityId)
+    if (!activity || isTerminalActivityStatus(activity.status)) return null
+
+    activity.status = 'cancelled'
+    activity.completedAt = Date.now()
+    activity.durationMs = activity.startedAt ? activity.completedAt - activity.startedAt : 0
+    this.emit({ type: 'activity.cancelled', activity })
+    return activity
+  }
+
+  get(activityId: ActivityId): Activity | undefined {
+    return this.activities.get(activityId)
+  }
+
+  getByToolCallId(toolCallId: string): Activity | undefined {
+    for (const activity of this.activities.values()) {
+      if (activity.toolCallId === toolCallId) return activity
+    }
+    return undefined
+  }
+
+  list(filter?: { status?: ActivityStatus; type?: ActivityType }): Activity[] {
+    let results = Array.from(this.activities.values())
+
+    if (filter?.status) {
+      results = results.filter((a) => a.status === filter.status)
+    }
+
+    if (filter?.type) {
+      results = results.filter((a) => a.type === filter.type)
+    }
+
+    return results.sort((a, b) => a.createdAt - b.createdAt)
+  }
+
+  getBlockedActivities(): Activity[] {
+    return this.list().filter((activity) => {
+      if (activity.status !== 'pending') return false
+      return activity.blockedBy.some((depId) => {
+        const dep = this.activities.get(depId)
+        return dep && !isTerminalActivityStatus(dep.status)
+      })
+    })
+  }
+
+  getReadyActivities(): Activity[] {
+    return this.list().filter((activity) => {
+      if (activity.status !== 'pending') return false
+      return activity.blockedBy.every((depId) => {
+        const dep = this.activities.get(depId)
+        return !dep || isTerminalActivityStatus(dep.status)
+      })
+    })
+  }
+
+  stats(): {
+    total: number
+    pending: number
+    running: number
+    completed: number
+    failed: number
+    cancelled: number
+  } {
+    const all = this.list()
+    return {
+      total: all.length,
+      pending: all.filter((a) => a.status === 'pending').length,
+      running: all.filter((a) => a.status === 'running').length,
+      completed: all.filter((a) => a.status === 'completed').length,
+      failed: all.filter((a) => a.status === 'failed').length,
+      cancelled: all.filter((a) => a.status === 'cancelled').length,
+    }
+  }
+
+  clear(): void {
+    this.activities.clear()
+  }
+}

package/src/store/conversation/memory.ts

@@ -0,0 +1,107 @@
+import type { ThreadId, RunId, MessageId } from '../../types/ids/index.js'
+import type { Message } from '../../types/message/index.js'
+import { createUserMessage, createAssistantMessage } from '../../types/message/index.js'
+import type { ConversationStore } from '../../types/conversation/index.js'
+import { extractFinalResponse } from '../../utils/conversation.js'
+import { generateMessageId } from '../../utils/id.js'
+
+interface ConversationMessage {
+  readonly id: MessageId
+
+  readonly threadId: ThreadId
+
+  readonly role: 'user' | 'assistant'
+
+  readonly content: string
+
+  readonly runId?: RunId
+
+  readonly createdAt: string
+}
+
+export interface InMemoryConversationStoreConfig {
+  readonly maxMessages?: number
+}
+
+export class InMemoryConversationStore implements ConversationStore {
+  private readonly threads = new Map<ThreadId, ConversationMessage[]>()
+  private readonly maxMessages: number
+
+  constructor(config: InMemoryConversationStoreConfig = {}) {
+    this.maxMessages = config.maxMessages ?? 100
+  }
+
+  loadMessages(threadId: ThreadId): Message[] {
+    const messages = this.threads.get(threadId)
+    if (!messages) return []
+
+    const slice = messages.length > this.maxMessages
+      ? messages.slice(-this.maxMessages)
+      : messages
+
+    return slice.map((m) => {
+      switch (m.role) {
+        case 'user':
+          return createUserMessage(m.content)
+        case 'assistant':
+          return createAssistantMessage(m.content)
+      }
+    })
+  }
+
+  persistRunResult(threadId: ThreadId, runId: RunId, messages: Message[]): void {
+    const finalAssistant = extractFinalResponse(messages)
+    if (!finalAssistant || !finalAssistant.content) return
+
+    this.ensureThread(threadId)
+    this.threads.get(threadId)!.push({
+      id: generateMessageId(),
+      threadId,
+      role: 'assistant',
+      content: finalAssistant.content,
+      runId,
+      createdAt: new Date().toISOString(),
+    })
+  }
+
+  addUserMessage(threadId: ThreadId, content: string): MessageId {
+    this.ensureThread(threadId)
+    const id = generateMessageId()
+    this.threads.get(threadId)!.push({
+      id,
+      threadId,
+      role: 'user',
+      content,
+      createdAt: new Date().toISOString(),
+    })
+    return id
+  }
+
+  hasThread(threadId: ThreadId): boolean {
+    return this.threads.has(threadId)
+  }
+
+  createThread(threadId: ThreadId): boolean {
+    if (this.threads.has(threadId)) return false
+    this.threads.set(threadId, [])
+    return true
+  }
+
+  deleteThread(threadId: ThreadId): boolean {
+    return this.threads.delete(threadId)
+  }
+
+  messageCount(threadId: ThreadId): number {
+    return this.threads.get(threadId)?.length ?? 0
+  }
+
+  clear(): void {
+    this.threads.clear()
+  }
+
+  private ensureThread(threadId: ThreadId): void {
+    if (!this.threads.has(threadId)) {
+      this.threads.set(threadId, [])
+    }
+  }
+}

package/src/store/index.ts

@@ -0,0 +1,14 @@
+export { InMemoryStore } from './InMemoryStore.js'
+export type { Identifiable, Timestamped } from './InMemoryStore.js'
+
+export { RunDiskStore, SessionStore } from './run/disk.js'
+
+export { ActivityStore } from './activity/memory.js'
+export type { ActivityEvent, ActivityEventListener } from './activity/memory.js'
+
+export { InMemoryTaskStore } from './task/memory.js'
+export { DiskTaskStore } from './task/disk.js'
+export type { DiskTaskStoreConfig } from './task/disk.js'
+
+export { InMemoryConversationStore } from './conversation/memory.js'
+export type { InMemoryConversationStoreConfig } from './conversation/memory.js'

package/src/store/run/disk.ts

@@ -0,0 +1,222 @@
+import { appendFile, mkdir, readFile, readdir, rename, unlink, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { AgentRun, RunEvent } from '../../types/run/index.js'
+import type { CheckpointId, IterationCheckpoint } from '../../types/hitl/index.js'
+import type { RunStoreConfig } from '../../types/run/index.js'
+import { getRootLogger, type Logger } from '../../utils/logger.js'
+
+export class RunDiskStore {
+  private baseDir: string
+  private runDir: string | null = null
+  private log: Logger
+  private indexLock: Promise<void> = Promise.resolve()
+
+  constructor(config: RunStoreConfig) {
+    this.baseDir = config.baseDir
+    this.log = (config.logger ?? getRootLogger()).child({ component: 'RunDiskStore' })
+  }
+
+  private requireInit(): string {
+    if (!this.runDir) {
+      throw new Error('RunDiskStore not initialized — call initRun() first')
+    }
+    return this.runDir
+  }
+
+  async initRun(runId: string, parentRunId?: string): Promise<string> {
+    if (parentRunId) {
+      this.runDir = join(this.baseDir, parentRunId, 'children', runId)
+    } else {
+      this.runDir = join(this.baseDir, runId)
+    }
+    await mkdir(this.runDir, { recursive: true })
+    this.log.info(`Run directory created: ${this.runDir}`)
+    return this.runDir
+  }
+
+  async appendEvent(event: RunEvent): Promise<void> {
+    const dir = this.requireInit()
+
+    const line = JSON.stringify({
+      ...event,
+      timestamp: Date.now(),
+    }) + '\n'
+
+    await appendFile(
+      join(dir, 'transcript.jsonl'),
+      line,
+      'utf-8',
+    )
+  }
+
+  async writeRunMeta(run: AgentRun): Promise<void> {
+    const dir = this.requireInit()
+
+    const meta: Record<string, unknown> = {
+      id: run.id,
+      status: run.status,
+      metadata: run.metadata,
+      tokenUsage: run.tokenUsage,
+      currentIteration: run.currentIteration,
+      startedAt: run.startedAt,
+      endedAt: run.endedAt,
+      lastError: run.lastError,
+      messageCount: run.messages.length,
+    }
+
+    if (run.parentRunId) meta.parentRunId = run.parentRunId
+    if (run.depth !== undefined && run.depth > 0) meta.depth = run.depth
+
+    await atomicWriteJson(join(dir, 'run.json'), meta)
+  }
+
+  async writeMessages(run: AgentRun): Promise<void> {
+    const dir = this.requireInit()
+    await atomicWriteJson(join(dir, 'messages.json'), run.messages)
+  }
+
+  async writeReport(content: string): Promise<string> {
+    const dir = this.requireInit()
+
+    const reportPath = join(dir, 'report.md')
+    await atomicWriteFile(reportPath, content)
+    this.log.info(`Report written: ${reportPath}`)
+    return reportPath
+  }
+
+  getRunDir(): string | null {
+    return this.runDir
+  }
+
+  async writeCheckpoint(checkpoint: IterationCheckpoint): Promise<void> {
+    const dir = this.requireInit()
+    const cpDir = join(dir, 'checkpoints')
+    await mkdir(cpDir, { recursive: true })
+    await atomicWriteJson(join(cpDir, `${checkpoint.id}.json`), checkpoint)
+  }
+
+  async readCheckpoint(checkpointId: CheckpointId): Promise<IterationCheckpoint | null> {
+    const dir = this.requireInit()
+    try {
+      const content = await readFile(join(dir, 'checkpoints', `${checkpointId}.json`), 'utf-8')
+      return JSON.parse(content) as IterationCheckpoint
+    } catch {
+      return null
+    }
+  }
+
+  async listCheckpoints(): Promise<IterationCheckpoint[]> {
+    const dir = this.requireInit()
+    const cpDir = join(dir, 'checkpoints')
+    try {
+      const files = await readdir(cpDir)
+      const checkpoints: IterationCheckpoint[] = []
+      for (const file of files) {
+        if (!file.endsWith('.json')) continue
+        try {
+          const content = await readFile(join(cpDir, file), 'utf-8')
+          checkpoints.push(JSON.parse(content) as IterationCheckpoint)
+        } catch {
+          this.log.warn(`Failed to parse checkpoint file: ${file}`)
+        }
+      }
+      return checkpoints.sort((a, b) => a.createdAt - b.createdAt)
+    } catch {
+      return []
+    }
+  }
+
+  async deleteCheckpoint(checkpointId: CheckpointId): Promise<void> {
+    const dir = this.requireInit()
+    try {
+      await unlink(join(dir, 'checkpoints', `${checkpointId}.json`))
+    } catch {
+    }
+  }
+
+  static async listRuns(baseDir: string): Promise<Array<{
+    id: string
+    agentName: string
+    status: string
+    startedAt: number
+    endedAt?: number
+  }>> {
+    try {
+      const indexPath = join(baseDir, 'index.json')
+      const content = await readFile(indexPath, 'utf-8')
+      return JSON.parse(content)
+    } catch {
+      return []
+    }
+  }
+
+  async addToIndex(run: AgentRun): Promise<void> {
+    if (run.parentRunId) return
+
+    const prev = this.indexLock
+    let resolve: () => void
+    this.indexLock = new Promise<void>((r) => { resolve = r })
+
+    try {
+      await prev
+
+      const indexPath = join(this.baseDir, 'index.json')
+      let index: Array<Record<string, unknown>> = []
+
+      try {
+        const content = await readFile(indexPath, 'utf-8')
+        index = JSON.parse(content)
+      } catch (err) {
+        const isNotFound =
+          typeof err === 'object' &&
+          err !== null &&
+          (err as NodeJS.ErrnoException).code === 'ENOENT'
+        if (!isNotFound) {
+          this.log.warn('Failed to read run index — starting fresh', { error: String(err) })
+        }
+      }
+
+      const entry = {
+        id: run.id,
+        agentId: run.metadata.agentId,
+        agentName: run.metadata.agentName,
+        model: run.metadata.config.model,
+        status: run.status,
+        startedAt: run.startedAt,
+        endedAt: run.endedAt,
+        iterations: run.currentIteration,
+        totalTokens: run.tokenUsage.totalTokens,
+      }
+
+      const existingIdx = index.findIndex((e) => e.id === run.id)
+      if (existingIdx >= 0) {
+        index[existingIdx] = entry
+      } else {
+        index.push(entry)
+      }
+
+      await atomicWriteJson(indexPath, index)
+    } finally {
+      resolve!()
+    }
+  }
+}
+
+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))
+}
+
+export const SessionStore = RunDiskStore
+
+export type SessionStore = RunDiskStore