@inetafrica/open-claudia 2.0.4 → 2.0.5

package/bin/task.js

@@ -1,42 +1,101 @@
 // open-claudia task <subcommand>
 // Per-channel todo list. Use this for multi-step work so progress
-// survives compactions and restarts.
+// survives compactions and restarts. Supports one level of hierarchy:
+// a parent "plan" task can have child subtasks via --parent.
 
 const { postJson } = require("./loopback-client");
 
 const HELP = `
-Per-channel todo list.
+Per-channel todo list with optional plan/subtask hierarchy.
 
-  open-claudia task add "<content>"
+  open-claudia task add "<content>" [--parent <id>] [--description "<...>"]
+  open-claudia task plan "<title>" "<sub1>" "<sub2>" ... [--description "<...>"]
   open-claudia task list [--status pending|in_progress|completed]
   open-claudia task start <id>
   open-claudia task done <id>
-  open-claudia task remove <id>
-  open-claudia task clear-completed
+  open-claudia task remove <id>          # removing a plan removes its subtasks
+  open-claudia task clear-completed      # only clears plans whose subtasks are all done
+
+Use plans for any work with 3+ distinct steps. Mark subtasks in_progress
+as you start them and done as you finish, so a resumed turn or a new
+turn after compaction can pick up where you left off.
 `;
 
