Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

feat(agent): show the todo checklist in the TUI and in the status row (#179)

Abdurrahman Fakhrul5fda2a01facf
diff --git a/docs/AGENT-CODING-PLAN.md b/docs/AGENT-CODING-PLAN.md
index f06614cc..e8e2f27e 100644
--- a/docs/AGENT-CODING-PLAN.md
+++ b/docs/AGENT-CODING-PLAN.md
@@ -63,7 +63,7 @@ renders that diff under the `fs_edit` row. See `docs/AGENT-EDIT-PREVIEW.md`.
| 4 | `todo_write` tool: session-scoped checklist the TUI renders | session store | keeps long tasks honest |
| 5 | Background subagent: `agent_subagent_start` + `agent_subagent_status` | existing subagent runner + `exec_job_*` lifecycle pattern | enables parallelism |
| 6 | TUI: render the `fs_edit` diff, and `dry_run` on `fs_edit` itself | returned tool result, no extra round trip | visibility |
-| 7 | TUI: render the `todo_write` list | session state on the status row | not started |
+| 7 | TUI: render the `todo_write` list, plus a status-row chip | the tool input and result, cached per session, cleared on /new and /resume | done |
## Non-negotiable constraints
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 3b0969f5..f7e41817 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -8,7 +8,8 @@ this is the *what*, and it is what Settings → Account → About shows as “Wh
**Added**
-- `agent` fs_edit reports the diff it applied and can preview without writing
+- `agent` show the todo checklist in the TUI and in the status row
+- `agent` fs_edit reports the diff it applied and can preview without writing (#178)
- `agent` a bounded pty_session tool, so an agent can drive an interactive process (#176)
- `agent` background subagents, so a parent can keep working in parallel (#175)
- `agent` surgical edit, content search, glob and a todo list (#173)
diff --git a/scripts/mso-agent-cmd-session.mjs b/scripts/mso-agent-cmd-session.mjs
index 76fce15f..dc712592 100644
--- a/scripts/mso-agent-cmd-session.mjs
+++ b/scripts/mso-agent-cmd-session.mjs
@@ -8,12 +8,32 @@ import {
} from "./mso-agent-session-ui.mjs";
import { api, state } from "./mso-agent-api.mjs";
import { C } from "./mso-agent-runtime.mjs";
+import { clearTodos, formatTodoBlock, latestTodos } from "./mso-agent-todos.mjs";
+
+export async function handleTodos(ctx, args = []) {
+ const { C: colors = C } = ctx;
+ const state = latestTodos();
+ if (!state || (!state.items?.length && !state.summary)) {
+ console.log("no todo list in this session yet: the agent writes one with todo_write");
+ return "handled";
+ }
+ const showAll = args.includes("--all");
+ const maxItems = showAll ? Number.POSITIVE_INFINITY : 12;
+ const block = formatTodoBlock(state, { colors, maxItems });
+ if (block) console.log(block);
+ else console.log("no todo list in this session yet: the agent writes one with todo_write");
+ return "handled";
+}
export async function handleSessionCommand(ctx, cmd, args) {
+ if (cmd === "/todos") {
+ return handleTodos(ctx, args);
+ }
const { rl, session, C: colors = C } = ctx;
switch (cmd) {
case "/new":
await startNewSession(rl, session, args.join(" "));
+ clearTodos();
session.state = await state();
return "refresh";
case "/restart":
@@ -23,6 +43,7 @@ export async function handleSessionCommand(ctx, cmd, args) {
case "/resume":
if (!args.length) await resumePicker(rl, session);
else await resumeInto(rl, session, args.join(" "));
+ clearTodos();
return "refresh";
case "/rename": {
const name = args.join(" ").trim();
@@ -71,6 +92,7 @@ export async function handleSessionCommand(ctx, cmd, args) {
return "handled";
}
case "/clear":
+ clearTodos();
Object.assign(session, {
history: [],
pendingSkill: null,
diff --git a/scripts/mso-agent-help.mjs b/scripts/mso-agent-help.mjs
index f014efa4..6057cb55 100644
--- a/scripts/mso-agent-help.mjs
+++ b/scripts/mso-agent-help.mjs
@@ -12,6 +12,7 @@ export const HELP_LINES = [
" /permission [mode] choose ask | auto-write | yolo",
" /context alias for /status",
" /diff [ref] [--full] show diff viewer panel for artifact write action",
+ " /todos [--all] show session checklist from todo_write",
" /compact force context compaction and archive history",
" /statusbar [on|off] toggle compact dynamic status line",
" /reasoning [on|off] toggle per-turn reasoning token metrics (/reasoning on|off)",
diff --git a/scripts/mso-agent-status.mjs b/scripts/mso-agent-status.mjs
index d8109a76..25406c08 100644
--- a/scripts/mso-agent-status.mjs
+++ b/scripts/mso-agent-status.mjs
@@ -2,6 +2,7 @@ import os from "node:os";
import path from "node:path";
import { projectHistoryForModel } from "./mso-agent-context.mjs";
import { addProviderUsage } from "../lib/ai/provider-usage.mjs";
+import { todoStatusChip } from "./mso-agent-todos.mjs";
function compactNumber(value) {
const n = Number(value || 0);
@@ -78,6 +79,7 @@ export function statusParts(session, cwd = process.cwd()) {
: ((usage.inputTokens ?? 0) > 0 || (usage.outputTokens ?? 0) > 0) ? `tokens ${compactNumber(usage.inputTokens)}in/${compactNumber(usage.outputTokens)}out` : null,
routing?.activeTools != null ? `route ${routing.routeIds?.join("+") || (routing.fallbackUsed ? "fallback" : "direct")} · tools ${routing.activeTools}/${routing.fullTools}` : null,
`turns ${turns}`,
+ todoStatusChip(),
elapsed > 0 ? `${(elapsed / 1000).toFixed(elapsed >= 10_000 ? 0 : 1)}s` : null,
`@${sessionName}`,
`session ${sessionTitle}`,
diff --git a/scripts/mso-agent-todos.mjs b/scripts/mso-agent-todos.mjs
new file mode 100644
index 00000000..1b11d85c
--- /dev/null
+++ b/scripts/mso-agent-todos.mjs
@@ -0,0 +1,190 @@
+import process from "node:process";
+import { fit } from "./mso-agent-ui.mjs";
+
+const VALID_STATUSES = new Set(["pending", "in_progress", "completed"]);
+
+let cachedTodos = null;
+
+/**
+ * Drop the cache. A new or resumed session must not inherit the previous checklist, because the
+ * status row would then describe work that belongs to a different session.
+ */
+export function clearTodos() {
+ cachedTodos = null;
+}
+
+export const resetTodosForTesting = clearTodos;
+
+/**
+ * Parse input.todos array and result summary string without throwing.
+ * Returns null when neither usable items nor a valid summary are present.
+ */
+export function parseTodoCall(input, result) {
+ let items = null;
+ if (input && typeof input === "object" && Array.isArray(input.todos)) {
+ const validItems = [];
+ for (const item of input.todos) {
+ if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+ if (typeof item.content !== "string") continue;
+ const content = item.content.trim();
+ if (!content || !VALID_STATUSES.has(item.status)) continue;
+
+ const cleanItem = {
+ content,
+ status: item.status,
+ };
+ if (typeof item.activeForm === "string" && item.activeForm.trim()) {
+ cleanItem.activeForm = item.activeForm.trim();
+ }
+ validItems.push(cleanItem);
+ }
+ if (validItems.length > 0) {
+ items = validItems;
+ }
+ }
+
+ let summary = null;
+ if (result != null) {
+ let parsed = result;
+ if (typeof result === "string") {
+ try {
+ parsed = JSON.parse(result);
+ } catch {
+ parsed = null;
+ }
+ }
+ if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+ if (typeof parsed.count === "number" && typeof parsed.completed === "number") {
+ summary = {
+ ok: true,
+ count: parsed.count,
+ inProgress: typeof parsed.inProgress === "string" ? parsed.inProgress : null,
+ completed: parsed.completed,
+ pending: typeof parsed.pending === "number" ? parsed.pending : Math.max(0, parsed.count - parsed.completed),
+ };
+ }
+ }
+ }
+
+ if (!items && !summary) {
+ return null;
+ }
+
+ return {
+ items: items || [],
+ summary,
+ };
+}
+
+/**
+ * Cache the latest non-null state in memory across turn boundaries.
+ */
+export function rememberTodos(state) {
+ if (state != null) {
+ cachedTodos = state;
+ }
+ return state;
+}
+
+/**
+ * Retrieve the cached todo state.
+ */
+export function latestTodos() {
+ return cachedTodos;
+}
+
+/**
+ * Format the checklist block for terminal output.
+ * Uses plain dimming without strike codes because strike escapes (\\x1b[9m) render inconsistently
+ * or corrupt glyphs on legacy Windows emulators.
+ */
+export function formatTodoBlock(state, { colors = {}, maxItems = 12, columns } = {}) {
+ if (!state) return "";
+ const items = Array.isArray(state.items) ? state.items : [];
+ if (!items.length && !state.summary) return "";
+
+ const termCols = Math.max(24, Number(columns ?? process.stdout?.columns ?? 80));
+ const accent = colors?.c || colors?.cyan || colors?.blue || "";
+ const dim = colors?.dim || "";
+ const reset = (accent || dim) ? (colors?.reset || "\x1b[0m") : "";
+
+ const indent = " ";
+ // Reserve 6 columns for two spaces of indentation and four-column status markers like "[x] ".
+ const textBudget = Math.max(10, termCols - 6);
+
+ const lines = [];
+ // `--all` passes Infinity; only a missing or negative cap falls back to the default, otherwise
+ // asking for everything would quietly render twelve rows.
+ const effectiveMax = typeof maxItems === "number" && maxItems >= 0 ? maxItems : 12;
+ const renderCount = Math.min(items.length, effectiveMax);
+
+ for (let i = 0; i < renderCount; i++) {
+ const item = items[i];
+ if (item.status === "completed") {
+ const text = fit(item.content, textBudget);
+ const row = `[x] ${text}`;
+ lines.push(`${indent}${dim ? `${dim}${row}${reset}` : row}`);
+ } else if (item.status === "in_progress") {
+ const text = fit(item.activeForm || item.content, textBudget);
+ const marker = accent ? `${accent}[~]${reset}` : "[~]";
+ lines.push(`${indent}${marker} ${text}`);
+ } else {
+ const text = fit(item.content, textBudget);
+ lines.push(`${indent}[ ] ${text}`);
+ }
+ }
+
+ if (items.length > effectiveMax) {
+ const withheld = items.length - effectiveMax;
+ const withheldText = `… ${withheld} more items`;
+ lines.push(`${indent}${dim ? `${dim}${withheldText}${reset}` : withheldText}`);
+ }
+
+ if (state.summary && typeof state.summary.count === "number" && typeof state.summary.completed === "number") {
+ const progressText = `${state.summary.completed}/${state.summary.count} done`;
+ lines.push(`${indent}${dim ? `${dim}${progressText}${reset}` : progressText}`);
+ }
+
+ return lines.join("\n");
+}
+
+/**
+ * Format a compact status chip showing progress and active task.
+ */
+export function todoStatusChip(state = cachedTodos) {
+ if (!state) return null;
+
+ const summary = state.summary;
+ const items = Array.isArray(state.items) ? state.items : [];
+
+ let count = summary?.count ?? items.length;
+ let completed = summary?.completed ?? items.filter((i) => i.status === "completed").length;
+
+ if (count <= 0) return null;
+
+ const activeItem = items.find((i) => i.status === "in_progress");
+ const activeText = activeItem ? (activeItem.activeForm || activeItem.content) : (summary?.inProgress || null);
+
+ const progress = `${completed}/${count}`;
+ if (activeText) {
+ // Cap label to 24 characters to prevent horizontal wrapping on tight status rows.
+ return `todos ${progress} · ${fit(activeText, 24)}`;
+ }
+ return `todos ${progress}`;
+}
+
+/**
+ * Print the formatted todo block via a designated sink.
+ */
+export function printTodoBlock(state, { colors, maxItems, print = console.log, activity } = {}) {
+ const formatted = formatTodoBlock(state, { colors, maxItems });
+ if (!formatted) return false;
+ if (activity?.live) {
+ activity.clear();
+ const tone = colors?.c || colors?.cyan || "";
+ const reset = colors?.reset || "";
+ print(`${tone} ✓ todo_write${reset}`);
+ }
+ print(formatted);
+ return true;
+}
diff --git a/scripts/mso-agent-todos.test.ts b/scripts/mso-agent-todos.test.ts
new file mode 100644
index 00000000..64f7e006
--- /dev/null
+++ b/scripts/mso-agent-todos.test.ts
@@ -0,0 +1,191 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+ clearTodos,
+ formatTodoBlock,
+ latestTodos,
+ parseTodoCall,
+ rememberTodos,
+ resetTodosForTesting,
+ todoStatusChip,
+} from "./mso-agent-todos.mjs";
+
+describe("MSO Agent todos view", () => {
+ beforeEach(() => {
+ resetTodosForTesting();
+ });
+
+ it("1. a full list renders all three states with the right markers and the active item uses activeForm", () => {
+ const input = {
+ todos: [
+ { status: "completed", content: "read plan documentation" },
+ { status: "in_progress", content: "write parser", activeForm: "writing parser" },
+ { status: "pending", content: "verify tests pass" },
+ ],
+ };
+ const result = JSON.stringify({
+ ok: true,
+ count: 3,
+ inProgress: "writing parser",
+ completed: 1,
+ pending: 1,
+ });
+
+ const parsed = parseTodoCall(input, result);
+ expect(parsed).not.toBeNull();
+
+ const output = formatTodoBlock(parsed);
+ expect(output).toContain(" [x] read plan documentation");
+ expect(output).toContain(" [~] writing parser");
+ expect(output).not.toContain("write parser");
+ expect(output).toContain(" [ ] verify tests pass");
+ expect(output).toContain(" 1/3 done");
+
+ const lines = output.split("\n");
+ for (const line of lines) {
+ expect(line.startsWith(" ")).toBe(true);
+ }
+ });
+
+ it("2. maxItems is respected and the withheld count is reported", () => {
+ const todos = [];
+ for (let i = 1; i <= 15; i++) {
+ todos.push({
+ status: i <= 5 ? "completed" : "pending",
+ content: `task item ${i}`,
+ });
+ }
+
+ const state = {
+ items: todos,
+ summary: { ok: true, count: 15, completed: 5, pending: 10, inProgress: null },
+ };
+
+ const output = formatTodoBlock(state, { maxItems: 12 });
+ expect(output).toContain(" … 3 more items");
+ expect(output).toContain(" 5/15 done");
+
+ const renderedTasks = output.split("\n").filter((l) => l.includes("task item"));
+ expect(renderedTasks).toHaveLength(12);
+ });
+
+ it("3. an unparseable result and a non-array todos do not throw and yield null or a summary-only state", () => {
+ expect(parseTodoCall(null, null)).toBeNull();
+ expect(parseTodoCall({}, "corrupt json string {")).toBeNull();
+ expect(parseTodoCall({ todos: "not an array" }, "invalid json")).toBeNull();
+
+ const summaryOnly = parseTodoCall(
+ { todos: "not an array" },
+ JSON.stringify({ ok: true, count: 4, completed: 2, inProgress: null, pending: 2 }),
+ );
+ expect(summaryOnly).not.toBeNull();
+ expect(summaryOnly?.items).toEqual([]);
+ expect(summaryOnly?.summary?.count).toBe(4);
+
+ const itemsOnly = parseTodoCall(
+ {
+ todos: [{ status: "pending", content: "item without valid summary result" }],
+ },
+ "corrupted { json",
+ );
+ expect(itemsOnly).not.toBeNull();
+ expect(itemsOnly?.items).toHaveLength(1);
+ expect(itemsOnly?.summary).toBeNull();
+ });
+
+ it("4. items with an invalid status or empty content are dropped, not rendered", () => {
+ const input = {
+ todos: [
+ { status: "unknown_status", content: "invalid status" },
+ { status: "pending", content: "" },
+ { status: "pending", content: " " },
+ { status: 123, content: "number status" },
+ null,
+ "string instead of object",
+ { status: "completed", content: "valid item" },
+ ],
+ };
+
+ const parsed = parseTodoCall(input, null);
+ expect(parsed).not.toBeNull();
+ expect(parsed?.items).toHaveLength(1);
+ expect(parsed?.items[0].content).toBe("valid item");
+
+ const output = formatTodoBlock(parsed);
+ expect(output).toContain(" [x] valid item");
+ expect(output).not.toContain("invalid status");
+ });
+
+ it("5. todoStatusChip() is null before any rememberTodos, and names the active item after", () => {
+ expect(latestTodos()).toBeNull();
+ expect(todoStatusChip()).toBeNull();
+
+ const state = {
+ items: [
+ { status: "completed", content: "setup project" },
+ { status: "in_progress", content: "write parser", activeForm: "writing the parser" },
+ { status: "pending", content: "add status chip" },
+ ],
+ summary: { ok: true, count: 3, completed: 1, pending: 1, inProgress: "write parser" },
+ };
+
+ rememberTodos(state);
+ expect(latestTodos()).toBe(state);
+
+ const chip = todoStatusChip();
+ expect(chip).toBe("todos 1/3 · writing the parser");
+ });
+
+ it("6. rememberTodos replaces the previous list rather than merging", () => {
+ const stateA = {
+ items: [{ status: "pending", content: "initial task" }],
+ summary: { ok: true, count: 1, completed: 0, pending: 1, inProgress: null },
+ };
+ rememberTodos(stateA);
+ expect(latestTodos()?.items[0].content).toBe("initial task");
+
+ const stateB = {
+ items: [{ status: "completed", content: "replacement task" }],
+ summary: { ok: true, count: 1, completed: 1, pending: 0, inProgress: null },
+ };
+ rememberTodos(stateB);
+
+ const current = latestTodos();
+ expect(current?.items).toHaveLength(1);
+ expect(current?.items[0].content).toBe("replacement task");
+ expect(formatTodoBlock(current)).not.toContain("initial task");
+ });
+
+ it("7. no colours passed means no ANSI codes in the output", () => {
+ const state = {
+ items: [
+ { status: "completed", content: "done task" },
+ { status: "in_progress", content: "working task", activeForm: "actively working" },
+ { status: "pending", content: "future task" },
+ ],
+ summary: { ok: true, count: 3, completed: 1, pending: 1, inProgress: "actively working" },
+ };
+
+ const outputWithoutColors = formatTodoBlock(state);
+ // Escape code regex detects ANSI sequences
+ expect(outputWithoutColors).not.toMatch(/\x1b/);
+
+ const outputWithEmptyColors = formatTodoBlock(state, { colors: {} });
+ expect(outputWithEmptyColors).not.toMatch(/\x1b/);
+ });
+});
+
+describe("todo view bounds and session hygiene", () => {
+ it("treats a non-finite maxItems as no cap, so --all really shows every item", () => {
+ const items = Array.from({ length: 30 }, (_, i) => ({ content: `task ${i}`, status: "pending" }));
+ const block = formatTodoBlock({ items, summary: null }, { maxItems: Number.POSITIVE_INFINITY });
+ expect(block).toContain("task 29");
+ expect(block).not.toContain("more items");
+ });
+
+ it("drops the cache when a session ends, so a new session does not inherit the checklist", () => {
+ rememberTodos(parseTodoCall({ todos: [{ content: "write the parser", status: "in_progress" }] }, null));
+ expect(todoStatusChip()).toBe("todos 0/1 · write the parser");
+ clearTodos();
+ expect(todoStatusChip()).toBeNull();
+ });
+});
diff --git a/scripts/mso-agent-turn.mjs b/scripts/mso-agent-turn.mjs
index cf94d09b..d0e97807 100644
--- a/scripts/mso-agent-turn.mjs
+++ b/scripts/mso-agent-turn.mjs
@@ -15,6 +15,7 @@ import { addUsage } from "./mso-agent-status.mjs";
import { oneShotApproves } from "./mso-agent-oneshot.mjs";
import { reasoningLine } from "./mso-agent-reasoning.mjs";
import { parseEditResult, printEditDiff } from "./mso-agent-edit-diff.mjs";
+import { parseTodoCall, printTodoBlock, rememberTodos } from "./mso-agent-todos.mjs";
function lazyAssistantOutput(session, options = {}) {
if (options.quiet) return null;
@@ -92,6 +93,7 @@ export async function executeTool(rl, tool, call, agentSession, permission = "as
if (options.activity) options.activity.toolEnd(tool, true);
else process.stdout.write(`\r${C.c} ✓ ${tool.name}${C.reset}\n`);
if (tool.name === "fs_edit") printEditDiff(parseEditResult(out.result), { colors: C, activity: options.activity });
+ if (tool.name === "todo_write") printTodoBlock(rememberTodos(parseTodoCall(input, out.result)), { colors: C, activity: options.activity });
}
if (!out.ok) return { ok: false, result: out.result || "tool failed" };
return { ok: true, result: String(out.result ?? "ok") };