@namzu/sdk 0.1.1

package/src/tools/task/list.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod'
+import type { TaskStore } from '../../types/task/index.js'
+import type { RunId } from '../../types/ids/index.js'
+import type { ToolDefinition } from '../../types/tool/index.js'
+import { isTerminalTaskStatus } from '../../types/task/index.js'
+import { defineTool } from '../defineTool.js'
+
+export function buildTaskListTool(
+  taskStore: TaskStore,
+  runId: RunId,
+): ToolDefinition {
+  return defineTool({
+    name: 'task_list',
+    description: 'List all tasks for the current run. Shows subject, status, owner, and unresolved blockers. Use this to review your plan and decide what to work on next.',
+    inputSchema: z.object({}),
+    category: 'custom',
+    permissions: [],
+    readOnly: true,
+    destructive: false,
+    concurrencySafe: true,
+    async execute() {
+      const tasks = await taskStore.list({ runId })
+
+      const completedIds = new Set(
+        tasks
+          .filter((t) => isTerminalTaskStatus(t.status))
+          .map((t) => t.id),
+      )
+
+      const summary = tasks.map((task) => {
+        const unresolvedBlockers = task.blockedBy.filter((bid) => !completedIds.has(bid))
+
+        return {
+          id: task.id,
+          subject: task.subject,
+          status: task.status,
+          owner: task.owner ?? null,
+          blockedBy: unresolvedBlockers.length > 0 ? unresolvedBlockers : undefined,
+          activeForm: task.status === 'in_progress' ? task.activeForm : undefined,
+        }
+      })
+
+      const stats = {
+        total: tasks.length,
+        pending: tasks.filter((t) => t.status === 'pending').length,
+        in_progress: tasks.filter((t) => t.status === 'in_progress').length,
+        completed: tasks.filter((t) => t.status === 'completed').length,
+      }
+
+      return {
+        success: true,
+        output: tasks.length === 0
+          ? 'No tasks yet.'
+          : `${stats.total} tasks: ${stats.completed} completed, ${stats.in_progress} in progress, ${stats.pending} pending.`,
+        data: { tasks: summary, stats },
+      }
+    },
+  })
+}

package/src/tools/task/update.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod'
+import type { TaskStore } from '../../types/task/index.js'
+import type { TaskId } from '../../types/ids/index.js'
+import type { ToolDefinition } from '../../types/tool/index.js'
+import { defineTool } from '../defineTool.js'
+
+export function buildTaskUpdateTool(
+  taskStore: TaskStore,
+): ToolDefinition {
+  return defineTool({
+    name: 'task_update',
+    description: 'Update an existing task. Change its status (pending → in_progress → completed), edit its description, transfer ownership, or manage dependencies. Use status "deleted" to remove a task entirely.',
+    inputSchema: z.object({
+      id: z.string().describe('Task ID (e.g. "task_abc123")'),
+      subject: z.string().optional().describe('Updated title'),
+      description: z.string().optional().describe('Updated description'),
+      activeForm: z.string().optional().describe('Updated present continuous form'),
+      status: z.enum(['pending', 'in_progress', 'completed', 'deleted']).optional().describe('New status'),
+      owner: z.string().optional().describe('Agent name to assign ownership'),
+      addBlocks: z.array(z.string()).optional().describe('Task IDs that this task should now block'),
+      addBlockedBy: z.array(z.string()).optional().describe('Task IDs that should now block this task'),
+      metadata: z.record(z.string(), z.unknown()).optional().describe('Metadata to merge'),
+    }),
+    category: 'custom',
+    permissions: [],
+    readOnly: false,
+    destructive: false,
+    concurrencySafe: true,
+    async execute({ id, subject, description, activeForm, status, owner, addBlocks, addBlockedBy, metadata }) {
+      const taskId = id as TaskId
+
+      if (status === 'deleted') {
+        const deleted = await taskStore.delete(taskId)
+        return {
+          success: deleted,
+          output: deleted ? `Task ${id} deleted` : `Task ${id} not found`,
+        }
+      }
+
+      if (addBlocks) {
+        for (const blockedId of addBlocks) {
+          await taskStore.block(taskId, blockedId as TaskId)
+        }
+      }
+      if (addBlockedBy) {
+        for (const blockerId of addBlockedBy) {
+          await taskStore.block(blockerId as TaskId, taskId)
+        }
+      }
+
+      const updated = await taskStore.update(taskId, {
+        subject,
+        description,
+        activeForm,
+        status: status as 'pending' | 'in_progress' | 'completed' | undefined,
+        owner,
+        metadata,
+      })
+
+      if (!updated) {
+        return { success: false, output: `Task ${id} not found` }
+      }
+
+      return {
+        success: true,
+        output: `Task ${id} updated — status: ${updated.status}`,
+        data: { id: updated.id, status: updated.status, owner: updated.owner },
+      }
+    },
+  })
+}

