@shareai-lab/kode-sdk 1.0.0-beta.8 → 2.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 shareAI-lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,311 +1,153 @@
-# Kode SDK v1.5.1
+# KODE SDK
 
-Event-driven Agent Model Client SDK for building long-running, collaborative AI agents.
+[English](./README.md) | [中文](./README.zh-CN.md)
 
-## Vision
-
-Transform the experience of collaborating with colleagues into a minimal yet sufficient API for **sending messages, giving instructions, interrupting, forking, and resuming** with long-running online Agents.
+> Event-driven, long-running AI Agent framework with enterprise-grade persistence and multi-agent collaboration.
 
 ## Features
 
-- **Event-Driven First**: Subscribe to data plane events (text/tools/usage), control plane callbacks (approvals/hooks)
-- **Multi-Agent Ready**: Long-running independent agents with colleague-style collaboration
-- **Strong Recovery**: 7-type breakpoint recovery; seals without inserting system text; defaults to READY state
-- **Forkable**: Safe-Fork-Points (SFP) naturally exist at tool results and text-only assistant messages
-- **Tool Safety**: Denial doesn't throw exceptions; rejected tool results are logged and auditable
-- **High Performance**: Concurrent tool execution (rate-limited), streaming model completion, incremental events (cursor/since)
-- **Extensible**: MCP tools, Sandbox drivers, Provider adapters, Store backends, Scheduler DSL
+- **Event-Driven Architecture** - Three-channel system (Progress/Control/Monitor) for clean separation of concerns
+- **Long-Running & Resumable** - Seven-stage checkpoints with Safe-Fork-Point for crash recovery
+- **Multi-Agent Collaboration** - AgentPool, Room messaging, and task delegation
+- **Enterprise Persistence** - SQLite/PostgreSQL support with unified WAL
+- **Cloud Sandbox** - [E2B](https://e2b.dev) integration for isolated remote code execution
+- **Extensible Ecosystem** - MCP tools, custom Providers, Skills system
 
 ## Quick Start
 
-```bash
-npm install kode-sdk
-```
-
-```typescript
-import { Agent, JSONStore, LocalSandbox, AnthropicProvider, builtin } from 'kode-sdk';
-
-const agent = new Agent({
-  sessionId: 'agent:assistant/session:demo',
-  provider: new AnthropicProvider(process.env.ANTHROPIC_API_KEY),
-  store: new JSONStore('./data'),
-  sandbox: LocalSandbox.local({ workDir: './workspace' }),
-  tools: [...builtin.fs({ workDir: './workspace' }), ...builtin.bash()],
-  system: 'You are a helpful assistant.',
-});
-
-// Send message
-await agent.send('Please list all files in the workspace');
-
-// Subscribe to events
-for await (const event of agent.subscribe()) {
-  if (event.type === 'text') {
-    console.log('Agent:', event.text);
-  }
-  if (event.type === 'state' && event.state === 'READY') {
-    break;
-  }
-}
-```
-
-## Core Concepts
-
-### 1. Agent States
-
-- **READY**: Waiting for user input
-- **BUSY**: Processing request or executing tools
-- **PAUSED**: Waiting for permission approval
-
-### 2. Safe-Fork-Points (SFP)
-
-SFPs are created when:
-- Tool results are written (`tool_result` blocks)
-- Assistant provides text-only response (no tools)
-
-Use SFPs to:
-- Fork sessions at safe states
-- Create bookmarks for rollback
-- Branch conversations
-
-### 3. Event System
-
-**MINIMAL Event Kinds** (default subscription):
-- `text_chunk`: Streaming text delta
-- `text`: Complete text content
-- `tool_use`: Tool invocation
-- `tool_result`: Tool execution result
-- `usage`: Token/cost metrics
-- `error`: Typed errors
-- `messages_update`: Message history changed
-
-**Additional Events** (opt-in):
-- `state`: Agent state changes
-- `commit`: SFP created
-- `permission_ask`: Approval required
-- `permission_decision`: Approval result
-- `resume`: Recovery from crash
-- `forked`: New session created
-
-### 4. Hooks
-
-Intercept and modify tool execution:
-
-```typescript
-agent.use({
-  preToolUse(call, ctx) {
-    // Validate, modify args, or deny
-    if (!ctx.sandbox.fs.isInside(call.args.file)) {
-      return { decision: 'deny', reason: 'path out of sandbox' };
-    }
-    // Request approval
-    return { decision: 'ask', meta: { title: 'File Access', path: call.args.file } };
-  },
-
-  postToolUse(outcome, ctx) {
-    // Trim large results
-    if (String(outcome.content).length > 100_000) {
-      const path = ctx.sandbox.fs.temp(`tool-${outcome.id}.log`);
-      ctx.sandbox.fs.write(path, outcome.content);
-      return { update: { content: `[Full output at ./${path}]` } };
-    }
-  },
-});
-```
-
-### 5. Scheduler
-
-Time-based and step-based triggers:
-
-```typescript
-agent.schedule()
-  .every('10m', () => agent.send('Status check'))
-  .everySteps(20, () => agent.send('Reminder: review security guidelines'))
-  .daily('09:00', () => agent.send('Daily report'))
-  .weekly('Mon 09:00', () => agent.send('Weekly summary'));
-```
-
-### 6. AgentPool
-
-Manage multiple agent instances:
-
-```typescript
-const pool = new AgentPool({
-  store: new JSONStore('./data'),
-  maxAgents: 50,
-});
-
-const agent = pool.create(sessionId, template, options);
-const existing = pool.get(sessionId);
-const agents = pool.list({ prefix: 'org:acme/' });
-```
-
-### 7. Room (Group Chat)
+**One-liner setup** (install dependencies and build):
 
-Multi-agent collaboration:
-
-```typescript
-const room = new Room(pool);
-room.join('alice', 'agent:pm/session:alice');
-room.join('bob', 'agent:dev/session:bob');
-
-// Direct mention
-await room.say('alice', '@bob Please review the PR');
-
-// Broadcast (excludes sender)
-await room.say('alice', 'Meeting at 3pm');
+```bash
+./quickstart.sh
 ```
 
-## Built-in Tools
+Or install as a dependency:
 
-### File System
-
-```typescript
-builtin.fs({ base: './workspace' })
+```bash
+npm install @shareai-lab/kode-sdk
 ```
 
-- `Fs.Read`: Read file contents
-- `Fs.Write`: Write/create files
-- `Fs.Edit`: Replace text in files
+Set environment variables:
 
-### Bash Commands
-
-```typescript
-builtin.bash({
-  allow: [/^git /, /^npm /],
-  block: [/rm -rf/, /sudo/],
-  approval: true,
-})
+<!-- tabs:start -->
+#### **Linux / macOS**
+```bash
+export ANTHROPIC_API_KEY=sk-...
+export ANTHROPIC_MODEL_ID=claude-sonnet-4-20250514  # optional, default: claude-sonnet-4-20250514
+export ANTHROPIC_BASE_URL=https://api.anthropic.com  # optional, default: https://api.anthropic.com
 ```
 
-- `Bash.Run`: Execute commands (foreground/background)
-- `Bash.Logs`: Get output from background shell
-- `Bash.Kill`: Terminate background shell
-
-### Task Delegation
-
-```typescript
-builtin.task({ subAgents: [FrontendAssistant, BackendAssistant] })
+#### **Windows (PowerShell)**
+```powershell
+$env:ANTHROPIC_API_KEY="sk-..."
+$env:ANTHROPIC_MODEL_ID="claude-sonnet-4-20250514"  # optional, default: claude-sonnet-4-20250514
+$env:ANTHROPIC_BASE_URL="https://api.anthropic.com"  # optional, default: https://api.anthropic.com
 ```
+<!-- tabs:end -->
 
-- `Task.Run`: Delegate work to specialized sub-agents
-
-## API Reference
-
-### Agent
+Minimal example:
 
 ```typescript
-// Send message (non-blocking)
-send(text: string): Promise<string>
-
-// Subscribe to events
-subscribe(opts?: { since?: number; kinds?: AgentEventKind[] }): AsyncIterable<AgentEvent>
-
-// Convenience: send + subscribe
-chat(text: string): AsyncIterable<AgentEvent>
-
-// Blocking: wait for complete response
-reply(text: string): Promise<string>
-
-// One-off LLM query
-askLLM(text: string, opts?): Promise<{ text: string; sessionId: string }>
+import { Agent, AnthropicProvider, JSONStore } from '@shareai-lab/kode-sdk';
 
-// Control
-interrupt(reason?: string): Promise<void>
-decide(permId: string, decision: 'allow' | 'deny', note?: string): Promise<void>
+const provider = new AnthropicProvider(
+  process.env.ANTHROPIC_API_KEY!,
+  process.env.ANTHROPIC_MODEL_ID
+);
 
-// Snapshot & Fork
-snapshot(label?: string): Promise<SnapshotId>
-fork(sel?: SnapshotId | { at?: string }): Agent
+const agent = await Agent.create({
+  provider,
+  store: new JSONStore('./.kode'),
+  systemPrompt: 'You are a helpful assistant.'
+});
 
-// Introspection
-status(): Promise<AgentStatus>
-info(): Promise<AgentInfo>
-history(opts?: { since?: number; limit?: number }): Promise<AgentEvent[]>
+// Subscribe to progress events
+for await (const envelope of agent.subscribe(['progress'])) {
+  if (envelope.event.type === 'text_chunk') {
+    process.stdout.write(envelope.event.delta);
+  }
+  if (envelope.event.type === 'done') break;
+}
 
-// Extension
-use(hooks: Hooks): this
-getHooks(): ReadonlyArray<RegisteredHook>
-registerTools(tools: Tool[]): this
-schedule(): AgentSchedulerHandle
-on(event: 'permission_ask' | 'error' | 'messages_update', handler: Function): this
+await agent.send('Hello!');
 ```
 
-## Session ID Format
+Run examples:
 
-```
-[org:{orgId}/][team:{teamId}/][user:{userId}/]agent:{template}/session:{rootId}[/fork:{forkId}]*
+```bash
+npm run example:getting-started    # Minimal chat
+npm run example:agent-inbox        # Event-driven inbox
+npm run example:approval           # Tool approval workflow
+npm run example:room               # Multi-agent collaboration
 ```
 
-Examples:
-- `agent:assistant/session:abc123`
-- `org:acme/team:eng/user:42/agent:pm/session:xyz789`
-- `agent:dev/session:main/fork:branch1/fork:branch2`
+## Architecture for Scale
 
-Snapshots:
-- `{sessionId}@sfp:{index}`
-- `{sessionId}@label:{slug}`
-
-## Examples
-
-See `examples/` directory:
-
-- **U1**: Next.js backend (send + subscribe via SSE)
-- **U2**: Permission approval flow
-- **U3**: Hook for path guard and result trimming
-- **U4**: Scheduler with time and step triggers
-- **U5**: Sub-agent task delegation
-- **U6**: Room group chat
-- **U7**: ChatDev team collaboration
-
-## Architecture
+For production deployments serving many users, we recommend the **Worker Microservice Pattern**:
 
 ```
-Core
- ├─ Agent          (推进引擎；事件管道；SFP 记录；Hook 执行)
- ├─ Events         (cursor/since；增量持久)
- ├─ Scheduler      (时间与 Steps 触发)
- ├─ Hooks          (pre/post tool；pre/post model)
- └─ API            (send/subscribe/chat/reply/askLLM/interrupt/decide/snapshot/fork/resume)
-
-Infra
- ├─ Providers      (Anthropic 直通；其余适配)
- ├─ Sandbox        (local/docker/k8s/remote/vfs)
- ├─ Store          (json/sqlite/postgres)
- ├─ Tools          (内置 FS/Bash/Task；MCP 适配)
- └─ Pool           (实例容器；限额；显式 resume)
+                        +------------------+
+                        |    Frontend      |  Next.js / SvelteKit (Vercel OK)
+                        +--------+---------+
+                                 |
+                        +--------v---------+
+                        |   API Gateway    |  Auth, routing, queue push
+                        +--------+---------+
+                                 |
+                        +--------v---------+
+                        |  Message Queue   |  Redis / SQS / NATS
+                        +--------+---------+
+                                 |
+            +--------------------+--------------------+
+            |                    |                    |
+   +--------v-------+   +--------v-------+   +--------v-------+
+   |   Worker 1     |   |   Worker 2     |   |   Worker N     |
+   | (KODE SDK)     |   | (KODE SDK)     |   | (KODE SDK)     |
+   | Long-running   |   | Long-running   |   | Long-running   |
+   +--------+-------+   +--------+-------+   +--------+-------+
+            |                    |                    |
+            +--------------------+--------------------+
+                                 |
+                        +--------v---------+
+                        | Distributed Store|  PostgreSQL / Redis
+                        +------------------+
 ```
 
-## Design Philosophy
-
-### Event-Driven First
-
-Default push **MINIMAL events only**. Other events require explicit opt-in via `kinds` parameter.
-
-This forces event-driven patterns and prevents "chaotic operations" on subscription interfaces.
-
-### Tool Safety
-
-Denial doesn't throw exceptions. Instead:
-- Returns `tool_result` with `ok: false`
-- Content explains reason for denial
-- Fully auditable trail
-
-### Strong Recovery
-
-7 breakpoint types (A-G):
-- A: Before model request
-- B: After model gives tool_use, before approval
-- C: During approval wait
-- D: In preToolUse hook
-- E: During tool execution
-- F: In postToolUse hook
-- G: During streaming response
-
-All recover by sealing incomplete operations (no system text injection) and returning to READY state.
-
-## Contributing
-
-Contributions welcome! Please see PRD and TDD in `Kode_SDK_v1.5.1.md` for detailed specifications.
+**Key Principles:**
+1. **API layer is stateless** - Can run on serverless
+2. **Workers are stateful** - Run KODE SDK, need long-running processes
+3. **Store is shared** - Single source of truth for agent state
+4. **Queue decouples** - Request handling from agent execution
+
+See [docs/en/guides/architecture.md](./docs/en/guides/architecture.md) for detailed deployment guides.
+
+## Supported Providers
+
+| Provider | Streaming | Tools | Reasoning | Files |
+|----------|-----------|-------|-----------|-------|
+| Anthropic | ✅ | ✅ | ✅ Extended Thinking | ✅ |
+| OpenAI | ✅ | ✅ | ✅ | ✅ |
+| Gemini | ✅ | ✅ | ✅ | ✅ |
+
+> **Note**: OpenAI-compatible services (DeepSeek, GLM, Qwen, Minimax, OpenRouter, etc.) can be used via `OpenAIProvider` with custom `baseURL` configuration. See [Providers Guide](./docs/en/guides/providers.md) for details.
+
+## Documentation
+
+| Section | Description |
+|---------|-------------|
+| **Getting Started** | |
+| [Installation](./docs/en/getting-started/installation.md) | Setup and configuration |
+| [Quickstart](./docs/en/getting-started/quickstart.md) | Build your first Agent |
+| [Concepts](./docs/en/getting-started/concepts.md) | Core concepts explained |
+| **Guides** | |
+| [Events](./docs/en/guides/events.md) | Three-channel event system |
+| [Tools](./docs/en/guides/tools.md) | Built-in tools & custom tools |
+| [Providers](./docs/en/guides/providers.md) | Model provider configuration |
+| [Database](./docs/en/guides/database.md) | SQLite/PostgreSQL persistence |
+| [Resume & Fork](./docs/en/guides/resume-fork.md) | Crash recovery & branching |
+| **Reference** | |
+| [API Reference](./docs/en/reference/api.md) | Complete API documentation |
+| [Examples](./docs/en/examples/playbooks.md) | All examples explained |
 
 ## License
 

package/README.zh-CN.md

@@ -0,0 +1,114 @@
+# KODE SDK
+
+[English](./README.md) | [中文](./README.zh-CN.md)
+
+> 事件驱动的长时运行 AI Agent 框架，支持企业级持久化和多 Agent 协作。
+
+## 核心特性
+
+- **事件驱动架构** - 三通道系统 (Progress/Control/Monitor) 清晰分离关注点
+- **长时运行与恢复** - 七段断点机制，支持 Safe-Fork-Point 崩溃恢复
+- **多 Agent 协作** - AgentPool、Room 消息、任务委派
+- **企业级持久化** - 支持 SQLite/PostgreSQL，统一 WAL 日志
+- **云端沙箱** - 集成 [E2B](https://e2b.dev)，提供隔离的远程代码执行环境
+- **可扩展生态** - MCP 工具、自定义 Provider、Skills 系统
+
+## 快速开始
+
+**一键启动**（安装依赖并构建）：
+
+```bash
+./quickstart.sh
+```
+
+或作为依赖安装：
+
+```bash
+npm install @shareai-lab/kode-sdk
+```
+
+设置环境变量：
+
+<!-- tabs:start -->
+#### **Linux / macOS**
+```bash
+export ANTHROPIC_API_KEY=sk-...
+export ANTHROPIC_MODEL_ID=claude-sonnet-4-20250514  # 可选，默认: claude-sonnet-4-20250514
+export ANTHROPIC_BASE_URL=https://api.anthropic.com  # 可选，默认: https://api.anthropic.com
+```
+
+#### **Windows (PowerShell)**
+```powershell
+$env:ANTHROPIC_API_KEY="sk-..."
+$env:ANTHROPIC_MODEL_ID="claude-sonnet-4-20250514"  # 可选，默认: claude-sonnet-4-20250514
+$env:ANTHROPIC_BASE_URL="https://api.anthropic.com"  # 可选，默认: https://api.anthropic.com
+```
+<!-- tabs:end -->
+
+最简示例：
+
+```typescript
+import { Agent, AnthropicProvider, JSONStore } from '@shareai-lab/kode-sdk';
+
+const provider = new AnthropicProvider(
+  process.env.ANTHROPIC_API_KEY!,
+  process.env.ANTHROPIC_MODEL_ID
+);
+
+const agent = await Agent.create({
+  provider,
+  store: new JSONStore('./.kode'),
+  systemPrompt: '你是一个乐于助人的助手。'
+});
+
+// 订阅 progress 事件
+for await (const envelope of agent.subscribe(['progress'])) {
+  if (envelope.event.type === 'text_chunk') {
+    process.stdout.write(envelope.event.delta);
+  }
+  if (envelope.event.type === 'done') break;
+}
+
+await agent.send('你好！');
+```
+
+运行示例：
+
+```bash
+npm run example:getting-started    # 最简对话
+npm run example:agent-inbox        # 事件驱动收件箱
+npm run example:approval           # 工具审批流程
+npm run example:room               # 多Agent协作
+```
+
+## 支持的 Provider
+
+| Provider | 流式输出 | 工具调用 | 推理 | 文件 |
+|----------|---------|---------|------|------|
+| Anthropic | ✅ | ✅ | ✅ Extended Thinking | ✅ |
+| OpenAI | ✅ | ✅ | ✅ | ✅ |
+| Gemini | ✅ | ✅ | ✅ | ✅ |
+
+> **说明**：OpenAI 兼容的服务（DeepSeek、GLM、Qwen、Minimax、OpenRouter 等）可以通过 `OpenAIProvider` 配置自定义 `baseURL` 来使用。详见 [Provider 配置指南](./docs/zh-CN/guides/providers.md)。
+
+## 文档
+
+| 章节 | 说明 |
+|------|------|
+| **入门指南** | |
+| [安装配置](./docs/zh-CN/getting-started/installation.md) | 环境配置与安装 |
+| [快速上手](./docs/zh-CN/getting-started/quickstart.md) | 创建第一个 Agent |
+| [核心概念](./docs/zh-CN/getting-started/concepts.md) | 核心概念详解 |
+| **使用指南** | |
+| [事件系统](./docs/zh-CN/guides/events.md) | 三通道事件系统 |
+| [工具系统](./docs/zh-CN/guides/tools.md) | 内置工具与自定义工具 |
+| [Provider 配置](./docs/zh-CN/guides/providers.md) | 模型 Provider 配置 |
+| [数据库存储](./docs/zh-CN/guides/database.md) | SQLite/PostgreSQL 持久化 |
+| [恢复与分叉](./docs/zh-CN/guides/resume-fork.md) | 崩溃恢复与分支 |
+| **参考** | |
+| [API 参考](./docs/zh-CN/reference/api.md) | 完整 API 文档 |
+| [示例集](./docs/zh-CN/examples/playbooks.md) | 所有示例详解 |
+
+## 许可证
+
+MIT

package/dist/core/agent/breakpoint-manager.d.ts

@@ -0,0 +1,16 @@
+import { BreakpointState } from '../types';
+export interface BreakpointEntry {
+    state: BreakpointState;
+    timestamp: number;
+    note?: string;
+}
+export declare class BreakpointManager {
+    private readonly onChange?;
+    private current;
+    private history;
+    constructor(onChange?: ((previous: BreakpointState, next: BreakpointState, entry: BreakpointEntry) => void) | undefined);
+    getCurrent(): BreakpointState;
+    getHistory(): ReadonlyArray<BreakpointEntry>;
+    set(state: BreakpointState, note?: string): void;
+    reset(state?: BreakpointState): void;
+}

package/dist/core/agent/breakpoint-manager.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BreakpointManager = void 0;
+class BreakpointManager {
+    constructor(onChange) {
+        this.onChange = onChange;
+        this.current = 'READY';
+        this.history = [];
+    }
+    getCurrent() {
+        return this.current;
+    }
+    getHistory() {
+        return this.history;
+    }
+    set(state, note) {
+        if (this.current === state)
+            return;
+        const entry = {
+            state,
+            timestamp: Date.now(),
+            note,
+        };
+        const previous = this.current;
+        this.current = state;
+        this.history.push(entry);
+        if (this.onChange) {
+            this.onChange(previous, state, entry);
+        }
+    }
+    reset(state = 'READY') {
+        this.current = state;
+        this.history = [];
+    }
+}
+exports.BreakpointManager = BreakpointManager;

package/dist/core/agent/message-queue.d.ts

@@ -0,0 +1,26 @@
+import { ContentBlock, Message } from '../types';
+import { ReminderOptions } from '../types';
+export type PendingKind = 'user' | 'reminder';
+export interface PendingMessage {
+    message: Message;
+    kind: PendingKind;
+    metadata?: Record<string, any>;
+}
+export interface SendOptions {
+    kind?: PendingKind;
+    metadata?: Record<string, any>;
+    reminder?: ReminderOptions;
+}
+export interface MessageQueueOptions {
+    wrapReminder(content: string, options?: ReminderOptions): string;
+    addMessage(message: Message, kind: PendingKind): void;
+    persist(): Promise<void>;
+    ensureProcessing(): void;
+}
+export declare class MessageQueue {
+    private readonly options;
+    private pending;
+    constructor(options: MessageQueueOptions);
+    send(content: string | ContentBlock[], opts?: SendOptions): string;
+    flush(): Promise<void>;
+}