@namzu/sdk 0.1.1

package/src/contracts/api.ts

@@ -0,0 +1,215 @@
+import type { ThreadId, RunId, MessageId, SessionId } from './ids.js'
+import type { MessageRole } from '../types/message/index.js'
+import type { StopReason } from '../types/run/events.js'
+import type { AgentType, AgentCapabilities } from '../types/agent/base.js'
+
+export type { MessageRole, StopReason, AgentType, AgentCapabilities }
+
+export type ISOTimestamp = string
+
+export interface AgentDefaults {
+  model: string
+  temperature?: number
+  tokenBudget: number
+  maxResponseTokens?: number
+  timeoutMs?: number
+}
+
+export interface AgentInfo {
+  id: string
+  name: string
+  version: string
+  category: string
+  description: string
+  tools: string[]
+  defaults: AgentDefaults
+  type?: AgentType
+  capabilities?: AgentCapabilities
+}
+
+export interface Thread {
+  id: ThreadId
+  created_at: ISOTimestamp
+  updated_at: ISOTimestamp
+  metadata: Record<string, string>
+  message_count: number
+}
+
+export interface ToolCallInfo {
+  id: string
+  type: 'function'
+  function: {
+    name: string
+    arguments: string
+  }
+}
+
+export interface ThreadMessage {
+  id: MessageId
+  thread_id: ThreadId
+  role: MessageRole
+  content: string | null
+  created_at: ISOTimestamp
+  run_id?: RunId
+  tool_call_id?: string
+  tool_calls?: ToolCallInfo[]
+  metadata?: Record<string, unknown>
+}
+
+export interface CreateThreadRequest {
+  metadata?: Record<string, string>
+  messages?: CreateMessageRequest[]
+}
+
+export interface CreateMessageRequest {
+  role: 'user'
+  content: string
+  metadata?: Record<string, unknown>
+}
+
+export type RunStatus =
+  | 'queued'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+  | 'cancelling'
+  | 'expired'
+
+export type RunStopReason = StopReason
+
+export interface Run {
+  id: RunId
+  thread_id: ThreadId | null
+  session_id?: SessionId
+  agent_id: string
+  agent_name?: string
+  status: RunStatus
+  stop_reason?: RunStopReason
+  created_at: ISOTimestamp
+  started_at?: ISOTimestamp
+  completed_at?: ISOTimestamp
+  duration_ms?: number
+  model?: string
+  config: RunConfig
+  usage?: RunUsage
+  iterations?: number
+  result?: string
+  last_error?: string
+
+  parent_run_id?: RunId
+
+  depth?: number
+
+  child_run_ids?: RunId[]
+}
+
+export interface RunHierarchyNode {
+  run_id: RunId
+  agent_id: string
+  depth: number
+  status: RunStatus
+  children: RunHierarchyNode[]
+}
+
+export type ApiPermissionMode = 'plan' | 'auto'
+
+export interface RunConfig {
+  model?: string
+  temperature?: number
+  tokenBudget?: number
+  maxResponseTokens?: number
+  timeoutMs?: number
+  permissionMode?: ApiPermissionMode
+
+  systemPrompt?: string
+}
+
+export interface RunUsage {
+  input_tokens: number
+  output_tokens: number
+  total_tokens: number
+  total_cost_usd?: number
+}
+
+export interface CreateRunRequest {
+  agent_id: string
+  config: RunConfig
+  env?: Record<string, string>
+  stream?: boolean
+}
+
+export interface CreateStatelessRunRequest {
+  agent_id: string
+  message: string
+  config: RunConfig
+  env?: Record<string, string>
+}
+
+export type StreamEventType =
+  | 'run.started'
+  | 'run.completed'
+  | 'run.failed'
+  | 'run.cancelled'
+  | 'run.paused'
+  | 'run.resuming'
+  | 'iteration.started'
+  | 'iteration.completed'
+  | 'tool.executing'
+  | 'tool.completed'
+  | 'tool.error'
+  | 'token.usage'
+  | 'message.created'
+  | 'message.delta'
+  | 'message.completed'
+  | 'review.requested'
+  | 'review.completed'
+  | 'checkpoint.created'
+  | 'activity.created'
+  | 'activity.updated'
+  | 'plan.ready'
+  | 'plan.approved'
+  | 'plan.rejected'
+  | 'plan.step_updated'
+  | 'agent.pending'
+  | 'agent.completed'
+  | 'agent.failed'
+  | 'agent.canceled'
+  | 'task.created'
+  | 'task.updated'
+
+export interface StreamEvent {
+  event: StreamEventType
+  data: Record<string, unknown>
+}
+
+export interface PaginationParams {
+  limit?: number
+  after?: string
+  before?: string
+  order?: 'asc' | 'desc'
+}
+
+export interface PaginatedResponse<T> {
+  data: T[]
+  has_more: boolean
+  first_id: string | null
+  last_id: string | null
+}
+
+export type ApiErrorType =
+  | 'validation_error'
+  | 'authentication_error'
+  | 'not_found'
+  | 'conflict'
+  | 'rate_limit_exceeded'
+  | 'internal_error'
+
+export interface ApiError {
+  error: {
+    code: string
+    message: string
+    type: ApiErrorType
+    param?: string
+  }
+}

