pi-kanban 0.2.0 → 0.3.0

package/README.md

@@ -2,10 +2,14 @@
 
 [![npm version](https://img.shields.io/npm/v/pi-kanban.svg)](https://www.npmjs.com/package/pi-kanban)
 
-Web dashboard for the [pi coding agent](https://pi.dev) — sessions, todos, subagents, observability.
+Web dashboard for the [pi coding agent](https://pi.dev/packages/pi-kanban?name=kanban) — sessions, todos, subagents, observability.
 
 ![pi-kanban dashboard](https://raw.githubusercontent.com/NikiforovAll/pi-kanban/main/assets/pi-kanban-poster.png)
 
+## Documentation
+
+**[→ See the documentation](https://nikiforovall.github.io/pi-kanban/docs/)**
+
 ## Try it now
 
 **[→ Open the live demo](https://nikiforovall.blog/pi-kanban/)**
@@ -39,8 +43,9 @@ pi install npm:@juicesharp/rpiv-todo
 
 - [`pi-subagents`](https://www.npmjs.com/package/pi-subagents) — spawns named subagent sessions; pi-kanban renders them under each parent session.
 - [`@juicesharp/rpiv-todo`](https://www.npmjs.com/package/@juicesharp/rpiv-todo) — task tracking that pi-kanban displays as kanban columns.
+- [`@juicesharp/rpiv-ask-user-question`](https://www.npmjs.com/package/@juicesharp/rpiv-ask-user-question) — pi-kanban surfaces these as interactive Q&A cards.
+
+## Demo
 
-## Documentation
 
-- [User guide](https://github.com/NikiforovAll/pi-kanban/blob/main/docs/user-guide.md) — slash commands, layout, sessions, subagents, storage manager, keyboard shortcuts.
-- [Theming](https://github.com/NikiforovAll/pi-kanban/blob/main/docs/theming.md) — built-in themes, configuration, custom theme authoring.
+![pi-kanban demo](https://raw.githubusercontent.com/NikiforovAll/pi-kanban/main/assets/pi-kanban-demo.gif)

package/lib/pi-parsers.js

@@ -35,30 +35,28 @@ function decodeProjectDir(name) {
   return s.replace(/-/g, path.sep);
 }
 
-function listSessionFiles() {
-  if (!fs.existsSync(SESSIONS_DIR)) return [];
-  const out = [];
-  for (const projDir of fs.readdirSync(SESSIONS_DIR)) {
+async function listSessionFiles() {
+  let projDirs;
+  try { projDirs = await fs.promises.readdir(SESSIONS_DIR, { withFileTypes: true }); }
+  catch { return []; }
+  const projects = projDirs.filter((d) => d.isDirectory());
+  const perProject = await Promise.all(projects.map(async (d) => {
+    const projDir = d.name;
     const projPath = path.join(SESSIONS_DIR, projDir);
-    let stat;
-    try { stat = fs.statSync(projPath); } catch { continue; }
-    if (!stat.isDirectory()) continue;
-    for (const f of fs.readdirSync(projPath)) {
-      if (!f.endsWith('.jsonl')) continue;
-      const full = path.join(projPath, f);
-      let s;
-      try { s = fs.statSync(full); } catch { continue; }
-      if (!s.isFile()) continue;
-      out.push({
-        file: full,
-        projectDir: projDir,
-        cwd: decodeProjectDir(projDir),
-        mtime: s.mtime,
-        size: s.size,
-      });
-    }
-  }
-  return out;
+    let files;
+    try { files = await fs.promises.readdir(projPath, { withFileTypes: true }); }
+    catch { return []; }
+    const jsonls = files.filter((f) => f.isFile() && f.name.endsWith('.jsonl'));
+    const stats = await Promise.all(jsonls.map(async (f) => {
+      const full = path.join(projPath, f.name);
+      try {
+        const s = await fs.promises.stat(full);
+        return { file: full, projectDir: projDir, cwd: decodeProjectDir(projDir), mtime: s.mtime, mtimeMs: s.mtimeMs, size: s.size };
+      } catch { return null; }
+    }));
+    return stats.filter(Boolean);
+  }));
+  return perProject.flat();
 }
 
 async function readJsonlLines(file) {
@@ -76,7 +74,7 @@ function parseLine(line) {
   try { return JSON.parse(line); } catch { return null; }
 }
 
-async function readSessionEntries(file) {
+async function readSessionEntriesUncached(file) {
   const lines = await readJsonlLines(file);
   const entries = [];
   for (const l of lines) {
@@ -86,6 +84,57 @@ async function readSessionEntries(file) {
   return entries;
 }
 
+// Parsed entries + summary + tool/subagent indices keyed by file path; (mtimeMs, size) is
+// the validity tag. Invalidated by chokidar events via invalidateSessionCache().
+const sessionCache = new Map();
+
+function buildToolMaps(entries) {
+  const toolResultByCallId = new Map();
+  const subagentInfoByCallId = new Map();
+  for (const e of entries) {
+    if (e.type !== 'message') continue;
+    const m = e.message;
+    if (m && m.role === 'toolResult' && m.toolCallId) {
+      toolResultByCallId.set(m.toolCallId, m);
+      if (m.toolName === 'subagent' && m.details && Array.isArray(m.details.results) && m.details.results[0]) {
+        const r = m.details.results[0];
+        subagentInfoByCallId.set(m.toolCallId, {
+          runId: m.details.runId || null,
+          agent: r.agent || null,
+          runIndex: 0,
+          outputPath: r.artifactPaths && r.artifactPaths.outputPath ? r.artifactPaths.outputPath : null,
+          inputPath: r.artifactPaths && r.artifactPaths.inputPath ? r.artifactPaths.inputPath : null,
+        });
+      }
+    }
+  }
+  return { toolResultByCallId, subagentInfoByCallId };
+}
+
+async function getCachedSession(file, knownStat = null) {
+  const mtimeMs = knownStat ? knownStat.mtimeMs : null;
+  const size = knownStat ? knownStat.size : null;
+  const cached = sessionCache.get(file);
+  if (cached && knownStat && cached.mtimeMs === mtimeMs && cached.size === size) return cached;
+  const stat = knownStat || await fs.promises.stat(file);
+  if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) return cached;
+  const entries = await readSessionEntriesUncached(file);
+  const summary = summarize(entries);
+  const { toolResultByCallId, subagentInfoByCallId } = buildToolMaps(entries);
+  const entry = { mtimeMs: stat.mtimeMs, size: stat.size, entries, summary, toolResultByCallId, subagentInfoByCallId };
+  sessionCache.set(file, entry);
+  return entry;
+}
+
+async function readSessionEntries(file) {
+  return (await getCachedSession(file)).entries;
+}
+
+function invalidateSessionCache(file) {
+  if (file) sessionCache.delete(file);
+  else sessionCache.clear();
+}
+
 // Extract concrete agent spawns from a `subagent` toolCall arguments.
 // Returns [] for management calls (action:"list" etc) so they don't pollute the agent list.
 // Single spawn: {agent, task} -> [{agent, task}]
@@ -120,6 +169,12 @@ function expandSubagentSpawns(args) {
   return [];
 }
 
+function lastMapValue(map) {
+  let v;
+  for (v of map.values());
+  return v;
+}
+
 function summarize(entries) {
   let sessionEntry = null;
   let firstModel = null;
@@ -144,6 +199,8 @@ function summarize(entries) {
   const subagentByToolCallId = new Map();
   // `${runId}_${index}` -> rec, for /run slash-invoked subagents (custom_message)
   const subagentByRunKey = new Map();
+  // toolCallId -> { timestamp } for unanswered ask_user_question calls
+  const pendingAskUsers = new Map();
 
   for (const e of entries) {
     if (e.type === 'session') sessionEntry = e;
@@ -178,7 +235,9 @@ function summarize(entries) {
           for (const c of m.content) {
             if (c && c.type === 'toolCall') {
               toolCalls++;
-              if (c.name === 'subagent') {
+              if (c.name === 'ask_user_question' && c.id) {
+                pendingAskUsers.set(c.id, { timestamp: e.timestamp || null });
+              } else if (c.name === 'subagent') {
                 const items = expandSubagentSpawns(c.arguments);
                 if (items.length) {
                   const recs = items.map((it, i) => ({
@@ -205,11 +264,25 @@ function summarize(entries) {
         }
       } else if (m.role === 'toolResult') {
         toolResults++;
-        if (m.toolName === 'todo' && m.details && Array.isArray(m.details.tasks)) {
+        if (m.toolName === 'ask_user_question' && m.toolCallId) {
+          pendingAskUsers.delete(m.toolCallId);
+        } else if (m.toolName === 'todo' && m.details && Array.isArray(m.details.tasks)) {
           lastTodoTasks = m.details.tasks;
-        } else if (m.toolName === 'subagent' && m.details && Array.isArray(m.details.results)) {
+        } else if (m.toolName === 'subagent') {
           const pendingArr = m.toolCallId ? subagentByToolCallId.get(m.toolCallId) : null;
-          m.details.results.forEach((r, idx) => {
+          const results = m.details && Array.isArray(m.details.results) ? m.details.results : null;
+          if (!results && pendingArr && pendingArr.length) {
+            // Validation/spawn-time failure: pi wrote an error toolResult with no results.
+            const errText = Array.isArray(m.content)
+              ? (m.content.find((c) => c && c.type === 'text')?.text || '')
+              : '';
+            for (const rec of pendingArr) {
+              rec.stoppedAt = e.timestamp || null;
+              rec._error = rec._error || (errText ? errText.split('\n')[0].slice(0, 200) : 'Spawn failed');
+              if (rec.exitCode == null) rec.exitCode = -1;
+            }
+          }
+          (results || []).forEach((r, idx) => {
             let target = pendingArr && pendingArr[idx];
             if (!target) {
               const base = pendingArr && pendingArr[0];
@@ -222,7 +295,7 @@ function summarize(entries) {
               };
               subagents.push(target);
             }
-            target.runId = m.details.runId || target.runId;
+            target.runId = (m.details && m.details.runId) || target.runId;
             target.runIndex = idx;
             target.agent = r.agent || target.agent;
             target.prompt = target.prompt || r.task || null;
@@ -237,7 +310,7 @@ function summarize(entries) {
               target._cancelled = true;
             }
           });
-          if (m.details.results.length === 0 && pendingArr && pendingArr.length) {
+          if (results && results.length === 0 && pendingArr && pendingArr.length) {
             const text = Array.isArray(m.content) ? (m.content.find((c) => c && c.type === 'text')?.text || '') : '';
             const cancelled = /cancel/i.test(text);
             for (const rec of pendingArr) {
@@ -322,6 +395,7 @@ function summarize(entries) {
     lastAssistantUsage,
     lastTodoTasks,
     subagents,
+    pendingAskUser: pendingAskUsers.size > 0 ? lastMapValue(pendingAskUsers) : null,
   };
 }
 
@@ -480,28 +554,35 @@ async function matchLiveSubagentRuns(meta, pending, allSubagents) {
     rec.sessionFile = lr.jsonl;
   }
 
-  let parentMtime = 0;
-  try { parentMtime = (await fs.promises.stat(meta.file)).mtimeMs; } catch {}
-  const STALE_MS = 60_000;
-  const now = Date.now();
-  const parentStale = parentMtime && (now - parentMtime > STALE_MS);
+  // Structural staleness: while a subagent is running, the parent assistant is blocked
+  // waiting on its toolResult, so the parent jsonl can't have any later message other
+  // than that toolResult. If we see a newer message that isn't this subagent's own
+  // toolResult, pi has moved on and the spawn is orphaned. Tradeoff: a real pi crash
+  // with no further parent activity stays as "active" until the user restarts pi.
+  const parentEntries = (await getCachedSession(meta.file)).entries;
   for (const rec of pending) {
     if (rec.stoppedAt) continue;
-    let runMtime = 0;
-    if (rec.sessionFile) {
-      try { runMtime = (await fs.promises.stat(rec.sessionFile)).mtimeMs; } catch {}
-    }
-    const runStale = runMtime ? (now - runMtime > STALE_MS) : true;
-    if (parentStale && runStale) {
-      rec.stoppedAt = new Date(runMtime || parentMtime || now).toISOString();
+    if (!rec.startedAt) continue;
+    const startMs = new Date(rec.startedAt).getTime();
+    if (!startMs) continue;
+    const movedOn = parentEntries.some((e) => {
+      if (e.type !== 'message') return false;
+      const t = e.timestamp ? new Date(e.timestamp).getTime() : 0;
+      if (t <= startMs) return false;
+      const m = e.message;
+      if (m && m.role === 'toolResult' && m.toolName === 'subagent'
+          && rec.toolCallId && m.toolCallId === rec.toolCallId) return false;
+      return true;
+    });
+    if (movedOn) {
+      rec.stoppedAt = new Date().toISOString();
       rec._error = rec._error || 'Interrupted (no result recorded)';
     }
   }
 }
 
-async function listAgentsForSession(meta) {
-  const entries = await readSessionEntries(meta.file);
-  const s = summarize(entries);
+async function listAgentsForSession(meta, summary = null) {
+  const s = summary || (await getCachedSession(meta.file)).summary;
   const recs = s.subagents || [];
   await enrichPendingSubagents(meta, recs);
   const out = [];
@@ -567,8 +648,8 @@ function slugFromFile(file) {
 const RECENT_MS = 5 * 60 * 1000;
 
 async function buildSessionSummary(meta) {
-  const entries = await readSessionEntries(meta.file);
-  const s = summarize(entries);
+  const cached = await getCachedSession(meta.file, meta.mtimeMs != null ? { mtimeMs: meta.mtimeMs, size: meta.size } : null);
+  const s = cached.summary;
   const id = (s.sessionEntry && s.sessionEntry.id) || slugFromFile(meta.file);
   const cwd = (s.sessionEntry && s.sessionEntry.cwd) || meta.cwd;
   const projectName = path.basename(cwd) || cwd;
@@ -586,13 +667,13 @@ async function buildSessionSummary(meta) {
     }),
     customTitle: s.customTitle || null,
     parentSession: (s.sessionEntry && s.sessionEntry.parentSession) || null,
-    ...tallyTasks(taskStore.listTasks(id)),
+    ...tallyTasks(await taskStore.listTasksAsync(id)),
     createdAt: s.sessionEntry && s.sessionEntry.timestamp,
     modifiedAt: meta.mtime.toISOString(),
     hasMessages: s.messageCount > 0,
     hasActiveAgents: false,
     hasRunningAgents: false,
-    hasWaitingForUser: false,
+    hasWaitingForUser: !!s.pendingAskUser,
     hasRecentLog: isRecent,
     jsonlPath: meta.file,
     tasksDir: null,
@@ -649,26 +730,26 @@ async function buildSessionSummary(meta) {
 }
 
 async function listSessions() {
-  const files = listSessionFiles();
+  const files = await listSessionFiles();
   files.sort((a, b) => b.mtime - a.mtime);
+  const summaries = await Promise.all(files.map(async (f) => {
+    try { return await buildSessionSummary(f); }
+    catch { return null; }
+  }));
   const out = [];
   const seen = new Set();
-  for (const f of files) {
-    try {
-      const summary = await buildSessionSummary(f);
-      if (summary.parentSession) continue;
-      if (seen.has(summary.id)) continue;
-      seen.add(summary.id);
-      out.push(summary);
-    } catch (err) {
-      // skip corrupt files
-    }
+  for (const summary of summaries) {
+    if (!summary) continue;
+    if (summary.parentSession) continue;
+    if (seen.has(summary.id)) continue;
+    seen.add(summary.id);
+    out.push(summary);
   }
   return out;
 }
 
 async function findSessionFileById(id) {
-  const files = listSessionFiles();
+  const files = await listSessionFiles();
   files.sort((a, b) => b.mtime - a.mtime);
   // First try filename match (faster)
   for (const f of files) {
@@ -726,22 +807,36 @@ function computeToolDetail(name, params) {
   }
   let detail = null;
   let full = null;
+  const trunc = (s, n = 80) => (s.length > n ? s.slice(0, n) + '...' : s);
   if (params.file_path) { detail = path.basename(params.file_path); full = params.file_path; }
   else if (params.path) { detail = path.basename(params.path); full = params.path; }
-  else if (params.command) { full = params.command; detail = full.length > 80 ? full.slice(0, 80) + '...' : full; }
+  else if (params.command) { full = params.command; detail = trunc(full); }
   else if (params.pattern) { full = params.pattern; detail = full; }
   else if (params.query) { full = params.query; detail = full; }
-  else if (params.queries) { full = Array.isArray(params.queries) ? params.queries.join(' | ') : String(params.queries); detail = full.length > 80 ? full.slice(0, 80) + '...' : full; }
-  else if (params.url) { full = params.url; detail = full.length > 80 ? full.slice(0, 80) + '...' : full; }
-  else if (params.task) { full = params.task; detail = full.length > 80 ? full.slice(0, 80) + '...' : full; }
+  else if (params.queries) { full = Array.isArray(params.queries) ? params.queries.join(' | ') : String(params.queries); detail = trunc(full); }
+  else if (params.url) { full = params.url; detail = trunc(full); }
+  else if (params.task) { full = params.task; detail = trunc(full); }
   else if (params.subject) { full = params.subject; detail = full; }
-  else if (params.description) { full = params.description; detail = full.length > 80 ? full.slice(0, 80) + '...' : full; }
-  else if (params.question) { full = params.question; detail = full.length > 80 ? full.slice(0, 80) + '...' : full; }
+  else if (params.description) { full = params.description; detail = trunc(full); }
+  else if (params.tasks && Array.isArray(params.tasks)) {
+    const agents = [...new Set(params.tasks.map((t) => t.agent).filter(Boolean))];
+    const n = params.tasks.length;
+    const agentStr = agents.length ? ` · ${agents.join(', ')}` : '';
+    detail = `${n} task${n > 1 ? 's' : ''}${agentStr}`;
+    full = detail;
+  }
+  else if (params.question) { full = params.question; detail = trunc(full); }
+  else if (params.questions && Array.isArray(params.questions)) {
+    const first = params.questions[0]?.question || '';
+    const extra = params.questions.length > 1 ? ` (+${params.questions.length - 1} more)` : '';
+    full = params.questions.map((q) => q.question).join(' | ');
+    detail = trunc(first, 60) + extra;
+  }
   else if (params.action) { detail = params.action; full = detail; }
   else if (params.operation) { detail = params.operation; full = detail; }
   else {
     try { full = JSON.stringify(params); } catch { full = ''; }
-    detail = full.length > 80 ? full.slice(0, 80) + '...' : full;
+    detail = trunc(full);
   }
   return { detail: detail || '', fullDetail: full && full !== detail ? full : null };
 }
@@ -779,26 +874,18 @@ async function readFileSafe(p) {
 }
 
 async function buildMessages(file, limit = 50, before = null) {
-  const entries = await readSessionEntries(file);
-  const toolResultByCallId = new Map();
-  const subagentInfoByCallId = new Map();
-  for (const e of entries) {
-    if (e.type !== 'message') continue;
-    const m = e.message;
-    if (m && m.role === 'toolResult' && m.toolCallId) {
-      toolResultByCallId.set(m.toolCallId, m);
-      if (m.toolName === 'subagent' && m.details && Array.isArray(m.details.results) && m.details.results[0]) {
-        const r = m.details.results[0];
-        subagentInfoByCallId.set(m.toolCallId, {
-          runId: m.details.runId || null,
-          agent: r.agent || null,
-          runIndex: 0,
-          outputPath: r.artifactPaths && r.artifactPaths.outputPath ? r.artifactPaths.outputPath : null,
-          inputPath: r.artifactPaths && r.artifactPaths.inputPath ? r.artifactPaths.inputPath : null,
-        });
-      }
-    }
+  const cached = await getCachedSession(file);
+  if (cached.allMessages) {
+    const filtered = before
+      ? cached.allMessages.filter((m) => m.timestamp && m.timestamp < before)
+      : cached.allMessages;
+    const total = filtered.length;
+    const sliced = limit && limit < total ? filtered.slice(-limit) : filtered;
+    return { messages: sliced, hasMore: sliced.length < total, sessionId: null };
   }
+  const entries = cached.entries;
+  const toolResultByCallId = cached.toolResultByCallId;
+  const subagentInfoByCallId = cached.subagentInfoByCallId;
 
   const messages = [];
   for (const e of entries) {
@@ -852,11 +939,15 @@ async function buildMessages(file, limit = 50, before = null) {
               toolResult: trText ? trText.slice(0, 1500) : null,
               toolResultTruncated: trText ? trText.length > 1500 : false,
             };
+            if (c.name === 'ask_user_question' && tr && tr.details && !tr.isError) {
+              msg.toolResultDetails = tr.details;
+            }
             if (c.name === 'subagent') {
               const info = subagentInfoByCallId.get(c.id);
               const agent = (c.arguments && c.arguments.agent) || (info && info.agent) || null;
               const runId = info && info.runId ? info.runId : null;
               const isSpawn = !!(c.arguments && c.arguments.task);
+              const isParallel = !!(c.arguments && Array.isArray(c.arguments.tasks));
               if (isSpawn) {
                 msg.tool = 'Agent';
                 msg.agentId = c.id ? `tc_${c.id}_${(info && info.runIndex) || 0}` : (runId && agent ? `${runId}_${agent}_${(info && info.runIndex) || 0}` : `pending_${Math.random().toString(36).slice(2, 10)}`);
@@ -865,6 +956,11 @@ async function buildMessages(file, limit = 50, before = null) {
                 msg.agentPrompt = c.arguments.task || null;
                 msg.agentLastMessage = info && info.outputPath ? await readFileSafe(info.outputPath) : null;
                 if (!msg.agentLastMessage && trText) msg.agentLastMessage = trText;
+              } else if (isParallel) {
+                msg.agentTasks = c.arguments.tasks;
+                if (tr && tr.details && Array.isArray(tr.details.results)) {
+                  msg.parallelResults = tr.details.results;
+                }
               }
             }
             messages.push(msg);
@@ -875,6 +971,7 @@ async function buildMessages(file, limit = 50, before = null) {
     // toolResult handled via map above.
   }
 
+  cached.allMessages = messages;
   const filtered = before
     ? messages.filter((m) => m.timestamp && m.timestamp < before)
     : messages;
@@ -898,4 +995,6 @@ module.exports = {
   findAgentRecord,
   slugFromFile,
   setOnBranchResolved,
+  flattenContentToText,
+  invalidateSessionCache,
 };

package/lib/task-store.js

@@ -24,8 +24,8 @@ function readTask(sessionId, taskId) {
   } catch { return null; }
 }
 
-function listSessionIds() {
-  try { return fs.readdirSync(TASKS_DIR); }
+async function listSessionIdsAsync() {
+  try { return await fs.promises.readdir(TASKS_DIR); }
   catch { return []; }
 }
 
@@ -45,6 +45,21 @@ function listTasks(sessionId) {
   return out;
 }
 
+async function listTasksAsync(sessionId) {
+  const dir = sessionDir(sessionId);
+  let entries;
+  try { entries = await fs.promises.readdir(dir); }
+  catch { return []; }
+  const jsons = entries.filter((n) => n.endsWith('.json'));
+  const tasks = await Promise.all(jsons.map(async (name) => {
+    try {
+      const raw = await fs.promises.readFile(path.join(dir, name), 'utf8');
+      return JSON.parse(raw);
+    } catch { return null; }
+  }));
+  return tasks.filter(Boolean);
+}
+
 function writeTask(sessionId, task) {
   const dir = sessionDir(sessionId);
   fs.mkdirSync(dir, { recursive: true });
@@ -126,8 +141,9 @@ function reconcileFromSnapshot(sessionId, snapshot) {
 module.exports = {
   getTasksDir,
   sessionDir,
-  listSessionIds,
+  listSessionIdsAsync,
   listTasks,
+  listTasksAsync,
   readTask,
   writeTask,
   deleteTask,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-kanban",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Workspace for the pi coding agent — sessions, todos, subagents, and more.",
   "main": "server.js",
   "bin": {
@@ -10,7 +10,13 @@
     "start": "node server.js",
     "dev": "node --watch server.js",
     "build:demo": "node scripts/build-demo.js",
-    "preview:demo": "npm run build:demo && npx --yes http-server dist -p 8765 -c-1"
+    "preview:demo": "npm run build:demo && npx --yes http-server dist -p 8765 -c-1",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "devDependencies": {
+    "vitepress": "^1.6.4"
   },
   "keywords": [
     "pi-package",