@namzu/sdk 0.1.1

package/src/types/rag/embedding.ts

@@ -0,0 +1,19 @@
+export interface EmbeddingProvider {
+  readonly id: string
+  readonly model: string
+  readonly dimensions: number
+
+  embed(texts: string[]): Promise<number[][]>
+  embedQuery(query: string): Promise<number[]>
+}
+
+export interface EmbeddingConfig {
+  model: string
+  dimensions?: number
+  batchSize?: number
+}
+
+export interface OpenRouterEmbeddingConfig extends EmbeddingConfig {
+  apiKey: string
+  baseUrl?: string
+}

package/src/types/rag/index.ts

@@ -0,0 +1,9 @@
+export * from './scope.js'
+export * from './storage.js'
+export * from './chunking.js'
+export * from './embedding.js'
+export * from './vector.js'
+export * from './retrieval.js'
+export * from './ingestion.js'
+export * from './knowledge-base.js'
+export * from './context.js'

package/src/types/rag/ingestion.ts

@@ -0,0 +1,20 @@
+import type { DocumentId, KnowledgeBaseId } from '../ids/index.js'
+import type { DocumentMetadata, TenantScope } from './scope.js'
+
+export interface IngestionResult {
+  documentId: DocumentId
+  chunkCount: number
+  totalTokens: number
+  durationMs: number
+}
+
+export interface IngestionPipeline {
+  ingest(
+    content: string,
+    metadata: DocumentMetadata,
+    scope: TenantScope,
+    knowledgeBaseId: KnowledgeBaseId,
+  ): Promise<IngestionResult>
+
+  remove(documentId: DocumentId): Promise<void>
+}

package/src/types/rag/knowledge-base.ts

@@ -0,0 +1,27 @@
+import type { DocumentId, KnowledgeBaseId } from '../ids/index.js'
+import type { DocumentMetadata } from './scope.js'
+import type { ChunkingConfig } from './chunking.js'
+import type { EmbeddingConfig } from './embedding.js'
+import type { RetrievalConfig, RetrievalQuery, RetrievalResult } from './retrieval.js'
+import type { IngestionResult } from './ingestion.js'
+
+export interface KnowledgeBaseConfig {
+  id?: KnowledgeBaseId
+  name: string
+  description?: string
+  tenantId: string
+  namespace?: string
+  chunking?: Partial<ChunkingConfig>
+  retrieval?: Partial<RetrievalConfig>
+  embedding?: EmbeddingConfig
+}
+
+export interface KnowledgeBase {
+  readonly id: KnowledgeBaseId
+  readonly config: KnowledgeBaseConfig
+
+  ingest(content: string, metadata?: DocumentMetadata): Promise<IngestionResult>
+  remove(documentId: DocumentId): Promise<void>
+  query(query: RetrievalQuery): Promise<RetrievalResult>
+  clear(): Promise<void>
+}

package/src/types/rag/retrieval.ts

@@ -0,0 +1,35 @@
+import type { ThreadId, KnowledgeBaseId } from '../ids/index.js'
+import type { TenantScope } from './scope.js'
+import type { VectorSearchResult } from './vector.js'
+
+export type RetrievalMode = 'vector' | 'keyword' | 'hybrid'
+
+export interface RetrievalConfig {
+  mode: RetrievalMode
+  topK: number
+  minScore?: number
+  hybridAlpha?: number
+}
+
+export interface RetrievalQuery {
+  text: string
+  threadId?: ThreadId
+  threadMessages?: string[]
+  config?: Partial<RetrievalConfig>
+}
+
+export interface RetrievalResult {
+  chunks: VectorSearchResult[]
+  query: string
+  expandedQuery?: string
+  mode: RetrievalMode
+  durationMs: number
+}
+
+export interface Retriever {
+  retrieve(
+    query: RetrievalQuery,
+    scope: TenantScope,
+    knowledgeBaseId?: KnowledgeBaseId,
+  ): Promise<RetrievalResult>
+}

package/src/types/rag/scope.ts

