New write_todos tool!

Author: jahooma

.agents/types/tools.ts

@@ -20,6 +20,7 @@ export type ToolName =
   | 'think_deeply'
   | 'web_search'
   | 'write_file'
+  | 'write_todos'
 
 /**
  * Map of tool names to their parameter types
@@ -43,6 +44,7 @@ export interface ToolParamsMap {
   think_deeply: ThinkDeeplyParams
   web_search: WebSearchParams
   write_file: WriteFileParams
+  write_todos: WriteTodosParams
 }
 
 /**
@@ -59,7 +61,7 @@ export interface AddMessageParams {
 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 -t js" for TypeScript and JavaScript files only, "-A 3" for 3 lines after match, "-B 2" for 2 lines before match, "--type-not py" to exclude Python files). */
+  /** Optional ripgrep flags to customize the search (e.g., "-i" for case-insensitive, "-g *.ts -g *.js" for TypeScript and JavaScript files only, "-g !*.test.ts" to exclude Typescript test files,  "-A 3" for 3 lines after match, "-B 2" for 2 lines before match, --no-ignore to include files in ignored by .gitignore). */
   flags?: string
   /** Optional working directory to search within, relative to the project root. Defaults to searching the entire project. */
   cwd?: string
@@ -221,6 +223,19 @@ export interface WriteFileParams {
   content: string
 }
 
+/**
+ * Write a todo list to track tasks. Use this frequently to maintain a step-by-step plan.
+ */
+export interface WriteTodosParams {
+  /** List of todos with their completion status */
+  todos: {
+    /** Description of the task */
+    task: string
+    /** Whether the task is completed */
+    completed: boolean
+  }[]
+}
+
 /**
  * Get parameters type for a specific tool
  */

common/src/templates/initial-agents-dir/types/tools.ts

@@ -20,6 +20,7 @@ export type ToolName =
   | 'think_deeply'
   | 'web_search'
   | 'write_file'
+  | 'write_todos'
 
 /**
  * Map of tool names to their parameter types
@@ -43,6 +44,7 @@ export interface ToolParamsMap {
   think_deeply: ThinkDeeplyParams
   web_search: WebSearchParams
   write_file: WriteFileParams
+  write_todos: WriteTodosParams
 }
 
 /**
@@ -59,7 +61,7 @@ export interface AddMessageParams {
 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 -t js" for TypeScript and JavaScript files only, "-A 3" for 3 lines after match, "-B 2" for 2 lines before match, "--type-not py" to exclude Python files). */
+  /** Optional ripgrep flags to customize the search (e.g., "-i" for case-insensitive, "-g *.ts -g *.js" for TypeScript and JavaScript files only, "-g !*.test.ts" to exclude Typescript test files,  "-A 3" for 3 lines after match, "-B 2" for 2 lines before match, --no-ignore to include files in ignored by .gitignore). */
   flags?: string
   /** Optional working directory to search within, relative to the project root. Defaults to searching the entire project. */
   cwd?: string
@@ -221,6 +223,19 @@ export interface WriteFileParams {
   content: string
 }
 
+/**
+ * Write a todo list to track tasks. Use this frequently to maintain a step-by-step plan.
+ */
+export interface WriteTodosParams {
+  /** List of todos with their completion status */
+  todos: {
+    /** Description of the task */
+    task: string
+    /** Whether the task is completed */
+    completed: boolean
+  }[]
+}
+
 /**
  * Get parameters type for a specific tool
  */

common/src/tools/constants.ts

