@crouton-kit/crouter 0.3.8 → 0.3.12

package/dist/core/canvas/attention.js

@@ -0,0 +1,94 @@
+// attention.ts — pending human-ask counters across the canvas.
+//
+// Human asks are stored per-cwd, not per-node (interactionsRoot is keyed by
+// the cwd the agent ran in, same pattern as humanloop's human list command).
+// A cwd can be shared by multiple nodes, so we de-dup on cwd before summing to
+// avoid counting the same pending ask N times.
+//
+// All public functions are best-effort: scanInbox failures return 0 / empty.
+// Callers are display code (dashboard, attention queue) that must not blow up
+// on a cold canvas or missing humanloop state.
+import { scanInbox } from '@crouton-kit/humanloop';
+import { interactionsRoot } from '../artifact.js';
+import { getNode, listNodes, view } from './canvas.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Count pending asks for a single cwd root. Never throws.
+ *
+ * When `nodeId` is given, count only asks raised by THAT node — humanloop
+ * stamps `deck.source.nodeId` with the originating CRTR_NODE_ID, so two nodes
+ * sharing a cwd no longer pollute each other's count. Asks with no stamp
+ * (legacy, or raised outside a canvas node) are not attributable to any node
+ * and are excluded from the per-node count. Read via a cast so this doesn't
+ * hard-depend on a humanloop type bump.
+ */
+function countForCwd(cwd, nodeId) {
+    try {
+        const items = scanInbox([interactionsRoot(cwd)]);
+        if (nodeId === undefined)
+            return items.length;
+        return items.filter((i) => i.source?.nodeId === nodeId).length;
+    }
+    catch {
+        // humanloop not installed, or interactions dir doesn't exist — both fine.
+        return 0;
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Count pending asks for the cwd of a single node.
+ * Returns 0 when the node is unknown or humanloop is unavailable.
+ */
+export function countAsks(nodeId) {
+    const node = getNode(nodeId);
+    if (node === null)
+        return 0;
+    return countForCwd(node.cwd, nodeId);
+}
+/**
+ * Pending asks for all nodes reachable in the subscription sub-DAG from
+ * `rootId` (including root itself). De-duped by cwd: when multiple nodes
+ * share a cwd the first one encountered claims the entry.
+ *
+ * Returns only entries with count > 0.
+ */
+export function pendingAsksForView(rootId) {
+    // view() returns children only (excludes root), so prepend root.
+    const ids = [rootId, ...view(rootId)];
+    const seen = new Map(); // cwd → entry
+    for (const id of ids) {
+        const node = getNode(id);
+        if (node === null)
+            continue;
+        if (seen.has(node.cwd))
+            continue; // already counted this cwd
+        const count = countForCwd(node.cwd);
+        if (count === 0) {
+            // Still mark the cwd seen so later nodes with the same cwd are skipped.
+            seen.set(node.cwd, { node_id: id, name: node.name, cwd: node.cwd, count: 0 });
+        }
+        else {
+            seen.set(node.cwd, { node_id: id, name: node.name, cwd: node.cwd, count });
+        }
+    }
+    return Array.from(seen.values()).filter((e) => e.count > 0);
+}
+/**
+ * Pending asks across the entire canvas — every distinct cwd among all known
+ * nodes. Returns only entries with count > 0.
+ */
+export function asksAcrossCanvas() {
+    const rows = listNodes();
+    const seen = new Map(); // cwd → entry
+    for (const row of rows) {
+        if (seen.has(row.cwd))
+            continue;
+        const count = countForCwd(row.cwd);
+        seen.set(row.cwd, { node_id: row.node_id, name: row.name, cwd: row.cwd, count });
+    }
+    return Array.from(seen.values()).filter((e) => e.count > 0);
+}

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

@@ -0,0 +1,40 @@
+import type { NodeMeta, NodeRow, NodeStatus, SubscriptionRef } from './types.js';
+/** Create a node: scaffold its dirs, write meta.json, index the row. */
+export declare function createNode(meta: NodeMeta): NodeMeta;
+/** The canonical node record (from meta.json), or null if unknown. */
+export declare function getNode(nodeId: string): NodeMeta | null;
+/** The indexed row (from the db) — cheap for queries that don't need full meta. */
+export declare function getRow(nodeId: string): NodeRow | null;
+/** Merge a patch into a node's meta.json and re-index its row. */
+export declare function updateNode(nodeId: string, patch: Partial<NodeMeta>): NodeMeta;
+/** Convenience for the most common mutation. */
+export declare function setStatus(nodeId: string, status: NodeStatus): void;
+/** All rows, optionally filtered by status. */
+export declare function listNodes(filter?: {
+    status?: NodeStatus | NodeStatus[];
+}): NodeRow[];
+/** Record `A subscribes_to B` — A receives B's output. active=true wakes A on
+ *  emit; passive accumulates pointers without a wake. Mutable; callable by anyone. */
+export declare function subscribe(subscriber: string, publisher: string, active?: boolean): void;
+/** Drop a subscription edge. */
+export declare function unsubscribe(subscriber: string, publisher: string): void;
+/** Flip an existing subscription's wake behavior. */
+export declare function setSubscriptionActive(subscriber: string, publisher: string, active: boolean): void;
+/** Record the audit-only `child spawned_by parent` edge. */
+export declare function recordSpawn(child: string, parent: string): void;
+/** Who subscribes to `publisher` — the targets a push fans out to. */
+export declare function subscribersOf(publisher: string): SubscriptionRef[];
+/** Who `subscriber` subscribes to — its reports / the nodes feeding it. */
+export declare function subscriptionsOf(subscriber: string): SubscriptionRef[];
+/** A "view": every node whose output cascades up to `root` via subscriptions —
+ *  the subscription sub-DAG reachable downward (root → its reports → theirs …).
+ *  Returns ids excluding root, in BFS order. Cycle-safe. */
+export declare function view(root: string): string[];
+/** Stop-guard primitive: does this node hold an *active* subscription to a node
+ *  that's still live (active|idle) — i.e. something that can actually wake it?
+ *  If so, stopping is a legitimate await; if not, it must finish or escalate. */
+export declare function hasActiveLiveSubscription(nodeId: string): boolean;
+/** Rebuild node rows from on-disk metas (the db node table is a derived index).
+ *  Edges are left intact — subscribes_to is db-authoritative; spawned_by is
+ *  re-derived from each meta's `parent`. */
+export declare function rebuildIndex(): void;

package/dist/core/canvas/canvas.js

@@ -0,0 +1,210 @@
+// The canvas data-access layer. The one place that reads/writes the node+edge
+// model. Later phases (spawn, push, lifecycle, daemon) call only this.
+//
+// Source-of-truth split: a node's meta.json is canonical for its own fields;
+// the db row is a queryable index re-derivable from it. The subscribes_to edges
+// are db-authoritative (mutable, many-writers — what WAL is for).
+import { existsSync, readFileSync, writeFileSync, renameSync, readdirSync, } from 'node:fs';
+import { join } from 'node:path';
+import { openDb } from './db.js';
+import { ensureHome, ensureNodeDirs, nodeMetaPath, nodeDir, nodesRoot, } from './paths.js';
+// ---------------------------------------------------------------------------
+// meta.json (source of truth)
+// ---------------------------------------------------------------------------
+function readMeta(nodeId) {
+    const p = nodeMetaPath(nodeId);
+    if (!existsSync(p))
+        return null;
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+function writeMeta(meta) {
+    const p = nodeMetaPath(meta.node_id);
+    const tmp = `${p}.tmp`;
+    writeFileSync(tmp, JSON.stringify(meta, null, 2));
+    renameSync(tmp, p);
+}
+// ---------------------------------------------------------------------------
+// row index (derived from meta)
+// ---------------------------------------------------------------------------
+function upsertRow(meta) {
+    openDb()
+        .prepare(`INSERT INTO nodes (node_id, name, kind, mode, lifecycle, status, cwd, parent, created)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(node_id) DO UPDATE SET
+         name=excluded.name, kind=excluded.kind, mode=excluded.mode,
+         lifecycle=excluded.lifecycle, status=excluded.status, cwd=excluded.cwd,
+         parent=excluded.parent`)
+        .run(meta.node_id, meta.name, meta.kind, meta.mode, meta.lifecycle, meta.status, meta.cwd, meta.parent ?? null, meta.created);
+}
+function rowFrom(r) {
+    return {
+        node_id: r['node_id'],
+        name: r['name'],
+        kind: r['kind'],
+        mode: r['mode'],
+        lifecycle: r['lifecycle'],
+        status: r['status'],
+        cwd: r['cwd'],
+        parent: r['parent'] ?? null,
+        created: r['created'],
+    };
+}
+// ---------------------------------------------------------------------------
+// Nodes
+// ---------------------------------------------------------------------------
+/** Create a node: scaffold its dirs, write meta.json, index the row. */
+export function createNode(meta) {
+    ensureHome();
+    ensureNodeDirs(meta.node_id);
+    writeMeta(meta);
+    upsertRow(meta);
+    return meta;
+}
+/** The canonical node record (from meta.json), or null if unknown. */
+export function getNode(nodeId) {
+    return readMeta(nodeId);
+}
+/** The indexed row (from the db) — cheap for queries that don't need full meta. */
+export function getRow(nodeId) {
+    const r = openDb()
+        .prepare('SELECT * FROM nodes WHERE node_id = ?')
+        .get(nodeId);
+    return r ? rowFrom(r) : null;
+}
+/** Merge a patch into a node's meta.json and re-index its row. */
+export function updateNode(nodeId, patch) {
+    const cur = readMeta(nodeId);
+    if (!cur)
+        throw new Error(`unknown node: ${nodeId}`);
+    const next = { ...cur, ...patch, node_id: cur.node_id };
+    writeMeta(next);
+    upsertRow(next);
+    return next;
+}
+/** Convenience for the most common mutation. */
+export function setStatus(nodeId, status) {
+    updateNode(nodeId, { status });
+}
+/** All rows, optionally filtered by status. */
+export function listNodes(filter) {
+    const db = openDb();
+    let rows;
+    if (filter?.status !== undefined) {
+        const statuses = Array.isArray(filter.status) ? filter.status : [filter.status];
+        const placeholders = statuses.map(() => '?').join(',');
+        rows = db
+            .prepare(`SELECT * FROM nodes WHERE status IN (${placeholders}) ORDER BY created`)
+            .all(...statuses);
+    }
+    else {
+        rows = db.prepare('SELECT * FROM nodes ORDER BY created').all();
+    }
+    return rows.map(rowFrom);
+}
+// ---------------------------------------------------------------------------
+// Edges
+// ---------------------------------------------------------------------------
+function addEdge(type, from, to, active) {
+    openDb()
+        .prepare(`INSERT INTO edges (type, from_id, to_id, active, created)
+       VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(type, from_id, to_id) DO UPDATE SET active=excluded.active`)
+        .run(type, from, to, active ? 1 : 0, new Date().toISOString());
+}
+/** Record `A subscribes_to B` — A receives B's output. active=true wakes A on
+ *  emit; passive accumulates pointers without a wake. Mutable; callable by anyone. */
+export function subscribe(subscriber, publisher, active = true) {
+    addEdge('subscribes_to', subscriber, publisher, active);
+}
+/** Drop a subscription edge. */
+export function unsubscribe(subscriber, publisher) {
+    openDb()
+        .prepare('DELETE FROM edges WHERE type = ? AND from_id = ? AND to_id = ?')
+        .run('subscribes_to', subscriber, publisher);
+}
+/** Flip an existing subscription's wake behavior. */
+export function setSubscriptionActive(subscriber, publisher, active) {
+    openDb()
+        .prepare('UPDATE edges SET active = ? WHERE type = ? AND from_id = ? AND to_id = ?')
+        .run(active ? 1 : 0, 'subscribes_to', subscriber, publisher);
+}
+/** Record the audit-only `child spawned_by parent` edge. */
+export function recordSpawn(child, parent) {
+    addEdge('spawned_by', child, parent, true);
+}
+/** Who subscribes to `publisher` — the targets a push fans out to. */
+export function subscribersOf(publisher) {
+    return openDb()
+        .prepare(`SELECT from_id AS node_id, active, created FROM edges
+         WHERE type = 'subscribes_to' AND to_id = ? ORDER BY created`)
+        .all(publisher).map((r) => ({
+        node_id: r['node_id'],
+        active: r['active'] === 1,
+        created: r['created'],
+    }));
+}
+/** Who `subscriber` subscribes to — its reports / the nodes feeding it. */
+export function subscriptionsOf(subscriber) {
+    return openDb()
+        .prepare(`SELECT to_id AS node_id, active, created FROM edges
+         WHERE type = 'subscribes_to' AND from_id = ? ORDER BY created`)
+        .all(subscriber).map((r) => ({
+        node_id: r['node_id'],
+        active: r['active'] === 1,
+        created: r['created'],
+    }));
+}
+// ---------------------------------------------------------------------------
+// Graph queries
+// ---------------------------------------------------------------------------
+/** A "view": every node whose output cascades up to `root` via subscriptions —
+ *  the subscription sub-DAG reachable downward (root → its reports → theirs …).
+ *  Returns ids excluding root, in BFS order. Cycle-safe. */
+export function view(root) {
+    const seen = new Set([root]);
+    const out = [];
+    const queue = subscriptionsOf(root).map((s) => s.node_id);
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        out.push(id);
+        for (const s of subscriptionsOf(id)) {
+            if (!seen.has(s.node_id))
+                queue.push(s.node_id);
+        }
+    }
+    return out;
+}
+/** Stop-guard primitive: does this node hold an *active* subscription to a node
+ *  that's still live (active|idle) — i.e. something that can actually wake it?
+ *  If so, stopping is a legitimate await; if not, it must finish or escalate. */
+export function hasActiveLiveSubscription(nodeId) {
+    const r = openDb()
+        .prepare(`SELECT 1 FROM edges e JOIN nodes n ON n.node_id = e.to_id
+       WHERE e.type = 'subscribes_to' AND e.from_id = ? AND e.active = 1
+         AND n.status IN ('active', 'idle') LIMIT 1`)
+        .get(nodeId);
+    return r !== undefined;
+}
+// ---------------------------------------------------------------------------
+// Index rebuild
+// ---------------------------------------------------------------------------
+/** Rebuild node rows from on-disk metas (the db node table is a derived index).
+ *  Edges are left intact — subscribes_to is db-authoritative; spawned_by is
+ *  re-derived from each meta's `parent`. */
+export function rebuildIndex() {
+    if (!existsSync(nodesRoot()))
+        return;
+    for (const id of readdirSync(nodesRoot())) {
+        if (!existsSync(join(nodeDir(id), 'meta.json')))
+            continue;
+        const meta = readMeta(id);
+        if (!meta)
+            continue;
+        upsertRow(meta);
+        if (meta.parent)
+            recordSpawn(meta.node_id, meta.parent);
+    }
+}

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

@@ -0,0 +1,7 @@
+import { DatabaseSync } from 'node:sqlite';
+/** Open (or reuse) the canvas db at the current `CRTR_HOME`, initializing the
+ *  schema and WAL on first open. Keyed by path so tests with distinct homes get
+ *  independent handles. */
+export declare function openDb(): DatabaseSync;
+/** Close and forget the handle for the current home. Mainly for tests. */
+export declare function closeDb(): void;

package/dist/core/canvas/db.js

@@ -0,0 +1,61 @@
+// canvas.db — the topology skeleton. sqlite in WAL mode so the many concurrent
+// writers a sisyphus-grade swarm produces don't contend on a single locked JSON.
+//
+// Node rows are a rebuildable index over each node's meta.json (the source of
+// truth). The `subscribes_to` edges are the one genuinely-mutable part no meta
+// owns, so the db is authoritative for them.
+import { DatabaseSync } from 'node:sqlite';
+import { canvasDbPath, ensureHome } from './paths.js';
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS nodes (
+  node_id    TEXT PRIMARY KEY,
+  name       TEXT NOT NULL,
+  kind       TEXT NOT NULL,
+  mode       TEXT NOT NULL DEFAULT 'base',
+  lifecycle  TEXT NOT NULL DEFAULT 'terminal',
+  status     TEXT NOT NULL DEFAULT 'active',
+  cwd        TEXT NOT NULL,
+  parent     TEXT,
+  created    TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS edges (
+  type     TEXT NOT NULL,           -- 'subscribes_to' | 'spawned_by'
+  from_id  TEXT NOT NULL,
+  to_id    TEXT NOT NULL,
+  active   INTEGER NOT NULL DEFAULT 1,
+  created  TEXT NOT NULL,
+  PRIMARY KEY (type, from_id, to_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_edges_to   ON edges(type, to_id);
+CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(type, from_id);
+CREATE INDEX IF NOT EXISTS idx_nodes_status ON nodes(status);
+`;
+const handles = new Map();
+/** Open (or reuse) the canvas db at the current `CRTR_HOME`, initializing the
+ *  schema and WAL on first open. Keyed by path so tests with distinct homes get
+ *  independent handles. */
+export function openDb() {
+    const path = canvasDbPath();
+    const existing = handles.get(path);
+    if (existing)
+        return existing;
+    ensureHome();
+    const db = new DatabaseSync(path);
+    db.exec('PRAGMA journal_mode = WAL;');
+    db.exec('PRAGMA foreign_keys = ON;');
+    db.exec('PRAGMA busy_timeout = 5000;');
+    db.exec(SCHEMA);
+    handles.set(path, db);
+    return db;
+}
+/** Close and forget the handle for the current home. Mainly for tests. */
+export function closeDb() {
+    const path = canvasDbPath();
+    const db = handles.get(path);
+    if (db) {
+        db.close();
+        handles.delete(path);
+    }
+}

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

@@ -0,0 +1,4 @@
+export * from './types.js';
+export * from './paths.js';
+export * from './canvas.js';
+export { openDb, closeDb } from './db.js';

package/dist/core/canvas/index.js

@@ -0,0 +1,6 @@
+// The canvas: one global graph of nodes + edges. Phase 0 of the pi-native
+// agent runtime. Topology in sqlite (WAL), node flesh on disk.
+export * from './types.js';
+export * from './paths.js';
+export * from './canvas.js';
+export { openDb, closeDb } from './db.js';

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

@@ -0,0 +1,16 @@
+/** Root of the global canvas home (`~/.crtr` unless `CRTR_HOME` is set). */
+export declare function crtrHome(): string;
+export declare function canvasDbPath(): string;
+export declare function nodesRoot(): string;
+export declare function nodeDir(nodeId: string): string;
+export declare function contextDir(nodeId: string): string;
+export declare function jobDir(nodeId: string): string;
+export declare function reportsDir(nodeId: string): string;
+export declare function nodeMetaPath(nodeId: string): string;
+export declare function inboxPath(nodeId: string): string;
+export declare function transcriptPath(nodeId: string): string;
+export declare function sessionPtrPath(nodeId: string): string;
+/** Create the full directory skeleton for a node. Idempotent. */
+export declare function ensureNodeDirs(nodeId: string): void;
+/** Ensure the canvas home exists. Idempotent. */
+export declare function ensureHome(): void;

package/dist/core/canvas/paths.js

@@ -0,0 +1,62 @@
+// The `~/.crtr/` layout. One global, cwd-agnostic home for the whole canvas.
+//
+//   ~/.crtr/
+//     canvas.db                 sqlite (WAL) — topology only (nodes + edges)
+//     nodes/<node_id>/
+//       meta.json               source of truth for the node's row
+//       context/                roadmap.md, initial-prompt.md, explore-*.md, artifacts
+//       job/                    log.jsonl, telemetry.json
+//       reports/                append-only push history (<ts>-<kind>.md)
+//       inbox.jsonl             messages + coalesced subscription feed
+//       transcript.jsonl        mirror/pointer of the pi session
+//       session.ptr             pi session id/path
+//
+// `CRTR_HOME` overrides the root (used by tests and isolated runs).
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync } from 'node:fs';
+/** Root of the global canvas home (`~/.crtr` unless `CRTR_HOME` is set). */
+export function crtrHome() {
+    const override = process.env['CRTR_HOME'];
+    return override !== undefined && override !== '' ? override : join(homedir(), '.crtr');
+}
+export function canvasDbPath() {
+    return join(crtrHome(), 'canvas.db');
+}
+export function nodesRoot() {
+    return join(crtrHome(), 'nodes');
+}
+export function nodeDir(nodeId) {
+    return join(nodesRoot(), nodeId);
+}
+export function contextDir(nodeId) {
+    return join(nodeDir(nodeId), 'context');
+}
+export function jobDir(nodeId) {
+    return join(nodeDir(nodeId), 'job');
+}
+export function reportsDir(nodeId) {
+    return join(nodeDir(nodeId), 'reports');
+}
+export function nodeMetaPath(nodeId) {
+    return join(nodeDir(nodeId), 'meta.json');
+}
+export function inboxPath(nodeId) {
+    return join(nodeDir(nodeId), 'inbox.jsonl');
+}
+export function transcriptPath(nodeId) {
+    return join(nodeDir(nodeId), 'transcript.jsonl');
+}
+export function sessionPtrPath(nodeId) {
+    return join(nodeDir(nodeId), 'session.ptr');
+}
+/** Create the full directory skeleton for a node. Idempotent. */
+export function ensureNodeDirs(nodeId) {
+    for (const d of [contextDir(nodeId), jobDir(nodeId), reportsDir(nodeId)]) {
+        mkdirSync(d, { recursive: true });
+    }
+}
+/** Ensure the canvas home exists. Idempotent. */
+export function ensureHome() {
+    mkdirSync(nodesRoot(), { recursive: true });
+}

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

@@ -0,0 +1,30 @@
+import type { NodeStatus } from './types.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;
+export interface DashboardRow {
+    node_id: string;
+    name: string;
+    status: NodeStatus;
+    kind: string;
+    mode: string;
+    ctx_tokens: number;
+    asks: number;
+}
+/** One row per node visible in the sub-DAG of `rootId` (including root). */
+export declare function dashboardRows(rootId: string): DashboardRow[];
+/** One row per node across the entire canvas. */
+export declare function dashboardRowsAll(): DashboardRow[];