@namzu/sdk 0.1.1

package/src/store/task/disk.ts

@@ -0,0 +1,333 @@
+import { mkdir, readFile, readdir, rename, unlink, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { TaskId, RunId, TenantId } from '../../types/ids/index.js'
+import type {
+  Task,
+  TaskStatus,
+  TaskStore,
+  TaskEvent,
+  TaskEventListener,
+  CreateTaskParams,
+  UpdateTaskParams,
+} from '../../types/task/index.js'
+import { generateTaskId } from '../../utils/id.js'
+import { getRootLogger, type Logger } from '../../utils/logger.js'
+
+export interface DiskTaskStoreConfig {
+  baseDir: string
+
+  defaultRunId: RunId
+
+  tenantId?: TenantId
+
+  logger?: Logger
+}
+
+const STATUS_ORDER: Record<TaskStatus, number> = {
+  pending: 0,
+  in_progress: 1,
+  completed: 2,
+}
+
+function isForwardTransition(from: TaskStatus, to: TaskStatus): boolean {
+  return STATUS_ORDER[to] > STATUS_ORDER[from]
+}
+
+export class DiskTaskStore implements TaskStore {
+  private baseDir: string
+  private defaultRunId: RunId
+  private tenantId?: TenantId
+  private log: Logger
+  private listeners: TaskEventListener[] = []
+
+  private locks = new Map<TaskId, Promise<void>>()
+
+  constructor(config: DiskTaskStoreConfig) {
+    this.baseDir = config.baseDir
+    this.defaultRunId = config.defaultRunId
+    this.tenantId = config.tenantId
+    this.log = (config.logger ?? getRootLogger()).child({ component: 'DiskTaskStore' })
+  }
+
+  private taskDir(runId: RunId): string {
+    if (this.tenantId) {
+      return join(this.baseDir, 'tenants', this.tenantId, 'tasks', runId)
+    }
+    return join(this.baseDir, 'tasks', runId)
+  }
+
+  private taskPath(runId: RunId, taskId: TaskId): string {
+    return join(this.taskDir(runId), `${taskId}.json`)
+  }
+
+  private async withLock<T>(taskId: TaskId, fn: () => Promise<T>): Promise<T> {
+    const existing = this.locks.get(taskId)
+    if (existing) {
+      await existing.catch(() => undefined)
+    }
+
+    let resolve: () => void
+    const lock = new Promise<void>((r) => { resolve = r })
+    this.locks.set(taskId, lock)
+
+    try {
+      return await fn()
+    } finally {
+      resolve!()
+      if (this.locks.get(taskId) === lock) {
+        this.locks.delete(taskId)
+      }
+    }
+  }
+
+  on(listener: TaskEventListener): () => void {
+    this.listeners.push(listener)
+    return () => {
+      this.listeners = this.listeners.filter((l) => l !== listener)
+    }
+  }
+
+  private emit(event: TaskEvent): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(event)
+      } catch {
+      }
+    }
+  }
+
+  async create(params: CreateTaskParams): Promise<Task> {
+    const taskId = generateTaskId()
+    const runId = params.runId ?? this.defaultRunId
+
+    const task: Task = {
+      id: taskId,
+      runId,
+      tenantId: params.tenantId ?? this.tenantId,
+      subject: params.subject,
+      description: params.description,
+      activeForm: params.activeForm,
+      status: 'pending',
+      owner: params.owner,
+      blocks: [],
+      blockedBy: params.blockedBy ? [...params.blockedBy] : [],
+      metadata: params.metadata ? { ...params.metadata } : undefined,
+      createdAt: Date.now(),
+    }
+
+    const dir = this.taskDir(runId)
+    await mkdir(dir, { recursive: true })
+    await atomicWriteJson(this.taskPath(runId, taskId), task)
+
+    if (params.blockedBy) {
+      for (const blockerId of params.blockedBy) {
+        await this.withLock(blockerId, async () => {
+          const blocker = await this.readTask(runId, blockerId)
+          if (blocker && !blocker.blocks.includes(taskId)) {
+            blocker.blocks.push(taskId)
+            await atomicWriteJson(this.taskPath(runId, blockerId), blocker)
+          }
+        })
+      }
+    }
+
+    this.log.info('Task created', { taskId, subject: params.subject, runId })
+    this.emit({ type: 'task.created', taskId, task, timestamp: Date.now() })
+    return task
+  }
+
+  async get(id: TaskId): Promise<Task | undefined> {
+    return this.findTask(id)
+  }
+
+  async update(id: TaskId, updates: UpdateTaskParams): Promise<Task | undefined> {
+    const found = await this.findTask(id)
+    if (!found) return undefined
+
+    return this.withLock(id, async () => {
+      const task = await this.readTask(found.runId, id)
+      if (!task) return undefined
+
+      const previousStatus = task.status
+
+      if (updates.subject !== undefined) task.subject = updates.subject
+      if (updates.description !== undefined) task.description = updates.description
+      if (updates.activeForm !== undefined) task.activeForm = updates.activeForm
+      if (updates.owner !== undefined) task.owner = updates.owner
+      if (updates.metadata !== undefined) {
+        task.metadata = task.metadata
+          ? { ...task.metadata, ...updates.metadata }
+          : { ...updates.metadata }
+      }
+
+      if (updates.status !== undefined && updates.status !== previousStatus
+          && isForwardTransition(previousStatus, updates.status)) {
+        task.status = updates.status
+        if (updates.status === 'in_progress' && !task.startedAt) {
+          task.startedAt = Date.now()
+        }
+        if (updates.status === 'completed') {
+          task.completedAt = Date.now()
+        }
+      }
+
+      await atomicWriteJson(this.taskPath(task.runId, id), task)
+      this.emit({ type: 'task.updated', taskId: id, task, previousStatus, timestamp: Date.now() })
+      return task
+    })
+  }
+
+  async delete(id: TaskId): Promise<boolean> {
+    const found = await this.findTask(id)
+    if (!found) return false
+
+    return this.withLock(id, async () => {
+      const task = await this.readTask(found.runId, id)
+      if (!task) return false
+
+      for (const blockerId of task.blockedBy) {
+        await this.withLock(blockerId, async () => {
+          const blocker = await this.readTask(task.runId, blockerId)
+          if (blocker) {
+            blocker.blocks = blocker.blocks.filter((bid) => bid !== id)
+            await atomicWriteJson(this.taskPath(task.runId, blockerId), blocker)
+          }
+        })
+      }
+      for (const blockedId of task.blocks) {
+        await this.withLock(blockedId, async () => {
+          const blocked = await this.readTask(task.runId, blockedId)
+          if (blocked) {
+            blocked.blockedBy = blocked.blockedBy.filter((bid) => bid !== id)
+            await atomicWriteJson(this.taskPath(task.runId, blockedId), blocked)
+          }
+        })
+      }
+
+      await unlink(this.taskPath(task.runId, id)).catch(() => undefined)
+      this.log.info('Task deleted', { taskId: id })
+      this.emit({ type: 'task.deleted', taskId: id, task, timestamp: Date.now() })
+      return true
+    })
+  }
+
+  async list(filter?: { status?: TaskStatus; owner?: string; runId?: RunId }): Promise<Task[]> {
+    const runId = filter?.runId ?? this.defaultRunId
+    const dir = this.taskDir(runId)
+
+    let files: string[]
+    try {
+      files = await readdir(dir)
+    } catch {
+      return []
+    }
+
+    const tasks: Task[] = []
+    for (const file of files) {
+      if (!file.endsWith('.json')) continue
+      try {
+        const raw = await readFile(join(dir, file), 'utf-8')
+        const task = JSON.parse(raw) as Task
+        tasks.push(task)
+      } catch {
+        this.log.warn('Failed to read task file', { file })
+      }
+    }
+
+    let results = tasks
+    if (filter?.status) {
+      results = results.filter((t) => t.status === filter.status)
+    }
+    if (filter?.owner) {
+      results = results.filter((t) => t.owner === filter.owner)
+    }
+
+    return results.sort((a, b) => a.createdAt - b.createdAt)
+  }
+
+  async claim(id: TaskId, owner: string): Promise<Task | undefined> {
+    const found = await this.findTask(id)
+    if (!found) return undefined
+
+    return this.withLock(id, async () => {
+      const task = await this.readTask(found.runId, id)
+      if (!task) return undefined
+      if (task.status !== 'pending') return undefined
+      if (task.owner !== undefined) return undefined
+
+      task.owner = owner
+      task.status = 'in_progress'
+      task.startedAt = Date.now()
+
+      await atomicWriteJson(this.taskPath(task.runId, id), task)
+      this.emit({ type: 'task.claimed', taskId: id, task, timestamp: Date.now() })
+      return task
+    })
+  }
+
+  async block(blockerId: TaskId, blockedId: TaskId): Promise<void> {
+    const blockerFound = await this.findTask(blockerId)
+    const blockedFound = await this.findTask(blockedId)
+    if (!blockerFound || !blockedFound) return
+
+    await this.withLock(blockerId, async () => {
+      const blocker = await this.readTask(blockerFound.runId, blockerId)
+      if (blocker && !blocker.blocks.includes(blockedId)) {
+        blocker.blocks.push(blockedId)
+        await atomicWriteJson(this.taskPath(blocker.runId, blockerId), blocker)
+      }
+    })
+
+    await this.withLock(blockedId, async () => {
+      const blocked = await this.readTask(blockedFound.runId, blockedId)
+      if (blocked && !blocked.blockedBy.includes(blockerId)) {
+        blocked.blockedBy.push(blockerId)
+        await atomicWriteJson(this.taskPath(blocked.runId, blockedId), blocked)
+      }
+    })
+  }
+
+  async reset(): Promise<void> {
+    const dir = this.taskDir(this.defaultRunId)
+    let files: string[]
+    try {
+      files = await readdir(dir)
+    } catch {
+      return
+    }
+    for (const file of files) {
+      if (file.endsWith('.json')) {
+        await unlink(join(dir, file)).catch(() => undefined)
+      }
+    }
+  }
+
+  private async readTask(runId: RunId, taskId: TaskId): Promise<Task | null> {
+    try {
+      const raw = await readFile(this.taskPath(runId, taskId), 'utf-8')
+      return JSON.parse(raw) as Task
+    } catch {
+      return null
+    }
+  }
+
+  private async findTask(id: TaskId): Promise<Task | undefined> {
+    const task = await this.readTask(this.defaultRunId, id)
+    return task ?? undefined
+  }
+}
+
+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/task/memory.ts

