@namzu/sdk 0.1.1

package/src/types/agent/reactive.ts

@@ -0,0 +1,21 @@
+import type { BaseAgentConfig, BaseAgentResult } from './base.js'
+import type { LLMProvider } from '../provider/index.js'
+import type { ToolRegistry } from '../../registry/tool/execute.js'
+import type { AgentPersona } from '../persona/index.js'
+import type { Skill } from '../skills/index.js'
+
+export interface ReactiveAgentConfig extends BaseAgentConfig {
+  systemPrompt?: string
+
+  persona?: AgentPersona
+
+  skills?: Skill[]
+
+  basePrompt?: string
+  provider: LLMProvider
+  tools: ToolRegistry
+}
+
+export interface ReactiveAgentResult extends BaseAgentResult {
+  toolCallCount: number
+}

package/src/types/agent/router.ts

@@ -0,0 +1,34 @@
+import type { LLMProvider } from '../provider/index.js'
+import type { BaseAgentConfig, BaseAgentResult } from './base.js'
+import type { Agent } from './core.js'
+
+export type RoutingDecisionSource = 'provider' | 'fallback' | 'hard_fail'
+
+export interface RoutingDecision {
+  agentId: string
+  confidence: number
+  reasoning?: string
+  routingSource: RoutingDecisionSource
+}
+
+export interface RouteDefinition {
+  agentId: string
+  agent: Agent<BaseAgentConfig, BaseAgentResult>
+  description: string
+  matchPatterns?: string[]
+}
+
+export interface RouterAgentConfig extends BaseAgentConfig {
+  routes: RouteDefinition[]
+  provider: LLMProvider
+  routingPrompt?: string
+  fallbackAgentId?: string
+  minConfidence?: number
+  maxRoutingRetries?: number
+}
+
+export interface RouterAgentResult extends BaseAgentResult {
+  selectedRoute: string
+  routingDecision: RoutingDecision
+  delegateResult: BaseAgentResult
+}

package/src/types/agent/supervisor.ts

@@ -0,0 +1,32 @@
+import type { LLMProvider } from '../provider/index.js'
+import type { BaseAgentConfig, BaseAgentResult } from './base.js'
+import type { AgentFactoryOptions } from './factory.js'
+import type { TaskGateway } from './gateway.js'
+import type { AgentManager } from '../../manager/agent/lifecycle.js'
+
+export interface SupervisorAgentConfig extends BaseAgentConfig {
+  provider: LLMProvider
+
+  agentIds: string[]
+
+  gateway?: TaskGateway
+  agentManager?: AgentManager
+
+  systemPrompt: string
+
+  maxDepth?: number
+
+  factoryOptions?: AgentFactoryOptions
+}
+
+export interface AgentTaskResult {
+  agentId: string
+  result: BaseAgentResult
+  taskIndex: number
+}
+
+export interface SupervisorAgentResult extends BaseAgentResult {
+  taskResults: AgentTaskResult[]
+  completedTasks: number
+  totalTasks: number
+}

package/src/types/agent/task.ts

@@ -0,0 +1,101 @@
+import type { TokenUsage } from "../common/index.js";
+import type { RunId, TaskId, ThreadId } from "../ids/index.js";
+import type { Message } from "../message/index.js";
+import type { RunEventListener } from "../run/events.js";
+import type { AgentInput, BaseAgentConfig, BaseAgentResult } from "./base.js";
+import type { Agent } from "./core.js";
+import type { AgentFactoryOptions } from "./factory.js";
+
+export type AgentTaskState =
+	| "pending"
+	| "running"
+	| "completed"
+	| "failed"
+	| "canceled"
+	| "rejected"
+	| "input-required";
+
+export function isTerminalAgentTaskState(state: AgentTaskState): boolean {
+	return (
+		state === "completed" ||
+		state === "failed" ||
+		state === "canceled" ||
+		state === "rejected"
+	);
+}
+
+export interface AgentTaskContext {
+	parentRunId: RunId;
+
+	parentAgentId: string;
+
+	parentAbortController: AbortController;
+
+	depth: number;
+
+	budgetTracker: AgentTaskBudget;
+
+	factoryOptions?: AgentFactoryOptions;
+
+	threadId?: ThreadId;
+}
+
+export interface AgentTaskBudget {
+	total: number;
+
+	remaining: number;
+}
+
+export interface AgentTask {
+	taskId: TaskId;
+	agentId: string;
+	agent: Agent<BaseAgentConfig, BaseAgentResult>;
+	childAbortController: AbortController;
+	context: AgentTaskContext;
+	state: AgentTaskState;
+	result?: BaseAgentResult;
+	progress?: AgentTaskProgress;
+
+	pendingMessages: Message[];
+	createdAt: number;
+	completedAt?: number;
+
+	evictAfter?: number;
+
+	runEventListener?: RunEventListener;
+}
+
+export interface AgentTaskProgress {
+	toolUseCount: number;
+	usage: TokenUsage;
+	recentActivities: string[];
+}
+
+export const MAX_RECENT_ACTIVITIES = 5;
+
+export interface SendMessageOptions {
+	agentId: string;
+
+	input: AgentInput;
+
+	configOverrides?: Partial<BaseAgentConfig>;
+
+	budgetAllocation?: {
+		tokenBudget?: number;
+		timeoutMs?: number;
+	};
+}
+
+export interface AgentManagerConfig {
+	maxDepth: number;
+
+	evictionMs: number;
+
+	maxBudgetFraction: number;
+}
+
+export const AGENT_MANAGER_DEFAULTS: Readonly<AgentManagerConfig> = {
+	maxDepth: 3,
+	evictionMs: 30_000,
+	maxBudgetFraction: 0.5,
+};