@@ -0,0 +1,13 @@
+export interface TenantScope {
+  tenantId: string
+  namespace?: string
+}
+
+export interface DocumentMetadata {
+  source?: string
+  title?: string
+  mimeType?: string
+  language?: string
+  tags?: string[]
+  [key: string]: unknown
+}

package/src/types/rag/storage.ts

@@ -0,0 +1,25 @@
+import type { DocumentId, KnowledgeBaseId, ChunkId } from '../ids/index.js'
+import type { DocumentMetadata } from './scope.js'
+
+export interface Document {
+  id: DocumentId
+  knowledgeBaseId: KnowledgeBaseId
+  tenantId: string
+  content: string
+  metadata: DocumentMetadata
+  createdAt: number
+  updatedAt: number
+}
+
+export interface Chunk {
+  id: ChunkId
+  documentId: DocumentId
+  knowledgeBaseId: KnowledgeBaseId
+  tenantId: string
+  content: string
+  index: number
+  tokenCount: number
+  embedding?: number[]
+  metadata: DocumentMetadata
+  createdAt: number
+}

package/src/types/rag/vector.ts

@@ -0,0 +1,24 @@
+import type { ChunkId, DocumentId, KnowledgeBaseId } from '../ids/index.js'
+import type { Chunk } from './storage.js'
+
+export interface VectorSearchResult {
+  chunk: Chunk
+  score: number
+}
+
+export interface VectorStoreQuery {
+  embedding: number[]
+  topK: number
+  tenantId: string
+  knowledgeBaseId?: KnowledgeBaseId
+  filter?: Record<string, unknown>
+  minScore?: number
+}
+
+export interface VectorStore {
+  upsert(chunks: Chunk[]): Promise<void>
+  search(query: VectorStoreQuery): Promise<VectorSearchResult[]>
+  delete(chunkIds: ChunkId[]): Promise<void>
+  deleteByDocument(documentId: DocumentId): Promise<void>
+  deleteByKnowledgeBase(knowledgeBaseId: KnowledgeBaseId, tenantId: string): Promise<void>
+}

package/src/types/run/config.ts

@@ -0,0 +1,50 @@
+import type { PermissionMode } from '../permission/index.js'
+import type { RunId } from '../ids/index.js'
+import type { ModelPricing } from '../../utils/cost.js'
+import type { Logger } from '../../utils/logger.js'
+
+export interface AgentRunConfig {
+  model: string
+  timeoutMs: number
+  maxResponseTokens?: number
+  tokenBudget: number
+  costLimitUsd?: number
+  maxIterations?: number
+  temperature?: number
+  env?: Record<string, string>
+  permissionMode?: PermissionMode
+}
+
+export interface RunPersistenceConfig {
+  runId: RunId
+  agentId: string
+  agentName: string
+  sessionConfig: AgentRunConfig
+  providerId: string
+  outputDir: string
+  pricing?: ModelPricing
+  log: Logger
+
+  parentRunId?: RunId
+
+  depth?: number
+}
+
+export interface RunStoreConfig {
+  baseDir: string
+  logger?: Logger
+}
+
+export interface LimitCheckerConfig {
+  tokenBudget: number
+  timeoutMs: number
+  costLimitUsd?: number
+  maxIterations: number
+  budgetWarningThreshold: number
+}
+
+export type SessionConfig = AgentRunConfig
+
+export type SessionManagerConfig = RunPersistenceConfig
+
+export type SessionStoreConfig = RunStoreConfig

package/src/types/run/events.ts

