@mjasnikovs/pi-task 0.6.0 → 0.7.1

package/dist/remote/ui.js

@@ -85,6 +85,13 @@ export function html(wsUrl) {
       background: var(--crust); color: var(--red); align-self: stretch;
       max-width: 100%; border: 1px solid var(--red); font-size: 12px;
     }
+    /* Persistent inline system note (e.g. context compaction) — a muted centered
+       divider, distinct from chat bubbles. */
+    .sysnote {
+      align-self: center; color: var(--subtext0); font-size: 11px;
+      font-family: ui-monospace, monospace; letter-spacing: 0.5px;
+      padding: 2px 10px; opacity: 0.85;
+    }
     .bubble.thinking {
       display: flex; gap: 5px; align-items: center; padding: 10px 14px;
     }
@@ -172,11 +179,12 @@ export function html(wsUrl) {
       font-size: 13px; z-index: 100; letter-spacing: 0.03em;
     }
     #reconnect-overlay.visible { display: flex; }
+    /* Trailing stream indicator: the same braille spinner as the thinking bubble,
+       inline at the end of the streaming text (not a green blinking block). */
     .cursor {
-      display: inline-block; width: 7px; height: 1em; vertical-align: text-bottom;
-      background: var(--green); animation: blink 1s step-end infinite; margin-left: 1px;
+      color: var(--mauve); margin-left: 2px;
+      font-family: ui-monospace, monospace;
     }
-    @keyframes blink { 50% { opacity: 0; } }
     #status-panel { padding: 6px 12px; border-bottom: 1px solid var(--surface1);
       color: var(--subtext1); white-space: pre-wrap; font-size: 13px; display: none; }
     #prompt-card { position: fixed; left: 0; right: 0; bottom: 0; background: var(--mantle);
@@ -208,7 +216,8 @@ export function html(wsUrl) {
       font-size: 12px; font-weight: 500; padding: 8px 10px; }
     #prompt-card button.cancel:hover { color: var(--red); filter: none; }
     #prompt-card button.cancel.armed { background: var(--red); color: var(--crust); font-weight: 700; }