package/src/types/a2a/index.ts

@@ -0,0 +1,239 @@
+export type A2ATaskState =
+  | 'pending'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'canceled'
+  | 'rejected'
+  | 'input-required'
+
+export type A2APartKind = 'text' | 'file' | 'data'
+
+export type A2AMessageRole = 'user' | 'agent'
+
+export type A2ATransport = 'jsonrpc' | 'rest' | 'grpc'
+
+export type A2AMethod =
+  | 'message/send'
+  | 'message/sendStreaming'
+  | 'tasks/get'
+  | 'tasks/list'
+  | 'tasks/cancel'
+  | 'tasks/subscribe'
+  | 'tasks/pushNotification/set'
+  | 'tasks/pushNotification/get'
+  | 'tasks/pushNotification/list'
+  | 'tasks/pushNotification/delete'
+  | 'agent/card'
+
+export type A2AErrorCode =
+  | 'TaskNotFound'
+  | 'TaskNotCancelable'
+  | 'ContentTypeNotSupported'
+  | 'UnsupportedOperation'
+  | 'PushNotificationNotSupported'
+  | 'InvalidRequest'
+  | 'InternalError'
+  | 'Unauthorized'
+
+export interface TextPart {
+  readonly kind: 'text'
+  readonly text: string
+  readonly metadata?: Record<string, unknown>
+}
+
+export interface FilePart {
+  readonly kind: 'file'
+  readonly file: {
+    readonly uri: string
+    readonly mimeType: string
+    readonly name?: string
+
+    readonly bytes?: string
+  }
+  readonly metadata?: Record<string, unknown>
+}
+
+export interface DataPart {
+  readonly kind: 'data'
+  readonly data: Record<string, unknown>
+  readonly mimeType?: string
+  readonly metadata?: Record<string, unknown>
+}
+
+export type A2APart = TextPart | FilePart | DataPart
+
+export interface A2AMessage {
+  readonly role: A2AMessageRole
+  readonly parts: readonly A2APart[]
+  readonly metadata?: Record<string, unknown>
+}
+
+export interface A2ATaskStatus {
+  readonly state: A2ATaskState
+  readonly message?: A2AMessage
+  readonly timestamp?: string
+}
+
+export interface A2AArtifact {
+  readonly artifactId: string
+  readonly name?: string
+  readonly description?: string
+  readonly parts: readonly A2APart[]
+  readonly metadata?: Record<string, unknown>
+}
+
+export interface A2ATask {
+  readonly id: string
+  readonly contextId?: string
+  readonly status: A2ATaskStatus
+  readonly history?: readonly A2AMessage[]
+  readonly artifacts?: readonly A2AArtifact[]
+  readonly metadata?: Record<string, unknown>
+}
+
+export interface A2AAgentProvider {
+  readonly organization: string
+  readonly url?: string
+}
+
+export interface A2AAgentCapabilities {
+  readonly streaming?: boolean
+  readonly pushNotifications?: boolean
+  readonly extendedAgentCard?: boolean
+}
+
+export interface A2AAgentSkill {
+  readonly id: string
+  readonly name: string
+  readonly description: string
+  readonly tags?: readonly string[]
+  readonly examples?: readonly string[]
+  readonly inputModes?: readonly string[]
+  readonly outputModes?: readonly string[]
+}
+
+export interface A2AAgentInterface {
+  readonly url: string
+  readonly transport: A2ATransport
+}
+
+export interface A2ASecurityScheme {
+  readonly type: 'http' | 'apiKey' | 'oauth2' | 'openIdConnect'
+  readonly scheme?: string
+  readonly bearerFormat?: string
+  readonly in?: 'header' | 'query' | 'cookie'
+  readonly name?: string
+}
+
+export interface A2ASecurityRequirement {
+  readonly [schemeName: string]: readonly string[]
+}
+
+export interface A2AAgentCard {
+  readonly name: string
+  readonly description: string
+  readonly version: string
+  readonly protocolVersion?: string
+  readonly provider?: A2AAgentProvider
+  readonly documentationUrl?: string
+  readonly capabilities: A2AAgentCapabilities
+  readonly defaultInputModes: readonly string[]
+  readonly defaultOutputModes: readonly string[]
+  readonly skills: readonly A2AAgentSkill[]
+  readonly securitySchemes?: Record<string, A2ASecurityScheme>
+  readonly securityRequirements?: readonly A2ASecurityRequirement[]
+  readonly iconUrl?: string
+  readonly supportedInterfaces: readonly A2AAgentInterface[]
+}
+
+export interface TaskStatusUpdateEvent {
+  readonly taskId: string
+  readonly contextId?: string
+  readonly status: A2ATaskStatus
+  readonly final: boolean
+  readonly metadata?: Record<string, unknown>
+}
+
+export interface TaskArtifactUpdateEvent {
+  readonly taskId: string
+  readonly contextId?: string
+  readonly artifact: A2AArtifact
+  readonly metadata?: Record<string, unknown>
+}
+
+export type A2AStreamEvent = TaskStatusUpdateEvent | TaskArtifactUpdateEvent
+
+export interface A2APushNotificationConfig {
+  readonly id?: string
+  readonly url: string
+  readonly token?: string
+  readonly authentication?: {
+    readonly schemes: readonly string[]
+    readonly credentials?: string
+  }
+  readonly events?: readonly A2ATaskState[]
+}
+
+export interface A2AMessageSendParams {
+  readonly message: A2AMessage
+
+  readonly id?: string
+
+  readonly contextId?: string
+  readonly metadata?: Record<string, unknown>
+}
+
+export interface A2ATaskQueryParams {
+  readonly id: string
+  readonly includeHistory?: boolean
+}
+
+export interface A2ATaskListParams {
+  readonly contextId?: string
+  readonly state?: A2ATaskState
+  readonly limit?: number
+  readonly cursor?: string
+}
+
+export interface A2ATaskCancelParams {
+  readonly id: string
+}
+
+export interface A2AJsonRpcRequest {
+  readonly jsonrpc: '2.0'
+  readonly id: string | number
+  readonly method: A2AMethod
+  readonly params?: unknown
+}
+
+export interface A2AJsonRpcResponse<T = unknown> {
+  readonly jsonrpc: '2.0'
+  readonly id: string | number
+  readonly result?: T
+  readonly error?: A2AJsonRpcError
+}
+
+export interface A2AJsonRpcError {
+  readonly code: number
+  readonly message: string
+  readonly data?: unknown
+}
+
+export class A2AProtocolError extends Error {
+  constructor(
+    public readonly code: A2AErrorCode,
+    message: string,
+    public readonly httpStatus: number = 400,
+  ) {
+    super(message)
+    this.name = 'A2AProtocolError'
+  }
+}
+
+export interface A2AServerConfig {
+  readonly baseUrl: string
+  readonly transport: A2ATransport
+  readonly providerOrganization?: string
+  readonly providerUrl?: string
+}

