brane 0.1.1 → 0.3.1

package/dist/crush-tool-log.js

@@ -0,0 +1,293 @@
+/** Reading tool calls out of crush's own session log.
+ *
+ *  Every other harness brane captures reports its tool calls by running a hook.
+ *  crush cannot: it has a `PreToolUse` hook and no `PostToolUse` event at all,
+ *  and its pre payload carries no call id — so the two halves of a call could
+ *  never share a `dedup_key` even if both fired, and every call would strand as
+ *  `pending`. What crush does have is a database that records both halves, and
+ *  records the first one *while the call is still running*: a `tool_call` part
+ *  is persisted with `finished: false` the moment the call starts (verified
+ *  live against a 25s sleep by crush-cdcwzh2b, claude-pasen1co:24). That is the
+ *  same pending→completed shape the hook path produces, arriving by a different
+ *  road, which is what the `source: "session_log"` lane was declared for.
+ *
+ *  Everything here is read-only against a database another process owns.
+ */
+import Database from "better-sqlite3";
+import { join } from "node:path";
+import { statSync } from "node:fs";
+import { recordToolUse } from "./db/tool-uses.js";
+/** crush keeps one database per project, under the working directory. The data
+ *  directory is configurable (`options.data_directory`), and a fold that moved
+ *  it will simply read as "no log", which degrades to no capture. */
+export function crushDbPath(foldPath) {
+    return join(foldPath, ".crush", "crush.db");
+}
+/** crush's own timestamp columns are in **seconds**, despite the schema comment
+ *  on them saying milliseconds — the live rows read `created_at = 1786904402`,
+ *  and its `AFTER UPDATE` trigger stamps `strftime('%s','now')`, which is
+ *  seconds by definition. The `start_time`/`end_time` inside a tool result's
+ *  metadata really are milliseconds. Mixing the two units in one file is easy
+ *  and silent: a `created_at >= Date.now()` comparison matches nothing at all,
+ *  forever, and looks exactly like a session with no tool calls. */
+function toCrushSeconds(epochMs) {
+    return Math.floor(epochMs / 1000);
+}
+/** Session ids crush mints for its own bookkeeping rather than for a
+ *  conversation: `title-<parentId>` for summary generation, and
+ *  `<messageID>$$<toolCallID>` for a sub-agent invoked through its `agent`
+ *  tool. Neither is the session a narrative is having. */
+function isSyntheticSessionId(id) {
+    return id.startsWith("title-") || id.includes("$$");
+}
+/** The tool call that spawned a sub-agent session, from the session's own id.
+ *  crush encodes it as `<messageID>$$<toolCallID>`, which is exactly the
+ *  `parent_id` edge `tool_uses` records — so a sub-agent's calls nest under the
+ *  call that started it instead of arriving as orphans. */
+function parentToolCallId(sessionId) {
+    const marker = sessionId.indexOf("$$");
+    return marker === -1 ? undefined : sessionId.slice(marker + 2) || undefined;
+}
+/** crush double-encodes: `tool_call.input` and `tool_result.metadata` are JSON
+ *  *strings* inside a JSON document. Parse them when they are, pass them
+ *  through when they aren't, and never throw on either. */
+function parseMaybeJson(value) {
+    if (typeof value !== "string")
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+export function newCrushLogCursor() {
+    return { updatedAt: 0, written: new Map(), signature: null };
+}
+/** A cheap fingerprint of the log's contents: size and mtime of the database
+ *  *and of its `-wal` sibling*.
+ *
+ *  The sibling is the whole point. In WAL mode a write lands in `-wal` and the
+ *  main file's mtime does not move until a checkpoint — so a gate that stats
+ *  only the database would go quiet during exactly the burst of activity it
+ *  exists to catch, and look like a session that stopped making tool calls.
+ *
+ *  Returns null when there is no log at all, which is also "nothing to do".
+ *  This is the poller's whole idle cost: two stats, no open, no query. */
+export function crushLogSignature(foldPath) {
+    const path = crushDbPath(foldPath);
+    let signature;
+    try {
+        const main = statSync(path);
+        signature = `${main.size}:${main.mtimeMs}`;
+    }
+    catch {
+        return null;
+    }
+    try {
+        const wal = statSync(`${path}-wal`);
+        signature += `|${wal.size}:${wal.mtimeMs}`;
+    }
+    catch {
+        // No -wal: either checkpointed away or the journal mode changed. Absence
+        // is itself a stable part of the signature.
+        signature += "|none";
+    }
+    return signature;
+}
+/** Which crush session belongs to this narrative.
+ *
+ *  Prefers the id brane recorded at spawn. The fallback — newest real session
+ *  created at or after the narrative was — is a heuristic with a known failure
+ *  mode: two crush instances started in one fold at the same moment can be
+ *  cross-assigned. That is the same risk the codex adapter's discovery already
+ *  accepts, and it disappears the moment `agent_session_id` is populated. */
+export function resolveCrushSessionIds(crush, opts) {
+    const recorded = (opts.recorded ?? []).filter((id) => id && !isSyntheticSessionId(id));
+    if (recorded.length > 0)
+        return recorded;
+    // The synthetic-id exclusion belongs in the query, not after it. Filtering a
+    // `LIMIT 1` result in JS asks for the newest row and then throws it away if
+    // it turns out to be bookkeeping — reporting "no session" while a perfectly
+    // good one sits directly underneath it. `parent_session_id IS NULL` is not
+    // enough on its own: it happens to exclude sub-agent rows in the logs seen so
+    // far, but nothing guarantees every kind of synthetic row is parented.
+    const row = crush
+        .prepare(`SELECT id FROM sessions
+        WHERE created_at >= ?
+          AND parent_session_id IS NULL
+          AND id NOT LIKE 'title-%'
+          AND id NOT LIKE '%$$%'
+        ORDER BY created_at DESC LIMIT 1`)
+        .get(toCrushSeconds(opts.narrativeCreatedAtMs));
+    return row ? [row.id] : [];
+}
+/** A session and every sub-agent session under it, so calls made by a
+ *  sub-agent are captured too rather than vanishing into a child row. */
+function sessionFamily(crush, sessionIds) {
+    if (sessionIds.length === 0)
+        return [];
+    const placeholders = sessionIds.map(() => "?").join(", ");
+    const children = crush
+        .prepare(`SELECT id FROM sessions WHERE parent_session_id IN (${placeholders})`)
+        .all(...sessionIds);
+    const family = new Set(sessionIds);
+    for (const child of children) {
+        // Title-generation sessions summarize; they make no tool calls worth
+        // showing and would only add rows the operator never asked about.
+        if (!child.id.startsWith("title-"))
+            family.add(child.id);
+    }
+    return [...family];
+}
+/** Translate one message's `parts` into record calls.
+ *
+ *  A `tool_call` part is the call as announced — crush persists it with
+ *  `finished: false` before the tool runs — so it maps to `pending` no matter
+ *  what `finished` says by the time we read it. `finished: true` means the call
+ *  returned, not that it succeeded; the outcome is in the `tool_result` part,
+ *  which may not have been written yet. Letting `finished` imply success would
+ *  mark failed calls completed.
+ *
+ *  Exported for tests: the payload shapes below are crush's, and pinning them
+ *  in a pure function is cheaper than standing up a crush. */
+export function toolUsesFromCrushParts(partsJson, ctx) {
+    let parts;
+    try {
+        parts = JSON.parse(partsJson);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parts))
+        return [];
+    const out = [];
+    for (const part of parts) {
+        if (typeof part !== "object" || part === null)
+            continue;
+        const { type, data } = part;
+        if (typeof data !== "object" || data === null)
+            continue;
+        const d = data;
+        if (type === "tool_call") {
+            if (typeof d.id !== "string" || typeof d.name !== "string")
+                continue;
+            out.push({
+                dedupKey: d.id,
+                name: d.name,
+                input: parseMaybeJson(d.input),
+                status: "pending",
+                source: "session_log",
+                agentType: "crush",
+                parentId: ctx.parentId,
+            });
+            continue;
+        }
+        if (type === "tool_result") {
+            if (typeof d.tool_call_id !== "string")
+                continue;
+            const metadata = parseMaybeJson(d.metadata);
+            const times = typeof metadata === "object" && metadata !== null
+                ? metadata
+                : {};
+            const start = typeof times.start_time === "number" ? times.start_time : undefined;
+            const end = typeof times.end_time === "number" ? times.end_time : undefined;
+            out.push({
+                dedupKey: d.tool_call_id,
+                // The result names the tool again, but a pending row already has it;
+                // recordToolUse ignores a name it already holds.
+                name: typeof d.name === "string" ? d.name : "unknown",
+                status: d.is_error === true ? "failed" : "completed",
+                output: d.content,
+                // These are milliseconds, unlike the columns around them.
+                startedAt: start,
+                durationMs: start !== undefined && end !== undefined && end > start ? end - start : undefined,
+                source: "session_log",
+                agentType: "crush",
+                parentId: ctx.parentId,
+            });
+        }
+    }
+    return out;
+}
+/** Read whatever is new in a crush session log and record it.
+ *
+ *  Returns the rows actually written, for the caller to push. An unchanged row
+ *  is not rewritten: every write bumps `rev`, which is the sync cursor, so
+ *  re-recording a settled call would re-push it to every client on every poll.
+ *
+ *  Opens the log read-only. crush runs in WAL mode, so a concurrent reader is
+ *  safe while its TUI is live, and read-only means this can never be the
+ *  process that damages someone else's session. Any failure — no log, a schema
+ *  that moved, a locked file — is swallowed into "nothing to record": capture
+ *  is a bystander and must never take a narrative down with it. */
+export function pollCrushToolLog(db, narrativeId, opts, cursor) {
+    // Nothing has changed since the last look — and most looks find nothing,
+    // since an agent is idle far more often than it is calling a tool. Costing
+    // an idle narrative two stats instead of a database open is what makes a
+    // 2-second interval defensible at all.
+    const signature = crushLogSignature(opts.foldPath);
+    if (signature === null || signature === cursor.signature)
+        return [];
+    const path = crushDbPath(opts.foldPath);
+    let crush = null;
+    const written = [];
+    try {
+        crush = new Database(path, { readonly: true, fileMustExist: true });
+        const sessions = sessionFamily(crush, resolveCrushSessionIds(crush, {
+            recorded: opts.sessionIds,
+            narrativeCreatedAtMs: opts.narrativeCreatedAtMs,
+        }));
+        if (sessions.length === 0)
+            return [];
+        const placeholders = sessions.map(() => "?").join(", ");
+        // `>=`, not `>`: crush's timestamps have one-second resolution, so a strict
+        // cursor would skip a message written in the same second as the last one
+        // read. Re-reading a second costs an upsert that the `written` map then
+        // discards.
+        const rows = crush
+            .prepare(`SELECT id, session_id, parts, created_at, updated_at FROM messages
+          WHERE session_id IN (${placeholders}) AND updated_at >= ?
+          ORDER BY updated_at, created_at`)
+            .all(...sessions, cursor.updatedAt);
+        for (const row of rows) {
+            if (row.updated_at > cursor.updatedAt)
+                cursor.updatedAt = row.updated_at;
+            for (const opt of toolUsesFromCrushParts(row.parts, {
+                parentId: parentToolCallId(row.session_id),
+            })) {
+                const key = opt.dedupKey;
+                const prior = cursor.written.get(key);
+                if (prior === opt.status)
+                    continue;
+                // The same message rows are re-read whenever the cursor's second is
+                // revisited, so a settled call's `tool_call` part comes back around
+                // after its `tool_result` has already completed the row. recordToolUse
+                // refuses the status regression, but it still bumps `rev` and so still
+                // re-pushes the row to every client — every poll, forever. The rule
+                // that matters is the same one the upsert applies: a call already seen
+                // never goes back to pending.
+                if (prior !== undefined && opt.status === "pending")
+                    continue;
+                cursor.written.set(key, opt.status);
+                written.push(recordToolUse(db, narrativeId, opt));
+            }
+        }
+        // Only on a clean read: a poll that threw halfway must look again rather
+        // than treat the log as consumed.
+        cursor.signature = signature;
+    }
+    catch (err) {
+        console.error(`[crush-log] reading ${path} for ${narrativeId} failed: ${err}`);
+    }
+    finally {
+        try {
+            crush?.close();
+        }
+        catch {
+            // Closing a read-only handle can't lose data; nothing to do about it.
+        }
+    }
+    return written;
+}
+//# sourceMappingURL=crush-tool-log.js.map

