pi-jar 0.1.3 → 0.1.5

package/src/task-tool.ts

@@ -1,53 +1,80 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-import type { Todo } from "./tasks.ts";
-import { TODO_STATUSES, TodoStore, todoMark } from "./tasks.ts";
+import type { Todo, TodoInput, TodoStatus } from "./tasks.ts";
+import { TODO_STATUSES, TodoStore, todoMark, todoProgress, todoTotals } from "./tasks.ts";
 
-const ACTIONS = ["write", "list", "add", "start", "done", "open", "edit", "delete"] as const;
-const Action = Type.Unsafe<(typeof ACTIONS)[number]>({ type: "string", enum: ACTIONS as any });
-const Status = Type.Unsafe<(typeof TODO_STATUSES)[number]>({ type: "string", enum: TODO_STATUSES as any });
+const ACTIONS = ["write", "list", "append", "remove", "update", "add", "start", "done", "open", "edit", "delete"] as const;
+const Action = Type.Unsafe<(typeof ACTIONS)[number]>({ type: "string", enum: [...ACTIONS] });
+const Status = Type.Unsafe<(typeof TODO_STATUSES)[number]>({ type: "string", enum: [...TODO_STATUSES] });
+const Content = Type.String({ description: "Imperative task title, e.g. \"Run the tests\"." });
+const ActiveForm = Type.Optional(Type.String({ description: "Present-continuous form shown while it runs, e.g. \"Running the tests\"." }));
 
 const Parameters = Type.Object({
   todos: Type.Optional(Type.Array(Type.Object({
-    content: Type.String({ description: "Imperative task title, e.g. \"Run the tests\"." }),
+    id: Type.Optional(Type.String({ description: "Existing stable task id for legacy write; omitted ids match by title." })),
+    content: Content,
     status: Status,
-    activeForm: Type.Optional(Type.String({ description: "Present-continuous form shown while it runs, e.g. \"Running the tests\"." }))
-  }), { description: "The complete, updated task list. Replaces the current list." })),
+    activeForm: ActiveForm,
+    subtasks: Type.Optional(Type.Array(Type.Object({ id: Type.Optional(Type.String()), content: Content, status: Status, activeForm: ActiveForm }), {
+      description: "Optional steps of this task (one level deep). The task's status then follows its subtasks."
+    }))
+  }), { description: "For append: new tasks only. For update: exactly one updated task. With write (or no action): the complete list, replacing it." })),
   action: Type.Optional(Action),
-  id: Type.Optional(Type.String({ description: "Task id for start/done/open/edit/delete." })),
-  title: Type.Optional(Type.String({ description: "Concise actionable task title for add/edit." })),
+  id: Type.Optional(Type.String({ description: "Stable task id for update/remove/start/done/open/edit/delete. On a parent, start runs its first open subtask; done/open apply to all its subtasks." })),
+  title: Type.Optional(Type.String({ description: "Task title for append/add/edit/update." })),
+  status: Type.Optional(Status),
+  activeForm: ActiveForm,
+  parent: Type.Optional(Type.String({ description: "For append/add: id of a top-level task to add the new task under as a subtask." })),
   details: Type.Optional(Type.String({ description: "Optional short task context for a new task." }))
 });
 
 interface TaskToolDetails {
   action: string;
-  /** Bounded preview only; the canonical list lives in TodoStore. */
+  /** Bounded preview (the full list in a subagent); the canonical list lives in TodoStore. */
   items: Todo[];
+  /** Leaf tasks: subtasks plus top-level tasks without subtasks. */
   total: number;
   done: number;
+  /** Every item, parents included. */
+  count?: number;
   current?: string;
   changed?: string;
+  /** Full stable id index, including items outside the bounded preview. */
+  ids?: { id: string; title: string; parentId?: string }[];
+  /** Optional deliberately small render surface for terse mutations such as start/done. */
+  display?: Todo[];
   truncated?: boolean;
+  /** Subtask counts of previewed parents when the preview cuts the list. */
+  progress?: { id: string; done: number; total: number }[];
 }
 
