Generate tools.d.ts! Create the file when using agent builder

Author: jahooma

.agents/agent-config.d.ts

@@ -12,6 +12,11 @@
  *   }
  */
 
+import type * as Tools from './tools'
+export type { Tools }
+
+type ToolName = Tools.ToolName
+
 // ============================================================================
 // Core Agent Configuration Types
 // ============================================================================
@@ -181,9 +186,9 @@ export interface AgentStepContext {
 /**
  * Tool call object for handleSteps generator
  */
-export interface ToolCall {
-  toolName: ToolName
-  args?: Record<string, any>
+export interface ToolCall<T extends ToolName = ToolName> {
+  toolName: T
+  args?: Tools.GetToolParams<T>
 }
 
 /**
@@ -249,16 +254,11 @@ export type PlanningTools =
 export type OutputTools = 'set_output' | 'end_turn'
 
 /**
- * All available tools that agents can use
+ * Common tool combinations for convenience
  */
-export type ToolName =
-  | FileTools
-  | CodeAnalysisTools
-  | TerminalTools
-  | WebTools
-  | AgentTools
-  | PlanningTools
-  | OutputTools
+export type FileEditingTools = FileTools | 'end_turn'
+export type ResearchTools = WebTools | 'write_file' | 'end_turn'
+export type CodeAnalysisToolSet = FileTools | CodeAnalysisTools | 'end_turn'
 
 // ============================================================================
 // Available Models (see: https://openrouter.ai/models)
@@ -299,14 +299,3 @@ export type SubagentName =
   | 'thinker'
   | 'reviewer'
   | (string & {})
-
-// ============================================================================
-// Utility Types
-// ============================================================================
-
-/**
- * Common tool combinations for convenience
- */
-export type FileEditingTools = FileTools | 'end_turn'
-export type ResearchTools = WebTools | 'write_file' | 'end_turn'
-export type CodeAnalysisToolSet = FileTools | CodeAnalysisTools | 'end_turn'

.agents/tools.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Add a new message to the conversation history. To be used for complex requests that can't be solved in a single step, as you may forget what happened!
+ */
+export interface AddMessageParams {
+  "role": "user" | "assistant"
+  "content": string
+}
+
+/**
+ * Add a new subgoal for tracking progress. To be used for complex requests that can't be solved in a single step, as you may forget what happened!
+ */
+export interface AddSubgoalParams {
+  // A unique identifier for the subgoal. Try to choose the next sequential integer that is not already in use.
+  "id": string
+  // The objective of the subgoal, concisely and clearly stated.
+  "objective": string
+  // The status of the subgoal.
+  "status": "NOT_STARTED" | "IN_PROGRESS" | "COMPLETE" | "ABORTED"
+  // A plan for the subgoal.
+  "plan"?: string
+  // A log message for the subgoal progress.
+  "log"?: string
+}
+
+/**
+ * Parameters for browser_logs tool
+ */
+export interface BrowserLogsParams {
+  // The type of browser action to perform (e.g., "navigate").
+  "type": string
+  // The URL to navigate to.
+  "url": string
+  // When to consider navigation successful. Defaults to 'load'.
+  "waitUntil"?: "load" | "domcontentloaded" | "networkidle0"
+}
+
+/**
+ * Search for string patterns in the project's files. This tool uses ripgrep (rg), a fast line-oriented search tool. Use this tool only when read_files is not sufficient to find the files you need.
+ */
+export interface CodeSearchParams {
+  // The pattern to search for.
+  "pattern": string
+  // Optional ripgrep flags to customize the search (e.g., "-i" for case-insensitive, "-t ts" for TypeScript files only, "-A 3" for 3 lines after match, "-B 2" for 2 lines before match, "--type-not test" to exclude test files).
+  "flags"?: string
+  // Optional working directory to search within, relative to the project root. Defaults to searching the entire project.
+  "cwd"?: string
+}
+
+/**
+ * Generate a detailed markdown plan for complex tasks.
+ */
+export interface CreatePlanParams {
+  // The path including the filename of a markdown file that will be overwritten with the plan.
+  "path": string
+  // A detailed plan to solve the user's request.
+  "plan": string
+}
+
+/**
+ * End your turn, regardless of any new tool results that might be coming. This will allow the user to type another prompt.
+ */
+export interface EndTurnParams {
+
+}
+
+/**
+ * Find several files related to a brief natural language description of the files or the name of a function or class you are looking for.
+ */
+export interface FindFilesParams {
+  // A brief natural language description of the files or the name of a function or class you are looking for. It's also helpful to mention a directory or two to look within.
+  "prompt": string
+}
+
+/**
+ * Fetch up-to-date documentation for libraries and frameworks using Context7 API.
+ */
+export interface ReadDocsParams {
+  // The exact library or framework name (e.g., "Next.js", "MongoDB", "React"). Use the official name as it appears in documentation, not a search query.
+  "libraryTitle": string
+  // Optional specific topic to focus on (e.g., "routing", "hooks", "authentication")
+  "topic"?: string
+  // Optional maximum number of tokens to return. Defaults to 10000. Values less than 10000 are automatically increased to 10000.
+  "max_tokens"?: number
+}
+
+/**
+ * Read the multiple files from disk and return their contents. Use this tool to read as many files as would be helpful to answer the user's request.
+ */
+export interface ReadFilesParams {
+  // List of file paths to read.
+  "paths": string[]
+}
+
+/**
+ * Parameters for run_file_change_hooks tool
+ */
+export interface RunFileChangeHooksParams {
+  // List of file paths that were changed and should trigger file change hooks
+  "files": string[]
+}
+
+/**
+ * Execute a CLI command from the **project root** (different from the user's cwd).
+ */
+export interface RunTerminalCommandParams {
+  // CLI command valid for user's OS.
+  "command": string
+  // Either SYNC (waits, returns output) or BACKGROUND (runs in background). Default SYNC
+  "process_type": "SYNC" | "BACKGROUND"
+  // The working directory to run the command in. Default is the project root.
+  "cwd"?: string
+  // Set to -1 for no timeout. Does not apply for BACKGROUND commands. Default 30
+  "timeout_seconds": number
+}
+
+/**
+ * Send a message to another agent (parent or child) for communication and data exchange.
+ */
+export interface SendAgentMessageParams {
+  // ID of the target agent to send message to. Use "PARENT_ID" to send to parent agent.
+  "target_agent_id": string
+  // Message prompt to send to the target agent
+  "prompt": string
+  // Optional parameters object to send with the message
+  "params"?: Record<string, any>
+}
+
+/**
+ * Set the conversation history to the provided messages.
+ */
+export interface SetMessagesParams {
+  "messages": {
+  "role": "user" | "assistant"
+  "content": string
+}[]
+}
+
+/**
+ * JSON object to set as the agent output. This completely replaces any previous output. If the agent was spawned, this value will be passed back to its parent. If the agent has an outputSchema defined, the output will be validated against it.
+ */
+export interface SetOutputParams {
+
+}
+
+/**
+ * Spawn multiple agents and send a prompt to each of them.
+ */
+export interface SpawnAgentsParams {
+  "agents": {
+  // Agent to spawn
+  "agent_type": string
+  // Prompt to send to the agent
+  "prompt"?: string
+  // Parameters object for the agent (if any)
+  "params"?: Record<string, any>
+}[]
+}
+
+/**
+ * Parameters for spawn_agents_async tool
+ */
+export interface SpawnAgentsAsyncParams {
+  "agents": {
+  // Agent to spawn
+  "agent_type": string
+  // Prompt to send to the agent
+  "prompt"?: string
+  // Parameters object for the agent (if any)
+  "params"?: Record<string, any>
+}[]
+}
+
+/**
+ * Replace strings in a file with new strings.
+ */
+export interface StrReplaceParams {
+  // The path to the file to edit.
+  "path": string
+  // Array of replacements to make.
+  "replacements": {
+  // The string to replace. This must be an *exact match* of the string you want to replace, including whitespace and punctuation.
+  "old": string
+  // The string to replace the corresponding old string with. Can be empty to delete.
+  "new": string
+}[]
+}
+
+/**
+ * Deeply consider complex tasks by brainstorming approaches and tradeoffs step-by-step.
+ */
+export interface ThinkDeeplyParams {
+  // Detailed step-by-step analysis. Initially keep each step concise (max ~5-7 words per step).
+  "thought": string
+}
+
+/**
+ * Update a subgoal in the context given the id, and optionally the status or plan, or a new log to append. Feel free to update any combination of the status, plan, or log in one invocation.
+ */
+export interface UpdateSubgoalParams {
+  // The id of the subgoal to update.
+  "id": string
+  // Change the status of the subgoal.
+  "status"?: "NOT_STARTED" | "IN_PROGRESS" | "COMPLETE" | "ABORTED"
+  // Change the plan for the subgoal.
+  "plan"?: string
+  // Add a log message to the subgoal. This will create a new log entry and append it to the existing logs. Use this to record your progress and any new information you learned as you go.
+  "log"?: string
+}
+
+/**
+ * Search the web for current information using Linkup API.
+ */
+export interface WebSearchParams {
+  // The search query to find relevant web content
+  "query": string
+  // Search depth - 'standard' for quick results, 'deep' for more comprehensive search. Default is 'standard'.
+  "depth": "standard" | "deep"
+}
+
+/**
+ * Create or edit a file with the given content.
+ */
+export interface WriteFileParams {
+  // Path to the file relative to the **project root**
+  "path": string
+  // What the change is intended to do in only one sentence.
+  "instructions": string
+  // Edit snippet to apply to the file.
+  "content": string
+}
+
+/**
+ * Union type of all available tool names
+ */
+export type ToolName = 'add_message' | 'add_subgoal' | 'browser_logs' | 'code_search' | 'create_plan' | 'end_turn' | 'find_files' | 'read_docs' | 'read_files' | 'run_file_change_hooks' | 'run_terminal_command' | 'send_agent_message' | 'set_messages' | 'set_output' | 'spawn_agents' | 'spawn_agents_async' | 'str_replace' | 'think_deeply' | 'update_subgoal' | 'web_search' | 'write_file'
+
+/**
+ * Map of tool names to their parameter types
+ */
+export interface ToolParamsMap {
+  'add_message': AddMessageParams
+  'add_subgoal': AddSubgoalParams
+  'browser_logs': BrowserLogsParams
+  'code_search': CodeSearchParams
+  'create_plan': CreatePlanParams
+  'end_turn': EndTurnParams
+  'find_files': FindFilesParams
+  'read_docs': ReadDocsParams
+  'read_files': ReadFilesParams
+  'run_file_change_hooks': RunFileChangeHooksParams
+  'run_terminal_command': RunTerminalCommandParams
+  'send_agent_message': SendAgentMessageParams
+  'set_messages': SetMessagesParams
+  'set_output': SetOutputParams
+  'spawn_agents': SpawnAgentsParams
+  'spawn_agents_async': SpawnAgentsAsyncParams
+  'str_replace': StrReplaceParams
+  'think_deeply': ThinkDeeplyParams
+  'update_subgoal': UpdateSubgoalParams
+  'web_search': WebSearchParams
+  'write_file': WriteFileParams
+}
+
+/**
+ * Get parameters type for a specific tool
+ */
+export type GetToolParams<T extends ToolName> = ToolParamsMap[T]

backend/src/templates/agents/agent-builder.ts

@@ -11,6 +11,7 @@ import {
   AGENT_CONFIG_FILE,
 } from '@codebuff/common/constants'
 import { AgentTemplateTypes } from '@codebuff/common/types/session-state'
+import { compileToolDefinitions } from '@codebuff/common/tools/compile-tool-definitions'
 import z from 'zod/v4'
 
 const TEMPLATE_RELATIVE_PATH =
@@ -22,6 +23,11 @@ import(TEMPLATE_RELATIVE_PATH)
 const TEMPLATE_PATH = path.join(__dirname, TEMPLATE_RELATIVE_PATH)
 const DEFAULT_MODEL = openrouterModels.openrouter_claude_sonnet_4
 const TEMPLATE_TYPES_PATH = path.join(AGENT_TEMPLATES_DIR, AGENT_CONFIG_FILE)
+const TOOL_DEFINITIONS_FILE = 'tools.d.ts'
+const TOOL_DEFINITIONS_PATH = path.join(
+  AGENT_TEMPLATES_DIR,
+  TOOL_DEFINITIONS_FILE
+)
 
 export const agentBuilder = (model: Model): Omit<AgentTemplate, 'id'> => {
   // Read the AGENT_CONFIG_FILE content dynamically
@@ -169,7 +175,18 @@ IMPORTANT: Always end your response with the end_turn tool when you have complet
         },
       }
 
-      // Step 3: Add user message with requirements for agent creation or editing
+      // Step 3: Write the tool definitions file
+      const toolDefinitionsContent = compileToolDefinitions()
+      yield {
+        toolName: 'write_file',
+        args: {
+          path: TOOL_DEFINITIONS_PATH,
+          instructions: 'Create tools type file',
+          content: toolDefinitionsContent,
+        },
+      }
+
+      // Step 4: Add user message with requirements for agent creation or editing
       const isEditMode = params?.editMode === true
 
       if (isEditMode) {

codebuff.json

@@ -59,6 +59,11 @@
       "name": "prettier-format",
       "command": "git diff --name-only --diff-filter=ACMR | grep -E '\\.(ts|tsx|json|md)$' | xargs -r npx prettier --write",
       "filePattern": "**/*.{ts,tsx,json,md}"
+    },
+    {
+      "name": "regenerate-tool-definitions",
+      "command": "bun run generate-tool-definitions",
+      "filePattern": "common/src/tools/{params/tool/*.ts,list.ts}"
     }
   ],
   "maxAgentSteps": 20