@@ -0,0 +1,159 @@
+import type { BaseAgentResult } from "../agent/base.js";
+import type { CostInfo, TokenUsage } from "../common/index.js";
+import type { CheckpointId, ToolCallSummary } from "../hitl/index.js";
+import type { ActivityId, PlanId, RunId, TaskId } from "../ids/index.js";
+import type { PlanStep } from "../plan/index.js";
+import type { ActivityStatus, ActivityType } from "../activity/index.js";
+import type { TaskStatus } from "../task/index.js";
+
+export type StopReason =
+	| "end_turn"
+	| "token_budget"
+	| "cost_limit"
+	| "timeout"
+	| "max_iterations"
+	| "cancelled"
+	| "plan_rejected"
+	| "paused"
+	| "error";
+
+export type RunEvent =
+	| { type: "run_started"; runId: RunId; systemPrompt?: string }
+	| { type: "iteration_started"; runId: RunId; iteration: number }
+	| {
+			type: "iteration_completed";
+			runId: RunId;
+			iteration: number;
+			hasToolCalls: boolean;
+	  }
+	| {
+			type: "llm_response";
+			runId: RunId;
+			content: string | null;
+			hasToolCalls: boolean;
+	  }
+	| {
+			type: "tool_executing";
+			runId: RunId;
+			toolName: string;
+			input: unknown;
+	  }
+	| {
+			type: "tool_completed";
+			runId: RunId;
+			toolName: string;
+			result: string;
+	  }
+	| {
+			type: "tool_review_requested";
+			runId: RunId;
+			toolCalls: ToolCallSummary[];
+			iteration: number;
+	  }
+	| {
+			type: "tool_review_completed";
+			runId: RunId;
+			decision: "approved" | "modified" | "rejected";
+	  }
+	| {
+			type: "checkpoint_created";
+			runId: RunId;
+			checkpointId: CheckpointId;
+			iteration: number;
+	  }
+	| {
+			type: "run_paused";
+			runId: RunId;
+			checkpointId: CheckpointId;
+			reason: string;
+	  }
+	| {
+			type: "run_resuming";
+			runId: RunId;
+			fromCheckpointId: CheckpointId;
+	  }
+	| { type: "run_completed"; runId: RunId; result: string }
+	| { type: "run_failed"; runId: RunId; error: string }
+	| {
+			type: "token_usage_updated";
+			runId: RunId;
+			usage: TokenUsage;
+			cost: CostInfo;
+	  }
+	| {
+			type: "activity_created";
+			runId: RunId;
+			activityId: ActivityId;
+			activityType: ActivityType;
+			description: string;
+	  }
+	| {
+			type: "activity_updated";
+			runId: RunId;
+			activityId: ActivityId;
+			status: ActivityStatus;
+			output?: unknown;
+			error?: string;
+	  }
+	| {
+			type: "plan_ready";
+			runId: RunId;
+			planId: PlanId;
+			title: string;
+			steps: PlanStep[];
+			summary?: string;
+	  }
+	| { type: "plan_approved"; runId: RunId; planId: PlanId }
+	| {
+			type: "plan_rejected";
+			runId: RunId;
+			planId: PlanId;
+			reason?: string;
+	  }
+	| {
+			type: "plan_step_updated";
+			runId: RunId;
+			planId: PlanId;
+			stepId: string;
+			status: PlanStep["status"];
+	  }
+	| {
+			type: "agent_pending";
+			runId: RunId;
+			taskId: TaskId;
+			parentAgentId: string;
+			childAgentId: string;
+			depth: number;
+	  }
+	| {
+			type: "agent_completed";
+			runId: RunId;
+			taskId: TaskId;
+			result: BaseAgentResult;
+	  }
+	| {
+			type: "agent_failed";
+			runId: RunId;
+			taskId: TaskId;
+			error: string;
+	  }
+	| { type: "agent_canceled"; runId: RunId; taskId: TaskId }
+	| {
+			type: "task_created";
+			runId: RunId;
+			taskId: TaskId;
+			subject: string;
+			status: TaskStatus;
+	  }
+	| {
+			type: "task_updated";
+			runId: RunId;
+			taskId: TaskId;
+			subject: string;
+			status: TaskStatus;
+			owner?: string;
+	  };
+
+export type RunEventListener = (
+	event: RunEvent,
+) => void | Promise<void>;

package/src/types/run/index.ts

@@ -0,0 +1,4 @@
+export * from './config.js'
+export * from './state.js'
+export * from './events.js'
+export * from './metadata.js'

package/src/types/run/metadata.ts

