superwiki 0.1.2 → 0.1.4

package/skills/sw-init/assets/sw.mjs

@@ -1,5 +1,11 @@
 #!/usr/bin/env node
-// Generated by scripts/build.mjs from src/core.js and src/cli.js. Do not edit.
+// Generated by scripts/build.mjs from src/core.js, src/stats.js, src/cli.js. Do not edit.
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve as resolvePath, sep } from 'node:path';
+import { spawn } from 'node:child_process';
+import { createServer } from 'node:http';
+import { fileURLToPath } from 'node:url';
 // Superwiki core: vault model, derived task state and lint. Pure: no fs, no DOM.
 // Runs in Node (docs/.sw/sw.mjs) and inlined in the viewer, so both report the same findings.
 
@@ -115,6 +121,8 @@ export function buildVault(files) {
       deps: asList(d.deps).map(String), softDeps: asList(d.soft_deps).map(String),
       milestone: d.milestone || '', priority: d.priority == null || d.priority === '' ? null : Number(d.priority),
       started: d.started || '', finished: d.finished || '',
+      // Any value asks for a separate review before the task may be done; the value names the kind.
+      review: d.review ? String(d.review) : '',
       state: null, wave: 0, dependents: [], plan: null,
     });
   }
@@ -314,13 +322,368 @@ export function guideFor(vault, area) {
   return vault.pages.find(p => p.folder === 'wiki' && p.data.type === 'guide' && key(p.data.area ?? '') === key(area)) || null;
 }
 