@@ -41,6 +41,7 @@ export const toolNames = [
   'update_subgoal',
   'web_search',
   'write_file',
+  'write_todos',
 ] as const
 
 export const publishedTools = [
@@ -62,6 +63,7 @@ export const publishedTools = [
   'think_deeply',
   'web_search',
   'write_file',
+  'write_todos',
   // 'spawn_agent_inline',
 ] as const
 

common/src/tools/list.ts

@@ -24,6 +24,7 @@ import { thinkDeeplyParams } from './params/tool/think-deeply'
 import { updateSubgoalParams } from './params/tool/update-subgoal'
 import { webSearchParams } from './params/tool/web-search'
 import { writeFileParams } from './params/tool/write-file'
+import { writeTodosParams } from './params/tool/write-todos'
 
 import type {
   $ToolParams,
@@ -61,6 +62,7 @@ export const $toolParams = {
   update_subgoal: updateSubgoalParams,
   web_search: webSearchParams,
   write_file: writeFileParams,
+  write_todos: writeTodosParams,
 } satisfies {
   [K in ToolName]: $ToolParams<K>
 }

common/src/tools/params/tool/write-todos.ts

@@ -0,0 +1,34 @@
+import z from 'zod/v4'
+
+import type { $ToolParams } from '../../constants'
+
+const toolName = 'write_todos'
+const endsAgentStep = false
+export const writeTodosParams = {
+  toolName,
+  endsAgentStep,
+  parameters: z
+    .object({
+      todos: z
+        .array(
+          z.object({
+            task: z.string().describe('Description of the task'),
+            completed: z.boolean().describe('Whether the task is completed'),
+          }),
+        )
+        .describe(
+          'List of todos with their completion status. Try to order the todos the same way you will complete them. Do not mark todos as completed if you have not completed them yet!',
+        ),
+    })
+    .describe(
+      'Write a todo list to track tasks. Use this frequently to maintain a step-by-step plan.',
+    ),
+  outputs: z.tuple([
+    z.object({
+      type: z.literal('json'),
+      value: z.object({
+        todos: z.array(z.object({ task: z.string(), completed: z.boolean() })),
+      }),
+    }),
+  ]),
+} satisfies $ToolParams

npm-app/src/utils/tool-renderers.ts

@@ -347,4 +347,27 @@ export const toolRenderers: Record<ToolName, ToolCallRenderer> = {
   lookup_agent_info: {
     ...defaultToolCallRenderer,
   },
+  write_todos: {
+    ...defaultToolCallRenderer,
+    onParamChunk: (content, paramName, toolName) => {
+      // Don't render chunks for todos array, wait for the full list
+      return null
+    },
+    onParamEnd: (paramName, toolName, content) => {
+      if (paramName !== 'todos') {
+        return null
+      }
+      let todos: Array<{ task: string; completed: boolean }> = []
+      try {
+        todos = JSON.parse(content)
+      } catch (e) {
+        return null
+      }
+      // Format as checkbox list
+      const formattedTodos = todos
+        .map((todo) => `${todo.completed ? '[x]' : '[]'} ${todo.task}`)
+        .join('\n')
+      return gray(formattedTodos)
+    },
+  },
 }

packages/agent-runtime/src/tools/definitions/list.ts

@@ -23,6 +23,7 @@ import { thinkDeeplyTool } from './tool/think-deeply'
 import { updateSubgoalTool } from './tool/update-subgoal'
 import { webSearchTool } from './tool/web-search'
 import { writeFileTool } from './tool/write-file'
+import { writeTodosTool } from './tool/write-todos'
 
 import type { ToolDescription } from './tool-def-type'
 import type { ToolName } from '@codebuff/common/tools/constants'
@@ -52,6 +53,7 @@ const toolDescriptions = {
   update_subgoal: updateSubgoalTool,
   web_search: webSearchTool,
   write_file: writeFileTool,
+  write_todos: writeTodosTool,
 } satisfies {
   [K in ToolName]: ToolDescription<K>
 }

packages/agent-runtime/src/tools/definitions/tool/write-todos.ts

@@ -0,0 +1,28 @@
+import { getToolCallString } from '@codebuff/common/tools/utils'
+
+import type { ToolDescription } from '../tool-def-type'
+
+const toolName = 'write_todos'
+export const writeTodosTool = {
+  toolName,
+  description: `
+Use this tool to track your objectives through an ordered step-by-step plan. Call this tool after you have gathered context on the user's request to plan out the implementation steps for the user's request.
+
+After completing each todo step, call this tool again to update the list and mark that task as completed. Note that each time you call this tool, rewrite ALL todos with their current status.
+
+Use this tool frequently as you work through tasks to update the list of todos with their current status. Doing this is extremely useful because it helps you stay on track and complete all the requirements of the user's request. It also helps inform the user of your plans and the current progress, which they want to know at all times.
+
+Example:
+${getToolCallString(toolName, {
+  todos: [
+    { task: 'Create new implementation in foo.ts', completed: true },
+    { task: 'Update bar.ts to use the new implementation', completed: false },
+    { task: 'Write tests for the new implementation', completed: false },
+    {
+      task: 'Run the tests to verify the new implementation',
+      completed: false,
+    },
+  ],
+})}
+`.trim(),
+} satisfies ToolDescription

packages/agent-runtime/src/tools/handlers/list.ts

@@ -21,6 +21,7 @@ import { handleThinkDeeply } from './tool/think-deeply'
 import { handleUpdateSubgoal } from './tool/update-subgoal'
 import { handleWebSearch } from './tool/web-search'
 import { handleWriteFile } from './tool/write-file'
+import { handleWriteTodos } from './tool/write-todos'
 
 import type { CodebuffToolHandlerFunction } from './handler-function-type'
 import type { ToolName } from '@codebuff/common/tools/constants'
@@ -58,6 +59,7 @@ export const codebuffToolHandlers = {
   update_subgoal: handleUpdateSubgoal,
   web_search: handleWebSearch,
   write_file: handleWriteFile,
+  write_todos: handleWriteTodos,
 } satisfies {
   [K in ToolName]: CodebuffToolHandlerFunction<K>
 }

packages/agent-runtime/src/tools/handlers/tool/write-todos.ts

@@ -0,0 +1,24 @@
+import type { CodebuffToolHandlerFunction } from '../handler-function-type'
+
+type ToolName = 'write_todos'
+export const handleWriteTodos: CodebuffToolHandlerFunction<ToolName> = (
+  params,
+) => {
+  const { previousToolCallFinished, toolCall } = params
+  const { todos } = toolCall.input
+
+  return {
+    result: (async () => {
+      await previousToolCallFinished
+      return [
+        {
+          type: 'json',
+          value: {
+            todos,
+          },
+        },
+      ]
+    })(),
+    state: {},
+  }
+}