@@ -0,0 +1,39 @@
+import type { RunId, ThreadId, TaskId } from '../ids/index.js'
+import type { AgentStatus, TokenUsage, CostInfo } from '../common/index.js'
+import type { StopReason } from './events.js'
+
+export interface RunMetadata {
+  id: RunId
+  threadId: ThreadId
+  agentId: string
+  agentName: string
+  status: AgentStatus
+  config: RunConfigSnapshot
+  provider: string
+
+  parentRunId?: RunId
+  taskId?: TaskId
+  depth: number
+
+  tokenUsage: TokenUsage
+  costInfo: CostInfo
+  iterations: number
+  startedAt: number
+  endedAt?: number
+  durationMs?: number
+  stopReason?: StopReason
+  lastError?: string
+  result?: string
+
+  childRunIds?: RunId[]
+}
+
+export interface RunConfigSnapshot {
+  model: string
+  tokenBudget: number
+  timeoutMs: number
+  maxIterations?: number
+  temperature?: number
+  maxResponseTokens?: number
+  costLimitUsd?: number
+}

package/src/types/run/state.ts

@@ -0,0 +1,35 @@
+import type { AgentStatus, TokenUsage, CostInfo } from '../common/index.js'
+import type { Message } from '../message/index.js'
+import type { RunId } from '../ids/index.js'
+import type { AgentRunConfig } from './config.js'
+import type { StopReason } from './events.js'
+
+export interface RunStateMetadata {
+  agentId: string
+  agentName: string
+  config: AgentRunConfig
+  provider: string
+}
+
+export type SessionMetadata = RunStateMetadata
+
+export interface AgentRun {
+  id: RunId
+  status: AgentStatus
+  metadata: RunStateMetadata
+  messages: Message[]
+  tokenUsage: TokenUsage
+  costInfo: CostInfo
+  currentIteration: number
+  startedAt: number
+  endedAt?: number
+  stopReason?: StopReason
+  lastError?: string
+  result?: string
+
+  parentRunId?: RunId
+
+  depth?: number
+}
+
+export type AgentSession = AgentRun

package/src/types/skills/index.ts

@@ -0,0 +1,34 @@
+export interface SkillMetadata {
+  name: string
+
+  description: string
+
+  compatibility?: string
+
+  metadata?: Record<string, string>
+}
+
+export interface Skill {
+  metadata: SkillMetadata
+
+  body?: string
+
+  dirPath: string
+}
+
+export type SkillDisclosureLevel = 'metadata' | 'full' | 'assets'
+
+export interface SkillLoadResult {
+  skill: Skill
+  disclosureLevel: SkillDisclosureLevel
+
+  tokenEstimate: number
+}
+
+export interface SkillChain {
+  inherited: Skill[]
+
+  own: Skill[]
+
+  resolved: Skill[]
+}

package/src/types/task/index.ts