+// Session statistics: what the agent session working in this project has cost so far.
+// Claude Code, Codex and Copilot CLI each keep a record of every session on disk. This finds the
+// record of the project's session and reduces it to one row per agent: the main session and each
+// subagent it started.
+
+export const STATS_TOOLS = ['claude', 'codex', 'copilot'];
+
+const MAIN = 'main';
+// Codex keeps every project's sessions in one tree; only the most recent files are opened.
+const CODEX_FILES_SCANNED = 100;
+
+// ---------- Reading records ----------
+
+// A record still being written can end in half a line; lines that do not parse are skipped.
+function jsonLines(path) {
+  const records = [];
+  for (const line of readFileSync(path, 'utf8').split('\n')) {
+    if (!line) continue;
+    try {
+      records.push(JSON.parse(line));
+    } catch {}
+  }
+  return records;
+}
+
+function jsonFile(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+const modifiedAt = path => statSync(path).mtimeMs;
+
+// The project root as typed and as resolved: tools record the working directory either way.
+function rootForms(root) {
+  const forms = new Set([root]);
+  try {
+    forms.add(realpathSync(root));
+  } catch {}
+  return [...forms];
+}
+
+const isWithin = (roots, dir) => Boolean(dir) && roots.some(root => dir === root || dir.startsWith(root + sep));
+
+// ---------- The summary being built ----------
+
+const newSession = (tool, id) => ({ tool, id, agents: [], tools: {}, note: '' });
+
+// Token fields stay null when the record does not hold them, so "unknown" never prints as 0.
+const newAgent = name => ({
+  name, model: '', steps: 0, first: null, peak: null, sent: null, cached: null, output: null, toolCalls: 0, start: null, end: null,
+});
+
+const plus = (sum, n) => (sum ?? 0) + (n || 0);
+
+// One model request. `context` is everything sent with it, `cached` the part read from the cache.
+function addStep(agent, { context, cached, output }) {
+  agent.steps++;
+  agent.first ??= context;
+  agent.peak = Math.max(agent.peak ?? 0, context);
+  agent.sent = plus(agent.sent, context);
+  agent.cached = plus(agent.cached, cached);
+  agent.output = plus(agent.output, output);
+}
+
+function addToolCall(session, agent, name) {
+  agent.toolCalls++;
+  session.tools[name] = (session.tools[name] || 0) + 1;
+}
+
+// Widens the agent's working period to include this record.
+function touch(agent, timestamp) {
+  const time = Date.parse(timestamp);
+  if (Number.isNaN(time)) return;
+  agent.start = Math.min(agent.start ?? time, time);
+  agent.end = Math.max(agent.end ?? time, time);
+}
+
+// Subagents are listed in the order they were started.
+const byStart = (a, b) => (a.start ?? 0) - (b.start ?? 0);
+
+// ---------- Claude Code ----------
+// ~/.claude/projects/<working directory, non-alphanumerics as dashes>/<session>.jsonl, and next to
+// it <session>/subagents/agent-<id>.jsonl with a .meta.json naming the agent type.
+
+const claudeHome = () => process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
+
+function claudeSessions(root) {
+  const sessions = [];
+  for (const form of rootForms(root)) {
+    const dir = join(claudeHome(), 'projects', form.replace(/[^A-Za-z0-9]/g, '-'));
+    if (!existsSync(dir)) continue;
+    for (const name of readdirSync(dir)) {
+      if (!name.endsWith('.jsonl')) continue;
+      const id = name.slice(0, -'.jsonl'.length);
+      const path = join(dir, name);
+      sessions.push({
+        tool: 'claude',
+        id,
+        modified: modifiedAt(path),
+        current: id === process.env.CLAUDE_CODE_SESSION_ID,
+        read: () => readClaude(id, path, join(dir, id, 'subagents')),
+      });
+    }
+  }
+  return sessions;
+}
+
+function readClaudeAgent(session, name, path) {
+  const agent = newAgent(name);
+  // A reply is written as one line per content block. Each line repeats the reply's usage, and
+  // only the last one has the final output count, so the last line of a reply is the one kept.
+  const replies = new Map();
+  for (const record of jsonLines(path)) {
+    touch(agent, record.timestamp);
+    const message = record.type === 'assistant' && record.message;
+    if (!message) continue;
+    for (const block of message.content || []) {
+      if (block.type === 'tool_use') addToolCall(session, agent, block.name);
+    }
+    if (message.usage) replies.set(message.id, message);
+  }
+  for (const { model, usage } of replies.values()) {
+    agent.model = model || agent.model;
+    const cached = usage.cache_read_input_tokens || 0;
+    addStep(agent, {
+      context: (usage.input_tokens || 0) + cached + (usage.cache_creation_input_tokens || 0),
+      cached,
+      output: usage.output_tokens,
+    });
+  }
+  return agent;
+}
+
+function readClaude(id, path, subagentDir) {
+  const session = newSession('claude', id);
+  session.agents.push(readClaudeAgent(session, MAIN, path));
+  if (!existsSync(subagentDir)) return session;
+  const subagents = readdirSync(subagentDir)
+    .filter(name => name.endsWith('.jsonl'))
+    .map(name => {
+      const meta = jsonFile(join(subagentDir, name.replace(/\.jsonl$/, '.meta.json')));
+      return readClaudeAgent(session, meta.agentType || 'subagent', join(subagentDir, name));
+    });
+  session.agents.push(...subagents.sort(byStart));
+  return session;
+}
+
+// ---------- Codex ----------
+// ~/.codex/sessions/<year>/<month>/<day>/rollout-*.jsonl. The first line is the session's meta:
+// its working directory and, for a subagent, the session that spawned it and its role.
+
+const codexHome = () => process.env.CODEX_HOME || join(homedir(), '.codex');
+
+function rolloutFiles(dir, found = []) {
+  if (!existsSync(dir)) return found;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) rolloutFiles(path, found);
+    else if (entry.name.endsWith('.jsonl')) found.push({ path, modified: modifiedAt(path) });
+  }
+  return found;
+}
+
+function codexSessions(root) {
+  const roots = rootForms(root);
+  const recent = rolloutFiles(join(codexHome(), 'sessions')).sort((a, b) => b.modified - a.modified).slice(0, CODEX_FILES_SCANNED);
+  const byId = new Map();
+  for (const { path, modified } of recent) {
+    const records = jsonLines(path);
+    const meta = records[0]?.type === 'session_meta' ? records[0].payload : null;
+    if (!meta || !isWithin(roots, meta.cwd)) continue;
+    const id = meta.session_id || meta.id;
+    if (!byId.has(id)) byId.set(id, { modified: 0, files: [] });
+    const group = byId.get(id);
+    group.modified = Math.max(group.modified, modified);
+    group.files.push({ meta, records });
+  }
+  return [...byId].map(([id, { modified, files }]) => ({ tool: 'codex', id, modified, current: false, read: () => readCodex(id, files) }));
+}
+
+function readCodexAgent(session, name, records) {
+  const agent = newAgent(name);
+  let lastTotal = null;
+  for (const record of records) {
+    touch(agent, record.timestamp);
+    const payload = record.payload || {};
+    if (record.type === 'turn_context') agent.model = payload.model || agent.model;
+    if (record.type === 'response_item' && /_call$/.test(payload.type || '')) addToolCall(session, agent, payload.name || payload.type);
+    if (record.type !== 'event_msg' || payload.type !== 'token_count' || !payload.info) continue;
+    // The count is also repeated when only the rate limits change; a new request moves the total.
+    const total = payload.info.total_token_usage?.total_tokens;
+    if (total === lastTotal) continue;
+    lastTotal = total;
+    const last = payload.info.last_token_usage || {};
+    addStep(agent, { context: last.input_tokens || 0, cached: last.cached_input_tokens, output: last.output_tokens });
+  }
+  return agent;
+}
+
+function readCodex(id, files) {
+  const session = newSession('codex', id);
+  const subagents = [];
+  for (const { meta, records } of files) {
+    if (meta.thread_source === 'subagent') subagents.push(readCodexAgent(session, meta.agent_role || meta.agent_nickname || 'subagent', records));
+    else session.agents.push(readCodexAgent(session, MAIN, records));
+  }
+  session.agents.push(...subagents.sort(byStart));
+  return session;
+}
+
+// ---------- Copilot CLI ----------
+// ~/.copilot/session-state/<session>/events.jsonl, with the working directory in workspace.yaml.
+// Events of a subagent carry its agentId. Token counts are written only when the session closes.
+
+const copilotHome = () => join(homedir(), '.copilot');
+
+function copilotSessions(root) {
+  const roots = rootForms(root);
+  const base = join(copilotHome(), 'session-state');
+  if (!existsSync(base)) return [];
+  const sessions = [];
+  for (const id of readdirSync(base)) {
+    const events = join(base, id, 'events.jsonl');
+    const workspace = join(base, id, 'workspace.yaml');
+    if (!existsSync(events) || !existsSync(workspace)) continue;
+    const cwd = (readFileSync(workspace, 'utf8').match(/^cwd: (.*)$/m) || [])[1];
+    if (!isWithin(roots, cwd)) continue;
+    sessions.push({ tool: 'copilot', id, modified: modifiedAt(events), current: false, read: () => readCopilot(id, events) });
+  }
+  return sessions;
+}
+
+function readCopilot(id, path) {
+  const session = newSession('copilot', id);
+  const agents = new Map();
+  const agentOf = key => {
+    if (!agents.has(key)) agents.set(key, newAgent(key));
+    return agents.get(key);
+  };
+  agentOf(MAIN);
+  let closed = false;
+  for (const event of jsonLines(path)) {
+    const data = event.data || {};
+    const agent = agentOf(event.agentId || MAIN);
+    touch(agent, event.timestamp);
+    if (event.type === 'subagent.started') {
+      agent.name = data.agentName || agent.name;
+    } else if (event.type === 'assistant.message') {
+      agent.steps++;
+      agent.model = data.model || agent.model;
+    } else if (event.type === 'tool.execution_start') {
+      addToolCall(session, agent, data.toolName);
+    } else if (event.type === 'session.shutdown' && data.agentMetrics) {
+      // A resumed session closes more than once; each close reports the run that ended with it.
+      closed = true;
+      for (const [key, metrics] of Object.entries(data.agentMetrics)) {
+        const reported = agentOf(key);
+        for (const { usage = {} } of Object.values(metrics.modelMetrics || {})) {
+          reported.sent = plus(reported.sent, usage.inputTokens);
+          reported.cached = plus(reported.cached, usage.cacheReadTokens);
+          reported.output = plus(reported.output, usage.outputTokens);
+        }
+      }
+    }
+  }
+  session.agents = [...agents.values()];
+  if (!closed) session.note = 'Copilot writes token counts when the session closes; until then /usage shows them.';
+  return session;
+}
+
+// ---------- Choosing the session ----------
+
+const LISTERS = { claude: claudeSessions, codex: codexSessions, copilot: copilotSessions };
+
+// The session to report: the one named by `id` (a prefix is enough), else the session this command
+// runs in when the tool says which one that is, else the most recently written one.
+export function sessionStats(root, { tool, id } = {}) {
+  let sessions = (tool ? [tool] : STATS_TOOLS).flatMap(name => LISTERS[name](root));
+  if (id) sessions = sessions.filter(session => session.id.startsWith(id));
+  sessions.sort((a, b) => b.modified - a.modified);
+  const chosen = (!id && sessions.find(session => session.current)) || sessions[0];
+  return chosen ? chosen.read() : null;
+}
+
+// ---------- Printing ----------
+
+const COLUMNS = ['agent', 'model', 'steps', 'first', 'peak', 'sent', 'cached', 'output', 'tools', 'min'];
+const TEXT_COLUMNS = 2; // agent and model align left; the numbers after them align right
+const LEGEND = 'first, peak: tokens sent with one request. sent: that, summed over every step. cached: the share of sent read from the cache.';
+
+function tokens(n) {
+  if (n == null) return '-';
+  if (n < 1000) return String(n);
+  if (n < 1e6) return `${Math.round(n / 1000)}k`;
+  return `${(n / 1e6).toFixed(1)}M`;
+}
+
+const cachedShare = agent => (agent.sent ? `${Math.round((100 * (agent.cached || 0)) / agent.sent)}%` : '-');
+const minutes = (start, end) => Math.round((end - start) / 60000);
+
+function clock(time) {
+  const d = new Date(time);
+  const two = n => String(n).padStart(2, '0');
+  return `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())} ${two(d.getHours())}:${two(d.getMinutes())}`;
+}
+
+// "2026-10-05 10:27 to 11:04, 37 min"; the end repeats the date only when it is another day.
+function period(start, end) {
+  const [from, to] = [clock(start), clock(end)];
+  const sameDay = from.slice(0, 10) === to.slice(0, 10);
+  return `${from} to ${sameDay ? to.slice(11) : to}, ${minutes(start, end)} min`;
+}
+
+function sessionPeriod(agents) {
+  const timed = agents.filter(agent => agent.start != null);
+  if (!timed.length) return '';
+  return period(Math.min(...timed.map(agent => agent.start)), Math.max(...timed.map(agent => agent.end)));
+}
+
+// The sum of the agents. It has no context of its own and no period, so those cells stay empty.
+function totalOf(agents) {
+  const total = newAgent('total');
+  for (const agent of agents) {
+    total.steps += agent.steps;
+    total.toolCalls += agent.toolCalls;
+    for (const field of ['sent', 'cached', 'output']) {
+      if (agent[field] != null) total[field] = plus(total[field], agent[field]);
+    }
+  }
+  return total;
+}
+
+const cells = agent => [
+  agent.name, agent.model, String(agent.steps), tokens(agent.first), tokens(agent.peak), tokens(agent.sent), cachedShare(agent),
+  tokens(agent.output), String(agent.toolCalls), agent.start == null ? '' : String(minutes(agent.start, agent.end)),
+];
+
+function table(rows) {
+  const widths = COLUMNS.map((_, column) => Math.max(...rows.map(row => row[column].length)));
+  const pad = (cell, column) => (column < TEXT_COLUMNS ? cell.padEnd(widths[column]) : cell.padStart(widths[column]));
+  return rows.map(row => row.map(pad).join('  ').trimEnd());
+}
+
+export function formatStats(session) {
+  const { agents } = session;
+  const rows = [COLUMNS, ...agents.map(cells)];
+  if (agents.length > 1) rows.push(cells(totalOf(agents)));
+  const calls = Object.entries(session.tools).sort((a, b) => b[1] - a[1]).map(([name, count]) => `${name} ${count}`);
+  return [
+    ['session', session.tool, session.id, sessionPeriod(agents)].filter(Boolean).join('  '),
+    ...table(rows),
+    `tool calls  ${calls.join('  ') || 'none'}`,
+    LEGEND,
+    ...(session.note ? [session.note] : []),
+  ].join('\n');
+}
+
 // Superwiki CLI. Lives in a project at docs/.sw/sw.mjs and prints short answers,
 // so agents do not have to read the vault to get them.
