Load AgentDefinition.ts file for Agent Reference section

Author: jahooma

bun.lock

@@ -12,8 +12,8 @@ import type { AgentState, AgentTemplateType } from './session-state'
 import type {
   ToolCall,
   AgentState as PublicAgentState,
-  Logger,
 } from '../templates/initial-agents-dir/types/agent-definition'
+import type { Logger } from '../templates/initial-agents-dir/types/util-types'
 import type { ToolName } from '../tools/constants'
 import type { OpenRouterProviderOptions } from '@codebuff/internal/openrouter-ai-sdk'
 import type { z } from 'zod/v4'

common/src/types/agent-template.ts

@@ -0,0 +1,38 @@
+import { NextResponse } from 'next/server'
+import { readFile } from 'fs/promises'
+import { join } from 'path'
+
+/**
+ * API route that serves the content of the agent-definition.ts file
+ * This allows the docs to dynamically include the actual TypeScript types
+ */
+export async function GET() {
+  try {
+    // Path to the agent-definition.ts file
+    const filePath = join(
+      process.cwd(),
+      '../common/src/templates/initial-agents-dir/types/agent-definition.ts'
+    )
+    
+    // Read the file content
+    const fileContent = await readFile(filePath, 'utf-8')
+    
+    return new NextResponse(fileContent, {
+      headers: {
+        'Content-Type': 'text/plain; charset=utf-8',
+        // Cache for 5 minutes to improve performance while allowing updates
+        'Cache-Control': 'public, max-age=300, stale-while-revalidate=60',
+      },
+    })
+  } catch (error) {
+    console.error('Error reading agent-definition.ts:', error)
+    
+    return NextResponse.json(
+      {
+        error: 'Failed to load agent definition file',
+        details: error instanceof Error ? error.message : 'Unknown error',
+      },
+      { status: 500 }
+    )
+  }
+}

web/src/app/api/docs/agent-definition/route.ts

@@ -0,0 +1,63 @@
+'use client'
+
+import { useState, useEffect } from 'react'
+import { CodeDemo } from './code-demo'
+
+/**
+ * Component that displays the actual TypeScript content from agent-definition.ts
+ * This loads the file content via API to ensure docs stay in sync with the actual types
+ */
+export function AgentDefinitionDisplay() {
+  const [fileContent, setFileContent] = useState<string>('')
+  const [isLoading, setIsLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    const loadFileContent = async () => {
+      try {
+        const response = await fetch('/api/docs/agent-definition')
+        if (!response.ok) {
+          throw new Error(`Failed to load file: ${response.statusText}`)
+        }
+        const content = await response.text()
+        setFileContent(content)
+      } catch (err) {
+        console.error('Error loading agent definition:', err)
+        setError(
+          err instanceof Error ? err.message : 'Failed to load file content'
+        )
+      } finally {
+        setIsLoading(false)
+      }
+    }
+
+    loadFileContent()
+  }, [])
+
+  if (isLoading) {
+    return (
+      <div className="rounded-lg border bg-muted/30 px-4 py-8 text-center text-muted-foreground">
+        Loading agent definition types...
+      </div>
+    )
+  }
+
+  if (error) {
+    return (
+      <div className="rounded-lg border bg-red-50 px-4 py-4 text-red-700">
+        <p className="font-medium">Error loading agent definition:</p>
+        <p className="text-sm mt-1">{error}</p>
+        <p className="text-xs mt-2 text-red-600">
+          The file should be located at:
+          common/src/templates/initial-agents-dir/types/agent-definition.ts
+        </p>
+      </div>
+    )
+  }
+
+  return (
+    <div className="space-y-2">
+      <CodeDemo language="typescript">{fileContent}</CodeDemo>
+    </div>
+  )
+}

web/src/components/docs/mdx/agent-definition-display.tsx

