@timqi/pier 0.0.17 → 0.0.20

package/dist/web/server.js

@@ -1,8 +1,9 @@
 // Web workbench backend: REST + SSE, a pure consumer of core.
 // See docs/design/03-web-workbench.md for the route contract.
 import { hostname } from "node:os";
-import { readFile } from "node:fs/promises";
-import { join, relative } from "node:path";
+import { randomUUID } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import { isAbsolute, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { serveStatic } from "@hono/node-server/serve-static";
 import { Hono } from "hono";
@@ -10,18 +11,31 @@ import { compress } from "hono/compress";
 import { streamSSE } from "hono/streaming";
 import { EventHub } from "../core/hub.js";
 import { logger } from "../log.js";
-import { Router } from "../core/router.js";
+import { QueueOperationError, Router } from "../core/router.js";
+import { registerConfigRoutes } from "./config.js";
 import { registerExplorerRoutes } from "./explorer.js";
-import { guarded, registerFileRoutes } from "./files.js";
+import { fileHeaders, MAX_FILE_BYTES, registerFsRoutes, scopedFile } from "./fs.js";
+import { guarded } from "./route.js";
 import { isThinkingLevel } from "../core/types.js";
 import { SESSION_TITLE_MAX } from "../limits.js";
-import { saveInbound } from "../core/inbox.js";
+import { INBOX_DIR, saveInbound } from "../core/inbox.js";
 import { MAX_INBOUND_BYTES } from "../core/inbound-file.js";
 import { RepoIndex } from "./repos.js";
 import {} from "./session-state.js";
 import { registerInstanceRoutes } from "./instance.js";
 import { registerProviderRoutes } from "./providers.js";
 const log = logger("web");
+async function queueResponse(action, status = 200) {
+    try {
+        return Response.json(await action(), { status });
+    }
+    catch (err) {
+        const code = err instanceof QueueOperationError
+            ? err.reason === "draining" ? 503 : err.reason === "missing" ? 404 : 409
+            : 404;
+        return Response.json({ error: String(err) }, { status: code });
+    }
+}
 /** A transcript without the bytes nobody has asked to see yet. A step's `args`
  *  and `output` are ~90% of a long session's snapshot and sit inside a
  *  collapsed group; the client fetches one turn's worth when it is opened. */
@@ -38,10 +52,26 @@ export const withTabPrefix = (html, prefix) => prefix
     ? html.replace("<title>Pier</title>", `<title>${prefix.replace(/&/g, "&amp;").replace(/</g, "&lt;")} - Pier</title>`)
     : html;
 const HEARTBEAT_MS = 15_000;
+/** A reader that stopped reading must not queue frames without bound. Past
+ *  this much frame text in flight the stream is dropped with a line in the
+ *  log; EventSource reconnects and replays from its Last-Event-ID. */
+const SSE_HIGH_WATER = 4 * 1024 * 1024;
 // 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, catalog, names, onToolsChanged, validateCustomTools, secrets, onUnlocked, reload, updates, updater, backgroundRuns, channelOf, }) {
+export function createServer({ factory, router, hub, sessions: state, config, providers, settings, catalog, names, onToolsChanged, validateCustomTools, secrets, onUnlocked, reload, updates, updater, backgroundRuns, activeBackgroundRunCounts, channelOf, }) {
     const app = new Hono();
+    const epoch = randomUUID();
+    // One frame shared by synchronous fan-out to every watching tab. The epoch
+    // and wire encoding stay here; core only stamps transport-blind events.
+    let lastEvent = null;
+    let lastFrame = "";
+    const sseFrame = (e) => {
+        if (e !== lastEvent) {
+            lastEvent = e;
+            lastFrame = `data: ${JSON.stringify(e)}\nid: ${epoch}:${e.seq}\n\n`;
+        }
+        return lastFrame;
+    };
     // A finished turn marks its session unread until some client reports it was
     // seen (session selected + tab visible → POST read below). Server-side so
     // every client shows the same attention state. Streaming → idle is the
@@ -62,8 +92,10 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
     });
     // Repository identity per project directory, refreshed off the request path.
     const repos = new RepoIndex(() => hub.emitWorkspace({ type: "sessions-changed" }));
