pi-tau-web-server 1.0.8

package/bin/tree.js

@@ -0,0 +1,248 @@
+"use strict";
+/*
+ * Session-tree navigation for the backend-local `navigate_tree` RPC command.
+ *
+ * pi stores a session as an append-only JSONL tree (entries have id/parentId;
+ * the current position is the "leaf"). pi's native RPC protocol only exposes
+ * READ-ONLY tree commands (get_tree / get_entries) — there is no command that
+ * moves the leaf — so tau bundles a small pi extension
+ * (src/pi-extension/tau-tree.ts, loaded into every child via `--extension`)
+ * that registers a `/tau-tree-navigate <entryId>` command. The handler calls
+ * pi's own ctx.navigateTree() — the same API the TUI /tree uses — so the move
+ * happens in-process, respects other extensions' session_before_tree hooks,
+ * and persists itself by appending a `custom` marker entry (pi derives the
+ * leaf from the LAST entry on load, so a bare in-memory move would not
+ * survive a restart). Matched extension commands never reach the LLM and
+ * never append a user message, so neither the command text nor the marker is
+ * visible to the model.
+ *
+ * navigateTree below drives that command over RPC: it resolves the target
+ * from a preflight get_tree, sends the prompt, then re-fetches the tree to
+ * refresh session.entries and VERIFY the move — a handler error does not fail
+ * the prompt response (pi reports it as an `extension_error` event instead),
+ * so the follow-up get_tree is the real success check.
+ *
+ * Selection semantics mirror pi's /tree (docs/sessions.md "Selection
+ * Behavior"); the extension delegates them to ctx.navigateTree, and tau
+ * re-derives them here (selectNavigationTarget) only to detect no-ops, verify
+ * the new leaf, and hand the client its editorText — RPC-mode extensions
+ * cannot fill an editor:
+ *   - user (or custom) MESSAGE entry → the leaf moves to the entry's PARENT
+ *     and the message text goes back as editorText so the client can put it
+ *     in the input box for edit + resubmit (root user message → reset to an
+ *     empty conversation).
+ *   - any other entry → the leaf moves TO that entry, no editorText.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NAVIGATION_MARKER_TYPE = exports.NAVIGATE_COMMAND = void 0;
+exports.selectNavigationTarget = selectNavigationTarget;
+exports.flattenTree = flattenTree;
+exports.pathFromRoot = pathFromRoot;
+exports.leafDescendsFrom = leafDescendsFrom;
+exports.isTreeNavigationInProgress = isTreeNavigationInProgress;
+exports.navigateTree = navigateTree;
+/**
+ * Name of the slash command registered by tau's bundled pi extension.
+ * Keep in sync with NAVIGATE_COMMAND in src/pi-extension/tau-tree.ts.
+ */
+exports.NAVIGATE_COMMAND = 'tau-tree-navigate';
+/**
+ * customType of the marker entries the extension appends to persist a leaf
+ * move. Keep in sync with src/pi-extension/tau-tree.ts (and the frontend
+ * constant in src/public/tree-view.ts, which hides markers from the tree).
+ */
+exports.NAVIGATION_MARKER_TYPE = 'tau:navigate-tree';
+function textFromContent(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .filter((b) => !!b && typeof b === 'object')
+        .filter((b) => b.type === 'text' && typeof b.text === 'string')
+        .map((b) => b.text)
+        .join('\n');
+}
+/**
+ * Decide where the leaf should move for a navigation target, mirroring pi's
+ * /tree selection behavior. Pure function — exported for tests.
+ */
+function selectNavigationTarget(entry) {
+    if (entry.type === 'message' && entry.message?.role === 'user') {
+        return { leafTargetId: entry.parentId ?? null, editorText: textFromContent(entry.message.content) };
+    }
+    if (entry.type === 'custom_message') {
+        return { leafTargetId: entry.parentId ?? null, editorText: textFromContent(entry.content) };
+    }
+    return { leafTargetId: entry.id };
+}
+/** Flatten get_tree nodes (possibly multiple roots) into an id → entry map. */
+function flattenTree(nodes) {
+    const byId = new Map();
+    const stack = [...(nodes || [])];
+    while (stack.length) {
+        const node = stack.pop();
+        if (!node || !node.entry || typeof node.entry.id !== 'string')
+            continue;
+        byId.set(node.entry.id, node.entry);
+        if (node.children && node.children.length)
+            stack.push(...node.children);
+    }
+    return byId;
+}
+/** Walk root→leaf along parentId links; returns [] for a null/unknown leaf. */
+function pathFromRoot(byId, leafId) {
+    const path = [];
+    const seen = new Set();
+    let current = leafId ? byId.get(leafId) : undefined;
+    while (current && !seen.has(current.id)) {
+        seen.add(current.id);
+        path.push(current);
+        current = current.parentId ? byId.get(current.parentId) : undefined;
+    }
+    path.reverse();
+    return path;
+}
+/** True when `leafId` is `ancestorId` or one of its descendants. */
+function leafDescendsFrom(byId, leafId, ancestorId) {
+    const seen = new Set();
+    let current = leafId ? byId.get(leafId) : undefined;
+    while (current && !seen.has(current.id)) {
+        if (current.id === ancestorId)
+            return true;
+        seen.add(current.id);
+        current = current.parentId ? byId.get(current.parentId) : undefined;
+    }
+    return false;
+}
+// Session ids with a navigate_tree currently in flight. navigateTree runs a
+// multi-await check→navigate→verify sequence, so without this a second
+// navigation (or a prompt — see the guard in server-main's handleRpcCommand)
+// could interleave with it and land its entries on the wrong branch.
+const navigationsInFlight = new Set();
+/** True while a navigate_tree is moving this session's leaf. */
+function isTreeNavigationInProgress(sessionId) {
+    return navigationsInFlight.has(sessionId);
+}
+function assertNotStreaming(session) {
+    if (session.isStreaming) {
+        throw new Error('Cannot navigate the session tree while the agent is streaming; abort or wait for the turn to finish');
+    }
+}
+/**
+ * Once per child process, confirm pi actually registered tau's extension
+ * command. Without this check a broken install (extension file missing or
+ * failing to load) would make the `/tau-tree-navigate …` text fall through
+ * pi's command matching and be sent to the LLM as a literal user prompt.
+ */
+async function assertNavigateCommandAvailable(session) {
+    if (session.navigateCommandChecked)
+        return;
+    const resp = await session.send({ type: 'get_commands' }, { timeoutMs: 15000 });
+    if (resp.success === false) {
+        throw new Error(`pi could not list its commands: ${resp.error || 'unknown error'}`);
+    }
+    const commands = (resp.data || {}).commands || [];
+    const found = commands.some((c) => c.name === exports.NAVIGATE_COMMAND && c.source === 'extension');
+    if (!found) {
+        throw new Error(`The pi child did not load tau's ${exports.NAVIGATE_COMMAND} extension; cannot navigate the session tree`);
+    }
+    session.navigateCommandChecked = true;
+}
+/**
+ * Full navigate_tree flow for a live session: resolve the target from a
+ * preflight get_tree, have the child move its leaf in-process via the bundled
+ * extension's /tau-tree-navigate command, re-fetch the tree to confirm the
+ * move, refresh session.entries to the new active path, and broadcast a fresh
+ * `live_session_snapshot` (plus `live_session_updated`) so every connected
+ * browser re-renders the conversation.
+ *
+ * The streaming guard cannot be made fully airtight from tau's side (a prompt
+ * whose agent_start has not yet round-tripped through the child is invisible
+ * here), so the flow is defensive instead: one navigation per session at a
+ * time, the extension re-checks idleness in-process (ctx.isIdle()) right
+ * before moving the leaf, prompts are refused by handleRpcCommand while a
+ * navigation is in flight, and if the child still turns out to have moved on
+ * (leaf verification fails) the clients are re-synced to the child's real
+ * state before the error is reported.
+ */
+async function navigateTree(session, entryId) {
+    if (navigationsInFlight.has(session.id)) {
+        throw new Error('Another tree navigation for this session is already in progress');
+    }
+    navigationsInFlight.add(session.id);
+    try {
+        assertNotStreaming(session);
+        // Preflight: fetch the tree to resolve the target entry (clear error for
+        // unknown ids), detect no-ops, and derive editorText locally — RPC-mode
+        // extensions cannot fill the client's editor, and the /tau-tree-navigate
+        // prompt response cannot carry handler data.
+        let treeResp = await session.send({ type: 'get_tree' }, { timeoutMs: 15000 });
+        if (treeResp.success === false) {
+            throw new Error(`pi did not answer the pre-navigation tree check: ${treeResp.error || 'unknown error'}`);
+        }
+        let treeData = (treeResp.data || {});
+        let byId = flattenTree(treeData.tree);
+        const entry = byId.get(entryId);
+        if (!entry)
+            throw new Error(`Entry ${entryId} not found in the session tree`);
+        const target = selectNavigationTarget(entry);
+        const previousLeafId = treeData.leafId ?? null;
+        // Already there: pi's navigateTree no-ops when the selected entry IS the
+        // current leaf, and moving to the current position would be pure churn —
+        // skip the round-trip (but still hand back the editorText, so selecting
+        // the leaf user message keeps prefilling the composer).
+        if (entryId === previousLeafId || (target.leafTargetId !== null && target.leafTargetId === previousLeafId)) {
+            return target.editorText !== undefined ? { editorText: target.editorText } : {};
+        }
+        await assertNavigateCommandAvailable(session);
+        // A turn may have started while the preflight round-tripped; re-check
+        // here for a fast, precise error (the extension re-checks in-process via
+        // ctx.isIdle() as the authoritative guard).
+        assertNotStreaming(session);
+        session.lastExtensionError = null;
+        const prompted = await session.send({ type: 'prompt', message: `/${exports.NAVIGATE_COMMAND} ${entryId}` }, { timeoutMs: 30000 });
+        if (prompted.success === false) {
+            throw new Error(`pi refused the tree-navigation command: ${prompted.error || 'unknown error'}`);
+        }
+        // The prompt ack only means the handler ran — its errors surface as
+        // `extension_error` events, not as a failed response — so the follow-up
+        // get_tree is the real success check.
+        treeResp = await session.send({ type: 'get_tree' }, { timeoutMs: 30000 });
+        if (treeResp.success === false) {
+            // The child MAY have moved its leaf; we just cannot re-derive the
+            // entries. At least nudge clients so they refetch metadata instead of
+            // silently rendering the old branch forever.
+            session.manager.broadcastUpdated(session.id);
+            throw new Error(`pi could not report the session tree after navigating: ${treeResp.error || 'unknown error'}`);
+        }
+        treeData = (treeResp.data || {});
+        byId = flattenTree(treeData.tree);
+        const newLeafId = treeData.leafId ?? null;
+        // Refresh entries and broadcast BEFORE verifying the leaf: at this point
+        // the child is authoritative, so even when verification fails below every
+        // client must be re-rendered onto whatever the child actually has.
+        session.entries = pathFromRoot(byId, newLeafId);
+        session.manager.broadcast({ type: 'live_session_snapshot', sessionId: session.id, ...session.snapshot() });
+        session.manager.broadcastUpdated(session.id);
+        // On success the extension appended a marker at the navigation target and
+        // that marker IS the child's new leaf (no reload happens, so nothing else
+        // gets appended in between). Requiring the leaf to have changed AND to be
+        // a marker parented at the target rejects both a silent no-move (handler
+        // error) and a leaf that moved somewhere unexpected.
+        const newLeaf = newLeafId ? byId.get(newLeafId) : undefined;
+        const moved = newLeafId !== previousLeafId &&
+            newLeaf !== undefined &&
+            newLeaf.type === 'custom' &&
+            newLeaf.customType === exports.NAVIGATION_MARKER_TYPE &&
+            (newLeaf.parentId ?? null) === target.leafTargetId;
+        if (!moved) {
+            const detail = session.lastExtensionError ? `: ${session.lastExtensionError}` : '';
+            throw new Error(`pi did not move the session leaf to the expected entry${detail}`);
+        }
+        return target.editorText !== undefined ? { editorText: target.editorText } : {};
+    }
+    finally {
+        navigationsInFlight.delete(session.id);
+    }
+}

