Skip to content

Update doc and fix unit test #27

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
CrazyBoyM merged 4 commits into from
Jan 23, 2026
Merged

Update doc and fix unit test #27

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
14b37fe
doc reconstruction
Gui-Yue Jan 22, 2026
55c6675
Merge branch 'main' into update_doc_and_fix
Gui-Yue Jan 23, 2026
24eb1bc
upgrade doc
Gui-Yue Jan 23, 2026
e80d537
fix(tests): migrate pool-shutdown test to project test runner
Gui-Yue Jan 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@ test-cli.ts
# Ignore all markdown files except README.md and files in doc/docs folders
*.md
!README.md
!README.zh-CN.md
!ROADMAP.md
!doc/**/*.md
!docs/**/*.md
!tests/**/*.md
Expand Down
287 changes: 78 additions & 209 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,175 +1,84 @@
# KODE SDK

> **Stateful Agent Runtime Kernel** - The engine that powers your AI agents with persistence, recovery, and trajectory exploration.
[English](./README.md) | [中文](./README.zh-CN.md)

```
+------------------+
| Your App | CLI / Desktop / IDE / Server
+--------+---------+
|
+--------v---------+
| KODE SDK | Agent Runtime Kernel
| +-----------+ |
| | Agent | | Lifecycle + State + Events
| +-----------+ |
| | Store | | Persistence (Pluggable)
| +-----------+ |
| | Sandbox | | Execution Isolation
| +-----------+ |
+------------------+
```

---

## What is KODE SDK?

KODE SDK is an **Agent Runtime Kernel** - think of it like V8 for JavaScript, but for AI agents. It handles the complex lifecycle management so you can focus on building your agent's capabilities.

**Core Capabilities:**
- **Crash Recovery**: WAL-protected persistence with 7-stage breakpoint recovery
- **Fork & Resume**: Explore different agent trajectories from any checkpoint
- **Event Streams**: Progress/Control/Monitor channels for real-time UI updates
- **Tool Governance**: Permission system, approval workflows, audit trails

**What KODE SDK is NOT:**
- Not a cloud platform (you deploy it)
- Not an HTTP server (you add that layer)
- Not a multi-tenant SaaS framework (you build that on top)

---

## When to Use KODE SDK

### Perfect Fit (Use directly)

| Scenario | Why It Works |
|----------|--------------|
| **CLI Agent Tools** | Single process, local filesystem, zero config |
| **Desktop Apps** (Electron/Tauri) | Full system access, long-running process |
| **IDE Plugins** (VSCode/JetBrains) | Single user, workspace integration |
| **Local Development** | Fast iteration, instant persistence |

### Good Fit (With architecture)

| Scenario | What You Need |
|----------|---------------|
| **Self-hosted Server** | Add HTTP layer (Express/Fastify/Hono) |
| **Small-scale Backend** (<1K users) | Implement PostgresStore, add user isolation |
| **Kubernetes Deployment** | Implement distributed Store + locks |

### Needs Custom Architecture

| Scenario | Recommended Approach |
|----------|---------------------|
| **Large-scale ToC** (10K+ users) | Worker microservice pattern (see [Architecture Guide](./docs/ARCHITECTURE.md)) |
| **Serverless** (Vercel/Cloudflare) | API layer on serverless + Worker pool for agents |
| **Multi-tenant SaaS** | Tenant isolation layer + distributed Store |
> Event-driven, long-running AI Agent framework with enterprise-grade persistence and multi-agent collaboration.

### Not Designed For
## Features

| Scenario | Reason |
|----------|--------|
| **Pure browser runtime** | No filesystem, no process execution |
| **Edge functions only** | Agent loops need long-running processes |
| **Stateless microservices** | Agents are inherently stateful |
- **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
- **Extensible Ecosystem** - MCP tools, custom Providers, Skills system

> **Rule of Thumb**: If your agents need to run for more than a few seconds, execute tools, and remember state - KODE SDK is for you. If you just need stateless LLM calls, use the provider APIs directly.
## Quick Start

---

## 60-Second Quick Start
**One-liner setup** (install dependencies and build):

```bash
npm install @anthropic/kode-sdk

# Set your API key
export ANTHROPIC_API_KEY=sk-...

# Run the example
npx ts-node examples/getting-started.ts
```

```typescript
import { Agent, AnthropicProvider, LocalSandbox } from '@anthropic/kode-sdk';

const agent = await Agent.create({
agentId: 'my-first-agent',
template: { systemPrompt: 'You are a helpful assistant.' },
deps: {
modelProvider: new AnthropicProvider(process.env.ANTHROPIC_API_KEY!),
sandbox: new LocalSandbox({ workDir: './workspace' }),
},
});

// Subscribe to events
agent.subscribeProgress({ kinds: ['text_chunk'] }, (event) => {
process.stdout.write(event.text);
});

// Chat with the agent
await agent.chat('Hello! What can you help me with?');
./quickstart.sh
```

---

## Core Concepts
Or install as a dependency:

### 1. Three-Channel Event System

```
+-------------+ +-------------+ +-------------+
| Progress | | Control | | Monitor |
+-------------+ +-------------+ +-------------+
| text_chunk | | permission | | tool_audit |
| tool:start | | _required | | state_change|
| tool:complete| | approval | | token_usage |
| done | | _response | | error |
+-------------+ +-------------+ +-------------+
| | |
v v v
Your UI Approval Service Observability
```bash
npm install @shareai-lab/kode-sdk
```

### 2. Crash Recovery & Breakpoints
Set environment variables:

<!-- 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
```
Agent Execution Flow:

