@codeany/open-agent-sdk 0.1.0 → 0.2.0

package/README.md

@@ -4,7 +4,7 @@
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
 
-Open-source Agent SDK that runs the full agent loop **in-process** — no subprocess or CLI required. Deploy anywhere: cloud, serverless, Docker, CI/CD.
+Open-source Agent SDK that runs the full agent loop **in-process** — no subprocess or CLI required. Supports both **Anthropic** and **OpenAI-compatible** APIs. Deploy anywhere: cloud, serverless, Docker, CI/CD.
 
 Also available in **Go**: [open-agent-sdk-go](https://github.com/codeany-ai/open-agent-sdk-go)
 
@@ -20,7 +20,18 @@ Set your API key:
 export CODEANY_API_KEY=your-api-key
 ```
 
-Third-party providers (e.g. OpenRouter) are supported via `CODEANY_BASE_URL`:
+### OpenAI-compatible models
+
+Works with OpenAI, DeepSeek, Qwen, Mistral, or any OpenAI-compatible endpoint:
+
+```bash
+export CODEANY_API_TYPE=openai-completions
+export CODEANY_API_KEY=sk-...
+export CODEANY_BASE_URL=https://api.openai.com/v1
+export CODEANY_MODEL=gpt-4o
+```
+
+### Third-party Anthropic-compatible providers
 
 ```bash
 export CODEANY_BASE_URL=https://openrouter.ai/api
@@ -64,6 +75,24 @@ console.log(
 );
 ```
 
+### OpenAI / GPT models
+
+```typescript
+import { createAgent } from "@codeany/open-agent-sdk";
+
+const agent = createAgent({
+  apiType: "openai-completions",
+  model: "gpt-4o",
+  apiKey: "sk-...",
+  baseURL: "https://api.openai.com/v1",
+});
+
+const result = await agent.prompt("What files are in this project?");
+console.log(result.text);
+```
+
+The `apiType` is auto-detected from model name — models containing `gpt-`, `o1`, `o3`, `deepseek`, `qwen`, `mistral`, etc. automatically use `openai-completions`.
+
 ### Multi-turn conversation
 
 ```typescript
@@ -137,6 +166,66 @@ const r = await agent.prompt("Calculate 2**10 * 3");
 console.log(r.text);
 ```
 
+### Skills
+
+Skills are reusable prompt templates that extend agent capabilities. Five bundled skills are included: `simplify`, `commit`, `review`, `debug`, `test`.
+
+```typescript
+import {
+  createAgent,
+  registerSkill,
+  getAllSkills,
+} from "@codeany/open-agent-sdk";
+
+// Register a custom skill
+registerSkill({
+  name: "explain",
+  description: "Explain a concept in simple terms",
+  userInvocable: true,
+  async getPrompt(args) {
+    return [
+      {
+        type: "text",
+        text: `Explain in simple terms: ${args || "Ask what to explain."}`,
+      },
+    ];
+  },
+});
+
+console.log(`${getAllSkills().length} skills registered`);
+
+// The model can invoke skills via the Skill tool
+const agent = createAgent();
+const result = await agent.prompt('Use the "explain" skill to explain git rebase');
+console.log(result.text);
+```
+
+### Hooks (lifecycle events)
+
+```typescript
+import { createAgent, createHookRegistry } from "@codeany/open-agent-sdk";
+
+const hooks = createHookRegistry({
+  PreToolUse: [
+    {
+      handler: async (input) => {
+        console.log(`About to use: ${input.toolName}`);
+        // Return { block: true } to prevent tool execution
+      },
+    },
+  ],
+  PostToolUse: [
+    {
+      handler: async (input) => {
+        console.log(`Tool ${input.toolName} completed`);
+      },
+    },
+  ],
+});
+```
+
+20 lifecycle events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `SessionStart`, `SessionEnd`, `Stop`, `SubagentStart`, `SubagentStop`, `UserPromptSubmit`, `PermissionRequest`, `PermissionDenied`, `TaskCreated`, `TaskCompleted`, `ConfigChange`, `CwdChanged`, `FileChanged`, `Notification`, `PreCompact`, `PostCompact`, `TeammateIdle`.
+
 ### MCP server integration
 
 ```typescript
@@ -214,9 +303,12 @@ npx tsx examples/web/server.ts
 | `tool(name, desc, schema, handler)`   | Create a tool with Zod schema validation                       |
 | `createSdkMcpServer({ name, tools })` | Bundle tools into an in-process MCP server                     |
 | `defineTool(config)`                  | Low-level tool definition helper                               |
-| `getAllBaseTools()`                   | Get all 34 built-in tools                                      |
+| `getAllBaseTools()`                   | Get all 35+ built-in tools                                     |
+| `registerSkill(definition)`           | Register a custom skill                                        |
+| `getAllSkills()`                       | Get all registered skills                                      |
+| `createProvider(apiType, opts)`        | Create an LLM provider directly                                |
+| `createHookRegistry(config)`          | Create a hook registry for lifecycle events                    |
 | `listSessions()`                      | List persisted sessions                                        |
-| `getSessionMessages(id)`              | Retrieve messages from a session                               |
 | `forkSession(id)`                     | Fork a session for branching                                   |
 
 ### Agent methods
@@ -230,12 +322,14 @@ npx tsx examples/web/server.ts
 | `agent.interrupt()`             | Abort current query                                   |
 | `agent.setModel(model)`         | Change model mid-session                              |
 | `agent.setPermissionMode(mode)` | Change permission mode                                |
+| `agent.getApiType()`            | Get current API type                                  |
 | `agent.close()`                 | Close MCP connections, persist session                |
 
 ### Options
 
 | Option               | Type                                    | Default                | Description                                                          |
 | -------------------- | --------------------------------------- | ---------------------- | -------------------------------------------------------------------- |
+| `apiType`            | `string`                                | auto-detected          | `'anthropic-messages'` or `'openai-completions'`                     |
 | `model`              | `string`                                | `claude-sonnet-4-6`    | LLM model ID                                                         |
 | `apiKey`             | `string`                                | `CODEANY_API_KEY`      | API key                                                              |
 | `baseURL`            | `string`                                | —                      | Custom API endpoint                                                  |
@@ -266,12 +360,13 @@ npx tsx examples/web/server.ts
 
 ### Environment variables
 
-| Variable             | Description            |
-| -------------------- | ---------------------- |
-| `CODEANY_API_KEY`    | API key (required)     |
-| `CODEANY_MODEL`      | Default model override |
-| `CODEANY_BASE_URL`   | Custom API endpoint    |
-| `CODEANY_AUTH_TOKEN` | Alternative auth token |
+| Variable             | Description                                              |
+| -------------------- | -------------------------------------------------------- |
+| `CODEANY_API_KEY`    | API key (required)                                       |
+| `CODEANY_API_TYPE`   | `anthropic-messages` (default) or `openai-completions`   |
+| `CODEANY_MODEL`      | Default model override                                   |
+| `CODEANY_BASE_URL`   | Custom API endpoint                                      |
+| `CODEANY_AUTH_TOKEN` | Alternative auth token                                   |
 
 ## Built-in tools
 
@@ -287,6 +382,7 @@ npx tsx examples/web/server.ts
 | **WebSearch**                              | Search the web                               |
 | **NotebookEdit**                           | Edit Jupyter notebook cells                  |
 | **Agent**                                  | Spawn subagents for parallel work            |
+| **Skill**                                  | Invoke registered skills                     |
 | **TaskCreate/List/Update/Get/Stop/Output** | Task management system                       |
 | **TeamCreate/Delete**                      | Multi-agent team coordination                |
 | **SendMessage**                            | Inter-agent messaging                        |
@@ -301,6 +397,18 @@ npx tsx examples/web/server.ts
 | **Config**                                 | Dynamic configuration                        |
 | **TodoWrite**                              | Session todo list                            |
 
+## Bundled skills
+
+| Skill        | Description                                                    |
+| ------------ | -------------------------------------------------------------- |
+| `simplify`   | Review changed code for reuse, quality, and efficiency         |
+| `commit`     | Create a git commit with a well-crafted message                |
+| `review`     | Review code changes for correctness, security, and performance |
+| `debug`      | Systematic debugging using structured investigation            |
+| `test`       | Run tests and analyze failures                                 |
+
+Register custom skills with `registerSkill()`.
+
 ## Architecture
 
 ```
@@ -312,7 +420,7 @@ npx tsx examples/web/server.ts
                          │
               ┌──────────▼──────────┐
               │       Agent         │  Session state, tool pool,
-              │  query() / prompt() │  MCP connections
+              │  query() / prompt() │  MCP connections, hooks
               └──────────┬──────────┘
                          │
               ┌──────────▼──────────┐
@@ -323,26 +431,28 @@ npx tsx examples/web/server.ts
          ┌───────────────┼───────────────┐
          │               │               │
    ┌─────▼─────┐  ┌─────▼─────┐  ┌─────▼─────┐
-   │  LLM API  │  │  34 Tools │  │    MCP     │
-   │  Client   │  │ Bash,Read │  │  Servers   │
-   │ (streaming)│  │ Edit,...  │  │ stdio/SSE/ │
-   └───────────┘  └───────────┘  │ HTTP/SDK   │
-                                  └───────────┘
+   │  Provider  │  │  35 Tools │  │    MCP     │
+   │ Anthropic  │  │ Bash,Read │  │  Servers   │
+   │  OpenAI    │  │ Edit,...  │  │ stdio/SSE/ │
+   │ DeepSeek   │  │ + Skills  │  │ HTTP/SDK   │
+   └───────────┘  └───────────┘  └───────────┘
 ```
 
 **Key internals:**
 
-| Component             | Description                                                      |
-| --------------------- | ---------------------------------------------------------------- |
-| **QueryEngine**       | Core agentic loop with auto-compact, retry, tool orchestration   |
-| **Auto-compact**      | Summarizes conversation when context window fills up             |
-| **Micro-compact**     | Truncates oversized tool results                                 |
-| **Retry**             | Exponential backoff for rate limits and transient errors         |
-| **Token estimation**  | Rough token counting for budget and compaction thresholds        |
-| **File cache**        | LRU cache (100 entries, 25 MB) for file reads                    |
-| **Hook system**       | 20 lifecycle events (PreToolUse, PostToolUse, SessionStart, ...) |
-| **Session storage**   | Persist / resume / fork sessions on disk                         |
-| **Context injection** | Git status + AGENT.md automatically injected into system prompt  |
+| Component             | Description                                                        |
+| --------------------- | ------------------------------------------------------------------ |
+| **Provider layer**    | Abstracts Anthropic / OpenAI API differences                       |
+| **QueryEngine**       | Core agentic loop with auto-compact, retry, tool orchestration     |
+| **Skill system**      | Reusable prompt templates with 5 bundled skills                    |
+| **Hook system**       | 20 lifecycle events integrated into the engine                     |
+| **Auto-compact**      | Summarizes conversation when context window fills up               |
+| **Micro-compact**     | Truncates oversized tool results                                   |
+| **Retry**             | Exponential backoff for rate limits and transient errors            |
+| **Token estimation**  | Rough token counting with pricing for Claude, GPT, DeepSeek models |
+| **File cache**        | LRU cache (100 entries, 25 MB) for file reads                      |
+| **Session storage**   | Persist / resume / fork sessions on disk                           |
+| **Context injection** | Git status + AGENT.md automatically injected into system prompt    |
 
 ## Examples
 
@@ -359,6 +469,9 @@ npx tsx examples/web/server.ts
 | 09  | `examples/09-subagents.ts`            | Subagent delegation                    |
 | 10  | `examples/10-permissions.ts`          | Read-only agent with tool restrictions |
 | 11  | `examples/11-custom-mcp-tools.ts`     | `tool()` + `createSdkMcpServer()`      |
+| 12  | `examples/12-skills.ts`              | Skill system usage                     |
+| 13  | `examples/13-hooks.ts`               | Lifecycle hooks                        |
+| 14  | `examples/14-openai-compat.ts`       | OpenAI / DeepSeek models               |
 | web | `examples/web/`                       | Web chat UI for testing                |
 
 Run any example:
@@ -375,11 +488,11 @@ npx tsx examples/web/server.ts
 
 ## Star History
 
-<a href="https://www.star-history.com/?repos=shipany-ai%2Fopen-agent-sdk&type=timeline&legend=top-left">
+<a href="https://www.star-history.com/?repos=codeany-ai%2Fopen-agent-sdk-typescript&type=timeline&legend=top-left">
  <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=shipany-ai/open-agent-sdk&type=timeline&theme=dark&legend=top-left" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=shipany-ai/open-agent-sdk&type=timeline&legend=top-left" />
-   <img alt="Star History Chart" src="https://api.star-history.com/image?repos=shipany-ai/open-agent-sdk&type=timeline&legend=top-left" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=codeany-ai/open-agent-sdk-typescript&type=timeline&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=codeany-ai/open-agent-sdk-typescript&type=timeline&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/image?repos=codeany-ai/open-agent-sdk-typescript&type=timeline&legend=top-left" />
  </picture>
 </a>
 

package/examples/12-skills.ts

@@ -0,0 +1,88 @@
+/**
+ * Example 12: Skills
+ *
+ * Shows how to use the skill system: bundled skills, custom skills,
+ * and invoking skills programmatically.
+ *
+ * Run: npx tsx examples/12-skills.ts
+ */
+import {
+  createAgent,
+  registerSkill,
+  getAllSkills,
+  getUserInvocableSkills,
+  getSkill,
+  initBundledSkills,
+} from '../src/index.js'
+import type { SkillContentBlock } from '../src/index.js'
+
+async function main() {
+  console.log('--- Example 12: Skills ---\n')
+
+  // Bundled skills are auto-initialized when creating an Agent,
+  // but you can also init them explicitly:
+  initBundledSkills()
+
+  // List all registered skills
+  const all = getAllSkills()
+  console.log(`Registered skills (${all.length}):`)
+  for (const skill of all) {
+    console.log(`  - ${skill.name}: ${skill.description.slice(0, 80)}...`)
+  }
+
+  // Register a custom skill
+  registerSkill({
+    name: 'explain',
+    description: 'Explain a concept or piece of code in simple terms.',
+    aliases: ['eli5'],
+    userInvocable: true,
+    async getPrompt(args): Promise<SkillContentBlock[]> {
+      return [{
+        type: 'text',
+        text: `Explain the following in simple, clear terms that a beginner could understand. Use analogies where helpful.\n\nTopic: ${args || 'Ask the user what they want explained.'}`,
+      }]
+    },
+  })
+
+  console.log(`\nAfter registering custom skill: ${getAllSkills().length} total`)
+  console.log(`User-invocable: ${getUserInvocableSkills().length}`)
+
+  // Get a specific skill
+  const commitSkill = getSkill('commit')
+  if (commitSkill) {
+    const blocks = await commitSkill.getPrompt('', { cwd: process.cwd() })
+    console.log(`\nCommit skill prompt (first 200 chars):`)
+    console.log(blocks[0]?.type === 'text' ? blocks[0].text.slice(0, 200) + '...' : '(non-text)')
+  }
+
+  // Use skills with an agent - the model can invoke them via the Skill tool
+  console.log('\n--- Using skills with an agent ---\n')
+
+  const agent = createAgent({
+    model: process.env.CODEANY_MODEL || 'claude-sonnet-4-6',
+    maxTurns: 5,
+  })
+
+  for await (const event of agent.query(
+    'Use the "explain" skill to explain what git rebase does.',
+  )) {
+    const msg = event as any
+    if (msg.type === 'assistant') {
+      for (const block of msg.message?.content || []) {
+        if (block.type === 'tool_use') {
+          console.log(`[Tool: ${block.name}] ${JSON.stringify(block.input)}`)
+        }
+        if (block.type === 'text' && block.text.trim()) {
+          console.log(block.text)
+        }
+      }
+    }
+    if (msg.type === 'result') {
+      console.log(`\n--- ${msg.subtype} ---`)
+    }
+  }
+
+  await agent.close()
+}
+
+main().catch(console.error)

package/examples/13-hooks.ts

@@ -0,0 +1,88 @@
+/**
+ * Example 13: Hooks
+ *
+ * Shows how to use lifecycle hooks to intercept agent behavior.
+ * Hooks fire at key points: session start/end, before/after tool use,
+ * compaction, etc.
+ *
+ * Run: npx tsx examples/13-hooks.ts
+ */
+import { createAgent, createHookRegistry } from '../src/index.js'
+import type { HookInput } from '../src/index.js'
+
+async function main() {
+  console.log('--- Example 13: Hooks ---\n')
+
+  // Create a hook registry with custom handlers
+  const registry = createHookRegistry({
+    SessionStart: [{
+      handler: async (input: HookInput) => {
+        console.log(`[Hook] Session started: ${input.sessionId}`)
+      },
+    }],
+    PreToolUse: [{
+      handler: async (input: HookInput) => {
+        console.log(`[Hook] About to use tool: ${input.toolName}`)
+        // You can block a tool by returning { block: true }
+        // return { block: true, message: 'Tool blocked by hook' }
+      },
+    }],
+    PostToolUse: [{
+      handler: async (input: HookInput) => {
+        const output = typeof input.toolOutput === 'string'
+          ? input.toolOutput.slice(0, 100)
+          : JSON.stringify(input.toolOutput).slice(0, 100)
+        console.log(`[Hook] Tool ${input.toolName} completed: ${output}...`)
+      },
+    }],
+    PostToolUseFailure: [{
+      handler: async (input: HookInput) => {
+        console.log(`[Hook] Tool ${input.toolName} FAILED: ${input.error}`)
+      },
+    }],
+    Stop: [{
+      handler: async () => {
+        console.log('[Hook] Agent loop completed')
+      },
+    }],
+    SessionEnd: [{
+      handler: async () => {
+        console.log('[Hook] Session ended')
+      },
+    }],
+  })
+
+  // Create agent with hook registry
+  // Note: For direct HookRegistry usage, we pass hooks via the engine config.
+  // The AgentOptions.hooks format also works (see below).
+  const agent = createAgent({
+    model: process.env.CODEANY_MODEL || 'claude-sonnet-4-6',
+    maxTurns: 5,
+    // Alternative: use AgentOptions.hooks format
+    hooks: {
+      PreToolUse: [{
+        hooks: [async (input: any, toolUseId: string) => {
+          console.log(`[AgentHook] PreToolUse: ${input.toolName} (${toolUseId})`)
+        }],
+      }],
+    },
+  })
+
+  for await (const event of agent.query('What files are in the current directory? Be brief.')) {
+    const msg = event as any
+    if (msg.type === 'assistant') {
+      for (const block of msg.message?.content || []) {
+        if (block.type === 'text' && block.text.trim()) {
+          console.log(`\nAssistant: ${block.text.slice(0, 200)}`)
+        }
+      }
+    }
+    if (msg.type === 'result') {
+      console.log(`\n--- ${msg.subtype} ---`)
+    }
+  }
+
+  await agent.close()
+}
+
+main().catch(console.error)

package/examples/14-openai-compat.ts

@@ -0,0 +1,71 @@
+/**
+ * Example 14: OpenAI-Compatible Models
+ *
+ * Shows how to use the SDK with OpenAI's API or any OpenAI-compatible
+ * endpoint (e.g., DeepSeek, Qwen, vLLM, Ollama).
+ *
+ * Environment variables:
+ *   CODEANY_API_KEY=sk-...          # Your OpenAI API key
+ *   CODEANY_BASE_URL=https://api.openai.com/v1   # Optional, defaults to OpenAI
+ *   CODEANY_API_TYPE=openai-completions           # Optional, auto-detected from model name
+ *
+ * Run: npx tsx examples/14-openai-compat.ts
+ */
+import { createAgent } from '../src/index.js'
+
+async function main() {
+  console.log('--- Example 14: OpenAI-Compatible Models ---\n')
+
+  // Option 1: Explicit apiType
+  const agent = createAgent({
+    apiType: 'openai-completions',
+    model: process.env.CODEANY_MODEL || 'gpt-4o',
+    apiKey: process.env.CODEANY_API_KEY,
+    baseURL: process.env.CODEANY_BASE_URL || 'https://api.openai.com/v1',
+    maxTurns: 5,
+  })
+
+  console.log(`API Type: ${agent.getApiType()}`)
+  console.log(`Model: ${process.env.CODEANY_MODEL || 'gpt-4o'}\n`)
+
+  // Option 2: Auto-detected from model name (uncomment to try)
+  // const agent = createAgent({
+  //   model: 'gpt-4o',  // Auto-detects 'openai-completions'
+  //   apiKey: process.env.CODEANY_API_KEY,
+  // })
+
+  // Option 3: DeepSeek example (uncomment to try)
+  // const agent = createAgent({
+  //   model: 'deepseek-chat',
+  //   apiKey: process.env.CODEANY_API_KEY,
+  //   baseURL: 'https://api.deepseek.com/v1',
+  // })
+
+  // Option 4: Via environment variables only
+  // CODEANY_API_TYPE=openai-completions
+  // CODEANY_MODEL=gpt-4o
+  // CODEANY_API_KEY=sk-...
+  // CODEANY_BASE_URL=https://api.openai.com/v1
+  // const agent = createAgent()
+
+  for await (const event of agent.query('What is 2+2? Reply in one sentence.')) {
+    const msg = event as any
+    if (msg.type === 'assistant') {
+      for (const block of msg.message?.content || []) {
+        if (block.type === 'text' && block.text.trim()) {
+          console.log(`Assistant: ${block.text}`)
+        }
+        if (block.type === 'tool_use') {
+          console.log(`[Tool: ${block.name}] ${JSON.stringify(block.input)}`)
+        }
+      }
+    }
+    if (msg.type === 'result') {
+      console.log(`\n--- ${msg.subtype} (${msg.usage?.input_tokens}+${msg.usage?.output_tokens} tokens) ---`)
+    }
+  }
+
+  await agent.close()
+}
+
+main().catch(console.error)

package/package.json

@@ -12,7 +12,7 @@
   "bugs": {
     "url": "https://github.com/codeany-ai/open-agent-sdk-typescript/issues"
   },
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Open-source Agent SDK. Runs the full agent loop in-process — no local CLI required. Deploy anywhere: cloud, serverless, Docker, CI/CD.",
   "type": "module",
   "main": "./dist/index.js",