diff --git a/packages/coding-agent/docs/sdk.md b/packages/coding-agent/docs/sdk.md index 6db72279..2fa85cd0 100644 --- a/packages/coding-agent/docs/sdk.md +++ b/packages/coding-agent/docs/sdk.md @@ -54,7 +54,7 @@ The main factory function for a single `AgentSession`. `createAgentSession()` uses a `ResourceLoader` to supply extensions, skills, prompt templates, themes, and context files. If you do not provide one, it uses `DefaultResourceLoader` with standard discovery. ```typescript -import { createAgentSession } from "@earendil-works/pi-coding-agent"; +import { createAgentSession, SessionManager } from "@earendil-works/pi-coding-agent"; // Minimal: defaults with DefaultResourceLoader const { session } = await createAgentSession(); @@ -62,7 +62,7 @@ const { session } = await createAgentSession(); // Custom: override specific options const { session } = await createAgentSession({ model: myModel, - tools: [readTool, bashTool], + tools: ["read", "bash"], sessionManager: SessionManager.inMemory(), }); ``` @@ -466,64 +466,50 @@ const { session } = await createAgentSession({ resourceLoader: loader }); ### Tools -```typescript -import { - codingTools, // read, bash, edit, write (default) - readOnlyTools, // read, grep, find, ls - readTool, bashTool, editTool, writeTool, - grepTool, findTool, lsTool, -} from "@earendil-works/pi-coding-agent"; +Specify which built-in tools to enable: -// Use built-in tool set +- Built-in tool names: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls` +- Default built-ins: `read`, `bash`, `edit`, `write` +- `noTools: "all"` disables all tools +- `noTools: "builtin"` disables default built-ins while keeping extension and custom tools enabled + +```typescript +import { createAgentSession } from "@earendil-works/pi-coding-agent"; + +// Read-only mode const { session } = await createAgentSession({ - tools: readOnlyTools, + tools: ["read", "grep", "find", "ls"], }); // Pick specific tools const { session } = await createAgentSession({ - tools: [readTool, bashTool, grepTool], + tools: ["read", "bash", "grep"], }); ``` #### Tools with Custom cwd -**Important:** The pre-built tool instances (`readTool`, `bashTool`, etc.) use `process.cwd()` for path resolution. When you specify a custom `cwd` AND provide explicit `tools`, you must use the tool factory functions to ensure paths resolve correctly: +When you pass a custom `cwd`, `createAgentSession()` builds selected built-in tools for that cwd. ```typescript -import { - createCodingTools, // Creates [read, bash, edit, write] for specific cwd - createReadOnlyTools, // Creates [read, grep, find, ls] for specific cwd - createReadTool, - createBashTool, - createEditTool, - createWriteTool, - createGrepTool, - createFindTool, - createLsTool, -} from "@earendil-works/pi-coding-agent"; +import { createAgentSession, SessionManager } from "@earendil-works/pi-coding-agent"; const cwd = "/path/to/project"; -// Use factory for tool sets +// Use default tools for custom cwd const { session } = await createAgentSession({ cwd, - tools: createCodingTools(cwd), // Tools resolve paths relative to cwd + sessionManager: SessionManager.inMemory(cwd), }); -// Or pick specific tools +// Or pick specific tools for custom cwd const { session } = await createAgentSession({ cwd, - tools: [createReadTool(cwd), createBashTool(cwd), createGrepTool(cwd)], + tools: ["read", "bash", "grep"], + sessionManager: SessionManager.inMemory(cwd), }); ``` -**When you don't need factories:** -- If you omit `tools`, pi automatically creates them with the correct `cwd` -- If you use `process.cwd()` as your `cwd`, the pre-built instances work fine - -**When you must use factories:** -- When you specify both `cwd` (different from `process.cwd()`) AND `tools` - > See [examples/sdk/05-tools.ts](../examples/sdk/05-tools.ts) ### Custom Tools @@ -556,6 +542,8 @@ Use `defineTool()` for standalone definitions and arrays like `customTools: [myT Custom tools passed via `customTools` are combined with extension-registered tools. Extensions loaded by the ResourceLoader can also register tools via `pi.registerTool()`. +If you pass `tools`, include each custom or extension tool name you want enabled, for example `tools: ["read", "bash", "my_tool"]`. + > See [examples/sdk/05-tools.ts](../examples/sdk/05-tools.ts) ### Extensions @@ -885,12 +873,10 @@ import { getModel } from "@earendil-works/pi-ai"; import { Type } from "typebox"; import { AuthStorage, - bashTool, createAgentSession, DefaultResourceLoader, defineTool, ModelRegistry, - readTool, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent"; @@ -944,7 +930,7 @@ const { session } = await createAgentSession({ authStorage, modelRegistry, - tools: [readTool, bashTool], + tools: ["read", "bash", "status"], customTools: [statusTool], resourceLoader: loader, @@ -1123,13 +1109,7 @@ defineTool SessionManager SettingsManager -// Built-in tools (use process.cwd()) -codingTools -readOnlyTools -readTool, bashTool, editTool, writeTool -grepTool, findTool, lsTool - -// Tool factories (for custom cwd) +// Tool factories createCodingTools createReadOnlyTools createReadTool, createBashTool, createEditTool, createWriteTool diff --git a/packages/coding-agent/examples/sdk/README.md b/packages/coding-agent/examples/sdk/README.md index 0fd95cf0..a8011aae 100644 --- a/packages/coding-agent/examples/sdk/README.md +++ b/packages/coding-agent/examples/sdk/README.md @@ -12,7 +12,7 @@ The runtime example shows how to build a recreate function that closes over proc | `02-custom-model.ts` | Select model and thinking level | | `03-custom-prompt.ts` | Replace or modify system prompt | | `04-skills.ts` | Discover, filter, or replace skills | -| `05-tools.ts` | Built-in tools, custom tools | +| `05-tools.ts` | Built-in tool allowlists | | `06-extensions.ts` | Logging, blocking, result modification | | `07-context-files.ts` | AGENTS.md context files | | `08-slash-commands.ts` | File-based slash commands | @@ -40,9 +40,6 @@ import { ModelRegistry, SessionManager, SettingsManager, - codingTools, - readOnlyTools, - readTool, bashTool, editTool, writeTool, } from "@earendil-works/pi-coding-agent"; // Auth and models setup @@ -64,7 +61,7 @@ await loader.reload(); const { session } = await createAgentSession({ resourceLoader: loader, authStorage, modelRegistry }); // Read-only -const { session } = await createAgentSession({ tools: readOnlyTools, authStorage, modelRegistry }); +const { session } = await createAgentSession({ tools: ["read", "grep", "find", "ls"], authStorage, modelRegistry }); // In-memory const { session } = await createAgentSession({ @@ -92,8 +89,8 @@ const { session } = await createAgentSession({ authStorage: customAuth, modelRegistry: customRegistry, resourceLoader, - tools: [readTool, bashTool], - customTools: [{ tool: myTool }], + tools: ["read", "bash", "my_tool"], + customTools: [myTool], sessionManager: SessionManager.inMemory(), settingsManager: SettingsManager.inMemory(), }); @@ -117,7 +114,7 @@ await session.prompt("Hello"); | `agentDir` | `~/.pi/agent` | Config directory | | `model` | From settings/first available | Model to use | | `thinkingLevel` | From settings/"off" | off, low, medium, high | -| `tools` | `codingTools` | Built-in tools | +| `tools` | `["read", "bash", "edit", "write"]` built-ins | Allowlist tool names across built-in, extension, and custom tools | | `customTools` | `[]` | Additional tool definitions | | `resourceLoader` | DefaultResourceLoader | Resource loader for extensions, skills, prompts, themes | | `sessionManager` | `SessionManager.create(cwd)` | Persistence | diff --git a/packages/coding-agent/src/core/sdk.ts b/packages/coding-agent/src/core/sdk.ts index 8bc96072..3e0533d0 100644 --- a/packages/coding-agent/src/core/sdk.ts +++ b/packages/coding-agent/src/core/sdk.ts @@ -184,7 +184,7 @@ function getAttributionHeaders( * await loader.reload(); * const { session } = await createAgentSession({ * model: myModel, - * tools: [readTool, bashTool], + * tools: ["read", "bash"], * resourceLoader: loader, * sessionManager: SessionManager.inMemory(), * });