@timqi/pier 0.1.0 → 0.1.1

package/README.md

@@ -2,17 +2,16 @@
 
 A self-hosted workspace for coding agents. Pier puts a web workbench and your
 IM channels in front of [Pi](https://github.com/earendil-works/pi) sessions:
-you talk to the same agent from a browser, from Slack, Telegram or Lark, steer a
-running turn, schedule tasks, watch what every session is doing, and publish a
-static page when something is worth showing.
+talk to the same agent from a browser, Slack, Telegram or Lark, steer a running
+turn, schedule tasks, watch every session, and publish a static page when
+something is worth showing.
 
 One instance, one account, your own machine. The agent runs shell commands in
-directories you name, so Pier is meant for a machine you own and a boundary you
-control — not for a shared host.
+directories you name — meant for a machine you own, not a shared host.
 
-**Status: pre-release.** The version is `0.0.x` and the database schema is
-versioned from `0.0.1` on — earlier databases are not migrated. Read
-`docs/deploy.md` before putting it anywhere reachable.
+**Status: pre-release.** The version is `0.0.x`; the database schema is
+versioned from `0.0.1` on. Read `docs/deploy.md` before putting it anywhere
+reachable.
 
 ## Requirements
 
@@ -35,75 +34,47 @@ It listens on `127.0.0.1:3141` (`PORT`, `HOST`) and keeps everything under
 session transcripts (`~/.pier/pi`, unless `PI_CODING_AGENT_DIR` says
 otherwise).
 
-**The first start generates a password and prints it once.** Every HTTP surface
-is behind it — there is no default password and no unclaimed window. Lost it?
-`sqlite3 ~/.pier/db/pier.db 'DELETE FROM auth'` and restart; a new one is printed.
-
-Open `http://localhost:3141`, sign in, then:
-
-- **Console → Settings** — everything the instance is configured with, one
-  tab per topic: Models (API-key/OAuth logins, and the menu of favored models
-  agents are advised with), Agent (Pi configuration, skills, extensions),
-  Channels (Slack Socket-Mode or Telegram bot tokens; chats are discovered
-  when the bot first sees traffic, gated by the mention/bind rules you set),
-  plus the public URL, password and master key
-- **New session** — pick a directory; that is where the agent's shell runs
+**The first start generates a password and prints it once.** Lost it?
+`sqlite3 ~/.pier/db/pier.db 'DELETE FROM auth'` and restart. Open
+`http://localhost:3141`, sign in; **Console → Settings** configures Models,
+Agent, Channels, the public URL, password and master key; **New session** picks
+the directory the agent's shell runs in.
 
 ## Configure Pi
 
-Pier gives Pi a dedicated agent directory instead of changing your normal Pi
-installation. By default it is `$PIER_HOME/pi` (`~/.pier/pi`). Set
-`PI_CODING_AGENT_DIR` before starting Pier to use another directory, including
-an existing Pi setup:
+Pier gives Pi its own agent directory, `$PIER_HOME/pi` by default; set
+`PI_CODING_AGENT_DIR` to use another, including an existing Pi setup:
 
 ```sh
 PI_CODING_AGENT_DIR="$HOME/.pi/agent" pier serve
 ```
 
-Pier exports that variable for the SDK, so anything it starts inherits it — an
-agent's shell included. A second Pier launched from there with its
-own `PIER_HOME` derives its own agent directory rather than adopting the first
-one's; setting `PI_CODING_AGENT_DIR` again on that command line still wins.
-
-Console → Settings is the normal setup path:
-
-- **Models** configures built-in or custom endpoints and API-key/OAuth login,
-  then pins the few models this deployment favors. Stored credentials are
-  sealed in Pier's SQLite database; they are not written back to `models.json`.
-  **Test** sends one real request on a model you pick and shows both halves of
-  it — the body as the provider received it, and what came back — so a wrong
-  base URL, a revoked key, a gateway rewriting the request or a model the
-  endpoint never had says so here instead of in a session.
-- **Agent** edits `SYSTEM.md`, `AGENTS.md`, `settings.json`, and advanced
-  `models.json` structure in the Pi agent directory — globally, or per project
-  scope, where it also shows that project's `.pi/skills` and `.pi/extensions`
-  resources. Changes apply when a session next opens; saving here recycles the
-  idle ones for you, and **Settings → Instance → Reload** does it for files
-  something else changed — an agent, or an editor on the box.
-  The same tab lists the extensions Pier ships with, under Global — they live
-  inside the package, so there is nothing to install and an update never
-  touches your own `extensions` directory, and if an extension of yours
-  already registers the same tool, Pier's copy stands down. `web` is the one
-  shipped today: the public web through the provider's own hosted web tools —
-  `web_search` on an authenticated Anthropic or OpenAI model, `web_fetch` on an
-  Anthropic one (OpenAI hosts no fetch tool), and no other key or service. The
-  page says which tools a switch adds and what each needs before you flip it.
-  Below it, the same tab switches on the command-line tools Pier manages —
-  `rtk`, `rg`, `fd`, `wt`, `jq`, or a tool of your own written as a
-  [ubix](https://github.com/timqi/ubix) block. A switch installs the binary
-  into `~/.pier/tools/bin`, which is first on the PATH every session and task
-  inherits, and a task you can read keeps them current.
-
-On first credential access, Pier imports an existing `auth.json` into its sealed
-store and renames the source to `auth.json.imported`. Literal provider keys left
-in `models.json` are moved the same way, with the original retained as
-`models.json.imported`. Use Providers for new secrets; the advanced editor will
-not accept plaintext keys or header values.
-
-Provider environment variables supported by Pi are inherited from the Pier
-process. A service installed with `pier service install` does not inherit your
-interactive shell, so put non-secret Pi environment settings in a systemd unit
-override; for API keys, prefer the sealed Providers UI.
+Pier exports that variable, so anything it starts inherits it. A second Pier
+launched from there with its own `PIER_HOME` derives its own agent directory
+unless `PI_CODING_AGENT_DIR` is set again on that command line.
+
+Console → Settings:
+
+- **Models** — endpoints, API-key/OAuth login, pinned models. Credentials are
+  sealed in Pier's SQLite database, never written back to `models.json`.
+  **Test** sends one real request and shows the body as sent and the reply.
+- **Agent** — edits `SYSTEM.md`, `AGENTS.md`, `settings.json` and the
+  `models.json` structure, globally or per project scope (with that project's
+  `.pi/skills` and `.pi/extensions` listed). Changes apply when a session next
+  opens; saving recycles idle sessions; **Settings → Instance → Reload** does
+  the same for files changed elsewhere. Also here: the bundled extensions
+  (`web`: `web_search` on Anthropic or OpenAI, `web_fetch` on Anthropic; a
+  copy of yours registering the same tool makes Pier's stand down) and the
+  managed CLI tools (`rtk`, `rg`, `fd`, `wt`, `jq`, or your own as a
+  [ubix](https://github.com/timqi/ubix) block), installed into
+  `~/.pier/tools/bin`, first on every session's PATH.
+
+On first credential access an existing `auth.json` is imported into the sealed
+store and renamed `auth.json.imported`; literal keys in `models.json` likewise
+(`models.json.imported`). The editor rejects plaintext keys or header values.
+Pi's provider environment variables are inherited from the Pier process; a
+systemd service does not inherit your shell, so put non-secret settings in a
+unit override and API keys in the Providers UI.
 
 ## Run it as a service
 
@@ -118,32 +89,11 @@ pier update              # latest release, then hard-stop/restart the service
 pier tools sync          # install/update the managed CLI tools by hand
 ```
 
-`pier restart` refuses new work, waits up to five minutes for active turns and
-Task runs, then restarts; if its deadline aborts an IM turn, the next process
-tells that conversation. `pier reload` stays in-process: adapters re-read their
-configuration and idle, unwatched sessions reopen on their next message.
-Streaming or watched sessions keep running and pick changes up after eviction.
-Both commands target the installed systemd service. `pier update` is still a
-hard stop because its separate updater replaces the installed code; let active
-work finish before starting it.
-
-Linux only, because it is systemd. It writes `~/.config/systemd/user/pier.service`
-with the absolute path of the node you installed with (systemd's PATH would not
-find a version-managed one), a memory drop-in it never rewrites afterwards, and
-turns on linger so scheduled tasks survive your logout. Install also records the
-exact npm executable in a separate updater unit. Re-run `pier service install
---force` after changing the service settings or its Node/npm installation; this
-rewrites both units and restarts Pier. On macOS run `pier serve` in a terminal,
-or under whatever supervisor you already use — `pier` on its own only prints
-the usage.
-
-`docs/deploy.md` is the same thing written out by hand, plus what the memory
-limits mean, how updates work (and why the updater is a second unit), how to
-read the first-run password out of the journal, and what to back up.
-
-Exposing it needs two things: a reverse proxy or tunnel that terminates TLS
-(Pier binds the loopback and expects `X-Forwarded-For`/`-Proto`), and the
-understanding that whoever gets past the password gets a shell.
+Linux only (systemd); on macOS run `pier serve` under your own supervisor.
+`docs/deploy.md` is the runbook: units, memory limits, updates and rollback,
+the first-run password, remote access, backups. Expose it only behind a
+TLS-terminating proxy or tunnel (`X-Forwarded-For`/`-Proto`) — whoever gets
+past the password gets a shell.
 
 ## Develop
 
@@ -157,40 +107,23 @@ npm run lint      # oxlint
 npm test          # vitest
 ```
 
-- `AGENTS.md` — the principles this codebase is held to, and the budgets that
-  say when a change is too big. Read it before writing code here.
+- `AGENTS.md` — the principles and budgets this codebase is held to
 - `docs/architecture.md` — the seams, the areas, and what is deliberately absent
-- `docs/design/` — one document per subsystem, written before it was built
+- `docs/design/` — one document per subsystem
 
 ## Releases
 
-Pier asks `registry.npmjs.org` at boot and every 30 minutes, and the version
-beside the title turns into `v0.0.1 → 0.0.2` when a release is out. Clicking it
-opens the panel: the source link, **Update now**, and **Update automatically**.
-
-Nothing here installs anything itself — the work is handed to the second
-systemd unit written at install time, because an npm running as a child of the
-process being restarted would be killed by that restart. Off systemd there is
-nothing to hand it to, so the panel says `pier update` instead.
-
-`pier update` typed in a terminal hard-stops the service. The Console and the
-automatic path both **drain first** — new work refused, running turns given
-time to finish, whatever the deadline still had to cut off written to the chat
-it belonged to — and only then hand over. The automatic path additionally waits
-for an idle instance: no turn streaming, no task run in flight.
-
-Either way the updater writes `~/.pier/db/backups/pier.db.release-<version>.bak`
-before npm touches the package — named for the release being replaced, which is
-the one to reinstall beside it; the three newest are kept. Then it updates the
-npm installation recorded when the service was installed, and starts Pier again.
-
-`main` is the only development line. `just release [patch|minor|major]` runs the
-checks, writes the tag and pushes it; the tag builds and publishes to npm and as
-a GitHub Release. The version in the web footer is the one from `package.json`
-— so the number on screen always names a commit.
-Schema upgrades are one-way: a database migrated by a newer Pier is refused by
-an older one. The release backup above is the way back; `docs/deploy.md` has the
-restore procedure and the additional snapshots taken before schema migrations.
+Pier asks `registry.npmjs.org` at boot and every 30 minutes; the footer version
+becomes `v0.0.1 → 0.0.2` when a release is out and opens a panel: source link,
+**Update now**, **Update automatically** (idle instance only). Both drain first
+and hand the install to the updater unit; off systemd the panel says `pier
+update`. The updater writes `~/.pier/db/backups/pier.db.release-<version>.bak`
+(the release being replaced; three kept) first. Schema upgrades are one-way;
+`docs/deploy.md` has the rollback.
+
+`main` is the only development line. `just release [patch|minor|major]` checks,
+tags and pushes; the tag builds and publishes to npm and a GitHub Release. The
+footer version is `package.json`'s.
 
 ## License
 

package/dist/agent/config.js

@@ -10,20 +10,15 @@ import { mergeSnapshotProviders, normalizeAgentSnapshot, snapshotProviders } fro
 const GLOBAL_FILES = ["SYSTEM.md", "AGENTS.md", "settings.json", "models.json"];
 const PROJECT_FILES = ["AGENTS.md"];
 // settings.json is on the list for two fields: the default model and its
-// reasoning effort. Everything else in it is machine-local and survives an
-// import untouched.
+// reasoning effort. Everything else in it is machine-local.
 const SNAPSHOT_FILES = ["SYSTEM.md", "AGENTS.md", "models.json", "settings.json"];
 const RESOURCE_DEPTH = 3; // extensions/skills nest at most a couple of levels
-/** Pier owns the Pi runtime dir: config lives in the syncable `~/.pier/pi`
- * repo, not `~/.pi`. main.ts exports this as PI_CODING_AGENT_DIR so the SDK's
- * own path resolution (auth.json, sessions, bin) lands in the same place. */
+/** Pier owns the Pi runtime dir; main.ts exports it as PI_CODING_AGENT_DIR. */
 export const defaultAgentDir = () => process.env.PI_CODING_AGENT_DIR ?? pierPath("pi");
 /** Stable mask: mapped back by field, without exposing key fragments. */
 const maskKey = (_key) => "••••••••";
-/** Pi reads the two highest levels off the model's own map, so a ceiling is
- *  read back from it and written into it — leaving the rest of a hand-written
- *  map (an `off: null` that forbids thinking-off) alone, because the Console
- *  does not offer it and therefore may not drop it. */
+/** Pi reads the two highest levels off the model's own map. The rest of a
+ *  hand-written map (an `off: null`) is left alone: the Console does not offer it. */
 const effortOf = (map) => typeof map?.max === "string" ? "max" : typeof map?.xhigh === "string" ? "xhigh" : undefined;
 function withEffort(map, effort) {
     const next = { ...map };
@@ -341,12 +336,8 @@ export class PiConfigStore {
         return fs.readFile(path, "utf8");
     }
 }
-/**
- * Relative paths of all files under root, bounded depth, sorted; [] if absent.
- * Symlinks are followed (skills and extensions are routinely linked in from a
- * checkout elsewhere) and everything reached through one is flagged, so the UI
- * can say where it really came from. The depth bound is also the cycle guard.
- */
+/** Symlinks are followed (skills are routinely linked in from elsewhere) and
+ *  flagged; the depth bound is also the cycle guard. */
 async function listDir(root, prefix = "", depth = RESOURCE_DEPTH, linked = false) {
     if (depth === 0)
         return [];

package/dist/agent/credentials.js

@@ -1,11 +1,8 @@
-// Provider credentials — what Pi kept in <agentDir>/auth.json, and the
-// literal API keys models.json used to carry — at rest in pier.db, sealed by
-// Secrets. Implements pi-ai's CredentialStore contract structurally (shapes
-// mirrored below, no SDK import: only pi.ts names SDK modules), so
-// ModelRuntime reads through here and an OAuth refresh writes the rotated
-// token back through here instead of a file. A stored credential wins over a
-// models.json apiKey in pi-ai's resolution order, which is what lets the
-// sweep below leave models.json purely structural — and safely syncable.
+// Provider credentials at rest in pier.db, sealed by Secrets. Implements
+// pi-ai's CredentialStore structurally (no SDK import), so an OAuth refresh
+// writes back here instead of a file. A stored credential wins over a
+// models.json apiKey in pi-ai's resolution order, which is what lets the sweep
+// leave models.json purely structural and syncable.
 import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
@@ -25,9 +22,7 @@ export class CredentialStore {
         this.secrets = secrets;
         this.agentDir = agentDir;
     }
-    /** Locked Secrets must fail a session open loudly, with the reason — not
-     *  surface later as "provider is not configured". Called by pi.ts before
-     *  every open; encrypt() throws the `secrets locked: ...` error we want. */
+    /** encrypt() throws the `secrets locked: ...` error a session open must fail with. */
     assertUnlocked() {
         if (this.secrets.state === "locked")
             this.secrets.encrypt("");
@@ -93,10 +88,8 @@ export class CredentialStore {
             "ON CONFLICT(key) DO UPDATE SET value = excluded.value")
             .run(providerId, this.secrets.encrypt(JSON.stringify(credential)));
     }
-    /** One-time move of <agentDir>/auth.json into the database. Lazy because
-     *  sealing needs an unlocked Secrets; retried until it succeeds (the flag is
-     *  set only then, and #put is an idempotent upsert). The file is renamed,
-     *  never deleted: auth.json.imported is the operator's receipt and way back. */
+    /** Lazy: sealing needs an unlocked Secrets, and #put is an idempotent upsert,
+     *  so this retries until it succeeds. The file is renamed, never deleted. */
     #ensureImported() {
         if (this.#imported)
             return;
@@ -123,14 +116,9 @@ export class CredentialStore {
         this.#sweepModelsJson();
         this.#imported = true;
     }
-    /**
-     * models.json apiKeys are secrets in a file that should be pure structure
-     * (it is what a config repo syncs between hosts). Literal keys move into the
-     * database; `!command` and `$ENV` references are already not plaintext and
-     * stay — the SDK resolves those forms itself, and a sealed copy of a
-     * reference would freeze its meaning. The pre-sweep file is kept whole as
-     * models.json.imported: keys leave the file only with a receipt.
-     */
+    /** models.json is what a config repo syncs, so literal keys move into the
+     *  database. `!command` and `$ENV` references stay: a sealed copy would
+     *  freeze their meaning. The pre-sweep file is kept as models.json.imported. */
     #sweepModelsJson() {
         const path = join(this.agentDir, "models.json");
         if (!existsSync(path))

package/dist/agent/events.js

@@ -1,11 +1,8 @@
-// Pure Pi-event → SessionEventPayload translation. Structurally typed on
-// purpose: no @earendil-works/pi-* imports, so it stays unit-testable without Pi
-// and Pi types never leak past the seam. The golden-table test in
-// events.test.ts is the mapping's spec; extend types.ts before adding events.
+// Pure Pi-event → SessionEventPayload translation. Structurally typed: no Pi
+// imports, so it is unit-testable without Pi and Pi types never leak past the
+// seam. The golden table in events.test.ts is the mapping's spec.
 import { isThinkingLevel, MAX_STEP_OUTPUT } from "../core/types.js";
-/** An assistant message that calls a tool is work in progress, not a reply —
- *  the rule `toChatTurns` rebuilds a transcript by, and agent/listing.ts
- *  indexes one by. */
+/** An assistant message that calls a tool is work in progress, not a reply. */
 export const hasToolCalls = (message) => Array.isArray(message?.content) && message.content.some((part) => part.type === "toolCall");
 export function textOf(content) {
     if (typeof content === "string")
@@ -28,9 +25,7 @@ function systemOrigin(message) {
         typeof origin.runId !== "string" ||
         (origin.sourceSessionId !== null && typeof origin.sourceSessionId !== "string"))
         return null;
-    // Rebuilt around a checked `source` rather than cast through it: a
-    // half-valid one drawn by the card is an `undefined` in a chip, which reads
-    // as a bug in the card rather than as bad metadata.
+    // A half-valid `source` drawn by the card is an `undefined` in a chip.
     const source = inputSource(raw);
     const shape = { ...origin, ...(source ? { source } : {}) };
     if (origin.kind === "task-delegation" || origin.kind === "task-callback") {
@@ -43,9 +38,6 @@ function systemOrigin(message) {
         return shape;
     return null;
 }
-/** What produced a system input, as read back off disk: the name is the whole
- *  point of it, the model and the effort are each kept only if they are the
- *  shape they claim to be (core/types.ts). */
 function inputSource(value) {
     if (!value || typeof value !== "object")
         return undefined;
@@ -61,6 +53,9 @@ function inputSource(value) {
         ...(isThinkingLevel(thinking) ? { thinking } : {}),
     };
 }
+/** `length`, `aborted` and `error` are Pi's to recover from (a truncated answer
+ *  is compacted and asked again), so they stay on the `agent_end` path. */
+const isAnswer = (m) => m?.role === "assistant" && m.stopReason === "stop" && !hasToolCalls(m);
 function lastAssistant(messages) {
     if (!messages)
         return undefined;
@@ -70,17 +65,9 @@ function lastAssistant(messages) {
     }
     return undefined;
 }
-/**
- * Completion metadata for the assistant message at `index` (bubble hover
- * hints). `completedAt` defaults to the message's own timestamp — Pi stamps
- * that at stream start, so callers with a real clock (live turn-end) pass
- * their own; history accepts the approximation.
- *
- * `tokens` is the context size at that point, not a sum: each assistant
- * message's `totalTokens` already covers the whole request (prompt + cache +
- * output), so adding them up double-counts the context on every turn. Pi
- * itself reads context usage off the last assistant message the same way.
- */
+/** Pi stamps a message's timestamp at stream start, so a live turn-end passes
+ *  its own `completedAt`. `tokens` is not a sum: each `totalTokens` already
+ *  covers the whole request. */
 export function turnMetaAt(messages, index, completedAt) {
     const m = messages[index];
     if (m?.role !== "assistant" || typeof m.timestamp !== "number")
@@ -104,11 +91,8 @@ export function turnMetaAt(messages, index, completedAt) {
     }
     return { completedAt: end, durationMs: Math.max(0, end - started), tokens };
 }
-/**
- * Rebuild the renderable transcript: user/assistant turns plus the activity
- * (thinking + tool calls) that preceded each assistant answer. This is what
- * makes a page reload show the real step counts instead of restarting at zero.
- */
+/** The renderable transcript, activity included, so a reload shows the same
+ *  step counts the live stream built. */
 export function toChatTurns(messages) {
     const turns = [];
     let steps = []; // activity seen since the last emitted turn
@@ -120,9 +104,8 @@ export function toChatTurns(messages) {
             turn.meta = meta;
         if (origin)
             turn.origin = origin;
-        // An assistant turn already says when it finished; these two would have no
-        // time at all after a reload, which is the one place the live stream's own
-        // stamp is gone.
+        // An assistant turn's meta says when it finished; user and system turns
+        // would have no time at all after a reload.
         if (at !== undefined && role !== "assistant")
             turn.at = at;
         if (steps.length) {
@@ -135,8 +118,7 @@ export function toChatTurns(messages) {
         if (m.role === "toolResult") {
             const step = pendingTools.get(m.toolCallId ?? "");
             if (step) {
-                // Capped where the transcript is rebuilt, not where it is rendered: a
-                // long session's tool results are megabytes nobody ever sees.
+                // Capped here: a long session's tool results are megabytes nobody sees.
                 const output = textOf(m.content);
                 step.output = output.length > MAX_STEP_OUTPUT ? output.slice(0, MAX_STEP_OUTPUT) + "…" : output;
                 step.isError = m.isError ?? false;
@@ -204,18 +186,21 @@ export function toSessionEvents(e) {
     switch (e.type) {
         case "agent_start":
             return [{ type: "state", state: "streaming" }, { type: "turn-start" }];
+        // One turn-end per answer, not per run: Pi drains a queued follow-up
+        // inside the run and emits a single agent_end for all of it.
+        case "turn_end":
+            return isAnswer(e.message) ? [{ type: "turn-end", text: textOf(e.message?.content) }] : [];
         case "agent_end": {
-            // Pi retries a retryable provider error itself and emits one agent_end
-            // per attempt. Only the last one ends the turn: translating the others
-            // posts a reply and an error per attempt for a failure Pi is still
-            // recovering from, and an `idle` the session is not in.
+            // Pi emits one agent_end per retry attempt; only the last ends the turn.
             if (e.willRetry)
                 return [];
             const final = lastAssistant(e.messages);
-            // A turn can end without the model ever answering. Carried twice on
-            // purpose: on turn-end because it is *how this turn ended*, which is what
-            // a task run settles on (tasks/agent.ts), and as the error event that is
-            // already every chat surface's failure path (core/router.ts).
+            // An answer ended its own turn above; what is left is every way a run
+            // ends without one.
+            if (isAnswer(final))
+                return [];
+            // Carried twice: on turn-end because it is how the turn ended (what a
+            // task run settles on), and as the error event every chat surface reports.
             const failure = final?.stopReason === "error"
                 ? final.errorMessage || "unknown agent error"
                 : undefined;
@@ -226,31 +211,27 @@ export function toSessionEvents(e) {
                 out.push({ type: "error", message: failure });
             return out;
         }
-        // Pi's own "the run-active flag is now false": `_emitAgentSettled` clears
-        // `isStreaming` one statement before emitting this, and reaches it from the
-        // finally of the prompt — many microtasks after the last `agent_end`. Idle
-        // rides on it rather than on the turn ending, so the seam's `state` getter
-        // and this stream stop being two derivations of one fact (§5): a waiter the
-        // idle wakes now re-reads `state` as idle instead of re-arming for an event
-        // that is already spent. It is also the truthful moment — Pi's
-        // auto-compaction and queued continuations run past `agent_end`.
+        // Pi clears `isStreaming` one statement before emitting this, many
+        // microtasks after the last `agent_end`; idle rides on it so the `state`
+        // getter and this stream agree. Auto-compaction runs past `agent_end` too.
         case "agent_settled":
             return [{ type: "state", state: "idle" }];
         case "message_start": {
-            // Pi emits this for every message entering the context; the user ones are
-            // what a client can't know about (queued/steered messages, IM traffic).
             const m = e.message;
             if (!m)
                 return [];
             if (m.role === "assistant")
                 return [{ type: "text-start" }];
             const origin = systemOrigin(m);
-            const text = textOf(m.content);
-            if (origin)
-                return text ? [{ type: "system-input", text, origin }] : [];
-            if (m.role !== "user")
+            if (!origin && m.role !== "user")
                 return [];
-            return text ? [{ type: "user-message", text }] : [];
+            // A message Pi drains mid-run opens a turn `agent_start` never announces.
+            // On the message, not its text: an attachment with no caption is still a turn.
+            const out = [{ type: "turn-start" }];
+            const text = textOf(m.content);
+            if (text)
+                out.push(origin ? { type: "system-input", text, origin } : { type: "user-message", text });
+            return out;
         }
         case "message_update": {
             const ame = e.assistantMessageEvent;
@@ -280,10 +261,8 @@ export function toSessionEvents(e) {
                 },
             ];
         case "compaction_end": {
-            // The only trace compaction leaves anywhere: Pi replaces the summarized
-            // entries with a `compactionSummary` message, which `toChatTurns` above
-            // renders nothing for — so without this event the button's effect is
-            // invisible and the automatic one is invisible twice over (§5b).
+            // The only trace compaction leaves: `toChatTurns` renders nothing for the
+            // summary message (§5).
             const r = e.result;
             if (r && typeof r.tokensBefore === "number") {
                 return [{
@@ -292,9 +271,8 @@ export function toSessionEvents(e) {
                         after: r.estimatedTokensAfter ?? r.tokensBefore,
                     }];
             }
-            // No result means the context was *not* shrunk — cancelled, or the
-            // summarization call failed. A manual compact reports through its route
-            // as well; an automatic one has no route, and this is all it has.
+            // No result: cancelled or failed. An automatic compaction has no route
+            // to report through; this is all it has.
             return [{ type: "error", message: e.errorMessage ?? "compaction cancelled" }];
         }
         case "tool_execution_end":