mini-coder 0.5.7 → 0.5.8

package/src/index.ts

@@ -25,9 +25,11 @@ import { getEnvApiKey, getModels, getProviders } from "@mariozechner/pi-ai";
 import { getOAuthApiKey, getOAuthProviders } from "@mariozechner/pi-ai/oauth";
 import type { ToolHandler } from "./agent.ts";
 import {
+  type CliOptions,
   parseCliArgs,
   resolveHeadlessPrompt,
   shouldUseHeadlessMode,
+  type TtyState,
 } from "./cli.ts";
 import { getErrorMessage } from "./errors.ts";
 import { type GitState, getGitState } from "./git.ts";
@@ -71,8 +73,12 @@ import {
   executeEdit,
   executeReadImage,
   executeShell,
+  executeTodoRead,
+  executeTodoWrite,
   readImageTool,
   shellTool,
+  todoReadTool,
+  todoWriteTool,
 } from "./tools.ts";
 import { resolveAppVersionLabel } from "./version.ts";
 
@@ -382,11 +388,28 @@ const BUILTIN_HANDLERS: Record<string, ToolHandler> = {
 function buildTools(
   model: Model<string>,
   plugins: LoadedPlugin[],
+  messages: AppState["messages"],
 ): { tools: Tool[]; toolHandlers: Map<string, ToolHandler> } {
-  const tools: Tool[] = [editTool, shellTool];
+  const tools: Tool[] = [editTool, shellTool, todoWriteTool, todoReadTool];
   const toolHandlers = new Map<string, ToolHandler>([
     [editTool.name, BUILTIN_HANDLERS.edit!],
     [shellTool.name, BUILTIN_HANDLERS.shell!],
+    [
+      todoWriteTool.name,
+      (args) =>
+        executeTodoWrite(
+          {
+            todos: Array.isArray(args.todos)
+              ? (args.todos as Array<{
+                  content: string;
+                  status: "pending" | "in_progress" | "completed" | "cancelled";
+                }>)
+              : [],
+          },
+          messages,
+        ),
+    ],
+    [todoReadTool.name, () => executeTodoRead(messages)],
   ]);
 
   // Conditionally register readImage for vision-capable models
@@ -542,8 +565,6 @@ export interface AppState {
   versionLabel: string;
   /** Current git state (null if not in a repo). */
   git: GitState | null;
-  /** Optional git state loader override used by tests. */
-  loadGitState?: (cwd: string) => Promise<GitState | null>;
   /** Available provider credentials (provider → API key). */
   providers: Map<string, string>;
   /** OAuth credentials on disk. */
@@ -671,8 +692,8 @@ function resolvePromptOs(): "linux" | "mac" | "docker" {
 /**
  * Build the system prompt for the current state.
  *
- * Separated from `init` because it's called on every turn (git state
- * may change between turns).
+ * Separated from `init` because turns still rebuild the assembled prompt
+ * from the session-stable prompt context plus the current runtime state.
  */
 export function buildPrompt(state: AppState): string {
   return buildSystemPrompt({
@@ -698,7 +719,7 @@ export function buildToolList(state: AppState): {
   toolHandlers: Map<string, ToolHandler>;
 } {
   if (!state.model) return { tools: [], toolHandlers: new Map() };
-  return buildTools(state.model, state.plugins);
+  return buildTools(state.model, state.plugins, state.messages);
 }
 
 /**
@@ -765,6 +786,47 @@ export {
   saveOAuthCredentials,
 };
 
+// ---------------------------------------------------------------------------
+// Headless CLI
+// ---------------------------------------------------------------------------
+
+type HeadlessCliStopReason = "stop" | "length" | "error" | "aborted";
+
+/**
+ * Run one headless CLI prompt using the output mode selected by the parsed CLI flags.
+ *
+ * Non-TTY detection only decides whether headless mode should run at all.
+ * Once headless mode is selected, `--json` is the only switch that chooses
+ * NDJSON streaming versus final-text output.
+ *
+ * @param state - Initialized application state for the run.
+ * @param cli - Parsed CLI options.
+ * @param tty - Current TTY availability.
+ * @param deps - Injected I/O and runner callbacks.
+ * @returns The terminal stop reason for the headless run.
+ */
+export async function runHeadlessCli(
+  state: AppState,
+  cli: CliOptions,
+  tty: TtyState,
+  deps: {
+    readStdin: () => Promise<string>;
+    runJson: (
+      state: AppState,
+      rawPrompt: string,
+    ) => Promise<HeadlessCliStopReason>;
+    runText: (
+      state: AppState,
+      rawPrompt: string,
+    ) => Promise<HeadlessCliStopReason>;
+  },
+): Promise<HeadlessCliStopReason> {
+  const rawPrompt = await resolveHeadlessPrompt(cli, tty, deps.readStdin);
+  return cli.json
+    ? deps.runJson(state, rawPrompt)
+    : deps.runText(state, rawPrompt);
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -787,11 +849,17 @@ export async function main(): Promise<void> {
 
   if (shouldUseHeadlessMode(cli, tty)) {
     try {
-      const rawPrompt = await resolveHeadlessPrompt(cli, tty, async () => {
-        return Bun.stdin.text();
+      const stopReason = await runHeadlessCli(state, cli, tty, {
+        readStdin: async () => Bun.stdin.text(),
+        runJson: async (headlessState, rawPrompt) => {
+          const { runHeadlessPrompt } = await import("./headless.ts");
+          return runHeadlessPrompt(headlessState, rawPrompt);
+        },
+        runText: async (headlessState, rawPrompt) => {
+          const { runHeadlessPromptText } = await import("./headless.ts");
+          return runHeadlessPromptText(headlessState, rawPrompt);
+        },
       });
-      const { runHeadlessPrompt } = await import("./headless.ts");
-      const stopReason = await runHeadlessPrompt(state, rawPrompt);
       if (stopReason === "aborted") {
         process.exitCode = 130;
       } else if (stopReason === "error") {

package/src/input.ts

@@ -24,6 +24,7 @@ export const COMMANDS = [
   "undo",
   "reasoning",
   "verbose",
+  "todo",
   "login",
   "logout",
   "help",

package/src/prompt.ts

@@ -252,11 +252,13 @@ function buildCorePrompt(opts: BuildSystemPromptOpts): string {
     "",
     "### Task management",
     "",
-    "- Use the /tmp or equivalent temp directory to make a To-do list for your task.",
-    "- This to-do list is **extremely** helpful for breaking down your task into smaller, less complex steps.",
-    "- Not using a to-do list may cause you to forget important steps, or lose focus on the user's request; that would be unacceptable.",
-    "- Keep the to-do list up-to-date above all, mark your completions as soon as you verify them.",
-    "- A to-do item is only complete if verification was successful and thorough.",
+    "- Use `todoWrite` proactively for multi-step or non-trivial tasks.",
+    "- Capture new requirements in the todo list as soon as you understand them.",
+    "- Use `todoRead` when you need to inspect the current list before updating it or when the user asks for the current plan/status.",
+    "- Keep the todo list up-to-date above all; mark tasks `in_progress` before starting them and `completed` as soon as verification succeeds.",
+    "- A todo item is only complete if the requested work is actually finished and verified to the degree the task requires.",
+    "- Use `cancelled` to remove tasks that are no longer relevant.",
+    "- Skip todo tools for single trivial tasks and purely conversational/informational requests.",
     '- You have the option to delegate tasks to copies of yourself with `mc -p "subtask prompt"` in the shell.',
     "- Delegate when you are orchestrating a large to-do/plan execution.",
     "",

package/src/session.ts

@@ -16,6 +16,7 @@ import type {
   ToolResultMessage,
   UserMessage,
 } from "@mariozechner/pi-ai";
+import type { TodoItem } from "./tools.ts";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -94,8 +95,8 @@ interface AppendPromptHistoryOpts {
   sessionId?: string;
 }
 
-/** A persisted UI-only message shown in the conversation log. */
-export interface UiMessage {
+/** A persisted UI-only info message shown in the conversation log. */
+export interface UiInfoMessage {
   /** Identifies this as an internal UI message. */
   role: "ui";
   /** UI message category for rendering and future behavior. */
@@ -106,6 +107,21 @@ export interface UiMessage {
   timestamp: number;
 }
 
+/** A persisted UI-only todo snapshot shown in the conversation log. */
+export interface UiTodoMessage {
+  /** Identifies this as an internal UI message. */
+  role: "ui";
+  /** UI message category for rendering and future behavior. */
+  kind: "todo";
+  /** Todo snapshot rendered in the conversation pane. */
+  todos: TodoItem[];
+  /** Unix timestamp in milliseconds. */
+  timestamp: number;
+}
+
+/** A persisted UI-only message shown in the conversation log. */
+export type UiMessage = UiInfoMessage | UiTodoMessage;
+
 /** Any message persisted in session history. */
 export type PersistedMessage = Message | UiMessage;
 
@@ -491,10 +507,27 @@ function isUiMessageRecord(value: unknown): value is UiMessage {
     return false;
   }
 
+  const timestamp = readFiniteNumber(record, "timestamp");
+  if (timestamp === null) {
+    return false;
+  }
+
+  if (record.kind === "info") {
+    return typeof record.content === "string";
+  }
+
   return (
-    record.kind === "info" &&
-    typeof record.content === "string" &&
-    readFiniteNumber(record, "timestamp") !== null
+    record.kind === "todo" &&
+    Array.isArray(record.todos) &&
+    record.todos.every(
+      (todo) =>
+        typeof todo === "object" &&
+        todo !== null &&
+        typeof (todo as { content?: unknown }).content === "string" &&
+        ((todo as { status?: unknown }).status === "pending" ||
+          (todo as { status?: unknown }).status === "in_progress" ||
+          (todo as { status?: unknown }).status === "completed"),
+    )
   );
 }
 
@@ -593,12 +626,12 @@ export function truncateSessions(
 // ---------------------------------------------------------------------------
 
 /**
- * Create a persisted UI message.
+ * Create a persisted UI info message.
  *
  * @param content - Display text shown in the conversation log.
- * @returns A new {@link UiMessage}.
+ * @returns A new {@link UiInfoMessage}.
  */
-export function createUiMessage(content: string): UiMessage {
+export function createUiMessage(content: string): UiInfoMessage {
   return {
     role: "ui",
     kind: "info",
@@ -607,6 +640,21 @@ export function createUiMessage(content: string): UiMessage {
   };
 }
 
+/**
+ * Create a persisted UI todo snapshot message.
+ *
+ * @param todos - Todo snapshot rendered in the conversation log.
+ * @returns A new {@link UiTodoMessage}.
+ */
+export function createUiTodoMessage(todos: readonly TodoItem[]): UiTodoMessage {
+  return {
+    role: "ui",
+    kind: "todo",
+    todos: todos.map((todo) => ({ ...todo })),
+    timestamp: Date.now(),
+  };
+}
+
 /**
  * Check whether a persisted message is a UI-only message.
  *

package/src/submit.ts

@@ -9,7 +9,6 @@ import type { UserMessage } from "@mariozechner/pi-ai";
 import type { AgentEvent } from "./agent.ts";
 import { runAgentLoop } from "./agent.ts";
 import { getErrorMessage } from "./errors.ts";
-import { getGitState } from "./git.ts";
 import {
   type AppState,
   buildPrompt,
@@ -328,7 +327,6 @@ export async function submitResolvedInput(
     content,
     timestamp: Date.now(),
   } satisfies UserMessage;
-  const loadGitState = state.loadGitState ?? getGitState;
 
   const turn = appendMessage(state.db, session.id, userMessage);
   state.messages.push(userMessage);
@@ -338,8 +336,6 @@ export async function submitResolvedInput(
   );
   hooks?.onUserMessage?.(state);
 
-  state.git = await loadGitState(state.cwd);
-
   const systemPrompt = buildPrompt(state);
   const { tools, toolHandlers } = buildToolList(state);
   const modelMessages = filterModelMessages(state.messages);
@@ -371,7 +367,6 @@ export async function submitResolvedInput(
       },
     });
     stopReason = result.stopReason;
-    state.git = await loadGitState(state.cwd);
     return result.stopReason;
   } finally {
     state.running = false;

package/src/tools.ts

@@ -1,5 +1,6 @@
 /**
- * Built-in tool implementations: `edit`, `shell`, and `readImage`.
+ * Built-in tool implementations: `edit`, `shell`, `todoWrite`, `todoRead`,
+ * and `readImage`.
  *
  * Each tool is exposed as a pure-ish execute function that takes typed
  * arguments and a working directory, returning a result object. The pi-ai
@@ -11,7 +12,13 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, extname, isAbsolute, join } from "node:path";
-import type { ImageContent, TextContent, Tool } from "@mariozechner/pi-ai";
+import type {
+  ImageContent,
+  Message,
+  TextContent,
+  Tool,
+  ToolResultMessage,
+} from "@mariozechner/pi-ai";
 import { Type } from "@mariozechner/pi-ai";
 import type { ToolUpdateCallback } from "./agent.ts";
 
@@ -37,6 +44,191 @@ function textResult(text: string, isError: boolean): ToolExecResult {
   return { content: [{ type: "text", text }], isError };
 }
 
+/** Persisted todo status values shown to the user and stored in snapshots. */
+export type TodoStatus = "pending" | "in_progress" | "completed";
+
+/** Todo status values accepted by `todoWrite`. */
+export type TodoWriteStatus = TodoStatus | "cancelled";
+
+/** A single persisted todo item. */
+export interface TodoItem {
+  /** Task description shown in the checklist. */
+  content: string;
+  /** Current persisted task status. */
+  status: TodoStatus;
+}
+
+interface TodoWriteInputItem {
+  /** Task description used as the matching key. */
+  content: string;
+  /** Requested next status for the task. */
+  status: TodoWriteStatus;
+}
+
+/** Arguments for the `todoWrite` tool. */
+export interface TodoWriteArgs {
+  /** Todo items to create, update, or remove. */
+  todos: TodoWriteInputItem[];
+}
+
+const MAX_TODO_CONTENT_LENGTH = 1_000;
+
+type TodoHistoryMessage = Message | { role: "ui" };
+
+function isTodoStatus(value: unknown): value is TodoStatus {
+  return (
+    value === "pending" || value === "in_progress" || value === "completed"
+  );
+}
+
+function isTodoWriteStatus(value: unknown): value is TodoWriteStatus {
+  return value === "cancelled" || isTodoStatus(value);
+}
+
+function cloneTodoItems(todos: readonly TodoItem[]): TodoItem[] {
+  return todos.map((todo) => ({ ...todo }));
+}
+
+function getToolResultText(content: ToolResultMessage["content"]): string {
+  return content
+    .filter((entry): entry is TextContent => entry.type === "text")
+    .map((entry) => entry.text)
+    .join("\n");
+}
+
+/** Serialize a full todo snapshot for storage in a tool result. */
+export function formatTodoSnapshot(todos: readonly TodoItem[]): string {
+  return JSON.stringify({ todos: cloneTodoItems(todos) }, null, 2);
+}
+
+/** Parse a serialized todo snapshot from tool-result text. */
+export function parseTodoSnapshot(text: string): TodoItem[] | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text) as unknown;
+  } catch {
+    return null;
+  }
+
+  if (
+    typeof parsed !== "object" ||
+    parsed === null ||
+    !Array.isArray((parsed as { todos?: unknown }).todos)
+  ) {
+    return null;
+  }
+
+  const todos = (parsed as { todos: unknown[] }).todos;
+  if (
+    !todos.every((todo) => {
+      return (
+        typeof todo === "object" &&
+        todo !== null &&
+        typeof (todo as { content?: unknown }).content === "string" &&
+        isTodoStatus((todo as { status?: unknown }).status)
+      );
+    })
+  ) {
+    return null;
+  }
+
+  return todos.map((todo) => ({
+    content: (todo as { content: string }).content,
+    status: (todo as { status: TodoStatus }).status,
+  }));
+}
+
+function getTodoSnapshotFromToolResult(
+  message: ToolResultMessage,
+): TodoItem[] | null {
+  if (message.isError) {
+    return null;
+  }
+  if (message.toolName !== "todoWrite" && message.toolName !== "todoRead") {
+    return null;
+  }
+  return parseTodoSnapshot(getToolResultText(message.content));
+}
+
+/** Return the current todo list derived from persisted message history. */
+export function getTodoItems(
+  messages: readonly TodoHistoryMessage[],
+): TodoItem[] {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (!message || message.role !== "toolResult") {
+      continue;
+    }
+
+    const snapshot = getTodoSnapshotFromToolResult(message);
+    if (snapshot) {
+      return snapshot;
+    }
+  }
+
+  return [];
+}
+
+function validateTodoContent(content: string): string | null {
+  if (content.trim().length === 0) {
+    return "Todo content cannot be empty";
+  }
+  if (content.length > MAX_TODO_CONTENT_LENGTH) {
+    return `Todo content exceeds maximum length of ${MAX_TODO_CONTENT_LENGTH} characters`;
+  }
+  return null;
+}
+
+/** Apply incremental todo changes and return the new full snapshot. */
+export function executeTodoWrite(
+  args: TodoWriteArgs,
+  messages: readonly TodoHistoryMessage[],
+): ToolExecResult {
+  const nextTodos = cloneTodoItems(getTodoItems(messages));
+
+  for (const todo of args.todos) {
+    const validationError = validateTodoContent(todo.content);
+    if (validationError) {
+      return textResult(validationError, true);
+    }
+    if (!isTodoWriteStatus(todo.status)) {
+      return textResult(`Invalid todo status: ${String(todo.status)}`, true);
+    }
+
+    if (todo.status === "cancelled") {
+      const index = nextTodos.findIndex(
+        (existingTodo) => existingTodo.content === todo.content,
+      );
+      if (index !== -1) {
+        nextTodos.splice(index, 1);
+      }
+      continue;
+    }
+
+    const existingTodo = nextTodos.find(
+      (candidate) => candidate.content === todo.content,
+    );
+    if (existingTodo) {
+      existingTodo.status = todo.status;
+      continue;
+    }
+
+    nextTodos.push({
+      content: todo.content,
+      status: todo.status,
+    });
+  }
+
+  return textResult(formatTodoSnapshot(nextTodos), false);
+}
+
+/** Return the current full todo snapshot without mutating it. */
+export function executeTodoRead(
+  messages: readonly TodoHistoryMessage[],
+): ToolExecResult {
+  return textResult(formatTodoSnapshot(getTodoItems(messages)), false);
+}
+
 function detectLineEnding(content: string): "\n" | "\r\n" | null {
   if (content.includes("\r\n")) {
     return "\r\n";
@@ -1330,6 +1522,53 @@ export const editTool: Tool = {
   }),
 };
 
+/** pi-ai tool definition for `todoWrite`. */
+export const todoWriteTool: Tool = {
+  name: "todoWrite",
+  description:
+    "Use this tool to create and manage a structured task list for your current coding session. " +
+    "This helps you track progress, organize complex tasks, and keep the user informed. " +
+    "Only send the items that changed; unchanged items stay as they are. " +
+    "Each item must include `content` and `status`, where `status` is one of `pending`, `in_progress`, `completed`, or `cancelled`. " +
+    "Use `cancelled` to remove an item from the list. " +
+    "Mark tasks `in_progress` before starting them and `completed` immediately after verification succeeds.",
+  parameters: Type.Object({
+    todos: Type.Array(
+      Type.Object({
+        content: Type.String({
+          description: "Task description used as the matching key",
+        }),
+        status: Type.Union(
+          [
+            Type.Literal("pending"),
+            Type.Literal("in_progress"),
+            Type.Literal("completed"),
+            Type.Literal("cancelled"),
+          ],
+          {
+            description:
+              "Task status. Use `cancelled` to remove the item entirely.",
+          },
+        ),
+      }),
+      {
+        description:
+          "List of todo items to create, update, or remove. Only send the items that changed.",
+      },
+    ),
+  }),
+};
+
+/** pi-ai tool definition for `todoRead`. */
+export const todoReadTool: Tool = {
+  name: "todoRead",
+  description:
+    "Retrieves the current todo list for this coding session. " +
+    "Use this tool before updating todos when you need to inspect the current list, or when the user asks for the current plan or progress. " +
+    "If no todos exist yet, it returns an empty list.",
+  parameters: Type.Object({}),
+};
+
 /** pi-ai tool definition for `shell`. */
 export const shellTool: Tool = {
   name: "shell",