package/src/types/common/index.ts

@@ -0,0 +1,54 @@
+export type AgentStatus =
+  | 'idle'
+  | 'pending'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+
+export function isTerminalStatus(status: AgentStatus): boolean {
+  return status === 'completed' || status === 'failed' || status === 'cancelled'
+}
+
+export interface TokenUsage {
+  promptTokens: number
+  completionTokens: number
+  totalTokens: number
+  cachedTokens: number
+  cacheWriteTokens: number
+}
+
+export const EMPTY_TOKEN_USAGE: TokenUsage = {
+  promptTokens: 0,
+  completionTokens: 0,
+  totalTokens: 0,
+  cachedTokens: 0,
+  cacheWriteTokens: 0,
+}
+
+export function accumulateTokenUsage(
+  current: TokenUsage,
+  addition: TokenUsage,
+): TokenUsage {
+  return {
+    promptTokens: current.promptTokens + addition.promptTokens,
+    completionTokens: current.completionTokens + addition.completionTokens,
+    totalTokens: current.totalTokens + addition.totalTokens,
+    cachedTokens: current.cachedTokens + addition.cachedTokens,
+    cacheWriteTokens: current.cacheWriteTokens + addition.cacheWriteTokens,
+  }
+}
+
+export interface CostInfo {
+  inputCostPer1M: number
+  outputCostPer1M: number
+  totalCost: number
+  cacheDiscount: number
+}
+
+export interface PlatformError {
+  code: string
+  message: string
+  details?: Record<string, unknown>
+  retryable: boolean
+}

package/src/types/connector/core.ts

@@ -0,0 +1,47 @@
+import type { z } from 'zod'
+import type { ConnectorInstanceId } from '../ids/index.js'
+
+export type ConnectionType = 'http' | 'webhook' | 'custom'
+
+export type ConnectorStatus = 'disconnected' | 'connecting' | 'connected' | 'error'
+
+export function isConnectorActive(status: ConnectorStatus): boolean {
+  return status === 'connected' || status === 'connecting'
+}
+
+export type AuthType = 'none' | 'api_key' | 'bearer' | 'basic' | 'oauth2' | 'custom'
+
+export interface AuthConfig {
+  type: AuthType
+  credentials?: Record<string, string>
+}
+
+export type ConnectorCategory =
+  | 'communication'
+  | 'data'
+  | 'development'
+  | 'productivity'
+  | 'integration'
+  | 'custom'
+
+export interface ConnectorMethod<TInput = unknown, TOutput = unknown> {
+  name: string
+  description: string
+  inputSchema: z.ZodType<TInput, z.ZodTypeDef, unknown>
+  outputSchema?: z.ZodType<TOutput, z.ZodTypeDef, unknown>
+}
+
+export interface ConnectorTrigger {
+  name: string
+  description: string
+  event: string
+  configSchema?: z.ZodType
+}
+
+export interface ConnectorEvent {
+  connectorId: string
+  instanceId: ConnectorInstanceId
+  trigger: string
+  payload: unknown
+  timestamp: number
+}

package/src/types/connector/definition.ts