READY -> PRE_MODEL -> STREAMING -> TOOL_PENDING -> PRE_TOOL -> EXECUTING -> POST_TOOL
| | | | | | |
+-------- WAL Protected State -------+-- Approval --+---- Tool Execution ---+

On crash: Resume from last safe breakpoint, auto-seal incomplete tool calls
#### **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 -->

### 3. Fork & Trajectory Exploration
Minimal example:

```typescript
// Create a snapshot at current state
const snapshotId = await agent.snapshot('before-decision');
import { Agent, AnthropicProvider, JSONStore } from '@shareai-lab/kode-sdk';

// Fork to explore different paths
const explorerA = await agent.fork(snapshotId);
const explorerB = await agent.fork(snapshotId);
const provider = new AnthropicProvider(
process.env.ANTHROPIC_API_KEY!,
process.env.ANTHROPIC_MODEL_ID
);

await explorerA.chat('Try approach A');
await explorerB.chat('Try approach B');
```
const agent = await Agent.create({
provider,
store: new JSONStore('./.kode'),
systemPrompt: 'You are a helpful assistant.'
});

---
// 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;
}

## Examples
await agent.send('Hello!');
```

| Example | Description | Key Features |
|---------|-------------|--------------|
| `npm run example:getting-started` | Minimal chat loop | Progress stream, basic setup |
| `npm run example:agent-inbox` | Event-driven inbox | Todo management, tool concurrency |
| `npm run example:approval` | Approval workflow | Control channel, hooks, policies |
| `npm run example:room` | Multi-agent collaboration | AgentPool, Room, Fork |
| `npm run example:scheduler` | Long-running with reminders | Scheduler, step triggers |
| `npm run example:nextjs` | Next.js API integration | Resume-or-create, SSE streaming |
Run examples:

---
```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
```

## Architecture for Scale

Expand Down Expand Up @@ -209,76 +118,36 @@ For production deployments serving many users, we recommend the **Worker Microse
3. **Store is shared** - Single source of truth for agent state
4. **Queue decouples** - Request handling from agent execution

See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) for detailed deployment guides.

---

## Documentation

| Document | Description |
|----------|-------------|
| [Architecture Guide](./docs/ARCHITECTURE.md) | Mental model, deployment patterns, scaling strategies |
| [Quickstart](./docs/quickstart.md) | Step-by-step first agent |
| [Events System](./docs/events.md) | Three-channel event model |
| [API Reference](./docs/api.md) | Core types and interfaces |
| [Playbooks](./docs/playbooks.md) | Common patterns and recipes |
| [Deployment](./docs/DEPLOYMENT.md) | Production deployment guide |
| [Roadmap](./docs/ROADMAP.md) | Future development plans |

### Scenario Guides

| Scenario | Guide |
|----------|-------|
| CLI Tools | [docs/scenarios/cli-tools.md](./docs/scenarios/cli-tools.md) |
| Desktop Apps | [docs/scenarios/desktop-apps.md](./docs/scenarios/desktop-apps.md) |
| IDE Plugins | [docs/scenarios/ide-plugins.md](./docs/scenarios/ide-plugins.md) |
| Web Backend | [docs/scenarios/web-backend.md](./docs/scenarios/web-backend.md) |
| Large-scale ToC | [docs/scenarios/large-scale-toc.md](./docs/scenarios/large-scale-toc.md) |

---
See [docs/en/guides/architecture.md](./docs/en/guides/architecture.md) for detailed deployment guides.

## Supported Providers

| Provider | Streaming | Tool Calling | Thinking/Reasoning |
|----------|-----------|--------------|-------------------|
| **Anthropic** | SSE | Native | Extended Thinking |
| **OpenAI** | SSE | Function Calling | o1/o3 reasoning |
| **Gemini** | SSE | Function Calling | thinkingLevel |
| **DeepSeek** | SSE | OpenAI-compatible | reasoning_content |
| **Qwen** | SSE | OpenAI-compatible | thinking_budget |
| **Groq/Cerebras** | SSE | OpenAI-compatible | - |

---

## Roadmap
| Provider | Streaming | Tools | Reasoning | Files |
|----------|-----------|-------|-----------|-------|
| Anthropic | ✅ | ✅ | ✅ Extended Thinking | ✅ |
| OpenAI | ✅ | ✅ | ✅ | ✅ |
| Gemini | ✅ | ✅ | ✅ | ✅ |

### v2.8 - Storage Foundation
- PostgresStore with connection pooling
- Distributed locking (Advisory Lock)
- Graceful shutdown support
> **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.

### v3.0 - Performance
- Incremental message storage (append-only)
- Copy-on-Write fork optimization
- Event sampling and aggregation

### v3.5 - Distributed
- Agent Scheduler with LRU caching
- Distributed EventBus (Redis Pub/Sub)
- Worker mode helpers

See [docs/ROADMAP.md](./docs/ROADMAP.md) for the complete roadmap.

---

## Contributing
## Documentation

We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
| 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

MIT License - see [LICENSE](./LICENSE) for details.

---

**KODE SDK** - *The runtime kernel that lets you build agents that persist, recover, and explore.*
MIT
Loading