package/src/types/activity/index.ts

@@ -0,0 +1,54 @@
+import type { ActivityId, RunId } from '../ids/index.js'
+import type { PermissionMode } from '../permission/index.js'
+
+export type ActivityType = 'tool_call' | 'llm_turn' | 'sub_agent' | 'shell'
+
+export type ActivityStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | 'skipped'
+
+export function isTerminalActivityStatus(status: ActivityStatus): boolean {
+  return status === 'completed' || status === 'failed' || status === 'cancelled' || status === 'skipped'
+}
+
+export interface ActivityProgress {
+  percentage?: number
+  message?: string
+  updatedAt: number
+}
+
+export interface Activity<TInput = unknown, TOutput = unknown> {
+  id: ActivityId
+  runId: RunId
+  type: ActivityType
+  status: ActivityStatus
+  description: string
+  input?: TInput
+  output?: TOutput
+  error?: string
+  parentActivityId?: ActivityId
+  blockedBy: ActivityId[]
+  blocks: ActivityId[]
+  progress?: ActivityProgress
+  toolName?: string
+  toolCallId?: string
+  createdAt: number
+  startedAt?: number
+  completedAt?: number
+  durationMs?: number
+}
+
+export interface ActivityTrackingConfig {
+  enabled: boolean
+  trackToolCalls: boolean
+  trackLlmTurns: boolean
+}
+
+export function resolveActivityTracking(
+  _permissionMode: PermissionMode,
+  explicit?: boolean,
+): ActivityTrackingConfig {
+  if (explicit === false) {
+    return { enabled: false, trackToolCalls: false, trackLlmTurns: false }
+  }
+
+  return { enabled: true, trackToolCalls: true, trackLlmTurns: true }
+}