package/src/contracts/ids.ts

@@ -0,0 +1 @@
+export type { ThreadId, RunId, MessageId, SessionId } from '../types/ids/index.js'

package/src/contracts/index.ts

@@ -0,0 +1,40 @@
+export {
+  type ISOTimestamp,
+  type AgentDefaults,
+  type AgentInfo,
+  type Thread,
+  type ToolCallInfo,
+  type ThreadMessage,
+  type CreateThreadRequest,
+  type CreateMessageRequest,
+  type RunStatus,
+  type RunStopReason,
+  type Run,
+  type RunHierarchyNode,
+  type ApiPermissionMode,
+  type RunConfig,
+  type RunUsage,
+  type CreateRunRequest,
+  type CreateStatelessRunRequest,
+  type StreamEventType,
+  type StreamEvent,
+  type PaginationParams,
+  type PaginatedResponse,
+  type ApiErrorType,
+  type ApiError,
+} from './api.js'
+
+export {
+  ThreadIdSchema,
+  RunIdSchema,
+  MessageIdSchema,
+  RunConfigSchema,
+  CreateMessageSchema,
+  CreateThreadSchema,
+  CreateRunSchema,
+  CreateStatelessRunSchema,
+  PaginationSchema,
+  zodErrorToApiError,
+} from './schemas.js'
+
+export * from './a2a.js'

package/src/contracts/schemas.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod'
+
+export const ThreadIdSchema = z.string().regex(/^thd_[a-z0-9]+$/, 'Invalid thread ID format')
+export const RunIdSchema = z.string().regex(/^run_[a-z0-9]+$/, 'Invalid run ID format')
+export const MessageIdSchema = z.string().regex(/^msg_[a-z0-9]+$/, 'Invalid message ID format')
+
+export const RunConfigSchema = z.object({
+  model: z.string().min(1).optional(),
+  temperature: z.number().min(0).max(2).optional(),
+  tokenBudget: z.number().int().positive().optional(),
+  maxResponseTokens: z.number().int().positive().optional(),
+  timeoutMs: z.number().int().positive().max(3_600_000).optional(),
+  permissionMode: z.enum(['plan', 'auto']).optional(),
+  systemPrompt: z.string().min(1).max(100_000).optional(),
+}).strict()
+
+export const CreateMessageSchema = z.object({
+  role: z.literal('user'),
+  content: z.string().min(1, 'Message content cannot be empty'),
+  metadata: z.record(z.unknown()).optional(),
+}).strict()
+
+export const CreateThreadSchema = z.object({
+  metadata: z.record(z.string()).optional(),
+  messages: z.array(CreateMessageSchema).optional(),
+}).strict()
+
+export const CreateRunSchema = z.object({
+  agent_id: z.string().min(1, 'agent_id is required'),
+  config: RunConfigSchema,
+  env: z.record(z.string()).optional(),
+  stream: z.boolean().optional(),
+}).strict()
+
+export const CreateStatelessRunSchema = z.object({
+  agent_id: z.string().min(1, 'agent_id is required'),
+  message: z.string().min(1, 'message is required'),
+  config: RunConfigSchema,
+  env: z.record(z.string()).optional(),
+}).strict()
+
+export const PaginationSchema = z.object({
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+  after: z.string().optional(),
+  before: z.string().optional(),
+  order: z.enum(['asc', 'desc']).default('desc'),
+})
+
+export function zodErrorToApiError(error: z.ZodError): {
+  code: string
+  message: string
+  type: 'validation_error'
+  param?: string
+} {
+  const firstIssue = error.issues[0]
+  return {
+    code: 'invalid_request',
+    message: firstIssue
+      ? `${firstIssue.path.join('.')}: ${firstIssue.message}`
+      : 'Validation failed',
+    type: 'validation_error',
+    param: firstIssue?.path.join('.') || undefined,
+  }
+}

