/** * Todo Tool - Demonstrates state management via session entries * * This tool stores state in tool result details (not external files), * which allows proper branching - when you branch, the todo state * is automatically correct for that point in history. * * The onSession callback reconstructs state by scanning past tool results. */ import { Type } from "@sinclair/typebox"; import { StringEnum } from "@mariozechner/pi-ai"; import { Text } from "@mariozechner/pi-tui"; import type { CustomAgentTool, CustomToolFactory, ToolSessionEvent } from "@mariozechner/pi-coding-agent"; interface Todo { id: number; text: string; done: boolean; } // State stored in tool result details interface TodoDetails { action: "list" | "add" | "toggle" | "clear"; todos: Todo[]; nextId: number; error?: string; } // Define schema separately for proper type inference const TodoParams = Type.Object({ action: StringEnum(["list", "add", "toggle", "clear"] as const), text: Type.Optional(Type.String({ description: "Todo text (for add)" })), id: Type.Optional(Type.Number({ description: "Todo ID (for toggle)" })), }); const factory: CustomToolFactory = (_pi) => { // In-memory state (reconstructed from session on load) let todos: Todo[] = []; let nextId = 1; /** * Reconstruct state from session entries. * Scans tool results for this tool and applies them in order. */ const reconstructState = (event: ToolSessionEvent) => { todos = []; nextId = 1; for (const entry of event.entries) { if (entry.type !== "message") continue; const msg = entry.message; // Tool results have role "toolResult" if (msg.role !== "toolResult") continue; if (msg.toolName !== "todo") continue; const details = msg.details as TodoDetails | undefined; if (details) { todos = details.todos; nextId = details.nextId; } } }; const tool: CustomAgentTool = { name: "todo", label: "Todo", description: "Manage a todo list. Actions: list, add (text), toggle (id), clear", parameters: TodoParams, // Called on session start/switch/branch/clear onSession: reconstructState, async execute(_toolCallId, params) { switch (params.action) { case "list": return { content: [{ type: "text", text: todos.length ? todos.map((t) => `[${t.done ? "x" : " "}] #${t.id}: ${t.text}`).join("\n") : "No todos" }], details: { action: "list", todos: [...todos], nextId }, }; case "add": if (!params.text) { return { content: [{ type: "text", text: "Error: text required for add" }], details: { action: "add", todos: [...todos], nextId, error: "text required" }, }; } const newTodo: Todo = { id: nextId++, text: params.text, done: false }; todos.push(newTodo); return { content: [{ type: "text", text: `Added todo #${newTodo.id}: ${newTodo.text}` }], details: { action: "add", todos: [...todos], nextId }, }; case "toggle": if (params.id === undefined) { return { content: [{ type: "text", text: "Error: id required for toggle" }], details: { action: "toggle", todos: [...todos], nextId, error: "id required" }, }; } const todo = todos.find((t) => t.id === params.id); if (!todo) { return { content: [{ type: "text", text: `Todo #${params.id} not found` }], details: { action: "toggle", todos: [...todos], nextId, error: `#${params.id} not found` }, }; } todo.done = !todo.done; return { content: [{ type: "text", text: `Todo #${todo.id} ${todo.done ? "completed" : "uncompleted"}` }], details: { action: "toggle", todos: [...todos], nextId }, }; case "clear": const count = todos.length; todos = []; nextId = 1; return { content: [{ type: "text", text: `Cleared ${count} todos` }], details: { action: "clear", todos: [], nextId: 1 }, }; default: return { content: [{ type: "text", text: `Unknown action: ${params.action}` }], details: { action: "list", todos: [...todos], nextId, error: `unknown action: ${params.action}` }, }; } }, renderCall(args, theme) { let text = theme.fg("toolTitle", theme.bold("todo ")) + theme.fg("muted", args.action); if (args.text) text += " " + theme.fg("dim", `"${args.text}"`); if (args.id !== undefined) text += " " + theme.fg("accent", `#${args.id}`); return new Text(text, 0, 0); }, renderResult(result, { expanded }, theme) { const { details } = result; if (!details) { const text = result.content[0]; return new Text(text?.type === "text" ? text.text : "", 0, 0); } // Error if (details.error) { return new Text(theme.fg("error", `Error: ${details.error}`), 0, 0); } const todoList = details.todos; switch (details.action) { case "list": if (todoList.length === 0) { return new Text(theme.fg("dim", "No todos"), 0, 0); } let listText = theme.fg("muted", `${todoList.length} todo(s):`); const display = expanded ? todoList : todoList.slice(0, 5); for (const t of display) { const check = t.done ? theme.fg("success", "✓") : theme.fg("dim", "○"); const itemText = t.done ? theme.fg("dim", t.text) : theme.fg("muted", t.text); listText += "\n" + check + " " + theme.fg("accent", `#${t.id}`) + " " + itemText; } if (!expanded && todoList.length > 5) { listText += "\n" + theme.fg("dim", `... ${todoList.length - 5} more`); } return new Text(listText, 0, 0); case "add": { const added = todoList[todoList.length - 1]; return new Text(theme.fg("success", "✓ Added ") + theme.fg("accent", `#${added.id}`) + " " + theme.fg("muted", added.text), 0, 0); } case "toggle": { const text = result.content[0]; const msg = text?.type === "text" ? text.text : ""; return new Text(theme.fg("success", "✓ ") + theme.fg("muted", msg), 0, 0); } case "clear": return new Text(theme.fg("success", "✓ ") + theme.fg("muted", "Cleared all todos"), 0, 0); } }, }; return tool; }; export default factory;