@codeany/open-agent-sdk 0.1.0 → 0.2.1

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/dist/agent.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Agent - High-level API
+ *
+ * Provides createAgent() and query() interfaces compatible with
+ * open-agent-sdk.
+ *
+ * Usage:
+ *   import { createAgent } from 'open-agent-sdk'
+ *   const agent = createAgent({ model: 'claude-sonnet-4-6' })
+ *   for await (const event of agent.query('Hello')) { ... }
+ *
+ *   // OpenAI-compatible models
+ *   const agent = createAgent({
+ *     apiType: 'openai-completions',
+ *     model: 'gpt-4o',
+ *     apiKey: 'sk-...',
+ *     baseURL: 'https://api.openai.com/v1',
+ *   })
+ */
+import type { AgentOptions, QueryResult, SDKMessage, Message, PermissionMode } from './types.js';
+import { type ApiType } from './providers/index.js';
+export declare class Agent {
+    private cfg;
+    private toolPool;
+    private modelId;
+    private apiType;
+    private apiCredentials;
+    private provider;
+    private mcpLinks;
+    private history;
+    private messageLog;
+    private setupDone;
+    private sid;
+    private abortCtrl;
+    private currentEngine;
+    private hookRegistry;
+    constructor(options?: AgentOptions);
+    /**
+     * Resolve API type from options, env, or model name heuristic.
+     */
+    private resolveApiType;
+    /** Pick API key and base URL from options or CODEANY_* env vars. */
+    private pickCredentials;
+    /** Read a value from process.env (returns undefined if missing). */
+    private readEnv;
+    /** Assemble the available tool set based on options. */
+    private buildToolPool;
+    /**
+     * Async initialization: connect MCP servers, register agents, resume sessions.
+     */
+    private setup;
+    /**
+     * Run a query with streaming events.
+     */
+    query(prompt: string, overrides?: Partial<AgentOptions>): AsyncGenerator<SDKMessage, void>;
+    /**
+     * Convenience method: send a prompt and collect the final answer as a single object.
+     * Internally iterates through the streaming query and aggregates the outcome.
+     */
+    prompt(text: string, overrides?: Partial<AgentOptions>): Promise<QueryResult>;
+    /**
+     * Get conversation messages.
+     */
+    getMessages(): Message[];
+    /**
+     * Reset conversation history.
+     */
+    clear(): void;
+    /**
+     * Interrupt the current query.
+     */
+    interrupt(): Promise<void>;
+    /**
+     * Change the model during a session.
+     */
+    setModel(model?: string): Promise<void>;
+    /**
+     * Change the permission mode during a session.
+     */
+    setPermissionMode(mode: PermissionMode): Promise<void>;
+    /**
+     * Set maximum thinking tokens.
+     */
+    setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;
+    /**
+     * Get the session ID.
+     */
+    getSessionId(): string;
+    /**
+     * Get the current API type.
+     */
+    getApiType(): ApiType;
+    /**
+     * Stop a background task.
+     */
+    stopTask(taskId: string): Promise<void>;
+    /**
+     * Close MCP connections and clean up.
+     * Optionally persist session to disk.
+     */
+    close(): Promise<void>;
+}
+/** Factory: shorthand for `new Agent(options)`. */
+export declare function createAgent(options?: AgentOptions): Agent;
+/**
+ * Execute a single agentic query without managing an Agent instance.
+ * The agent is created, used, and cleaned up automatically.
+ */
+export declare function query(params: {
+    prompt: string;
+    options?: AgentOptions;
+}): AsyncGenerator<SDKMessage, void>;
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EAGV,OAAO,EACP,cAAc,EACf,MAAM,YAAY,CAAA;AAYnB,OAAO,EAAoC,KAAK,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAOrF,qBAAa,KAAK;IAChB,OAAO,CAAC,GAAG,CAAc;IACzB,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,SAAS,CAAe;IAChC,OAAO,CAAC,GAAG,CAAQ;IACnB,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,aAAa,CAA2B;IAChD,OAAO,CAAC,YAAY,CAAc;gBAEtB,OAAO,GAAE,YAAiB;IAkDtC;;OAEG;IACH,OAAO,CAAC,cAAc;IAgCtB,oEAAoE;IACpE,OAAO,CAAC,eAAe;IAgBvB,oEAAoE;IACpE,OAAO,CAAC,OAAO;IAIf,wDAAwD;IACxD,OAAO,CAAC,aAAa;IAerB;;OAEG;YACW,KAAK;IAsCnB;;OAEG;IACI,KAAK,CACV,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAChC,cAAc,CAAC,UAAU,EAAE,IAAI,CAAC;IAqHnC;;;OAGG;IACG,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAChC,OAAO,CAAC,WAAW,CAAC;IA+BvB;;OAEG;IACH,WAAW,IAAI,OAAO,EAAE;IAIxB;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAIhC;;OAEG;IACG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7C;;OAEG;IACG,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5D;;OAEG;IACG,oBAAoB,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ3E;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ7C;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAmB7B;AAMD,mDAAmD;AACnD,wBAAgB,WAAW,CAAC,OAAO,GAAE,YAAiB,GAAG,KAAK,CAE7D;AAMD;;;GAGG;AACH,wBAAuB,KAAK,CAAC,MAAM,EAAE;IACnC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,YAAY,CAAA;CACvB,GAAG,cAAc,CAAC,UAAU,EAAE,IAAI,CAAC,CAOnC"}