package/src/types/agent/base.ts

@@ -0,0 +1,73 @@
+import type { RunId, ThreadId } from '../ids/index.js'
+import type { AgentStatus, TokenUsage, CostInfo } from '../common/index.js'
+import type { Message } from '../message/index.js'
+import type { StopReason } from '../run/index.js'
+import type { PermissionMode } from '../permission/index.js'
+import type { TaskStore } from '../task/index.js'
+import type { ToolAvailability } from '../tool/index.js'
+
+export type AgentType = 'reactive' | 'pipeline' | 'router' | 'supervisor'
+
+export type AgentContextLevel = 'full' | 'standard' | 'minimal'
+
+export interface BaseAgentConfig {
+  model: string
+  tokenBudget: number
+  timeoutMs: number
+  maxIterations?: number
+  temperature?: number
+  maxResponseTokens?: number
+  costLimitUsd?: number
+  permissionMode?: PermissionMode
+  env?: Record<string, string>
+
+  threadId?: ThreadId
+
+  parentRunId?: RunId
+
+  depth?: number
+
+  contextLevel?: AgentContextLevel
+}
+
+export type RuntimeToolOverrides = Record<string, ToolAvailability | 'disabled'>
+
+export interface AgentInput {
+  messages: Message[]
+  workingDirectory: string
+  signal?: AbortSignal
+
+  taskStore?: TaskStore
+
+  runtimeToolOverrides?: RuntimeToolOverrides
+}
+
+export interface BaseAgentResult {
+  runId: RunId
+  status: AgentStatus
+  stopReason?: StopReason
+  usage: TokenUsage
+  cost: CostInfo
+  iterations: number
+  durationMs: number
+  messages: Message[]
+  result?: string
+  lastError?: string
+}
+
+export interface AgentCapabilities {
+  supportsTools: boolean
+  supportsStreaming: boolean
+  supportsConcurrency: boolean
+  supportsSubAgents: boolean
+}
+
+export interface AgentMetadata {
+  type: AgentType
+  id: string
+  name: string
+  version: string
+  category: string
+  description: string
+  capabilities: AgentCapabilities
+}

package/src/types/agent/core.ts

@@ -0,0 +1,26 @@
+import type { RunEventListener } from '../run/index.js'
+import type {
+  AgentType,
+  AgentMetadata,
+  AgentCapabilities,
+  BaseAgentConfig,
+  BaseAgentResult,
+  AgentInput,
+} from './base.js'
+
+export interface Agent<
+  TConfig extends BaseAgentConfig = BaseAgentConfig,
+  TResult extends BaseAgentResult = BaseAgentResult,
+> {
+  readonly type: AgentType
+  readonly metadata: AgentMetadata
+
+  run(
+    input: AgentInput,
+    config: TConfig,
+    listener?: RunEventListener,
+  ): Promise<TResult>
+
+  cancel(): Promise<void>
+  getCapabilities(): AgentCapabilities
+}

package/src/types/agent/factory.ts

@@ -0,0 +1,46 @@
+import type { AgentInfo } from '../../contracts/index.js'
+import type { BaseAgentConfig, BaseAgentResult, AgentContextLevel } from './base.js'
+import type { Agent } from './core.js'
+
+export type { AgentContextLevel } from './base.js'
+
+export interface AgentDefinition {
+  info: AgentInfo
+  typedAgent: Agent<BaseAgentConfig, BaseAgentResult>
+  configBuilder?: (options: AgentFactoryOptions) => BaseAgentConfig | Promise<BaseAgentConfig>
+
+  contextLevel?: AgentContextLevel
+}
+
+export interface AgentFactoryOptions {
+  apiKey: string
+  model?: string
+  workingDirectory?: string
+  tokenBudget?: number
+  timeoutMs?: number
+  temperature?: number
+  maxResponseTokens?: number
+  env?: Record<string, string>
+  permissionMode?: 'plan' | 'auto'
+
+  systemPrompt?: string
+
+  provider?: 'openrouter' | 'bedrock'
+
+  bedrockConfig?: {
+    region?: string
+    accessKeyId?: string
+    secretAccessKey?: string
+    sessionToken?: string
+  }
+
+  agentDefinitions?: AgentDefinition[]
+
+  threadId?: string
+
+  runId?: string
+
+  parentRunId?: string
+
+  depth?: number
+}