+type TodoParam = { id?: string; content: string; status: TodoStatus; activeForm?: string; subtasks?: readonly TodoParam[] };
+/** Deeper nesting is passed through so the store rejects it with a clear message. */
+const toInput = (item: TodoParam): TodoInput => ({
+  ...(item.id !== undefined ? { id: item.id } : {}),
+  title: item.content, status: item.status,
+  ...(item.activeForm !== undefined ? { activeForm: item.activeForm } : {}),
+  ...(item.subtasks !== undefined ? { subtasks: item.subtasks.map(toInput) } : {})
+});
+
 const stats = (items: readonly Todo[]) => {
-  let done = 0;
-  let current: Todo | undefined;
-  for (const item of items) {
-    if (item.done) done++;
-    if (!current && item.status === "in_progress") current = item;
-  }
-  return { total: items.length, done, current };
+  const parents = new Set<string>();
+  for (const item of items) if (item.parentId) parents.add(item.parentId);
+  const current = items.find((item) => item.status === "in_progress" && !parents.has(item.id));
+  const parent = current?.parentId ? items.find((item) => item.id === current.parentId) : undefined;
+  return { ...todoTotals(items), current: current && (parent ? parent.title + " › " : "") + current.title };
 };
 const summary = (items: readonly Todo[]) => {
   const value = stats(items);
-  return `${value.done}/${value.total} done` + (value.current ? ` · now: ${value.current.title}` : "");
+  return `${value.done}/${value.total} done` + (value.current ? ` · now: ${value.current}` : "");
 };
 
-const lines = (items: readonly Todo[]) => items.length
-  ? items.map((item) => `${todoMark(item)} [${item.status}] ${item.title} (${item.id})`).join("\n")
-  : "No tracked tasks.";
+const line = (items: readonly Todo[], item: Todo) => {
+  const progress = todoProgress(items, item.id);
+  return `${item.parentId ? "  " : ""}${todoMark(item)} [${item.status}] ${item.title}${progress.total ? ` (${progress.done}/${progress.total} done)` : ""} (${item.id})`;
+};
+const lines = (items: readonly Todo[]) => items.length ? items.map((item) => line(items, item)).join("\n") : "No tracked tasks.";
 
 const REMINDER = "Keep using jar_todo to track progress: mark the next task in_progress before starting it and completed as soon as it is verified.";
 