@@ -6,6 +6,7 @@ import React, { useState, useEffect } from 'react'
 import { CodeDemo } from './code-demo'
 import { MarkdownTable } from './markdown-table'
 import { AgentTemplateSchemaDisplay, SchemaDisplay } from './schema-display'
+import { AgentDefinitionDisplay } from './agent-definition-display'
 
 import type {
   HTMLAttributes,
@@ -288,6 +289,7 @@ const components = {
   MarkdownTable,
   SchemaDisplay,
   AgentTemplateSchemaDisplay,
+  AgentDefinitionDisplay,
 }
 
 export function Mdx({ code }: MdxProps) {

web/src/components/docs/mdx/mdx-components.tsx

@@ -7,27 +7,9 @@ order: 4
 
 # Agent Reference
 
-Complete reference for all agent configuration fields and tools.
+Complete reference for all agent definition fields:
 
-## Key Terms
-
-**Agent Template:** JSON file defining agent behavior
-
-**Spawnable Agents:** Sub-agents this agent can create
-
-**Tool Names:** Capabilities (read files, run commands, etc.)
-
-**Output Mode:** Response format (last message, report, all messages)
-
-**Prompt Schema:** Input validation rules
-
-## Agent Configuration
-
-When creating agent templates, you define all aspects of the agent from scratch.
-
-### Agent Schema
-
-<AgentTemplateSchemaDisplay />
+<AgentDefinitionDisplay />
 
 ### Core Configuration
 
@@ -177,10 +159,12 @@ Other agents this agent can spawn. Use the fully qualified agent ID from the age
 > **⚠️ Important:** When referencing built-in agents, you **must** specify both publisher and version (e.g., `codebuff/reviewer@0.0.1`). Omit publisher/version only for local agents defined in your `.agents/` directory.
 
 **Referencing Agents:**
+
 - Published/built-in agents: `"codebuff/file-picker@0.0.1"` (publisher and version required!)
 - Local agents: `"my-custom-agent"` (just the agent ID)
 
 **Available Built-in Agents:**
+
 - `codebuff/base` - Main coding assistant
 - `codebuff/reviewer` - Code review agent
 - `codebuff/thinker` - Deep thinking agent
@@ -231,25 +215,24 @@ Prompt inserted at each agent step. Powerful for changing behavior but usually n
 **🚀 This is what makes Codebuff agents truly powerful!** Unlike traditional prompt-based agents, `handleSteps` lets you write actual code to control agent behavior.
 
 Programmatically control the agent's execution using a TypeScript generator function. This enables:
+
 - **Dynamic decision making** based on tool results
 - **Complex orchestration** between multiple tools and agents
 - **Conditional branching** based on file contents or agent responses
 - **Iterative refinement** until desired results are achieved
 - **State management** across multiple steps
 
-
 **What You Can Yield:**
 
 <MarkdownTable>
-| Yield Value | What It Does |
-|------------|-------------|
-| Tool call object | Execute a specific tool and get its result |
-| 'STEP' | Run agent's LLM for one generation step |
-| 'STEP_ALL' | Let agent run until completion |
-| return | End the agent's turn immediately |
+  | Yield Value | What It Does | |------------|-------------| | Tool call object
+  | Execute a specific tool and get its result | | 'STEP' | Run agent's LLM for
+  one generation step | | 'STEP_ALL' | Let agent run until completion | | return
+  | End the agent's turn immediately |
 </MarkdownTable>
 
 **Tool Call Pattern:**
+
 ```typescript
 const { toolResult, toolError } = yield {
   toolName: 'read_files',
@@ -259,6 +242,7 @@ const { toolResult, toolError } = yield {
 ```
 
 **Example:**
+
 ```typescript
 handleSteps: function* ({ agentState, prompt, params }) {
   // First, read some files
@@ -304,6 +288,7 @@ JSON Schema definitions for validating prompt and params when spawning the agent
 ```
 
 **Real-World Example:**
+
 ```typescript
   // 1. Dynamically find relevant files
   const { toolResult: searchResults } = yield {