langchain/dist/agents/middleware/todoListMiddleware.cjs

Typescript bindings for langchain

const require_middleware = require("../middleware.cjs");
require("../index.cjs");
let _langchain_core_messages = require("@langchain/core/messages");
let _langchain_core_tools = require("@langchain/core/tools");
let _langchain_langgraph = require("@langchain/langgraph");
let zod_v3 = require("zod/v3");
// src/agents/middleware/todoListMiddleware.ts
/**
* Description for the write_todos tool
* Ported exactly from Python WRITE_TODOS_DESCRIPTION
*/
const WRITE_TODOS_DESCRIPTION = `Use this tool to create and manage a structured task list for your current work session. This helps you track progress and organize complex tasks.

Only use this tool if you think it will be helpful in staying organized. If the user's request is trivial and takes less than 3 steps, it is better to NOT use this tool and just do the task directly.

## When to Use This Tool

Use this tool in these scenarios:

1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
3. User explicitly requests todo list - When the user directly asks you to use the todo list
4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
5. The plan may need future revisions or updates based on results from the first few steps

## How to Use This Tool

1. When you start working on a task - Mark it as in_progress BEFORE beginning work.
2. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation.
3. You can also update future tasks, such as deleting them if they are no longer necessary, or adding new tasks that are necessary. Don't change previously completed tasks.
4. You can make several updates to the todo list at once. For example, when you complete a task, you can mark the next task you need to start as in_progress.

## When NOT to Use This Tool

It is important to skip using this tool when:
1. There is only a single, straightforward task
2. The task is trivial and tracking it provides no benefit
3. The task can be completed in less than 3 trivial steps
4. The task is purely conversational or informational

## Task States and Management

1. **Task States**: Use these states to track progress:
    - pending: Task not yet started
    - in_progress: Currently working on (you can have multiple tasks in_progress at a time if they are not related to each other and can be run in parallel)
    - completed: Task finished successfully

2. **Task Management**:
    - Update task status in real-time as you work
    - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)
    - Complete current tasks before starting new ones
    - Remove tasks that are no longer relevant from the list entirely
    - IMPORTANT: When you write this todo list, you should mark your first task (or tasks) as in_progress immediately!.
    - IMPORTANT: Unless all tasks are completed, you should always have at least one task in_progress.

3. **Task Completion Requirements**:
    - ONLY mark a task as completed when you have FULLY accomplished it
    - If you encounter errors, blockers, or cannot finish, keep the task as in_progress
    - When blocked, create a new task describing what needs to be resolved
    - Never mark a task as completed if:
        - There are unresolved issues or errors
        - Work is partial or incomplete
        - You encountered blockers that prevent completion
        - You couldn't find necessary resources or dependencies
        - Quality standards haven't been met

4. **Task Breakdown**:
    - Create specific, actionable items
    - Break complex tasks into smaller, manageable steps
    - Use clear, descriptive task names

Being proactive with task management ensures you complete all requirements successfully
Remember: If you only need to make a few tool calls to complete a task, and it is clear what you need to do, it is better to just do the task directly and NOT call this tool at all.

## When You Finish

\`write_todos\` tracks your work; it does not deliver the answer. Whatever the user asked for — computations, summaries, comparisons, data — must appear as text content in a message after your final \`write_todos\` call. Marking the last todo complete is not itself an answer to the user.`;
const TODO_LIST_MIDDLEWARE_SYSTEM_PROMPT = `## \`write_todos\`

You have access to the \`write_todos\` tool to help you manage and plan complex objectives.
Use this tool for complex objectives to ensure that you are tracking each necessary step.
This tool is very helpful for planning complex objectives, and for breaking down these larger complex objectives into smaller steps.

It is critical that you mark todos as completed as soon as you are done with a step. Do not batch up multiple steps before marking them as completed.
For simple objectives that only require a few steps, it is better to just complete the objective directly and NOT use this tool.
Writing todos takes time and tokens, use it when it is helpful for managing complex many-step problems! But not for simple few-step requests.

## Important To-Do List Usage Notes to Remember

- The \`write_todos\` tool should never be called multiple times in parallel.
- Don't be afraid to revise the To-Do list as you go. New information may reveal new tasks that need to be done, or old tasks that are irrelevant.

## Finishing a task

When you finish all work, write your final answer in the message AFTER your last \`write_todos\` call — not in the same turn as that call. Start the final message with the substantive content the user asked for — the data, computation, summary, or analysis. The user wants the result, not confirmation that the work is done.`;
const TodoStatus = zod_v3.z.enum([
	"pending",
	"in_progress",
	"completed"
]).describe("Status of the todo");
const TodoSchema = zod_v3.z.object({
	content: zod_v3.z.string().describe("Content of the todo item"),
	status: TodoStatus
});
const stateSchema = zod_v3.z.object({ todos: zod_v3.z.array(TodoSchema).default([]) });
/**
* Creates a middleware that provides todo list management capabilities to agents.
*
* This middleware adds a `write_todos` tool that allows agents to create and manage
* structured task lists for complex multi-step operations. It's designed to help
* agents track progress, organize complex tasks, and provide users with visibility
* into task completion status.
*
* The middleware automatically injects system prompts that guide the agent on when
* and how to use the todo functionality effectively. It also enforces that the
* `write_todos` tool is called at most once per model turn, since the tool replaces
* the entire todo list and parallel calls would create ambiguity about precedence.
*
* @example
* ```typescript
* import { todoListMiddleware, createAgent } from 'langchain';
*
* const agent = createAgent({
*   model: "openai:gpt-4o",
*   middleware: [todoListMiddleware()],
* });
*
* // Agent now has access to write_todos tool and todo state tracking
* const result = await agent.invoke({
*   messages: [new HumanMessage("Help me refactor my codebase")]
* });
*
* console.log(result.todos); // Array of todo items with status tracking
* ```
*
* @returns A configured middleware instance that provides todo management capabilities
*
* @see {@link TodoMiddlewareState} for the state schema
* @see {@link writeTodos} for the tool implementation
*/
function todoListMiddleware(options) {
	/**
	* Write todos tool - manages todo list with Command return
	*/
	const writeTodos = (0, _langchain_core_tools.tool)(({ todos }, config) => {
		return new _langchain_langgraph.Command({ update: {
			todos,
			messages: [new _langchain_core_messages.ToolMessage({
				content: `Updated todo list to ${JSON.stringify(todos)}`,
				tool_call_id: config.toolCall?.id,
				name: "write_todos"
			})]
		} });
	}, {
		name: "write_todos",
		description: options?.toolDescription ?? WRITE_TODOS_DESCRIPTION,
		schema: zod_v3.z.object({ todos: zod_v3.z.array(TodoSchema).describe("List of todo items to update") })
	});
	return require_middleware.createMiddleware({
		name: "todoListMiddleware",
		stateSchema,
		tools: [writeTodos],
		wrapModelCall: (request, handler) => handler({
			...request,
			systemMessage: request.systemMessage.concat(`\n\n${options?.systemPrompt ?? "## `write_todos`\n\nYou have access to the `write_todos` tool to help you manage and plan complex objectives.\nUse this tool for complex objectives to ensure that you are tracking each necessary step.\nThis tool is very helpful for planning complex objectives, and for breaking down these larger complex objectives into smaller steps.\n\nIt is critical that you mark todos as completed as soon as you are done with a step. Do not batch up multiple steps before marking them as completed.\nFor simple objectives that only require a few steps, it is better to just complete the objective directly and NOT use this tool.\nWriting todos takes time and tokens, use it when it is helpful for managing complex many-step problems! But not for simple few-step requests.\n\n## Important To-Do List Usage Notes to Remember\n\n- The `write_todos` tool should never be called multiple times in parallel.\n- Don't be afraid to revise the To-Do list as you go. New information may reveal new tasks that need to be done, or old tasks that are irrelevant.\n\n## Finishing a task\n\nWhen you finish all work, write your final answer in the message AFTER your last `write_todos` call — not in the same turn as that call. Start the final message with the substantive content the user asked for — the data, computation, summary, or analysis. The user wants the result, not confirmation that the work is done."}`)
		}),
		afterModel: (state) => {
			/**
			* Check for parallel write_todos tool calls and return errors if detected.
			*
			* The todo list is designed to be updated at most once per model turn. Since
			* the `write_todos` tool replaces the entire todo list with each call, making
			* multiple parallel calls would create ambiguity about which update should take
			* precedence. This method prevents such conflicts by rejecting any response that
			* contains multiple write_todos tool calls.
			*/
			const messages = state.messages;
			if (!messages || messages.length === 0) return;
			/**
			* Find the last AI message
			*/
			const lastAiMsg = [...messages].reverse().find((msg) => _langchain_core_messages.AIMessage.isInstance(msg));
			if (!lastAiMsg || !lastAiMsg.tool_calls || lastAiMsg.tool_calls.length === 0) return;
			/**
			* Count write_todos tool calls
			*/
			const writeTodosCalls = lastAiMsg.tool_calls.filter((tc) => tc.name === writeTodos.name);
			if (writeTodosCalls.length > 1)
 /**
			* Keep the tool calls in the AI message but return error messages
			* This follows the same pattern as HumanInTheLoopMiddleware
			*/
			return { messages: writeTodosCalls.map((tc) => new _langchain_core_messages.ToolMessage({
				content: "Error: The `write_todos` tool should never be called multiple times in parallel. Please call it only once per model invocation to update the todo list.",
				tool_call_id: tc.id,
				name: "write_todos",
				status: "error"
			})) };
		}
	});
}
exports.TODO_LIST_MIDDLEWARE_SYSTEM_PROMPT = TODO_LIST_MIDDLEWARE_SYSTEM_PROMPT;
exports.todoListMiddleware = todoListMiddleware;

//# sourceMappingURL=todoListMiddleware.cjs.map