Update sdk readme and docs

Author: jahooma

sdk/README.md

@@ -23,10 +23,52 @@ npm install @codebuff/sdk
 
 ## Usage
 
+### Basic Example
+
 ```typescript
 import * as fs from 'fs'
 import * as os from 'os'
+import { CodebuffClient } from '@codebuff/sdk'
+
+// Available after running `codebuff login`
+const apiKey = JSON.parse(
+  fs
+    .readFileSync(os.homedir() + '/.config/manicode/credentials.json')
+    .toString(),
+).default.authToken
+
+const client = new CodebuffClient({
+  apiKey,
+  cwd: process.cwd(),
+  onError: (e) => console.error('Codebuff error:', e.message),
+})
+
+// First run
+const run1 = await client.run({
+  agent: 'base',
+  prompt: 'Create a simple calculator class',
+})
+
+// Continue the same session with a follow-up
+const run2 = await client.run({
+  agent: 'base',
+  prompt: 'Add unit tests for the calculator',
+  previousRun: run1,
+  handleEvent: (event) => {
+    // Log all events
+    console.log('Progress:', event)
+  },
+})
+
+client.closeConnection()
+```
 
+### Advanced Example with Custom Agents, Tools, and Images
+
+```typescript
+import * as fs from 'fs'
+import * as os from 'os'
+import { z } from 'zod'
 import {
   CodebuffClient,
   generateInitialRunState,
@@ -39,20 +81,16 @@ const apiKey = JSON.parse(
     .readFileSync(os.homedir() + '/.config/manicode/credentials.json')
     .toString(),
 ).default.authToken
-const cwd = process.cwd()
 
 const client = new CodebuffClient({
   apiKey,
-  cwd,
+  cwd: process.cwd(),
   onError: (e) => console.error('Codebuff error:', e.message),
-  // Optional: Override the implementation of specific tools.
-  overrideTools: {},
 })
 
-// Single run
-const emptyRun = generateInitialRunState({ cwd })
-
-const runWithExampleImage = withAdditionalMessage({
+// Create a run with an image
+const emptyRun = await generateInitialRunState({ cwd: process.cwd() })
+const runWithImage = withAdditionalMessage({
   runState: emptyRun,
   message: {
     role: 'user',
@@ -67,37 +105,47 @@ const runWithExampleImage = withAdditionalMessage({
   },
 })
 
-const run1 = await client.run({
-  agent: 'base',
-  prompt: 'What is depicted in the attached image?',
-  previousRun: runWithExampleImage,
-  handleEvent: (event) => {
-    console.log('event from run1:', { event })
-  },
-})
-
-// Continue same session with follow‑up
-const run2 = await client.run({
-  agent: 'base',
-  prompt: 'What about the text? (ignoring the pictures)',
-  previousRun: run1,
+const result = await client.run({
+  agent: 'my-custom-agent',
+  prompt: 'Analyze this image and create code based on what you see',
+  previousRun: runWithImage,
 
-  // Stream events (optional)
-  handleEvent: (event) => {
-    // event includes streamed updates like assistant messages and tool calls
-    console.log('event from run2:', event)
-  },
-
-  // Custom agents (optional)
+  // Custom agent definitions
   agentDefinitions: [
     {
-      id: 'my-awesome-agent',
+      id: 'my-custom-agent',
       model: 'openai/gpt-5',
-      displayName: 'My awesome agent',
-      instructionsPrompt: 'Do something awesome',
+      displayName: 'Image Analyzer',
+      instructionsPrompt:
+        '1. describe all the details in the image. 2. answer the user prompt',
       // ... other AgentDefinition properties
     },
   ],
+
+  // Custom tool definitions
+  customToolDefinitions: [
+    {
+      toolName: 'fetch_api_data',
+      zodSchema: z
+        .object({
+          url: z.string().url(),
+          method: z.enum(['GET', 'POST']).default('GET'),
+          headers: z.record(z.string()).optional(),
+        })
+        .describe('Fetch data from an API endpoint'),
+      handler: async ({ url, method, headers }) => {
+        const response = await fetch(url, { method, headers })
+        const data = await response.text()
+        return {
+          toolResultMessage: `API Response: ${data.slice(0, 500)}...`,
+        }
+      },
+    },
+  ],
+
+  handleEvent: (event) => {
+    console.log('Agent progress:', event)
+  },
 })
 
 client.closeConnection()
@@ -126,6 +174,9 @@ Runs a Codebuff agent with the specified options.
 - **`knowledgeFiles`** (object, optional): Knowledge files to inject into every `run()` call. Uses the same schema as `projectFiles` - keys are file paths and values are file contents. These files are added directly to the agent's context.
 
 - **`agentDefinitions`** (array, optional): Array of custom agent configurations. Each object should satisfy the AgentConfig type.
+
+- **`customToolDefinitions`** (array, optional): Array of custom tool definitions that extend the agent's capabilities. Each tool definition includes a name, Zod schema for input validation, and a handler function. These tools can be called by the agent during execution.
+
 - **`maxAgentSteps`** (number, optional): Maximum number of steps the agent can take before stopping. Use this as a safety measure in case your agent starts going off the rails. A reasonable number is around 20.
 
 #### Returns

sdk/package.json

@@ -2,7 +2,7 @@
   "name": "@codebuff/sdk",
   "private": false,
   "access": "public",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Official SDK for Codebuff — AI coding agent & framework",
   "license": "MIT",
   "type": "module",

sdk/src/client.ts

@@ -112,6 +112,7 @@ export class CodebuffClient {
    * @param projectFiles - (Optional) All the files in your project as a plain JavaScript object. Keys should be the full path from your current directory to each file, and values should be the string contents of the file. Example: { "src/index.ts": "console.log('hi')" }. This helps Codebuff pick good source files for context.
    * @param knowledgeFiles - (Optional) Knowledge files to inject into every run() call. Uses the same schema as projectFiles - keys are file paths and values are file contents. These files are added directly to the agent's context.
    * @param agentDefinitions - (Optional) Array of custom agent definitions. Each object should satisfy the AgentDefinition type. You can input the agent's id field into the agent parameter to run that agent.
+   * @param customToolDefinitions - (Optional) Array of custom tool definitions that extend the agent's capabilities. Each tool definition includes a name, Zod schema for input validation, and a handler function. These tools can be called by the agent during execution.
    * @param maxAgentSteps - (Optional) Maximum number of steps the agent can take before stopping. Use this as a safety measure in case your agent starts going off the rails. A reasonable number is around 20.
    *
    * @returns A Promise that resolves to a RunState JSON object which you can pass to a subsequent run() call to continue the run.