@crewx/sdk 0.8.0-rc.72 → 0.8.0-rc.74

package/README.md

@@ -1,1022 +1,584 @@
-# SowonAI CrewX SDK
+# @crewx/sdk
 
-[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-[![npm version](https://badge.fury.io/js/%40crewx%2Fsdk.svg)](https://www.npmjs.com/package/@crewx/sdk)
+CrewX SDK — load `crewx.yaml` and run AI agents from TypeScript/JavaScript.
 
-Core SDK for building custom AI agent integrations and tools on top of SowonAI CrewX.
+> **Status**: `0.9.0-alpha` — Core API, Plugin system, and Event system are stable. Tool system coming soon.
 
-## Overview
+## Table of Contents
 
-The CrewX SDK provides the foundational interfaces, types, and utilities for building AI agent systems. It's designed to be framework-agnostic and extensible, allowing you to:
+1. [Quick Start](#1-quick-start)
+2. [Core API](#2-core-api)
+3. [crewx.yaml Structure](#3-crewxyaml-structure)
+4. [Layout System](#4-layout-system)
+5. [Template Helpers](#5-template-helpers)
+6. [Provider Bridge](#6-provider-bridge)
+7. [Plugin System](#7-plugin-system)
+8. [Event System](#8-event-system)
+9. [Type Reference](#9-type-reference)
 
-- Build custom AI provider integrations
-- Implement conversation history management
-- Create knowledge base utilities
-- Develop agent orchestration systems
-- Integrate with existing applications
-
-## Installation
+---
 
-```bash
-npm install @crewx/sdk
-```
+## 1. Quick Start
 
-For peer dependencies (if using NestJS):
+### Install
 
 ```bash
-npm install @nestjs/common @nestjs/core reflect-metadata rxjs
+npm install @crewx/sdk
 ```
 
-## Quick Start
-
-### Basic Usage with createCrewxAgent (NEW)
-
-The SDK provides a high-level `createCrewxAgent` factory function for simplified agent creation:
+### Hello World
 
 ```typescript
-import { createCrewxAgent } from '@crewx/sdk';
-
-// Create an agent with configuration
-const { agent, onEvent } = await createCrewxAgent({
-  provider: {
-    namespace: 'cli',
-    id: 'codex',
-    apiKey: process.env.CODEX_TOKEN,
-  },
-  enableCallStack: true,
-  defaultAgentId: 'my-agent',
-});
-
-// Subscribe to agent events
-onEvent('callStackUpdated', (stack) => {
-  console.log('Call stack:', stack.map(f => `${f.depth}: ${f.agentId}`));
-});
+import { Crewx } from '@crewx/sdk';
 
-onEvent('agentStarted', ({ agentId, mode }) => {
-  console.log(`Agent ${agentId} started in ${mode} mode`);
-});
-
-// Execute a query (read-only)
-const queryResult = await agent.query({
-  prompt: 'What is the current status?',
-  context: 'Project: CrewX',
-  messages: [
-    {
-      id: 'msg-1',
-      text: 'Previous message',
-      timestamp: new Date().toISOString(),
-      isAssistant: false,
-    },
-  ],
-});
-
-console.log(queryResult.content);
+const crewx = await Crewx.loadYaml('./crewx.yaml');
 
-// Execute an action (write mode)
-const executeResult = await agent.execute({
-  prompt: 'Create a summary document',
-  context: 'Project root: /path/to/project',
-});
+const result = await crewx.query('assistant', 'Hello! What can you do?');
 
-console.log(executeResult.content);
+if (result.ok) {
+  console.log(result.data);          // agent's response text
+} else {
+  console.error(result.error?.message);
+}
 ```
 
-### Using Utilities
+### Minimal `crewx.yaml`
 
-```typescript
-import {
-  MentionParser,
-  loadAvailableAgents,
-  type AgentConfig,
-  type AIProvider
-} from '@crewx/sdk';
-
-// Parse agent mentions from user input
-const parser = new MentionParser();
-const parsed = parser.parse('@claude analyze this code');
-
-console.log(parsed.mentions); // ['claude']
-console.log(parsed.cleanedPrompt); // 'analyze this code'
+```yaml
+agents:
+  assistant:
+    name: Assistant
+    provider: cli/claude
+    inline:
+      model: claude-sonnet-4-6
+      prompt: |
+        You are a helpful assistant.
+        Answer concisely.
 ```
 
-### Working with Conversation History
+### Task Execution (with side effects)
 
 ```typescript
-import {
-  type ConversationMessage,
-  type ConversationThread,
-  type IConversationHistoryProvider,
-  getConversationConfig
-} from '@crewx/sdk';
-
-// Implement custom conversation storage
-class MyConversationProvider implements IConversationHistoryProvider {
-  async fetchHistory(options) {
-    // Fetch from your database
-    return {
-      messages: [],
-      metadata: { platform: 'my-platform' }
-    };
-  }
+const crewx = await Crewx.loadYaml('./crewx.yaml');
 
-  async saveMessage(message, threadId) {
-    // Save to your database
-  }
+// execute() allows the agent to write files, run commands, etc.
+const result = await crewx.execute('assistant', 'Refactor src/utils.ts');
 
-  // ... other methods
-}
+console.log(`Done in ${result.meta.durationMs}ms`);
+console.log(result.data);
 ```
 
-### Using Document Manager
+### Plugin Setup (optional)
 
 ```typescript
-import { DocumentManager } from '@crewx/sdk';
-
-const docManager = new DocumentManager();
+import { FileLoggerPlugin } from '@crewx/cli/plugins/file-logger';
+import { SqliteTracingPlugin } from '@crewx/cli/plugins/sqlite-tracing';
 
-// Load markdown documents
-await docManager.loadDocument('./docs/api.md', 'markdown');
-
-// Get document content
-const content = docManager.getDocument('./docs/api.md');
-console.log(content);
+await crewx.use(new FileLoggerPlugin());    // log files → .crewx/logs/
+await crewx.use(new SqliteTracingPlugin()); // task records → ~/.crewx/crewx.db
+// ... run tasks ...
+await crewx.close(); // flush all plugins on exit
 ```
 
-## API Reference
+---
 
-### Core Interfaces
+## 2. Core API
 
-#### AIProvider
+### `Crewx.loadYaml(path, options?)`
 
-The fundamental interface for all AI providers:
+Load from a `crewx.yaml` file. Documents referenced in the config are loaded automatically.
 
 ```typescript
-interface AIProvider {
-  respond(
-    prompt: string,
-    options?: AIQueryOptions
-  ): Promise<AIResponse>;
-}
-
-interface AIQueryOptions {
-  messages?: ConversationMessage[];
-  pipedContext?: string;
-  model?: string;
-  // ... other options
-}
-
-interface AIResponse {
-  content: string;
-  metadata?: Record<string, unknown>;
-}
-```
+const crewx = await Crewx.loadYaml('./crewx.yaml');
 
-#### IConversationHistoryProvider
-
-Interface for conversation storage implementations:
-
-```typescript
-interface IConversationHistoryProvider {
-  fetchHistory(options: FetchHistoryOptions): Promise<ConversationThread>;
-  saveMessage(message: ConversationMessage, threadId: string): Promise<void>;
-  createThread(threadId: string, metadata?: Record<string, unknown>): Promise<void>;
-  listThreads(): Promise<Array<{ id: string; updatedAt: Date }>>;
-}
+// With options
+const crewx = await Crewx.loadYaml('./crewx.yaml', {
+  execPolicy: { allow: ['git *', 'npm run *'], deny: ['rm *'] },
+});
 ```
 
-### Configuration
-
-#### TimeoutConfig
+### `Crewx.fromConfig(config, options?, projectRoot?)`
 
-Manage timeout settings for AI operations:
+Create from an already-parsed config object. Useful when you load YAML yourself or build config programmatically.
 
 ```typescript
-import { getTimeoutConfig, getDefaultTimeoutConfig } from '@crewx/sdk';
+import { Crewx, CrewxProjectConfig } from '@crewx/sdk';
 
-// Get timeout configuration
-const timeout = getTimeoutConfig();
+const config: CrewxProjectConfig = {
+  agents: [
+    { id: 'bot', provider: 'cli/claude', inline: { prompt: 'You are a bot.' } },
+  ],
+};
 
-// Use default timeouts
-const defaults = getDefaultTimeoutConfig();
-console.log(defaults.default); // 120000ms
-console.log(defaults.query); // 60000ms
-console.log(defaults.execute); // 300000ms
+const crewx = await Crewx.fromConfig(config, {}, process.cwd());
 ```
 
-#### ConversationConfig
+### `crewx.query(agentRef, message, options?)`
 
-Configure conversation behavior:
+Ask an agent a question. Read-only — the agent is expected to respond with text only.
 
 ```typescript
-import { getConversationConfig, DEFAULT_CONVERSATION_CONFIG } from '@crewx/sdk';
+const result = await crewx.query('assistant', 'Summarize this PR');
 
-const config = getConversationConfig();
-// Or use defaults
-console.log(DEFAULT_CONVERSATION_CONFIG);
+// With options
+const result = await crewx.query('assistant', 'Translate to Korean', {
+  model: 'claude-opus-4-6',      // override model
+  provider: 'cli/claude',        // override provider
+  context: 'Additional context', // prepended to the message
+});
 ```
 
-### Utilities
+> **Note**: `'@assistant'` 형태도 동작합니다 (CLI 호환). SDK에서는 bare id가 권장됩니다.
 
-#### MentionParser
+**Returns**: [`QueryResult`](#queryresult)
 
-Parse agent mentions from text:
+### `crewx.execute(agentRef, message, options?)`
 
-```typescript
-import { MentionParser, type ParsedMentions } from '@crewx/sdk';
-
-const parser = new MentionParser();
-
-// Parse single mention
-const result = parser.parse('@claude help me');
-// result.mentions: ['claude']
-// result.cleanedPrompt: 'help me'
-
-// Parse multiple mentions
-const multi = parser.parse('@claude @gemini compare approaches');
-// multi.mentions: ['claude', 'gemini']
-
-// Override model
-const withModel = parser.parse('@claude:opus analyze');
-// Model override detected
-```
-
-#### Error Utilities
-
-Handle errors consistently:
+Run a task with an agent. The agent may write files, run shell commands, etc. Uses `--dangerously-skip-permissions` for `cli/claude`.
 
 ```typescript
-import { getErrorMessage, getErrorStack, isError } from '@crewx/sdk';
-
-try {
-  // ... operation
-} catch (err) {
-  if (isError(err)) {
-    console.error(getErrorMessage(err));
-    console.error(getErrorStack(err));
-  }
+const result = await crewx.execute('coder', 'Fix the failing tests in src/');
+
+if (!result.ok) {
+  console.error('Failed:', result.error?.code, result.error?.message);
 }
 ```
 
-### Agent Factory API
+**Returns**: [`ExecuteResult`](#executeresult)
 
-#### createCrewxAgent
+### `crewx.renderAgentPromptFull(agentId, options?)`
 
-Create and configure an agent with event support:
+Render the complete system prompt for an agent — layout + template expansion. Used to inspect what the agent actually receives, or to pass the prompt to another system.
 
 ```typescript
-import {
-  createCrewxAgent,
-  type CrewxAgentConfig,
-  type CrewxAgent,
-  type AgentQueryRequest,
-  type AgentExecuteRequest,
-  type CallStackFrame
-} from '@crewx/sdk';
-
-// Configuration interface
-interface CrewxAgentConfig {
-  provider?: {
-    namespace: string;
-    id: string;
-    apiKey?: string;
-    model?: string;
-  };
-  knowledgeBase?: {
-    path?: string;
-    sources?: string[];
-  };
-  enableCallStack?: boolean;
-  defaultAgentId?: string;
-}
+const prompt = await crewx.renderAgentPromptFull('assistant');
+console.log(prompt);
 
-// Create agent
-const { agent, onEvent, eventBus } = await createCrewxAgent({
-  provider: { namespace: 'cli', id: 'codex' },
-  enableCallStack: true,
+// With layout override
+const prompt = await crewx.renderAgentPromptFull('assistant', {
+  layout: 'crewx/minimal',
+  session: { mode: 'execute', platform: 'api' },
 });
-
-// Agent interface
-agent.query(request: AgentQueryRequest): Promise<AgentResult>
-agent.execute(request: AgentExecuteRequest): Promise<AgentResult>
-agent.getCallStack(): CallStackFrame[]
 ```
 
-#### Event System
+### `crewx.registerLayout(name, template)`
 
-The event system supports lifecycle and call stack tracking:
+Register a custom layout at runtime. See [Layout System](#4-layout-system).
 
 ```typescript
-// Subscribe to events
-const unsubscribe = onEvent('eventName', (payload) => {
-  console.log('Event:', payload);
-});
-
-// Supported events:
-// - 'callStackUpdated': CallStackFrame[]
-// - 'agentStarted': { agentId: string, mode: 'query' | 'execute' }
-// - 'agentCompleted': { agentId: string, success: boolean }
-// - 'toolCallStarted': { toolName: string, args: any }
-// - 'toolCallCompleted': { toolName: string, result: any }
-
-// Unsubscribe when done
-unsubscribe();
+crewx.registerLayout('my-layout', `
+# {{agent.name}}
+{{agent.inline.prompt}}
+---
+Session: {{session.mode}}
+`);
 
-// Direct event bus access for advanced usage
-eventBus.emit('customEvent', { data: 'value' });
-eventBus.listenerCount('eventName');
-eventBus.clear(); // Remove all listeners
+const prompt = await crewx.renderAgentPromptFull('assistant', {
+  layout: 'my-layout',
+});
 ```
 
-### Types
+### `crewx.agents`
 
-#### Agent Types
+`ReadonlyMap<string, AgentConfig>` — all agents loaded from `crewx.yaml`.
 
 ```typescript
-import type {
-  AgentConfig,
-  AgentsConfig,
-  AgentInfo,
-  AgentQueryOptions,
-  AgentResponse,
-  RemoteAgentConfigInput,
-  RemoteAgentInfo
-} from '@crewx/sdk';
-
-import { ExecutionMode, SecurityLevel } from '@crewx/sdk';
+// List all agents
+for (const [id, agent] of crewx.agents) {
+  console.log(id, agent.provider);
+}
+
+// Check if an agent exists
+if (crewx.agents.has('coder')) {
+  // ...
+}
 ```
 
-## Provider Development
+### `crewx.filterAgents(filters)`
 
-### Creating a Custom Provider
+Filter agents by role, team, or provider. Supports glob patterns.
 
 ```typescript
-import { AIProvider, AIQueryOptions, AIResponse } from '@crewx/sdk';
-
-export class MyCustomProvider implements AIProvider {
-  async respond(
-    prompt: string,
-    options?: AIQueryOptions
-  ): Promise<AIResponse> {
-    // Implement your AI provider logic
-    const result = await this.callMyAI(prompt, options);
-
-    return {
-      content: result.text,
-      metadata: {
-        model: result.model,
-        tokens: result.usage
-      }
-    };
-  }
+// All agents on the 'backend' team
+const agents = crewx.filterAgents({ team: 'backend' });
 
-  private async callMyAI(prompt: string, options?: AIQueryOptions) {
-    // Your implementation
-    return {
-      text: 'Response from my AI',
-      model: 'my-model-v1',
-      usage: { total: 100 }
-    };
-  }
-}
+// All Claude-based agents
+const agents = crewx.filterAgents({ provider: 'cli/claude' });
+
+// Wildcard: all cli/* providers
+const agents = crewx.filterAgents({ provider: 'cli/*' });
 ```
 
-### Implementing Conversation Storage
+---
 
-```typescript
-import {
-  IConversationHistoryProvider,
-  ConversationMessage,
-  ConversationThread,
-  FetchHistoryOptions
-} from '@crewx/sdk';
-
-export class DatabaseConversationProvider implements IConversationHistoryProvider {
-  constructor(private db: MyDatabase) {}
-
-  async fetchHistory(options: FetchHistoryOptions): Promise<ConversationThread> {
-    const messages = await this.db.query(
-      'SELECT * FROM messages WHERE thread_id = ?',
-      [options.threadId]
-    );
-
-    return {
-      messages: messages.map(this.toMessage),
-      metadata: { platform: 'database' }
-    };
-  }
+## 3. `crewx.yaml` Structure
 
-  async saveMessage(message: ConversationMessage, threadId: string): Promise<void> {
-    await this.db.insert('messages', {
-      thread_id: threadId,
-      ...message
-    });
-  }
+```yaml
+# ─── Agents ──────────────────────────────────────────────────
+agents:
+  my_agent:
+    name: My Agent              # Display name (optional)
+    role: Backend Developer     # Role label (optional)
+    team: core                  # Team label (optional)
+    provider: cli/claude        # Provider (required)
+    working_directory: .        # Working dir for the agent
 
-  async createThread(threadId: string, metadata?: Record<string, unknown>): Promise<void> {
-    await this.db.insert('threads', { id: threadId, metadata });
-  }
+    inline:                     # Inline agent definition
+      model: claude-sonnet-4-6  # Model override (optional)
+      prompt: |                 # System prompt (Handlebars template)
+        You are an expert {{agent.role}}.
+        Today's context: {{{documents.guidelines.content}}}
+      layout: crewx/minimal     # Layout override for this agent (optional)
 
-  async listThreads() {
-    return await this.db.query('SELECT id, updated_at FROM threads');
-  }
+# ─── Layouts ─────────────────────────────────────────────────
+layouts:
+  default: crewx/minimal        # Project-level default layout
 
-  private toMessage(row: any): ConversationMessage {
-    return {
-      id: row.id,
-      userId: row.user_id,
-      text: row.text,
-      timestamp: row.created_at,
-      isAssistant: row.is_assistant,
-      metadata: row.metadata
-    };
-  }
-}
+# ─── Documents ───────────────────────────────────────────────
+documents:
+  guidelines:
+    path: ./docs/guidelines.md  # Loaded at startup, available as documents.guidelines
+  api_spec:
+    path: ./docs/api.md
 ```
 
-## Shared SDK/CLI Integration
+### Multiple providers
 
-The SDK provides reusable components that were previously CLI-only. These abstractions enable custom platform integrations while maintaining consistency.
-
-### Message Formatting (Phase 1)
+```yaml
+agents:
+  polyglot:
+    provider:                   # Array = first is primary, rest are fallbacks (future)
+      - cli/claude
+      - cli/gemini
+```
 
-The SDK provides a flexible message formatting system that supports multiple platforms (Slack, Terminal, API, etc.) and allows custom formatters.
+---
 
-#### Platform-Specific Formatters
+## 4. Layout System
 
-**Terminal Formatter (Built-in)**
+Layouts wrap the agent's raw prompt with structure — identity blocks, session info, available tools, etc.
 
-```typescript
-import { BaseMessageFormatter, type StructuredMessage } from '@crewx/sdk';
+### Built-in Layouts
 
-const formatter = new BaseMessageFormatter();
+| ID | Description |
+|----|-------------|
+| `crewx/default` | Full structured layout (identity + session + prompt) |
+| `crewx/minimal` | Minimal wrapper — just the agent prompt |
 
-// Format messages for terminal display
-const history = formatter.formatHistory(messages, {
-  includeUserId: true,
-  includeTimestamp: true,
-  timestampFormat: 'iso', // 'iso' | 'relative' | 'unix'
-});
+### Resolution Priority
 
-console.log(history);
-// Output:
-// [2025-10-17T10:00:00Z] user123: Hello!
-// [2025-10-17T10:00:05Z] assistant: How can I help?
-```
+When calling `renderAgentPromptFull()`, the layout is resolved in this order (first match wins):
 
-**Slack Formatter (Built-in)**
+1. `options.layout` — call-site override
+2. `agent.inline.layout` — per-agent definition in `crewx.yaml`
+3. `config.layouts.default` — project-level default
+4. `crewx/default` — SDK built-in fallback
 
-For Slack bot integrations, use the Slack-specific formatter that handles threading, mentions, and rich formatting:
+### Custom Layout via `registerLayout()`
 
 ```typescript
-import { SlackMessageFormatter } from '@crewx/sdk';
+crewx.registerLayout('compact', `
+## {{agent.name}} ({{agent.role}})
+{{agent.inline.prompt}}
+`);
 
-const slackFormatter = new SlackMessageFormatter();
-
-// Format for Slack with rich text support
-const formatted = slackFormatter.formatForSlack(messages, {
-  includeTimestamp: true,
-  useThreading: true,
-  preserveMentions: true,
+const prompt = await crewx.renderAgentPromptFull('assistant', {
+  layout: 'compact',
 });
+```
 
-// Format agent response with Slack-specific blocks
-const response = slackFormatter.formatAgentResponse({
-  content: 'Task completed successfully!',
-  agentId: 'backend',
-  metadata: { status: 'success' }
-});
+### Inline Layout in `crewx.yaml`
 
-// Send to Slack
-await slackClient.chat.postMessage({
-  channel: channelId,
-  blocks: response.blocks,
-  thread_ts: threadId,
-});
+```yaml
+agents:
+  assistant:
+    provider: cli/claude
+    inline:
+      prompt: You are helpful.
+      layout:
+        id: crewx/default
+        props:
+          show_skills: false     # Pass props to the layout template
 ```
 
-**API/JSON Formatter**
-
-For API responses or structured data:
+### Inline Template String
 
 ```typescript
-import {
-  BaseMessageFormatter,
-  type StructuredMessage,
-  type ConversationMetadata
-} from '@crewx/sdk';
-
-class APIFormatter extends BaseMessageFormatter {
-  formatForAPI(messages: StructuredMessage[]): {
-    messages: Array<{
-      id: string;
-      author: { id: string; isBot: boolean };
-      content: string;
-      timestamp: string;
-      metadata?: Record<string, unknown>;
-    }>;
-    meta: ConversationMetadata;
-  } {
-    return {
-      messages: messages.map(msg => ({
-        id: msg.id,
-        author: {
-          id: msg.userId || 'unknown',
-          isBot: msg.isAssistant || false,
-        },
-        content: msg.text,
-        timestamp: msg.timestamp,
-        metadata: msg.metadata,
-      })),
-      meta: {
-        platform: 'api',
-        totalMessages: messages.length,
-        generatedAt: new Date().toISOString(),
-      },
-    };
-  }
-}
-
-const apiFormatter = new APIFormatter();
-const response = apiFormatter.formatForAPI(messages);
-
-// Return as JSON API response
-res.json(response);
+const prompt = await crewx.renderAgentPromptFull('assistant', {
+  layout: { template: 'SYSTEM: {{agent.inline.prompt}}' },
+});
 ```
 
-#### Custom Formatter Extension
-
-Create your own formatter for custom platforms:
-
-```typescript
-import {
-  BaseMessageFormatter,
-  StructuredMessage,
-  FormatterOptions
-} from '@crewx/sdk';
+---
 
-class DiscordFormatter extends BaseMessageFormatter {
-  formatMessage(msg: StructuredMessage, options: FormatterOptions): string {
-    const timestamp = options.includeTimestamp
-      ? `<t:${Math.floor(new Date(msg.timestamp).getTime() / 1000)}:R> `
-      : '';
+## 5. Template Helpers
 
-    const author = msg.isAssistant ? '🤖 **Bot**' : `👤 **${msg.userId}**`;
+The `inline.prompt` field in `crewx.yaml` is a **Handlebars template**. These helpers are available:
 
-    return `${timestamp}${author}: ${msg.text}`;
-  }
+### P0 Helpers (Core)
 
-  formatForDiscordEmbed(
-    message: string,
-    options: { color?: number; title?: string }
-  ) {
-    return {
-      embeds: [{
-        title: options.title || 'Agent Response',
-        description: message,
-        color: options.color || 0x5865F2,
-        timestamp: new Date().toISOString(),
-      }],
-    };
-  }
-}
+| Helper | Usage | Description |
+|--------|-------|-------------|
+| `exec` | `{{exec "git log --oneline -5"}}` | Run shell command and inline output |
+| `include` | `{{include someVar}}` | Include a string variable as-is (no escaping) |
+| `fenced_code` | `{{fenced_code content lang="ts"}}` | Wrap content in Markdown code block |
 
-const discordFormatter = new DiscordFormatter();
-const embed = discordFormatter.formatForDiscordEmbed(
-  'Analysis complete!',
-  { title: 'Backend Agent', color: 0x00FF00 }
-);
+### Condition Helpers
 
-await discordChannel.send(embed);
+```handlebars
+{{#if (eq agent.team "backend")}}Backend mode{{/if}}
+{{#if (and featureA featureB)}}Both enabled{{/if}}
 ```
 
-#### Metadata Handling
+Available: `eq`, `ne`, `and`, `or`, `not`, `contains`
 
-The formatter system supports rich metadata for enhanced context:
+### Utility Helpers
 
-```typescript
-import {
-  BaseMessageFormatter,
-  type StructuredMessage,
-  type ConversationMetadata
-} from '@crewx/sdk';
-
-const messages: StructuredMessage[] = [
-  {
-    id: 'msg-1',
-    userId: 'user123',
-    text: 'What is the status?',
-    timestamp: new Date().toISOString(),
-    isAssistant: false,
-    metadata: {
-      platform: 'slack',
-      channelId: 'C123456',
-      threadTs: '1234567890.123456',
-      userAgent: 'SlackBot/1.0',
-    },
-  },
-  {
-    id: 'msg-2',
-    userId: 'backend-agent',
-    text: 'All systems operational.',
-    timestamp: new Date().toISOString(),
-    isAssistant: true,
-    metadata: {
-      agentId: 'backend',
-      model: 'claude-3-5-sonnet',
-      processingTime: 1234,
-      tokenUsage: { input: 50, output: 100 },
-    },
-  },
-];
+| Helper | Description |
+|--------|-------------|
+| `truncate text len` | Truncate string to N chars |
+| `length array` | Array/string length |
+| `escapeHandlebars text` | Escape `{{` in content |
+| `formatFileSize bytes` | `1048576` → `1 MB` |
+| `formatTimestamp ms` | Unix ms → readable date |
 
-const formatter = new BaseMessageFormatter();
+### Document Access in Templates
 
-// Format with metadata extraction
-const formatted = formatter.formatHistory(messages, {
-  includeUserId: true,
-  includeTimestamp: true,
-  extractMetadata: true,
-});
-
-// Access metadata
-messages.forEach(msg => {
-  if (msg.metadata?.tokenUsage) {
-    console.log(`Tokens used: ${msg.metadata.tokenUsage.input + msg.metadata.tokenUsage.output}`);
-  }
-});
-```
+Documents defined in `crewx.yaml` are automatically available:
 
-#### Migration Guide for Existing Formatter Users
+```handlebars
+# Inline the full document
+{{{documents.guidelines.content}}}
 
-If you're migrating from the CLI's internal formatter to the SDK formatter:
+# Access metadata
+Path: {{documents.guidelines.path}}
+```
 
-**Before (CLI internal)**
-```typescript
-// This was CLI-only code
-import { MessageFormatter } from '../cli/src/utils/message-formatter';
+### `exec` Security Policy
 
-const formatter = new MessageFormatter();
-const result = formatter.format(messages);
-```
+Control which shell commands are allowed in templates:
 
-**After (SDK)**
 ```typescript
-// Now use SDK's BaseMessageFormatter
-import { BaseMessageFormatter } from '@crewx/sdk';
-
-const formatter = new BaseMessageFormatter();
-const result = formatter.formatHistory(messages, {
-  includeUserId: true,
-  includeTimestamp: true,
+const crewx = await Crewx.loadYaml('./crewx.yaml', {
+  execPolicy: {
+    allow: ['git *', 'npm run *', 'cat *'],
+    deny:  ['rm *', 'curl *'],
+  },
 });
 ```
 
-**Key Changes:**
-1. Import from `@crewx/sdk` instead of CLI internals
-2. Use `formatHistory()` method instead of `format()`
-3. Options are now explicitly passed as second parameter
-4. Metadata handling is built-in with `extractMetadata` option
-
-**Slack Migration**
-```typescript
-// Before (CLI)
-import { SlackFormatter } from '../cli/src/slack/formatter';
-
-// After (SDK)
-import { SlackMessageFormatter } from '@crewx/sdk';
+Or set it in `crewx.yaml`:
 
-const formatter = new SlackMessageFormatter();
-// Same API, now available in SDK
+```yaml
+settings:
+  template:
+    exec:
+      allow:
+        - "git *"
+        - "npm run *"
+      deny:
+        - "rm *"
 ```
 
-#### CLI Developer Guide: Adding Slack Formatting
-
-If you're building a CLI tool and want to add Slack formatting support:
-
-**Step 1: Install SDK**
-```bash
-npm install @crewx/sdk
-```
+Glob syntax: `*` matches within a segment, `**` matches across path segments.
 
-**Step 2: Import Slack Formatter**
-```typescript
-import { SlackMessageFormatter } from '@crewx/sdk';
-import { WebClient } from '@slack/web-api';
+---
 
-const slackClient = new WebClient(process.env.SLACK_BOT_TOKEN);
-const formatter = new SlackMessageFormatter();
-```
+## 6. Provider Bridge
 
-**Step 3: Format Messages for Slack**
-```typescript
-async function sendToSlack(
-  channelId: string,
-  content: string,
-  threadTs?: string
-) {
-  // Format using SDK formatter
-  const formatted = formatter.formatAgentResponse({
-    content,
-    agentId: 'my-cli-agent',
-    metadata: {
-      source: 'cli',
-      timestamp: new Date().toISOString(),
-    },
-  });
-
-  // Send to Slack
-  await slackClient.chat.postMessage({
-    channel: channelId,
-    text: content, // Fallback text
-    blocks: formatted.blocks,
-    thread_ts: threadTs,
-  });
-}
-```
+Each agent has a `provider` field that tells the SDK which AI backend to use.
 
-**Step 4: Handle Conversation History**
-```typescript
-import {
-  SlackMessageFormatter,
-  type StructuredMessage
-} from '@crewx/sdk';
-
-async function formatSlackThread(threadTs: string) {
-  // Fetch Slack thread
-  const thread = await slackClient.conversations.replies({
-    channel: channelId,
-    ts: threadTs,
-  });
-
-  // Convert to StructuredMessage format
-  const messages: StructuredMessage[] = thread.messages.map(msg => ({
-    id: msg.ts,
-    userId: msg.user || 'bot',
-    text: msg.text || '',
-    timestamp: new Date(parseFloat(msg.ts) * 1000).toISOString(),
-    isAssistant: !!msg.bot_id,
-    metadata: {
-      platform: 'slack',
-      threadTs: msg.thread_ts,
-    },
-  }));
-
-  // Format for display or processing
-  const formatter = new SlackMessageFormatter();
-  const formatted = formatter.formatHistory(messages, {
-    includeTimestamp: true,
-    useThreading: true,
-  });
-
-  return formatted;
-}
-```
+### Supported Providers
 
-**Step 5: Error Handling**
-```typescript
-try {
-  await sendToSlack(channelId, 'Task completed!', threadTs);
-} catch (error) {
-  // Format error for Slack
-  const errorMessage = formatter.formatAgentResponse({
-    content: `❌ Error: ${error.message}`,
-    agentId: 'cli-agent',
-    metadata: { status: 'error' },
-  });
-
-  await slackClient.chat.postMessage({
-    channel: channelId,
-    blocks: errorMessage.blocks,
-  });
-}
-```
+| Provider | CLI Command | Notes |
+|----------|-------------|-------|
+| `cli/claude` | `claude` | Claude Code CLI |
+| `cli/gemini` | `gemini` | Gemini CLI |
+| `cli/copilot` | `gh copilot suggest` | GitHub Copilot |
+| `cli/codex` | `codex` | OpenAI Codex CLI |
 
-### AI Providers (Phase 2)
+> **Coming Soon**: `api/claude`, `api/openai` — direct API providers without CLI dependency.
 
-Use built-in providers or create custom ones:
+### Provider Override at Call Site
 
 ```typescript
-import {
-  BaseAIProvider,
-  ClaudeProvider,
-  GeminiProvider,
-  CopilotProvider,
-  CodexProvider,
-  type LoggerLike,
-  type BaseAIProviderOptions
-} from '@crewx/sdk';
-
-// Use built-in provider
-const claude = new ClaudeProvider({
-  apiKey: process.env.ANTHROPIC_API_KEY,
-  logger: console,
-  enableToolUse: true,
-  model: 'claude-3-5-sonnet-20241022',
+// Use a different provider for one call
+const result = await crewx.query('assistant', 'Hello', {
+  provider: 'cli/gemini',
+  model: 'gemini-2.0-flash',
 });
-
-// Custom provider
-class MyProvider extends BaseAIProvider {
-  constructor(options: BaseAIProviderOptions) {
-    super(options);
-  }
-
-  async query(prompt: string, options: AIQueryOptions): Promise<AIResponse> {
-    // Custom implementation
-    return { content: 'Response', metadata: {} };
-  }
-}
 ```
 
-### Remote Agent Management (Phase 3)
+### `query` vs `execute` Mode
 
-Manage remote agent communications:
+| | `query()` | `execute()` |
+|--|-----------|-------------|
+| Intent | Read-only Q&A | Task with side effects |
+| cli/claude flags | `-p --output-format stream-json --verbose` | + `--dangerously-skip-permissions` |
+| Use when | Asking questions, generating text | Writing files, running commands |
 
-```typescript
-import {
-  RemoteAgentManager,
-  FetchRemoteTransport,
-  MockRemoteTransport,
-  type RemoteAgentConfig
-} from '@crewx/sdk';
-
-// Production transport
-const transport = new FetchRemoteTransport({
-  timeout: 30000,
-  headers: { 'Authorization': `Bearer ${token}` },
-});
+---
 
-// Testing transport
-const mockTransport = new MockRemoteTransport({
-  'agent-1': { content: 'Mocked response', success: true },
-});
+## 7. Plugin System
 
-const manager = new RemoteAgentManager({
-  transport,
-  enableLogging: true,
-  logger: console,
-});
+Plugins extend `CrewxPlugin` from `@crewx/sdk` and attach event listeners in `attach()`. Register with `crewx.use(plugin)` and release resources by calling `crewx.close()`.
 
-// Load remote agent
-await manager.loadAgent({
-  id: 'backend',
-  url: 'https://api.example.com/agent',
-  apiKey: process.env.REMOTE_API_KEY,
-  tools: ['search', 'analyze'],
-});
+### Lifecycle
 
-// Query remote agent
-const result = await manager.queryAgent('backend', 'Analyze codebase');
-console.log(result.content);
+```typescript
+await crewx.use(plugin);   // calls plugin.attach(crewx) — subscribe events, open DB, etc.
+await crewx.close();       // calls plugin.detach(crewx) on all plugins in LIFO order
 ```
 
-## Advanced Usage
+Same plugin instance registered twice is silently ignored.
 
-### Using Internal APIs
-
-Some internal APIs are available for advanced use cases:
-
-```typescript
-import { /* internal exports */ } from '@crewx/sdk/internal';
+### Built-in Plugins (`@crewx/cli`)
 
-// Note: Internal APIs may change between minor versions
-// Use at your own risk
-```
+| Plugin | Import path | Storage |
+|--------|-------------|---------|
+| `FileLoggerPlugin` | `@crewx/cli/plugins/file-logger` | `.crewx/logs/{ts}_{traceId}.log` (one file per task) |
+| `SqliteTracingPlugin` | `@crewx/cli/plugins/sqlite-tracing` | `~/.crewx/crewx.db` — `tasks` table |
 
-### Integration with NestJS
+> The `crewx` CLI auto-attaches both plugins for every run. No setup needed when using the CLI directly.
 
-The SDK works seamlessly with NestJS:
+### Custom Plugin
 
 ```typescript
-import { Injectable } from '@nestjs/common';
-import { DocumentManager } from '@crewx/sdk';
+import { CrewxPlugin } from '@crewx/sdk';
+import type { Crewx } from '@crewx/sdk';
 
-@Injectable()
-export class MyService {
-  constructor(private readonly docManager: DocumentManager) {}
+class CostTrackerPlugin extends CrewxPlugin {
+  readonly name = 'cost-tracker';
 
-  async loadDocs() {
-    await this.docManager.loadDocument('./docs/api.md', 'markdown');
+  attach(crewx: Crewx) {
+    crewx.on('task:end', (e) => {
+      if (e.costUsd) console.log(`[cost] ${e.agentRef}: $${e.costUsd.toFixed(4)}`);
+    });
   }
+  // detach() is optional — base class no-op is sufficient if no cleanup needed
 }
-```
 
-## Constants
-
-```typescript
-import {
-  SERVER_NAME,
-  PREFIX_TOOL_NAME,
-  DEFAULT_MAX_FILE_SIZE,
-  DEFAULT_MAX_FILES
-} from '@crewx/sdk';
-
-console.log(SERVER_NAME); // 'crewx'
-console.log(PREFIX_TOOL_NAME); // 'crewx_'
+await crewx.use(new CostTrackerPlugin());
 ```
 
-## Package Exports
-
-The SDK provides the following export paths:
-
-- `@crewx/sdk` - Main public API
-- `@crewx/sdk/internal` - Internal utilities (use with caution)
-- `@crewx/sdk/package.json` - Package metadata
+---
 
-## TypeScript
+## 8. Event System
 
-The SDK is written in TypeScript and includes full type definitions. No additional `@types` packages are needed.
+The `Crewx` class extends `TypedEventEmitter`. Events are emitted automatically during `query()` and `execute()`.
 
-```typescript
-import type { AIProvider, AgentConfig } from '@crewx/sdk';
+### Event Catalog
 
-// Full type safety
-const config: AgentConfig = {
-  id: 'my-agent',
-  provider: 'cli/claude',
-  // ... TypeScript will guide you
-};
-```
+| Event | When | Key Payload Fields |
+|-------|------|--------------------|
+| `task:start` | `query()`/`execute()` begins | `traceId`, `agentRef`, `mode`, `pid`, `model`, `provider`, `message`, `timestamp` |
+| `task:end` | Call completes (success or failure) | `traceId`, `agentRef`, `durationMs`, `result`, `error`, `inputTokens`, `outputTokens`, `costUsd`, `model` |
+| `task:output` | Each line of provider output | `traceId`, `agentRef`, `output`, `level` (`stdout`\|`stderr`\|`info`) |
 
-## Testing
+All events share `traceId` (format: `tsk_XXXXXXXX`) and `timestamp` inherited from `BaseEvent`.
 
-```bash
-# Run unit tests
-npm test
+### `crewx.on(event, listener)` → `UnsubscribeFn`
 
-# Run tests in watch mode
-npm run test:watch
+```typescript
+import type { TaskEndEvent } from '@crewx/sdk';
 
-# Run tests with UI
-npm run test:ui
+const unsub = crewx.on('task:end', (e: TaskEndEvent) => {
+  console.log(`${e.agentRef} finished in ${e.durationMs}ms | tokens: ${e.inputTokens}+${e.outputTokens}`);
+});
 
-# Run tests with coverage
-npm run test:coverage
+// Remove listener when no longer needed
+unsub();
 ```
 
-## Building
+`crewx.once(event, listener)` fires exactly once and auto-unsubscribes.
 
-```bash
-# Build the package
-npm run build
+> **Best practice**: Subscribe inside `Plugin.attach()` so listeners are automatically removed by `crewx.close()`. Direct `crewx.on()` calls are fine for one-off use but require manual `unsub()` calls.
 
-# Output: dist/
-```
+---
 
-## Contributing
+## 9. Type Reference
 
-Contributions to the SDK require signing our [Contributor License Agreement (CLA)](../../docs/CLA.md).
+### `CrewxOptions`
 
-Please follow these steps:
+```typescript
+interface CrewxOptions {
+  workspaceRoot?: string;
+  platform?: 'cli' | 'slack' | 'api';
+  execPolicy?: ExecPolicy;        // Allowed/denied shell commands in {{exec}}
+}
+```
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests for new functionality
-5. Run `npm test` and `npm run build`
-6. Submit a pull request
+### `QueryOptions` / `ExecuteOptions`
 
-## License
+```typescript
+interface QueryOptions {
+  model?: string;                 // Override model (e.g. 'claude-opus-4-6')
+  provider?: string;              // Override provider (e.g. 'cli/gemini')
+  context?: string;               // Extra context prepended to message
+  metadata?: Record<string, unknown>;
+}
+// ExecuteOptions has the same shape
+```
 
-Apache-2.0 License - See [LICENSE](./LICENSE) for details.
+### `QueryResult` / `ExecuteResult`
 
-## Context Integration
+```typescript
+interface QueryResult {
+  ok: boolean;
+  data: string;                   // Agent's response text
+  error?: {
+    code: string;                 // 'AGENT_NOT_FOUND' | 'PROVIDER_ERROR' | 'QUERY_FAILED'
+    message: string;
+  };
+  meta: {
+    agentId: string;
+    provider: string;
+    model?: string;
+    durationMs: number;
+  };
+}
+// ExecuteResult has the same shape
+```
 
-The SDK provides `TemplateContext` and `AgentMetadata` exports for dynamic template processing:
+### `AgentConfig`
 
 ```typescript
-import { TemplateContext, AgentMetadata } from '@crewx/sdk';
-
-// Use TemplateContext for dynamic prompts
-const context: TemplateContext = {
-  env: process.env,
-  agent: {
-    id: 'claude',
-    name: 'Claude Assistant',
-    provider: 'cli/claude',
-    model: 'claude-3-5-sonnet'
-  },
-  agentMetadata: {
-    specialties: ['code-analysis', 'architecture'],
-    capabilities: ['file-operations', 'web-search'],
-    description: 'Advanced reasoning and analysis specialist'
-  },
-  mode: 'query',
-  platform: 'cli'
-};
+interface AgentConfig {
+  id: string;
+  name?: string;
+  role?: string;
+  team?: string;
+  provider: string | string[];
+  working_directory?: string;
+  description?: string;
+  inline?: {
+    model?: string;
+    system_prompt?: string;
+    prompt?: string;
+    layout?: string | { id: string; props?: Record<string, unknown> };
+  };
+}
 ```
 
-For detailed usage, see [Template Variables Guide](../../docs/template-variables.md).
+### `ExecPolicy`
 
-## Support
+```typescript
+interface ExecPolicy {
+  allow: string[];   // Glob patterns for allowed commands
+  deny: string[];    // Glob patterns for denied commands (takes precedence)
+}
+```
 
-- [GitHub Issues](https://github.com/sowonlabs/crewx/issues)
-- [Documentation](../../docs/)
-- [Main README](../../README.md)
+---
 
-## Related Packages
+## Coming Soon
 
-- [`crewx`](../cli/README.md) - Full-featured CLI tool built on this SDK
+- **Tool System** — attach custom tools/functions to agents (§3 of design spec)
+- **`api/*` Providers** — direct API calls without CLI dependency
 
 ---
 
-Built by [SowonLabs](https://github.com/sowonlabs)
+## Requirements
+
+- Node.js >= 20.19.0
+- At least one CLI provider installed (e.g. `npm i -g @anthropic-ai/claude-code`)