-    /** Background runs this session launched that are still in flight. */
-    const activeRuns = (id) => backgroundRuns?.(id).filter((r) => r.state === "queued" || r.state === "running").length ?? 0;
+    /** Background runs still in flight, per launching session. One query for a
+     *  whole list: asking row by row loaded every run object of every session to
+     *  draw one dot each. */
+    const activeRuns = () => activeBackgroundRunCounts?.() ?? new Map();
     /** The web channel's session for `id` — every session route resolves here. */
     const ensure = (id) => router.ensure({ channelId: "web", conversationId: id });
     // Sessions created here that Pi doesn't list yet — it persists a session
@@ -118,7 +150,7 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
     // decided about it, and what is true of it right now.
     // The listing's `modified` is dropped rather than forwarded: it dates a
     // transcript, and no surface renders it.
-    const present = ({ modified: _drop, ...s }, own) => {
+    const present = ({ modified: _drop, ...s }, own, active) => {
         return {
             ...s,
             ...(own?.sort === undefined ? {} : { sort: own.sort }),
@@ -133,7 +165,7 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
             listed: own?.pinned ?? false,
             unread: own?.unread ?? false,
             channel: channelOf?.(s.id) ?? "web",
-            activeRuns: activeRuns(s.id),
+            activeRuns: active.get(s.id) ?? 0,
         };
     };
     // The rail: the same rows as the full list, minus everything Projects is not
@@ -141,8 +173,9 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
     // the summaries out of SQLite, which is what had to be kept in step.
     app.get("/api/projects", async (c) => {
         const flags = state.flags();
+        const active = activeRuns();
         return c.json((await allSessions())
-            .map((s) => present(s, flags.get(s.id)))
+            .map((s) => present(s, flags.get(s.id), active))
             .filter((row) => row.listed));
     });
     // One drag, one write of the list that changed: the projects, or one
@@ -167,7 +200,8 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
     });
     app.get("/api/sessions", async (c) => {
         const flags = state.flags();
-        return c.json((await allSessions()).map((s) => present(s, flags.get(s.id))));
+        const active = activeRuns();
+        return c.json((await allSessions()).map((s) => present(s, flags.get(s.id), active)));
     });
     app.post("/api/sessions", async (c) => {
         const body = await c.req.json().catch(() => ({}));
@@ -219,16 +253,28 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
     guarded(app, "GET", "/api/sessions/:id/history", 404, async (c) => {
         const id = c.req.param("id");
         const session = await ensureLoadable(id);
-        return c.json({
-            turns: (await session.history()).map(slim),
-            lastSeq: hub.lastSeq(id),
-            model: session.model ?? null,
-            state: session.state,
-            context: session.contextUsage ?? null,
-            thinkingLevel: session.thinkingLevel,
-            queue: await session.pendingQueue(),
-            backgroundRuns: backgroundRuns?.(id) ?? [],
-        });
+        // Async seam reads can straddle an event. Never label older content with a
+        // newer cursor, and never spin indefinitely if the session stays busy.
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const lastSeq = hub.lastSeq(id);
+            const turns = (await session.history()).map(slim);
+            const queue = await session.pendingQueue();
+            if (hub.lastSeq(id) !== lastSeq)
+                continue;
+            return c.json({
+                turns, lastSeq, epoch,
+                model: session.model ?? null,
+                state: session.state,
+                context: session.contextUsage ?? null,
+                thinkingLevel: session.thinkingLevel,
+                queue,
+                queueRecovery: router.recoveryOf(id),
+                queueUncertain: router.queueUncertain(id),
+                backgroundRuns: backgroundRuns?.(id) ?? [],
+            });
+        }
+        log.warn(`snapshot for ${id} changed during all 3 reads`);
+        return c.json({ error: "Session changed while loading history; retry loading the session" }, 503);
     });
     // One turn's activity in full, for the group the user just opened. Indexed
     // like the edit route below; the steps carry their own id and tool name so a
@@ -245,6 +291,29 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         // hands back what a surface shows, not the untruncated tool result.
         return c.json({ steps: turn.steps ?? [] });
     });
