pi-central 0.2.0 → 0.4.0

package/README.md

@@ -1,18 +1,43 @@
-# Pi Central
+<p align="center">
+  <img src="assets/pi-central-logo-full-dark-mode.svg" alt="Pi Central" width="420" />
+</p>
 
-> The central station where Pi sessions come together and are orchestrated.
+<p align="center">
+  <a href="https://www.npmjs.com/package/pi-central"><img alt="npm version" src="https://img.shields.io/npm/v/pi-central" /></a>
+  <a href="https://www.npmjs.com/package/pi-central"><img alt="npm downloads" src="https://img.shields.io/npm/dm/pi-central" /></a>
+  <a href="https://github.com/sven1103-agent/pi-central/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/sven1103-agent/pi-central/actions/workflows/ci.yml/badge.svg" /></a>
+  <img alt="node version" src="https://img.shields.io/node/v/pi-central" />
+  <img alt="license" src="https://img.shields.io/npm/l/pi-central" />
+</p>
 
-Pi Central is a local dashboard for running, watching, and switching between multiple
-[Pi](https://pi.dev) coding-agent sessions that live in **different working directories**, while
-keeping every session inside its own **Agent Safehouse** sandbox.
+**Pi Central** (/paɪ ˈsɛntrəl/) is a local dashboard for running, watching, and switching between
+multiple [Pi](https://pi.dev) coding-agent sessions that live in **different working directories**,
+while keeping every session inside its own **Agent Safehouse** sandbox.
 
-The name is the design brief: a central station is where independent lines arrive, are dispatched,
-and are kept apart from one another. Pi Central does the same for agent sessions.
+The central station is the design brief: independent lines arrive, are dispatched, and are kept apart
+from one another. Pi Central does the same for agent sessions.
 
 **Status: works end to end, verified, and published.** The version is deliberately not written down
 here: `pi-central --version` reports the version of the package it was actually shipped in, and a
 number restated in prose is a number that drifts. See [docs/RELEASING.md](docs/RELEASING.md).
 
+## Install it as an app
+
+Pi Central is a web app that installs to your dock. Start it once (see [Quick start](#quick-start)),
+open <http://127.0.0.1:8787>, and then install it from the browser's own menu:
+
+| Browser | How |
+|---|---|
+| **Safari** | *File → Add to Dock* |
+| **Chrome / Edge** | the install icon at the right end of the address bar, or *⋮ → Install page as app* |
+| **Firefox** | **not supported** — Mozilla has no PWA install on desktop. The service worker still works; use another browser for the dock icon. |
+
+You get the π mark in the dock and a window with no tab bar or address field.
+
+**It is not an offline app, deliberately.** Every screen is fed by the socket, so if the orchestrator is
+not running the installed app says `disconnected` and nothing else. A window that claimed to work
+offline would open onto a blank dashboard.
+
 ## The problem
 
 Pi has no fleet concept. One `pi` process owns one session and one working directory:
@@ -41,6 +66,18 @@ explanation rather than failing confusingly later.
 
 ## Design in one picture
 
+![The Pi Central dashboard. On the left, a session rail lists two sessions with their state and
+cost. In the middle, a transcript shows the reader's own prompt in a tinted block labelled YOU,
+followed by the agent's reasoning, two tool runs, and a live "responding" indicator. Below the
+transcript, a tool trace lists the last three commands with their durations. The right-hand panel is
+collapsed.](docs/images/dashboard.png)
+
+*A session mid-run. The rail carries the fleet, the transcript carries the conversation, and the tool
+trace carries what the agent actually ran. The right-hand panel — session facts, or a file browser —
+is **collapsed by default**; `Show panel` in the top bar opens it.*
+
+The layers behind that window:
+
 ```
 ┌──────────────────────────────┐
 │  Pi Central UI (localhost)   │  session rail · transcript · approvals · tool trace
@@ -67,7 +104,29 @@ never runs untrusted content, so being outside the sandbox is safe by constructi
 
 **One process.** The orchestrator serves the built UI and the WebSocket from the same origin, so
 there is no dev server to start and no port to coordinate. It must run from a plain terminal (see
-the constraint above).
+the constraint above), and it prints the URL it is serving on — <http://127.0.0.1:8787> unless you
+passed `--port`.
+
+### From npm — what a user does
+
+```bash
+npm install --global pi-central
+pi-central
+```
+
+Or without installing it at all:
+
+```bash
+npx pi-central
+```
+
+Once it is running, [install it as an app](#install-it-as-an-app) and you will not need the terminal
+again until the next reboot.
+
+The package is **one bundled ESM file plus the built UI**, with a single runtime dependency (`ws`),
+and `pi-central --version` reports the version of the package it was actually shipped in.
+
+### From a checkout — what a contributor does
 
 ```bash
 npm install
@@ -75,11 +134,7 @@ npm run ui:build      # once, and after any UI change
 npm run server        # the orchestrator, which also serves the UI
 ```
 
-Then open <http://127.0.0.1:8787> — the URL the server prints.
-
-### From the packaged artifact
-
-Nothing is published yet, but the artifact is buildable and installable today (issue #52):
+To build the publishable artifact from a checkout:
 
 ```bash
 npm run build:package     # bundles the orchestrator, copies the built UI
@@ -87,10 +142,8 @@ npm pack --dry-run        # show exactly what would ship
 npm run serve:package     # run the packaged binary from ./bin
 ```
 
-It ships as JavaScript — TypeScript cannot be loaded from `node_modules` — as **one bundled ESM
-file plus the built UI**, with a single runtime dependency. `pi-central --version` reports the
-version of the package it was actually shipped in, read from that `package.json` rather than
-restated in code. See [ADR-0011](docs/decisions/0011-distribution-and-update.md).
+It ships as JavaScript — TypeScript cannot be loaded from `node_modules` — as one bundled ESM file
+plus the built UI. See [ADR-0011](docs/decisions/0011-distribution-and-update.md).
 
 Serving the UI from the orchestrator is not only convenience. A Vite dev server watches
 `packages/ui/src`, so an agent editing a component reloads the interface you are using out from

package/bin/pi-central.js

@@ -25,7 +25,7 @@ function isBlockingDialog(record) {
 }
 
 // packages/protocol/src/envelopes.ts
-var PROTOCOL_VERSION = 2;
+var PROTOCOL_VERSION = 3;
 
 // packages/protocol/src/own-installation.ts
 var PIPELINE_MARKERS = ["packages/orchestrator", "packages/ui", "packages/protocol"];
@@ -1132,6 +1132,7 @@ function renderPolicyFragment(options = {}) {
 import { lstatSync, readdirSync as readdirSync2, readFileSync as readFileSync4, realpathSync, statSync as statSync4 } from "node:fs";
 import { isAbsolute, join as join7, resolve as resolve6, sep as sep3 } from "node:path";
 var MAX_FILE_BYTES = 256 * 1024;
+var MAX_IMAGE_BYTES = 8 * 1024 * 1024;
 var BINARY_SNIFF_BYTES = 8 * 1024;
 var DEFAULT_ENTRY_LIMIT = 2e3;
 function containsPath(parent, child) {
@@ -1311,7 +1312,7 @@ function readFileText(root, relative) {
       ok: false,
       error: {
         reason: "binary",
-        message: `"${relPath}" is a binary file (it contains NUL bytes), so it was not rendered as text`
+        message: `"${relPath}" is a binary file of ${formatBytes(stats.size)} (it contains NUL bytes), so it was not rendered as text`
       }
     };
   }
@@ -1323,11 +1324,77 @@ function readFileText(root, relative) {
       ok: false,
       error: {
         reason: "binary",
-        message: `"${relPath}" is not valid UTF-8, so it was not rendered as text`
+        message: `"${relPath}" is ${formatBytes(stats.size)} and not valid UTF-8, so it was not rendered as text`
       }
     };
   }
-  return { ok: true, value: { path: relPath, text, bytes: buffer.byteLength } };
+  return { ok: true, value: { kind: "text", path: relPath, text, bytes: buffer.byteLength } };
+}
+function imageTypeOf(buffer) {
+  const starts = (...signature) => signature.every((byte, index) => buffer[index] === byte);
+  if (starts(137, 80, 78, 71, 13, 10, 26, 10)) return "image/png";
+  if (starts(255, 216, 255)) return "image/jpeg";
+  if (starts(71, 73, 70, 56)) return "image/gif";
+  if (buffer.length >= 12 && buffer.subarray(0, 4).toString("latin1") === "RIFF" && buffer.subarray(8, 12).toString("latin1") === "WEBP") {
+    return "image/webp";
+  }
+  return void 0;
+}
+function svgRootOf(text) {
+  let rest = text.slice(0, SVG_HEAD_BYTES);
+  for (; ; ) {
+    const next = rest.replace(/^\s+|^<\?xml[^>]*\?>|^<!--[\s\S]*?-->|^<!DOCTYPE[^>[]*(?:\[[\s\S]*?\])?\s*>/gi, "");
+    if (next === rest) break;
+    rest = next;
+  }
+  if (!/^<svg[\s>]/i.test(rest)) return false;
+  return /xmlns\s*=\s*["']http:\/\/www\.w3\.org\/2000\/svg["']/i.test(rest);
+}
+var SVG_HEAD_BYTES = 8 * 1024;
+function readFileForDisplay(root, relative) {
+  const resolvedPath = resolveWithin(root, relative);
+  if (!resolvedPath.ok) return resolvedPath;
+  const { path, relPath } = resolvedPath.value;
+  let stats;
+  try {
+    stats = lstatSync(path);
+  } catch (error) {
+    return { ok: false, error: fromErrno(error, "cannot open", relPath) };
+  }
+  if (stats.isDirectory()) {
+    return { ok: false, error: { reason: "is-directory", message: `"${relPath}" is a directory` } };
+  }
+  if (stats.size > MAX_IMAGE_BYTES) {
+    return {
+      ok: false,
+      error: {
+        reason: "too-large",
+        message: `"${relPath}" is ${formatBytes(stats.size)}, above the ${formatBytes(MAX_IMAGE_BYTES)} limit for displaying a file here, so it was not read`
+      }
+    };
+  }
+  let buffer;
+  try {
+    buffer = readFileSync4(path);
+  } catch (error) {
+    return { ok: false, error: fromErrno(error, "cannot read", relPath) };
+  }
+  const imageType = imageTypeOf(buffer);
+  if (imageType !== void 0) {
+    return {
+      ok: true,
+      value: { kind: "image", path: relPath, type: imageType, bytes: buffer.byteLength, data: buffer }
+    };
+  }
+  const asText = readFileText(root, relative);
+  if (!asText.ok) return asText;
+  if (svgRootOf(asText.value.text)) {
+    return {
+      ok: true,
+      value: { kind: "image", path: relPath, type: "image/svg+xml", bytes: stats.size, data: buffer }
+    };
+  }
+  return asText;
 }
 
 // packages/orchestrator/src/state.ts
@@ -1858,7 +1925,7 @@ ${rpc.stderrTail}` : ""}`;
         error: { reason: "not-found", message: `no session ${id}, so there is no working directory to read from` }
       };
     }
-    return readFileText(session.cwd, path);
+    return readFileForDisplay(session.cwd, path);
   }
   /**
    * Where this Pi Central installation lives, resolved once.
@@ -2079,7 +2146,15 @@ function directoryExists(dir) {
 import { createReadStream as createReadStream2, existsSync as existsSync6, statSync as statSync6 } from "node:fs";
 import { extname, join as join11, posix, resolve as resolve7, sep as sep4 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
-var UI_CSP = "default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'";
+var UI_CSP = (
+  // `blob:` is REQUIRED and is not covered by `'self'` (issue #111).
+  //
+  // A blob URL has an opaque origin, so `img-src 'self'` does not match it — the file viewer builds
+  // its images from a Blob and would have every one of them blocked, with the `<img>` firing `error`
+  // and the UI reporting "could not decode". That is a false accusation about a valid file, and it is
+  // what shipped: the comment said a blob URL "counts as 'self'", which stopped anyone checking.
+  "default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self'; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
+);
 var CONTENT_TYPES = {
   ".html": "text/html; charset=utf-8",
   ".js": "text/javascript; charset=utf-8",
@@ -2096,7 +2171,13 @@ var CONTENT_TYPES = {
   ".ico": "image/x-icon",
   ".woff": "font/woff",
   ".woff2": "font/woff2",
-  ".txt": "text/plain; charset=utf-8"
+  ".txt": "text/plain; charset=utf-8",
+  // A manifest served as `application/octet-stream` is IGNORED by every browser, silently — no icon, no
+  // install prompt, no error anywhere. The failure mode is a feature that simply does not exist.
+  ".webmanifest": "application/manifest+json",
+  // The service worker must be JavaScript, and must not be cached: a stale worker is the one artefact that
+  // can outlive a rebuild indefinitely (issues #119, #120).
+  ".webmanifest.json": "application/manifest+json"
 };
 function resolveUiDistDir(env = process.env, from = import.meta.url) {
   const explicit = env["PI_CENTRAL_UI_DIST"];
@@ -2549,8 +2630,8 @@ var Transport = class {
             sessionId: control.sessionId,
             // As sent, for the same reason as `files`: one key for the client's bookkeeping.
             path: control.path,
-            text: result.value.text,
-            bytes: result.value.bytes
+            bytes: result.value.bytes,
+            content: result.value.kind === "image" ? { kind: "image", type: result.value.type, base64: result.value.data.toString("base64") } : { kind: "text", text: result.value.text }
           });
         } else {
           this.#broadcastFileError(control.sessionId, control.path, "read", result.error);
@@ -2634,6 +2715,54 @@ var Transport = class {
   }
 };
 
+// packages/orchestrator/src/startup-error.ts
+import { readFileSync as readFileSync6, statSync as statSync7 } from "node:fs";
+import { join as join12 } from "node:path";
+function explainStartupError(error, host, port) {
+  const code = error?.code;
+  if (code === "EADDRINUSE") {
+    return [
+      `Port ${port} is already in use on ${host}.`,
+      ``,
+      `That is almost always a Pi Central that is already running \u2014 and it is why this one did not`,
+      `start. If you were expecting the code you just rebuilt to be served, you are probably looking at`,
+      `the OLD process: its pages are still being served, and Node has its old modules cached.`,
+      ``,
+      `  Find it:   lsof -ti tcp:${port}`,
+      `  Stop it:   kill $(lsof -ti tcp:${port})`,
+      `  Or use another port:  --port <n>`
+    ].join("\n");
+  }
+  if (code === "EACCES") {
+    return [
+      `Permission denied binding ${host}:${port}.`,
+      ``,
+      `Ports below 1024 need elevated privileges on most systems, and Pi Central has no reason to want`,
+      `one \u2014 it is a local tool. Use a port above 1024:  --port 8788`
+    ].join("\n");
+  }
+  if (code === "EADDRNOTAVAIL") {
+    return [
+      `${host} is not an address this machine has.`,
+      ``,
+      `Pi Central binds loopback only (C5), so the host should be 127.0.0.1. A wrong host is usually a`,
+      `typo in --host or in PI_CENTRAL_HOST.`
+    ].join("\n");
+  }
+  return void 0;
+}
+function describeBuiltUi(uiDir) {
+  try {
+    const html = readFileSync6(join12(uiDir, "index.html"), "utf8");
+    const entry = /assets\/index-[A-Za-z0-9_-]+\.js/.exec(html)?.[0];
+    if (entry === void 0) return "(no entry bundle named in index.html)";
+    const { mtime } = statSync7(join12(uiDir, "index.html"));
+    return `${entry} (built ${mtime.toISOString().slice(0, 16).replace("T", " ")})`;
+  } catch {
+    return "(unreadable)";
+  }
+}
+
 // packages/orchestrator/src/sandbox-guard.ts
 import { spawnSync } from "node:child_process";
 function probeSandbox(execPath = "/usr/bin/sandbox-exec") {
@@ -2703,6 +2832,7 @@ Pi Central starts sessions with \`pi\` under Agent Safehouse. Run it from a PLAI
 Seatbelt does not nest, so a sandboxed shell cannot start a sandboxed session (C1).`);
 }
 var DEFAULT_PORT = 8787;
+var startupPort;
 function parseArgs(argv) {
   const options = {
     port: DEFAULT_PORT,
@@ -2744,6 +2874,7 @@ function parseArgs(argv) {
 }
 async function main() {
   const options = parseArgs(process.argv.slice(2));
+  startupPort = options.port;
   if (options.showVersion) {
     console.log(versionLine());
     return 0;
@@ -2789,6 +2920,7 @@ async function main() {
     console.log(`UI: not served (--no-ui). Use a dev server, or drop the flag to serve a build.`);
   } else if (hasBuiltUi(options.uiDir)) {
     console.log(`Open ${httpUrl} \u2014 the UI is served from ${options.uiDir}`);
+    console.log(`  UI build: ${describeBuiltUi(options.uiDir)}`);
   } else {
     console.log(
       `No built UI at ${options.uiDir}
@@ -2829,7 +2961,8 @@ main().then(
     if (code !== 0) process.exit(code);
   },
   (error) => {
-    console.error(`Pi Central failed to start: ${error.message}`);
+    const explained = explainStartupError(error, "127.0.0.1", startupPort ?? 0);
+    console.error(explained ?? `Pi Central failed to start: ${error.message}`);
     process.exit(1);
   }
 );