@@ -60,74 +87,138 @@ export function registerTaskTool(
   pi.registerTool({
     name: "jar_todo",
     label: "tasks",
-    description: "Maintain pi-jar's session task list, shown live to the user. Send `todos` with the complete updated list (each with content, status pending|in_progress|completed, and activeForm). Single-task actions (start, done, open, add, edit, delete, list) are also available.",
-    promptSnippet: "Track multi-step work with jar_todo: write the full list, keep exactly one task in_progress, complete tasks as they finish.",
+    description: "Maintain session tasks: write establishes a fresh complete task plan, update changes one existing task by stable id, append adds genuinely new work, and remove deletes one task tree. start/done/open/edit remain concise status operations. Stable IDs are returned for every task.",
+    promptSnippet: "Track multi-step work with jar_todo: write the task plan first, update/remove existing tasks by stable id, append only when new work arrives mid-run, and keep one leaf in_progress.",
     promptGuidelines: [
       "Use jar_todo proactively, without waiting for the user, for any task with three or more distinct steps, when the user gives several tasks, or right after receiving new instructions. Skip it for single trivial requests and pure questions.",
-      "Prefer jar_todo with `todos` (the full updated list). Each item has `content` (imperative, e.g. \"Run tests\"), `status`, and `activeForm` (present continuous, e.g. \"Running tests\"), which the user sees while it runs.",
-      "Keep exactly one task in_progress at a time. Mark a task in_progress before you start it and completed immediately after it is verified; do not batch completions.",
+      "Prefer write when establishing the task plan for a new request. If the existing checklist is fully completed, start the next request with a fresh write rather than appending onto old completed work.",
+      "Use update with a stable id to revise one existing task and remove to delete one task tree. Use append mainly when the user steers or adds genuinely new requirements while an active checklist is already in progress; do not use append as the default way to create a new plan.",
+      "write with todos is the complete current task plan and removes omitted tasks. Each item has content, status, and optional activeForm/subtasks.",
+      "Break a large task into `subtasks` (same shape, one level deep). A parent's status follows its subtasks: it is completed when all of them are. Progress counts leaf tasks (subtasks and tasks without subtasks).",
+      "Keep exactly one leaf task in_progress at a time. Mark a task in_progress before you start it and completed immediately after it is verified; do not batch completions.",
       "Only mark a task completed when it is fully done. If tests fail, work is partial or you are blocked, keep it in_progress and add a task for what must be resolved. Remove tasks that are no longer relevant."
     ],
     parameters: Parameters,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const current = store();
-      const action = params.todos ? "write" : params.action ?? "list";
+      const action = params.action ?? (params.todos !== undefined ? "write" : "list");
       if (!current) {
         return { content: [{ type: "text", text: "Task tracking is unavailable before a Pi session starts." }], details: { action, items: [], total: 0, done: 0 } satisfies TaskToolDetails };
       }
       let changedId: string | undefined;
       let error: string | undefined;
-      switch (action) {
+      let inputs: TodoInput[] | undefined;
+      if (params.todos !== undefined) {
+        try {
+          if (!Array.isArray(params.todos)) throw new Error();
+          inputs = params.todos.map(toInput);
+        } catch { error = "todos must be an array of task objects with array subtasks."; }
+        if (!["write", "append", "update"].includes(action)) error = "todos may only be used with write, append, or update; no tasks were changed.";
+      }
+      if (!error) switch (action) {
         case "list":
           break;
         case "write":
-          if (!params.todos) { error = "write needs `todos`: the complete updated list."; break; }
-          error = current.write(params.todos.map((item) => ({ title: item.content, status: item.status, ...(item.activeForm ? { activeForm: item.activeForm } : {}) })));
+          if (!inputs) { error = "write needs `todos`: the complete updated list."; break; }
+          error = current.write(inputs);
+          break;
+        case "append": {
+          const before = new Set(current.all().map((item) => item.id));
+          if (inputs && params.title !== undefined) { error = "append accepts either todos or title, not both."; break; }
+          error = current.appendTodos(inputs ?? [{ title: params.title ?? "", status: params.status ?? "pending", activeForm: params.activeForm, details: params.details }], params.parent);
+          if (!error) changedId = current.all().find((item) => !before.has(item.id))?.id;
           break;
+        }
+        case "update": {
+          if (!params.id) { error = "update needs a valid existing task id."; break; }
+          if (inputs && (inputs.length !== 1 || params.title !== undefined || params.status !== undefined || params.activeForm !== undefined)) { error = "update accepts exactly one todos item OR title/status/activeForm fields."; break; }
+          const replacement = inputs?.[0] ?? {
+            ...(params.title !== undefined ? { title: params.title } : {}),
+            ...(params.status !== undefined ? { status: params.status } : {}),
+            ...(params.activeForm !== undefined ? { activeForm: params.activeForm } : {})
+          };
+          error = current.update(params.id, replacement);
+          if (!error) changedId = params.id;
+          break;
+        }
         case "add": {
-          const item = params.title?.trim() ? current.add(params.title, params.details) : undefined;
-          if (!item) error = "add needs a short title.";
+          const parent = params.parent?.trim() || undefined;
+          const title = params.title ?? "";
+          error = current.addError(title, parent);
+          const item = error ? undefined : current.add(title, params.details, parent);
+          if (!error && !item) error = "Could not save the task.";
           changedId = item?.id;
           break;
         }
         case "start":
         case "done":
-        case "open":
-          if (!params.id || !current.setStatus(params.id, action === "start" ? "in_progress" : action === "done" ? "completed" : "pending")) error = `${action} needs a valid id from jar_todo list.`;
-          else changedId = params.id;
+        case "open": {
+          const item = params.id ? current.get(params.id) : undefined;
+          const progress = item ? todoProgress(current.all(), item.id) : { done: 0, total: 0 };
+          if (!item) error = `${action} needs a valid id from jar_todo list.`;
+          else if (action === "start" && progress.total && progress.done === progress.total) error = `every subtask of ${item.id} is completed; open it or add a subtask first.`;
+          else if (!current.setStatus(item.id, action === "start" ? "in_progress" : action === "done" ? "completed" : "pending")) error = "Could not save the task.";
+          else changedId = action === "start" ? (current.current()?.id ?? item.id) : item.id;
           break;
+        }
         case "edit":
           if (!params.id || !params.title?.trim() || !current.edit(params.id, params.title)) error = "edit needs a valid id and a title.";
           else changedId = params.id;
           break;
+        case "remove":
         case "delete":
-          if (!params.id || !current.delete(params.id)) error = "delete needs a valid id from jar_todo list.";
+          if (!params.id || !current.delete(params.id)) error = `${action} needs a valid id from jar_todo list.`;
           else changedId = params.id;
           break;
+        default: error = "Unknown task action; no tasks were changed.";
       }
       if (action !== "list" && !error) changed(ctx);
       const items = current.all();
       const state = stats(items);
+      // The changed task in context: its whole parent group, subtasks indented.
       const changedItem = changedId ? items.find((item) => item.id === changedId) : undefined;
+      const root = changedItem?.parentId ?? changedItem?.id;
+      const group = root ? items.filter((item) => item.id === root || item.parentId === root) : [];
+      const mutationItems = action === "write" || action === "append" ? items : group;
+      const mutationPreview = mutationItems.slice(0, 8);
+      const terseMutation = action === "start" || action === "done";
+      const terseItem = terseMutation && changedId ? items.find((item) => item.id === changedId) : undefined;
+      // Keep task prose bounded while still returning every addressable id in canonical order.
+      const idIndex = mutationItems.length > 8
+        ? "\nTask IDs (list order): " + items.map((item, index) => `${index + 1}=${item.id}`).join(", ") + "\nUse list for all task titles."
+        : "";
       const message = error
         ? `Could not ${action} tasks: ${error} (${summary(items)}).`
         : action === "list"
           ? `Tasks (${summary(items)}):\n${lines(items)}`
-          : `Task list updated (${summary(items)}).${changedItem ? `\n${todoMark(changedItem)} [${changedItem.status}] ${changedItem.title} (${changedItem.id})` : ""}\n${REMINDER}`;
-      const preview = items.slice(0, 8);
+          : action === "start" && terseItem
+            ? `Started task:\n${line(items, terseItem)}`
+            : action === "done" && terseItem
+              ? `Completed task:\n${line(items, terseItem)}`
+              : `Task list updated (${summary(items)}).${mutationPreview.length ? "\n" + mutationPreview.map((item) => line(items, item)).join("\n") : ""}${idIndex}\n${REMINDER}`;
+      // A subagent's parent mirrors the checklist from these details, so children send it whole.
+      const preview = process.env.PI_JAR_CHILD ? items : items.slice(0, 8);
+      const truncated = preview.length < items.length;
+      const progress = truncated ? preview.flatMap((item) => {
+        const value = todoProgress(items, item.id);
+        return value.total ? [{ id: item.id, ...value }] : [];
+      }) : [];
       return {
         content: [{ type: "text", text: message }],
         details: {
-          action, items: preview, total: state.total, done: state.done,
-          ...(state.current ? { current: state.current.title } : {}),
-          ...(preview.length < items.length ? { truncated: true } : {}),
+          action, items: preview, total: state.total, done: state.done, count: items.length,
+          ids: items.map(({ id, title, parentId }) => ({ id, title, ...(parentId ? { parentId } : {}) })),
+          ...(terseItem ? { display: [{ ...terseItem }] } : {}),
+          ...(state.current ? { current: state.current } : {}),
+          ...(truncated ? { truncated: true } : {}),
+          ...(progress.length ? { progress } : {}),
           ...(changedId ? { changed: changedId } : {})
         } satisfies TaskToolDetails
       };
     },
     renderCall(args, theme) {
       let text = theme.fg("toolTitle", theme.bold("tasks"));
-      if (args.todos) text += " " + theme.fg("accent", `update · ${args.todos.length} item${args.todos.length === 1 ? "" : "s"}`);
+      if (args.todos) text += " " + theme.fg("accent", `${args.action ?? "write"} · ${args.todos.length} item${args.todos.length === 1 ? "" : "s"}`);
       else {
         text += " " + theme.fg("accent", args.action ?? "list");
         if (args.title) text += " " + theme.fg("muted", args.title);
@@ -138,22 +229,33 @@ export function registerTaskTool(
       if (isPartial) return new Text(theme.fg("warning", "Updating tasks…"), 0, 0);
       const details = result.details as TaskToolDetails | undefined;
       const items = details?.items ?? [];
-      const total = details?.total ?? items.length;
-      const done = details?.done ?? items.filter((item) => item.done).length;
-      if (!total) return new Text(theme.fg("dim", "No tracked tasks."), 0, 0);
-      const shown = expanded ? items : items.slice(0, 8);
-      let text = theme.fg("dim", `${done}/${total} done${details?.current ? " · now: " + details.current : ""}`);
-      for (const item of shown) text += "\n" + todoRow(item, (color, value) => theme.fg(color, value), (value) => theme.bold(value));
-      if (details?.truncated || shown.length < total) text += "\n" + theme.fg("dim", `  … +${Math.max(0, total - shown.length)} more · /jar tasks`);
+      const displayItems = details?.display ?? items;
+      // Older results predate `count`, when `total` counted every item.
+      const count = details?.count ?? details?.total ?? items.length;
+      const totals = details?.total === undefined ? todoTotals(items) : { done: details.done, total: details.total };
+      if (!count) return new Text(theme.fg("dim", "No tracked tasks."), 0, 0);
+      const known = new Map((details?.progress ?? []).map((value) => [value.id, value]));
+      const shown = details?.display ? displayItems : expanded ? items : items.slice(0, 8);
+      let text = details?.display ? "" : theme.fg("dim", `${totals.done}/${totals.total} done${details?.current ? " · now: " + details.current : ""}`);
+      for (const item of shown) {
+        const row = todoRow(item, (color, value) => theme.fg(color, value), (value) => theme.bold(value), known.get(item.id) ?? todoProgress(items, item.id));
+        text += (text ? "\n" : "") + row;
+      }
+      if (!details?.display && (details?.truncated || shown.length < count)) text += "\n" + theme.fg("dim", `  … +${Math.max(0, count - shown.length)} more · /jar tasks`);
       return new Text(text, 0, 0);
     }
   });
 }
 
 type TodoColor = "accent" | "muted" | "dim" | "success";
-/** One checklist row: completed rows are struck through, the running one is bold. */
-export function todoRow(item: Todo, fg: (color: TodoColor, text: string) => string, bold: (text: string) => string = (text) => text): string {
-  if (item.status === "completed") return fg("success", "  ✔ ") + fg("dim", "\x1b[9m" + item.title + "\x1b[29m");
-  if (item.status === "in_progress") return fg("accent", "  ◼ ") + fg("accent", bold(item.title));
-  return fg("muted", "  ☐ " + item.title);
+/**
+ * One checklist row: completed rows are struck through, the running one is bold. Subtasks are
+ * indented; pass a parent's subtask `progress` to show its `(done/total)`.
+ */
+export function todoRow(item: Todo, fg: (color: TodoColor, text: string) => string, bold: (text: string) => string = (text) => text, progress?: { done: number; total: number }): string {
+  const indent = item.parentId ? "    " : "  ";
+  const suffix = progress?.total ? fg("dim", ` (${progress.done}/${progress.total})`) : "";
+  if (item.status === "completed") return fg("success", indent + "✔ ") + fg("dim", "\x1b[9m" + item.title + "\x1b[29m") + suffix;
+  if (item.status === "in_progress") return fg("accent", indent + "◼ ") + fg("accent", bold(item.title)) + suffix;
+  return fg("muted", indent + "☐ " + item.title) + suffix;
 }

package/src/tasks-ui.ts

@@ -1,6 +1,6 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { promptChoice, promptText, todoView, type TodoFilter } from "./dialogs.ts";
-import { TodoStore } from "./tasks.ts";
+import { TodoStore, todoProgress } from "./tasks.ts";
 
 const help = "Usage: /jar tasks [list|add TITLE|done ID|open ID|edit ID TITLE|delete ID]";
 
@@ -11,7 +11,15 @@ export async function manageTasks(args: string, ctx: ExtensionContext, store: To
   };
   const list = () => {
     const items = store.all();
-    notify(items.length ? items.map((item) => `${item.done ? "[x]" : "[ ]"} ${item.title} (${item.id})`).join("\n") : "pi-jar to-do: empty (separate from other task managers)");
+    notify(items.length ? items.map((item) => {
+      const progress = todoProgress(items, item.id);
+      return `${item.parentId ? "  " : ""}${item.done ? "[x]" : "[ ]"} ${item.title}${progress.total ? ` (${progress.done}/${progress.total})` : ""} (${item.id})`;
+    }).join("\n") : "pi-jar to-do: empty (separate from other task managers)");
+  };
+  /** Deleting a parent also deletes its subtasks, so say so before confirming. */
+  const deleteLabel = (id: string, title: string) => {
+    const count = todoProgress(store.all(), id).total;
+    return count ? `${title} (and ${count} subtask${count === 1 ? "" : "s"})` : title;
   };
   if (!args && ctx.hasUI && ctx.mode === "tui") {
     const filter: { value: TodoFilter } = { value: "all" };
@@ -29,7 +37,7 @@ export async function manageTasks(args: string, ctx: ExtensionContext, store: To
         if (title) success = store.edit(action.id, title);
       } else if (action.id && action.kind === "delete") {
         const item = store.get(action.id);
-        const choice = item && await promptChoice(ctx, "Delete to-do?", item.title, ["Delete item", "Keep item"], 1);
+        const choice = item && await promptChoice(ctx, "Delete to-do?", deleteLabel(item.id, item.title), ["Delete item", "Keep item"], 1);
         if (choice === 0) success = store.delete(action.id);
       }
       if (success) changed();
@@ -47,8 +55,10 @@ export async function manageTasks(args: string, ctx: ExtensionContext, store: To
     }
     case "done":
     case "open": {
+      // On a parent, done completes and open reopens every subtask.
       const item = id && store.get(id);
-      if (item && item.done !== (verb === "done") && store.toggle(id)) { changed(); notify("Updated pi-jar to-do"); }
+      const already = item && (verb === "done" ? item.done : item.status === "pending");
+      if (item && !already && store.setStatus(id, verb === "done" ? "completed" : "pending")) { changed(); notify("Updated pi-jar to-do"); }
       else notify("To-do not found or already in that state", "error");
       return;
     }
@@ -61,7 +71,7 @@ export async function manageTasks(args: string, ctx: ExtensionContext, store: To
     case "delete": {
       if (!id || !store.get(id)) { notify("To-do not found", "error"); return; }
       if (ctx.hasUI && ctx.mode === "tui") {
-        const choice = await promptChoice(ctx, "Delete pi-jar to-do?", store.get(id)!.title, ["Delete item", "Keep item"], 1);
+        const choice = await promptChoice(ctx, "Delete pi-jar to-do?", deleteLabel(id, store.get(id)!.title), ["Delete item", "Keep item"], 1);
         if (choice !== 0) return;
       }
       // Headless deletion is explicit and requires the full ID; TUI deletion asks for confirmation.