@@ -0,0 +1,183 @@
+import type { TaskId, RunId } from '../../types/ids/index.js'
+import type {
+  Task,
+  TaskStatus,
+  TaskStore,
+  TaskEvent,
+  TaskEventListener,
+  CreateTaskParams,
+  UpdateTaskParams,
+} from '../../types/task/index.js'
+import { generateTaskId } from '../../utils/id.js'
+
+const STATUS_ORDER: Record<TaskStatus, number> = {
+  pending: 0,
+  in_progress: 1,
+  completed: 2,
+}
+
+function isForwardTransition(from: TaskStatus, to: TaskStatus): boolean {
+  return STATUS_ORDER[to] > STATUS_ORDER[from]
+}
+
+export class InMemoryTaskStore implements TaskStore {
+  private tasks = new Map<TaskId, Task>()
+  private listeners: TaskEventListener[] = []
+
+  on(listener: TaskEventListener): () => void {
+    this.listeners.push(listener)
+    return () => {
+      this.listeners = this.listeners.filter((l) => l !== listener)
+    }
+  }
+
+  private emit(event: TaskEvent): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(event)
+      } catch {
+      }
+    }
+  }
+
+  async create(params: CreateTaskParams): Promise<Task> {
+    const task: Task = {
+      id: generateTaskId(),
+      runId: params.runId,
+      tenantId: params.tenantId,
+      subject: params.subject,
+      description: params.description,
+      activeForm: params.activeForm,
+      status: 'pending',
+      owner: params.owner,
+      blocks: [],
+      blockedBy: params.blockedBy ? [...params.blockedBy] : [],
+      metadata: params.metadata ? { ...params.metadata } : undefined,
+      createdAt: Date.now(),
+    }
+
+    this.tasks.set(task.id, task)
+
+    if (params.blockedBy) {
+      for (const blockerId of params.blockedBy) {
+        const blocker = this.tasks.get(blockerId)
+        if (blocker) {
+          blocker.blocks.push(task.id)
+        }
+      }
+    }
+
+    this.emit({ type: 'task.created', taskId: task.id, task, timestamp: Date.now() })
+    return task
+  }
+
+  async get(id: TaskId): Promise<Task | undefined> {
+    return this.tasks.get(id)
+  }
+
+  async update(id: TaskId, updates: UpdateTaskParams): Promise<Task | undefined> {
+    const task = this.tasks.get(id)
+    if (!task) return undefined
+
+    const previousStatus = task.status
+
+    if (updates.subject !== undefined) task.subject = updates.subject
+    if (updates.description !== undefined) task.description = updates.description
+    if (updates.activeForm !== undefined) task.activeForm = updates.activeForm
+    if (updates.owner !== undefined) task.owner = updates.owner
+    if (updates.metadata !== undefined) {
+      task.metadata = task.metadata
+        ? { ...task.metadata, ...updates.metadata }
+        : { ...updates.metadata }
+    }
+
+    if (updates.status !== undefined && updates.status !== previousStatus
+        && isForwardTransition(previousStatus, updates.status)) {
+      task.status = updates.status
+      if (updates.status === 'in_progress' && !task.startedAt) {
+        task.startedAt = Date.now()
+      }
+      if (updates.status === 'completed') {
+        task.completedAt = Date.now()
+      }
+    }
+
+    this.emit({
+      type: 'task.updated',
+      taskId: task.id,
+      task,
+      previousStatus,
+      timestamp: Date.now(),
+    })
+    return task
+  }
+
+  async delete(id: TaskId): Promise<boolean> {
+    const task = this.tasks.get(id)
+    if (!task) return false
+
+    for (const blockerId of task.blockedBy) {
+      const blocker = this.tasks.get(blockerId)
+      if (blocker) {
+        blocker.blocks = blocker.blocks.filter((bid) => bid !== id)
+      }
+    }
+    for (const blockedId of task.blocks) {
+      const blocked = this.tasks.get(blockedId)
+      if (blocked) {
+        blocked.blockedBy = blocked.blockedBy.filter((bid) => bid !== id)
+      }
+    }
+
+    this.tasks.delete(id)
+    this.emit({ type: 'task.deleted', taskId: id, task, timestamp: Date.now() })
+    return true
+  }
+
+  async list(filter?: { status?: TaskStatus; owner?: string; runId?: RunId }): Promise<Task[]> {
+    let results = Array.from(this.tasks.values())
+
+    if (filter?.status) {
+      results = results.filter((t) => t.status === filter.status)
+    }
+    if (filter?.owner) {
+      results = results.filter((t) => t.owner === filter.owner)
+    }
+    if (filter?.runId) {
+      results = results.filter((t) => t.runId === filter.runId)
+    }
+
+    return results.sort((a, b) => a.createdAt - b.createdAt)
+  }
+
+  async claim(id: TaskId, owner: string): Promise<Task | undefined> {
+    const task = this.tasks.get(id)
+    if (!task) return undefined
+    if (task.status !== 'pending') return undefined
+    if (task.owner !== undefined) return undefined
+
+    task.owner = owner
+    task.status = 'in_progress'
+    task.startedAt = Date.now()
+
+    this.emit({ type: 'task.claimed', taskId: task.id, task, timestamp: Date.now() })
+    return task
+  }
+
+  async block(blockerId: TaskId, blockedId: TaskId): Promise<void> {
+    const blocker = this.tasks.get(blockerId)
+    const blocked = this.tasks.get(blockedId)
+    if (!blocker || !blocked) return
+
+    if (!blocker.blocks.includes(blockedId)) {
+      blocker.blocks.push(blockedId)
+    }
+    if (!blocked.blockedBy.includes(blockerId)) {
+      blocked.blockedBy.push(blockerId)
+    }
+  }
+
+  async reset(): Promise<void> {
+    this.tasks.clear()
+  }
+}