-import { spawn } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync } from 'node:fs';
-import { createServer } from 'node:http';
-import { basename, dirname, join, resolve as resolvePath } from 'node:path';
-import { fileURLToPath } from 'node:url';
 
 const HELP = `sw <command> [--docs <dir>] [--json]
 
@@ -331,6 +694,8 @@ const HELP = `sw <command> [--docs <dir>] [--json]
   search <words>  pages and log entries that mention the words, best match first
   next-id <AREA>  next free task id for an area (numbers are never reused)
   lint            structural checks; exit code 1 on errors
+  stats           what the agent session here has cost so far: steps, context and tokens per agent
+                  [--session <id>] another session of this project  [--tool ${STATS_TOOLS.join('|')}]
   serve [--open]  start (or reuse) a local viewer at http://127.0.0.1:<port>/ that reads the files live
   snapshot        write docs/.sw/data.js so docs/viewer.html opens as a file, frozen at this moment`;
 
@@ -392,8 +757,8 @@ export function vaultData(docs) {
 export const dataScript = data => `window.SW_DATA = ${JSON.stringify(data).replace(/</g, '\\u003c')};\n`;
 
 // ---------- Commands ----------
-// Each command gets { docs, vault, args, flags } and returns { data, text, code? }.
-// `data` is what --json prints; `text` is the default output.
+// Each command gets { docs, vault, args, flags } and returns { data, text, code? } or
+// { error, code? }. `data` is what --json prints; `text` is the default output.
 
 function status({ vault }) {
   const s = summary(vault);
@@ -436,12 +801,13 @@ function check(ctx) {
     : `can start: n/a, status is ${t.status}${openDeps}`;
   const draft = t.plan?.data.status === 'draft' ? '  (draft, not approved)' : '';
   return {
-    data: { id: t.id, status: t.status, canStart, canFinish, openDeps: t.openDeps, openSoftDeps, plan },
+    data: { id: t.id, status: t.status, canStart, canFinish, openDeps: t.openDeps, openSoftDeps, plan, review: t.review || null },
     text: [
       `${t.id}  ${t.status}  ${t.title}`,
       startLine,
       `can finish: ${canFinish ? 'yes' : 'no'}${openSoftDeps.length ? `  open soft deps: ${openSoftDeps.join(', ')}` : ''}`,
       `plan: ${plan ? plan + draft : 'none'}`,
+      `review: ${t.review ? `required (${t.review})` : 'not required'}`,
     ].join('\n'),
   };
 }
@@ -466,6 +832,7 @@ function explain(ctx) {
     t.priority != null && `priority: ${t.priority}`,
     t.started && `started: ${t.started}`,
     t.finished && `finished: ${t.finished}`,
+    t.review && `review: ${t.review}`,
   ].filter(Boolean);
   return {
     data: {
@@ -553,6 +920,17 @@ function lintCommand({ vault }) {
   };
 }
 
+// Agent sessions are recorded by the folder they ran in: the project root, which holds docs/.
+function stats({ docs, flags }) {
+  if (flags.tool && !STATS_TOOLS.includes(flags.tool)) {
+    return { error: `usage: sw stats [--session <id>] [--tool ${STATS_TOOLS.join('|')}]` };
+  }
+  const root = dirname(docs);
+  const session = sessionStats(root, { tool: flags.tool, id: flags.session });
+  if (!session) return { error: `no ${flags.tool || 'agent'} session record found for ${root}`, code: 1 };
+  return { data: session, text: formatStats(session) };
+}
+
 function snapshot({ docs }) {
   const data = vaultData(docs);
   mkdirSync(join(docs, '.sw'), { recursive: true });
@@ -660,20 +1038,24 @@ const COMMANDS = {
   search: { run: searchCommand, needsVault: true },
   'next-id': { run: nextIdCommand, needsVault: true },
   lint: { run: lintCommand, needsVault: true },
+  stats: { run: stats, needsVault: false },
   snapshot: { run: snapshot, needsVault: false },
   serve: { run: serve, needsVault: false },
 };
 
+// Flags that are on or off, and flags that take the next argument as their value.
+const SWITCHES = ['json', 'open', 'foreground'];
+const OPTIONS = ['docs', 'tool', 'session'];
+
+// Anything that is not a known flag is positional, so search words may start with dashes.
 function parseArgs(argv) {
-  const flags = { json: false, open: false, foreground: false, docs: null };
+  const flags = Object.fromEntries([...SWITCHES.map(name => [name, false]), ...OPTIONS.map(name => [name, null])]);
   const positional = [];
   for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === '--docs') flags.docs = argv[++i] || '.';
-    else if (arg === '--json') flags.json = true;
-    else if (arg === '--open') flags.open = true;
-    else if (arg === '--foreground') flags.foreground = true;
-    else positional.push(arg);
+    const name = argv[i].startsWith('--') ? argv[i].slice(2) : null;
+    if (SWITCHES.includes(name)) flags[name] = true;
+    else if (OPTIONS.includes(name)) flags[name] = argv[++i] ?? null;
+    else positional.push(argv[i]);
   }
   return { command: positional[0], args: positional.slice(1), flags };
 }

package/skills/sw-init/assets/templates/task.md

@@ -7,6 +7,7 @@ deps: []
 soft_deps: []
 milestone:
 priority:
+review:
 started:
 finished:
 ---
@@ -29,5 +30,8 @@ What exists when this is done, and why it matters.
 id: from `node docs/.sw/sw.mjs next-id <AREA>`; the file is docs/tasks/<id>.md.
 status: todo | in-progress | done | cancelled. Cancelled tasks stay; ids are never reused.
 deps: must be done before this starts. soft_deps: may start, cannot finish before them.
-Steps go in docs/plans/<id>-plan.md, not here. Delete this comment.
+review: leave empty for no separate review. Any value (for example `required`, or the name of
+the project's review class) makes sw-implement run a reviewer before the task can be done.
+Keep this file short: steps go in docs/plans/<id>-plan.md, what happened goes in docs/log.md.
+Delete this comment.
 -->

package/skills/sw-init/assets/viewer.html

@@ -494,6 +494,8 @@ function buildVault(files) {
       deps: asList(d.deps).map(String), softDeps: asList(d.soft_deps).map(String),
       milestone: d.milestone || '', priority: d.priority == null || d.priority === '' ? null : Number(d.priority),
       started: d.started || '', finished: d.finished || '',
+      // Any value asks for a separate review before the task may be done; the value names the kind.
+      review: d.review ? String(d.review) : '',
       state: null, wave: 0, dependents: [], plan: null,
     });
   }