package/src/execution/base.ts

@@ -0,0 +1,80 @@
+import type {
+  ExecutionEnvironment,
+  ExecutionContextLifecycle,
+} from '../types/execution/index.js'
+import { getRootLogger, type Logger } from '../utils/logger.js'
+import { toErrorMessage } from '../utils/error.js'
+
+export interface BaseExecutionEvent {
+  type: string
+  contextId: string
+  [key: string]: unknown
+}
+
+export type ExecutionEventListener = (event: BaseExecutionEvent) => void
+
+export abstract class BaseExecutionContext implements ExecutionContextLifecycle {
+  abstract readonly id: string
+  abstract readonly environment: ExecutionEnvironment
+
+  protected log: Logger
+  protected ready = false
+  private listeners: ExecutionEventListener[] = []
+
+  constructor() {
+    this.log = getRootLogger().child({ component: this.constructor.name })
+  }
+
+  async initialize(): Promise<void> {
+    try {
+      await this.doInitialize()
+      this.ready = true
+      this.emit({ type: 'context_initialized', contextId: this.id, environment: this.environment })
+      this.emit({ type: 'context_ready', contextId: this.id })
+      this.log.info(`Execution context initialized: ${this.id} (${this.environment})`)
+    } catch (err) {
+      const message = toErrorMessage(err)
+      this.emit({ type: 'context_error', contextId: this.id, error: message })
+      this.log.error(`Execution context initialization failed: ${this.id}`, { error: message })
+      throw err
+    }
+  }
+
+  isReady(): boolean {
+    return this.ready
+  }
+
+  async teardown(): Promise<void> {
+    try {
+      await this.doTeardown()
+    } finally {
+      this.ready = false
+      this.emit({ type: 'context_teardown', contextId: this.id })
+      this.log.info(`Execution context torn down: ${this.id}`)
+    }
+  }
+
+  on(listener: ExecutionEventListener): void {
+    this.listeners.push(listener)
+  }
+
+  off(listener: ExecutionEventListener): void {
+    const index = this.listeners.indexOf(listener)
+    if (index >= 0) this.listeners.splice(index, 1)
+  }
+
+  protected emit(event: BaseExecutionEvent): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(event)
+      } catch (err) {
+        this.log.error('Execution context event listener error', {
+          error: toErrorMessage(err),
+        })
+      }
+    }
+  }
+
+  protected abstract doInitialize(): Promise<void>
+  protected abstract doTeardown(): Promise<void>
+}

package/src/execution/index.ts

@@ -0,0 +1,3 @@
+export { BaseExecutionContext } from './base.js'
+export { LocalExecutionContext } from './local.js'
+export type { LocalExecutionContextOptions } from './local.js'

package/src/execution/local.ts