package/src/types/agent/gateway.ts

@@ -0,0 +1,38 @@
+import type { TaskId } from '../ids/index.js'
+import type { AgentTaskState } from './task.js'
+import type { BaseAgentResult } from './base.js'
+
+export interface TaskHandle {
+  readonly taskId: TaskId
+  readonly agentId: string
+  readonly state: AgentTaskState
+  readonly result?: BaseAgentResult
+  readonly createdAt: number
+  readonly completedAt?: number
+}
+
+export interface CreateTaskOptions {
+  agentId: string
+
+  prompt: string
+
+  workingDirectory: string
+
+  configOverrides?: Record<string, unknown>
+}
+
+export interface TaskGateway {
+  createTask(options: CreateTaskOptions): Promise<TaskHandle>
+
+  waitForTask(taskId: TaskId): Promise<TaskHandle>
+
+  continueTask(taskId: TaskId, message: string): Promise<void>
+
+  cancelTask(taskId: TaskId): void
+
+  getTask(taskId: TaskId): TaskHandle | undefined
+
+  listTasks(): TaskHandle[]
+
+  onTaskCompleted(callback: (handle: TaskHandle) => void): () => void
+}

package/src/types/agent/index.ts

@@ -0,0 +1,10 @@
+export * from './base.js'
+export * from './core.js'
+export * from './reactive.js'
+export * from './pipeline.js'
+export * from './router.js'
+export * from './supervisor.js'
+export * from './factory.js'
+export * from './gateway.js'
+export * from './task.js'
+export * from './lifecycle-event.js'

package/src/types/agent/lifecycle-event.ts

@@ -0,0 +1,21 @@
+import type { TaskId } from "../ids/index.js";
+import type { BaseAgentResult } from "./base.js";
+import type { AgentTaskProgress } from "./task.js";
+
+export type AgentLifecycleEvent =
+	| {
+			type: "pending";
+			taskId: TaskId;
+			agentId: string;
+			parentAgentId: string;
+			depth: number;
+	  }
+	| { type: "running"; taskId: TaskId }
+	| { type: "progress_updated"; taskId: TaskId; progress: AgentTaskProgress }
+	| { type: "completed"; taskId: TaskId; result: BaseAgentResult }
+	| { type: "failed"; taskId: TaskId; error: string }
+	| { type: "canceled"; taskId: TaskId };
+
+export type AgentLifecycleListener = (
+	event: AgentLifecycleEvent,
+) => void | Promise<void>;

package/src/types/agent/pipeline.ts

@@ -0,0 +1,41 @@
+import type { RunId } from '../ids/index.js'
+import type { LLMProvider } from '../provider/index.js'
+import type { BaseAgentConfig, BaseAgentResult } from './base.js'
+
+export interface StepContext {
+  runId: RunId
+  stepIndex: number
+  totalSteps: number
+  previousResults: Map<string, unknown>
+  provider?: LLMProvider
+  signal?: AbortSignal
+  env: Record<string, string>
+}
+
+export interface PipelineStep<TInput = unknown, TOutput = unknown> {
+  name: string
+  description?: string
+  execute(input: TInput, context: StepContext): Promise<TOutput>
+  rollback?(input: TInput, context: StepContext): Promise<void>
+  validate?(input: TInput): boolean
+}
+
+export interface PipelineAgentConfig extends BaseAgentConfig {
+  steps: PipelineStep[]
+  provider?: LLMProvider
+  continueOnError?: boolean
+}
+
+export interface PipelineStepResult {
+  stepName: string
+  status: 'completed' | 'failed' | 'skipped'
+  output?: unknown
+  error?: string
+  durationMs: number
+}
+
+export interface PipelineAgentResult extends BaseAgentResult {
+  stepResults: PipelineStepResult[]
+  completedSteps: number
+  totalSteps: number
+}