+    // Attachments, both directions: the agent links a file it produced, the chat
+    // renders a file the user sent. Read-only, and only from the session's own
+    // cwd or the inbox inbound files land in (core/inbox.ts) — a session route
+    // rather than an /api/fs one, because the session *is* the scope here.
+    guarded(app, "GET", "/api/sessions/:id/files", 400, async (c) => {
+        const raw = c.req.query("path");
+        if (!raw)
+            return c.json({ error: "path required" }, 400);
+        const id = c.req.param("id");
+        const cwd = nascent.get(id)?.cwd ?? (await factory.find(id))?.cwd;
+        // Absolute only: a link into a session's files is written by the agent or
+        // by Pier, and neither of them writes a path relative to anything.
+        const file = cwd && isAbsolute(raw) ? await scopedFile([cwd, INBOX_DIR], raw) : null;
+        if (!file)
+            return c.json({ error: "no such file" }, 404);
+        if ((await stat(file)).size > MAX_FILE_BYTES)
+            return c.json({ error: "file too large" }, 413);
+        const bytes = await readFile(file);
+        return c.body(bytes, 200, {
+            ...fileHeaders(file, bytes, c.req.query("download") === "1"),
+            "cache-control": "private, max-age=60",
+        });
+    });
     // Composer attachments: bytes land in the inbox, the message carries the
     // path as a `[name](file:///…)` line the client builds itself — upload
     // first, so the text it sends (and optimistically renders) is final.
@@ -354,8 +423,8 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         return c.json({ ok: true }, 202);
     });
     // Promote queued messages: "steer" delivers them into the running turn,
-    // "restart" aborts the turn and sends them as a fresh prompt. Pi has no
-    // promote primitive, so this is clear-queue + re-dispatch through core.
+    // "restart" aborts the turn and sends them as a fresh prompt. Core owns
+    // exclusion and retains originals through the asynchronous handoff.
     guarded(app, "POST", "/api/sessions/:id/queue/deliver", 404, async (c) => {
         const id = c.req.param("id");
         const body = await c.req.json().catch(() => null);
@@ -363,38 +432,20 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         if (mode !== "steer" && mode !== "restart") {
             return c.json({ error: "mode must be steer or restart" }, 400);
         }
-        // Same reason as edit above: a refused dispatch must not cost the queue.
-        if (router.isDraining())
-            return c.json({ error: "Pier is restarting — try again in a moment" }, 503);
-        const session = await ensure(id);
-        const { steering, followUp } = await session.clearQueue();
-        const text = [...steering, ...followUp].join("\n").trim();
-        if (!text)
-            return c.json({ error: "queue is empty" }, 409);
-        if (mode === "restart")
-            await router.abort(id); // resolves once idle
-        // No sender here, unlike the other dispatches: the queued texts were
-        // headed when they were first dispatched — and in a shared session they
-        // are other speakers' words, which an operator header would claim.
-        await router.dispatch({
-            key: { channelId: "web", conversationId: id },
-            senderId: "web",
-            text,
-            mode: mode === "steer" ? "steer" : "auto",
-        });
-        return c.json({ delivered: text }, 202);
+        return queueResponse(async () => ({ submitted: await router.deliverQueue(id, mode) }), 202);
     });
     // Recall: drop all pending queued messages and hand them back (composer restore).
     guarded(app, "POST", "/api/sessions/:id/queue/recall", 404, async (c) => {
         const id = c.req.param("id");
-        const session = await ensure(id);
-        const { steering, followUp } = await session.clearQueue();
-        // Those messages carried the header that told the session who is speaking,
-        // and they are going back to the composer instead of to the model.
-        if (steering.length || followUp.length)
-            router.forgetSender(id);
-        return c.json({ messages: [...steering, ...followUp] });
+        return queueResponse(async () => {
+            const { steering, followUp } = await router.recallQueue(id);
+            return { messages: [...steering, ...followUp] };
+        });
     });
