mini-coder 0.5.7 → 0.5.9

package/README.md

@@ -39,10 +39,12 @@ $ mc
 
 ## Tools
 
-Two built-in tools, plus a read-only image tool:
+Four built-in tools, plus a read-only image tool:
 
 - **`shell`** — runs commands in the user's shell. Returns stdout, stderr, and exit code. Large output is truncated to protect model context.
 - **`edit`** — exact-text replacement in a single file. Fails deterministically if the target is missing or ambiguous. Creates new files when old text is empty.
+- **`todoWrite`** — creates or updates the session todo list incrementally and returns the full current snapshot.
+- **`todoRead`** — returns the full current session todo list snapshot.
 - **`readImage`** — reads PNG, JPEG, GIF, and WebP files as model input. Only registered when the active model supports images.
 
 Plugins can add more tools, but the core stays intentionally small.
@@ -68,6 +70,7 @@ Plugins can add more tools, but the core stays intentionally small.
 | `/undo`      | Remove the last conversational turn without touching filesystem changes.                               |
 | `/reasoning` | Show or hide model thinking. The setting is saved and restored on launch.                              |
 | `/verbose`   | Expand shell output plus edit previews and edit errors in the conversation log.                        |
+| `/todo`      | Show the current session todo list in the conversation log as a UI-only checklist block.               |
 | `/login`     | Sign in with a supported OAuth provider.                                                               |
 | `/logout`    | Remove saved OAuth credentials for a logged-in provider.                                               |
 | `/effort`    | Choose low, medium, high, or xhigh reasoning effort.                                                   |
@@ -100,7 +103,7 @@ $ printf '%s\n' 'fix the failing tests' | mc
 - Starts when `-p/--prompt` is provided or when stdin or stdout is not a TTY.
 - If stdout is redirected but stdin is still interactive, pass `-p`; headless mode will not fall back to an interactive prompt.
 - Uses the same parser as the TUI for plain text, `/skill:name`, and standalone image paths.
-- Writes raw NDJSON events to stdout for text deltas, tool activity, final messages, and `done` / `error` / `aborted` outcomes.
+- With `--json`, writes NDJSON events for completed assistant/tool-result messages plus `done` / `error` / `aborted` outcomes; streaming deltas are omitted.
 - Headless runs still persist like normal sessions and show up in `/session` history for that working directory.
 - Interactive slash commands such as `/model`, `/session`, and `/help` are not available in headless mode.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mini-coder",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "A small, fast CLI coding agent",
   "module": "src/index.ts",
   "type": "module",

package/src/agent.ts

@@ -22,7 +22,7 @@ import type {
 } from "@mariozechner/pi-ai";
 import { streamSimple } from "@mariozechner/pi-ai";
 import { appendMessage } from "./session.ts";
-import type { ToolExecResult } from "./tools.ts";
+import { getTodoItems, type ToolExecResult } from "./tools.ts";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -605,28 +605,111 @@ function appendToolResultMessage(
   onEvent?.({ type: "tool_result", message: toolResultMessage });
 }
 