@@ -0,0 +1,159 @@
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { spawn } from 'node:child_process'
+import type {
+  ExecutionEnvironment,
+  ExecutionCapability,
+  CommandOptions,
+  CommandResult,
+  CommandExecutor,
+} from '../types/execution/index.js'
+import type { LocalExecutionContextConfig } from '../types/connector/index.js'
+import { BaseExecutionContext } from './base.js'
+
+export interface LocalExecutionContextOptions {
+  id: string
+  cwd: string
+  fsAccess?: boolean
+  envVars?: Record<string, string>
+  capabilities?: ExecutionCapability[]
+  shell?: string
+}
+
+export class LocalExecutionContext extends BaseExecutionContext implements CommandExecutor {
+  readonly id: string
+  readonly environment: ExecutionEnvironment = 'local'
+
+  private cwd: string
+  private fsAccess: boolean
+  private envVars: Record<string, string>
+  private capabilities: ExecutionCapability[]
+  private shell: string | undefined
+
+  constructor(options: LocalExecutionContextOptions) {
+    super()
+    this.id = options.id
+    this.cwd = resolve(options.cwd)
+    this.fsAccess = options.fsAccess ?? true
+    this.envVars = options.envVars ?? {}
+    this.capabilities = options.capabilities ?? ['filesystem', 'process', 'shell']
+    this.shell = options.shell
+  }
+
+  protected async doInitialize(): Promise<void> {
+    if (!existsSync(this.cwd)) {
+      throw new Error(`Working directory does not exist: ${this.cwd}`)
+    }
+    this.log.info(`Local context initialized at ${this.cwd}`)
+  }
+
+  protected async doTeardown(): Promise<void> {
+  }
+
+  getCwd(): string {
+    return this.cwd
+  }
+
+  setCwd(newCwd: string): void {
+    const resolved = resolve(newCwd)
+    if (!existsSync(resolved)) {
+      throw new Error(`Working directory does not exist: ${resolved}`)
+    }
+    this.cwd = resolved
+  }
+
+  hasFsAccess(): boolean {
+    return this.fsAccess
+  }
+
+  resolvePath(relativePath: string): string {
+    return resolve(this.cwd, relativePath)
+  }
+
+  getEnvVar(key: string): string | undefined {
+    return this.envVars[key] ?? process.env[key]
+  }
+
+  getEnvVars(): Record<string, string> {
+    return { ...this.envVars }
+  }
+
+  getCapabilities(): ExecutionCapability[] {
+    return [...this.capabilities]
+  }
+
+  hasCapability(cap: ExecutionCapability): boolean {
+    return this.capabilities.includes(cap)
+  }
+
+  async executeCommand(
+    command: string,
+    args: string[] = [],
+    options?: CommandOptions,
+  ): Promise<CommandResult> {
+    if (!this.hasCapability('process') && !this.hasCapability('shell')) {
+      return {
+        exitCode: 1,
+        stdout: '',
+        stderr: 'Command execution not available: context lacks process/shell capability',
+        durationMs: 0,
+      }
+    }
+
+    const cwd = options?.cwd ? resolve(this.cwd, options.cwd) : this.cwd
+    const env = { ...process.env, ...this.envVars, ...options?.env }
+    const timeoutMs = options?.timeoutMs ?? 30_000
+    const shell = options?.shell ?? this.shell ?? true
+
+    return new Promise<CommandResult>((resolvePromise) => {
+      const start = performance.now()
+      const proc = spawn(command, args, {
+        cwd,
+        env,
+        shell,
+        timeout: timeoutMs,
+      })
+
+      let stdout = ''
+      let stderr = ''
+
+      proc.stdout?.on('data', (data: Buffer) => {
+        stdout += data.toString()
+      })
+
+      proc.stderr?.on('data', (data: Buffer) => {
+        stderr += data.toString()
+      })
+
+      proc.on('close', (code) => {
+        resolvePromise({
+          exitCode: code ?? 1,
+          stdout,
+          stderr,
+          durationMs: Math.round(performance.now() - start),
+        })
+      })
+
+      proc.on('error', (err) => {
+        resolvePromise({
+          exitCode: 1,
+          stdout,
+          stderr: err.message,
+          durationMs: Math.round(performance.now() - start),
+        })
+      })
+    })
+  }
+
+  toConfig(): LocalExecutionContextConfig {
+    return {
+      id: this.id,
+      environment: 'local',
+      cwd: this.cwd,
+      fsAccess: this.fsAccess,
+      envVars: this.envVars,
+      capabilities: this.capabilities,
+      shell: this.shell,
+    }
+  }
+}