package/src/telemetry/attributes.ts

@@ -0,0 +1,50 @@
+export const GENAI = {
+  OPERATION_NAME: 'gen_ai.operation.name',
+  SYSTEM: 'gen_ai.system',
+
+  REQUEST_MODEL: 'gen_ai.request.model',
+  REQUEST_TEMPERATURE: 'gen_ai.request.temperature',
+  REQUEST_MAX_TOKENS: 'gen_ai.request.max_tokens',
+
+  RESPONSE_MODEL: 'gen_ai.response.model',
+  RESPONSE_FINISH_REASONS: 'gen_ai.response.finish_reasons',
+  RESPONSE_ID: 'gen_ai.response.id',
+
+  USAGE_INPUT_TOKENS: 'gen_ai.usage.input_tokens',
+  USAGE_OUTPUT_TOKENS: 'gen_ai.usage.output_tokens',
+
+  TOOL_NAME: 'gen_ai.tool.name',
+  TOOL_TYPE: 'gen_ai.tool.type',
+  TOOL_CALL_ID: 'gen_ai.tool.call_id',
+
+  AGENT_NAME: 'gen_ai.agent.name',
+  AGENT_ID: 'gen_ai.agent.id',
+} as const
+
+export const NAMZU = {
+  SESSION_ID: 'namzu.session.id',
+  SESSION_STATUS: 'namzu.session.status',
+  ITERATION: 'namzu.iteration',
+  TOOL_SUCCESS: 'namzu.tool.success',
+  TOOL_ERROR: 'namzu.tool.error',
+  COST_TOTAL: 'namzu.cost.total',
+  CACHE_READ_TOKENS: 'namzu.cache.read_tokens',
+  CACHE_WRITE_TOKENS: 'namzu.cache.write_tokens',
+  CACHE_DISCOUNT: 'namzu.cache.discount',
+} as const
+
+export function agentSessionSpanName(agentName: string): string {
+  return `namzu.agent.session ${agentName}`
+}
+
+export function agentIterationSpanName(iteration: number): string {
+  return `namzu.agent.iteration ${iteration}`
+}
+
+export function chatSpanName(model: string): string {
+  return `chat ${model}`
+}
+
+export function toolSpanName(toolName: string): string {
+  return `namzu.tool.execute ${toolName}`
+}