@@ -0,0 +1,97 @@
+import type { TaskId, RunId, TenantId } from '../ids/index.js'
+
+export type TaskStatus = 'pending' | 'in_progress' | 'completed'
+
+export function isTerminalTaskStatus(status: TaskStatus): boolean {
+  return status === 'completed'
+}
+
+export function assertTaskStatus(status: TaskStatus): void {
+  switch (status) {
+    case 'pending':
+    case 'in_progress':
+    case 'completed':
+      return
+    default: {
+      const _exhaustive: never = status
+      throw new Error(`Unknown TaskStatus: ${_exhaustive}`)
+    }
+  }
+}
+
+export interface Task {
+  readonly id: TaskId
+  readonly runId: RunId
+  readonly tenantId?: TenantId
+
+  subject: string
+
+  description?: string
+
+  activeForm?: string
+
+  status: TaskStatus
+
+  owner?: string
+
+  blocks: TaskId[]
+
+  blockedBy: TaskId[]
+
+  metadata?: Record<string, unknown>
+
+  createdAt: number
+  startedAt?: number
+  completedAt?: number
+}
+
+export type TaskEventType =
+  | 'task.created'
+  | 'task.updated'
+  | 'task.deleted'
+  | 'task.claimed'
+
+export interface TaskEvent {
+  type: TaskEventType
+  taskId: TaskId
+  task: Task
+  previousStatus?: TaskStatus
+  timestamp: number
+}
+
+export type TaskEventListener = (event: TaskEvent) => void
+
+export interface CreateTaskParams {
+  runId: RunId
+  tenantId?: TenantId
+  subject: string
+  description?: string
+  activeForm?: string
+  owner?: string
+  blockedBy?: TaskId[]
+  metadata?: Record<string, unknown>
+}
+
+export interface UpdateTaskParams {
+  subject?: string
+  description?: string
+  activeForm?: string
+  status?: TaskStatus
+  owner?: string
+  metadata?: Record<string, unknown>
+}
+
+export interface TaskStore {
+  create(params: CreateTaskParams): Promise<Task>
+  get(id: TaskId): Promise<Task | undefined>
+  update(id: TaskId, updates: UpdateTaskParams): Promise<Task | undefined>
+  delete(id: TaskId): Promise<boolean>
+  list(filter?: { status?: TaskStatus; owner?: string; runId?: RunId }): Promise<Task[]>
+
+  claim(id: TaskId, owner: string): Promise<Task | undefined>
+
+  block(blockerId: TaskId, blockedId: TaskId): Promise<void>
+
+  on(listener: TaskEventListener): () => void
+  reset(): Promise<void>
+}

package/src/types/telemetry/index.ts

@@ -0,0 +1,10 @@
+export type ExporterType = 'console' | 'otlp' | 'none'
+
+export interface TelemetryConfig {
+  serviceName: string
+  serviceVersion?: string
+  exporterType: ExporterType
+  otlpEndpoint?: string
+  otlpHeaders?: Record<string, string>
+  metricExportIntervalMs?: number
+}

package/src/types/tool/index.ts

@@ -0,0 +1,69 @@
+import type { z } from "zod";
+import type { Logger } from "../../utils/logger.js";
+import type { RunId } from "../ids/index.js";
+import type { PermissionMode } from "../permission/index.js";
+
+export interface ToolRegistryRef {
+	searchDeferred(query: string): ToolDefinition[];
+	activate(names: string[]): void;
+	getAvailability(name: string): ToolAvailability;
+}
+
+export interface ToolContext {
+	runId: RunId;
+	workingDirectory: string;
+	abortSignal: AbortSignal;
+	env: Record<string, string>;
+	log: (level: "info" | "warn" | "error", message: string) => void;
+	permissionContext?: {
+		mode: PermissionMode;
+		sessionId: string;
+		workingDirectory: string;
+	};
+
+	toolRegistry?: ToolRegistryRef;
+}
+
+export interface ToolResult {
+	success: boolean;
+	output: string;
+	data?: unknown;
+	error?: string;
+}
+
+export interface ToolDefinition<TInput = unknown> {
+	name: string;
+	description: string;
+	inputSchema: z.ZodType<TInput, z.ZodTypeDef, unknown>;
+	execute(input: TInput, context: ToolContext): Promise<ToolResult>;
+	permissions?: ToolPermission[];
+	category?: "filesystem" | "shell" | "network" | "analysis" | "custom";
+
+	isReadOnly?(input: TInput): boolean;
+	isDestructive?(input: TInput): boolean;
+	isConcurrencySafe?(input: TInput): boolean;
+}
+
+export type ToolPermission =
+	| "file_read"
+	| "file_write"
+	| "shell_execute"
+	| "network_access"
+	| "env_access";
+
+export interface LLMToolSchema {
+	type: "function";
+	function: {
+		name: string;
+		description: string;
+		parameters: Record<string, unknown>;
+	};
+}
+
+export type ToolAvailability = "deferred" | "active" | "suspended";
+
+export type ZodToJsonSchema = (schema: z.ZodType) => Record<string, unknown>;
+
+export interface ToolRegistryConfig {
+	logger?: Logger;
+}