@claudebuddy/claudebuddy-agent-sdk 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CodeAny (https://codeany.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,501 @@
+# Open Agent SDK (TypeScript)
+
+[![npm version](https://img.shields.io/npm/v/@claudebuddy/claudebuddy-agent-sdk)](https://www.npmjs.com/package/@claudebuddy/claudebuddy-agent-sdk)
+[![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. 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/claudebuddy/claudebuddy-agent-sdk)
+
+## Get started
+
+```bash
+npm install @claudebuddy/claudebuddy-agent-sdk
+```
+
+Set your API key:
+
+```bash
+export CLAUDEBUDDY_API_KEY=your-api-key
+```
+
+### OpenAI-compatible models
+
+Works with OpenAI, DeepSeek, Qwen, Mistral, or any OpenAI-compatible endpoint:
+
+```bash
+export CLAUDEBUDDY_API_TYPE=openai-completions
+export CLAUDEBUDDY_API_KEY=sk-...
+export CLAUDEBUDDY_BASE_URL=https://api.openai.com/v1
+export CLAUDEBUDDY_MODEL=gpt-4o
+```
+
+### Third-party Anthropic-compatible providers
+
+```bash
+export CLAUDEBUDDY_BASE_URL=https://openrouter.ai/api
+export CLAUDEBUDDY_API_KEY=sk-or-...
+export CLAUDEBUDDY_MODEL=anthropic/claude-sonnet-4
+```
+
+## Quick start
+
+### One-shot query (streaming)
+
+```typescript
+import { query } from "@claudebuddy/claudebuddy-agent-sdk";
+
+for await (const message of query({
+  prompt: "Read package.json and tell me the project name.",
+  options: {
+    allowedTools: ["Read", "Glob"],
+    permissionMode: "bypassPermissions",
+  },
+})) {
+  if (message.type === "assistant") {
+    for (const block of message.message.content) {
+      if ("text" in block) console.log(block.text);
+    }
+  }
+}
+```
+
+### Simple blocking prompt
+
+```typescript
+import { createAgent } from "@claudebuddy/claudebuddy-agent-sdk";
+
+const agent = createAgent({ model: "claude-sonnet-4-6" });
+const result = await agent.prompt("What files are in this project?");
+
+console.log(result.text);
+console.log(
+  `Turns: ${result.num_turns}, Tokens: ${result.usage.input_tokens + result.usage.output_tokens}`,
+);
+```
+
+### OpenAI / GPT models
+
+```typescript
+import { createAgent } from "@claudebuddy/claudebuddy-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
+import { createAgent } from "@claudebuddy/claudebuddy-agent-sdk";
+
+const agent = createAgent({ maxTurns: 5 });
+
+const r1 = await agent.prompt(
+  'Create a file /tmp/hello.txt with "Hello World"',
+);
+console.log(r1.text);
+
+const r2 = await agent.prompt("Read back the file you just created");
+console.log(r2.text);
+
+console.log(`Session messages: ${agent.getMessages().length}`);
+```
+
+### Custom tools (Zod schema)
+
+```typescript
+import { z } from "zod";
+import { query, tool, createSdkMcpServer } from "@claudebuddy/claudebuddy-agent-sdk";
+
+const getWeather = tool(
+  "get_weather",
+  "Get the temperature for a city",
+  { city: z.string().describe("City name") },
+  async ({ city }) => ({
+    content: [{ type: "text", text: `${city}: 22°C, sunny` }],
+  }),
+);
+
+const server = createSdkMcpServer({ name: "weather", tools: [getWeather] });
+
+for await (const msg of query({
+  prompt: "What is the weather in Tokyo?",
+  options: { mcpServers: { weather: server } },
+})) {
+  if (msg.type === "result")
+    console.log(`Done: $${msg.total_cost_usd?.toFixed(4)}`);
+}
+```
+
+### Custom tools (low-level)
+
+```typescript
+import {
+  createAgent,
+  getAllBaseTools,
+  defineTool,
+} from "@claudebuddy/claudebuddy-agent-sdk";
+
+const calculator = defineTool({
+  name: "Calculator",
+  description: "Evaluate a math expression",
+  inputSchema: {
+    type: "object",
+    properties: { expression: { type: "string" } },
+    required: ["expression"],
+  },
+  isReadOnly: true,
+  async call(input) {
+    const result = Function(`'use strict'; return (${input.expression})`)();
+    return `${input.expression} = ${result}`;
+  },
+});
+
+const agent = createAgent({ tools: [...getAllBaseTools(), calculator] });
+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 "@claudebuddy/claudebuddy-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 "@claudebuddy/claudebuddy-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
+import { createAgent } from "@claudebuddy/claudebuddy-agent-sdk";
+
+const agent = createAgent({
+  mcpServers: {
+    filesystem: {
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+    },
+  },
+});
+
+const result = await agent.prompt("List files in /tmp");
+console.log(result.text);
+await agent.close();
+```
+
+### Subagents
+
+```typescript
+import { query } from "@claudebuddy/claudebuddy-agent-sdk";
+
+for await (const msg of query({
+  prompt: "Use the code-reviewer agent to review src/index.ts",
+  options: {
+    agents: {
+      "code-reviewer": {
+        description: "Expert code reviewer",
+        prompt: "Analyze code quality. Focus on security and performance.",
+        tools: ["Read", "Glob", "Grep"],
+      },
+    },
+  },
+})) {
+  if (msg.type === "result") console.log("Done");
+}
+```
+
+### Permissions
+
+```typescript
+import { query } from "@claudebuddy/claudebuddy-agent-sdk";
+
+// Read-only agent — can only analyze, not modify
+for await (const msg of query({
+  prompt: "Review the code in src/ for best practices.",
+  options: {
+    allowedTools: ["Read", "Glob", "Grep"],
+    permissionMode: "dontAsk",
+  },
+})) {
+  // ...
+}
+```
+
+### Web UI
+
+A built-in web chat interface is included for testing:
+
+```bash
+npx tsx examples/web/server.ts
+# Open http://localhost:8081
+```
+
+## API reference
+
+### Top-level functions
+
+| Function                              | Description                                                    |
+| ------------------------------------- | -------------------------------------------------------------- |
+| `query({ prompt, options })`          | One-shot streaming query, returns `AsyncGenerator<SDKMessage>` |
+| `createAgent(options)`                | Create a reusable agent with session persistence               |
+| `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 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                                        |
+| `forkSession(id)`                     | Fork a session for branching                                   |
+
+### Agent methods
+
+| Method                          | Description                                           |
+| ------------------------------- | ----------------------------------------------------- |
+| `agent.query(prompt)`           | Streaming query, returns `AsyncGenerator<SDKMessage>` |
+| `agent.prompt(text)`            | Blocking query, returns `Promise<QueryResult>`        |
+| `agent.getMessages()`           | Get conversation history                              |
+| `agent.clear()`                 | Reset session                                         |
+| `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`                                | `CLAUDEBUDDY_API_KEY`      | API key                                                              |
+| `baseURL`            | `string`                                | —                      | Custom API endpoint                                                  |
+| `cwd`                | `string`                                | `process.cwd()`        | Working directory                                                    |
+| `systemPrompt`       | `string`                                | —                      | System prompt override                                               |
+| `appendSystemPrompt` | `string`                                | —                      | Append to default system prompt                                      |
+| `tools`              | `ToolDefinition[]`                      | All built-in           | Available tools                                                      |
+| `allowedTools`       | `string[]`                              | —                      | Tool allow-list                                                      |
+| `disallowedTools`    | `string[]`                              | —                      | Tool deny-list                                                       |
+| `permissionMode`     | `string`                                | `bypassPermissions`    | `default` / `acceptEdits` / `dontAsk` / `bypassPermissions` / `plan` |
+| `canUseTool`         | `function`                              | —                      | Custom permission callback                                           |
+| `maxTurns`           | `number`                                | `10`                   | Max agentic turns                                                    |
+| `maxBudgetUsd`       | `number`                                | —                      | Spending cap                                                         |
+| `thinking`           | `ThinkingConfig`                        | `{ type: 'adaptive' }` | Extended thinking                                                    |
+| `effort`             | `string`                                | `high`                 | Reasoning effort: `low` / `medium` / `high` / `max`                  |
+| `mcpServers`         | `Record<string, McpServerConfig>`       | —                      | MCP server connections                                               |
+| `agents`             | `Record<string, AgentDefinition>`       | —                      | Subagent definitions                                                 |
+| `hooks`              | `Record<string, HookCallbackMatcher[]>` | —                      | Lifecycle hooks                                                      |
+| `resume`             | `string`                                | —                      | Resume session by ID                                                 |
+| `continue`           | `boolean`                               | `false`                | Continue most recent session                                         |
+| `persistSession`     | `boolean`                               | `true`                 | Persist session to disk                                              |
+| `sessionId`          | `string`                                | auto                   | Explicit session ID                                                  |
+| `outputFormat`       | `{ type: 'json_schema', schema }`       | —                      | Structured output                                                    |
+| `sandbox`            | `SandboxSettings`                       | —                      | Filesystem/network sandbox                                           |
+| `settingSources`     | `SettingSource[]`                       | —                      | Load AGENT.md, project settings                                      |
+| `env`                | `Record<string, string>`                | —                      | Environment variables                                                |
+| `abortController`    | `AbortController`                       | —                      | Cancellation controller                                              |
+
+### Environment variables
+
+| Variable             | Description                                              |
+| -------------------- | -------------------------------------------------------- |
+| `CLAUDEBUDDY_API_KEY`    | API key (required)                                       |
+| `CLAUDEBUDDY_API_TYPE`   | `anthropic-messages` (default) or `openai-completions`   |
+| `CLAUDEBUDDY_MODEL`      | Default model override                                   |
+| `CLAUDEBUDDY_BASE_URL`   | Custom API endpoint                                      |
+| `CLAUDEBUDDY_AUTH_TOKEN` | Alternative auth token                                   |
+
+## Built-in tools
+
+| Tool                                       | Description                                  |
+| ------------------------------------------ | -------------------------------------------- |
+| **Bash**                                   | Execute shell commands                       |
+| **Read**                                   | Read files with line numbers                 |
+| **Write**                                  | Create / overwrite files                     |
+| **Edit**                                   | Precise string replacement in files          |
+| **Glob**                                   | Find files by pattern                        |
+| **Grep**                                   | Search file contents with regex              |
+| **WebFetch**                               | Fetch and parse web content                  |
+| **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                        |
+| **EnterWorktree/ExitWorktree**             | Git worktree isolation                       |
+| **EnterPlanMode/ExitPlanMode**             | Structured planning workflow                 |
+| **AskUserQuestion**                        | Ask the user for input                       |
+| **ToolSearch**                             | Discover lazy-loaded tools                   |
+| **ListMcpResources/ReadMcpResource**       | MCP resource access                          |
+| **CronCreate/Delete/List**                 | Scheduled task management                    |
+| **RemoteTrigger**                          | Remote agent triggers                        |
+| **LSP**                                    | Language Server Protocol (code intelligence) |
+| **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
+
+```
+┌──────────────────────────────────────────────────────┐
+│                   Your Application                    │
+│                                                       │
+│   import { createAgent } from '@claudebuddy/claudebuddy-agent-sdk' │
+└────────────────────────┬─────────────────────────────┘
+                         │
+              ┌──────────▼──────────┐
+              │       Agent         │  Session state, tool pool,
+              │  query() / prompt() │  MCP connections, hooks
+              └──────────┬──────────┘
+                         │
+              ┌──────────▼──────────┐
+              │    QueryEngine      │  Agentic loop:
+              │   submitMessage()   │  API call → tools → repeat
+              └──────────┬──────────┘
+                         │
+         ┌───────────────┼───────────────┐
+         │               │               │
+   ┌─────▼─────┐  ┌─────▼─────┐  ┌─────▼─────┐
+   │  Provider  │  │  35 Tools │  │    MCP     │
+   │ Anthropic  │  │ Bash,Read │  │  Servers   │
+   │  OpenAI    │  │ Edit,...  │  │ stdio/SSE/ │
+   │ DeepSeek   │  │ + Skills  │  │ HTTP/SDK   │
+   └───────────┘  └───────────┘  └───────────┘
+```
+
+**Key internals:**
+
+| 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
+
+| #   | File                                  | Description                            |
+| --- | ------------------------------------- | -------------------------------------- |
+| 01  | `examples/01-simple-query.ts`         | Streaming query with event handling    |
+| 02  | `examples/02-multi-tool.ts`           | Multi-tool orchestration (Glob + Bash) |
+| 03  | `examples/03-multi-turn.ts`           | Multi-turn session persistence         |
+| 04  | `examples/04-prompt-api.ts`           | Blocking `prompt()` API                |
+| 05  | `examples/05-custom-system-prompt.ts` | Custom system prompt                   |
+| 06  | `examples/06-mcp-server.ts`           | MCP server integration                 |
+| 07  | `examples/07-custom-tools.ts`         | Custom tools with `defineTool()`       |
+| 08  | `examples/08-official-api-compat.ts`  | `query()` API pattern                  |
+| 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:
+
+```bash
+npx tsx examples/01-simple-query.ts
+```
+
+Start the web UI:
+
+```bash
+npx tsx examples/web/server.ts
+```
+
+## Star History
+
+<a href="https://www.star-history.com/?repos=claudebuddy%2Fclaudebuddy-agent-sdk&type=timeline&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=claudebuddy/claudebuddy-agent-sdk&type=timeline&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=claudebuddy/claudebuddy-agent-sdk&type=timeline&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/image?repos=claudebuddy/claudebuddy-agent-sdk&type=timeline&legend=top-left" />
+ </picture>
+</a>
+
+## License
+
+MIT

package/dist/agent.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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 CLAUDEBUDDY_* env vars. */
+    private pickCredentials;
+    /**
+     * Read an env var by its short key using the CLAUDEBUDDY_ prefix.
+     * e.g. readEnv('MODEL') checks CLAUDEBUDDY_MODEL.
+     */
+    private readEnv;
+    /** Read a value from the options `env` map using the CLAUDEBUDDY_ prefix. */
+    private envMapValue;
+    /** 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 | any[], 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>;
+    /**
+     * Goal-driven autonomous loop.
+     *
+     * Runs the agent toward `goal` over up to `maxRounds` rounds. Unlike a single
+     * `query`, the agent keeps working ("give it a task and let it run until done")
+     * and only stops when:
+     *  - it calls the injected `update_goal` tool with goal_status="complete", or
+     *  - it reports goal_status="blocked", or
+     *  - `maxRounds` is exhausted (returns with a helpful error event), or
+     *  - it is aborted.
+     *
+     * The `update_goal` internal tool is injected into the tool pool and a
+     * goal-mode system prompt is appended, so the agent knows it should keep
+     * working autonomously and how to signal completion.
+     */
+    runGoal(goal: string, overrides?: {
+        maxGoalRounds?: number;
+        turnsPerRound?: number;
+    }): AsyncGenerator<SDKMessage, void>;
+    /**
+     * 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 | any[];
+    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;AAarF,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,wEAAwE;IACxE,OAAO,CAAC,eAAe;IAevB;;;OAGG;IACH,OAAO,CAAC,OAAO;IAIf,6EAA6E;IAC7E,OAAO,CAAC,WAAW;IAInB,wDAAwD;IACxD,OAAO,CAAC,aAAa;IAerB;;OAEG;YACW,KAAK;IA2CnB;;OAEG;IACI,KAAK,CACV,MAAM,EAAE,MAAM,GAAG,GAAG,EAAE,EACtB,SAAS,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAChC,cAAc,CAAC,UAAU,EAAE,IAAI,CAAC;IAuInC;;;OAGG;IACG,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAChC,OAAO,CAAC,WAAW,CAAC;IA+BvB;;;;;;;;;;;;;;OAcG;IACI,OAAO,CACZ,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7D,cAAc,CAAC,UAAU,EAAE,IAAI,CAAC;IAyFnC;;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,GAAG,GAAG,EAAE,CAAA;IACtB,OAAO,CAAC,EAAE,YAAY,CAAA;CACvB,GAAG,cAAc,CAAC,UAAU,EAAE,IAAI,CAAC,CAOnC"}