package/dist/daemon/agent-scope.js

@@ -0,0 +1,116 @@
+/**
+ * What an agent's token may reach. Default-deny: a route is open to an agent
+ * only if it is listed here, so a route added later is closed to agents
+ * until someone decides otherwise.
+ *
+ * Open: reading brane (narratives, events, files, wiki, search), the pure
+ * renderers, and the session lifecycle agents drive themselves — spawn and
+ * revive (/ramify, reviving a peer) — and the memory index. Closed:
+ *
+ * - `/ws/terminal/:nid` and `/ws/control`, the app's channels: keystrokes
+ *   into any session, and signals. (tmux still lets one agent reach
+ *   another's pane; that is known and accepted, SECURITY.md.)
+ * - The operator's housekeeping: registering and archiving folds,
+ *   archiving narratives, absorb, cost backfill and reprice, the Devices
+ *   list. An operator who wants one of these from a phone runs it in a
+ *   utility session (the spawn dialog's Utility side), whose env carries
+ *   no agent token.
+ * - `POST /api/run`: a utility session's env carries no agent token, so
+ *   starting one would hand an agent this account's standing in a single
+ *   call. Only the app starts those; there is no CLI command for it.
+ * - `human_signal` (src/daemon/signal-source.ts) and the gated acts
+ *   (src/daemon/presence-gate.ts), which refuse agents with their own
+ *   messages; they are closed here too, so the list stays the whole story.
+ *
+ * Hygiene, not containment: an agent runs as the operator's Unix account
+ * and can drop its token and use `daemon.sock` (SECURITY.md, "What an agent
+ * token does not do"). What this stops is an agent that follows the rules
+ * overreaching, and a leaked agent token reaching any of the above.
+ */
+/** Routes an agent token may use, as `METHOD path-pattern`. `:x` matches
+ *  one path segment, `*` the rest of the path. */
+export const AGENT_ROUTES = [
+    "GET /api/status",
+    "GET /api/branes",
+    "GET /api/protocols",
+    "GET /api/folds",
+    "GET /api/narratives",
+    "GET /api/narratives/recent",
+    "GET /api/narratives/:id",
+    "GET /api/narratives/:id/events",
+    "GET /api/narratives/:id/export",
+    "GET /api/narratives/:id/tool_uses",
+    "GET /api/narratives/:id/tool_uses/:key",
+    "GET /api/payloads/:nid/*",
+    "GET /api/files",
+    "GET /api/files/list",
+    "GET /api/files/find",
+    "GET /api/wiki/read",
+    "GET /api/wiki/asset",
+    "GET /api/spawn-history",
+    "GET /api/run-history",
+    "POST /api/search",
+    "POST /api/wiki/search",
+    "POST /api/diagram",
+    "POST /api/highlight",
+    "POST /api/memory/index",
+    "POST /api/spawn",
+    "POST /api/revive/:nid",
+    // Bound to the token's own narrative where the upgrade is handled.
+    "GET /ws/mcp",
+];
+/** What an agent is told when a route is closed to it. */
+export const AGENT_SCOPE_REFUSAL = "An agent's token cannot use this route; it is the operator's. From a phone, run the command in a utility session (the spawn dialog's Utility side), which carries no agent token";
+const MATCHERS = AGENT_ROUTES.map((route) => {
+    const [method, pattern] = route.split(" ");
+    return { method, segments: pattern.split("/").slice(1) };
+});
+function matches(m, method, segments) {
+    if (m.method !== method)
+        return false;
+    for (let i = 0; i < m.segments.length; i++) {
+        const want = m.segments[i];
+        if (want === "*")
+            return i < segments.length && segments.slice(i).every((s) => s !== "");
+        if (i >= segments.length)
+            return false;
+        if (want.startsWith(":")) {
+            if (segments[i] === "")
+                return false;
+            continue;
+        }
+        if (want !== segments[i])
+            return false;
+    }
+    return m.segments.length === segments.length;
+}
+export const AGENT_LOOPBACK_REFUSAL = "An agent's token works only from this machine";
+/** Why a request made with an agent's token is refused, or null if it may
+ *  go on. An agent's token works only from this machine — over
+ *  `daemon.sock` or loopback — so a copy that leaks off it opens nothing.
+ *  That costs no client anything: a spawned agent's MCP bridge and an
+ *  external client's (`brane mcp`, started from its `.mcp.json`) both run
+ *  here and dial the socket. */
+export function agentRefusal(req) {
+    if (!req.loopback)
+        return AGENT_LOOPBACK_REFUSAL;
+    return agentMayUse(req.method, req.path) ? null : AGENT_SCOPE_REFUSAL;
+}
+export const AGENT_REVIVE_REFUSAL = "An agent cannot revive or prompt a utility session: it carries no agent token, so typing into it would act as this account";
+/** Why an agent may not revive (or prompt) a narrative with this role, or
+ *  null if it may. A `utility` narrative is a session the app started
+ *  through `POST /api/run`: its env carries no agent token, so a prompt
+ *  typed into it — or its command replayed — runs as this account, the
+ *  standing closing that route withholds.
+ *  Reviving or prompting another agent stays open: tmux already lets agents
+ *  reach each other, which is accepted. */
+export function agentReviveRefusal(role) {
+    return role === "utility" ? AGENT_REVIVE_REFUSAL : null;
+}
+/** Whether an agent's token may make this request. `path` is the URL's
+ *  pathname, without the query string. A WebSocket upgrade is a `GET`. */
+export function agentMayUse(method, path) {
+    const segments = path.split("/").slice(1);
+    return MATCHERS.some((m) => matches(m, method.toUpperCase(), segments));
+}
+//# sourceMappingURL=agent-scope.js.map

