run agent builder

Author: charleslien

.agents/examples/01-basic-diff-reviewer.ts

@@ -0,0 +1,17 @@
+import type { AgentDefinition } from '../types/agent-definition'
+
+const definition: AgentDefinition = {
+  id: 'basic-diff-reviewer',
+  displayName: 'Basic Diff Reviewer',
+  model: 'anthropic/claude-4-sonnet-20250522',
+  toolNames: ['read_files', 'run_terminal_command'],
+
+  spawnerPrompt: 'Spawn when you need to review code changes in the git diff',
+
+  instructionsPrompt: `Execute the following steps:
+1. Run git diff
+2. Read the files that have changed
+3. Review the changes and suggest improvements`,
+}
+
+export default definition

.agents/examples/02-intermediate-git-committer.ts

@@ -0,0 +1,76 @@
+import type {
+  AgentDefinition,
+  AgentStepContext,
+  ToolCall,
+} from '../types/agent-definition'
+
+const definition: AgentDefinition = {
+  id: 'git-committer',
+  displayName: 'Intermediate Git Committer',
+  model: 'anthropic/claude-4-sonnet-20250522',
+  toolNames: ['read_files', 'run_terminal_command', 'add_message', 'end_turn'],
+
+  inputSchema: {
+    prompt: {
+      type: 'string',
+      description: 'What changes to commit',
+    },
+  },
+
+  spawnerPrompt:
+    'Spawn when you need to commit code changes to git with an appropriate commit message',
+
+  systemPrompt:
+    'You are an expert software developer. Your job is to create a git commit with a really good commit message.',
+
+  instructionsPrompt:
+    'Follow the steps to create a good commit: analyze changes with git diff and git log, read relevant files for context, stage appropriate files, analyze changes, and create a commit with proper formatting.',
+
+  handleSteps: function* ({ agentState, prompt, params }: AgentStepContext) {
+    // Step 1: Run git diff and git log to analyze changes.
+    yield {
+      toolName: 'run_terminal_command',
+      input: {
+        command: 'git diff',
+        process_type: 'SYNC',
+        timeout_seconds: 30,
+      },
+    } satisfies ToolCall
+
+    yield {
+      toolName: 'run_terminal_command',
+      input: {
+        command: 'git log --oneline -10',
+        process_type: 'SYNC',
+        timeout_seconds: 30,
+      },
+    } satisfies ToolCall
+
+    // Step 2: Put words in AI's mouth so it will read files next.
+    yield {
+      toolName: 'add_message',
+      input: {
+        role: 'assistant',
+        content:
+          "I've analyzed the git diff and recent commit history. Now I'll read any relevant files to better understand the context of these changes.",
+      },
+    } satisfies ToolCall
+
+    // Step 3: Let AI generate a step to decide which files to read.
+    yield 'STEP'
+
+    // Step 4: Put words in AI's mouth to analyze the changes and create a commit.
+    yield {
+      toolName: 'add_message',
+      input: {
+        role: 'assistant',
+        content:
+          "Now I'll analyze the changes and create a commit with a good commit message.",
+      },
+    } satisfies ToolCall
+
+    yield 'STEP_ALL'
+  },
+}
+
+export default definition

.agents/examples/03-advanced-file-explorer.ts