-function finalizeStoppedAssistantMessage(
-  db: Database,
-  sessionId: string,
-  messages: Message[],
+function getIncompleteTodos(messages: readonly Message[]) {
+  return getTodoItems(messages).filter((todo) => todo.status !== "completed");
+}
+
+function getTodoReminderSignature(
+  todos: ReturnType<typeof getIncompleteTodos>,
+): string {
+  return JSON.stringify(
+    [...todos].sort((left, right) => {
+      const contentOrder = left.content.localeCompare(right.content);
+      if (contentOrder !== 0) {
+        return contentOrder;
+      }
+      return left.status.localeCompare(right.status);
+    }),
+  );
+}
+
+function createTodoReminderMessage(
+  messages: readonly Message[],
+  remindedTodoSignatures: Set<string>,
+): UserMessage | null {
+  const incompleteTodos = getIncompleteTodos(messages);
+  if (incompleteTodos.length === 0) {
+    return null;
+  }
+
+  const signature = getTodoReminderSignature(incompleteTodos);
+  if (remindedTodoSignatures.has(signature)) {
+    return null;
+  }
+  remindedTodoSignatures.add(signature);
+
+  const lines = [
+    "You have pending todo items that must be completed before finishing the task:",
+    "",
+    ...incompleteTodos.map((todo) => {
+      const status = todo.status === "in_progress" ? "IN_PROGRESS" : "PENDING";
+      return `- [${status}] ${todo.content}`;
+    }),
+    "",
+    "Please complete all pending items before finishing.",
+  ];
+
+  return {
+    role: "user",
+    content: lines.join("\n"),
+    timestamp: Date.now(),
+  };
+}
+
+interface StoppedAssistantResolution {
+  /** Next turn number when a queued steering message was consumed. */
+  nextTurn: number | null;
+  /** Ephemeral context messages to include on the next model request. */
+  pendingContextMessages: Message[];
+  /** Final loop result when the turn should stop immediately. */
+  finalResult: AgentLoopResult | null;
+}
+
+function resolveStoppedAssistantMessage(
   assistantMessage: AssistantMessage,
   stopReason: "stop" | "length",
-  takeQueuedUserMessage: RunAgentOpts["takeQueuedUserMessage"],
-  onEvent: RunAgentOpts["onEvent"],
-): AgentLoopResult | number {
+  opts: Pick<
+    RunAgentOpts,
+    "db" | "sessionId" | "messages" | "takeQueuedUserMessage" | "onEvent"
+  >,
+  remindedTodoSignatures: Set<string>,
+): StoppedAssistantResolution {
   const queuedTurn = consumeQueuedUserMessage(
-    db,
-    sessionId,
-    messages,
-    takeQueuedUserMessage,
-    onEvent,
+    opts.db,
+    opts.sessionId,
+    opts.messages,
+    opts.takeQueuedUserMessage,
+    opts.onEvent,
   );
   if (queuedTurn !== null) {
-    return queuedTurn;
+    return {
+      nextTurn: queuedTurn,
+      pendingContextMessages: [],
+      finalResult: null,
+    };
   }
 
-  onEvent?.({ type: "done", message: assistantMessage });
-  return { messages, stopReason };
+  const todoReminder = createTodoReminderMessage(
+    opts.messages,
+    remindedTodoSignatures,
+  );
+  if (todoReminder) {
+    return {
+      nextTurn: null,
+      pendingContextMessages: [todoReminder],
+      finalResult: null,
+    };
+  }
+
+  opts.onEvent?.({ type: "done", message: assistantMessage });
+  return {
+    nextTurn: null,
+    pendingContextMessages: [],
+    finalResult: {
+      messages: opts.messages,
+      stopReason,
+    },
+  };
 }
 
 async function executeAssistantToolCalls(
@@ -671,6 +754,95 @@ async function executeAssistantToolCalls(
   return null;
 }
 
+interface AgentIterationOutcome {
+  /** Final loop result when the run should stop immediately. */
+  finalResult: AgentLoopResult | null;
+  /** Next turn number when a queued steering message starts a new turn. */
+  nextTurn: number;
+  /** Ephemeral context messages for the next model request. */
+  pendingContextMessages: Message[];
+}
+
+async function resolveAgentIteration(
+  assistantMessage: AssistantMessage,
+  currentTurn: number,
+  remindedTodoSignatures: Set<string>,
+  opts: Pick<
+    RunAgentOpts,
+    | "db"
+    | "sessionId"
+    | "messages"
+    | "toolHandlers"
+    | "cwd"
+    | "signal"
+    | "onEvent"
+    | "model"
+    | "takeQueuedUserMessage"
+  >,
+): Promise<AgentIterationOutcome> {
+  const stopResult = resolveLoopStopReason(
+    assistantMessage,
+    opts.messages,
+    opts.onEvent,
+  );
+  if (stopResult) {
+    return {
+      finalResult: stopResult,
+      nextTurn: currentTurn,
+      pendingContextMessages: [],
+    };
+  }
+
+  if (
+    assistantMessage.stopReason === "stop" ||
+    assistantMessage.stopReason === "length"
+  ) {
+    const stopResolution = resolveStoppedAssistantMessage(
+      assistantMessage,
+      assistantMessage.stopReason,
+      {
+        db: opts.db,
+        sessionId: opts.sessionId,
+        messages: opts.messages,
+        takeQueuedUserMessage: opts.takeQueuedUserMessage,
+        onEvent: opts.onEvent,
+      },
+      remindedTodoSignatures,
+    );
+    return {
+      finalResult: stopResolution.finalResult,
+      nextTurn: stopResolution.nextTurn ?? currentTurn,
+      pendingContextMessages: stopResolution.pendingContextMessages,
+    };
+  }
+
+  const toolStopResult = await executeAssistantToolCalls(
+    assistantMessage,
+    opts,
+    currentTurn,
+  );
+  if (toolStopResult) {
+    return {
+      finalResult: toolStopResult,
+      nextTurn: currentTurn,
+      pendingContextMessages: [],
+    };
+  }
+
+  const queuedTurn = consumeQueuedUserMessage(
+    opts.db,
+    opts.sessionId,
+    opts.messages,
+    opts.takeQueuedUserMessage,
+    opts.onEvent,
+  );
+  return {
+    finalResult: null,
+    nextTurn: queuedTurn ?? currentTurn,
+    pendingContextMessages: [],
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Agent loop
 // ---------------------------------------------------------------------------
@@ -702,9 +874,18 @@ export async function runAgentLoop(
     takeQueuedUserMessage,
   } = opts;
   let currentTurn = turn;
+  let pendingContextMessages: Message[] = [];
+  const remindedTodoSignatures = new Set<string>();
 
   while (true) {
-    const assistantMessage = await streamAssistantMessage(opts);
+    const assistantMessage = await streamAssistantMessage({
+      ...opts,
+      messages:
+        pendingContextMessages.length > 0
+          ? [...messages, ...pendingContextMessages]
+          : messages,
+    });
+    pendingContextMessages = [];
     appendAssistantMessage(
       db,
       sessionId,
@@ -714,37 +895,10 @@ export async function runAgentLoop(
       onEvent,
     );
 
-    const stopResult = resolveLoopStopReason(
-      assistantMessage,
-      messages,
-      onEvent,
-    );
-    if (stopResult) {
-      return stopResult;
-    }
-
-    if (
-      assistantMessage.stopReason === "stop" ||
-      assistantMessage.stopReason === "length"
-    ) {
-      const finalResult = finalizeStoppedAssistantMessage(
-        db,
-        sessionId,
-        messages,
-        assistantMessage,
-        assistantMessage.stopReason,
-        takeQueuedUserMessage,
-        onEvent,
-      );
-      if (typeof finalResult === "number") {
-        currentTurn = finalResult;
-        continue;
-      }
-      return finalResult;
-    }
-
-    const toolStopResult = await executeAssistantToolCalls(
+    const iterationOutcome = await resolveAgentIteration(
       assistantMessage,
+      currentTurn,
+      remindedTodoSignatures,
       {
         db,
         sessionId,
@@ -754,22 +908,14 @@ export async function runAgentLoop(
         signal,
         onEvent,
         model,
+        takeQueuedUserMessage,
       },
-      currentTurn,
     );
-    if (toolStopResult) {
-      return toolStopResult;
+    if (iterationOutcome.finalResult) {
+      return iterationOutcome.finalResult;
     }
 
-    const queuedTurn = consumeQueuedUserMessage(
-      db,
-      sessionId,
-      messages,
-      takeQueuedUserMessage,
-      onEvent,
-    );
-    if (queuedTurn !== null) {
-      currentTurn = queuedTurn;
-    }
+    currentTurn = iterationOutcome.nextTurn;
+    pendingContextMessages = iterationOutcome.pendingContextMessages;
   }
 }

package/src/cli.ts

@@ -12,6 +12,8 @@
 export interface CliOptions {
   /** One-shot prompt text, or `null` when not provided. */
   prompt: string | null;
+  /** Whether to stream headless output as NDJSON instead of final text. */
+  json: boolean;
 }
 
 /** TTY availability for stdin/stdout. */
@@ -29,7 +31,8 @@ export interface TtyState {
 /**
  * Parse supported CLI arguments.
  *
- * Currently supports only `-p, --prompt <text>` for headless one-shot mode.
+ * Supports `-p, --prompt <text>` for headless one-shot mode and `--json`
+ * to stream NDJSON events instead of the default final-text output.
  * Unknown flags and positional arguments fail eagerly.
  *
  * @param argv - Process arguments excluding the Bun executable and script path.
@@ -37,6 +40,7 @@ export interface TtyState {
  */
 export function parseCliArgs(argv: readonly string[]): CliOptions {
   let prompt: string | null = null;
+  let json = false;
 
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
@@ -59,6 +63,11 @@ export function parseCliArgs(argv: readonly string[]): CliOptions {
       continue;
     }
 
+    if (arg === "--json") {
+      json = true;
+      continue;
+    }
+
     if (arg.startsWith("-")) {
       throw new Error(`Unknown argument: ${arg}`);
     }
@@ -66,7 +75,7 @@ export function parseCliArgs(argv: readonly string[]): CliOptions {
     throw new Error(`Unexpected positional argument: ${arg}`);
   }
 
-  return { prompt };
+  return { prompt, json };
 }
 
 // ---------------------------------------------------------------------------

package/src/headless.ts

@@ -4,6 +4,8 @@
  * @module
  */
 
+import type { AssistantMessage, UserMessage } from "@mariozechner/pi-ai";
+import type { AgentEvent } from "./agent.ts";
 import type { AppState } from "./index.ts";
 import {
   resolveRawInput,
@@ -15,18 +17,37 @@ import {
 // Types
 // ---------------------------------------------------------------------------
 
-/** Options for a headless one-shot run. */
+type HeadlessStopReason = "stop" | "length" | "error" | "aborted";
+
+/** Options for a headless NDJSON run. */
 export interface HeadlessRunOptions {
-  /** Optional line writer for NDJSON event output. */
+  /** Optional line writer for completed NDJSON event output. */
   writeLine?: (line: string) => void;
 }
 
+/** Options for a headless final-text run. */
+export interface HeadlessTextRunOptions {
+  /** Optional writer for the final assistant text output. */
+  writeText?: (text: string) => void;
+}
+
+interface HeadlessOutputController {
+  /** Write text to stdout with broken-pipe handling. */
+  write(text: string): void;
+  /** Attach SIGINT/stdout error handlers for the active run. */
+  attach(): void;
+  /** Remove SIGINT/stdout error handlers after the run. */
+  detach(): void;
+  /** Resolve the final stop reason, converting broken pipes into quiet shutdowns. */
+  finalize(stopReason: HeadlessStopReason): HeadlessStopReason;
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
-function defaultWriteLine(line: string): void {
-  process.stdout.write(`${line}\n`);
+function defaultWrite(text: string): void {
+  process.stdout.write(text);
 }
 
 function isBrokenPipeError(error: unknown): boolean {
@@ -52,23 +73,10 @@ function buildCommandError(command: string): Error {
   );
 }
 
-/**
- * Run a single headless prompt to completion and stream NDJSON events.
- *
- * The raw input is parsed with the same rules as interactive input. Slash
- * commands are rejected in headless mode. Assistant/tool events are written as
- * one JSON object per line.
- *
- * @param state - Mutable application state for the run.
- * @param rawInput - Exact raw prompt text supplied by the user.
- * @param options - Optional event-output overrides.
- * @returns The terminal stop reason for the agent loop.
- */
-export async function runHeadlessPrompt(
+function resolveHeadlessContent(
   state: AppState,
   rawInput: string,
-  options?: HeadlessRunOptions,
-): Promise<"stop" | "length" | "error" | "aborted"> {
+): UserMessage["content"] {
   const resolved = resolveRawInput(rawInput, state);
   switch (resolved.type) {
     case "empty":
@@ -78,11 +86,52 @@ export async function runHeadlessPrompt(
     case "command":
       throw buildCommandError(resolved.command);
     case "message":
-      break;
+      return resolved.content;
+  }
+}
+
+function extractAssistantText(message: AssistantMessage | null): string {
+  if (!message) {
+    return "";
   }
 
+  return message.content
+    .filter(
+      (
+        block,
+      ): block is Extract<
+        AssistantMessage["content"][number],
+        { type: "text" }
+      > => {
+        return block.type === "text";
+      },
+    )
+    .map((block) => block.text)
+    .join("");
+}
+
+function shouldWriteHeadlessJsonEvent(event: AgentEvent): boolean {
+  switch (event.type) {
+    case "user_message":
+    case "assistant_message":
+    case "tool_result":
+    case "done":
+    case "error":
+    case "aborted":
+      return true;
+    default:
+      return false;
+  }
+}
+
+function createHeadlessOutputController(
+  state: AppState,
+  writeImpl: (text: string) => void,
+): HeadlessOutputController {
   let brokenPipe = false;
   let outputError: unknown = null;
+  const sigintHandler = createSigintHandler(state);
+
   const stopForBrokenPipe = (): void => {
     if (brokenPipe) {
       return;
@@ -90,51 +139,140 @@ export async function runHeadlessPrompt(
     brokenPipe = true;
     state.abortController?.abort();
   };
-  const writeLineImpl = options?.writeLine ?? defaultWriteLine;
-  const writeLine = (line: string): void => {
-    if (brokenPipe) {
+
+  const stdoutErrorHandler = (error: unknown): void => {
+    if (isBrokenPipeError(error)) {
+      stopForBrokenPipe();
       return;
     }
 
-    try {
-      writeLineImpl(line);
-    } catch (error) {
-      if (!isBrokenPipeError(error)) {
-        throw error;
+    outputError = error;
+    state.abortController?.abort();
+  };
+
+  return {
+    write(text) {
+      if (brokenPipe) {
+        return;
       }
-      stopForBrokenPipe();
-    }
+
+      try {
+        writeImpl(text);
+      } catch (error) {
+        if (!isBrokenPipeError(error)) {
+          throw error;
+        }
+        stopForBrokenPipe();
+      }
+    },
+    attach() {
+      process.stdout.on("error", stdoutErrorHandler);
+      process.on("SIGINT", sigintHandler);
+    },
+    detach() {
+      process.stdout.off("error", stdoutErrorHandler);
+      process.off("SIGINT", sigintHandler);
+    },
+    finalize(stopReason) {
+      if (outputError) {
+        throw outputError;
+      }
+      return brokenPipe ? "stop" : stopReason;
+    },
   };
+}
+
+/**
+ * Run a single headless prompt to completion and stream completed NDJSON events.
+ *
+ * The raw input is parsed with the same rules as interactive input. Slash
+ * commands are rejected in headless mode. Persisted messages and terminal
+ * events are written as one JSON object per line; streaming delta/progress
+ * events are omitted.
+ *
+ * @param state - Mutable application state for the run.
+ * @param rawInput - Exact raw prompt text supplied by the user.
+ * @param options - Optional event-output overrides.
+ * @returns The terminal stop reason for the agent loop.
+ */
+export async function runHeadlessPrompt(
+  state: AppState,
+  rawInput: string,
+  options?: HeadlessRunOptions,
+): Promise<HeadlessStopReason> {
+  const content = resolveHeadlessContent(state, rawInput);
+  const output = createHeadlessOutputController(
+    state,
+    options?.writeLine ?? ((line) => defaultWrite(`${line}\n`)),
+  );
   const hooks: SubmitTurnHooks = {
     onEvent: (event) => {
-      writeLine(JSON.stringify(event));
+      if (!shouldWriteHeadlessJsonEvent(event)) {
+        return;
+      }
+      output.write(JSON.stringify(event));
     },
   };
-  const sigintHandler = createSigintHandler(state);
-  const stdoutErrorHandler = (error: unknown): void => {
-    if (isBrokenPipeError(error)) {
-      stopForBrokenPipe();
-      return;
-    }
-    outputError = error;
-    state.abortController?.abort();
+
+  output.attach();
+  try {
+    const stopReason = await submitResolvedInput(
+      rawInput,
+      content,
+      state,
+      hooks,
+    );
+    return output.finalize(stopReason);
+  } finally {
+    output.detach();
+  }
+}
+
+/**
+ * Run a single headless prompt to completion and write only the final assistant text.
+ *
+ * The raw input is parsed with the same rules as interactive input. Slash
+ * commands are rejected in headless mode. Only the final persisted assistant
+ * message's text content is written to stdout.
+ *
+ * @param state - Mutable application state for the run.
+ * @param rawInput - Exact raw prompt text supplied by the user.
+ * @param options - Optional final-text output overrides.
+ * @returns The terminal stop reason for the agent loop.
+ */
+export async function runHeadlessPromptText(
+  state: AppState,
+  rawInput: string,
+  options?: HeadlessTextRunOptions,
+): Promise<HeadlessStopReason> {
+  const content = resolveHeadlessContent(state, rawInput);
+  const output = createHeadlessOutputController(
+    state,
+    options?.writeText ?? defaultWrite,
+  );
+  let finalAssistantMessage: AssistantMessage | null = null;
+  const hooks: SubmitTurnHooks = {
+    onEvent: (event) => {
+      if (event.type === "assistant_message") {
+        finalAssistantMessage = event.message;
+      }
+    },
   };
 
-  process.stdout.on("error", stdoutErrorHandler);
-  process.on("SIGINT", sigintHandler);
+  output.attach();
   try {
     const stopReason = await submitResolvedInput(
       rawInput,
-      resolved.content,
+      content,
       state,
       hooks,
     );
-    if (outputError) {
-      throw outputError;
+    const finalText = extractAssistantText(finalAssistantMessage);
+    if (finalText.length > 0) {
+      output.write(finalText);
     }
-    return brokenPipe ? "stop" : stopReason;
+    return output.finalize(stopReason);
   } finally {
-    process.stdout.off("error", stdoutErrorHandler);
-    process.off("SIGINT", sigintHandler);
+    output.detach();
   }
 }