@tshu-w/pi-agents 0.1.1 → 0.2.1

package/src/workbench.mjs

@@ -6,8 +6,9 @@ import { readFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { styleText } from 'node:util';
 import { setTimeout as delay } from 'node:timers/promises';
-import { alive, attach, listHosts, startHost } from './host/client.mjs';
+import { alive, attach, listHosts, settledHosts, startHost } from './host/client.mjs';
 import { detachKey, detachMatcher } from './host/keys.mjs';
 import { piPackage } from './pi.mjs';
 import { ensureDaemon, sendViaDaemon } from './daemon/client.mjs';
@@ -37,23 +38,21 @@ function textOf(content) {
   return Array.isArray(content) ? content.filter(block => block?.type === 'text').map(block => block.text).join('\n') : '';
 }
 
-/** The messages on the Session's active branch since its last compaction, oldest first. */
-async function branchMessages(file) {
-  const entries = new Map();
+/** The messages on the Session's active branch since its last compaction, oldest first, read as Pi reads the Session. */
+async function branchMessages(pi, file) {
+  const entries = pi.parseSessionEntries(await readFile(file, 'utf8'));
+  // Older Sessions take Pi's current form.
+  pi.migrateSessionEntries(entries);
+  const byId = new Map();
   let leaf;
-  for (const line of (await readFile(file, 'utf8')).split('\n')) {
-    let entry;
-    try { entry = JSON.parse(line); } catch { continue; }
+  for (const entry of entries) {
     if (typeof entry?.id !== 'string' || entry.type === 'session') continue;
-    entries.set(entry.id, entry);
+    byId.set(entry.id, entry);
     leaf = entry;
   }
-  const messages = [];
-  for (let entry = leaf; entry && entry.type !== 'compaction'; entry = entries.get(entry.parentId)) {
-    if (entry.type === 'message' && entry.message) messages.push(entry.message);
-    else if (entry.type === 'custom_message') messages.push({ role: 'custom', ...entry });
-  }
-  return messages.reverse();
+  const branch = [];
+  for (let entry = leaf; entry && entry.type !== 'compaction'; entry = byId.get(entry.parentId)) branch.push(entry);
+  return branch.reverse().flatMap(entry => pi.sessionEntryToContextMessages(entry));
 }
 
 function age(ms) {
@@ -75,9 +74,9 @@ const COMMANDS = [
 // Pi's working spinner.
 const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 const GROUPS = [
-  ['attention', 'Needs input', 'Sessions waiting on you or with a finished turn you have not seen land here'],
-  ['working', 'Working', 'Sessions Pi is working on; they keep running after you leave'],
-  ['completed', 'Completed', 'Sessions you have seen wait here'],
+  ['attention', 'Needs attention', 'Sessions with a question for you or a reply you have not read'],
+  ['working', 'Working', 'Sessions still working; they keep running when you close the terminal'],
+  ['completed', 'Completed', 'Sessions with nothing new for you'],
 ];
 
 function stateOf(session) {
@@ -112,6 +111,8 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
   let sessions = [], stream, connected = false, quitting = false;
   // `picked` is the Session last chosen with `@` and its mention; a message starting with the mention goes to it.
   let selectedKey, top = 0, notice, modal, pane, picked, lastCtrlC = 0, finish;
+  // Messages in flight by Session ID; each settles once the daemon has delivered it, waking the Session if needed.
+  const sending = new Map();
 
   /** How `@` refers to a Session: its name when that is one word, otherwise the shortest unique ID prefix. */
   function mention(session) {
@@ -201,14 +202,15 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
     // While the preview is open, the keys are its own: Enter may send a message, so `app.tools.expand` attaches.
     const keys = pane ? [
       hints.keyHint('app.tools.expand', 'attach'),
-      hints.rawKeyHint(`${hints.keyText('tui.altScreen.pageUp')}/${hints.keyText('tui.altScreen.pageDown')}`, 'scroll'),
-      hints.rawKeyHint('esc', 'close'),
+      hints.rawKeyHint(['lineUp', 'halfPageUp', 'pageUp', 'lineDown', 'halfPageDown', 'pageDown']
+        .map(name => hints.keyText(`tui.altScreen.${name}`)).filter(Boolean).join('/'), 'scroll'),
+      hints.rawKeyHint(`${detach}/${hints.keyText('tui.select.cancel')}`, 'close'),
     ].join(theme.fg('muted', ' · ')) : [
-      hints.rawKeyHint('enter', 'attach'),
+      hints.keyHint('tui.select.confirm', 'attach'),
       hints.rawKeyHint(detach, 'quit'),
       hints.rawKeyHint('space', 'preview'),
       hints.rawKeyHint('ctrl+x', 'stop'),
-      hints.rawKeyHint('ctrl+d', 'remove'),
+      hints.keyHint('app.session.delete', 'remove'),
       hints.rawKeyHint('@', 'message'),
       hints.rawKeyHint('/', 'commands'),
     ].join(theme.fg('muted', ' · '));
@@ -275,14 +277,14 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
     handleInput(data) {
       // Holding only the preview's mention, the input counts as empty.
       const empty = ['', pane?.mention].includes(editor.getText());
-      // As in a Session, the detach key leaves and everything keeps running.
-      if (isDetach(data)) return void quit();
+      // As in a Session, the detach key leaves and everything keeps running; in the preview, it returns to the list.
+      if (isDetach(data)) return void (pane ? pane.close() : quit());
       if (pane?.handleInput(data, empty)) return;
-      if (T.matchesKey(data, 'ctrl+c')) {
+      if (keybindings.matches(data, 'app.clear')) {
         if (!empty) return editor.setText(pane?.mention ?? '');
         if (Date.now() - lastCtrlC < 1000) return void quit();
         lastCtrlC = Date.now();
-        return say('Press Ctrl+C again to quit');
+        return say(`Press ${hints.keyText('app.clear')} again to quit`);
       }
       if (T.matchesKey(data, 'ctrl+x')) return interrupt();
       if (empty && keybindings.matches(data, 'app.session.delete')) return void remove(selected()?.session);
@@ -293,10 +295,10 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
         if (pane && !editor.getText().startsWith(pane.mention)) editor.setText(before);
         return;
       }
-      if (empty && T.matchesKey(data, 'escape')) return void quit();
-      if (empty && T.matchesKey(data, 'up')) return move(-1);
-      if (empty && T.matchesKey(data, 'down')) return move(1);
-      if (empty && T.matchesKey(data, 'enter')) return void open(selected());
+      if (empty && keybindings.matches(data, 'tui.select.cancel')) return void quit();
+      if (empty && keybindings.matches(data, 'tui.select.up')) return move(-1);
+      if (empty && keybindings.matches(data, 'tui.select.down')) return move(1);
+      if (empty && keybindings.matches(data, 'tui.select.confirm')) return void open(selected());
       if (empty && T.matchesKey(data, 'space')) return void preview(selected()?.session);
       if (empty && data === '@') return pick(session => {
         picked = { session, mention: `@${mention(session)} ` };
@@ -365,7 +367,10 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
   async function openSession(session) {
     stream?.send({ type: 'show', id: session.id });
     try {
-      const hosted = (await listHosts(paths)).find(host => host.session?.id === session.id);
+      // A message just sent may be waking the Session in a host.
+      await sending.get(session.id);
+      const running = host => host.session?.id === session.id;
+      const hosted = (await settledHosts(paths, running)).find(running);
       if (hosted) return await attachTo(hosted.socket);
       if (session.running || session.status === 'unknown') {
         return say(`${named(session)} runs outside a host; attach it after it exits.`, 'warning');
@@ -418,11 +423,11 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
   async function preview(session) {
     if (!session?.sessionFile) return;
     let messages;
-    try { messages = await branchMessages(session.sessionFile); }
+    try { messages = await branchMessages(pi, session.sessionFile); }
     catch (error) { return say(error.message, 'error'); }
     let body = conversation(messages);
     const border = themes.getEditorTheme().borderColor;
-    let scroll = 0, page = 1, timer;
+    let scroll = 0, page = 1, timer, scrolled, hideBar;
     // A turn the preview shows counts as seen.
     const see = () => stream?.send({ type: 'see', id: session.id });
     see();
@@ -430,7 +435,7 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
     const watcher = watch(session.sessionFile, () => {
       clearTimeout(timer);
       timer = setTimeout(async () => {
-        try { body = conversation(await branchMessages(session.sessionFile)); }
+        try { body = conversation(await branchMessages(pi, session.sessionFile)); }
         catch (error) { return say(error.message, 'error'); }
         see();
         ui.requestRender();
@@ -440,6 +445,7 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
       watcher.close();
       see();
       clearTimeout(timer);
+      clearTimeout(hideBar);
       // A draft stays, still addressed to the Session.
       if (editor.getText() === pane?.mention) editor.setText('');
       pane = undefined;
@@ -454,34 +460,50 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
       invalidate() { body.invalidate(); },
       /** A short conversation takes only its own height; a longer one takes `max` lines and scrolls. */
       render(width, max) {
-        const current = sessions.find(other => other.id === session.id) ?? session;
-        const live = ['working', 'blocked', 'unknown'].includes(current.status) ? `  ${icon(current)} ${activity(current)}` : '';
-        const head = truncate(` ${theme.bold(label(session))}  ${theme.fg('dim', session.cwd ?? '')}${live}`, width);
-        const lines = body.render(width);
+        // The selected row and the input's mention name the Session, so the preview needs no title. A blank line
+        // sets it apart from the list.
+        const top = ['', border('─'.repeat(width))];
+        const bar = width > 1 ? settings.getFullscreenScrollbar() : 'hidden';
+        // The conversation starts right below the border.
+        const lines = body.render(bar === 'always' ? width - 1 : width);
+        while (lines.length && !T.stripTerminalSequences(lines[0]).trim()) lines.shift();
         page = Math.max(1, max - 2);
         scroll = Math.min(scroll, Math.max(0, lines.length - page));
-        const end = lines.length - scroll;
-        return [border('─'.repeat(width)), head, ...lines.slice(Math.max(0, end - page), end)];
+        const end = lines.length - scroll, start = Math.max(0, end - page);
+        const shown = lines.slice(start, end);
+        if (bar !== 'always' && !(bar === 'auto' && scrolled && lines.length > page)) return [...top, ...shown];
+        // The scrollbar of Pi's fullscreen transcript, in the last column.
+        const track = shown.length, size = Math.max(Math.min(2, track), Math.min(track, Math.round(track * track / lines.length)));
+        const offset = lines.length === track ? 0 : Math.round(start / (lines.length - track) * (track - size));
+        const cell = row => row >= offset && row < offset + size ? theme.fg('scrollbarThumb', '┃') : theme.fg('scrollbarTrack', '│');
+        return [...top, ...shown.map((line, row) => `${T.truncateToWidth(line, width - 1, '', true)}${cell(row)}`)];
       },
       /** Enter, `↑`/`↓`, and Space act on the preview only while no message is typed. */
       handleInput(data, empty) {
-        if (keybindings.matches(data, 'app.tools.expand') || (empty && T.matchesKey(data, 'enter'))) {
+        if (keybindings.matches(data, 'app.tools.expand') || (empty && keybindings.matches(data, 'tui.select.confirm'))) {
           close();
           void openSession(session);
           return true;
         }
-        if (!empty && T.matchesKey(data, 'escape')) {
+        if (!empty && keybindings.matches(data, 'tui.select.cancel')) {
           editor.setText(pane.mention);
           return true;
         }
-        if (T.matchesKey(data, 'escape') || (empty && (T.matchesKey(data, 'space') || T.matchesKey(data, 'ctrl+c')))) {
+        if (keybindings.matches(data, 'tui.select.cancel') || (empty && (T.matchesKey(data, 'space') || keybindings.matches(data, 'app.clear')))) {
           close();
           return true;
         }
-        const step = empty && T.matchesKey(data, 'up') ? 1 : empty && T.matchesKey(data, 'down') ? -1
-          : keybindings.matches(data, 'tui.altScreen.pageUp') ? page - 1 : keybindings.matches(data, 'tui.altScreen.pageDown') ? 1 - page : 0;
+        // The scroll keys of Pi's fullscreen mode; a step counts lines up from the end.
+        const half = Math.max(1, Math.floor(page / 2));
+        const steps = { lineUp: 1, lineDown: -1, halfPageUp: half, halfPageDown: -half, pageUp: page - 1, pageDown: 1 - page, top: Infinity, bottom: -Infinity };
+        const action = Object.keys(steps).find(name => keybindings.matches(data, `tui.altScreen.${name}`));
+        const step = empty && keybindings.matches(data, 'tui.select.up') ? 1 : empty && keybindings.matches(data, 'tui.select.down') ? -1 : action ? steps[action] : 0;
         if (!step) return false;
         scroll = Math.max(0, scroll + step);
+        // As in Pi's `auto` mode, the scrollbar shows while scrolling and for a second after.
+        scrolled = true;
+        clearTimeout(hideBar);
+        hideBar = setTimeout(() => { scrolled = false; ui.requestRender(); }, 1000);
         ui.requestRender();
         return true;
       },
@@ -490,20 +512,27 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
     ui.requestRender(true);
   }
 
-  /** Messages and replies as Pi shows them; thinking is left out and each run of tool calls folds to one line. */
+  /**
+   * Messages and replies as Pi shows them; thinking is left out, and each run of tool calls, branch summary, and custom
+   * message other than the user's input folds to one line.
+   */
   function conversation(messages) {
     const markdown = themes.getMarkdownTheme();
     const view = new T.Container();
     let tools = [];
+    // Pi's hint for folded output: "... (36 more lines, …)".
+    const summarize = summary => {
+      view.addChild(new T.Spacer(1));
+      view.addChild(new T.Text(theme.fg('muted', `... (${summary})`), 1, 0));
+    };
     const fold = () => {
       if (!tools.length) return;
-      // Pi's hint for folded output: "... (36 more lines, …)".
-      const names = [...new Set(tools)].join(', ');
-      view.addChild(new T.Spacer(1));
-      view.addChild(new T.Text(theme.fg('muted', `... (${tools.length} tool call${tools.length > 1 ? 's' : ''}: ${names})`), 1, 0));
+      summarize(`${tools.length} tool call${tools.length > 1 ? 's' : ''}: ${[...new Set(tools)].join(', ')}`);
       tools = [];
     };
     for (const message of messages) {
+      // As in Pi's chat, a custom message not for display is skipped.
+      if (message.role === 'custom' && !message.display) continue;
       const user = message.role === 'user' || (message.role === 'custom' && message.customType === 'pi-agents' && message.details?.user);
       if (user) {
         const text = textOf(message.content).trim();
@@ -518,6 +547,13 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
           view.addChild(new pi.AssistantMessageComponent({ ...message, content }, true, markdown));
         }
         tools.push(...message.content.flatMap(part => part.type === 'toolCall' ? [part.name] : []));
+      } else if (message.role === 'branchSummary') {
+        fold();
+        summarize('branch summary');
+      } else if (message.role === 'custom') {
+        const from = message.customType === 'pi-agents' ? message.details?.sender?.name ?? message.details?.sender?.id : undefined;
+        fold();
+        summarize(from ? `message from ${from}` : `${message.customType} message`);
       }
     }
     fold();
@@ -528,8 +564,12 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
   async function send(session, body) {
     say(`Sending to ${named(session)}…`);
     const message = { id: randomUUID(), user: true, recipient: session.id, body };
+    const pending = sendViaDaemon(paths, message, { sessionDir, launch: { command: executable, args: [], env } });
+    const settled = pending.then(() => {}, () => {});
+    sending.set(session.id, settled);
+    void settled.then(() => { if (sending.get(session.id) === settled) sending.delete(session.id); });
     try {
-      const receipt = await sendViaDaemon(paths, message, { sessionDir, launch: { command: executable, args: [], env } });
+      const receipt = await pending;
       if (receipt?.accepted !== true || receipt.messageId !== message.id) throw new Error(`Invalid acknowledgement from ${named(session)}; it may have received the message.`);
       say(`Sent to ${named(session)}.`);
     } catch (error) { say(error.message, 'error'); }
@@ -587,7 +627,7 @@ export async function workbench({ pi: executable, paths, sessionDir }) {
     themeSync.disableAutoSync();
     await terminal.drainInput(1000);
     ui.stop();
-    process.stdout.write(`${MAIN_SCREEN}Sessions keep running. To reopen, run pd agents\n`);
+    process.stdout.write(`${MAIN_SCREEN}${styleText('dim', 'Sessions keep running. To reopen:')} pd agents\n`);
     finish();
   }
 

package/docs/WORKBENCH.md

@@ -1,167 +0,0 @@
-# Pi Agents Workbench
-
-## 1. Overview
-
-The workbench shows the user's root Sessions in one terminal view. From it the
-user opens a Session, reads its latest result, or sends it a message. Sessions
-started with `pd` keep running after their terminal closes.
-
-Three kinds of process take part:
-
-- **Host**: one per Session. It runs Pi's full TUI in a pseudo-terminal and
-  relays it to whichever terminal is attached.
-- **Daemon**: one per user. It tracks Sessions, delivers messages, and starts
-  hosts.
-- **Workbench**: the daemon's terminal view, opened with `pd agents`.
-
-Every running root Session reports its state to the daemon. The daemon starts
-when a Session or the workbench first needs it, and exits 30 seconds after its
-last connection closes.
-
-Files live in `${XDG_STATE_HOME:-~/.local/state}/pi/agents/`:
-
-- `workbench.json`: seen marks and which Sessions are listed. The file is
-  versioned.
-- `host.log`, `daemon.log`: logs.
-
-Sockets and Session locks go in `$XDG_RUNTIME_DIR/pi-agents/`. macOS has no
-`XDG_RUNTIME_DIR`, so there they go in `runtime/` under the state directory.
-
-## 2. Setup
-
-Install with npm to get the `pd` command, also named `pi-agents`, then have Pi
-load the extension from the same copy, so the command and the extension are
-always the same version:
-
-    npm install -g @tshu-w/pi-agents
-    pi install "$(npm root -g)/@tshu-w/pi-agents"
-
-`pd` runs whichever `pi` is on `PATH`. Sessions started with plain `pi` also
-load the extension, but run outside hosts and end with their terminal.
-
-## 3. Commands
-
-- `pd [pi options]` starts Pi interactively in a new host and attaches the
-  terminal. If the Session is already running in a host, `pd` attaches to it
-  instead.
-- `pd agents` opens the workbench.
-- `pd attach <session>` attaches to a Session, starting it first if it is not
-  running.
-- Non-interactive starts (`-p`, `--mode`, piped stdin) and package commands
-  (`pd install`, `pd update`, ...) run Pi directly.
-
-A host inherits the environment of the process that asked for it, because Pi
-reads terminal features from the environment once, at startup.
-
-A Session running outside a host still appears in the workbench, but can be
-attached only after it exits.
-
-## 4. Attach and detach
-
-Only one terminal is attached at a time. A new terminal takes over, and the
-previous one is told how to reattach.
-
-On attach, the host restores the screen and the terminal modes Pi has set
-(keyboard protocols, bracketed paste, mouse, title, program status). Images
-come back when the host then has Pi redraw.
-
-A host started from a terminal waits for that terminal to attach before it
-starts Pi, so Pi detects the terminal's colors and keyboard protocol just as it
-would without a host. A host started in the background passes the queries Pi
-sent at startup to the first terminal that attaches, and Pi finishes detecting
-then.
-
-Closing the window, pressing `Ctrl+Z` (the `pi-agents.detach` keybinding), or
-running `/detach` detaches. The Session keeps running, and the terminal prints:
-
-    Pi keeps running. To reattach, run pd attach <session>
-
-A host disables suspend, since a suspended Pi would stay stopped; `Ctrl+Z`
-detaches in its place.
-
-A detached Session exits once its tree has had no live work for 5 minutes. A
-message to a Session that is not running starts it in a host, detached.
-
-## 5. Workbench
-
-The list shows running Sessions, Sessions that ran without a terminal (started
-here, woken by a message, or detached), Sessions opened here, and Sessions
-with an unseen turn. Older Sessions are reached with `/resume`.
-
-Each row shows a root Session's name and what it did last. The name is the
-Session name, or else the first line of its first message. While the Session
-works, the row shows the running tool; otherwise, the start of its last reply.
-Running owned Agents and Programs are counted, as in `3 agents running`.
-
-Rows are grouped by state, newest first in each group:
-
-- **Needs input**: a dialog waiting for the user, or a finished turn the user
-  has not seen. A turn that failed after Pi's retries, or a host that exited
-  abnormally, is marked failed.
-- **Working**: the Session or its tree has live work.
-- **Completed**: everything else.
-
-While a Session works, its icon spins. Otherwise the shape tells whether Pi is
-still running (`●`) or has exited (`○`), and the color marks a finished (green)
-or failed (red) turn, or a dialog waiting for the user (yellow). The header
-shows Pi's logo, the size of each group, and key hints.
-
-A turn counts as seen once it has been shown in an attached terminal or a
-preview. Sessions
-from before the workbench start out seen. A Session that holds its lock but is
-not reporting to the daemon, as while its Pi exits, shows as unknown (`?`); the
-daemon checks it again every second until that changes.
-
-Keys:
-
-- `Enter` attaches; detaching returns here.
-- `Space` previews the selected Session below the list: the conversation
-  since the last compaction, with thinking left out and each run of tool
-  calls folded to one line, such as `... (6 tool calls: bash, read, edit)`.
-  The preview follows the Session as it works.
-  The input keeps `@<session>` at its start, so a message goes to the
-  previewed Session. In the preview:
-  - `Enter` sends a typed message; with none typed, it attaches.
-  - `Ctrl+O` (`app.tools.expand`) attaches.
-  - The page keys of fullscreen mode (`tui.altScreen.pageUp`/`pageDown`)
-    scroll; with no message typed, `↑`/`↓` scroll too.
-  - `Esc` clears a typed message; with none typed, it closes the preview.
-- `Ctrl+X` stops the current turn, as `app.interrupt` does.
-- `Ctrl+D` removes the selected Session from the list. Its file stays, and
-  `/resume` brings it back. An idle Session in a host that no terminal is
-  attached to quits first; any other running Session must quit itself.
-- `Ctrl+Z` (`pi-agents.detach`) exits the workbench, as detaching leaves a
-  Session; every Session keeps running.
-
-The input at the bottom:
-
-- `@` on an empty input opens Pi's session picker. The chosen Session is
-  selected in the list, and the input starts with `@<session>`; the text after
-  it goes to that Session as a user message. After `/`, Tab completes a
-  command.
-- `/resume` opens Pi's session picker over all directories, newest first, and
-  attaches the chosen Session. `Ctrl+D` in the picker deletes a Session file.
-- `/quit` exits the workbench, as do `Esc` and `Ctrl+C` twice on an empty
-  input.
-- Any other text starts a new Session in the current directory with Pi's
-  default settings, detached.
-
-## 6. Upgrades
-
-A host keeps running the version it started with until its Session exits.
-When the daemon sees a newer pi-agents version, it restarts once idle, and
-Sessions reconnect to the new daemon.
-
-## 7. Platform
-
-macOS and Linux. Every dependency is pure JavaScript or prebuilt: hosts use
-`@lydell/node-pty`, and a Session lock is a file that records the process
-holding it.
-
-## Not in this version
-
-Attaching several terminals to one Session, Sessions on other machines,
-model-written summaries, and a confirmation before quitting while work is
-running. Keeping Sessions alive across host crashes and reboots needs a
-durable runtime, which [Pi Durable](https://earendil.com/posts/pi-durable/)
-explores.