@@ -0,0 +1,73 @@
+import type { AgentDefinition, ToolCall } from '../types/agent-definition'
+
+const definition: AgentDefinition = {
+  id: 'advanced-file-explorer',
+  displayName: 'Dora the File Explorer',
+  model: 'openai/gpt-5',
+
+  spawnerPrompt:
+    'Spawns multiple file picker agents in parallel to comprehensively explore the codebase from different perspectives',
+
+  includeMessageHistory: false,
+  toolNames: ['spawn_agents', 'set_output'],
+  spawnableAgents: [`codebuff/file-picker@0.0.1`],
+
+  inputSchema: {
+    prompt: {
+      description: 'What you need to accomplish by exploring the codebase',
+      type: 'string',
+    },
+    params: {
+      type: 'object',
+      properties: {
+        prompts: {
+          description:
+            'List of 1-4 different parts of the codebase that could be useful to explore',
+          type: 'array',
+          items: {
+            type: 'string',
+          },
+        },
+      },
+      required: ['prompts'],
+      additionalProperties: false,
+    },
+  },
+  outputMode: 'structured_output',
+  outputSchema: {
+    type: 'object',
+    properties: {
+      results: {
+        type: 'string',
+        description: 'The results of the file exploration',
+      },
+    },
+    required: ['results'],
+    additionalProperties: false,
+  },
+
+  handleSteps: function* ({ prompt, params }) {
+    const prompts: string[] = params?.prompts ?? []
+    const filePickerPrompts = prompts.map(
+        (focusPrompt) =>
+          `Based on the overall goal "${prompt}", find files related to this specific area: ${focusPrompt}`,
+      ),
+      { toolResult: spawnResult } = yield {
+        toolName: 'spawn_agents',
+        input: {
+          agents: filePickerPrompts.map((promptText) => ({
+            agent_type: 'codebuff/file-picker@0.0.1',
+            prompt: promptText,
+          })),
+        },
+      } satisfies ToolCall
+    yield {
+      toolName: 'set_output',
+      input: {
+        results: spawnResult,
+      },
+    } satisfies ToolCall
+  },
+}
+
+export default definition

.agents/types/agent-definition.ts

@@ -62,7 +62,7 @@ export interface AgentDefinition {
    */
   inputSchema?: {
     prompt?: { type: 'string'; description?: string }
-    params?: JsonSchema
+    params?: JsonObjectSchema
   }
 
   /** Whether to include conversation history from the parent agent in context.
@@ -83,7 +83,7 @@ export interface AgentDefinition {
   outputMode?: 'last_message' | 'all_messages' | 'structured_output'
 
   /** JSON schema for structured output (when outputMode is 'structured_output') */
-  outputSchema?: JsonSchema
+  outputSchema?: JsonObjectSchema
 
   // ============================================================================
   // Prompts
@@ -116,7 +116,7 @@ export interface AgentDefinition {
   /** Programmatically step the agent forward and run tools.
    *
    * You can either yield:
-   * - A tool call object with toolName and input properties.
+   * - A tool call object with toolName and args properties.
    * - 'STEP' to run agent's model and generate one assistant message.
    * - 'STEP_ALL' to run the agent's model until it uses the end_turn tool or stops includes no tool calls in a message.
    *
@@ -126,7 +126,7 @@ export interface AgentDefinition {
    * function* handleSteps({ agentStep, prompt, params}) {
    *   const { toolResult } = yield {
    *     toolName: 'read_files',
-   *     input: { paths: ['file1.txt', 'file2.txt'] }
+   *     args: { paths: ['file1.txt', 'file2.txt'] }
    *   }
    *   yield 'STEP_ALL'
    * }
@@ -136,7 +136,7 @@ export interface AgentDefinition {
    *   while (true) {
    *     yield {
    *       toolName: 'spawn_agents',
-   *       input: {
+   *       args: {
    *         agents: [
    *         {
    *           agent_type: 'thinker',
@@ -191,19 +191,29 @@ export interface AgentStepContext {
 export type ToolCall<T extends ToolName = ToolName> = {
   [K in T]: {
     toolName: K
-    input?: Tools.GetToolParams<K>
+    input: Tools.GetToolParams<K>
   }
 }[T]
 
 /**
  * JSON Schema definition (for prompt schema or output schema)
  */
-export interface JsonSchema {
-  type: string
-  properties?: Record<string, any>
+export type JsonSchema = {
+  type?:
+    | 'object'
+    | 'array'
+    | 'string'
+    | 'number'
+    | 'boolean'
+    | 'null'
+    | 'integer'
+  description?: string
+  properties?: Record<string, JsonSchema | boolean>
   required?: string[]
-  [key: string]: any
+  enum?: Array<string | number | boolean | null>
+  [k: string]: unknown
 }
+export type JsonObjectSchema = JsonSchema & { type: 'object' }
 
 // ============================================================================
 // Available Tools