@timqi/pier 0.0.7 → 0.0.9

package/dist/web/server.js

@@ -37,7 +37,7 @@ export const withTabPrefix = (html, prefix) => prefix
 const HEARTBEAT_MS = 15_000;
 // Canonical base64 only: Buffer.from(.., "base64") happily "decodes" garbage.
 const BASE64_RE = /^[A-Za-z0-9+/]+={0,2}$/;
-export function createServer({ factory, router, hub, sessions: state, config, providers, settings, secrets, onUnlocked, reload, updates, updater, backgroundRuns, }) {
+export function createServer({ factory, router, hub, sessions: state, config, providers, settings, extensions, secrets, onUnlocked, reload, updates, updater, backgroundRuns, channelOf, }) {
     const app = new Hono();
     // A finished turn marks its session unread until some client reports it was
     // seen (session selected + tab visible → POST read below). Server-side so
@@ -77,11 +77,15 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         .finally(() => {
         listing = undefined;
     });
-    const present = (s, pinned, unread) => ({
+    // `order` is where the workbench was arranged to put this row, not a fact
+    // about the Pi session — it rides along so one Projects read is enough.
+    const present = (s, pinned, unread, order = {}) => ({
         ...s,
+        ...order,
         state: router.stateOf(s.id) ?? "idle",
         pinned,
         unread,
+        channel: channelOf?.(s.id) ?? "web",
         activeRuns: activeRuns(s.id),
     });
     app.get("/api/projects", async (c) => {
@@ -93,7 +97,27 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
             // happened to be unreadable. A later explicit full listing can repair it.
             projectBackfillNeeded = false;
         }
-        return c.json(state.projects().map((s) => present(s, true, s.unread)));
+        return c.json(state.projects().map(({ sort, projectSort, ...s }) => present(s, true, s.unread, { sort, projectSort })));
+    });
+    // One drag, one write of the list that changed: the projects, or one
+    // project's sessions. Whole lists rather than a move — the client has just
+    // rendered the result, and replaying a move on top of a stale list would put
+    // the row somewhere nobody dropped it.
+    app.post("/api/projects/order", async (c) => {
+        const body = await c.req.json().catch(() => null);
+        const list = (raw) => raw === undefined
+            ? undefined
+            : Array.isArray(raw) && raw.every((x) => typeof x === "string" && x)
+                ? raw
+                : null;
+        const sessions = list(body?.sessions);
+        const projects = list(body?.projects);
+        if (sessions === null || projects === null || (!sessions && !projects)) {
+            return c.json({ error: "sessions and/or projects must be lists of ids" }, 400);
+        }
+        state.reorder({ sessions, projects });
+        hub.emitWorkspace({ type: "sessions-changed" });
+        return c.json({ ok: true });
     });
     app.get("/api/sessions", async (c) => {
         const sessions = await listSessions();
@@ -106,7 +130,10 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         const flags = state.flags();
         return c.json([...[...nascent].map(([id, n]) => ({ id, ...n })), ...sessions].map((s) => {
             const row = flags.get(s.id);
-            return present(s, row?.pinned ?? false, row?.unread ?? false);
+            return present(s, row?.pinned ?? false, row?.unread ?? false, {
+                sort: row?.sort,
+                projectSort: row?.projectSort,
+            });
         }));
     });
     app.post("/api/sessions", async (c) => {
@@ -396,6 +423,7 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         updates,
         updater,
         secrets,
+        extensions,
         onUnlocked,
         onSettingsChanged: () => recycle("instance settings"),
     });
@@ -422,6 +450,9 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
     const prefix = tabPrefix(process.env.PIER_TITLE, hostname().split(".")[0] ?? "");
     let shell = null;
     app.get("/", async (c, next) => {
+        // A release replaces hashed assets. Revalidate the shell on every
+        // navigation so a cached index cannot name bundles that no longer exist.
+        c.header("cache-control", "private, no-cache");
         if (shell === null) {
             try {
                 shell = withTabPrefix(await readFile(join(bundle, "index.html"), "utf8"), prefix);
@@ -435,6 +466,22 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         }
         return c.html(shell);
     });
+    // Same reasoning as the shell above, for the one asset that is not hashed:
+    // an installed app keeps its worker until the script it re-fetches differs,
+    // so a cached copy is a released fix that never ships.
+    app.get("/sw.js", async (c, next) => {
+        c.header("cache-control", "private, no-cache");
+        await next();
+    });
+    // Hashed bundles never change under their name — a release writes new names,
+    // and the shell above is what re-points at them. Without this they carry only
+    // the auth layer's bare `private`, so a browser revalidates each one before it
+    // may reuse it: three round trips on a remote instance, one of them in front
+    // of the 636KB terminal emulator, every time the workbench is opened.
+    app.get("/assets/*", async (c, next) => {
+        c.header("cache-control", "private, max-age=31536000, immutable");
+        await next();
+    });
     app.use("/*", serveStatic({ root: relative(process.cwd(), bundle) || "." }));
     return app;
 }

package/dist/web/session-state.js

@@ -22,26 +22,53 @@ export class SessionStateStore {
     }
     /** Pin plus the summary Projects needs, atomically in one row. */
     pin(summary, pinned) {
-        this.#db.prepare(`INSERT INTO session_state(session_id, pinned, cwd, title, created_at)
-       VALUES (?, ?, ?, ?, ?)
+        // A new session joins a project that already has a place in the list.
+        // Unranked it would sort on top — lifting the whole project with it, which
+        // is the jump manual order exists to stop.
+        const sibling = this.#db.prepare("SELECT project_sort AS rank FROM session_state WHERE cwd = ? AND project_sort IS NOT NULL LIMIT 1").get(summary.cwd);
+        this.#db.prepare(`INSERT INTO session_state(session_id, pinned, cwd, title, created_at, project_sort)
+       VALUES (?, ?, ?, ?, ?, ?)
        ON CONFLICT(session_id) DO UPDATE SET
          pinned = excluded.pinned,
          cwd = excluded.cwd,
          title = COALESCE(excluded.title, session_state.title),
-         created_at = excluded.created_at`).run(summary.id, pinned ? 1 : 0, summary.cwd, summary.title ?? null, summary.createdAt);
+         created_at = excluded.created_at,
+         project_sort = COALESCE(session_state.project_sort, excluded.project_sort)`).run(summary.id, pinned ? 1 : 0, summary.cwd, summary.title ?? null, summary.createdAt, sibling?.rank ?? null);
+    }
+    /** One drag = one write of the whole list it reordered: index is the place.
+     *  `sessions` are ids (a session's place inside its project), `projects` are
+     *  cwds, whose place is stamped on every session that has that cwd. */
+    reorder(order) {
+        const bySession = this.#db.prepare("UPDATE session_state SET sort = ? WHERE session_id = ?");
+        const byCwd = this.#db.prepare("UPDATE session_state SET project_sort = ? WHERE cwd = ?");
+        this.#tx(() => {
+            order.sessions?.forEach((id, i) => bySession.run(i, id));
+            order.projects?.forEach((cwd, i) => byCwd.run(i, cwd));
+        });
     }
     /** Project rows only; unlike AgentFactory.list(), this never touches disk. */
     projects() {
-        const rows = this.#db.prepare(`SELECT session_id AS id, cwd, title, created_at AS createdAt, unread
+        const rows = this.#db.prepare(`SELECT session_id AS id, cwd, title, created_at AS createdAt, unread,
+              sort, project_sort AS projectSort
        FROM session_state
        WHERE pinned = 1 AND cwd IS NOT NULL AND created_at IS NOT NULL
        ORDER BY created_at DESC`).all();
-        return rows.map(({ title, unread, ...row }) => ({
+        return rows.map(({ title, unread, sort, projectSort, ...row }) => ({
             ...row,
             ...(title ? { title } : {}),
+            ...(sort === null ? {} : { sort }),
+            ...(projectSort === null ? {} : { projectSort }),
             unread: unread === 1,
         }));
     }
+    /** What to call a session where there is room for one line — a push
+     *  notification's title. Falls back to the project directory, then to the
+     *  fact that it is a session at all: a notification with no title reads as a
+     *  browser bug rather than as an unnamed session. */
+    name(sessionId) {
+        const row = this.#db.prepare("SELECT title, cwd FROM session_state WHERE session_id = ?").get(sessionId);
+        return row?.title || row?.cwd?.split("/").filter(Boolean).at(-1) || "Pier session";
+    }
     needsProjectBackfill() {
         return this.#db.prepare("SELECT 1 FROM session_state WHERE pinned = 1 AND (cwd IS NULL OR created_at IS NULL) LIMIT 1").get() !== undefined;
     }
@@ -50,10 +77,16 @@ export class SessionStateStore {
         const update = this.#db.prepare(`UPDATE session_state SET
          cwd = ?, title = COALESCE(?, title), created_at = ?
        WHERE session_id = ?`);
-        this.#db.exec("BEGIN");
-        try {
+        this.#tx(() => {
             for (const s of summaries)
                 update.run(s.cwd, s.title ?? null, s.createdAt, s.id);
+        });
+    }
+    /** All-or-nothing: a half-written order is a list nobody arranged. */
+    #tx(run) {
+        this.#db.exec("BEGIN");
+        try {
+            run();
             this.#db.exec("COMMIT");
         }
         catch (err) {
@@ -62,8 +95,14 @@ export class SessionStateStore {
         }
     }
     flags() {
-        const rows = this.#db.prepare("SELECT session_id AS id, pinned, unread FROM session_state WHERE pinned = 1 OR unread = 1").all();
-        return new Map(rows.map((r) => [r.id, { pinned: r.pinned === 1, unread: r.unread === 1 }]));
+        const rows = this.#db.prepare(`SELECT session_id AS id, pinned, unread, sort, project_sort AS projectSort
+       FROM session_state WHERE pinned = 1 OR unread = 1`).all();
+        return new Map(rows.map((r) => [r.id, {
+                pinned: r.pinned === 1,
+                unread: r.unread === 1,
+                ...(r.sort === null ? {} : { sort: r.sort }),
+                ...(r.projectSort === null ? {} : { projectSort: r.projectSort }),
+            }]));
     }
     /** The first prompt supplies the title of a newly-created pinned session. */
     title(sessionId, text) {

package/dist/web/terminal.js

@@ -28,6 +28,15 @@ const MAX_FRAME_BYTES = 1024 * 1024;
 // start under. Inheriting these can attach the shell back into Pier's parent
 // tmux session; SSH_AUTH_SOCK deliberately stays so git/ssh keep working.
 const PARENT_TERMINAL_ENV = ["TMUX", "TMUX_PANE", "SSH_TTY", "SSH_CLIENT", "SSH_CONNECTION"];
+// Pier's own configuration is Pier's, not this shell's. `NODE_ENV=production`
+// alone turns an `npm i` typed here into an install with no dev dependencies,
+// and every `PI_*`/`PIER_*` would point a `pi` started here at Pier's own
+// instance rather than the person's. Everything else is inherited on purpose:
+// PATH, LANG, SSH_AUTH_SOCK and the session's XDG/DBUS handles are what make
+// the shell usable, and on a service-managed instance nothing else supplies
+// them.
+const PIER_OWN_ENV = ["NODE_ENV", "PORT", "HOST"];
+const PIER_OWN_PREFIX = /^PI(ER)?_/;
 const send = (sock, data) => {
     try {
         sock.send(data);
@@ -44,6 +53,7 @@ export class TerminalHub {
     #shell;
     #idleMs;
     #maxTerms;
+    #initCommand;
     #sweeper;
     #closeListeners = new Set();
     #closed = false;
@@ -51,6 +61,7 @@ export class TerminalHub {
         this.#shell = opts.shell ?? process.env.SHELL ?? "/bin/bash";
         this.#idleMs = opts.idleMs ?? IDLE_MS;
         this.#maxTerms = opts.maxTerms ?? MAX_TERMS;
+        this.#initCommand = opts.initCommand ?? (() => "");
         this.#sweeper = setInterval(() => this.sweep(Date.now()), SWEEP_MS);
         this.#sweeper.unref();
     }
@@ -117,8 +128,11 @@ export class TerminalHub {
     }
     #spawn(cwd) {
         const env = { ...process.env };
-        for (const key of PARENT_TERMINAL_ENV)
-            delete env[key];
+        for (const key of Object.keys(env)) {
+            if (PARENT_TERMINAL_ENV.includes(key) || PIER_OWN_ENV.includes(key) || PIER_OWN_PREFIX.test(key)) {
+                delete env[key];
+            }
+        }
         const pty = spawn(this.#shell, [], {
             name: "xterm-256color",
             cols: 120,
@@ -129,6 +143,14 @@ export class TerminalHub {
         const term = { pty, ring: [], ringBytes: 0, clients: new Set(), idleSince: Infinity };
         this.#terms.set(cwd, term);
         log.info(`shell ${pty.pid} for ${cwd}`);
+        // Typed in, not exec'd: the shell stays the parent, so quitting whatever
+        // this starts leaves a usable prompt, and the echo plus any error is in
+        // the ring where the person can see what ran. The tty buffers it until the
+        // shell's first read, so no wait is needed. A reattach never repeats it —
+        // this runs once per pty, which is once per cwd.
+        const init = this.#initCommand().trim();
+        if (init)
+            pty.write(`${init}\r`);
         pty.onData((data) => {
             const chunk = Buffer.from(data);
             term.ring.push(chunk);
@@ -179,6 +201,13 @@ export class TerminalHub {
             term.pty.write(msg.d);
             return;
         }
+        // The only way a page can end a shell: everything attached to it is told by
+        // the exit path below, exactly as if the shell had exited on its own.
+        if (msg.t === "restart") {
+            log.info(`shell ${term.pty.pid} for ${cwd} killed on request`);
+            term.pty.kill();
+            return;
+        }
         if (msg.t === "resize" &&
             typeof msg.cols === "number" && typeof msg.rows === "number" &&
             Number.isInteger(msg.cols) && Number.isInteger(msg.rows) &&
@@ -225,8 +254,9 @@ export class TerminalHub {
 /** The upgrade seam: `/api/terminal?cwd=…` behind the same password boundary
  *  as every route. SameSite=Lax already withholds the cookie cross-site; the
  *  Origin check is the explicit copy of that fact. */
-export function attachTerminal(server, auth, heartbeatMs = HEARTBEAT_MS) {
-    const hub = new TerminalHub();
+export function attachTerminal(server, auth, opts = {}) {
+    const heartbeatMs = opts.heartbeatMs ?? HEARTBEAT_MS;
+    const hub = new TerminalHub(opts);
     const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_FRAME_BYTES });
     const alive = new WeakSet();
     const heartbeat = setInterval(() => {

package/dist/web/webpush.js

@@ -0,0 +1,131 @@
+// The Web Push wire format, and only that: RFC 8291 message encryption
+// (ECDH P-256 → HKDF → one aes128gcm record) and RFC 8292 VAPID
+// authorization. Who is notified, and why, is push.ts.
+//
+// Written on node:crypto instead of pulled in: the whole format is one ECDH,
+// two HKDFs, one AES-GCM record and a JWT, and every step of it has a
+// published test vector (webpush.test.ts runs the RFC's). A dependency here
+// would be new transitive code inside the process that holds the operator's
+// provider keys, buying ~120 lines (principle 8).
+import { createCipheriv, createECDH, createPrivateKey, hkdfSync, randomBytes, sign } from "node:crypto";
+/** RFC 8291 §4: one record, and a push service need not accept more than 4096
+ *  octets of body. Header (86) + padding (1) + GCM tag (16) leaves this. */
+export const MAX_PUSH_PLAINTEXT = 3993;
+const RECORD_SIZE = 4096;
+/** VAPID token lifetime. Apple refuses anything past 24h; half a day is well
+ *  inside every push service's limit and still outlives a slow retry. */
+const TOKEN_TTL_S = 12 * 60 * 60;
+const REQUEST_TIMEOUT_MS = 10_000;
+const b64 = (b) => Buffer.from(b instanceof ArrayBuffer ? new Uint8Array(b) : b).toString("base64url");
+const unb64 = (s) => Buffer.from(s, "base64url");
+/** A P-256 scalar is 32 octets; OpenSSL hands back the minimal encoding, so a
+ *  key with a zero high byte is one octet short of what JWK accepts. */
+const pad32 = (b) => b.length >= 32 ? b : Buffer.concat([Buffer.alloc(32 - b.length), b]);
+export function generateVapidKeys() {
+    const ecdh = createECDH("prime256v1");
+    ecdh.generateKeys();
+    return {
+        publicKey: b64(ecdh.getPublicKey()),
+        privateKey: b64(pad32(ecdh.getPrivateKey())),
+    };
+}
+/**
+ * Encrypt one push message for `target` (RFC 8291 §3.4, RFC 8188 header).
+ *
+ * `salt` and `serverKey` are injectable for exactly one reason: the RFC's
+ * worked example is the only way to prove this implementation is right, and it
+ * fixes both. Nothing else may pass them — a reused salt is a broken cipher.
+ */
+export function encryptPush(plaintext, target, { salt = randomBytes(16), serverKey } = {}) {
+    const body = Buffer.from(plaintext);
+    if (body.length > MAX_PUSH_PLAINTEXT) {
+        throw new Error(`push payload is ${String(body.length)} bytes, over ${String(MAX_PUSH_PLAINTEXT)}`);
+    }
+    const uaPublic = unb64(target.p256dh);
+    const ecdh = createECDH("prime256v1");
+    // computeSecret() rejects a point that is not on the curve, which is the
+    // validation RFC 8291 §7 asks for before a private key touches it.
+    if (serverKey)
+        ecdh.setPrivateKey(serverKey);
+    else
+        ecdh.generateKeys();
+    const asPublic = ecdh.getPublicKey();
+    const shared = ecdh.computeSecret(uaPublic);
+    const keyInfo = Buffer.concat([Buffer.from("WebPush: info\0"), uaPublic, asPublic]);
+    const ikm = Buffer.from(hkdfSync("sha256", shared, unb64(target.auth), keyInfo, 32));
+    const cek = Buffer.from(hkdfSync("sha256", ikm, salt, Buffer.from("Content-Encoding: aes128gcm\0"), 16));
+    const nonce = Buffer.from(hkdfSync("sha256", ikm, salt, Buffer.from("Content-Encoding: nonce\0"), 12));
+    const cipher = createCipheriv("aes-128-gcm", cek, nonce);
+    // 0x02 is the padding delimiter of the last (here: only) record.
+    const sealed = Buffer.concat([
+        cipher.update(Buffer.concat([body, Buffer.of(2)])),
+        cipher.final(),
+        cipher.getAuthTag(),
+    ]);
+    const header = Buffer.alloc(21);
+    salt.copy(header);
+    header.writeUInt32BE(RECORD_SIZE, 16);
+    header.writeUInt8(asPublic.length, 20);
+    return Buffer.concat([header, asPublic, sealed]);
+}
+/** The `Authorization` a push service checks before it accepts anything: a
+ *  short-lived ES256 JWT bound to the service's own origin, plus the public
+ *  key the subscription was created with (RFC 8292 §3). */
+export function vapidAuthorization(endpoint, keys, subject, now = Date.now()) {
+    const token = [
+        b64(Buffer.from(JSON.stringify({ typ: "JWT", alg: "ES256" }))),
+        b64(Buffer.from(JSON.stringify({
+            aud: new URL(endpoint).origin,
+            exp: Math.floor(now / 1000) + TOKEN_TTL_S,
+            sub: subject,
+        }))),
+    ].join(".");
+    const pub = unb64(keys.publicKey);
+    const key = createPrivateKey({
+        format: "jwk",
+        key: {
+            kty: "EC",
+            crv: "P-256",
+            x: b64(pub.subarray(1, 33)),
+            y: b64(pub.subarray(33, 65)),
+            d: b64(pad32(unb64(keys.privateKey))),
+        },
+    });
+    // JOSE wants the raw r||s pair; node's default for EC keys is DER.
+    const signature = sign("sha256", Buffer.from(token), { key, dsaEncoding: "ieee-p1363" });
+    return `vapid t=${token}.${b64(signature)}, k=${keys.publicKey}`;
+}
+/** POST one encrypted message. Never throws: every outcome is a result the
+ *  caller can log or act on. */
+export async function sendPush(target, payload, keys, subject, ttlSeconds = 4 * 60 * 60, fetchImpl = fetch) {
+    let body;
+    try {
+        body = encryptPush(payload, target);
+    }
+    catch (err) {
+        return { status: 0, error: `encrypting failed: ${String(err)}` };
+    }
+    try {
+        const res = await fetchImpl(target.endpoint, {
+            method: "POST",
+            headers: {
+                authorization: vapidAuthorization(target.endpoint, keys, subject),
+                "content-encoding": "aes128gcm",
+                "content-type": "application/octet-stream",
+                ttl: String(ttlSeconds),
+                urgency: "normal",
+            },
+            body: new Uint8Array(body),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (res.ok)
+            return { status: res.status };
+        // The service's own sentence is the only thing that explains a 400 from
+        // Apple or a 403 from FCM; without it the operator sees a bare number.
+        const said = (await res.text().catch(() => "")).slice(0, 200);
+        return { status: res.status, error: said || res.statusText };
+    }
+    catch (err) {
+        return { status: 0, error: String(err) };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timqi/pier",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "A self-hosted workspace for coding agents: web workbench and IM channels in front of Pi sessions",
   "license": "AGPL-3.0-only",
   "repository": "github:timqi/pier",

package/skills/pier-help/SKILL.md

@@ -71,6 +71,18 @@ operator's source of truth.
   (Telegram ~3.8k chars); the footer and the next-step buttons ride the last
   one.
 
+## Notifications on the web
+
+- The workbench can push a notification when a turn finishes and no client
+  had that session on screen — Settings → Instance → Notifications, per
+  browser. Chrome and Edge on desktop work in a tab; **iPhone and iPad only
+  notify the installed app**, so it is Share → Add to Home Screen first, then
+  enable it from the icon's window. A "Send a test notification" button in the
+  same card answers whether it actually arrives.
+- Pier is installable (an **Install Pier** button appears in that same card on
+  Chrome and Edge; elsewhere it is the address-bar icon), and an installed
+  Pier badges its icon with the number of sessions carrying an unread turn.
+
 ## Who may talk (groups and binding)
 
 - Group messages pass a per-chat gate the operator sets: it can require a