@mjasnikovs/pi-task 0.7.0 → 0.7.2

package/README.md

@@ -1,5 +1,7 @@
 <div align="center">
 
+<img src="./assets/pipeline.svg" alt="pi-task pipeline: a /task request runs through refine, research, grill, compose and critique, then the final spec is delivered to your main pi session in the same chat. Every phase boundary is persisted to .pi-tasks/TASK_NNNN.md, so the task is crash-safe and resumable." width="820"/>
+
 # 🧩 pi-task
 
 **Deterministic spec-orchestration for local models — with bundled web, docs, fetch, and worker sub-agent tools.**
@@ -7,7 +9,7 @@
 [![npm](https://img.shields.io/npm/v/@mjasnikovs/pi-task?color=cb3837&logo=npm)](https://www.npmjs.com/package/@mjasnikovs/pi-task)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![pi extension](https://img.shields.io/badge/pi-extension-7c3aed)](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
-[![tests](https://img.shields.io/badge/tests-326%20passing-3fb950)](#development)
+[![tests](https://img.shields.io/badge/tests-559%20passing-3fb950)](#development)
 [![types](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](./tsconfig.json)
 
 </div>
@@ -16,24 +18,7 @@
 
 ## What it does
 
-Local models drift. Ask one to plan a non-trivial change and it skips context, hallucinates APIs, and forgets what you actually asked. `pi-task` fixes this by **not trusting a single prompt** — it drives your request through a fixed, persisted pipeline of small, verifiable steps, then hands the main session a clean spec to execute.
-
-```
-/task add rate-limiting to the public API
-        │
-        ▼
-  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
-  │  refine  │──▶│ research │──▶│  grill   │──▶│ compose  │──▶│ critique │
-  └──────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────┘
-   sharpen the    parallel        clarifying     assemble        triage +
-   raw prompt     sub-agents:     questions      the spec        rewrite if
-                  files · APIs ·  (auto- or                      the draft
-                  context ·       you answer)                    isn't clean
-                  tooling
-        │
-        ▼
-  final spec ──▶ main pi session   (you keep working in the same chat)
-```
+Local models drift. Ask one to plan a non-trivial change and it skips context, hallucinates APIs, and forgets what you actually asked. `pi-task` fixes this by **not trusting a single prompt** — it drives your request through a fixed, persisted pipeline of small, verifiable steps (shown above), then hands the main session a clean spec to execute.
 
 Every phase boundary is written to `.pi-tasks/TASK_NNNN.md`, so a task survives a crash, a restart, or a `/task-cancel` — pick it back up with `/task-resume`.
 
@@ -51,7 +36,7 @@ Every phase boundary is written to `.pi-tasks/TASK_NNNN.md`, so a task survives
 pi install npm:@mjasnikovs/pi-task
 ```
 
-> Requires [`pi`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) (the Earendil coding agent) ≥ 0.75.
+> Requires [`pi`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) (the Earendil coding agent) ≥ 0.78.
 
 ## Slash commands
 
@@ -82,22 +67,11 @@ The finished spec is delivered to your main `pi` conversation via `sendUserMessa
 
 A real feature is usually several tasks, not one. `/task-auto` is a thin planner on top of the single-task pipeline:
 
-```
-/task-auto add multi-tenant billing
-        │
-        ▼
-  ┌──────────┐   ┌──────────┐   ┌─────────────┐
-  │ clarify  │──▶│ decompose│──▶│ TASK_AUTO_…  │   resumable list of task titles
-  │ gray     │   │ → titles │   │ .md (titles) │
-  │ areas    │   └──────────┘   └──────┬───────┘
-  └──────────┘                         │
-                          ┌────────────▼─────────────┐
-                          │  for each unchecked title │
-                          │   → full /task pipeline    │  (spec + implement)
-                          │   → wait until it finishes │
-                          │   → check the box, next    │
-                          └────────────────────────────┘
-```
+<div align="center">
+
+<img src="./assets/task-auto.svg" alt="/task-auto plans a feature: it clarifies the gray areas, decomposes the answers into an ordered list of task titles written to TASK_AUTO_NNNN.md, then runs each unchecked title through the full /task pipeline one at a time, ticking the box before moving on." width="820"/>
+
+</div>
 
 - **It only produces titles.** All the depth — refine, research, grill, compose, critique — is `/task`'s job, run fresh per title. `/task-auto` never researches or specs anything itself.
 - **Clarify first.** It asks the few clarifying questions whose answers change how the feature splits, then decomposes the answers into an ordered list of task titles written to `.pi-tasks/TASK_AUTO_NNNN.md`.
@@ -114,6 +88,26 @@ The remote server is **always on** — it starts automatically with each session
 
 Prompts use a **first-answer-wins race**: the same question shows in the local TUI *and* every connected browser, and whoever answers first wins — the other surfaces dismiss. With nobody connected, `/task` behaves exactly as before; the remote path is purely additive.
 
+### Push notifications
+
+Tap the bell (◯ → ◉) in the remote header to get pushed a notification — even with the app backgrounded or the phone locked — when:
+
+- a **grill / clarify question** needs answering (*"pi needs your input"*),
+- a **task finishes** (*"Task finished"*), or
+- the agent hits an **error** (*"Agent error"*).
+
+Delivery is **server → push service → device** over the [Web Push](https://developer.mozilla.org/en-US/docs/Web/API/Push_API) standard (service worker + VAPID), so it reaches a suspended device. It works on desktop browsers and on iOS home-screen PWAs.
+
+**iOS setup** (these are Apple's requirements, not ours):
+
+1. Open the **HTTPS** Tailscale URL (`/remote` lists it). iOS only allows push from a secure context — the plain `http://` LAN URL won't work.
+2. **Share → Add to Home Screen**, then open the app from that icon. iOS only permits notifications for installed PWAs.
+3. Launch the app, **tap the bell**, and **Allow** when prompted.
+
+The subscription is kept in memory, so after restarting `pi` just reload the app (it re-subscribes automatically) or tap the bell again. Notifications are suppressed while the app is focused in the foreground — the in-page UI already shows the prompt there.
+
+VAPID keys are generated once and persisted to `${XDG_DATA_HOME:-~/.local/share}/pi-task/vapid.json` (deleting them invalidates existing subscriptions). The JWT contact (`sub`) defaults to the project URL; override it with `PI_REMOTE_PUSH_SUBJECT` (e.g. your own `mailto:you@domain.com`). To debug delivery, set `PI_REMOTE_PUSH_DEBUG=1` and tail `/tmp/pi-task-push.log` — it records each push and the **push-service HTTP status** (`201` delivered, `403`/`400` token/key problem, `410` stale subscription).
+
 `/remote stop` shuts the server down for the rest of the session (it comes back on the next session start). There is **no authentication** — it's a personal LAN/Tailscale tool. Don't expose the port to untrusted networks.
 
 ## Bundled tools
@@ -129,9 +123,9 @@ Runs a Brave Search query and returns a compact markdown list (title · URL · s
 > **Requires** `BRAVE_SEARCH_API_KEY` (also accepted as `BRAVE_API_KEY`). Grab a free key at [api.search.brave.com/app/keys](https://api.search.brave.com/app/keys).
 
 ### `pi-worker-fetch`
-Fetches a URL, cleans the HTML to markdown ([Readability](https://github.com/mozilla/readability) + [Turndown](https://github.com/mixmark-io/turndown)), then hands it to an isolated child that extracts **only** the content answering your `query`. The parent never sees the raw page.
+Fetches a URL, cleans HTML to markdown ([Readability](https://github.com/mozilla/readability) + [Turndown](https://github.com/mixmark-io/turndown)), then hands it to an isolated child that extracts **only** the content answering your `query`. The parent never sees the raw page.
 
-- Only `text/html` responses — PDFs, JSON, etc. return a clear error.
+- HTML is cleaned; text formats (plain text, markdown, JSON, XML/feeds, `llms.txt`, …) pass through verbatim. Binary responses — PDFs, images, octet-streams — return a clear error.
 - Bodies over 2 MB are rejected.
 - The extraction child runs with `--no-tools` to mitigate visible-text prompt injection.
 
@@ -148,6 +142,10 @@ Resolves an installed npm package, indexes its `.d.ts` files and README into a l
 | --- | --- | --- |
 | `BRAVE_SEARCH_API_KEY` / `BRAVE_API_KEY` | `pi-worker-search`, research enrichment | Required for web search. |
 | `XDG_CACHE_HOME` | `pi-worker-docs` | Overrides the docs cache location (defaults to `~/.cache`). |
+| `XDG_DATA_HOME` | remote push | Where the VAPID keypair is stored (defaults to `~/.local/share`). |
+| `PI_REMOTE_PUSH_SUBJECT` | remote push | VAPID JWT `sub` contact. Defaults to the project URL; set your own `mailto:you@domain.com` or `https://…`. |
+| `PI_REMOTE_PUSH_DEBUG` | remote push | When set (e.g. `1`), logs push delivery and push-service HTTP status. Off by default. |
+| `PI_REMOTE_PUSH_LOG` | remote push | Path for the debug log (defaults to `/tmp/pi-task-push.log`). |
 
 Tasks are persisted to `<cwd>/.pi-tasks/TASK_NNNN.md`. Add `.pi-tasks/` to your `.gitignore` if you don't want them checked in.
 
@@ -155,7 +153,7 @@ Tasks are persisted to `<cwd>/.pi-tasks/TASK_NNNN.md`. Add `.pi-tasks/` to your
 
 ```sh
 bun install
-bun test src/      # 326 tests across 28 files
+bun test src/      # 559 tests across 46 files
 bun run lint       # prettier + eslint + tsc --noEmit
 bun run build      # tsc → dist/
 ```

package/assets/pipeline.svg

@@ -0,0 +1,90 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 396" width="900" height="396" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif" role="img" aria-label="pi-task pipeline: a /task request runs through refine, research, grill, compose and critique phases, then the final spec is delivered to your main pi session in the same chat. Every phase boundary is persisted to .pi-tasks/TASK_NNNN.md, so the task is crash-safe and resumable.">
+  <defs>
+    <marker id="ah" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0,0 L10,5 L0,10 z" fill="#6e7681"/>
+    </marker>
+    <style>
+      .title  { font-size:17px; font-weight:600; fill:#e6edf3; }
+      .cap    { font-size:11.5px; fill:#8b949e; }
+      .num    { font-size:11px; font-weight:700; }
+      .code   { font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; }
+      .foot   { font-size:11.5px; fill:#768390; font-style:italic; }
+    </style>
+  </defs>
+
+  <rect x="6" y="6" width="888" height="384" rx="16" fill="#0d1117" stroke="#30363d" stroke-width="1.5"/>
+
+  <!-- input -->
+  <rect x="220" y="32" width="460" height="38" rx="19" fill="#161b22" stroke="#7c3aed" stroke-width="1.5"/>
+  <text x="450" y="57" text-anchor="middle" class="code" font-size="14"><tspan fill="#a371f7" font-weight="700">/task</tspan><tspan fill="#c9d1d9" dx="7">add rate-limiting to the public API</tspan></text>
+  <line x1="450" y1="70" x2="450" y2="106" stroke="#6e7681" stroke-width="1.5" marker-end="url(#ah)"/>
+
+  <!-- phase row -->
+  <!-- refine -->
+  <g>
+    <rect x="32" y="118" width="150" height="72" rx="10" fill="#161b22" stroke="#30363d"/>
+    <rect x="32" y="118" width="5" height="72" rx="2.5" fill="#58a6ff"/>
+    <text x="50" y="138" class="num" fill="#58a6ff">1</text>
+    <text x="107" y="161" text-anchor="middle" class="title">refine</text>
+  </g>
+  <text x="107" y="210" text-anchor="middle" class="cap">sharpen the</text>
+  <text x="107" y="225" text-anchor="middle" class="cap">raw prompt</text>
+
+  <!-- research -->
+  <g>
+    <rect x="203.5" y="118" width="150" height="72" rx="10" fill="#161b22" stroke="#30363d"/>
+    <rect x="203.5" y="118" width="5" height="72" rx="2.5" fill="#39c5cf"/>
+    <text x="221.5" y="138" class="num" fill="#39c5cf">2</text>
+    <text x="278.5" y="161" text-anchor="middle" class="title">research</text>
+  </g>
+  <text x="278.5" y="210" text-anchor="middle" class="cap">parallel sub-agents:</text>
+  <text x="278.5" y="225" text-anchor="middle" class="cap">files · APIs ·</text>
+  <text x="278.5" y="240" text-anchor="middle" class="cap">context · tooling</text>
+
+  <!-- grill -->
+  <g>
+    <rect x="375" y="118" width="150" height="72" rx="10" fill="#161b22" stroke="#30363d"/>
+    <rect x="375" y="118" width="5" height="72" rx="2.5" fill="#d29922"/>
+    <text x="393" y="138" class="num" fill="#d29922">3</text>
+    <text x="450" y="161" text-anchor="middle" class="title">grill</text>
+  </g>
+  <text x="450" y="210" text-anchor="middle" class="cap">clarifying Q&amp;A</text>
+  <text x="450" y="225" text-anchor="middle" class="cap">(auto, or you answer)</text>
+
+  <!-- compose -->
+  <g>
+    <rect x="546.5" y="118" width="150" height="72" rx="10" fill="#161b22" stroke="#30363d"/>
+    <rect x="546.5" y="118" width="5" height="72" rx="2.5" fill="#3fb950"/>
+    <text x="564.5" y="138" class="num" fill="#3fb950">4</text>
+    <text x="621.5" y="161" text-anchor="middle" class="title">compose</text>
+  </g>
+  <text x="621.5" y="210" text-anchor="middle" class="cap">assemble</text>
+  <text x="621.5" y="225" text-anchor="middle" class="cap">the spec</text>
+
+  <!-- critique -->
+  <g>
+    <rect x="718" y="118" width="150" height="72" rx="10" fill="#161b22" stroke="#30363d"/>
+    <rect x="718" y="118" width="5" height="72" rx="2.5" fill="#a371f7"/>
+    <text x="736" y="138" class="num" fill="#a371f7">5</text>
+    <text x="793" y="161" text-anchor="middle" class="title">critique</text>
+  </g>
+  <text x="793" y="210" text-anchor="middle" class="cap">triage, rewrite</text>
+  <text x="793" y="225" text-anchor="middle" class="cap">if not clean</text>
+
+  <!-- inter-phase arrows -->
+  <line x1="182"   y1="154" x2="201.5" y2="154" stroke="#6e7681" stroke-width="1.5" marker-end="url(#ah)"/>
+  <line x1="353.5" y1="154" x2="373"   y2="154" stroke="#6e7681" stroke-width="1.5" marker-end="url(#ah)"/>
+  <line x1="525"   y1="154" x2="544.5" y2="154" stroke="#6e7681" stroke-width="1.5" marker-end="url(#ah)"/>
+  <line x1="696.5" y1="154" x2="716"   y2="154" stroke="#6e7681" stroke-width="1.5" marker-end="url(#ah)"/>
+
+  <!-- to result -->
+  <line x1="450" y1="252" x2="450" y2="292" stroke="#6e7681" stroke-width="1.5" marker-end="url(#ah)"/>
+
+  <!-- result -->
+  <rect x="120" y="296" width="660" height="48" rx="12" fill="#0f261a" stroke="#2ea043" stroke-width="1.5"/>
+  <text x="450" y="318" text-anchor="middle" font-size="14" font-weight="600" fill="#e6edf3">final spec  →  delivered to your main <tspan class="code" fill="#7ee787">pi</tspan> session</text>
+  <text x="450" y="334" text-anchor="middle" class="cap">same chat — no handoff, no copy-paste</text>
+
+  <!-- footnote -->
+  <text x="450" y="372" text-anchor="middle" class="foot">every phase boundary is persisted to <tspan class="code" font-style="normal">.pi-tasks/TASK_NNNN.md</tspan> — crash-safe &amp; resumable</text>
+</svg>

package/assets/task-auto.svg

@@ -0,0 +1,65 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 332" width="900" height="332" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif" role="img" aria-label="/task-auto plans a feature: it clarifies the gray areas, decomposes the answers into an ordered list of task titles written to TASK_AUTO_NNNN.md, then runs each unchecked title through the full /task pipeline one at a time, ticking the box before moving on.">
+  <defs>
+    <marker id="ah2" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M0,0 L10,5 L0,10 z" fill="#6e7681"/>
+    </marker>
+    <style>
+      .title  { font-size:17px; font-weight:600; fill:#e6edf3; }
+      .titlec { font-size:15px; font-weight:600; fill:#e6edf3; font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; }
+      .cap    { font-size:11.5px; fill:#8b949e; }
+      .num    { font-size:11px; font-weight:700; }
+      .code   { font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; }
+    </style>
+  </defs>
+
+  <rect x="6" y="6" width="888" height="320" rx="16" fill="#0d1117" stroke="#30363d" stroke-width="1.5"/>
+
+  <!-- input -->
+  <rect x="240" y="30" width="420" height="38" rx="19" fill="#161b22" stroke="#7c3aed" stroke-width="1.5"/>
+  <text x="450" y="55" text-anchor="middle" class="code" font-size="14"><tspan fill="#a371f7" font-weight="700">/task-auto</tspan><tspan fill="#c9d1d9" dx="7">add multi-tenant billing</tspan></text>
+  <line x1="450" y1="68" x2="450" y2="100" stroke="#6e7681" stroke-width="1.5" marker-end="url(#ah2)"/>
+
+  <!-- clarify -->
+  <g>
+    <rect x="32" y="110" width="200" height="72" rx="10" fill="#161b22" stroke="#30363d"/>
+    <rect x="32" y="110" width="5" height="72" rx="2.5" fill="#d29922"/>
+    <text x="50" y="130" class="num" fill="#d29922">1</text>
+    <text x="132" y="153" text-anchor="middle" class="title">clarify gray areas</text>
+  </g>
+  <text x="132" y="202" text-anchor="middle" class="cap">ask only what</text>
+  <text x="132" y="217" text-anchor="middle" class="cap">changes the split</text>
+
+  <!-- decompose -->
+  <g>
+    <rect x="350" y="110" width="200" height="72" rx="10" fill="#161b22" stroke="#30363d"/>
+    <rect x="350" y="110" width="5" height="72" rx="2.5" fill="#58a6ff"/>
+    <text x="368" y="130" class="num" fill="#58a6ff">2</text>
+    <text x="450" y="153" text-anchor="middle" class="title">decompose → titles</text>
+  </g>
+  <text x="450" y="202" text-anchor="middle" class="cap">ordered list of</text>
+  <text x="450" y="217" text-anchor="middle" class="cap">task titles only</text>
+
+  <!-- file -->
+  <g>
+    <rect x="668" y="110" width="200" height="72" rx="10" fill="#161b22" stroke="#30363d"/>
+    <rect x="668" y="110" width="5" height="72" rx="2.5" fill="#3fb950"/>
+    <text x="686" y="130" class="num" fill="#3fb950">3</text>
+    <text x="768" y="154" text-anchor="middle" class="titlec">TASK_AUTO_NNNN.md</text>
+  </g>
+  <text x="768" y="202" text-anchor="middle" class="cap">resumable checklist</text>
+  <text x="768" y="217" text-anchor="middle" class="cap">of titles</text>
+
+  <!-- arrows between -->
+  <line x1="232" y1="146" x2="348" y2="146" stroke="#6e7681" stroke-width="1.5" marker-end="url(#ah2)"/>
+  <line x1="550" y1="146" x2="666" y2="146" stroke="#6e7681" stroke-width="1.5" marker-end="url(#ah2)"/>
+
+  <!-- to loop -->
+  <line x1="768" y1="227" x2="768" y2="248" stroke="#6e7681" stroke-width="1.5"/>
+  <path d="M768,248 H450 V248" fill="none" stroke="#6e7681" stroke-width="1.5"/>
+  <line x1="450" y1="244" x2="450" y2="252" stroke="#6e7681" stroke-width="1.5" marker-end="url(#ah2)"/>
+
+  <!-- loop -->
+  <rect x="120" y="256" width="660" height="54" rx="12" fill="#0d1117" stroke="#a371f7" stroke-width="1.5"/>
+  <text x="450" y="278" text-anchor="middle" font-size="14" font-weight="600" fill="#e6edf3">↻  for each unchecked title</text>
+  <text x="450" y="296" text-anchor="middle" class="cap">run the full <tspan class="code" fill="#a371f7">/task</tspan> pipeline  →  implement  →  wait until done  →  tick the box  →  next</text>
+</svg>

package/dist/remote/bridge.d.ts

@@ -1,14 +1,8 @@
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from '@earendil-works/pi-coding-agent';
-import type { ContextUsage, PromptMessage, ServerMessage } from './protocol.js';
+import type { ServerMessage } from './protocol.js';
 export interface BridgeState {
     /** promptId → resolver that settles the remote side of an ask() race. */
     pending: Map<string, (value: string | undefined) => void>;
-    /** The prompt currently awaiting an answer (replayed to late joiners), or null. */
-    activePrompt: PromptMessage | null;
-    /** Last lines pushed per widget key (replayed to late joiners). */
-    activeWidgets: Map<string, string[]>;
-    /** Most recent context-window usage (replayed to seed late joiners' bar), or null. */
-    lastContextUsage: ContextUsage | null;
     nextId: number;
     /** Command name → handler, populated as pi-task registers its commands. */
     commands: Map<string, (args: string, ctx: ExtensionCommandContext) => unknown>;
@@ -43,9 +37,6 @@ export declare class SessionUI {
     /** Race the local input against a remote answer; first to settle wins. */
     ask(spec: AskSpec): Promise<string | undefined>;
 }
-/** Mirror a status widget to browsers and remember it for late joiners.
- *  `lines === undefined` clears the widget (broadcast as `lines: null`). */
-export declare function publishWidget(key: string, lines: string[] | undefined): void;
 export declare function publishNotify(message: string, level: 'info' | 'warning' | 'error'): void;
 export declare function publishViewer(title: string, text: string): void;
 /**

package/dist/remote/bridge.js

@@ -1,13 +1,11 @@
 import { broadcast as wsBroadcast } from './broadcast.js';
 import { pushNotify } from './push.js';
+import { setPrompt, clearPrompt } from './session-state.js';
 const g = globalThis;
 export function getBridge() {
     if (!g.__piBridge) {
         g.__piBridge = {
             pending: new Map(),
-            activePrompt: null,
-            activeWidgets: new Map(),
-            lastContextUsage: null,
             nextId: 0,
             commands: new Map(),
             currentCtx: null,
@@ -56,8 +54,7 @@ export class SessionUI {
             recommended: spec.recommended,
             allowSkip: spec.allowSkip
         };
-        b.activePrompt = prompt;
-        b.broadcast(prompt);
+        setPrompt(prompt);
         // Reaches a backgrounded/suspended phone, which the in-page UI can't.
         void pushNotify('pi needs your input', spec.question, 'pi-prompt').catch(() => { });
         // Local: resolves to a value/undefined, or undefined on abort. Swallow
@@ -78,23 +75,10 @@ export class SessionUI {
         }
         finally {
             b.pending.delete(id);
-            b.activePrompt = null;
-            b.broadcast({ type: 'prompt_resolved', id });
+            clearPrompt(id);
         }
     }
 }
-/** Mirror a status widget to browsers and remember it for late joiners.
- *  `lines === undefined` clears the widget (broadcast as `lines: null`). */
-export function publishWidget(key, lines) {
-    const b = getBridge();
-    if (lines === undefined) {
-        b.activeWidgets.delete(key);
-        b.broadcast({ type: 'widget', key, lines: null });
-        return;
-    }
-    b.activeWidgets.set(key, lines);
-    b.broadcast({ type: 'widget', key, lines });
-}
 export function publishNotify(message, level) {
     getBridge().broadcast({ type: 'notify', message, level });
 }

package/dist/remote/events.d.ts

@@ -1,3 +1,4 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import type { HistoryBuffer } from './history.js';
-export declare function setupEvents(pi: ExtensionAPI, history: HistoryBuffer, broadcastFn: (msg: unknown) => void): void;
+/** Mirror pi agent events into the authoritative SessionState. Each handler
+ *  drives a mutator, which updates the snapshot AND broadcasts the live delta. */
+export declare function setupEvents(pi: ExtensionAPI): void;

package/dist/remote/events.js

@@ -1,22 +1,18 @@
 import { setAgentIdle } from './state.js';
-import { getBridge } from './bridge.js';
 import { pushNotify } from './push.js';
-export function setupEvents(pi, history, broadcastFn) {
-    let currentText = '';
-    const currentTools = [];
-    const pendingArgs = new Map();
+import { publishNotify } from './bridge.js';
+import { agentStart, appendText, textEnd, startTool, updateTool, endTool, agentEnd, addUserTurn, addError, addSystemNote } from './session-state.js';
+/** Mirror pi agent events into the authoritative SessionState. Each handler
+ *  drives a mutator, which updates the snapshot AND broadcasts the live delta. */
+export function setupEvents(pi) {
     pi.on('agent_start', (_event, _ctx) => {
-        currentText = '';
-        currentTools.length = 0;
-        pendingArgs.clear();
         setAgentIdle(false);
-        broadcastFn({ type: 'agent_start' });
+        agentStart();
     });
     pi.on('message_update', (event, _ctx) => {
         const ae = event.assistantMessageEvent;
         if (ae.type === 'text_delta' && 'delta' in ae && typeof ae.delta === 'string') {
-            currentText += ae.delta;
-            broadcastFn({ type: 'text_delta', delta: ae.delta });
+            appendText(ae.delta);
         }
         else if (ae.type === 'error') {
             const errorMessage = 'error' in ae && ae.error && typeof ae.error.errorMessage === 'string' ?
@@ -25,63 +21,42 @@ export function setupEvents(pi, history, broadcastFn) {
             // Skip silent user aborts (no message); only surface genuine failures.
             if (errorMessage || ae.reason === 'error') {
                 const message = errorMessage || 'Request failed';
-                history.addError(message);
-                broadcastFn({ type: 'agent_error', message });
+                addError(message);
                 void pushNotify('Agent error', message, 'pi-error').catch(() => { });
             }
         }
     });
     pi.on('message_end', (_event, _ctx) => {
-        broadcastFn({ type: 'text_end' });
+        textEnd();
     });
     pi.on('tool_execution_start', (event, _ctx) => {
-        pendingArgs.set(event.toolCallId, event.args);
-        broadcastFn({
-            type: 'tool_start',
-            toolCallId: event.toolCallId,
-            toolName: event.toolName,
-            args: event.args
-        });
+        startTool(event.toolCallId, event.toolName, event.args);
     });
     pi.on('tool_execution_update', (event, _ctx) => {
-        broadcastFn({
-            type: 'tool_update',
-            toolCallId: event.toolCallId,
-            partialResult: event.partialResult
-        });
+        updateTool(event.toolCallId, event.partialResult);
     });
     pi.on('tool_execution_end', (event, _ctx) => {
-        const args = pendingArgs.get(event.toolCallId);
-        pendingArgs.delete(event.toolCallId);
-        currentTools.push({
-            toolName: event.toolName,
-            args,
-            result: event.result,
-            isError: event.isError
-        });
-        broadcastFn({
-            type: 'tool_end',
-            toolCallId: event.toolCallId,
-            toolName: event.toolName,
-            result: event.result,
-            isError: event.isError
-        });
+        endTool(event.toolCallId, event.toolName, event.result, event.isError);
     });
     pi.on('agent_end', (_event, ctx) => {
-        const contextUsage = ctx.getContextUsage();
         setAgentIdle(true);
-        // Remember it so a browser that connects mid-session gets its bar seeded.
-        getBridge().lastContextUsage = contextUsage;
-        history.addAssistantTurn(currentText, [...currentTools]);
-        broadcastFn({ type: 'agent_end', contextUsage });
+        agentEnd(ctx.getContextUsage());
         void pushNotify('Task finished', '', 'pi-end').catch(() => { });
-        currentText = '';
-        currentTools.length = 0;
     });
     pi.on('input', (event, _ctx) => {
         if (event.source === 'interactive' && typeof event.text === 'string') {
-            history.addUserMessage(event.text);
-            broadcastFn({ type: 'user_message', text: event.text });
+            addUserTurn(event.text);
         }
     });
+    // Context-window compaction (incl. the auto-compaction triggered by a context
+    // overflow) is invisible to a remote viewer otherwise — mirror it as a toast so
+    // they see the same "compacting…" status the terminal shows.
+    pi.on('session_before_compact', (_event, _ctx) => {
+        publishNotify('Context full — compacting…', 'warning');
+    });
+    pi.on('session_compact', (_event, _ctx) => {
+        // Persistent inline note so it's still visible after a reconnect, not just a
+        // transient toast.
+        addSystemNote('Context compacted');
+    });
 }

package/dist/remote/history.d.ts

@@ -1,13 +1,24 @@
-export interface ToolSummary {
+export interface TextPart {
+    kind: 'text';
+    text: string;
+}
+export interface ToolPart {
+    kind: 'tool';
+    toolCallId: string;
     toolName: string;
     args: unknown;
     result: unknown;
     isError: boolean;
+    /** false while the tool is still running (result not in yet). */
+    done: boolean;
 }
+export type Part = TextPart | ToolPart;
 export interface Turn {
-    role: 'user' | 'assistant';
-    text: string;
-    tools: ToolSummary[];
+    role: 'user' | 'assistant' | 'system';
+    /** User text, error text, or a system note. Assistant content lives in `parts`. */
+    text?: string;
+    /** Ordered assistant content (text + tools). */
+    parts?: Part[];
     error?: boolean;
 }
 export declare class HistoryBuffer {
@@ -15,8 +26,10 @@ export declare class HistoryBuffer {
     private readonly limit;
     constructor(limit?: number);
     addUserMessage(text: string): void;
-    addAssistantTurn(text: string, tools: ToolSummary[]): void;
+    addAssistantTurn(parts: Part[]): void;
     addError(text: string): void;
+    /** A persistent, inline system note (e.g. "Context compacted"). */
+    addSystemNote(text: string): void;
     getEntries(): Turn[];
     private _push;
 }

package/dist/remote/history.js

@@ -1,3 +1,6 @@
+// An assistant turn is an ORDERED list of parts — text segments and tool calls
+// interleaved exactly as they happened — so the remote transcript reproduces the
+// terminal's layout instead of collapsing a whole run into one text blob.
 export class HistoryBuffer {
     entries = [];
     limit;
@@ -5,13 +8,17 @@ export class HistoryBuffer {
         this.limit = limit;
     }
     addUserMessage(text) {
-        this._push({ role: 'user', text, tools: [] });
+        this._push({ role: 'user', text });
     }
-    addAssistantTurn(text, tools) {
-        this._push({ role: 'assistant', text, tools });
+    addAssistantTurn(parts) {
+        this._push({ role: 'assistant', parts });
     }
     addError(text) {
-        this._push({ role: 'assistant', text, tools: [], error: true });
+        this._push({ role: 'assistant', text, error: true });
+    }
+    /** A persistent, inline system note (e.g. "Context compacted"). */
+    addSystemNote(text) {
+        this._push({ role: 'system', text });
     }
     getEntries() {
         return [...this.entries];

package/dist/remote/protocol.d.ts

@@ -9,9 +9,9 @@ export interface PromptResolvedMessage {
     type: 'prompt_resolved';
     id: string;
 }
+/** The single task-widget slot. `lines: null` clears it. */
 export interface WidgetMessage {
     type: 'widget';
-    key: string;
     lines: string[] | null;
 }
 export interface NotifyMessage {
@@ -40,10 +40,13 @@ export interface ContextMessage {
 export interface ResetMessage {
     type: 'reset';
 }
-/** Server → browser messages added by the integration. The existing
- *  history / text_delta / tool_* / agent_* / client_count / user_message messages are
- *  emitted ad hoc by events.ts / server.ts and are not enumerated here. */
-export type ServerMessage = PromptMessage | PromptResolvedMessage | WidgetMessage | NotifyMessage | ViewerMessage | ContextMessage | ResetMessage;
+/** The full authoritative state sent to a (re)connecting client. Defined in
+ *  session-state.ts (its serializer); re-exported here as part of the wire type. */
+export type { SnapshotMessage } from './session-state.js';
+/** Server → browser messages. The live text_delta / tool_* / agent_* /
+ *  client_count / user_message deltas are emitted by the SessionState mutators
+ *  and not all enumerated here; the snapshot below carries the full state. */
+export type ServerMessage = PromptMessage | PromptResolvedMessage | WidgetMessage | NotifyMessage | ViewerMessage | ContextMessage | ResetMessage | import('./session-state.js').SnapshotMessage;
 /** Browser → server messages. */
 export interface ClientChatMessage {
     type: 'message';