@a3s-lab/code 0.3.1 → 0.4.0

package/README.md

@@ -5,7 +5,7 @@
 </p>
 
 <p align="center">
-  <em>Full-featured gRPC client for building AI coding agent applications</em>
+  <em>Session-centric AI coding agent SDK with Vercel AI SDK-compatible convenience API</em>
 </p>
 
 <p align="center">
@@ -16,9 +16,10 @@
 </p>
 
 <p align="center">
-  <a href="#features">Features</a> •
-  <a href="#installation">Installation</a> •
   <a href="#quick-start">Quick Start</a> •
+  <a href="#session-api">Session API</a> •
+  <a href="#tool-calling">Tool Calling</a> •
+  <a href="#convenience-api">Convenience API</a> •
   <a href="#api-reference">API Reference</a> •
   <a href="./examples">Examples</a>
 </p>
@@ -27,572 +28,438 @@
 
 ## Overview
 
-**@a3s-lab/code** is the official TypeScript SDK for [A3S Code](https://github.com/a3s-lab/a3s), providing a complete gRPC client implementation for the CodeAgentService API. Build AI-powered coding assistants, IDE integrations, and automation tools with full access to A3S Code's capabilities.
-
-### Why This SDK?
-
-- **100% API Coverage**: All 53 RPCs from CodeAgentService fully implemented
-- **Type-Safe**: Full TypeScript definitions for all types and enums
-- **Async/Await**: Modern Promise-based API with streaming support
-- **Flexible Configuration**: Environment variables, config files, or programmatic setup
-- **Real-World Examples**: Comprehensive examples with real LLM API integration
-
-## Features
-
-| Category | Features |
-|----------|----------|
-| **Lifecycle** | Health check, capabilities, initialization, shutdown |
-| **Sessions** | Create, list, get, configure, destroy with persistence |
-| **Generation** | Streaming/non-streaming responses, structured output, context compaction |
-| **Tools** | Load/unload skills, list available tools, custom tool registration |
-| **Context** | Add/clear context, manage conversation history, usage monitoring |
-| **Control** | Abort operations, pause/resume, cancel confirmations |
-| **Events** | Subscribe to real-time agent events, tool execution tracking |
-| **HITL** | Human-in-the-loop confirmations, approval workflows |
-| **Permissions** | Fine-grained permission policies, tool access control |
-| **Todos** | Task tracking for multi-step workflows, goal management |
-| **Providers** | Multi-provider LLM configuration (Anthropic, OpenAI, KIMI, etc.) |
-| **Planning** | Execution plans, goal extraction, achievement checking |
-| **Memory** | Episodic/semantic/procedural memory storage and retrieval |
-| **Storage** | Configurable session storage (memory, file, custom) |
+**@a3s-lab/code** is the official TypeScript SDK for [A3S Code](https://github.com/a3s-lab/a3s). The SDK is session-centric — every interaction goes through a `Session` object:
+
+1. **Session API** — The core pattern. Create a session with `client.createSession()`, then call `session.generateText()`, `session.streamText()`, etc. Model and workspace are bound at creation time and immutable. Supports `await using` for automatic cleanup.
+
+2. **Convenience API** — Standalone functions (`generateText`, `streamText`, etc.) that create temporary sessions under the hood. Great for one-shot operations.
 
 ## Installation
 
 ```bash
 npm install @a3s-lab/code
-# or
-yarn add @a3s-lab/code
-# or
-pnpm add @a3s-lab/code
 ```
 
 ## Quick Start
 
-### Basic Usage
-
 ```typescript
-import { A3sClient } from '@a3s-lab/code';
+import { A3sClient, createProvider } from '@a3s-lab/code';
 
-// Create client with default config
-const client = new A3sClient();
-
-// Or with explicit address
 const client = new A3sClient({ address: 'localhost:4088' });
+const openai = createProvider({ name: 'openai', apiKey: 'sk-xxx' });
 
-// Or load from config file
-const client = new A3sClient({ configDir: '/path/to/.a3s' });
-
-async function main() {
-  // Check health
-  const health = await client.healthCheck();
-  console.log('Agent status:', health.status);
-
-  // Create a session
-  const session = await client.createSession({
-    name: 'my-session',
-    workspace: '/path/to/project',
-    systemPrompt: 'You are a helpful coding assistant.',
-  });
+// Create session — model and workspace bound here, immutable after
+await using session = await client.createSession({
+  model: openai('gpt-4o'),
+  workspace: '/project',
+  system: 'You are a helpful coding assistant.',
+});
 
-  // Generate a response (streaming)
-  for await (const chunk of client.streamGenerate(session.sessionId, [
-    { role: 'user', content: 'Explain this codebase structure' }
-  ])) {
-    if (chunk.type === 'CHUNK_TYPE_CONTENT' && chunk.content) {
-      process.stdout.write(chunk.content);
-    }
-  }
+// Generate text
+const { text } = await session.generateText({
+  prompt: 'Explain this codebase',
+});
+console.log(text);
 
-  // Clean up
-  await client.destroySession(session.sessionId);
-  client.close();
+// Stream text
+const { textStream } = session.streamText({
+  prompt: 'Now refactor it',
+});
+for await (const chunk of textStream) {
+  process.stdout.write(chunk);
 }
 
-main().catch(console.error);
-```
-
-### 📚 Complete Examples
-
-See the [examples](./examples) directory for comprehensive, runnable examples:
-
-| Example | Description | Run |
-|---------|-------------|-----|
-| [kimi-test.ts](./examples/src/kimi-test.ts) | Test with KIMI K2.5 model | `npm run kimi-test` |
-| [chat-simulation.ts](./examples/src/chat-simulation.ts) | Multi-turn chat with skills | `npm run chat` |
-| [code-generation-interactive.ts](./examples/src/code-generation-interactive.ts) | Interactive code generation | `npm run code-gen` |
-| [skill-usage-demo.ts](./examples/src/skill-usage-demo.ts) | Skill loading and usage | `npm run skill-demo` |
-| [simple-test.ts](./examples/src/simple-test.ts) | Basic SDK usage | `npm run dev` |
-| [storage-configuration.ts](./examples/src/storage-configuration.ts) | Memory vs file storage | `npm run storage` |
-| [hitl-confirmation.ts](./examples/src/hitl-confirmation.ts) | Human-in-the-loop | `npm run hitl` |
-| [provider-config.ts](./examples/src/provider-config.ts) | Provider management | `npm run provider` |
-| [context-management.ts](./examples/src/context-management.ts) | Context monitoring | `npm run context` |
-| [code-review-agent.ts](./examples/src/code-review-agent.ts) | Complete production example | `npm run code-review` |
-
-**Quick start with examples:**
-
-```bash
-cd examples
-npm install
-
-# Test with KIMI model (recommended)
-npm run kimi-test
+// Multi-turn: session remembers context
+const { text: followUp } = await session.generateText({
+  prompt: 'What about error handling?',
+});
 
-# Try chat simulation
-npm run chat
+// Context management
+const usage = await session.getContextUsage();
+await session.compactContext();
+// session.close() called automatically via `await using`
 ```
 
-See [examples/README.md](./examples/README.md) for detailed documentation and [TESTING_WITH_REAL_MODELS.md](./examples/TESTING_WITH_REAL_MODELS.md) for API configuration guide.
+## Session API
 
-## Usage Examples
+Sessions are the core concept in A3S Code. Each session binds a model and workspace at creation time (immutable). The session maintains conversation history, context, permissions, and tool state.
 
-### Multi-Turn Conversations
+### Session Lifecycle
 
 ```typescript
-import { A3sClient } from '@a3s-lab/code';
-
-const client = new A3sClient({ configDir: '~/.a3s' });
-
-async function multiTurnChat() {
-  await client.connect();
+import { A3sClient, createProvider } from '@a3s-lab/code';
 
-  const { sessionId } = await client.createSession({
-    name: 'chat-session',
-    workspace: '/path/to/project',
-  });
+const client = new A3sClient({ address: 'localhost:4088' });
+const openai = createProvider({ name: 'openai', apiKey: 'sk-xxx' });
 
-  // First turn
-  for await (const chunk of client.streamGenerate(sessionId, [
-    { role: 'user', content: 'List all TypeScript files in this project' }
-  ])) {
-    if (chunk.content) process.stdout.write(chunk.content);
-  }
+// Create session — model and workspace are immutable after creation
+const session = await client.createSession({
+  model: openai('gpt-4o'),
+  workspace: '/project',
+  system: 'You are a code reviewer.',
+});
 
-  // Second turn - context is preserved
-  for await (const chunk of client.streamGenerate(sessionId, [
-    { role: 'user', content: 'Now analyze the main entry point' }
-  ])) {
-    if (chunk.content) process.stdout.write(chunk.content);
-  }
+// Multi-turn conversation (session remembers context)
+await session.generateText({ prompt: 'Review the auth module' });
+await session.generateText({ prompt: 'What about error handling?' });
 
-  // Get conversation history
-  const { messages } = await client.getMessages(sessionId, { limit: 10 });
-  console.log(`\nConversation has ${messages.length} messages`);
+// Context management
+const usage = await session.getContextUsage();
+console.log(`Tokens: ${usage?.totalTokens}`);
+await session.compactContext();  // Compress when large
 
-  await client.destroySession(sessionId);
-  client.close();
-}
+// Cleanup
+await session.close();
 ```
 
-### Event Subscription
+### Auto-Cleanup with `using`
 
 ```typescript
-import { A3sClient } from '@a3s-lab/code';
-
-const client = new A3sClient();
-
-async function subscribeToEvents() {
-  await client.connect();
-
-  const { sessionId } = await client.createSession({
-    name: 'event-demo',
-    workspace: '/tmp/workspace',
+// `await using` calls session.close() automatically when the block exits
+{
+  await using session = await client.createSession({
+    model: openai('gpt-4o'),
+    workspace: '/project',
   });
 
-  // Subscribe to all events
-  const eventStream = client.subscribeEvents(sessionId);
+  const { text } = await session.generateText({ prompt: 'Hello' });
+  // session.close() called automatically here
+}
+```
 
-  // Handle events in background
-  (async () => {
-    for await (const event of eventStream) {
-      console.log(`[${event.type}] ${event.message}`);
+### Streaming
 
-      if (event.type === 'EVENT_TYPE_TOOL_CALLED') {
-        console.log(`  Tool: ${event.metadata?.tool_name}`);
-      }
+```typescript
+const { textStream, fullStream, toolStream, text, steps } = session.streamText({
+  prompt: 'Explain this codebase',
+  tools: { weather: weatherTool },
+  maxSteps: 5,
+});
 
-      if (event.type === 'EVENT_TYPE_CONFIRMATION_REQUIRED') {
-        console.log(`  Confirmation needed for: ${event.metadata?.tool_name}`);
-      }
-    }
-  })();
+// Text-only stream
+for await (const chunk of textStream) {
+  process.stdout.write(chunk);
+}
 
-  // Generate with tool usage
-  for await (const chunk of client.streamGenerate(sessionId, [
-    { role: 'user', content: 'Read the README.md file' }
-  ])) {
-    if (chunk.content) process.stdout.write(chunk.content);
+// Or full event stream
+for await (const chunk of fullStream) {
+  switch (chunk.type) {
+    case 'content':
+      process.stdout.write(chunk.content);
+      break;
+    case 'tool_call':
+      console.log(`Tool: ${chunk.toolCall?.name}`);
+      break;
+    case 'done':
+      console.log(`\nFinish: ${chunk.finishReason}`);
+      break;
   }
-
-  await client.destroySession(sessionId);
-  client.close();
 }
 ```
 
-### Human-in-the-Loop (HITL)
+### Structured Output
 
 ```typescript
-import { A3sClient } from '@a3s-lab/code';
-
-const client = new A3sClient();
-
-async function hitlDemo() {
-  await client.connect();
-
-  const { sessionId } = await client.createSession({
-    name: 'hitl-demo',
-    workspace: '/path/to/project',
-  });
-
-  // Set confirmation policy - require approval for bash commands
-  await client.setConfirmationPolicy(sessionId, {
-    defaultAction: 'TIMEOUT_ACTION_REJECT',
-    timeoutMs: 30000,
-    rules: [
-      {
-        toolPattern: 'bash',
-        action: 'TIMEOUT_ACTION_REJECT',
-        requireConfirmation: true,
-      }
-    ]
-  });
-
-  // Subscribe to events to detect confirmation requests
-  const eventStream = client.subscribeEvents(sessionId);
-
-  (async () => {
-    for await (const event of eventStream) {
-      if (event.type === 'EVENT_TYPE_CONFIRMATION_REQUIRED') {
-        const toolName = event.metadata?.tool_name;
-        const toolArgs = event.metadata?.tool_args;
-
-        console.log(`\nConfirmation required:`);
-        console.log(`  Tool: ${toolName}`);
-        console.log(`  Args: ${toolArgs}`);
-
-        // Auto-approve for demo (in real app, prompt user)
-        const approved = true;
+// Unary
+const { object, data, usage } = await session.generateObject({
+  schema: JSON.stringify({
+    type: 'object',
+    properties: { summary: { type: 'string' }, files: { type: 'array' } },
+  }),
+  prompt: 'Analyze this project',
+});
 
-        await client.confirmToolExecution(sessionId, {
-          approved,
-          reason: approved ? 'User approved' : 'User rejected',
-        });
-      }
-    }
-  })();
+// Streaming
+const { partialStream, object: finalObject } = session.streamObject({
+  schema: '{"type":"object","properties":{"items":{"type":"array"}}}',
+  prompt: 'List project dependencies',
+});
+for await (const partial of partialStream) {
+  process.stdout.write(partial);
+}
+const result = await finalObject;
+```
 
-  // This will trigger confirmation
-  for await (const chunk of client.streamGenerate(sessionId, [
-    { role: 'user', content: 'Run "ls -la" command' }
-  ])) {
-    if (chunk.content) process.stdout.write(chunk.content);
-  }
+### Events (Low-Level Client)
 
-  await client.destroySession(sessionId);
-  client.close();
+```typescript
+for await (const event of client.subscribeEvents(session.id)) {
+  console.log(`[${event.type}] ${event.message}`);
 }
 ```
 
-### Permission Policies
+## Tool Calling
+
+Define client-side tools with `tool()` and enable multi-step agent behavior with `maxSteps`:
 
 ```typescript
-import { A3sClient } from '@a3s-lab/code';
+import { A3sClient, createProvider, tool } from '@a3s-lab/code';
 
 const client = new A3sClient();
+const openai = createProvider({ name: 'openai', apiKey: 'sk-xxx' });
+
+const weather = tool({
+  description: 'Get weather for a city',
+  parameters: {
+    type: 'object',
+    properties: {
+      city: { type: 'string', description: 'City name' },
+    },
+    required: ['city'],
+  },
+  execute: async ({ city }) => ({
+    city,
+    temperature: 72,
+    condition: 'sunny',
+  }),
+});
 
-async function permissionDemo() {
-  await client.connect();
-
-  const { sessionId } = await client.createSession({
-    name: 'permission-demo',
-    workspace: '/path/to/project',
-  });
+await using session = await client.createSession({
+  model: openai('gpt-4o'),
+  system: 'You are a helpful assistant with weather tools.',
+});
 
-  // Set permission policy - read-only mode
-  await client.setPermissionPolicy(sessionId, {
-    defaultDecision: 'PERMISSION_DECISION_DENY',
-    rules: [
-      {
-        toolPattern: 'read',
-        decision: 'PERMISSION_DECISION_ALLOW',
-      },
-      {
-        toolPattern: 'grep',
-        decision: 'PERMISSION_DECISION_ALLOW',
-      },
-      {
-        toolPattern: 'glob',
-        decision: 'PERMISSION_DECISION_ALLOW',
-      },
-      {
-        toolPattern: 'ls',
-        decision: 'PERMISSION_DECISION_ALLOW',
-      },
-      {
-        toolPattern: 'write',
-        decision: 'PERMISSION_DECISION_DENY',
-      },
-      {
-        toolPattern: 'bash',
-        decision: 'PERMISSION_DECISION_ASK',
-      }
-    ]
-  });
+// Multi-step: model calls tools, gets results, continues reasoning
+const { text, steps } = await session.generateText({
+  prompt: 'What is the weather in Tokyo and Paris?',
+  tools: { weather },
+  maxSteps: 5,
+  onStepFinish: (step) => {
+    console.log(`Step ${step.stepIndex}: ${step.toolCalls.length} tool calls`);
+  },
+  onToolCall: ({ toolName, args }) => {
+    console.log(`Calling ${toolName}`, args);
+  },
+});
 
-  // Check permission before operation
-  const canWrite = await client.checkPermission(sessionId, {
-    toolName: 'write',
-    args: { file_path: '/tmp/test.txt' }
-  });
+console.log(text);
+console.log(`Completed in ${steps.length} steps`);
+```
 
-  console.log(`Can write: ${canWrite.decision === 'PERMISSION_DECISION_ALLOW'}`);
+### Streaming with Tools
 
-  // This will be allowed (read-only tools)
-  for await (const chunk of client.streamGenerate(sessionId, [
-    { role: 'user', content: 'List all files in the current directory' }
-  ])) {
-    if (chunk.content) process.stdout.write(chunk.content);
-  }
+```typescript
+const { textStream, toolStream } = session.streamText({
+  prompt: 'Check the weather everywhere',
+  tools: { weather },
+  maxSteps: 5,
+});
 
-  await client.destroySession(sessionId);
-  client.close();
+for await (const chunk of textStream) {
+  process.stdout.write(chunk);
 }
 ```
 
-### Provider Configuration
+### Tools Without Execute (onToolCall)
 
 ```typescript
-import { A3sClient } from '@a3s-lab/code';
-
-const client = new A3sClient();
-
-async function providerDemo() {
-  await client.connect();
-
-  // List available providers
-  const { providers } = await client.listProviders();
-  console.log('Available providers:', providers.map(p => p.name));
-
-  // Add a new provider
-  await client.addProvider({
-    name: 'openai',
-    apiKey: 'sk-...',
-    baseUrl: 'https://api.openai.com/v1',
-    models: [
-      {
-        id: 'gpt-4',
-        name: 'GPT-4',
-        family: 'gpt',
-        toolCall: true,
-      }
-    ]
-  });
-
-  // Set default model
-  await client.setDefaultModel('openai', 'gpt-4');
-
-  // Get current default
-  const { provider, model } = await client.getDefaultModel();
-  console.log(`Default: ${provider}/${model}`);
-
-  // Create session with specific model
-  const { sessionId } = await client.createSession({
-    name: 'openai-session',
-    workspace: '/tmp/workspace',
-    llmConfig: {
-      provider: 'openai',
-      model: 'gpt-4',
-      temperature: 0.7,
+const { text } = await session.generateText({
+  prompt: 'Look up the user profile',
+  tools: {
+    getUser: tool({
+      description: 'Get user profile by ID',
+      parameters: {
+        type: 'object',
+        properties: { userId: { type: 'string' } },
+      },
+      // No execute — handled by onToolCall
+    }),
+  },
+  maxSteps: 3,
+  onToolCall: async ({ toolName, args }) => {
+    if (toolName === 'getUser') {
+      return { name: 'Alice', role: 'admin' };
     }
-  });
-
-  await client.destroySession(sessionId);
-  client.close();
-}
+  },
+});
 ```
 
-### Context Management
+## Convenience API
+
+Standalone functions that create temporary sessions under the hood. Useful for one-shot operations:
 
 ```typescript
-import { A3sClient } from '@a3s-lab/code';
+import { generateText, streamText, createProvider } from '@a3s-lab/code';
 
-const client = new A3sClient();
+const openai = createProvider({ name: 'openai', apiKey: 'sk-xxx' });
 
-async function contextDemo() {
-  await client.connect();
+// One-shot generation (auto session)
+const { text } = await generateText({
+  model: openai('gpt-4o'),
+  prompt: 'Explain this codebase',
+  workspace: '/project',
+});
 
-  const { sessionId } = await client.createSession({
-    name: 'context-demo',
-    workspace: '/path/to/project',
-  });
+// Streaming (auto session)
+const { textStream } = streamText({
+  model: openai('gpt-4o'),
+  prompt: 'Explain this codebase',
+});
+for await (const chunk of textStream) {
+  process.stdout.write(chunk);
+}
+```
 
-  // Have a long conversation...
-  for (let i = 0; i < 10; i++) {
-    await client.generate(sessionId, [
-      { role: 'user', content: `Question ${i + 1}: Tell me about this project` }
-    ]);
-  }
+### createChat (Convenience Wrapper)
 
-  // Check context usage
-  const usage = await client.getContextUsage(sessionId);
-  console.log(`Context tokens: ${usage.totalTokens}/${usage.maxTokens}`);
-  console.log(`Messages: ${usage.messageCount}`);
+`createChat()` is a convenience wrapper that manages a session internally:
 
-  if (usage.totalTokens > usage.maxTokens * 0.8) {
-    console.log('Context is getting full, compacting...');
+```typescript
+import { createChat, createProvider } from '@a3s-lab/code';
 
-    // Compact context using LLM summarization
-    const result = await client.compactContext(sessionId);
-    console.log(`Compacted: ${result.originalMessages} → ${result.compactedMessages} messages`);
-    console.log(`Saved: ${result.tokensSaved} tokens`);
-  }
+const openai = createProvider({ name: 'openai', apiKey: 'sk-xxx' });
 
-  await client.destroySession(sessionId);
-  client.close();
+const chat = createChat({
+  model: openai('gpt-4o'),
+  workspace: '/project',
+  system: 'You are a helpful code assistant',
+});
+
+const { text } = await chat.send('What does main.rs do?');
+const { textStream } = chat.stream('Now refactor it');
+for await (const chunk of textStream) {
+  process.stdout.write(chunk);
 }
+await chat.close();
 ```
 
-### Skills Management
+For new code, prefer using `Session` directly — it provides the same functionality with more control.
 
-```typescript
-import { A3sClient } from '@a3s-lab/code';
-import { readFileSync } from 'fs';
+## Message Conversion (UIMessage ↔ ModelMessage)
 
-const client = new A3sClient();
+The SDK provides Vercel AI SDK-style message types for frontend ↔ backend conversion:
 
-async function skillsDemo() {
-  await client.connect();
-
-  const { sessionId } = await client.createSession({
-    name: 'skills-demo',
-    workspace: '/path/to/project',
-  });
+- `UIMessage` — Frontend format with `id`, `createdAt`, `parts` (for rendering in chat UIs)
+- `ModelMessage` — Backend format with `role`, `content` (for LLM / generateText / streamText)
 
-  // Load a custom skill from markdown file
-  const skillContent = readFileSync('./my-skill.md', 'utf-8');
+### Frontend → Backend
 
-  await client.loadSkill(sessionId, 'my-custom-tool', skillContent);
-
-  // List all available skills
-  const { skills } = await client.listSkills(sessionId);
-  console.log('Available skills:', skills.map(s => s.name));
-
-  // Use the custom skill
-  for await (const chunk of client.streamGenerate(sessionId, [
-    { role: 'user', content: 'Use my-custom-tool to process data' }
-  ])) {
-    if (chunk.content) process.stdout.write(chunk.content);
-  }
+```typescript
+import { convertToModelMessages, generateText, createProvider } from '@a3s-lab/code';
+import type { UIMessage } from '@a3s-lab/code';
+
+const openai = createProvider({ name: 'openai', apiKey: 'sk-xxx' });
+
+// UIMessages from your frontend (e.g., useChat hook, database, etc.)
+const uiMessages: UIMessage[] = [
+  {
+    id: 'msg-1',
+    role: 'user',
+    content: 'What does main.rs do?',
+    parts: [{ type: 'text', text: 'What does main.rs do?' }],
+    createdAt: new Date(),
+  },
+];
+
+// Convert to model format before calling generateText/streamText
+const modelMessages = convertToModelMessages(uiMessages);
+const { text } = await generateText({
+  model: openai('gpt-4o'),
+  messages: modelMessages,
+});
+```
 
-  // Unload the skill
-  await client.unloadSkill(sessionId, 'my-custom-tool');
+### Backend → Frontend
 
-  await client.destroySession(sessionId);
-  client.close();
-}
+```typescript
+import { convertToUIMessages } from '@a3s-lab/code';
+import type { ModelMessage } from '@a3s-lab/code';
+
+// ModelMessages from LLM response or database
+const modelMessages: ModelMessage[] = [
+  { role: 'user', content: 'Hello' },
+  { role: 'assistant', content: 'Hi! How can I help?' },
+];
+
+// Convert to UIMessage format for rendering
+const uiMessages = convertToUIMessages(modelMessages);
+// uiMessages[0].parts → [{ type: 'text', text: 'Hello' }]
+// uiMessages[1].parts → [{ type: 'text', text: 'Hi! How can I help?' }]
 ```
 
-### Todo/Task Tracking
+### A3S Message ↔ UIMessage (Shorthand)
 
 ```typescript
-import { A3sClient } from '@a3s-lab/code';
+import { a3sMessagesToUI, uiMessagesToA3s } from '@a3s-lab/code';
 
-const client = new A3sClient();
+// A3S session messages → UIMessage (for rendering)
+const messages = await client.getMessages(sessionId);
+const uiMessages = a3sMessagesToUI(messages.messages);
 
-async function todoDemo() {
-  await client.connect();
+// UIMessage → A3S messages (for session generation)
+const a3sMessages = uiMessagesToA3s(uiMessages);
+await client.generate(sessionId, a3sMessages);
+```
 
-  const { sessionId } = await client.createSession({
-    name: 'todo-demo',
-    workspace: '/path/to/project',
-  });
+### Tool Invocations in UIMessage
 
-  // Set initial todos
-  await client.setTodos(sessionId, [
+UIMessages support rich tool invocation parts for rendering tool calls in chat UIs:
+
+```typescript
+const assistantMessage: UIMessage = {
+  id: 'msg-2',
+  role: 'assistant',
+  content: 'The weather in Tokyo is 22°C.',
+  parts: [
     {
-      id: '1',
-      title: 'Analyze codebase structure',
-      description: 'Understand the project layout',
-      completed: false,
+      type: 'tool-invocation',
+      toolInvocation: {
+        toolCallId: 'call-1',
+        toolName: 'weather',
+        args: { city: 'Tokyo' },
+        state: 'result',
+        result: { temperature: 22, condition: 'sunny' },
+      },
     },
-    {
-      id: '2',
-      title: 'Fix bug in authentication',
-      description: 'User login fails with invalid token',
-      completed: false,
-    }
-  ]);
-
-  // Agent works on tasks...
-  await client.generate(sessionId, [
-    { role: 'user', content: 'Complete the first todo item' }
-  ]);
-
-  // Get updated todos
-  const { todos } = await client.getTodos(sessionId);
-  console.log('Todos:');
-  todos.forEach(todo => {
-    const status = todo.completed ? '✓' : '○';
-    console.log(`  ${status} ${todo.title}`);
-  });
+    { type: 'text', text: 'The weather in Tokyo is 22°C and sunny.' },
+  ],
+};
 
-  await client.destroySession(sessionId);
-  client.close();
-}
+// Converts to: assistant message with toolCalls + tool result message
+const modelMessages = convertToModelMessages([assistantMessage]);
 ```
 
-### Operation Control
+## Structured Output
 
 ```typescript
-import { A3sClient } from '@a3s-lab/code';
-
-const client = new A3sClient();
-
-async function controlDemo() {
-  await client.connect();
-
-  const { sessionId } = await client.createSession({
-    name: 'control-demo',
-    workspace: '/path/to/project',
-  });
-
-  // Start a long-running operation
-  const generatePromise = (async () => {
-    for await (const chunk of client.streamGenerate(sessionId, [
-      { role: 'user', content: 'Analyze all files in this large project' }
-    ])) {
-      if (chunk.content) process.stdout.write(chunk.content);
-    }
-  })();
-
-  // Cancel after 5 seconds
-  setTimeout(async () => {
-    console.log('\nCancelling operation...');
-    await client.cancel(sessionId);
-  }, 5000);
-
-  try {
-    await generatePromise;
-  } catch (error) {
-    console.log('Operation was cancelled');
-  }
-
-  // Pause and resume
-  await client.pause(sessionId);
-  console.log('Session paused');
+import { generateObject, streamObject, createProvider } from '@a3s-lab/code';
+
+const openai = createProvider({ name: 'openai', apiKey: 'sk-xxx' });
+
+// Generate a typed object
+const { object } = await generateObject({
+  model: openai('gpt-4o'),
+  schema: JSON.stringify({
+    type: 'object',
+    properties: {
+      summary: { type: 'string' },
+      files: { type: 'array', items: { type: 'string' } },
+      complexity: { type: 'string', enum: ['low', 'medium', 'high'] },
+    },
+    required: ['summary', 'files', 'complexity'],
+  }),
+  prompt: 'Analyze this project structure',
+  workspace: '/project',
+});
 
-  await client.resume(sessionId);
-  console.log('Session resumed');
+// Stream partial results
+const { partialStream, object: finalObject } = streamObject({
+  model: openai('gpt-4o'),
+  schema: '{"type":"object","properties":{"items":{"type":"array"}}}',
+  prompt: 'List all project dependencies',
+});
 
-  await client.destroySession(sessionId);
-  client.close();
+for await (const partial of partialStream) {
+  process.stdout.write(partial);
 }
+const result = await finalObject;
 ```
 
 ## Configuration
 
 ### Using Real LLM APIs
 
-The SDK requires a running A3S Code service configured with real LLM API credentials. See [examples/TESTING_WITH_REAL_MODELS.md](./examples/TESTING_WITH_REAL_MODELS.md) for detailed setup instructions.
+The SDK requires a running A3S Code service. See [examples/TESTING_WITH_REAL_MODELS.md](./examples/TESTING_WITH_REAL_MODELS.md) for detailed setup.
 
 **Quick setup:**
 
@@ -639,31 +506,28 @@ cd /path/to/a3s
 ./target/debug/a3s-code -d .a3s -w /tmp/a3s-workspace
 ```
 
-3. **Use SDK with config:**
+3. **Use SDK:**
 
 ```typescript
-import { A3sClient } from '@a3s-lab/code';
+import { A3sClient, loadConfigFromDir } from '@a3s-lab/code';
 
-// Load configuration from A3S Code config directory
+const config = loadConfigFromDir('/path/to/a3s/.a3s');
 const client = new A3sClient({
-  address: 'localhost:4088',
-  configDir: '/path/to/a3s/.a3s'
+  address: config.address || 'localhost:4088',
+  configDir: '/path/to/a3s/.a3s',
 });
 
-// Create session - will use default model from config
-const session = await client.createSession({
+// Create session — uses default model from config
+const { sessionId } = await client.createSession({
   name: 'my-session',
-  workspace: '/tmp/workspace'
+  workspace: '/tmp/workspace',
 });
 
 // Or specify model explicitly
-const session = await client.createSession({
+const { sessionId: s2 } = await client.createSession({
   name: 'my-session',
   workspace: '/tmp/workspace',
-  llm: {
-    provider: 'openai',
-    model: 'kimi-k2.5'
-  }
+  llm: { provider: 'openai', model: 'kimi-k2.5' },
 });
 ```
 
@@ -674,48 +538,46 @@ const session = await client.createSession({
 | `A3S_ADDRESS` | gRPC server address | `localhost:4088` |
 | `A3S_CONFIG_DIR` | Configuration directory | - |
 
-### Programmatic Configuration
-
-```typescript
-import { A3sClient, loadConfigFromDir } from '@a3s-lab/code';
-
-// Load config from directory
-const config = loadConfigFromDir('/path/to/.a3s');
-
-// Create client with loaded config
-const client = new A3sClient({
-  address: config.address || 'localhost:4088',
-  configDir: '/path/to/.a3s'
-});
-
-// Access config values
-console.log('Default provider:', config.defaultProvider);
-console.log('Default model:', config.defaultModel);
-console.log('API key:', config.apiKey ? '(set)' : '(not set)');
-```
-
-### Legacy Config File Format
-
-```json
-{
-  "address": "localhost:4088",
-  "defaultProvider": "anthropic",
-  "defaultModel": "claude-sonnet-4-20250514",
-  "providers": [
-    {
-      "name": "anthropic",
-      "apiKey": "sk-ant-...",
-      "models": [
-        { "id": "claude-sonnet-4-20250514", "name": "Claude Sonnet 4" }
-      ]
-    }
-  ]
-}
-```
-
 ## API Reference
 
-### Client Methods
+### Session (Core)
+
+| Method | Description |
+|--------|-------------|
+| `session.generateText(options)` | Generate text, supports tools + maxSteps |
+| `session.streamText(options)` | Stream text, returns `textStream`/`fullStream`/`toolStream` |
+| `session.generateObject(options)` | Generate structured JSON output |
+| `session.streamObject(options)` | Stream structured JSON output |
+| `session.getContextUsage()` | Get context token usage |
+| `session.compactContext()` | Compact session context |
+| `session.clearContext()` | Clear conversation history |
+| `session.getMessages(limit?)` | Get conversation messages |
+| `session.close()` | Close session and release resources |
+| `session.id` | Session ID (readonly) |
+| `session.closed` | Whether session is closed (readonly) |
+
+### Convenience Functions
+
+| Function | Description |
+|----------|-------------|
+| `generateText(options)` | Generate text (auto session) |
+| `streamText(options)` | Stream text (auto session) |
+| `generateObject(options)` | Generate structured output (auto session) |
+| `streamObject(options)` | Stream structured output (auto session) |
+| `createChat(options)` | Create multi-turn chat (auto session) |
+| `createProvider(options)` | Create provider factory for model selection |
+| `tool(definition)` | Define a client-side tool |
+
+### Message Conversion
+
+| Function | Description |
+|----------|-------------|
+| `convertToModelMessages(uiMessages)` | UIMessage[] → ModelMessage[] |
+| `convertToUIMessages(modelMessages)` | ModelMessage[] → UIMessage[] |
+| `a3sMessagesToUI(messages)` | A3S Message[] → UIMessage[] |
+| `uiMessagesToA3s(uiMessages)` | UIMessage[] → A3S Message[] |
+
+### Low-Level Client (A3sClient)
 
 #### Lifecycle (4 methods)