package/src/gateway/local.ts

@@ -0,0 +1,112 @@
+import type { AgentManager } from '../manager/agent/lifecycle.js'
+import type { AgentTaskContext } from '../types/agent/task.js'
+import type { AgentInput } from '../types/agent/base.js'
+import type {
+  TaskGateway,
+  TaskHandle,
+  CreateTaskOptions,
+} from '../types/agent/gateway.js'
+import type { RunEventListener } from '../types/run/events.js'
+import type { TaskId } from '../types/ids/index.js'
+import { createUserMessage } from '../types/message/index.js'
+
+export class LocalTaskGateway implements TaskGateway {
+  private agentManager: AgentManager
+  private taskContext: AgentTaskContext
+  private listener: RunEventListener | undefined
+  private trackedTaskIds: Set<TaskId> = new Set()
+
+  private parentInput?: Pick<AgentInput, 'taskStore' | 'runtimeToolOverrides'>
+
+  private completionListeners: Set<(handle: TaskHandle) => void> = new Set()
+
+  constructor(
+    agentManager: AgentManager,
+    taskContext: AgentTaskContext,
+    listener?: RunEventListener,
+    parentInput?: Pick<AgentInput, 'taskStore' | 'runtimeToolOverrides'>,
+  ) {
+    this.agentManager = agentManager
+    this.taskContext = taskContext
+    this.listener = listener
+    this.parentInput = parentInput
+  }
+
+  async createTask(options: CreateTaskOptions): Promise<TaskHandle> {
+    const task = await this.agentManager.sendMessage(
+      {
+        agentId: options.agentId,
+        input: {
+          messages: [createUserMessage(options.prompt)],
+          workingDirectory: options.workingDirectory,
+          taskStore: this.parentInput?.taskStore,
+          runtimeToolOverrides: this.parentInput?.runtimeToolOverrides,
+        },
+      },
+      { ...this.taskContext, budgetTracker: { ...this.taskContext.budgetTracker } },
+      this.listener,
+    )
+
+    this.trackedTaskIds.add(task.taskId)
+
+    this.agentManager.waitForCompletion(task.taskId).then(() => {
+      const completed = this.agentManager.getInstance(task.taskId)
+      if (completed) {
+        const handle = toHandle(completed)
+        for (const cb of this.completionListeners) {
+          cb(handle)
+        }
+      }
+    }).catch(() => {
+    })
+
+    return toHandle(task)
+  }
+
+  async waitForTask(taskId: TaskId): Promise<TaskHandle> {
+    await this.agentManager.waitForCompletion(taskId)
+    const task = this.agentManager.getInstance(taskId)
+    if (!task) {
+      throw new Error(`Task ${taskId} not found after completion`)
+    }
+    return toHandle(task)
+  }
+
+  async continueTask(taskId: TaskId, message: string): Promise<void> {
+    await this.agentManager.continueTask(taskId, message)
+  }
+
+  cancelTask(taskId: TaskId): void {
+    this.agentManager.cancel(taskId)
+  }
+
+  getTask(taskId: TaskId): TaskHandle | undefined {
+    const task = this.agentManager.getInstance(taskId)
+    return task ? toHandle(task) : undefined
+  }
+
+  listTasks(): TaskHandle[] {
+    const handles: TaskHandle[] = []
+    for (const taskId of this.trackedTaskIds) {
+      const task = this.agentManager.getInstance(taskId)
+      if (task) handles.push(toHandle(task))
+    }
+    return handles
+  }
+
+  onTaskCompleted(callback: (handle: TaskHandle) => void): () => void {
+    this.completionListeners.add(callback)
+    return () => { this.completionListeners.delete(callback) }
+  }
+}
+
+function toHandle(task: import('../types/agent/task.js').AgentTask): TaskHandle {
+  return {
+    taskId: task.taskId,
+    agentId: task.agentId,
+    state: task.state,
+    result: task.result,
+    createdAt: task.createdAt,
+    completedAt: task.completedAt,
+  }
+}