@gobing-ai/spur 0.3.99 → 0.4.1

package/plugins/sp/lib/transcript.ts

@@ -0,0 +1,275 @@
+/**
+ * Host-transcript measurement primitives shared by session-timeline (session review) and
+ * run-summary (dev-run / dev-runall execution summary). Reads Claude Code JSONL rows read-only;
+ * tokens are counted once per message id (a response spans several records). Node builtins only.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export type Tokens = Record<'input' | 'cacheCreate' | 'cacheRead' | 'output', number>;
+
+export interface Span {
+    workMs: number;
+    waitMs: number;
+    toolCalls: number;
+    tokens: Tokens;
+}
+
+export interface Block {
+    type?: string;
+    id?: string;
+    name?: string;
+    text?: string;
+    tool_use_id?: string;
+    /** Claude tool_result error flag (1146 R4): a failed subagent call is counted. */
+    is_error?: boolean;
+}
+
+export interface Row {
+    type?: string;
+    /** Claude `system` rows carry the compaction subtype (1146 R4). */
+    subtype?: string;
+    timestamp?: string;
+    isMeta?: boolean;
+    isCompactSummary?: boolean;
+    id?: string; // pi: the row id doubles as the once-per-message usage key
+    message?: {
+        id?: string;
+        role?: string;
+        content?: unknown;
+        usage?: Record<string, number | undefined>;
+        toolCallId?: string;
+        /** pi toolResult rows name their tool here (1146 R4). */
+        toolName?: string;
+        /** pi toolResult error flag (1146 R4). */
+        isError?: boolean;
+    };
+}
+
+/** Running measurement of one segment or window. */
+export interface Acc {
+    last: number;
+    askMs: number;
+    asks: Map<string, number>;
+    toolIds: Set<string>;
+    messages: Map<string, Tokens>;
+    compactions: number;
+}
+
+const SESSION_ID = /^[A-Za-z0-9_-]+$/;
+/** Host tools whose call→result gap is the operator answering, not the agent working. */
+const OPERATOR_TOOLS = new Set(['AskUserQuestion', 'ask_user_question']);
+const PI_ROLES = new Set(['user', 'assistant', 'toolResult']);
+
+export const zeroTokens = (): Tokens => ({ input: 0, cacheCreate: 0, cacheRead: 0, output: 0 });
+
+export function formatDuration(ms: number): string {
+    const s = Math.round(ms / 1000);
+    const h = Math.floor(s / 3600);
+    const m = Math.floor((s % 3600) / 60);
+    const ss = String(s % 60).padStart(2, '0');
+    return h > 0 ? `${h}:${String(m).padStart(2, '0')}:${ss}` : `${m}:${ss}`;
+}
+
+/** Compact token units: `950`, `41k`, `28.4M`. */
+export function formatTokens(n: number): string {
+    if (n >= 999_500) return `${(n / 1e6).toFixed(1)}M`;
+    return n >= 1000 ? `${Math.round(n / 1000)}k` : String(n);
+}
+
+/**
+ * `<total> / <non-cached>`: total = every input class + output; non-cached drops cache reads, the
+ * share re-served from the prompt cache, leaving the fresh input, cache writes and output.
+ */
+export function formatTokenSplit(t: Tokens | null): string {
+    if (!t) return 'n/a';
+    const nonCached = t.input + t.cacheCreate + t.output;
+    return `${formatTokens(nonCached + t.cacheRead)} / ${formatTokens(nonCached)}`;
+}
+
+/** Operator prompt text, or undefined for tool results, meta rows and compaction summaries. */
+export function promptText(row: Row): string | undefined {
+    if (row.type === 'message') {
+        // pi (1130): only a user-role message with text content is a prompt; toolResult rows are not.
+        if (row.message?.role !== 'user') return undefined;
+        // pi (1138 R2): a skill-injected body is activity, not an operator prompt.
+        if (isInjectedPrompt(row)) return undefined;
+        const content = row.message.content;
+        if (typeof content === 'string') return content;
+        if (!Array.isArray(content)) return undefined;
+        return (content as Block[]).find((b) => b.type === 'text')?.text;
+    }
+    if (row.type !== 'user' || row.isMeta || row.isCompactSummary) return undefined;
+    const content = row.message?.content;
+    if (typeof content === 'string') return content;
+    if (!Array.isArray(content) || (content as Block[]).some((b) => b.type === 'tool_result')) return undefined;
+    return (content as Block[]).find((b) => b.type === 'text')?.text;
+}
+
+/**
+ * 1138 R2: a pi user row whose first text block, after leading whitespace, opens with
+ * `<skill name="`, is an injected body (pi has no `isMeta` to key on). It is accumulated as
+ * activity and must not open a segment. Operator text that merely CONTAINS `<skill` later in the
+ * body is still a prompt. Claude rows are unaffected: their injected bodies already arrive as `isMeta`.
+ */
+export function isInjectedPrompt(row: Row): boolean {
+    if (row.type !== 'message' || row.message?.role !== 'user') return false;
+    const content = row.message.content;
+    const text =
+        typeof content === 'string'
+            ? content
+            : Array.isArray(content)
+              ? (content as Block[]).find((b) => b.type === 'text')?.text
+              : undefined;
+    return typeof text === 'string' && text.replace(/^\s+/, '').startsWith('<skill name="');
+}
+
+export function sumTokens(all: Tokens[]): Tokens {
+    const total = zeroTokens();
+    for (const t of all) for (const k of Object.keys(total) as (keyof Tokens)[]) total[k] += t[k];
+    return total;
+}
+
+export function sumSpans(spans: Span[]): Span {
+    return {
+        workMs: spans.reduce((n, s) => n + s.workMs, 0),
+        waitMs: spans.reduce((n, s) => n + s.waitMs, 0),
+        toolCalls: spans.reduce((n, s) => n + s.toolCalls, 0),
+        tokens: sumTokens(spans.map((s) => s.tokens)),
+    };
+}
+
+export const newAcc = (ts: number): Acc => ({
+    last: ts,
+    askMs: 0,
+    asks: new Map(),
+    toolIds: new Set(),
+    messages: new Map(),
+    compactions: 0,
+});
+
+/** Fold one timestamped non-prompt record into a segment or window. */
+export function accumulate(acc: Acc, row: Row, ts: number): void {
+    acc.last = Math.max(acc.last, ts);
+    if (row.type === 'message') {
+        // pi (1130): mirrors the importer's field semantics (piRole / normalizeOmpToolCall /
+        // ompToolResultTiming) — toolCall blocks on assistant rows, results paired by toolCallId.
+        const m = row.message;
+        if (m?.role === 'assistant') {
+            const blocks = Array.isArray(m.content) ? (m.content as Block[]) : [];
+            for (const b of blocks) {
+                if (b.type === 'toolCall' && b.id) {
+                    acc.toolIds.add(b.id);
+                    if (b.name && OPERATOR_TOOLS.has(b.name)) acc.asks.set(b.id, ts);
+                }
+            }
+            const u = m.usage;
+            if (u && row.id)
+                acc.messages.set(row.id, {
+                    input: u.input ?? 0,
+                    cacheCreate: u.cacheWrite ?? 0,
+                    cacheRead: u.cacheRead ?? 0,
+                    output: u.output ?? 0,
+                });
+        } else if (m?.role === 'toolResult' && m.toolCallId && acc.asks.has(m.toolCallId)) {
+            acc.askMs += ts - (acc.asks.get(m.toolCallId) ?? ts);
+        }
+        return;
+    }
+    if (row.type === 'compaction') acc.compactions++; // pi-only row type (1130 R4)
+    const blocks = Array.isArray(row.message?.content) ? (row.message.content as Block[]) : [];
+    for (const b of blocks) {
+        if (b.type === 'tool_use' && b.id) {
+            acc.toolIds.add(b.id);
+            if (b.name && OPERATOR_TOOLS.has(b.name)) acc.asks.set(b.id, ts);
+        } else if (b.type === 'tool_result' && b.tool_use_id && acc.asks.has(b.tool_use_id)) {
+            acc.askMs += ts - (acc.asks.get(b.tool_use_id) ?? ts);
+        }
+    }
+    const u = row.message?.usage;
+    // Split records of one response repeat its usage: keyed by message id, overwrite, never add.
+    if (row.type === 'assistant' && u && row.message?.id) {
+        acc.messages.set(row.message.id, {
+            input: u.input_tokens ?? 0,
+            cacheCreate: u.cache_creation_input_tokens ?? 0,
+            cacheRead: u.cache_read_input_tokens ?? 0,
+            output: u.output_tokens ?? 0,
+        });
+    }
+}
+
+/**
+ * 1146 R4: a compaction boundary in either host shape — pi writes a `compaction` row, Claude a
+ * `system` row with `subtype:"compact_boundary"`.
+ */
+export function isCompaction(row: Row): boolean {
+    return row.type === 'compaction' || (row.type === 'system' && row.subtype === 'compact_boundary');
+}
+
+/** First row matching a known shape decides: `type:"message"` with a pi role → pi, else Claude. */
+export function sniffFormat(rows: Row[]): 'claude' | 'pi' | 'unknown' {
+    for (const row of rows) {
+        if (row.type === 'message' && PI_ROLES.has(row.message?.role ?? '')) return 'pi';
+        if (row.type === 'user' || row.type === 'assistant') return 'claude';
+    }
+    return 'unknown';
+}
+
+/** Timestamped rows in file order; malformed lines counted, timestamp-less rows dropped. */
+export function parseRows(lines: string[]): {
+    rows: [Row, number][];
+    skippedLines: number;
+    format: 'claude' | 'pi' | 'unknown';
+} {
+    const rows: [Row, number][] = [];
+    let skippedLines = 0;
+    for (const line of lines) {
+        if (!line.trim()) continue;
+        let row: Row;
+        try {
+            row = JSON.parse(line) as Row;
+        } catch {
+            skippedLines++;
+            continue;
+        }
+        const ts = row.timestamp ? Date.parse(row.timestamp) : Number.NaN;
+        if (!Number.isNaN(ts)) rows.push([row, ts]);
+    }
+    return { rows, skippedLines, format: sniffFormat(rows.map(([r]) => r)) };
+}
+
+export type Resolved = { ok: true; path: string } | { ok: false; reason: string };
+
+export function resolveTranscript(
+    env: Record<string, string | undefined>,
+    projectsRoot = join(homedir(), '.claude', 'projects'),
+    override?: string,
+): Resolved {
+    if (override) return existsSync(override) ? { ok: true, path: override } : { ok: false, reason: 'no transcript' };
+    const id = env.CLAUDE_CODE_SESSION_ID;
+    if (!id) {
+        // 1138 R1: pi exports PI_SESSION_FILE (an exact path) and no Claude session id. Order is
+        // explicit override → Claude id → PI_SESSION_FILE; PI_SESSION_ID is never used for lookup
+        // because pi's filename embeds a timestamp, so the path is not derivable from the id.
+        const piFile = env.PI_SESSION_FILE;
+        if (piFile !== undefined && piFile !== '') {
+            return existsSync(piFile)
+                ? { ok: true, path: piFile }
+                : { ok: false, reason: `PI_SESSION_FILE ${piFile} does not exist` };
+        }
+        return {
+            ok: false,
+            reason:
+                'no host session id; pass --transcript <path> (pi: ~/.pi/agent/sessions/<cwd-slug>/<file>.jsonl, ' +
+                'or set PI_SESSION_FILE)',
+        };
+    }
+    if (!SESSION_ID.test(id)) return { ok: false, reason: 'refusing a session id with path characters' };
+    if (!existsSync(projectsRoot)) return { ok: false, reason: `no transcript root ${projectsRoot}` };
+    for (const dir of readdirSync(projectsRoot)) {
+        const path = join(projectsRoot, dir, `${id}.jsonl`);
+        if (existsSync(path)) return { ok: true, path };
+    }
+    return { ok: false, reason: `no transcript for session ${id}` };
+}

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.99",
+    "version": "0.4.1",
     "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics.",
     "extensions": {
         "pi": ["./hooks/pi/guard-extension.ts"]

package/plugins/sp/references/roles.md

@@ -62,7 +62,7 @@ roles:
     stages: [verify, review, dogfood]
   - id: planner
     tier: capable-2
-    commands: [dev-plan, dev-refine, dev-brainstorm, dev-idea, dev-runall, dev-parallel, dev-next, dev-job-resume, dev-arch, dev-refineall, dev-find-next, dev-feature-change]
+    commands: [dev-plan, dev-refine, dev-brainstorm, dev-find-way, dev-idea, dev-runall, dev-parallel, dev-next, dev-job-resume, dev-arch, dev-refineall, dev-find-next, dev-feature-change]
     stages: [plan, refine, brainstorm]
 ```
 

package/plugins/sp/scripts/batch-plan.mjs

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+// @bun
+
+// plugins/sp/scripts/batch-plan.ts
+import { readFileSync } from "fs";
+
+// plugins/sp/lib/plan-projection.generated.mjs
+function planLetter(index) {
+  if (!Number.isInteger(index) || index < 0 || index > 25) {
+    throw new Error(`plan letter out of range: ${index} (expected 0..25)`);
+  }
+  return String.fromCharCode(65 + index);
+}
+function planChild(parent, index) {
+  if (!Number.isInteger(index) || index < 0 || index > 8) {
+    throw new Error(`plan child index out of range: ${index} (expected 0..8 under ${parent})`);
+  }
+  if (parent.length !== 1 || !/[A-Z]/.test(parent)) {
+    throw new Error(`plan child parent must be a single letter: ${parent}`);
+  }
+  return `${parent}${index + 1}`;
+}
+var PREPARE_ID = "prepare";
+var REPORT_ID = "report";
+var PHASE_ID_PREFIX = "phase.";
+var TASK_ID_PREFIX = "task.";
+var WAVE_SIZE = 24;
+var TITLE_CAP = 60;
+function isStateMachine(def) {
+  return def.kind !== "transition-flow" && def.kind !== "dag";
+}
+function hasDisplay(s) {
+  return s.display !== undefined;
+}
+function resolvePhaseTitle(states, phase) {
+  for (const s of states) {
+    if (s.display?.phase === phase && s.display.phaseTitle !== undefined)
+      return s.display.phaseTitle;
+  }
+  return phase;
+}
+function childText(label, title, id) {
+  return id.startsWith("prepare.") || id.startsWith("task.") || id === PREPARE_ID || id === REPORT_ID ? `${label} ${title}` : `${label} ${title} · ${id}`;
+}
+function buildPhasedPlan(def) {
+  if (!isStateMachine(def))
+    return null;
+  const annotated = def.states.filter(hasDisplay);
+  if (annotated.length === 0)
+    return null;
+  const items = [
+    { label: "A", id: PREPARE_ID, outcome: "pending", title: "Prepare", text: "A Prepare" },
+    {
+      label: "A1",
+      id: "prepare.1",
+      outcome: "pending",
+      parent: "A",
+      title: "Quick readiness",
+      text: "A1 Quick readiness"
+    },
+    { label: "A2", id: "prepare.2", outcome: "pending", parent: "A", title: "Prepare Git", text: "A2 Prepare Git" },
+    {
+      label: "A3",
+      id: "prepare.3",
+      outcome: "pending",
+      parent: "A",
+      title: "Publish plan",
+      text: "A3 Publish plan"
+    }
+  ];
+  const phases = [];
+  for (const s of def.states) {
+    if (s.display !== undefined && !phases.includes(s.display.phase))
+      phases.push(s.display.phase);
+  }
+  for (const [phaseIndex, phase] of phases.entries()) {
+    const letter = planLetter(phaseIndex + 1);
+    const phaseTitle = resolvePhaseTitle(def.states, phase);
+    items.push({
+      label: letter,
+      id: `${PHASE_ID_PREFIX}${phase}`,
+      outcome: "pending",
+      title: phaseTitle,
+      text: `${letter} ${phaseTitle}`
+    });
+    let childIndex = 0;
+    for (const s of def.states) {
+      if (s.display?.phase !== phase || s.display.show === "on-entry")
+        continue;
+      const label = planChild(letter, childIndex++);
+      const title = s.display.title ?? s.id;
+      items.push({
+        label,
+        id: s.id,
+        outcome: "pending",
+        parent: letter,
+        title,
+        text: childText(label, title, s.id)
+      });
+    }
+  }
+  return items;
+}
+function validatePhaseTable(def) {
+  if (!isStateMachine(def))
+    return [];
+  const annotated = def.states.filter(hasDisplay);
+  if (annotated.length === 0)
+    return [];
+  const errors = [];
+  const terminals = new Set(def.terminalStates ?? []);
+  for (const s of def.states) {
+    if (s.display === undefined && !terminals.has(s.id)) {
+      errors.push(`state "${s.id}" has no display phase — every non-terminal state must declare display when any state does`);
+    }
+    if (s.display !== undefined && terminals.has(s.id)) {
+      errors.push(`terminal state "${s.id}" must not declare display`);
+    }
+  }
+  const phases = [];
+  for (const s of annotated) {
+    if (!phases.includes(s.display.phase))
+      phases.push(s.display.phase);
+  }
+  if (phases.length > 25) {
+    errors.push(`${phases.length} phases exceed the 25 plan letters (B-Z); split the workflow or drop phase rows`);
+  }
+  for (const phase of phases) {
+    const members = annotated.filter((s) => s.display.phase === phase);
+    if (members.length > 9) {
+      errors.push(`phase "${phase}" has ${members.length} states — at most 9 digit children fit under one letter`);
+    }
+    const titles = [...new Set(members.map((s) => s.display.phaseTitle).filter((t) => t !== undefined))];
+    if (titles.length > 1) {
+      errors.push(`phase "${phase}" has conflicting phaseTitle values: ${titles.map((t) => `"${t}"`).join(", ")}`);
+    }
+  }
+  return errors;
+}
+function insertOnEntry(items, stateId, def) {
+  if (!isStateMachine(def))
+    return items;
+  if (items.some((i) => i.id === stateId))
+    return items;
+  const display = def.states.find((s) => s.id === stateId)?.display;
+  if (display === undefined || (def.terminalStates ?? []).includes(stateId))
+    return items;
+  const phaseRow = items.find((i) => i.id === `${PHASE_ID_PREFIX}${display.phase}`);
+  if (phaseRow === undefined)
+    return items;
+  const children = items.filter((i) => i.parent === phaseRow.label);
+  const label = planChild(phaseRow.label, children.length);
+  const title = display.title ?? stateId;
+  const item = {
+    label,
+    id: stateId,
+    outcome: "pending",
+    parent: phaseRow.label,
+    title,
+    text: childText(label, title, stateId)
+  };
+  const last = children.at(-1) ?? phaseRow;
+  const at = items.indexOf(last) + 1;
+  return [...items.slice(0, at), item, ...items.slice(at)];
+}
+function truncateTitle(name) {
+  if (name.length <= TITLE_CAP)
+    return name;
+  return `${name.slice(0, TITLE_CAP - 1).replace(/[\uD800-\uDBFF]$/, "")}…`;
+}
+function buildBatchPlan(tasks) {
+  const waves = [];
+  for (let offset = 0;offset < tasks.length; offset += WAVE_SIZE) {
+    const items = [
+      { label: "A", id: PREPARE_ID, outcome: "pending", title: "Prepare batch", text: "A Prepare batch" },
+      {
+        label: "A1",
+        id: "prepare.1",
+        outcome: "pending",
+        parent: "A",
+        title: "Resolve and freeze task set",
+        text: "A1 Resolve and freeze task set"
+      },
+      {
+        label: "A2",
+        id: "prepare.2",
+        outcome: "pending",
+        parent: "A",
+        title: "Order by dependencies",
+        text: "A2 Order by dependencies"
+      },
+      {
+        label: "A3",
+        id: "prepare.3",
+        outcome: "pending",
+        parent: "A",
+        title: "Prepare Git",
+        text: "A3 Prepare Git"
+      },
+      {
+        label: "A4",
+        id: "prepare.4",
+        outcome: "pending",
+        parent: "A",
+        title: "Publish plan",
+        text: "A4 Publish plan"
+      }
+    ];
+    tasks.slice(offset, offset + WAVE_SIZE).forEach((task, i) => {
+      const label = planLetter(i + 1);
+      const title = `${task.wbs} ${truncateTitle(task.name)}`;
+      items.push({
+        label,
+        id: `${TASK_ID_PREFIX}${task.wbs}`,
+        outcome: "pending",
+        title,
+        text: `${label} ${title}`
+      });
+    });
+    items.push({ label: "Z", id: REPORT_ID, outcome: "pending", title: "Batch report", text: "Z Batch report" });
+    waves.push(items);
+  }
+  return waves;
+}
+function taskPhaseChildren(taskLetter, plan) {
+  if (!Array.isArray(plan))
+    return [];
+  return plan.filter((i) => i.id.startsWith(PHASE_ID_PREFIX) && i.label.length === 1).map((row, i) => {
+    const label = planChild(taskLetter, i);
+    return {
+      label,
+      id: row.id,
+      outcome: row.outcome,
+      parent: taskLetter,
+      title: row.title,
+      text: `${label} ${row.title}`
+    };
+  });
+}
+function hostStatus(outcome) {
+  if (outcome === "completed")
+    return "completed";
+  if (outcome === "active")
+    return "in_progress";
+  return "pending";
+}
+function hostText(item) {
+  const hostDecided = item.outcome === "skipped" || item.outcome === "failed" || item.outcome === "unattempted" || item.outcome === "blocked";
+  return hostDecided ? `${item.text} [${item.outcome}]` : item.text;
+}
+
+// plugins/sp/scripts/batch-plan.ts
+var BATCH_PLAN_USAGE = "usage: batch-plan.ts waves --tasks <tasks.json> | task-children --letter <A-Z> --plan <plan.json>";
+function readJsonFile(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+function isBatchTask(value) {
+  return typeof value === "object" && value !== null && typeof value.wbs === "string" && typeof value.name === "string";
+}
+function main(argv) {
+  const mode = argv[0];
+  if (mode === "waves") {
+    if (argv[1] !== "--tasks" || argv[2] === undefined) {
+      process.stderr.write(`${BATCH_PLAN_USAGE}
+`);
+      return 2;
+    }
+    let tasks;
+    try {
+      tasks = readJsonFile(argv[2]);
+    } catch (error) {
+      process.stderr.write(`batch-plan: cannot read ${argv[2]} \u2014 ${error instanceof Error ? error.message : String(error)}
+`);
+      return 1;
+    }
+    if (!Array.isArray(tasks) || !tasks.every(isBatchTask)) {
+      process.stderr.write(`batch-plan: --tasks file must be a JSON array of {wbs, name}
+`);
+      return 1;
+    }
+    process.stdout.write(`${JSON.stringify({ waves: buildBatchPlan(tasks) })}
+`);
+    return 0;
+  }
+  if (mode === "task-children") {
+    let letter = "";
+    let planPath = "";
+    for (let i = 1;i + 1 < argv.length; i += 2) {
+      if (argv[i] === "--letter")
+        letter = argv[i + 1] ?? "";
+      else if (argv[i] === "--plan")
+        planPath = argv[i + 1] ?? "";
+    }
+    if (!/^[A-Z]$/.test(letter) || planPath === "") {
+      process.stderr.write(`${BATCH_PLAN_USAGE}
+`);
+      return 2;
+    }
+    let payload;
+    try {
+      payload = readJsonFile(planPath);
+    } catch (error) {
+      process.stderr.write(`batch-plan: cannot read ${planPath} \u2014 ${error instanceof Error ? error.message : String(error)}
+`);
+      return 1;
+    }
+    const plan = Array.isArray(payload) ? payload : payload.plan;
+    if (!Array.isArray(plan)) {
+      process.stderr.write("batch-plan: --plan file must be a plan array or a todo --json payload with a `plan` field\n");
+      return 1;
+    }
+    process.stdout.write(`${JSON.stringify(taskPhaseChildren(letter, plan))}
+`);
+    return 0;
+  }
+  process.stderr.write(`${BATCH_PLAN_USAGE}
+`);
+  return 2;
+}
+{
+  process.exit(main(process.argv.slice(2)));
+}
+export {
+  validatePhaseTable,
+  taskPhaseChildren,
+  planLetter,
+  planChild,
+  main,
+  insertOnEntry,
+  hostText,
+  hostStatus,
+  buildPhasedPlan,
+  buildBatchPlan,
+  BATCH_PLAN_USAGE
+};