-    .toast { position: fixed; top: 12px; right: 12px; max-width: calc(100vw - 24px);
+    .toast { position: fixed; top: calc(env(safe-area-inset-top, 0px) + 12px);
+      right: calc(env(safe-area-inset-right, 0px) + 12px); max-width: calc(100vw - 24px);
       padding: 8px 12px; border-radius: 6px; overflow-wrap: anywhere; word-break: break-word;
       background: var(--surface1); color: var(--text); z-index: 60; }
     .toast.warning { background: var(--peach); color: var(--crust); }
@@ -224,7 +233,7 @@ export function html(wsUrl) {
   <div id="header">
     <span class="title">pi-task remote</span>
     <div class="hgroup">
-      <span class="status" id="client-status"><span class="cdot" id="conn-dot">&#x25CB;</span><span id="client-label">connecting&#x2026;</span></span>
+      <span class="status" id="client-status"><span class="cdot" id="conn-dot">&#x25CB;</span></span>
       <button id="bell" aria-label="Toggle notifications" title="Notifications">&#x25EF;</button>
     </div>
   </div>
@@ -264,17 +273,29 @@ export function html(wsUrl) {
       if (usage && usage.percent != null) contextFill.style.width = usage.percent + '%';
     }
     const connDot = document.getElementById('conn-dot');
-    const clientLabel = document.getElementById('client-label');
     // state: 'connecting' (○ yellow) | 'up' (● green) | 'down' (● red)
-    function setConn(state, label) {
+    function setConn(state) {
       connDot.textContent = state === 'connecting' ? '\\u25CB' : '\\u25CF';
       connDot.className = 'cdot' + (state === 'up' ? ' up' : state === 'down' ? ' down' : '');
-      if (label !== undefined) clientLabel.textContent = label;
     }
     const reconnectOverlay = document.getElementById('reconnect-overlay');
     const reconnectMsg = document.getElementById('reconnect-msg');
     const cmdSuggestions = document.getElementById('cmd-suggestions');
     const statusPanel = document.getElementById('status-panel');
+    // Widgets are keyed (e.g. 'pi-tasks', 'pi-task-auto'); track them per key so a
+    // clear for one key can't be masked by a stale message from another.
+    // Single authoritative task-widget slot. The snapshot and the live 'widget'
+    // delta both set this; null hides the panel. (No more per-key map that could
+    // strand an orphaned widget on screen.)
+    let taskWidgetLines = null;
+    function renderWidgets() {
+      if (taskWidgetLines && taskWidgetLines.length) {
+        statusPanel.textContent = taskWidgetLines.join('\\n');
+        statusPanel.style.display = 'block';
+      } else {
+        statusPanel.style.display = 'none';
+      }
+    }
     const promptCard = document.getElementById('prompt-card');
     const promptQ = document.getElementById('prompt-q');
     const promptRec = document.getElementById('prompt-rec');
@@ -292,6 +313,7 @@ export function html(wsUrl) {
     let streamText = '';
     let autoScroll = true;
     let reconnectDelay = 1000;
+    let reconnectAnim = null;
     let ws = null;
 
     const BT = String.fromCharCode(96);
@@ -475,30 +497,46 @@ export function html(wsUrl) {
     let spinTimer = null;
     let spinIdx = 0;
     const SPIN = '\\u280B\\u2819\\u2839\\u2838\\u283C\\u2834\\u2826\\u2827\\u2807\\u280F';
+    // One braille ticker drives every '.spin' element — the thinking bubble AND the
+    // trailing stream cursor — so they share the same frame and look identical.
+    function spinPaint() {
+      const g = SPIN[spinIdx % SPIN.length];
+      const els = document.getElementsByClassName('spin');
+      for (let i = 0; i < els.length; i++) els[i].textContent = g;
+    }
+    function startSpin() {
+      spinPaint();
+      if (spinTimer) return;
+      spinTimer = setInterval(function () {
+        spinIdx = (spinIdx + 1) % SPIN.length;
+        spinPaint();
+      }, 90);
+    }
+    // Stop the ticker once nothing on screen needs spinning.
+    function stopSpinIfIdle() {
+      if (spinTimer && !document.querySelector('.spin')) {
+        clearInterval(spinTimer); spinTimer = null;
+      }
+    }
     function showThinking() {
       if (!thinkingEl) {
         thinkingEl = document.createElement('div');
         thinkingEl.className = 'bubble assistant thinking';
-        thinkingEl.innerHTML = '<span class="spinner"></span>';
-      }
-      if (!spinTimer) {
-        var sp = thinkingEl.firstChild;
-        sp.textContent = SPIN[spinIdx % SPIN.length];
-        spinTimer = setInterval(function () {
-          spinIdx = (spinIdx + 1) % SPIN.length;
-          sp.textContent = SPIN[spinIdx];
-        }, 90);
+        thinkingEl.innerHTML = '<span class="spinner spin"></span>';
       }
       chatLog.appendChild(thinkingEl); // append (or move) to bottom
+      startSpin();
       scrollBottom();
     }
     function hideThinking() {
-      if (spinTimer) { clearInterval(spinTimer); spinTimer = null; }
       if (thinkingEl) thinkingEl.remove();
+      stopSpinIfIdle();
     }
 
     function addToolCall(toolName, argsStr, isError) {
-      const label = (toolName + ': ' + argsStr).slice(0, 64);
+      // argsStr can be undefined (no args / JSON.stringify(undefined)); don't let
+      // that render as the literal "name: undefined" in the collapsed summary.
+      const label = (toolName + (argsStr ? ': ' + argsStr : '')).slice(0, 64);
       const d = document.createElement('details');
       d.className = 'tool-call' + (isError ? ' error' : '');
       const s = document.createElement('summary');
@@ -515,6 +553,82 @@ export function html(wsUrl) {
       sendBtn.disabled = !allow;
     }
 
+    // Stringify a tool result safely. A null/undefined result (e.g. a tool that
+    // hasn't produced output) must NOT become the JS value undefined, whose
+    // .slice() throws — a throw here aborts the whole snapshot rebuild after the
+    // log was already cleared, blanking the transcript on reconnect.
+    function toolResultText(result) {
+      if (result == null) return '';
+      const r = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+      return (r == null ? '' : r).slice(0, 8000);
+    }
+
+    // Render one tool part from the ordered parts list (running or finished).
+    function renderToolPart(p) {
+      const argsStr = typeof p.args === 'string' ? p.args : JSON.stringify(p.args);
+      const d = addToolCall(p.toolName, argsStr, p.isError);
+      if (p.done) {
+        const pre = document.createElement('pre');
+        pre.textContent = toolResultText(p.result);
+        d.appendChild(pre);
+      } else {
+        toolCallMap[p.toolCallId] = d; // a later tool_end delta fills the result
+      }
+      return d;
+    }
+
+    // A muted, centered system note (e.g. "Context compacted").
+    function addSystemLine(text) {
+      const el = document.createElement('div');
+      el.className = 'sysnote';
+      el.textContent = text;
+      chatLog.appendChild(el);
+      scrollBottom();
+      return el;
+    }
+
+    // Render one committed transcript turn. Assistant turns are an ordered list of
+    // parts (text segments + tool calls), so the layout matches the terminal's
+    // interleaving instead of one merged blob with tools dumped at the end.
+    function renderTurn(t) {
+      if (t.error) { addBubble('error', t.text); return; }
+      if (t.role === 'system') { addSystemLine(t.text); return; }
+      if (t.role === 'user') { addBubble('user', t.text); return; }
+      for (const p of (t.parts || [])) {
+        if (p.kind === 'text') { if (p.text) addBubble('assistant', p.text); }
+        else renderToolPart(p);
+      }
+    }
+
+    // Render the in-progress assistant turn from a snapshot, preserving order. The
+    // trailing OPEN text segment becomes the live streaming bubble (cursor + spin)
+    // so subsequent text_delta frames keep flowing into it.
+    function renderLiveTurn(live) {
+      const parts = live.parts || [];
+      for (let i = 0; i < parts.length; i++) {
+        const p = parts[i];
+        const last = i === parts.length - 1;
+        if (p.kind === 'text') {
+          if (last && live.textOpen) {
+            currentBubble = document.createElement('div');
+            currentBubble.className = 'bubble assistant';
+            const cursor = document.createElement('span');
+            cursor.className = 'cursor spin';
+            currentBubble.appendChild(cursor);
+            if (p.text) currentBubble.insertBefore(document.createTextNode(p.text), cursor);
+            chatLog.appendChild(currentBubble);
+            streamText = p.text || '';
+            startSpin();
+            scrollBottom();
+          } else if (p.text) {
+            addBubble('assistant', p.text);
+          }
+        } else {
+          renderToolPart(p);
+        }
+      }
+    }
+
     function showToast(message, level) {
       const t = document.createElement('div');
       t.className = 'toast ' + (level || 'info');
@@ -557,26 +671,65 @@ export function html(wsUrl) {
       }
       const issue = notifyEnvIssue();
       if (issue) { showToast(issue, 'warning'); return; }
+      if (!('serviceWorker' in navigator) || !('PushManager' in window)) {
+        showToast('This browser doesn\\u2019t support push notifications.', 'warning'); return;
+      }
       Notification.requestPermission().then(function (perm) {
-        if (perm === 'granted') { localStorage.setItem(NOTIFY_KEY, '1'); }
-        else { showToast('Notifications blocked in browser settings.', 'warning'); }
-        updateBell();
+        if (perm !== 'granted') {
+          showToast('Notifications blocked in browser settings.', 'warning');
+          updateBell(); return;
+        }
+        subscribePush().then(function (ok) {
+          if (ok) { localStorage.setItem(NOTIFY_KEY, '1'); showToast('Notifications on.', 'info'); }
+          else { showToast('Could not register for notifications.', 'warning'); }
+          updateBell();
+        }).catch(function (e) {
+          showToast('Notification setup failed: ' + (e && e.message ? e.message : e), 'warning');
+          updateBell();
+        });
       });
     });
 
-    // Fire a browser notification, but only when armed, in a secure context,
-    // and the tab is backgrounded (foreground already has the in-page UI).
-    function notify(title, body, tag) {
-      if (!notifyEnabled()) return;
-      if (!window.isSecureContext) return;
-      if (!document.hidden) return;
-      try {
-        const n = new Notification(title, { body: body || '', tag: tag });
-        n.onclick = function () { window.focus(); n.close(); };
-      } catch (e) { /* constructor unsupported (e.g. iOS without SW) */ }
+    // VAPID public key (base64url) -> Uint8Array for applicationServerKey.
+    function urlB64ToUint8Array(base64) {
+      const pad = '='.repeat((4 - base64.length % 4) % 4);
+      const b64 = (base64 + pad).replace(/-/g, '+').replace(/_/g, '/');
+      const raw = atob(b64);
+      const arr = new Uint8Array(raw.length);
+      for (let i = 0; i < raw.length; i++) arr[i] = raw.charCodeAt(i);
+      return arr;
+    }
+
+    // Register the service worker, subscribe via the Push API, and hand the
+    // subscription to the server. The server (not the page) sends notifications,
+    // so they arrive even when this PWA is backgrounded/suspended on iOS.
+    function subscribePush() {
+      return navigator.serviceWorker.register('/sw.js')
+        .then(function () { return navigator.serviceWorker.ready; })
+        .then(function (reg) {
+          return fetch('/push-key').then(function (r) { return r.text(); }).then(function (key) {
+            return reg.pushManager.getSubscription().then(function (existing) {
+              return existing || reg.pushManager.subscribe({
+                userVisibleOnly: true,
+                applicationServerKey: urlB64ToUint8Array(key.trim())
+              });
+            });
+          });
+        })
+        .then(function (subscription) {
+          return fetch('/subscribe', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(subscription)
+          }).then(function (res) { return res.ok; });
+        });
     }
 
     updateBell();
+    // Self-heal: if notifications were enabled before, re-register the
+    // subscription on load (the server keeps subscriptions in memory and may
+    // have restarted, and browsers can rotate the subscription).
+    if (notifyEnabled()) { subscribePush().catch(function () {}); }
 
     function answer(value) {
       if (activePromptId === null) return;
@@ -679,19 +832,27 @@ export function html(wsUrl) {
 
     function handleMsg(msg) {
       switch (msg.type) {
-        case 'history':
-          for (const t of (msg.turns || [])) {
-            if (t.error) { addBubble('error', t.text); continue; }
-            addBubble(t.role, t.text);
-            for (const tool of (t.tools || [])) {
-              const d = addToolCall(tool.toolName, JSON.stringify(tool.args), tool.isError);
-              const pre = document.createElement('pre');
-              const r = typeof tool.result === 'string' ? tool.result : JSON.stringify(tool.result, null, 2);
-              pre.textContent = r.slice(0, 8000);
-              d.appendChild(pre);
-            }
-          }
+        case 'snapshot': {
+          // Authoritative full state on every (re)connect: replace the WHOLE view.
+          // This is what kills duplicated transcript / stale-orphaned widgets —
+          // whatever was on screen is discarded and rebuilt from server truth.
+          chatLog.innerHTML = '';
+          closePrompt();
+          hideThinking();
+          currentBubble = null; streamText = '';
+          for (const k in toolCallMap) delete toolCallMap[k];
+          // Per-turn try/catch: one malformed turn must never abort the rebuild
+          // and leave the (already-cleared) transcript blank.
+          for (const t of (msg.turns || [])) { try { renderTurn(t); } catch (e) {} }
+          if (msg.live) { try { renderLiveTurn(msg.live); } catch (e) {} }
+          taskWidgetLines = (msg.taskWidget && msg.taskWidget.length) ? msg.taskWidget : null;
+          renderWidgets();
+          if (msg.context) setContextBar(msg.context); else contextFill.style.width = '0%';
+          if (msg.prompt) showPrompt(msg.prompt);
+          setEnabled(!msg.agentRunning && !msg.prompt);
+          if (msg.agentRunning && !msg.live) showThinking();
           break;
+        }
         case 'agent_start':
           autoScroll = true;
           streamText = '';
@@ -705,9 +866,10 @@ export function html(wsUrl) {
             currentBubble = document.createElement('div');
             currentBubble.className = 'bubble assistant';
             const cursor = document.createElement('span');
-            cursor.className = 'cursor';
+            cursor.className = 'cursor spin';
             currentBubble.appendChild(cursor);
             chatLog.appendChild(currentBubble);
+            startSpin();
           }
           streamText += msg.delta;
           {
@@ -721,6 +883,11 @@ export function html(wsUrl) {
             const c = currentBubble.querySelector('.cursor');
             if (c) c.remove();
             if (streamText) setContent(currentBubble, streamText);
+            // Close this message's bubble so the next text segment (after a tool or
+            // the next message) starts a fresh bubble — matching the terminal.
+            currentBubble = null;
+            streamText = '';
+            stopSpinIfIdle();
           }
           break;
         case 'tool_start': {
@@ -734,8 +901,7 @@ export function html(wsUrl) {
           if (d) {
             if (msg.isError) d.classList.add('error');
             const pre = document.createElement('pre');
-            const r = typeof msg.result === 'string' ? msg.result : JSON.stringify(msg.result, null, 2);
-            pre.textContent = r.slice(0, 8000);
+            pre.textContent = toolResultText(msg.result);
             d.appendChild(pre);
             delete toolCallMap[msg.toolCallId];
           }
@@ -748,6 +914,9 @@ export function html(wsUrl) {
         case 'user_message':
           addBubble('user', msg.text);
           break;
+        case 'system_note':
+          addSystemLine(msg.text);
+          break;
         case 'agent_error':
           hideThinking();
           if (currentBubble) {
@@ -756,9 +925,9 @@ export function html(wsUrl) {
             if (streamText) setContent(currentBubble, streamText);
             currentBubble = null;
             streamText = '';
+            stopSpinIfIdle();
           }
           addBubble('error', msg.message || 'Error');
-          notify('Agent error', msg.message || 'Error', 'pi-error');
           setEnabled(true);
           break;
         case 'agent_end':
@@ -766,7 +935,6 @@ export function html(wsUrl) {
           currentBubble = null;
           streamText = '';
           setEnabled(true);
-          notify('Task finished', '', 'pi-end');
           setContextBar(msg.contextUsage);
           break;
         case 'context':
@@ -774,22 +942,17 @@ export function html(wsUrl) {
           setContextBar(msg.contextUsage);
           break;
         case 'client_count':
-          setConn('up', msg.count + ' client' + (msg.count === 1 ? '' : 's') + ' connected');
+          setConn('up');
           break;
         case 'prompt':
           showPrompt(msg);
-          notify('pi needs your input', msg.question, 'pi-prompt');
           break;
         case 'prompt_resolved':
           if (activePromptId === msg.id) closePrompt();
           break;
         case 'widget':
-          if (msg.lines && msg.lines.length) {
-            statusPanel.textContent = msg.lines.join('\\n');
-            statusPanel.style.display = 'block';
-          } else {
-            statusPanel.style.display = 'none';
-          }
+          taskWidgetLines = (msg.lines && msg.lines.length) ? msg.lines : null;
+          renderWidgets();
           break;
         case 'notify':
           showToast(msg.message, msg.level);
@@ -798,6 +961,16 @@ export function html(wsUrl) {
           viewerBody.textContent = msg.text;
           viewer.style.display = 'block';
           break;
+        case 'reset':
+          // A new session started — wipe the previous session's transcript.
+          chatLog.innerHTML = '';
+          hideThinking();
+          currentBubble = null; streamText = '';
+          closePrompt();
+          taskWidgetLines = null;
+          renderWidgets();
+          contextFill.style.width = '0%';
+          break;
       }
     }
 
@@ -837,9 +1010,10 @@ export function html(wsUrl) {
     function connect() {
       ws = new WebSocket(WS_URL);
       ws.addEventListener('open', () => {
+        if (reconnectAnim) { clearInterval(reconnectAnim); reconnectAnim = null; }
         reconnectOverlay.classList.remove('visible');
         reconnectDelay = 1000;
-        setConn('up', 'connected');
+        setConn('up');
         setEnabled(true);
       });
       ws.addEventListener('message', (e) => {
@@ -847,9 +1021,21 @@ export function html(wsUrl) {
       });
       ws.addEventListener('close', () => {
         setEnabled(false);
-        setConn('down', 'disconnected');
+        setConn('down');
         reconnectOverlay.classList.add('visible');
-        reconnectMsg.textContent = 'reconnecting in ' + (reconnectDelay / 1000) + 's…';
+        // Animate the same braille spinner used elsewhere, with a live countdown.
+        const until = Date.now() + reconnectDelay;
+        let frame = 0;
+        const paint = () => {
+          const left = Math.max(0, Math.ceil((until - Date.now()) / 1000));
+          const glyph = SPIN[frame++ % SPIN.length];
+          reconnectMsg.textContent = left > 0
+            ? glyph + '  connection lost — retrying in ' + left + 's'
+            : glyph + '  reconnecting…';
+        };
+        if (reconnectAnim) clearInterval(reconnectAnim);
+        paint();
+        reconnectAnim = setInterval(paint, 90);
         setTimeout(() => { reconnectDelay = Math.min(reconnectDelay * 2, 30000); connect(); }, reconnectDelay);
       });
     }

package/dist/task/widget.js

@@ -5,7 +5,7 @@
  * context usage, and the latest child-process line.
  */
 import { PHASE_INDEX, PHASE_ORDER } from './task-file.js';
-import { publishWidget } from '../remote/bridge.js';
+import { setTaskWidget } from '../remote/session-state.js';
 // ─── Constants ───────────────────────────────────────────────────────────────
 export const WIDGET_KEY = 'pi-tasks';
 export const AUTO_WIDGET_KEY = 'pi-task-auto';
@@ -101,7 +101,7 @@ export function startWidget(ctx, getState) {
         catch {
             /* stale ctx */
         }
-        publishWidget(WIDGET_KEY, plain);
+        setTaskWidget(plain);
     };
     render();
     const timer = setInterval(render, WIDGET_REFRESH_MS);
@@ -114,7 +114,7 @@ export function startWidget(ctx, getState) {
         catch {
             /* stale ctx */
         }
-        publishWidget(WIDGET_KEY, undefined);
+        setTaskWidget(undefined);
     };
 }
 export function buildAutoLoaderLines(s, theme) {
@@ -150,7 +150,7 @@ export function startAutoLoader(ctx, getState) {
         catch {
             /* stale ctx */
         }
-        publishWidget(AUTO_WIDGET_KEY, plain);
+        setTaskWidget(plain);
     };
     render();
     const timer = setInterval(render, WIDGET_REFRESH_MS);
@@ -163,7 +163,7 @@ export function startAutoLoader(ctx, getState) {
         catch {
             /* stale ctx */
         }
-        publishWidget(AUTO_WIDGET_KEY, undefined);
+        setTaskWidget(undefined);
     };
 }
 export function flashTerminalWidget(ctx, state, taskId, reason) {
@@ -185,7 +185,7 @@ export function flashTerminalWidget(ctx, state, taskId, reason) {
         : `✘ ${taskId} failed${reason ? ': ' + reason : ''}`;
     try {
         ctx.ui.setWidget(WIDGET_KEY, [line]);
-        publishWidget(WIDGET_KEY, [plainLine]);
+        setTaskWidget([plainLine]);
     }
     catch {
         /* stale ctx */
@@ -193,7 +193,7 @@ export function flashTerminalWidget(ctx, state, taskId, reason) {
     setTimeout(() => {
         try {
             ctx.ui.setWidget(WIDGET_KEY, undefined);
-            publishWidget(WIDGET_KEY, undefined);
+            setTaskWidget(undefined);
         }
         catch {
             /* stale ctx */

package/dist/workers/pi-worker-docs.js

@@ -20,17 +20,20 @@ export function registerPiWorkerDocs(pi, internals = {}) {
     pi.registerTool({
         name: 'pi-worker-docs',
         label: 'Pi Worker Docs',
-        description: 'Look up an npm package locally and return a focused, version-pinned '
-            + 'answer extracted from its .d.ts types and README. No network after install (except a small '
-            + 'live npm registry call described below). The cache lives at ~/.cache/pi-worker/docs.sqlite '
-            + 'and is keyed by exact installed version.\n'
-            + 'If the package is not yet installed, it is installed automatically via bun add or npm install.\n'
-            + '\n'
-            + 'Live registry data: in addition to the docs answer, the tool fetches the latest published '
-            + 'version, recent versions, and publish date from the npm registry and prepends them to the '
-            + 'output (and exposes them in details). This is the source of truth for "what is the latest '
-            + 'version of X" questions — training-data versions are typically months stale. The lookup is '
-            + 'best-effort and silently absent when offline.\n'
+        description: 'Look up an INSTALLED npm package and return a focused, version-pinned '
+            + 'answer from its .d.ts types and README, PLUS the latest published version '
+            + 'from a live npm registry call. USE THIS BEFORE ANSWERING any question '
+            + 'about how to use a library, what it exports, its types/overloads/config, '
+            + 'or the latest published version of an npm package. Do NOT answer package '
+            + 'APIs from memory, do NOT run `npm view`/bash to get a package version, and '
+            + 'do NOT web-search for an installed package — this tool is the source of '
+            + 'truth and is version-pinned to what is actually installed (training-data '
+            + 'versions and APIs are typically months stale).\n'
+            + 'For a non-package framework/runtime version (e.g. Node.js, Ubuntu), use '
+            + '`pi-worker-search` instead. If the package is not installed it is '
+            + 'auto-installed via bun add or npm install. The cache lives at '
+            + '~/.cache/pi-worker/docs.sqlite, keyed by exact installed version; the '
+            + 'registry lookup is best-effort and silently absent when offline.\n'
             + '\n'
             + 'Good fits:\n'
             + '- "What does library X export?" / "How does function Y work?"\n'

package/dist/workers/pi-worker-search.js

@@ -14,9 +14,14 @@ export function registerPiWorkerSearch(pi, internals = {}) {
     pi.registerTool({
         name: 'pi-worker-search',
         label: 'Pi Worker Search',
-        description: 'Search the web via Brave Search. Returns a compact markdown list of '
-            + 'up to 10 results (title, URL, snippet). Use this to find candidate '
-            + 'URLs, then call `pi-worker-fetch` on the URL you want to read. '
+        description: 'Search the live web via Brave Search. CALL THIS BEFORE ANSWERING any '
+            + 'question about current or version-specific external facts: '
+            + 'library/framework versions and their APIs, latest releases, recently '
+            + 'shipped features, current events, prices, or who currently holds a '
+            + 'role. Your built-in knowledge is out of date — do NOT answer such '
+            + 'questions from memory and do NOT shell out with bash to guess. Returns '
+            + 'a compact markdown list of up to 10 results (title, URL, snippet); then '
+            + 'call `pi-worker-fetch` on the URL you want to read. '
             + 'Requires BRAVE_SEARCH_API_KEY env var.',
         parameters: Params,
         executionMode: 'parallel',

package/dist/workers/pi-worker.js

@@ -18,16 +18,19 @@ export function registerPiWorker(pi) {
     pi.registerTool({
         name: 'pi-worker',
         label: 'Pi Worker',
-        description: 'Dispatch an isolated child Pi to investigate a question and return its '
-            + 'conclusion — not the raw evidence. Use when answering requires reading '
-            + 'multiple files, running several greps, or scanning large command output '
-            + 'you do not need verbatim.\n'
+        description: 'Dispatch an isolated child Pi to investigate and return its CONCLUSION — '
+            + 'not the raw evidence. USE THIS FIRST, instead of running your own '
+            + 'ls/grep/find/read, whenever a question spans MULTIPLE files or means '
+            + 'searching/scanning code you have not already located. Doing it yourself '
+            + 'floods your context with raw file output; the worker reads in isolation '
+            + 'and returns only the answer. You can dispatch several in one turn for '
+            + 'independent questions.\n'
             + '\n'
             + 'Good fits:\n'
             + '- "Where/how is X handled in this repo?" across unfamiliar code\n'
             + '- Audits and pattern scans across many files ("every place we log PII")\n'
-            + '- Summarising long test output, logs, or shell output\n'
-            + '- Parallel fan-out: dispatch several workers in one turn for independent questions\n'
+            + '- Tracing a flow across layers (router → service → database)\n'
+            + '- Summarising long test output, logs, or shell output you do not need verbatim\n'
             + '\n'
             + 'Skip when:\n'
             + '- You already know the exact file — call `read` directly\n'