+    guarded(app, "POST", "/api/sessions/:id/queue/recovery/:batchId/ack", 404, async (c) => queueResponse(async () => {
+        router.acknowledgeRecovery(c.req.param("id"), c.req.param("batchId"));
+        return { ok: true };
+    }));
     // Shrink the context on demand: Pi summarizes the older transcript away and
     // the session continues from the summary. Refused while streaming, like the
     // edit route above and for the same reason — Pi's own compaction aborts a
@@ -446,16 +497,40 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
     }));
     app.get("/api/sessions/:id/events", (c) => {
         const id = c.req.param("id");
-        const lastId = Number(c.req.header("Last-Event-ID") ?? "") ||
-            Number(c.req.query("after") ?? "") ||
-            0;
+        const cursor = c.req.header("Last-Event-ID") ?? c.req.query("after") ?? "";
+        const match = /^([^:]+):(0|[1-9]\d*)$/.exec(cursor);
+        const lastId = match ? Number(match[2]) : NaN;
         return streamSSE(c, async (stream) => {
-            const send = (e) => stream.writeSSE({ id: String(e.seq), data: JSON.stringify(e) });
-            for (const e of hub.replay(id, lastId))
-                await send(e);
-            // Same as above: the client may be gone by the time an event fires.
-            const unsubscribe = hub.subscribe(id, (e) => void send(e).catch(() => { }));
+            if (match?.[1] !== epoch || !hub.covers(id, lastId)) {
+                await stream.writeSSE({ event: "reset", data: "snapshot required" });
+                return;
+            }
+            let queued = 0; // frame chars written but not yet drained by the reader
+            const send = (frame) => {
+                if (stream.aborted || stream.closed)
+                    return;
+                if (queued > SSE_HIGH_WATER) {
+                    log.warn(`dropping slow event client for ${id} — ${queued} chars queued`);
+                    stream.abort(); // unsubscribes; the client reconnects and replays
+                    return;
+                }
+                queued += frame.length;
+                void stream
+                    .write(frame)
+                    .catch((err) => log.warn(`event write for ${id} failed: ${String(err)}`))
+                    .finally(() => (queued -= frame.length));
+            };
+            // Subscribe before the replay write can wait on its reader: an event that
+            // arrives while that write is backpressured must queue behind it, not fall
+            // between replay() and subscribe(). Both snapshots happen synchronously,
+            // so live writes cannot overtake the replay write.
+            const unsubscribe = hub.subscribe(id, (e) => send(sseFrame(e)));
             stream.onAbort(unsubscribe);
+            // One write for the whole replay: a reconnect after a busy turn used to
+            // cost an await per event before the client saw any of them.
+            const missed = hub.replay(id, lastId);
+            if (missed.length)
+                await stream.write(missed.map(sseFrame).join(""));
             // Heartbeat keeps proxies from closing the stream; loop ends on abort.
             while (!stream.aborted) {
                 await stream.sleep(HEARTBEAT_MS);
@@ -509,12 +584,8 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         onSettingsChanged: () => recycle("instance settings"),
     });
     registerProviderRoutes(app, providers, () => recycle("provider configuration"));
-    registerFileRoutes(app, {
-        factory,
-        config,
-        nascentCwd: (id) => nascent.get(id)?.cwd,
-        onConfigWritten: () => recycle("an agent file"),
-    });
+    registerConfigRoutes(app, { factory, config, onConfigWritten: () => recycle("an agent file") });
+    registerFsRoutes(app);
     registerExplorerRoutes(app);
     // serveStatic resolves `root` against the *working directory*, and an
     // installed Pier is started from wherever the operator happens to be. The
@@ -530,6 +601,11 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
     // at /login learns neither. Read once: neither can change under a process.
     const prefix = tabPrefix(process.env.PIER_TITLE, hostname().split(".")[0] ?? "");
     let shell = null;
+    // The one file the precompressed siblings below cannot cover: this route
+    // answers from the patched string, not from disk, and it is re-fetched on
+    // every navigation because it may not be cached. Exact path, like the two
+    // API routes above — never the SSE streams.
+    app.use("/", compress());
     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.
@@ -563,6 +639,16 @@ export function createServer({ factory, router, hub, sessions: state, config, pr
         c.header("cache-control", "private, max-age=31536000, immutable");
         await next();
     });
-    app.use("/*", serveStatic({ root: relative(process.cwd(), bundle) || "." }));
+    // `precompressed` looks for a `.br`/`.gz` sibling of the file it is about to
+    // serve and hands that over when the request accepts the encoding; the build
+    // writes them (vite.config.ts). Without it the 325 kB bundle, the 87 kB
+    // stylesheet and the 636 kB terminal emulator all go out verbatim.
+    // serveStatic only sets Vary when it selects a sibling. Identity must carry
+    // it too, or a cache can reuse that response for a later Brotli request.
+    app.use("/*", async (c, next) => {
+        await next();
+        c.header("Vary", "Accept-Encoding");
+    });
+    app.use("/*", serveStatic({ root: relative(process.cwd(), bundle) || ".", precompressed: true }));
     return app;
 }

package/dist/web/terminal.js

@@ -6,11 +6,10 @@
 // to survive that — durability is tmux's job, not ours). This is the one
 // WebSocket surface: a keystroke is a round trip, which SSE cannot carry
 // upstream. Everything else stays on the event stream.
-import { realpath, stat } from "node:fs/promises";
-import { isAbsolute } from "node:path";
 import { spawn } from "node-pty";
 import { WebSocketServer } from "ws";
 import { logger } from "../log.js";
+import { scoped } from "./fs.js";
 import { ALL, upgradeAuthorized } from "./auth.js";
 const log = logger("terminal");
 /** Live shells at once — a guard against forgotten spawns, not a quota. */
@@ -71,11 +70,7 @@ export class TerminalHub {
     async attach(cwd, sock) {
         let key;
         try {
-            if (!isAbsolute(cwd))
-                throw new Error("cwd must be an absolute directory");
-            key = await realpath(cwd);
-            if (!(await stat(key)).isDirectory())
-                throw new Error("cwd must be an absolute directory");
+            key = await scoped(cwd); // absolute, real, and a directory — or it throws
         }
         catch (err) {
             control(sock, { t: "error", message: String(err) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timqi/pier",
-  "version": "0.0.17",
+  "version": "0.0.20",
   "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",
@@ -44,7 +44,7 @@
     "vitest": "^4.1.11"
   },
   "dependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
     "@hono/node-server": "^2.1.1",
     "@larksuiteoapi/node-sdk": "^1.73.0",
     "croner": "^10.0.1",

package/skills/pier-slack/SKILL.md

@@ -24,20 +24,13 @@ this: there is no current conversation and `channel` is required.
 
 `{"operation":"channels"}` lists what Pier can reach (`id`, `name`, `kind`,
 `respondsToMessages`); pass either an id or a `#name` anywhere a channel is
-wanted. `not_in_channel` means someone must run `/invite @Pier`.
+wanted.
 
 ## Never ask for an id
 
-You already have them:
-
-- **The person talking to you** — a message may start with `[name<id> time]`,
-  added by Pier, not typed by them. It appears only on a change — new speaker,
-  a time gap, a new day — so the last one you saw still applies (a gap alone
-  shows as time only, like `[14:23]`).
-- **Anyone in a transcript** — every line carries `name[id]`.
-- **This channel and thread** — from `context`.
-
-Asking a human to paste their own user ID is never acceptable.
+You already have them: the sender header on the message you are answering,
+`name[id]` on every line of a transcript, and `context` for this channel and
+thread. Asking a human to paste their own user ID is never acceptable.
 
 ## Reading
 
@@ -107,8 +100,6 @@ The response carries `ts` and `threadTs` for replying under what you posted.
 `text` replaces the message outright; there is no partial edit. Read the
 message first if you are changing part of it.
 
-- Slack only lets Pier edit what **its own bot** posted — anyone else's message
-  answers `cant_update_message`, and the answer is to reply, not to retry.
 - `ts` is always explicit, as with `delete`, and means nothing outside the
   channel it was read in.
 - The old text is gone — Slack keeps no version a reader can open, and may not
@@ -123,9 +114,6 @@ message first if you are changing part of it.
 {"operation":"delete","channel":"#ops","ts":"1717243800.000100"}
 ```
 
-Slack only lets Pier delete what **its own bot** posted — a person's message
-answers `cant_delete_message`, and the answer is to ask them, not to retry.
-
 - `ts` is always explicit. There is no "delete the last one" and no default
   from the thread you are in: the wrong `ts` cannot be undone.
 - A `ts` means nothing outside the conversation it came from — pass the

package/skills/pier-tasks/SKILL.md

@@ -32,12 +32,18 @@ A summary's `triggerSource` is who fired that run (`agent` when you did, plus
 `manual` / `cron` / `watch` / `task`); a definition's `trigger` is only its
 schedule policy, where `manual` means on-demand — by a human or by you.
 
-- `fresh`: clean context, requires `cwd`. `fork`: child starts with a copy of
-  your conversation — use when the task needs your context. `reuse`: sends
-  work to an existing session by id.
+- `fresh`: clean context, requires `cwd` — how a child normally starts.
+  `reuse`: sends work to an existing session by id, continuing its history.
+  There is no way to copy your context into a child: what the child needs, you
+  write down.
+- **The handoff is the prompt.** A child cannot see your discussion, so state:
+  the goal; the decisions *currently* in force (not the ones you argued out of);
+  the constraints the user added late; absolute paths; what "done" means and how
+  to verify it. Writing it is also the check — a decision you cannot state in a
+  sentence was not settled.
 - The child inherits your current model unless `launch.model` is set.
   Unknown models fail with the available list in the error. `launch` applies to
-  `fresh` and `fork` only — a `reuse` session owns its own model and tools.
+  `fresh` only — a `reuse` session owns its own model and tools.
 - The child has the same tools you do.
 - Runs time out after 900s by default; set `timeoutSeconds` in the draft for
   longer jobs.
@@ -65,9 +71,8 @@ group in core — you never track run ids across turns:
 ## Chains
 
 Run step 1, end your turn, receive its callback, splice the needed part into
-step 2's prompt. Children share nothing implicitly (except fork's copied
-history) — every prompt must be self-contained: paths, acceptance criteria,
-expected output format. Branching and retries are your own logic between
+step 2's prompt. Children share nothing implicitly — every prompt must be
+self-contained: paths, acceptance criteria, expected output format. Branching and retries are your own logic between
 turns.
 
 ## Choosing a model and thinking level
@@ -103,8 +108,8 @@ list in the error, so a stale guess costs one call.
 
 `{"operation":"contact","reason":"decision","message":"..."}` returns a
 receipt immediately. State what you are waiting for and **end your turn** —
-never spin or poll. The answer arrives as a follow-up if your run is still
-active; if your run already finished, Pier resumes your session with the
+never spin or poll. The answer is steered into your current turn if your run is
+still active; if your run already finished, Pier resumes your session with the
 reply as the prompt. One open decision per run.
 
 As a parent: the question arrives as a system input with a message id, steered