@north-light/crouter 0.3.154

package/dist/core/canvas/render-source.js

@@ -0,0 +1,457 @@
+// render-source.ts — the openDb-FREE half of canvas rendering.
+//
+// Every `*FromSource` variant + the pure/disk helpers they share live here so a
+// CLI process rendering the canvas through a `CanvasSource` (the API-backed
+// `ApiCanvasSource`, or a `RemoteCanvasSource`) NEVER drags in `core/canvas/db.ts`
+// (`openDb`) or the `core/canvas/canvas.ts` accessors. The sync, db-backed
+// renderers (`renderTree`/`dashboardRows`/…) stay in `render.ts`, which imports the
+// shared helpers FROM here and re-exports this whole module (`export *`) so its
+// existing importers are unaffected.
+//
+// ALLOWED imports (verified openDb-free): node:fs/path, ./pid.js, ./labels.js,
+// ./status-glyph.js, ../runtime/fault.js, ./paths.js, ./remote-canvas-source.js,
+// and TYPE-ONLY ./source.js + ./types.js. Do NOT import ./canvas.js, ./attention.js,
+// ./focuses.js, or ./db.js here — that is the whole point of the split.
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { RemoteCanvasSource } from './remote-canvas-source.js';
+import { fullName } from './labels.js';
+import { jobDir, contextDir } from './paths.js';
+import { isPidAlive } from './pid.js';
+import { resolveNodeVisual, faultSummary } from './status-glyph.js';
+import { readFault } from '../runtime/fault.js';
+// ---------------------------------------------------------------------------
+// Active-fault overlay: stale daemon-owned provider faults are hidden once the
+// broker pid is gone; manual/client faults stay visible until cleared.
+// ---------------------------------------------------------------------------
+export function activeFaultForDisplay(node, fault) {
+    if (fault === null)
+        return null;
+    if (fault.link === 'pi→provider' && fault.retry.by === 'daemon' && fault.retry.disposition === 'auto' && !isPidAlive(node.pi_pid))
+        return null;
+    return fault;
+}
+export function hangingFor(node) {
+    return activeFaultForDisplay(node, readFault(node.node_id));
+}
+export function readNodeTelemetry(nodeId) {
+    const path = join(jobDir(nodeId), 'telemetry.json');
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/** Format a token count as `Nk` (rounded down to nearest 1 k). */
+export function fmtCtx(tokensIn) {
+    if (tokensIn === undefined || tokensIn === 0)
+        return '0k';
+    return `${Math.floor(tokensIn / 1000)}k`;
+}
+// ---------------------------------------------------------------------------
+// Source-driven tree builder (openDb-free)
+//
+// Ticket counts are threaded in as a `Record<node_id, count>` fetched ONCE per
+// render via `source.ticketCountsForView(root)` (the API/remote source's
+// attention projection) — never `countTickets()` (openDb). `ctx`/`hanging` are
+// LOCAL disk reads (telemetry.json / fault.json), valid for a same-host source
+// but meaningless for a truly remote canvas, so both are suppressed when the
+// source is a `RemoteCanvasSource`.
+// ---------------------------------------------------------------------------
+async function nodeLineFromSource(source, nodeId, indent, connector, remote, tickets) {
+    const node = await source.getNode(nodeId);
+    if (node === null)
+        return `${indent}${connector}? <missing meta: ${nodeId}>`;
+    const hanging = remote ? null : hangingFor(node);
+    const glyph = resolveNodeVisual(node.status, { hanging }).glyph;
+    const ctx = remote ? '0k' : fmtCtx(readNodeTelemetry(nodeId).tokens_in);
+    const asks = tickets[nodeId] ?? 0;
+    const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
+    const faultSuffix = hanging !== null ? ` · ${faultSummary(hanging)}` : '';
+    return `${indent}${connector}${glyph} ${fullName(node)} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}${faultSuffix}`;
+}
+async function walkTreeFromSource(source, nodeId, indent, isLast, visited, out, remote, tickets) {
+    if (visited.has(nodeId))
+        return;
+    visited.add(nodeId);
+    const connector = isLast ? '└─ ' : '├─ ';
+    out.push(await nodeLineFromSource(source, nodeId, indent, connector, remote, tickets));
+    const children = await source.subscriptionsOf(nodeId).catch(() => []);
+    const childIndent = indent + (isLast ? '   ' : '│  ');
+    for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        const childIsLast = i === children.length - 1;
+        if (visited.has(child.node_id)) {
+            const cycleConnector = childIsLast ? '└─ ' : '├─ ';
+            out.push(`${childIndent}${cycleConnector}↺ <cycle: ${child.node_id}>`);
+            continue;
+        }
+        await walkTreeFromSource(source, child.node_id, childIndent, childIsLast, visited, out, remote, tickets);
+    }
+}
+export async function renderTreeFromSource(source, rootId) {
+    const remote = source instanceof RemoteCanvasSource;
+    const node = await source.getNode(rootId);
+    if (node === null)
+        return `? <missing node: ${rootId}>`;
+    const tickets = await source.ticketCountsForView(rootId).catch(() => ({}));
+    const ctx = remote ? '0k' : fmtCtx(readNodeTelemetry(rootId).tokens_in);
+    const asks = tickets[rootId] ?? 0;
+    const askSuffix = asks > 0 ? ` ⚑${asks}` : '';
+    const hanging = remote ? null : hangingFor(node);
+    const glyph = resolveNodeVisual(node.status, { hanging }).glyph;
+    const faultSuffix = hanging !== null ? ` · ${faultSummary(hanging)}` : '';
+    const out = [];
+    out.push(`${glyph} ${fullName(node)} [${node.kind}/${node.mode}] ctx ${ctx}${askSuffix}${faultSuffix}`);
+    const visited = new Set([rootId]);
+    const children = await source.subscriptionsOf(rootId).catch(() => []);
+    for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        const isLast = i === children.length - 1;
+        await walkTreeFromSource(source, child.node_id, '', isLast, visited, out, remote, tickets);
+    }
+    return out.join('\n');
+}
+export async function renderForestFromSource(source) {
+    const all = await source.listNodes();
+    if (all.length === 0)
+        return '(canvas is empty)';
+    const roots = all.filter((n) => n.parent === null && (n.status === 'active' || n.status === 'idle'));
+    if (roots.length === 0)
+        return '(no live roots)';
+    const parts = [];
+    for (const r of roots) {
+        parts.push(await renderTreeFromSource(source, r.node_id));
+    }
+    return parts.join('\n\n');
+}
+/** The spawn prompt, read straight off disk (canvas-home state) and capped so a
+ *  giant initial-prompt.md can't bloat the snapshot. Mirrors how telemetry is
+ *  read here directly rather than via the runtime layer (which would invert the
+ *  canvas→runtime dependency). Never throws. */
+const GOAL_CAP = 4096;
+export function readGoalText(nodeId) {
+    try {
+        const p = join(contextDir(nodeId), 'initial-prompt.md');
+        if (!existsSync(p))
+            return undefined;
+        const body = readFileSync(p, 'utf8').trim();
+        if (body === '')
+            return undefined;
+        return body.length > GOAL_CAP ? body.slice(0, GOAL_CAP) : body;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The node's session-derived preview text in ONE file read (today's two reads,
+ *  folded): EVERY user prompt across the pi session (`prompts` — the whole
+ *  conversation, not just the spawn prompt) AND the LAST assistant message text
+ *  (`lastAssistant`). The single jsonl read is split once; a forward pass collects
+ *  user prompts (prefiltering to user-role lines so the big assistant/toolResult
+ *  lines are never JSON-parsed) and a backward pass finds the newest assistant
+ *  reply with text content (tool-only replies skipped). Both are capped per-message
+ *  + total so a long session can't bloat the snapshot. Never throws; returns an
+ *  empty object when there is no session file yet (a node that was never revived). */
+const CONVO_CAP = 8192;
+const CONVO_MSG_CAP = 2048;
+export function readSessionParts(sessionFile) {
+    if (sessionFile === undefined || sessionFile === null || sessionFile === '')
+        return {};
+    let lines;
+    try {
+        if (!existsSync(sessionFile))
+            return {};
+        lines = readFileSync(sessionFile, 'utf8').split('\n');
+    }
+    catch {
+        return {};
+    }
+    // Forward pass: every user prompt, joined + capped.
+    const parts = [];
+    let total = 0;
+    for (const line of lines) {
+        // Cheap prefilter: skip every line that isn't a user-role message before the
+        // (relatively costly) JSON.parse. Pi writes compact JSON (no spaces), but
+        // tolerate the spaced form too.
+        if (line === '' || (line.indexOf('"role":"user"') === -1 && line.indexOf('"role": "user"') === -1))
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (rec.type !== 'message' || rec.message?.role !== 'user')
+            continue;
+        const text = extractUserText(rec.message.content);
+        if (text === '')
+            continue;
+        const capped = text.length > CONVO_MSG_CAP ? text.slice(0, CONVO_MSG_CAP) : text;
+        parts.push(capped);
+        total += capped.length + 1;
+        if (total >= CONVO_CAP)
+            break;
+    }
+    let prompts;
+    if (parts.length > 0) {
+        const joined = parts.join('\n');
+        prompts = joined.length > CONVO_CAP ? joined.slice(0, CONVO_CAP) : joined;
+    }
+    // Backward pass: the newest assistant message carrying text.
+    let lastAssistant;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (line === '' || (line.indexOf('"role":"assistant"') === -1 && line.indexOf('"role": "assistant"') === -1))
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (rec.type !== 'message' || rec.message?.role !== 'assistant')
+            continue;
+        const text = extractUserText(rec.message.content);
+        if (text === '')
+            continue;
+        lastAssistant = text.length > CONVO_MSG_CAP ? text.slice(0, CONVO_MSG_CAP) : text;
+        break;
+    }
+    return { prompts, lastAssistant };
+}
+/** Did this node's engine ever PRODUCE something — an assistant message with real
+ *  text, a tool call, or non-empty reasoning? The signal that a node did work and
+ *  is not an empty shell. A never-revived node (no session file) is trivially
+ *  false; an assistant turn that is only an empty/aborted `thinking` stub does NOT
+ *  count (that's a node started and killed before it did anything). CONSERVATIVE
+ *  by design: ANY substance keeps the node, so the reap never deletes real work
+ *  — a tool-call-only turn (no final text) still counts. Drives reap-on-close/
+ *  detach. One file read with an early exit on the first substantive turn. */
+export function nodeHasAssistantMessage(sessionFile) {
+    if (sessionFile === undefined || sessionFile === null || sessionFile === '')
+        return false;
+    let lines;
+    try {
+        if (!existsSync(sessionFile))
+            return false;
+        lines = readFileSync(sessionFile, 'utf8').split('\n');
+    }
+    catch {
+        return false;
+    }
+    for (const line of lines) {
+        if (line === '' || (line.indexOf('"role":"assistant"') === -1 && line.indexOf('"role": "assistant"') === -1))
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (rec.type !== 'message' || rec.message?.role !== 'assistant')
+            continue;
+        if (assistantContentIsSubstantive(rec.message.content))
+            return true;
+    }
+    return false;
+}
+/** True when an assistant message's content has at least one block that PRODUCED
+ *  something: non-empty text, non-empty thinking, a tool call (`toolCall`/
+ *  `tool_use`/…), or any other non-thinking/text block type. The lone non-case is
+ *  an empty thinking stub (`[{type:'thinking',thinking:''}]`) or empty content —
+ *  what an immediately-aborted first turn leaves behind. */
+function assistantContentIsSubstantive(content) {
+    if (typeof content === 'string')
+        return content.trim() !== '';
+    if (!Array.isArray(content))
+        return false;
+    for (const block of content) {
+        if (block === null || typeof block !== 'object')
+            continue;
+        const b = block;
+        const t = (b.type ?? '').toLowerCase();
+        if (t === 'text') {
+            if (typeof b.text === 'string' && b.text.trim() !== '')
+                return true;
+        }
+        else if (t === 'thinking') {
+            if (typeof b.thinking === 'string' && b.thinking.trim() !== '')
+                return true;
+        }
+        else
+            return true; // toolCall / tool_use / toolResult / any other block = real output
+    }
+    return false;
+}
+/** Is the node GENUINELY mid-turn right now? The `busy` marker (touched on
+ *  agent_start, removed on agent_end) AND-ed with broker-pid liveness, so a stale
+ *  marker from a crashed pi reads false. This is the live "generating?" signal
+ *  — distinct from `status: 'active'`, which only means the engine never closed
+ *  (an active node is usually dormant between turns). Read directly off disk
+ *  (mirrors telemetry) to avoid inverting the canvas→runtime dependency. */
+export function isStreaming(nodeId, piPid) {
+    if (!isPidAlive(piPid))
+        return false;
+    try {
+        return existsSync(join(jobDir(nodeId), 'busy'));
+    }
+    catch {
+        return false;
+    }
+}
+/** Concatenate the `text` blocks of one pi user message's content. Content is
+ *  usually an array of `{type,text}` blocks but may be a bare string. */
+function extractUserText(content) {
+    if (typeof content === 'string')
+        return content.trim();
+    if (!Array.isArray(content))
+        return '';
+    const out = [];
+    for (const block of content) {
+        if (block !== null && typeof block === 'object') {
+            const b = block;
+            if (b.type === 'text' && typeof b.text === 'string')
+                out.push(b.text);
+        }
+    }
+    return out.join(' ').trim();
+}
+/** "Most recent activity" sort key (epoch ms) read CHEAPLY: a `statSync` (no file
+ *  read, no parse) of the node's job/telemetry.json — rewritten on every turn_end at
+ *  a deterministic canvas-home path, so it tracks last-message recency without a meta
+ *  read. Falls back to `created`'s epoch when a node never ran a turn (no telemetry).
+ *  Never throws. */
+export function sessionMtime(nodeId, created, remote = false) {
+    if (!remote) {
+        try {
+            const st = statSync(join(jobDir(nodeId), 'telemetry.json'), { throwIfNoEntry: false });
+            if (st !== undefined)
+                return st.mtimeMs;
+        }
+        catch {
+            /* fall through to created */
+        }
+    }
+    const t = Date.parse(created);
+    return Number.isNaN(t) ? 0 : t;
+}
+function hasLiveBrokerViewer(row) {
+    if (row.status !== 'active')
+        return false; // a crashed broker can leave stale attach.json
+    try {
+        const record = JSON.parse(readFileSync(join(jobDir(row.node_id), 'attach.json'), 'utf8'));
+        return typeof record.viewers === 'number' && record.viewers > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Build one cheap-boot row from a raw db/source row. `remote` suppresses the
+ *  LOCAL disk reads (fault/streaming/telemetry-mtime/viewers) that are meaningless
+ *  for a truly remote canvas. A local row is viewed when either its tmux focus
+ *  row exists or its live broker reports a terminal/web viewer. */
+export function dashboardRowFromNodeRow(row, focusedNodeIds, remote) {
+    const live = row.status === 'active' || row.status === 'idle';
+    const hanging = remote ? null : activeFaultForDisplay(row, readFault(row.node_id));
+    return {
+        node_id: row.node_id,
+        name: row.name, // handle only; enrichRow upgrades to fullName (meta.description)
+        status: row.status,
+        kind: row.kind,
+        mode: row.mode,
+        ctx_tokens: 0, // lazy: enrichRow
+        asks: 0, // lazy: enrichRow / enrichRows
+        cwd: row.cwd,
+        profile_id: row.profile_id,
+        created: row.created,
+        lifecycle: row.lifecycle,
+        mtimeMs: sessionMtime(row.node_id, row.created, remote),
+        streaming: !remote && hanging === null && live ? isStreaming(row.node_id, row.pi_pid) : false,
+        hanging,
+        viewed: remote ? false : focusedNodeIds.has(row.node_id) || hasLiveBrokerViewer(row),
+    };
+}
+/** One row per node visible in the sub-DAG of `rootId` (including root), read
+ *  entirely through the source — the openDb-free sibling of `dashboardRows`.
+ *  Ticket counts come from ONE `source.ticketCountsForView(rootId)` call (the
+ *  API/remote attention projection), never `countTickets` (openDb). */
+export async function dashboardRowsFromSource(source, rootId) {
+    const remote = source instanceof RemoteCanvasSource;
+    const tickets = await source.ticketCountsForView(rootId).catch(() => ({}));
+    const ids = [rootId, ...(await source.view(rootId))];
+    const rows = [];
+    for (const id of ids) {
+        const node = await source.getNode(id);
+        if (node === null)
+            continue;
+        const tel = remote ? {} : readNodeTelemetry(id);
+        rows.push({
+            node_id: id,
+            name: fullName(node),
+            status: node.status,
+            kind: node.kind,
+            mode: node.mode,
+            ctx_tokens: tel.tokens_in ?? 0,
+            asks: tickets[id] ?? 0,
+            cwd: node.cwd,
+            profile_id: node.profile_id,
+            created: node.created,
+        });
+    }
+    return rows;
+}
+/** CHEAP boot builder over a source — one row per node across the whole canvas,
+ *  fields that need no per-node meta/session read. Local API callers may supply
+ *  the node ids from one `listFocuses()` query so `viewed` remains visible without
+ *  coupling the canvas source to local viewer state. Remote sources ignore that
+ *  set. Local disk telemetry/fault/streaming are likewise suppressed remotely. */
+export async function dashboardRowsAllFromSource(source, localFocusedNodeIds = new Set()) {
+    const remote = source instanceof RemoteCanvasSource;
+    const focusedNodeIds = remote ? new Set() : localFocusedNodeIds;
+    return (await source.listNodes()).map((row) => dashboardRowFromNodeRow(row, focusedNodeIds, remote));
+}
+// ---------------------------------------------------------------------------
+// Lazy enrichment (source-driven) — fold expensive per-node reads into rows on
+// demand. Ask counts are supplied by the caller (`asks` — a pre-fetched
+// `ticketCountsForView` map merged across the visible roots), NOT scanned here
+// (`ticketCountsForNodes` reaches openDb). Telemetry (ctx tokens) + goal/session
+// are LOCAL disk reads, suppressed for a `RemoteCanvasSource`.
+// ---------------------------------------------------------------------------
+export async function enrichRowsFromSource(source, rows, asks) {
+    const todo = rows.filter((r) => r.enriched !== true);
+    if (todo.length === 0)
+        return;
+    const remote = source instanceof RemoteCanvasSource;
+    const askMap = asks ?? {};
+    await Promise.all(todo.map(async (row) => {
+        const meta = await source.getNode(row.node_id);
+        if (meta !== null)
+            row.name = fullName(meta);
+        row.ctx_tokens = remote ? 0 : (readNodeTelemetry(row.node_id).tokens_in ?? 0);
+        row.asks = askMap[row.node_id] ?? 0;
+        row.enriched = true;
+    }));
+}
+/** goal (initial-prompt.md) and session parts are local disk reads — suppressed
+ *  to undefined for a remote source. */
+export async function loadPreviewFromSource(source, row) {
+    if (row.previewLoaded === true)
+        return row;
+    const remote = source instanceof RemoteCanvasSource;
+    row.goal = remote ? undefined : readGoalText(row.node_id);
+    if (!remote) {
+        const meta = await source.getNode(row.node_id);
+        const { prompts, lastAssistant } = readSessionParts(meta?.pi_session_file);
+        row.prompts = prompts;
+        row.lastAssistant = lastAssistant;
+    }
+    row.previewLoaded = true;
+    return row;
+}

package/dist/core/canvas/render.d.ts

@@ -0,0 +1,47 @@
+import { type DashboardRow } from './render-source.js';
+export * from './render-source.js';
+/**
+ * Render the subscription sub-DAG rooted at `rootId` as an ASCII tree.
+ * The root is the first line (no connector prefix); children are indented.
+ *
+ * Each line: `<glyph> <name> [<kind>/<mode>] ctx <Nk>[ ⚑<asks>]`
+ *
+ * Returns a multi-line string (no trailing newline).
+ */
+export declare function renderTree(rootId: string): string;
+/**
+ * Render all canvas roots as a forest. A root is a node with no subscribers
+ * (no one subscribes to it = it has no managers in the org chart).
+ *
+ * If there are no roots on the canvas, returns a placeholder string.
+ */
+export declare function renderForest(): string;
+/** One row per node visible in the sub-DAG of `rootId` (including root). */
+export declare function dashboardRows(rootId: string): DashboardRow[];
+/**
+ * CHEAP boot builder — one row per node across the entire canvas, with only the
+ * fields that need no per-node meta/telemetry/session read. Two db queries total:
+ * `listNodes()` + `listFocuses()` (the focus set replaces per-node getFocusByNode
+ * calls). See {@link dashboardRowFromNodeRow} for the per-row projection, and
+ * {@link enrichRow}/{@link enrichRows}/{@link loadPreview} for the lazy fields.
+ */
+export declare function dashboardRowsAll(): DashboardRow[];
+/** Fold the cheap-boot row's deferred fields in for ONE row: the full label
+ *  (meta.description → fullName), ctx tokens (telemetry.json), and ⚑ asks. One
+ *  meta read + one telemetry read + one ticket scan. Idempotent (no-op once enriched).
+ *  For a batch, prefer {@link enrichRows} — it scans each cwd's ticket inbox once. */
+export declare function enrichRow(row: DashboardRow): DashboardRow;
+/** Batch {@link enrichRow}: enrich every not-yet-enriched row, scanning each
+ *  distinct cwd's ticket inbox exactly ONCE (via `ticketCountsForNodes`) instead
+ *  of per row. Use this for a whole viewport / the full forest; mutates each row in place. */
+export declare function enrichRows(rows: DashboardRow[]): void;
+/** Load the SELECTED row's preview text: the spawn `goal` (initial-prompt.md) plus
+ *  the whole-conversation `prompts` and the `lastAssistant` reply — the latter two
+ *  folded into ONE session-file read (see {@link readSessionParts}). Mutates the row
+ *  in place; idempotent. Call only for the cursor row (and lazily/in-background to
+ *  warm the prompt super-search corpus), never on the boot path. */
+export declare function loadPreview(row: DashboardRow): DashboardRow;
+/** {@link isStreaming} keyed by node id alone — hydrates the broker pid off the
+ *  db row. The exported "is this node actively generating right now?" guard so a
+ *  reap never nukes a node mid-first-turn before its output lands on disk. */
+export declare function isNodeStreaming(nodeId: string): boolean;