package/dist/daemon/awaiting.js

@@ -0,0 +1,54 @@
+/**
+ * Which narratives are parked waiting for direction.
+ *
+ * An agent that has gone back to a blocking `listen` — or to a
+ * `narrate({ wait: true })`, which parks through the same machinery — is, as
+ * a rule, done with what it was doing and waiting to be told what next. The
+ * daemon holds that fact exactly: the call sits in its bridge's
+ * `pendingListens` until something resolves it. This turns the parks and
+ * resolutions into one boolean per narrative, and reports its edges.
+ *
+ * The boolean means "a call is parked right now", and every way a call ends
+ * clears it: `delivered` (the agent has something to act on), `closed` (its
+ * bridge is gone), `cancelled` (the harness abandoned the call: Esc, a killed
+ * task) and `timeout`. A timeout clears it too, though the agent will usually
+ * park again a model turn later. The glow goes out for that turn, and that is
+ * accurate: the agent is re-reading its context, not hanging on the operator's
+ * next word. (A 120 s grace used to hold it on across the gap; it made the
+ * glow a guess exactly when the agent had left the loop at the timeout.)
+ *
+ * Counted per narrative, not per call: a narrative can have more than one
+ * bridge (a reconnect, a subagent's), and it is awaiting while any of them
+ * holds a parked call.
+ */
+export class AwaitingTracker {
+    emit;
+    parkedCount = new Map();
+    constructor(emit) {
+        this.emit = emit;
+    }
+    isAwaiting(nid) {
+        return (this.parkedCount.get(nid) ?? 0) > 0;
+    }
+    /** A blocking call parked for this narrative. */
+    parked(nid) {
+        const count = this.parkedCount.get(nid) ?? 0;
+        this.parkedCount.set(nid, count + 1);
+        if (count === 0)
+            this.emit(nid, true);
+    }
+    /** A parked call for this narrative stopped waiting. The ending no longer
+     *  changes what happens; it is kept so every call site says why. */
+    resolved(nid, _ending) {
+        const count = this.parkedCount.get(nid) ?? 0;
+        if (count === 0)
+            return; // not one we saw park; nothing to undo
+        if (count > 1) {
+            this.parkedCount.set(nid, count - 1);
+            return;
+        }
+        this.parkedCount.delete(nid);
+        this.emit(nid, false);
+    }
+}
+//# sourceMappingURL=awaiting.js.map