mini-coder 0.5.6 → 0.5.8

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";
@@ -490,9 +682,12 @@ interface ShellOpts {
   onUpdate?: ToolUpdateCallback;
 }
 
+type ShellProcess = ReturnType<typeof Bun.spawn>;
+
 const DEFAULT_MAX_LINES = 1000;
 const DEFAULT_MAX_BYTES = 50_000;
 const SHELL_UPDATE_INTERVAL_MS = 75;
+const SHELL_STREAM_DRAIN_TIMEOUT_MS = 25;
 
 /** Format combined stdout/stderr for display in tool results. */
 function formatShellOutput(stdout: string, stderr: string): string {
@@ -837,26 +1032,132 @@ function normalizeShellCommand(command: string): string {
   }
 }
 
-/** Read a spawned shell stream into a string, reporting progressive updates. */
-async function consumeShellStream(
+interface ShellStreamCapture {
+  done: Promise<void>;
+  getOutput: () => string;
+  isFinished: () => boolean;
+  close: () => Promise<void>;
+}
+
+function startShellStreamCapture(
   stream: ReadableStream<Uint8Array>,
   onChunk: (chunk: string) => void,
-): Promise<string> {
+): ShellStreamCapture {
   const reader = stream.getReader();
   const decoder = new TextDecoder();
   let output = "";
+  let closed = false;
+  let finished = false;
+
+  const done = (async (): Promise<void> => {
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          break;
+        }
+
+        const chunk = decoder.decode(value, { stream: true });
+        output += chunk;
+        onChunk(chunk);
+      }
+    } catch (error) {
+      if (!closed) {
+        throw error;
+      }
+    } finally {
+      const trailing = decoder.decode();
+      output += trailing;
+      onChunk(trailing);
+      finished = true;
+    }
+  })();
 
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) {
-      output += decoder.decode();
-      return output;
+  return {
+    done,
+    getOutput: () => output,
+    isFinished: () => finished,
+    close: async (): Promise<void> => {
+      if (!finished) {
+        closed = true;
+        try {
+          await reader.cancel();
+        } catch {
+          // Ignore cancellation errors while closing the pipe after exit/abort.
+        }
+      }
+      await done;
+    },
+  };
+}
+
+async function finalizeShellStreamCaptures(
+  captures: readonly ShellStreamCapture[],
+): Promise<void> {
+  const pending = captures
+    .filter((capture) => !capture.isFinished())
+    .map((capture) => capture.done);
+
+  if (pending.length > 0) {
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(resolve, SHELL_STREAM_DRAIN_TIMEOUT_MS);
+      void Promise.allSettled(pending).then(() => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
+  }
+
+  await Promise.all(captures.map((capture) => capture.close()));
+}
+
+function buildShellSpawnOptions(cwd: string): Parameters<typeof Bun.spawn>[1] {
+  return {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+    ...(process.platform === "win32" ? {} : { detached: true }),
+  };
+}
+
+function abortShellProcess(proc: ShellProcess): void {
+  if (proc.killed || proc.exitCode !== null) {
+    return;
+  }
+
+  if (process.platform !== "win32") {
+    try {
+      process.kill(-proc.pid, "SIGTERM");
+      return;
+    } catch {
+      // Fall through to a direct kill when the process group is unavailable.
     }
+  }
+
+  proc.kill("SIGTERM");
+}
+
+function registerShellAbort(
+  signal: AbortSignal | undefined,
+  proc: ShellProcess,
+): (() => void) | null {
+  if (!signal) {
+    return null;
+  }
+
+  const abortListener = (): void => {
+    abortShellProcess(proc);
+  };
 
-    const chunk = decoder.decode(value, { stream: true });
-    output += chunk;
-    onChunk(chunk);
+  if (signal.aborted) {
+    abortShellProcess(proc);
+    return null;
   }
+
+  signal.addEventListener("abort", abortListener, { once: true });
+  return () => {
+    signal.removeEventListener("abort", abortListener);
+  };
 }
 
 /**
@@ -880,22 +1181,13 @@ export async function executeShell(
   const maxLines = opts?.maxLines ?? DEFAULT_MAX_LINES;
   const maxBytes = opts?.maxBytes ?? DEFAULT_MAX_BYTES;
   let updateTimer: ReturnType<typeof setTimeout> | null = null;
+  let cleanupAbort: (() => void) | null = null;
+  let lastReportedOutput = "";
+  let lastReportAt = 0;
+  let stdoutCapture: ShellStreamCapture | null = null;
+  let stderrCapture: ShellStreamCapture | null = null;
 
   try {
-    const spawnOpts: Parameters<typeof Bun.spawn>[1] = {
-      cwd,
-      stdout: "pipe",
-      stderr: "pipe",
-    };
-    if (opts?.signal) spawnOpts.signal = opts.signal;
-    const command = normalizeShellCommand(args.command);
-    const proc = Bun.spawn([shell, "-c", command], spawnOpts);
-
-    let stdoutBuf = "";
-    let stderrBuf = "";
-    let lastReportedOutput = "";
-    let lastReportAt = 0;
-
     const clearPendingUpdate = (): void => {
       if (updateTimer) {
         clearTimeout(updateTimer);
@@ -903,9 +1195,14 @@ export async function executeShell(
       }
     };
 
-    const buildProgressOutput = (): string => {
+    const buildOutput = (trimEnd: boolean): string => {
+      const stdout = stdoutCapture?.getOutput() ?? "";
+      const stderr = stderrCapture?.getOutput() ?? "";
       return truncateOutput(
-        formatShellOutput(stdoutBuf, stderrBuf),
+        formatShellOutput(
+          trimEnd ? stdout.trimEnd() : stdout,
+          trimEnd ? stderr.trimEnd() : stderr,
+        ),
         maxLines,
         maxBytes,
       );
@@ -917,7 +1214,7 @@ export async function executeShell(
         return;
       }
 
-      const output = buildProgressOutput();
+      const output = buildOutput(false);
       if (!output || output === lastReportedOutput) {
         return;
       }
@@ -946,24 +1243,29 @@ export async function executeShell(
       }, SHELL_UPDATE_INTERVAL_MS - elapsed);
     };
 
-    const [stdout, stderr, exitCode] = await Promise.all([
-      consumeShellStream(proc.stdout as ReadableStream<Uint8Array>, (chunk) => {
-        stdoutBuf += chunk;
+    const command = normalizeShellCommand(args.command);
+    const proc = Bun.spawn([shell, "-c", command], buildShellSpawnOptions(cwd));
+    cleanupAbort = registerShellAbort(opts?.signal, proc);
+    stdoutCapture = startShellStreamCapture(
+      proc.stdout as ReadableStream<Uint8Array>,
+      () => {
         scheduleUpdate();
-      }),
-      consumeShellStream(proc.stderr as ReadableStream<Uint8Array>, (chunk) => {
-        stderrBuf += chunk;
+      },
+    );
+    stderrCapture = startShellStreamCapture(
+      proc.stderr as ReadableStream<Uint8Array>,
+      () => {
         scheduleUpdate();
-      }),
-      proc.exited,
-    ]);
+      },
+    );
 
+    const exitCode = await proc.exited;
+    cleanupAbort?.();
+    cleanupAbort = null;
+
+    await finalizeShellStreamCaptures([stdoutCapture, stderrCapture]);
     clearPendingUpdate();
-    const output = truncateOutput(
-      formatShellOutput(stdout.trimEnd(), stderr.trimEnd()),
-      maxLines,
-      maxBytes,
-    );
+    const output = buildOutput(true);
     if (opts?.onUpdate && output && output !== lastReportedOutput) {
       lastReportedOutput = output;
       opts.onUpdate(textResult(output, false));
@@ -973,6 +1275,14 @@ export async function executeShell(
     const body = output || "(no output)";
     return textResult(`Exit code: ${exitCode}\n${body}`, isError);
   } catch (err) {
+    cleanupAbort?.();
+    cleanupAbort = null;
+    const captures = [stdoutCapture, stderrCapture].filter(
+      (capture): capture is ShellStreamCapture => capture !== null,
+    );
+    if (captures.length > 0) {
+      await Promise.allSettled(captures.map((capture) => capture.close()));
+    }
     if (updateTimer) {
       clearTimeout(updateTimer);
       updateTimer = null;
@@ -1212,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",

package/src/ui/agent.ts

@@ -13,7 +13,11 @@ import type { AssistantMessage } from "@mariozechner/pi-ai";
 import type { AgentEvent } from "../agent.ts";
 import { getErrorMessage } from "../errors.ts";
 import type { AppState } from "../index.ts";
-import { resolveRawInput, submitResolvedInput } from "../submit.ts";
+import {
+  queueResolvedInput,
+  resolveRawInput,
+  submitResolvedInput,
+} from "../submit.ts";
 import type {
   PendingToolResult,
   StreamingConversationState,
@@ -103,7 +107,12 @@ export function createUiAgentController(
         break;
     }
 
-    if (!state.model || state.running) {
+    if (state.running) {
+      queueResolvedInput(rawInput, resolved.content, state);
+      return;
+    }
+
+    if (!state.model) {
       return;
     }
 
@@ -154,6 +163,11 @@ export function createUiAgentController(
         runtime.render();
         break;
 
+      case "user_message":
+        runtime.scrollConversationToBottom();
+        runtime.render();
+        break;
+
       case "assistant_message":
         streamingContent = [];
         runtime.render();