-function fmt(t, idx) {
-  const mark = t.status === "completed" ? "[x]" : t.status === "in_progress" ? "[~]" : "[ ]";
-  return `${idx + 1}. ${mark} ${t.content}    (${t.id})`;
+function statusMark(t) {
+  return t.status === "completed" ? "[x]" : t.status === "in_progress" ? "[~]" : "[ ]";
+}
+
+function takeFlag(args, name) {
+  const idx = args.indexOf(`--${name}`);
+  if (idx < 0) return null;
+  const v = args[idx + 1];
+  args.splice(idx, 2);
+  return v;
+}
+
+function renderTree(list) {
+  const byParent = new Map();
+  const roots = [];
+  for (const t of list) {
+    if (t.parentId) {
+      if (!byParent.has(t.parentId)) byParent.set(t.parentId, []);
+      byParent.get(t.parentId).push(t);
+    } else {
+      roots.push(t);
+    }
+  }
+  const lines = [];
+  roots.forEach((root, i) => {
+    lines.push(`${i + 1}. ${statusMark(root)} ${root.content}    (${root.id})`);
+    if (root.description) lines.push(`      ${root.description}`);
+    (byParent.get(root.id) || []).forEach((c) => {
+      lines.push(`    ${statusMark(c)} ${c.content}    (${c.id})`);
+    });
+  });
+  for (const orphan of list) {
+    if (orphan.parentId && !roots.find((r) => r.id === orphan.parentId)) {
+      lines.push(`    ${statusMark(orphan)} ${orphan.content}    (${orphan.id}) [orphan]`);
+    }
+  }
+  return lines.join("\n");
 }
 
 async function runAdd(args) {
+  const parentId = takeFlag(args, "parent");
+  const description = takeFlag(args, "description");
   const content = args.join(" ").trim();
-  if (!content) { console.error("Usage: task add \"<content>\""); process.exit(2); }
+  if (!content) { console.error("Usage: task add \"<content>\" [--parent <id>] [--description \"<...>\"]"); process.exit(2); }
   try {
-    const res = await postJson("task-add", { content });
+    const res = await postJson("task-add", { content, parentId, description });
     console.log(`Added task ${res.task.id}.`);
     process.exit(0);
   } catch (e) { console.error(e.message); process.exit(1); }
 }
 
+async function runPlan(args) {
+  const description = takeFlag(args, "description");
+  if (args.length < 2) {
+    console.error("Usage: task plan \"<title>\" \"<sub1>\" \"<sub2>\" ... [--description \"<...>\"]");
+    process.exit(2);
+  }
+  const [title, ...subtasks] = args;
+  try {
+    const res = await postJson("task-plan", { title, subtasks, description });
+    const parent = res.plan.parent;
+    const kids = res.plan.children || [];
+    console.log(`Plan ${parent.id}: ${parent.content}`);
+    kids.forEach((c) => console.log(`  - ${c.content}  (${c.id})`));
+    process.exit(0);
+  } catch (e) { console.error(e.message); process.exit(1); }
+}
+
 async function runList(args) {
-  const status = args[args.indexOf("--status") + 1] && args.includes("--status") ? args[args.indexOf("--status") + 1] : null;
+  const status = args.includes("--status") ? args[args.indexOf("--status") + 1] : null;
   try {
     const res = await postJson("task-list", status ? { status } : {});
     const list = res.tasks || [];
     if (list.length === 0) { console.log("No tasks."); process.exit(0); }
-    list.forEach((t, i) => console.log(fmt(t, i)));
+    console.log(renderTree(list));
     process.exit(0);
   } catch (e) { console.error(e.message); process.exit(1); }
 }
@@ -58,7 +117,8 @@ async function runRemove(args) {
   try {
     const res = await postJson("task-remove", { id });
     if (!res.ok) { console.error(`Not found: ${id}`); process.exit(1); }
-    console.log(`Removed ${id}.`);
+    const extra = (res.removed && res.removed.alsoRemoved) ? ` (and ${res.removed.alsoRemoved} subtask${res.removed.alsoRemoved === 1 ? "" : "s"})` : "";
+    console.log(`Removed ${id}${extra}.`);
     process.exit(0);
   } catch (e) { console.error(e.message); process.exit(1); }
 }
@@ -77,6 +137,7 @@ async function run(args) {
   if (!sub || sub === "--help" || sub === "help") { console.log(HELP); process.exit(sub ? 0 : 2); }
   switch (sub) {
     case "add": return runAdd(rest);
+    case "plan": return runPlan(rest);
     case "list": case "ls": return runList(rest);
     case "start": return runUpdate(rest, "in_progress");
     case "done": case "complete": return runUpdate(rest, "completed");

package/core/config.js

@@ -78,7 +78,7 @@ if (!CLAUDE_PATH) { console.error("CLAUDE_PATH not set"); process.exit(1); }
 if (!fs.existsSync(WORKSPACE)) {
   try {
     fs.mkdirSync(WORKSPACE, { recursive: true });
-    console.log(`Created workspace: ${WORKSPACE}`);
+    console.error(`Created workspace: ${WORKSPACE}`);
   } catch (e) {
     console.error(`Failed to create workspace: ${e.message}`);
     process.exit(1);
@@ -99,14 +99,14 @@ if (!resolvedCursorPath) {
   try { resolvedCursorPath = execSync("which agent 2>/dev/null", { encoding: "utf-8" }).trim() || null; }
   catch (e) { resolvedCursorPath = null; }
 }
-if (resolvedCursorPath) console.log(`Cursor Agent CLI: ${resolvedCursorPath}`);
+if (resolvedCursorPath) console.error(`Cursor Agent CLI: ${resolvedCursorPath}`);
 
 let resolvedCodexPath = CODEX_PATH;
 if (!resolvedCodexPath) {
   try { resolvedCodexPath = execSync("which codex 2>/dev/null", { encoding: "utf-8" }).trim() || null; }
   catch (e) { resolvedCodexPath = null; }
 }
-if (resolvedCodexPath) console.log(`Codex CLI: ${resolvedCodexPath}`);
+if (resolvedCodexPath) console.error(`Codex CLI: ${resolvedCodexPath}`);
 
 if (!fs.existsSync(TEMP_DIR)) fs.mkdirSync(TEMP_DIR, { recursive: true });
 if (!fs.existsSync(FILES_DIR)) fs.mkdirSync(FILES_DIR, { recursive: true });

package/core/loopback.js

@@ -64,7 +64,7 @@ function readBodyToFile(req, dest) {
 const SEND_KINDS = new Set(["send-file", "send-voice", "send-photo"]);
 const JSON_KINDS = new Set([
   "schedule-wakeup", "cron-add", "cron-remove", "job-list",
-  "task-add", "task-update", "task-remove", "task-list", "task-clear-completed",
+  "task-add", "task-plan", "task-update", "task-remove", "task-list", "task-tree", "task-clear-completed",
 ]);
 
 function readBodyAsString(req, max = 64 * 1024) {
@@ -177,8 +177,28 @@ async function handleJson(req, res, url, kind) {
 
   if (kind === "task-add") {
     if (!payload.content) return reply(res, 400, { error: "missing content" });
-    const t = tasksStore.add(adapterId, channelId, payload.content);
-    return reply(res, 200, { ok: true, task: t });
+    try {
+      const t = tasksStore.add(adapterId, channelId, payload.content, {
+        parentId: payload.parentId || null,
+        description: payload.description || null,
+      });
+      return reply(res, 200, { ok: true, task: t });
+    } catch (e) { return reply(res, 400, { error: e.message }); }
+  }
+
+  if (kind === "task-plan") {
+    if (!payload.title) return reply(res, 400, { error: "missing title" });
+    const subs = Array.isArray(payload.subtasks) ? payload.subtasks : [];
+    if (subs.length === 0) return reply(res, 400, { error: "subtasks must be a non-empty array" });
+    const result = tasksStore.plan(adapterId, channelId, payload.title, subs, {
+      description: payload.description || null,
+    });
+    return reply(res, 200, { ok: true, plan: result });
+  }
+
+  if (kind === "task-tree") {
+    const t = tasksStore.tree(adapterId, channelId);
+    return reply(res, 200, { ok: true, tree: t });
   }
 
   if (kind === "task-update") {

package/core/system-prompt.js

@@ -6,9 +6,10 @@ const fs = require("fs");
 const path = require("path");
 const { SOUL_FILE, CRONS_FILE, VAULT_FILE, FILES_DIR, BOT_DIR, WHISPER_CLI, FFMPEG } = require("./config");
 const { currentState } = require("./state");
-const { currentAdapter } = require("./context");
+const { currentAdapter, currentChannelId } = require("./context");
 const { vault } = require("./vault-store");
 const { transcriptPointerNote } = require("./transcripts");
+const tasksStore = require("./tasks");
 
 function loadSoul() {
   try { return fs.readFileSync(SOUL_FILE, "utf-8"); }
@@ -20,10 +21,22 @@ function buildSystemPrompt() {
   const soul = loadSoul();
   const hasVoice = WHISPER_CLI && FFMPEG;
   const adapter = currentAdapter();
+  const channelId = currentChannelId();
   const channelLabel = adapter
     ? (adapter.type === "kazee" ? "Kazee Chat" : adapter.type === "telegram" ? "Telegram" : adapter.type)
     : "Telegram";
 
+  let pendingTasksBlock = "";
+  if (adapter && channelId) {
+    try {
+      const pending = tasksStore.pendingSummary(adapter.id, channelId);
+      if (pending.length > 0) {
+        const tree = tasksStore.formatTree(adapter.id, channelId, { showIds: true });
+        pendingTasksBlock = `\n## Pending tasks\nYou may be resuming prior work. Before starting anything new, review these and decide whether to continue, update, or abandon them. Mark a subtask in_progress when you actually start it and completed when it's done.\n\n${tree}\n`;
+      }
+    } catch (e) {}
+  }
+
   return `
 ${soul}
 
@@ -43,7 +56,7 @@ ${soul}
 - Received user files directory: ${FILES_DIR}
 
 ${transcriptPointerNote(state)}
-
+${pendingTasksBlock}
 ## Delivery
 Reply normally in your final answer. To send a file, image, or voice clip back to the current chat, run the bot CLI from inside this task — channel context is already in the env:
 - \`open-claudia send-file <path> [caption]\` — any document/binary
@@ -60,10 +73,17 @@ Wake-ups and crons (real schedulers, not hallucinations — use them instead of
 - \`open-claudia cron-list\` — list all wakeups + crons on this channel.
 - \`open-claudia cron-remove <id>\` — cancel one.
 
-Persistent todo list (per channel; use for multi-step work so progress survives compaction):
-- \`open-claudia task add "<content>"\`
-- \`open-claudia task list\`
-- \`open-claudia task start <id>\` / \`task done <id>\` / \`task remove <id>\`
+Persistent todo list with plans + subtasks (per channel; survives compaction and restart).
+
+For any work with 3+ distinct steps you MUST create a plan before starting. The plan is a parent task whose children are the steps. As you work, mark each subtask in_progress when you begin and completed when done — this is how a resumed turn (after compaction, restart, or wakeup) sees where you left off. If pending tasks already exist when you start a turn they will be shown under "## Pending tasks" above; check them first.
+
+- \`open-claudia task plan "<plan title>" "<step 1>" "<step 2>" "<step 3>" [--description "<why / success criteria>"]\` — atomic create
+- \`open-claudia task add "<content>" [--parent <plan-id>] [--description "..."]\` — add a single task or subtask
+- \`open-claudia task list\` — renders as a tree
+- \`open-claudia task start <id>\` / \`task done <id>\` / \`task remove <id>\` (removing a plan removes its subtasks)
+- \`open-claudia task clear-completed\` — only clears plans whose subtasks are all done
+
+For one-off work under 3 steps, skip the plan and just track it in your own response.
 
 Sub-agents (spawn a fresh throwaway Claude for focused research — output comes back on stdout):
 - \`open-claudia agent "<prompt>" [--role "<role>"]\`

package/core/tasks.js

@@ -2,6 +2,10 @@
 // multi-step work that should survive a turn, a compaction, or a
 // restart. Scoped by adapter+channel so Telegram and Kazee see
 // separate lists.
+//
+// Tasks support a single level of hierarchy via parentId: a top-level
+// "plan" task can have child subtasks. This lets the agent break a big
+// piece of work into a plan whose progress is visible at a glance.
 
 const fs = require("fs");
 const path = require("path");
@@ -34,12 +38,20 @@ function nextId() {
   return `task_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
 }
 
-function add(adapter, channelId, content) {
+function add(adapter, channelId, content, opts = {}) {
   const list = load(adapter, channelId);
+  const parentId = opts.parentId || null;
+  if (parentId) {
+    const parent = list.find((t) => t.id === parentId);
+    if (!parent) throw new Error(`parent task not found: ${parentId}`);
+    if (parent.parentId) throw new Error(`nested subtasks not supported: ${parentId} is already a subtask`);
+  }
   const t = {
     id: nextId(),
     content: String(content || "").trim(),
     status: "pending",
+    parentId,
+    description: opts.description ? String(opts.description) : null,
     createdAt: Date.now(),
     updatedAt: Date.now(),
   };
@@ -48,6 +60,16 @@ function add(adapter, channelId, content) {
   return t;
 }
 
+function plan(adapter, channelId, title, subtaskContents, opts = {}) {
+  const parent = add(adapter, channelId, title, { description: opts.description || null });
+  const children = [];
+  for (const c of subtaskContents || []) {
+    if (!String(c || "").trim()) continue;
+    children.push(add(adapter, channelId, c, { parentId: parent.id }));
+  }
+  return { parent, children };
+}
+
 function update(adapter, channelId, id, patch) {
   const list = load(adapter, channelId);
   const idx = list.findIndex((t) => t.id === id);
@@ -59,17 +81,32 @@ function update(adapter, channelId, id, patch) {
 
 function remove(adapter, channelId, id) {
   const list = load(adapter, channelId);
-  const idx = list.findIndex((t) => t.id === id);
-  if (idx < 0) return null;
-  const [removed] = list.splice(idx, 1);
-  save(adapter, channelId, list);
-  return removed;
+  const target = list.find((t) => t.id === id);
+  if (!target) return null;
+  const ids = new Set([id]);
+  if (!target.parentId) {
+    for (const t of list) if (t.parentId === id) ids.add(t.id);
+  }
+  const next = list.filter((t) => !ids.has(t.id));
+  save(adapter, channelId, next);
+  return { removed: target, alsoRemoved: ids.size - 1 };
 }
 
 function clearCompleted(adapter, channelId) {
-  const list = load(adapter, channelId).filter((t) => t.status !== "completed");
-  save(adapter, channelId, list);
-  return list;
+  const all = load(adapter, channelId);
+  const drop = new Set();
+  for (const t of all) {
+    if (t.status !== "completed") continue;
+    if (t.parentId) { drop.add(t.id); continue; }
+    const kids = all.filter((c) => c.parentId === t.id);
+    if (kids.length === 0 || kids.every((c) => c.status === "completed")) {
+      drop.add(t.id);
+      for (const c of kids) drop.add(c.id);
+    }
+  }
+  const remaining = all.filter((t) => !drop.has(t.id));
+  save(adapter, channelId, remaining);
+  return remaining;
 }
 
 function list(adapter, channelId, opts = {}) {
@@ -78,15 +115,54 @@ function list(adapter, channelId, opts = {}) {
   return all;
 }
 
+function tree(adapter, channelId) {
+  const all = load(adapter, channelId);
+  const byParent = new Map();
+  const roots = [];
+  for (const t of all) {
+    if (t.parentId) {
+      if (!byParent.has(t.parentId)) byParent.set(t.parentId, []);
+      byParent.get(t.parentId).push(t);
+    } else {
+      roots.push(t);
+    }
+  }
+  return roots.map((r) => ({ ...r, children: byParent.get(r.id) || [] }));
+}
+
+function pendingSummary(adapter, channelId) {
+  const all = load(adapter, channelId);
+  return all.filter((t) => t.status === "pending" || t.status === "in_progress");
+}
+
+function statusMark(t) {
+  return t.status === "completed" ? "[x]" : t.status === "in_progress" ? "[~]" : "[ ]";
+}
+
 function format(t, idx) {
-  const mark = t.status === "completed" ? "[x]" : t.status === "in_progress" ? "[~]" : "[ ]";
   const num = typeof idx === "number" ? `${idx + 1}. ` : "";
-  return `${num}${mark} ${t.content}`;
+  return `${num}${statusMark(t)} ${t.content}`;
+}
+
+function formatTree(adapter, channelId, opts = {}) {
+  const showIds = opts.showIds !== false;
+  const t = tree(adapter, channelId);
+  const lines = [];
+  t.forEach((root, i) => {
+    const head = `${i + 1}. ${statusMark(root)} ${root.content}` + (showIds ? `    (${root.id})` : "");
+    lines.push(head);
+    if (root.description) lines.push(`      ${root.description}`);
+    root.children.forEach((child) => {
+      lines.push(`    ${statusMark(child)} ${child.content}` + (showIds ? `    (${child.id})` : ""));
+    });
+  });
+  return lines.join("\n");
 }
 
 module.exports = {
   filePathFor,
   load, save,
-  add, update, remove, list, clearCompleted,
-  format,
+  add, plan, update, remove, list, tree, clearCompleted,
+  pendingSummary,
+  format, formatTree, statusMark,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "Your always-on AI coding assistant — Claude Code, Cursor Agent, and OpenAI Codex via Telegram or Kazee Chat",
   "main": "bot.js",
   "bin": {