@@ -0,0 +1,69 @@
+import type { z } from 'zod'
+import type { ConnectorInstanceId } from '../ids/index.js'
+import type { ConnectorCategory, ConnectionType, AuthType, ConnectorMethod, ConnectorTrigger, ConnectorStatus, AuthConfig } from './core.js'
+
+export interface ConnectorDefinition<TConfig = unknown> {
+  id: string
+  name: string
+  description: string
+  version?: string
+  category?: ConnectorCategory
+  connectionType: ConnectionType
+  supportedAuth?: AuthType[]
+  configSchema: z.ZodType<TConfig, z.ZodTypeDef, unknown>
+  methods: ConnectorMethod[]
+  triggers?: ConnectorTrigger[]
+}
+
+export interface ConnectorConfig {
+  connectorId: string
+  name: string
+  auth?: AuthConfig
+  options?: Record<string, unknown>
+}
+
+export interface ConnectorInstance {
+  id: ConnectorInstanceId
+  connectorId: string
+  config: ConnectorConfig
+  status: ConnectorStatus
+  createdAt: number
+  connectedAt?: number
+  lastUsedAt?: number
+  error?: string
+}
+
+export interface ConnectorExecuteParams {
+  instanceId: ConnectorInstanceId
+  method: string
+  input: unknown
+}
+
+export interface ConnectorExecuteResult {
+  success: boolean
+  output: unknown
+  error?: string
+  durationMs: number
+  metadata?: Record<string, unknown>
+}
+
+export interface ConnectorLifecycle<TConfig = unknown> {
+  connect(config: TConfig, auth?: AuthConfig): Promise<void>
+  disconnect(): Promise<void>
+  healthCheck(): Promise<boolean>
+  execute(method: string, input: unknown): Promise<ConnectorExecuteResult>
+}
+
+export type ConnectorLifecycleEvent =
+  | { type: 'connector_registered'; connectorId: string }
+  | { type: 'connector_unregistered'; connectorId: string }
+  | { type: 'instance_created'; instanceId: ConnectorInstanceId; connectorId: string }
+  | { type: 'instance_connecting'; instanceId: ConnectorInstanceId }
+  | { type: 'instance_connected'; instanceId: ConnectorInstanceId }
+  | { type: 'instance_disconnected'; instanceId: ConnectorInstanceId }
+  | { type: 'instance_error'; instanceId: ConnectorInstanceId; error: string }
+  | { type: 'instance_removed'; instanceId: ConnectorInstanceId }
+  | { type: 'action_executing'; instanceId: ConnectorInstanceId; method: string }
+  | { type: 'action_completed'; instanceId: ConnectorInstanceId; method: string; success: boolean; durationMs: number }
+
+export type ConnectorEventListener = (event: ConnectorLifecycleEvent) => void

package/src/types/connector/execution-context.ts

@@ -0,0 +1,51 @@
+import type { AuthConfig } from './core.js'
+import type {
+  ExecutionEnvironment,
+  ExecutionCapability,
+  ExecutionContextBase,
+  ExecutionContextEvent,
+  ExecutionRoutingStrategy,
+} from '../execution/index.js'
+
+export type { ExecutionEnvironment, ExecutionCapability, ExecutionContextBase } from '../execution/index.js'
+export type { CommandOptions, CommandResult, CommandExecutor, RemoteCommandHandler } from '../execution/index.js'
+export type { ExecutionRoutingStrategy, ExecutionContextLifecycle } from '../execution/index.js'
+export type { ExecutionContextEventListener } from '../execution/index.js'
+
+export interface RemoteTarget {
+  type: 'ssh' | 'rdp' | 'api'
+  host: string
+  port?: number
+  auth?: AuthConfig
+  metadata?: Record<string, unknown>
+}
+
+export interface LocalExecutionContextConfig extends ExecutionContextBase {
+  environment: 'local'
+  cwd: string
+  fsAccess: boolean
+  envVars?: Record<string, string>
+  shell?: string
+}
+
+export interface RemoteExecutionContextConfig extends ExecutionContextBase {
+  environment: 'remote'
+  target: RemoteTarget
+}
+
+export interface HybridExecutionContextConfig extends ExecutionContextBase {
+  environment: 'hybrid'
+  local: Omit<LocalExecutionContextConfig, 'id' | 'environment'>
+  remotes: RemoteTarget[]
+  routingStrategy?: ExecutionRoutingStrategy
+}
+
+export type ExecutionContextConfig =
+  | LocalExecutionContextConfig
+  | RemoteExecutionContextConfig
+  | HybridExecutionContextConfig
+
+export type ConnectorExecutionContextEvent =
+  | ExecutionContextEvent
+  | { type: 'remote_connected'; contextId: string; target: RemoteTarget }
+  | { type: 'remote_disconnected'; contextId: string; host: string }