package/src/telemetry/index.ts

@@ -0,0 +1,14 @@
+export {
+  TelemetryProvider,
+  initTelemetry,
+  getTelemetry,
+  getTracer,
+  getMeter,
+} from '../provider/telemetry/setup.js'
+
+export type { TelemetryConfig, ExporterType } from '../types/telemetry/index.js'
+
+export { createPlatformMetrics } from './metrics.js'
+export type { PlatformMetrics } from './metrics.js'
+
+export * from './attributes.js'

package/src/telemetry/metrics.ts

@@ -0,0 +1,70 @@
+import { getMeter } from '../provider/telemetry/setup.js'
+import type { Counter, Histogram } from '@opentelemetry/api'
+
+export interface PlatformMetrics {
+  recordTokenUsage(model: string, inputTokens: number, outputTokens: number): void
+  recordToolCall(toolName: string, success: boolean): void
+  recordSessionDuration(status: string, durationSec: number): void
+  recordLLMLatency(model: string, durationSec: number): void
+}
+
+export function createPlatformMetrics(): PlatformMetrics {
+  const meter = getMeter()
+
+  const tokenInputCounter = meter.createCounter('gen_ai.client.token.usage', {
+    description: 'Number of input (prompt) tokens used',
+    unit: '{token}',
+  })
+
+  const tokenOutputCounter = meter.createCounter('gen_ai.client.token.usage.output', {
+    description: 'Number of output (completion) tokens used',
+    unit: '{token}',
+  })
+
+  const toolCallCounter = meter.createCounter('gen_ai.tool.call.count', {
+    description: 'Number of tool calls executed',
+    unit: '{call}',
+  })
+
+  const sessionDurationHistogram = meter.createHistogram('namzu.session.duration', {
+    description: 'Agent session duration',
+    unit: 's',
+  })
+
+  const llmLatencyHistogram = meter.createHistogram('gen_ai.client.operation.duration', {
+    description: 'LLM request duration (GenAI semantic convention)',
+    unit: 's',
+  })
+
+  return {
+    recordTokenUsage(model: string, inputTokens: number, outputTokens: number): void {
+      tokenInputCounter.add(inputTokens, {
+        'gen_ai.request.model': model,
+        'gen_ai.token.type': 'input',
+      })
+      tokenOutputCounter.add(outputTokens, {
+        'gen_ai.request.model': model,
+        'gen_ai.token.type': 'output',
+      })
+    },
+
+    recordToolCall(toolName: string, success: boolean): void {
+      toolCallCounter.add(1, {
+        'gen_ai.tool.name': toolName,
+        'namzu.tool.success': success,
+      })
+    },
+
+    recordSessionDuration(status: string, durationSec: number): void {
+      sessionDurationHistogram.record(durationSec, {
+        'namzu.session.status': status,
+      })
+    },
+
+    recordLLMLatency(model: string, durationSec: number): void {
+      llmLatencyHistogram.record(durationSec, {
+        'gen_ai.request.model': model,
+      })
+    },
+  }
+}