package/bin/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "pi-tau-web-server",
+  "version": "1.0.8",
+  "description": "Web browser workspace for Pi — a standalone web server that manages multiple live Pi RPC sessions in parallel.",
+  "keywords": [
+    "pi",
+    "pi-coding-agent",
+    "ai-agent",
+    "ai-coding-agent",
+    "coding-agent",
+    "harness",
+    "web-ui",
+    "web-server",
+    "rpc",
+    "standalone",
+    "multi-session"
+  ],
+  "author": {
+    "name": "Milan Glacier",
+    "email": "dev@milanglacier.com",
+    "url": "https://github.com/milanglacier"
+  },
+  "contributors": [
+    {
+      "name": "deflating",
+      "url": "https://github.com/deflating"
+    }
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/milanglacier/pi-tau-web-server#readme",
+  "bugs": {
+    "url": "https://github.com/milanglacier/pi-tau-web-server/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/milanglacier/pi-tau-web-server.git"
+  },
+  "main": "./bin/tau.js",
+  "bin": {
+    "pi-tau-web-server": "./bin/tau.js"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "bin",
+    "public",
+    "scripts",
+    "src",
+    "tsconfig.json",
+    "tsconfig.server.json",
+    "tsconfig.public.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.server.json && tsc -p tsconfig.public.json && node scripts/copy-katex.mjs",
+    "prepare": "npm run build",
+    "typecheck": "tsc -p tsconfig.server.json --noEmit && tsc -p tsconfig.public.json --noEmit && tsc -p tsconfig.test.json",
+    "test": "npm run build && node --test"
+  },
+  "dependencies": {
+    "ws": "^8.21.1"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.80.10",
+    "@types/node": "^26.1.1",
+    "@types/ws": "^8.18.1",
+    "katex": "^0.18.0",
+    "typescript": "^7.0.2"
+  }
+}