package/src/types/connector/http.ts

@@ -0,0 +1,22 @@
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD'
+
+export interface HttpConnectorConfig {
+  baseUrl: string
+  defaultHeaders?: Record<string, string>
+  timeoutMs?: number
+}
+
+export interface HttpRequestInput {
+  method: HttpMethod
+  path: string
+  headers?: Record<string, string>
+  query?: Record<string, string>
+  body?: unknown
+}
+
+export interface HttpResponseOutput {
+  status: number
+  statusText: string
+  headers: Record<string, string>
+  body: unknown
+}

package/src/types/connector/index.ts

@@ -0,0 +1,8 @@
+export * from './core.js'
+export * from './definition.js'
+export * from './http.js'
+export * from './webhook.js'
+export * from './scope.js'
+export * from './tenant.js'
+export * from './execution-context.js'
+export * from './mcp.js'

package/src/types/connector/mcp.ts

@@ -0,0 +1,205 @@
+import type { MCPServerId, MCPClientId, ConnectorInstanceId } from '../ids/index.js'
+import type { ConnectorDefinition, ConnectorInstance, ConnectorExecuteParams, ConnectorExecuteResult } from './definition.js'
+
+export type MCPTransportType = 'stdio' | 'http-sse'
+
+export interface MCPTransportConfigBase {
+  type: MCPTransportType
+}
+
+export interface MCPStdioTransportConfig extends MCPTransportConfigBase {
+  type: 'stdio'
+  command: string
+  args?: string[]
+  env?: Record<string, string>
+  cwd?: string
+}
+
+export interface MCPHttpSseTransportConfig extends MCPTransportConfigBase {
+  type: 'http-sse'
+  url: string
+  headers?: Record<string, string>
+  timeoutMs?: number
+}
+
+export type MCPTransportUnion = MCPStdioTransportConfig | MCPHttpSseTransportConfig
+
+export interface MCPJsonRpcError {
+  code: number
+  message: string
+  data?: unknown
+}
+
+export interface MCPJsonRpcMessage {
+  jsonrpc: '2.0'
+  id?: string | number
+  method?: string
+  params?: Record<string, unknown>
+  result?: unknown
+  error?: MCPJsonRpcError
+}
+
+export interface MCPTransport {
+  connect(): Promise<void>
+  close(): Promise<void>
+  send(message: MCPJsonRpcMessage): Promise<void>
+  onMessage(handler: (message: MCPJsonRpcMessage) => void): void
+  onClose(handler: () => void): void
+  onError(handler: (error: Error) => void): void
+  isConnected(): boolean
+}
+
+export interface MCPJsonSchema {
+  type: 'object'
+  properties?: Record<string, unknown>
+  required?: string[]
+  [key: string]: unknown
+}
+
+export interface MCPToolAnnotations {
+  title?: string
+  readOnlyHint?: boolean
+  destructiveHint?: boolean
+  idempotentHint?: boolean
+  openWorldHint?: boolean
+}
+
+export interface MCPToolDefinition {
+  name: string
+  description?: string
+  inputSchema: MCPJsonSchema
+  annotations?: MCPToolAnnotations
+}
+
+export type MCPContentBlock =
+  | { type: 'text'; text: string }
+  | { type: 'image'; data: string; mimeType: string }
+  | { type: 'resource'; resource: { uri: string; mimeType?: string; text?: string } }
+
+export interface MCPToolResult {
+  content: MCPContentBlock[]
+  isError?: boolean
+}
+
+export interface MCPResource {
+  uri: string
+  name: string
+  description?: string
+  mimeType?: string
+}
+
+export interface MCPResourceTemplate {
+  uriTemplate: string
+  name: string
+  description?: string
+  mimeType?: string
+}
+
+export interface MCPPromptArgument {
+  name: string
+  description?: string
+  required?: boolean
+}
+
+export interface MCPPromptDefinition {
+  name: string
+  description?: string
+  arguments?: MCPPromptArgument[]
+}
+
+export interface MCPClientCapabilities {
+  roots?: { listChanged?: boolean }
+  sampling?: Record<string, never>
+  experimental?: Record<string, unknown>
+}
+
+export interface MCPServerCapabilities {
+  tools?: { listChanged?: boolean }
+  resources?: { subscribe?: boolean; listChanged?: boolean }
+  prompts?: { listChanged?: boolean }
+  logging?: Record<string, never>
+  experimental?: Record<string, unknown>
+}
+
+export interface MCPInitializeParams {
+  protocolVersion: string
+  capabilities: MCPClientCapabilities
+  clientInfo: { name: string; version: string }
+}
+
+export interface MCPInitializeResult {
+  protocolVersion: string
+  capabilities: MCPServerCapabilities
+  serverInfo: { name: string; version?: string }
+}
+
+export type MCPConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error'
+
+export interface MCPClientConfig {
+  id?: MCPClientId
+  serverName: string
+  transport: MCPTransportUnion
+  capabilities?: MCPClientCapabilities
+  clientInfo?: { name: string; version: string }
+}
+
+export interface MCPClientState {
+  id: MCPClientId
+  serverName: string
+  status: MCPConnectionStatus
+  serverInfo?: { name: string; version?: string }
+  serverCapabilities?: MCPServerCapabilities
+  connectedAt?: number
+  error?: string
+}
+
+export interface MCPServerConfig {
+  id?: MCPServerId
+  name: string
+  version?: string
+  capabilities?: Partial<MCPServerCapabilities>
+}
+
+export interface MCPServerState {
+  id: MCPServerId
+  name: string
+  running: boolean
+  connectedClients: number
+  startedAt?: number
+}
+
+export interface MCPConnectorBridgeConfig {
+  manager: ConnectorManager
+  prefix?: string
+}
+
+export interface MCPConnectorBridgeToolMapping {
+  mcpToolName: string
+  connectorId: string
+  instanceId: ConnectorInstanceId
+  methodName: string
+}
+
+export interface MCPDiscoveredTool {
+  tool: MCPToolDefinition
+  clientId: MCPClientId
+  serverName: string
+}
+
+export type MCPLifecycleEvent =
+  | { type: 'mcp_client_connected'; clientId: MCPClientId; serverName: string }
+  | { type: 'mcp_client_disconnected'; clientId: MCPClientId }
+  | { type: 'mcp_client_error'; clientId: MCPClientId; error: string }
+  | { type: 'mcp_server_started'; serverId: MCPServerId }
+  | { type: 'mcp_server_stopped'; serverId: MCPServerId }
+  | { type: 'mcp_tool_called'; tool: string; clientId?: MCPClientId; serverId?: MCPServerId }
+  | { type: 'mcp_tools_changed'; clientId: MCPClientId }
+
+export type MCPEventListener = (event: MCPLifecycleEvent) => void
+
+type ConnectorManager = {
+  getInstance(instanceId: ConnectorInstanceId): ConnectorInstance | undefined
+  getRegistry(): { get(connectorId: string): ConnectorDefinition | undefined; getOrThrow(connectorId: string): ConnectorDefinition }
+  listConnectedInstances(): ConnectorInstance[]
+  execute(params: ConnectorExecuteParams): Promise<ConnectorExecuteResult>
+}

package/src/types/connector/scope.ts

@@ -0,0 +1,42 @@
+import type { AuthConfig } from './core.js'
+import type { ConnectorConfig } from './definition.js'
+
+export type ConnectorScope = 'org' | 'environment' | 'team' | 'project' | 'agent'
+
+export const CONNECTOR_SCOPE_ORDER: readonly ConnectorScope[] = [
+  'org',
+  'environment',
+  'team',
+  'project',
+  'agent',
+] as const
+
+export interface ScopeRef {
+  scope: ConnectorScope
+  scopeId: string
+}
+
+export interface ScopedConnectorConfig {
+  scope: ScopeRef
+  connectorId: string
+
+  config?: Partial<ConnectorConfig>
+
+  auth?: AuthConfig
+
+  enabled?: boolean
+
+  options?: Record<string, unknown>
+}
+
+export interface ResolvedConnectorConfig {
+  connectorId: string
+  config: ConnectorConfig
+  auth?: AuthConfig
+  enabled: boolean
+  options: Record<string, unknown>
+
+  resolvedFrom: ScopeRef[]
+}
+
+export type ScopeChain = Partial<Record<ConnectorScope, string>>