@namzu/sdk 0.1.1

package/src/types/connector/tenant.ts

@@ -0,0 +1,41 @@
+import type { TenantId, CredentialId, EnvironmentId } from '../ids/index.js'
+import type { AuthType, AuthConfig } from './core.js'
+
+export type EnvironmentTier = 'production' | 'staging' | 'development' | 'testing'
+
+export interface EnvironmentDescriptor {
+  id: EnvironmentId
+  name: string
+  tier: EnvironmentTier
+  orgId?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface TenantDescriptor {
+  id: TenantId
+  name: string
+  metadata?: Record<string, unknown>
+}
+
+export interface TenantRateLimitConfig {
+  maxRequests: number
+
+  windowMs: number
+}
+
+export interface CredentialRef {
+  id: CredentialId
+  connectorId: string
+  tenantId: TenantId
+  label: string
+  authType: AuthType
+  createdAt: number
+  expiresAt?: number
+}
+
+export interface CredentialVault {
+  store(tenantId: TenantId, connectorId: string, label: string, auth: AuthConfig): Promise<CredentialRef>
+  retrieve(credentialId: CredentialId): Promise<AuthConfig | undefined>
+  revoke(credentialId: CredentialId): Promise<boolean>
+  list(tenantId: TenantId, connectorId?: string): Promise<CredentialRef[]>
+}

package/src/types/connector/webhook.ts

@@ -0,0 +1,18 @@
+export interface WebhookConnectorConfig {
+  url: string
+  secret?: string
+  defaultHeaders?: Record<string, string>
+  timeoutMs?: number
+}
+
+export interface WebhookSendInput {
+  payload: unknown
+  headers?: Record<string, string>
+  url?: string
+}
+
+export interface WebhookSendOutput {
+  status: number
+  body: unknown
+  deliveredAt: number
+}

package/src/types/conversation/index.ts

@@ -0,0 +1,8 @@
+import type { Message } from '../message/index.js'
+import type { ThreadId, RunId } from '../ids/index.js'
+
+export interface ConversationStore {
+  loadMessages(threadId: ThreadId): Message[]
+
+  persistRunResult(threadId: ThreadId, runId: RunId, messages: Message[]): void
+}

package/src/types/decision/index.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod'
+
+export const RoutingResponseSchema = z.object({
+  agentId: z.string().min(1, 'agentId is required'),
+  confidence: z.number().min(0).max(1),
+  reasoning: z.string().optional(),
+}).strict()
+
+export type RoutingResponse = z.infer<typeof RoutingResponseSchema>
+
+export interface DecisionParserConfig {
+  validAgentIds: string[]
+
+  minConfidence: number
+
+  maxRetries: number
+
+  fallbackAgentId: string
+}
+
+export type DecisionParseResult =
+  | { ok: true; decision: RoutingResponse; source: 'parsed' }
+  | { ok: true; decision: RoutingResponse; source: 'pattern_match' }
+  | { ok: true; decision: RoutingResponse; source: 'fallback'; reason: string }
+  | { ok: false; error: string; rawContent: string }
+
+export type FallbackStrategy =
+  | { type: 'fixed'; agentId: string }
+  | { type: 'pattern_match'; patterns: Map<string, string[]> }
+  | { type: 'first_route' }

package/src/types/execution/index.ts

@@ -0,0 +1,48 @@
+export type ExecutionEnvironment = 'local' | 'remote' | 'hybrid'
+
+export type ExecutionCapability = 'filesystem' | 'process' | 'network' | 'shell'
+
+export interface CommandOptions {
+  cwd?: string
+  env?: Record<string, string>
+  timeoutMs?: number
+  shell?: string | boolean
+}
+
+export interface CommandResult {
+  exitCode: number
+  stdout: string
+  stderr: string
+  durationMs: number
+}
+
+export interface CommandExecutor {
+  executeCommand(command: string, args?: string[], options?: CommandOptions): Promise<CommandResult>
+}
+
+export interface RemoteCommandHandler {
+  executeRemote(command: string, options?: CommandOptions): Promise<CommandResult>
+}
+
+export type ExecutionRoutingStrategy = 'local-first' | 'remote-first' | 'round-robin'
+
+export interface ExecutionContextBase {
+  id: string
+  environment: ExecutionEnvironment
+  capabilities?: ExecutionCapability[]
+  metadata?: Record<string, unknown>
+}
+
+export interface ExecutionContextLifecycle {
+  initialize(): Promise<void>
+  isReady(): boolean
+  teardown(): Promise<void>
+}
+
+export type ExecutionContextEvent =
+  | { type: 'context_initialized'; contextId: string; environment: ExecutionEnvironment }
+  | { type: 'context_ready'; contextId: string }
+  | { type: 'context_error'; contextId: string; error: string }
+  | { type: 'context_teardown'; contextId: string }
+
+export type ExecutionContextEventListener = (event: ExecutionContextEvent) => void

package/src/types/hitl/index.ts

@@ -0,0 +1,106 @@
+import type { RunId, PlanId } from '../ids/index.js'
+import type { TokenUsage, CostInfo } from '../common/index.js'
+import type { PlanStep, PlanStatus } from '../plan/index.js'
+import type { Message } from '../message/index.js'
+
+import type { CheckpointId } from '../ids/index.js'
+export type { CheckpointId }
+
+export type HITLResumeDecision =
+  | { action: 'continue' }
+  | { action: 'approve_plan' }
+  | { action: 'reject_plan'; feedback: string }
+  | { action: 'approve_tools' }
+  | { action: 'modify_tools'; modifications: ToolModification[] }
+  | { action: 'reject_tools'; feedback: string }
+  | { action: 'pause'; reason: string }
+  | { action: 'abort'; reason: string }
+
+export type HITLDecisionRequest =
+  | { type: 'plan_approval'; runId: RunId; checkpointId: CheckpointId; plan: PlanApprovalData }
+  | { type: 'tool_review'; runId: RunId; checkpointId: CheckpointId; toolCalls: ToolCallSummary[] }
+  | { type: 'iteration_checkpoint'; runId: RunId; checkpointId: CheckpointId; summary: CheckpointSummary }
+
+export type ResumeHandler = (request: HITLDecisionRequest) => Promise<HITLResumeDecision>
+
+export interface ToolCallSummary {
+  id: string
+  name: string
+  input: unknown
+  isDestructive: boolean
+}
+
+export interface ToolModification {
+  toolCallId: string
+  action: 'approve' | 'deny' | 'modify'
+  modifiedInput?: unknown
+}
+
+export interface PlanApprovalData {
+  planId: PlanId
+  title: string
+  steps: Array<{ id: string; description: string; toolName?: string; dependsOn: string[]; order: number }>
+  summary?: string
+}
+
+export interface CheckpointSummary {
+  iteration: number
+  messageCount: number
+  tokenUsage: TokenUsage
+  costInfo: CostInfo
+  lastAssistantMessage?: string
+}
+
+export interface ActiveNodeInfo {
+  agentId: string
+  agentType: 'reactive' | 'pipeline' | 'router' | 'supervisor'
+
+  nodeRef?: string
+
+  parentAgentId?: string
+
+  depth: number
+}
+
+export interface BranchStackEntry {
+  agentId: string
+  decision: string
+  confidence: number
+  timestamp: number
+}
+
+export interface IterationCheckpoint {
+  id: CheckpointId
+  runId: RunId
+  iteration: number
+  messages: Message[]
+  tokenUsage: TokenUsage
+  costInfo: CostInfo
+  planStatus?: PlanStatus
+  guardState: {
+    iterationCount: number
+    elapsedMs: number
+  }
+  createdAt: number
+
+  toolResultHashes?: Record<string, string>
+
+  branchStack?: BranchStackEntry[]
+
+  activeNode?: ActiveNodeInfo
+}
+
+export function autoApproveHandler(request: HITLDecisionRequest): Promise<HITLResumeDecision> {
+  switch (request.type) {
+    case 'plan_approval':
+      return Promise.resolve({ action: 'approve_plan' })
+    case 'tool_review':
+      return Promise.resolve({ action: 'approve_tools' })
+    case 'iteration_checkpoint':
+      return Promise.resolve({ action: 'continue' })
+    default: {
+      const _exhaustive: never = request
+      throw new Error(`Unhandled HITL request type: ${(_exhaustive as HITLDecisionRequest).type}`)
+    }
+  }
+}

package/src/types/ids/index.ts

@@ -0,0 +1,21 @@
+export type ThreadId = `thd_${string}`
+export type RunId = `run_${string}`
+export type MessageId = `msg_${string}`
+export type SessionId = `sess_${string}`
+export type ToolCallId = `call_${string}`
+export type ActivityId = `act_${string}`
+export type TaskId = `task_${string}`
+export type PlanId = `plan_${string}`
+export type KnowledgeBaseId = `kb_${string}`
+export type DocumentId = `doc_${string}`
+export type ChunkId = `chk_${string}`
+export type ConnectorId = `conn_${string}`
+export type ConnectorInstanceId = `ci_${string}`
+export type TenantId = `ten_${string}`
+export type CredentialId = `cred_${string}`
+export type ExecutionContextId = `ectx_${string}`
+export type MCPServerId = `mcp_${string}`
+export type MCPClientId = `mcpc_${string}`
+export type MCPSessionId = `mcps_${string}`
+export type EnvironmentId = `env_${string}`
+export type CheckpointId = `cp_${string}`

package/src/types/message/index.ts

@@ -0,0 +1,62 @@
+export type MessageRole = 'system' | 'user' | 'assistant' | 'tool'
+
+export interface ToolCall {
+  id: string
+  type: 'function'
+  function: {
+    name: string
+    arguments: string
+  }
+}
+
+export interface BaseMessage {
+  role: MessageRole
+  content: string | null
+  timestamp?: number
+}
+
+export interface SystemMessage extends BaseMessage {
+  role: 'system'
+  content: string
+}
+
+export interface UserMessage extends BaseMessage {
+  role: 'user'
+  content: string
+}
+
+export interface AssistantMessage extends BaseMessage {
+  role: 'assistant'
+  content: string | null
+  toolCalls?: ToolCall[]
+}
+
+export interface ToolMessage extends BaseMessage {
+  role: 'tool'
+  content: string
+  toolCallId: string
+}
+
+export type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage
+
+export function createSystemMessage(content: string): SystemMessage {
+  return { role: 'system', content, timestamp: Date.now() }
+}
+
+export function createUserMessage(content: string): UserMessage {
+  return { role: 'user', content, timestamp: Date.now() }
+}
+
+export function createAssistantMessage(
+  content: string | null,
+  toolCalls?: ToolCall[],
+): AssistantMessage {
+  return { role: 'assistant', content, toolCalls, timestamp: Date.now() }
+}
+
+export function createToolMessage(
+  content: string,
+  toolCallId: string,
+): ToolMessage {
+  return { role: 'tool', content, toolCallId, timestamp: Date.now() }
+}

package/src/types/permission/index.ts

@@ -0,0 +1 @@
+export type PermissionMode = 'plan' | 'auto'

package/src/types/persona/index.ts

@@ -0,0 +1,55 @@
+export type PersonaLayer =
+  | 'system'
+  | 'identity'
+  | 'expertise'
+  | 'reflexes'
+  | 'skills'
+  | 'tools'
+  | 'output'
+  | 'task-context'
+
+export interface PersonaIdentity {
+  role: string
+
+  description: string
+}
+
+export interface PersonaExpertise {
+  domains: string[]
+}
+
+export interface PersonaReflexes {
+  constraints: string[]
+
+  toolGuidance?: string
+}
+
+export interface PersonaOutput {
+  format: string
+}
+
+export interface AgentPersona {
+  identity: PersonaIdentity
+  expertise?: PersonaExpertise
+  reflexes?: PersonaReflexes
+  output?: PersonaOutput
+  sessionContext?: string
+}
+
+export interface BehavioralConstraints {
+  prohibitions: string[]
+  requirements?: string[]
+  scope?: string
+}
+
+export interface PersonaDefinition {
+  schemaVersion: 1
+  agentId?: string
+  personaId?: string
+
+  extends?: string
+  identity: PersonaIdentity
+  expertise?: PersonaExpertise
+  reflexes?: PersonaReflexes
+  output?: PersonaOutput
+}

package/src/types/plan/index.ts

@@ -0,0 +1,56 @@
+import type { PlanId, RunId } from '../ids/index.js'
+
+export type PlanStatus =
+  | 'generating'
+  | 'ready'
+  | 'pending_approval'
+  | 'approved'
+  | 'rejected'
+  | 'executing'
+  | 'completed'
+  | 'failed'
+
+export function isTerminalPlanStatus(status: PlanStatus): boolean {
+  return status === 'completed' || status === 'failed' || status === 'rejected'
+}
+
+export interface PlanStep {
+  id: string
+  description: string
+  toolName?: string
+  estimatedInput?: unknown
+  dependsOn: string[]
+  status: 'pending' | 'running' | 'completed' | 'skipped' | 'failed'
+  error?: string
+  order: number
+}
+
+export interface Plan {
+  id: PlanId
+  runId: RunId
+  status: PlanStatus
+  title: string
+  summary?: string
+  steps: PlanStep[]
+  rawContent?: string
+  createdAt: number
+  readyAt?: number
+  approvedAt?: number
+  rejectedAt?: number
+  completedAt?: number
+  rejectionReason?: string
+}
+
+export interface PlanApprovalRequest {
+  planId: PlanId
+  runId: RunId
+  title: string
+  steps: PlanStep[]
+  summary?: string
+}
+
+export interface PlanApprovalResponse {
+  approved: boolean
+  feedback?: string
+  modifiedSteps?: PlanStep[]
+}

package/src/types/provider/chat.ts

@@ -0,0 +1,59 @@
+import type { Message } from '../message/index.js'
+import type { LLMToolSchema } from '../tool/index.js'
+import type { TokenUsage } from '../common/index.js'
+
+export type ToolChoice =
+  | 'auto'
+  | 'none'
+  | 'required'
+  | { type: 'function'; function: { name: string } }
+
+export type ResponseFormat =
+  | { type: 'json_object' }
+  | { type: 'json_schema'; json_schema: { name: string; schema: Record<string, unknown>; strict?: boolean } }
+
+export interface CacheControl {
+  type: 'auto' | 'ephemeral'
+}
+
+export interface ChatCompletionParams {
+  model: string
+  messages: Message[]
+  tools?: LLMToolSchema[]
+  temperature?: number
+  maxTokens?: number
+  stream?: boolean
+  stop?: string[]
+
+  toolChoice?: ToolChoice
+  parallelToolCalls?: boolean
+
+  cacheControl?: CacheControl
+
+  topP?: number
+  topK?: number
+  frequencyPenalty?: number
+  presencePenalty?: number
+  repetitionPenalty?: number
+
+  responseFormat?: ResponseFormat
+}
+
+export interface ChatCompletionResponse {
+  id: string
+  model: string
+  message: {
+    role: 'assistant'
+    content: string | null
+    toolCalls?: Array<{
+      id: string
+      type: 'function'
+      function: {
+        name: string
+        arguments: string
+      }
+    }>
+  }
+  finishReason: 'stop' | 'tool_calls' | 'length' | 'content_filter'
+  usage: TokenUsage
+}

package/src/types/provider/config.ts

@@ -0,0 +1,50 @@
+import type { LLMProvider } from './interface.js'
+
+export type ProviderType = 'openrouter' | 'bedrock' | 'mock'
+
+export interface OpenRouterConfig {
+  apiKey: string
+  baseUrl?: string
+  siteUrl?: string
+  siteName?: string
+  timeout?: number
+}
+
+export interface OpenRouterProviderConfig extends OpenRouterConfig {
+  type: 'openrouter'
+}
+
+export interface BedrockConfig {
+  region?: string
+
+  accessKeyId?: string
+  secretAccessKey?: string
+  sessionToken?: string
+
+  timeout?: number
+}
+
+export interface BedrockProviderConfig extends BedrockConfig {
+  type: 'bedrock'
+}
+
+export interface MockProviderConfig {
+  type: 'mock'
+  model?: string
+  responseText?: string
+  responseDelayMs?: number
+}
+
+export type ProviderFactoryConfig = OpenRouterProviderConfig | BedrockProviderConfig | MockProviderConfig
+
+export interface ProviderCapabilities {
+  supportsTools: boolean
+  supportsStreaming: boolean
+  supportsFunctionCalling: boolean
+  maxOutputTokens?: number
+}
+
+export interface ProviderFactoryResult {
+  provider: LLMProvider
+  capabilities: ProviderCapabilities
+}

package/src/types/provider/index.ts

@@ -0,0 +1,15 @@
+export type { ToolChoice, ResponseFormat, CacheControl, ChatCompletionParams, ChatCompletionResponse } from './chat.js'
+export type { StreamChunk } from './stream.js'
+export type { ModelInfo } from './model.js'
+export type { LLMProvider } from './interface.js'
+export type {
+  ProviderType,
+  OpenRouterConfig,
+  OpenRouterProviderConfig,
+  BedrockConfig,
+  BedrockProviderConfig,
+  MockProviderConfig,
+  ProviderFactoryConfig,
+  ProviderCapabilities,
+  ProviderFactoryResult,
+} from './config.js'

package/src/types/provider/interface.ts

@@ -0,0 +1,16 @@
+import type { ChatCompletionParams, ChatCompletionResponse } from './chat.js'
+import type { StreamChunk } from './stream.js'
+import type { ModelInfo } from './model.js'
+
+export interface LLMProvider {
+  readonly id: string
+  readonly name: string
+
+  chat(params: ChatCompletionParams): Promise<ChatCompletionResponse>
+
+  chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk>
+
+  listModels?(): Promise<ModelInfo[]>
+
+  healthCheck?(): Promise<boolean>
+}

package/src/types/provider/model.ts

@@ -0,0 +1,10 @@
+export interface ModelInfo {
+  id: string
+  name: string
+  contextWindow: number
+  maxOutputTokens: number
+  inputPrice: number
+  outputPrice: number
+  supportsToolUse: boolean
+  supportsStreaming: boolean
+}

package/src/types/provider/stream.ts

@@ -0,0 +1,20 @@
+import type { TokenUsage } from '../common/index.js'
+
+export interface StreamChunk {
+  id: string
+  delta: {
+    content?: string
+    toolCalls?: Array<{
+      index: number
+      id?: string
+      type?: 'function'
+      function?: {
+        name?: string
+        arguments?: string
+      }
+    }>
+  }
+  finishReason?: 'stop' | 'tool_calls' | 'length' | 'content_filter'
+  usage?: TokenUsage
+  error?: string
+}

package/src/types/rag/chunking.ts

@@ -0,0 +1,17 @@
+export type ChunkingStrategy = 'fixed' | 'sentence' | 'paragraph' | 'recursive'
+
+export interface ChunkingConfig {
+  strategy: ChunkingStrategy
+  chunkSize: number
+  chunkOverlap: number
+  separators?: string[]
+}
+
+export interface Chunker {
+  chunk(content: string, config: ChunkingConfig): ChunkContent[]
+}
+
+export interface ChunkContent {
+  content: string
+  index: number
+}

package/src/types/rag/context.ts

@@ -0,0 +1,28 @@
+import type { DocumentId, KnowledgeBaseId } from '../ids/index.js'
+import type { KnowledgeBase } from './knowledge-base.js'
+
+export interface RAGToolInput {
+  query: string
+  knowledgeBaseId?: string
+  topK?: number
+}
+
+export interface RAGContextConfig {
+  maxTokens: number
+  separator: string
+  includeMetadata: boolean
+  headerTemplate?: string
+}
+
+export interface RAGContext {
+  content: string
+  sources: Array<{ documentId: DocumentId; chunk: string; score: number }>
+  tokenCount: number
+}
+
+export interface RAGToolConfig {
+  knowledgeBases: Map<string, KnowledgeBase>
+  defaultKnowledgeBaseId?: KnowledgeBaseId
+  contextConfig?: Partial<RAGContextConfig>
+  topK?: number
+}