@softov/ahpc 0.3.0 → 0.4.0

package/dist/src/tui.js

@@ -2,6 +2,7 @@ import { WRITER_KEY, createApp } from '@textui/core';
 import { writeFile } from 'node:fs/promises';
 import { bufferToSvg, createNodeTerminal, createWriter, renderStill, } from '@textui/terminal';
 import { registerChat } from './app.js';
+import { parseSessionLink } from './links.js';
 import { CONTROLLER } from './control.js';
 import { connect, sink } from './connect.js';
 import { loadConfig } from './config.js';
@@ -30,6 +31,11 @@ What this client serves back
                         terminal attached this prints one frame and exits,
                         so a background shell publishes nothing.
 
+Seeing the wire
+  --wire <file>         Append every frame, both directions, as JSON lines:
+                        { at, from, peer, frame }. AHPC_RECORD=<file> is
+                        the same thing from a shell.
+
 Appearance
   --theme <name>        workbench, paper-light, ...
   --shell <name>        The shell layout
@@ -37,7 +43,8 @@ Appearance
   --bood                Let the creature loose on the whole screen. It
                         keeps off the composer and off anything asking
                         a question, and alt+g turns it off again.
-  --session <uri>       Open this session
+  --session <uri>       Open this session, by its URI or by an
+                        agent-host-session:// link
 
 Stills, for a README or a test
   --static, -s          One frame to stdout instead of running
@@ -148,6 +155,9 @@ export function parse(argv) {
             case '--publish-writable':
                 options.publishWritable = true;
                 break;
+            case '--wire':
+                options.wire = String(argv[++i]);
+                break;
             case '--help':
             case '-h':
                 options.help = true;
@@ -198,10 +208,15 @@ async function still(options) {
         // of scripted words rather than all of them, and the caret is wherever the
         // agent had got to. `--settled` runs until the script has nothing left it
         // can do without being answered, which is how the confirmation is reached.
-        before: (app) => {
+        before: async (app) => {
             const controller = app.services.require(CONTROLLER);
-            if (options.session)
-                controller.open(options.session);
+            // A URI, or the link the reference host's tools answer with.
+            if (options.session) {
+                if (parseSessionLink(options.session))
+                    await controller.openLink(options.session);
+                else
+                    controller.open(options.session);
+            }
             /*
              * Pushed when asked for, and not otherwise.
              *
@@ -346,6 +361,15 @@ export async function tui(argv) {
     app.services.provide(WRITER_KEY, createWriter(terminal.capabilities()));
     sink.report = (message) => reportHostError(app.store, message);
     await app.start();
+    // `--session`, on the screen as well as in a still: the conversation named,
+    // by its URI or by an `agent-host-session://` link, opened on arrival.
+    if (options.session) {
+        const controller = app.services.require(CONTROLLER);
+        const named = options.session;
+        const opened = parseSessionLink(named) ? controller.openLink(named) : (controller.open(named), Promise.resolve(true));
+        void opened.then((ok) => { if (ok)
+            app.screens.push('chat'); });
+    }
     /**
      * The last resort, and the reason it exists at all.
      *

package/dist/src/view/creature.d.ts

@@ -43,18 +43,6 @@ export type { CreatureProps, Form, Mood } from './bood/index.js';
  * that matches the status row above it.
  */
 export declare function moodOf(activity: Activity): Mood;
-/**
- * Say which row this component starts at, so nothing stands on top of it.
- *
- * Its top row rather than its height: the row is where the thing actually is,
- * and a height has to be added to a guess about everything below it to mean
- * anything. Published rather than assumed because it moves - the composer
- * grows a slash menu upward and grows again with a wrapped draft, and the
- * block that asks about a tool is only there while something is waiting.
- * Cleared on the way out, or a screen that had one would keep making room for
- * it after it had gone.
- */
-export declare function useFloorTop(key: string, row: number): void;
 /**
  * One animal per run, rather than one per component that draws one.
  *

package/dist/src/view/creature.js

@@ -25,8 +25,6 @@
  * instead of being the big one shrunk.
  */
 import { BOOD, boodHeight, livelyNames } from './bood/index.js';
-import { useApp, useEffect } from '@textui/core';
-import { boodFloorFor } from '../state.js';
 export { BoodSprite, Creature, MOODS, FORMS, creatureFrames, creatureMotion, creatureSize, drawCreature, livelyNames, } from './bood/index.js';
 /**
  * What the figure is doing, from what the session is doing.
@@ -48,24 +46,6 @@ export function moodOf(activity) {
             : activity === 'input' ? 'thinking'
                 : 'happy';
 }
-/**
- * Say which row this component starts at, so nothing stands on top of it.
- *
- * Its top row rather than its height: the row is where the thing actually is,
- * and a height has to be added to a guess about everything below it to mean
- * anything. Published rather than assumed because it moves - the composer
- * grows a slash menu upward and grows again with a wrapped draft, and the
- * block that asks about a tool is only there while something is waiting.
- * Cleared on the way out, or a screen that had one would keep making room for
- * it after it had gone.
- */
-export function useFloorTop(key, row) {
-    const app = useApp();
-    useEffect(() => {
-        app.store.set(boodFloorFor(key), row);
-        return () => app.store.set(boodFloorFor(key), 0);
-    }, [key, row]);
-}
 /**
  * One animal per run, rather than one per component that draws one.
  *

package/dist/src/view/wire.d.ts

@@ -0,0 +1,36 @@
+import type { BindingPath, BoxProps, Disposable, RenderOutput, TextUIApp } from '@textui/core';
+import type { WireRow } from '../wire.js';
+export declare const WIRE_ROWS: BindingPath;
+export declare const WIRE_FILTER: BindingPath;
+export declare const WIRE_SELECTED: BindingPath;
+export declare const WIRE_FOLLOW: BindingPath;
+export declare const WIRE_FILE: BindingPath;
+export declare const WIRE_FRAME: BindingPath;
+export declare const WIRE_SCOPE = "wire.rows";
+/** The rows the filter keeps, from what the store holds. */
+export declare const visibleRows: (rows: WireRow[], filter: string) => WireRow[];
+export interface WireListProps extends BoxProps {
+    rows: WireRow[];
+    selectedId?: string | null;
+    onSelect?(id: string): void;
+    onOpen?(id: string): void;
+    emptyMessage?: string;
+    focusId?: string;
+    autoFocus?: boolean;
+}
+export declare const WireList: (props: WireListProps) => RenderOutput;
+export declare const WireScreen: (props: Record<string, never>) => RenderOutput;
+export interface WireOptions {
+    /** The capture to read. */
+    file: string;
+    /** How often to look for more of it, in milliseconds. */
+    interval?: number;
+    builtins?: boolean;
+}
+/**
+ * The wire screen on an application, reading one file.
+ *
+ * The same shape as `registerChat`, and nothing shared with it: no host, no
+ * controller, no sessions. What comes back takes the reader down with it.
+ */
+export declare function registerWire(app: TextUIApp, options: WireOptions): Disposable;

package/dist/src/view/wire.js

@@ -0,0 +1,196 @@
+import { jsx as _jsx, jsxs as _jsxs } from "@textui/core/jsx-runtime";
+import { createBag, defineComponent, useApp, useEffect, useFocusScope, useSize, useStoreValue, useTheme } from '@textui/core';
+import { Column, KeyHints, List, Panel, Row, ScrollView, SearchBox, registerBuiltins } from '@textui/widgets';
+import { follow, matches } from '../wire.js';
+/*
+ * The wire, as a screen.
+ *
+ * One row per frame and nothing else on it: the time, which way it went, the
+ * method or the action type, the channel. A row opens to the frame itself.
+ * The file is read as it grows, so a capture `ahpd --wire` or this client is
+ * still writing is watched live - which is the point: every question about
+ * the wire had been answered by reading source, and this answers it by
+ * looking.
+ *
+ * Its own screen rather than one of the conversation's, because it needs no
+ * host. A capture is a file, and the file may be the other end's.
+ */
+export const WIRE_ROWS = '$/wire/rows';
+export const WIRE_FILTER = '$/wire/filter';
+export const WIRE_SELECTED = '$/wire/selected';
+export const WIRE_FOLLOW = '$/wire/follow';
+export const WIRE_FILE = '$/wire/file';
+export const WIRE_FRAME = '$/wire/frame';
+export const WIRE_SCOPE = 'wire.rows';
+/** The most frames held. A capture of a long session is more than a screen can list, and the newest are what is being watched. */
+const KEPT = 20_000;
+/** Below this width the frame is a drawer over the list rather than a pane beside it. */
+const SPLIT = 100;
+const TONE = {
+    request: 'default',
+    notification: 'default',
+    response: 'muted',
+    error: 'danger',
+    text: 'warning',
+};
+/** The rows the filter keeps, from what the store holds. */
+export const visibleRows = (rows, filter) => (filter.trim() === '' ? rows : rows.filter((row) => matches(row, filter)));
+/** The frame, as lines. Capped: a snapshot can run to thousands, and the top of it is what says what it is. */
+const linesOf = (frame) => {
+    const text = typeof frame === 'string' ? frame : JSON.stringify(frame, null, 2) ?? '';
+    const lines = text.split('\n');
+    return lines.length > 3000 ? [...lines.slice(0, 3000), `… ${lines.length - 3000} more lines`] : lines;
+};
+export const WireList = defineComponent('WireList', (props) => {
+    const { rows, selectedId, onSelect, onOpen, emptyMessage, focusId, autoFocus, ...rest } = props;
+    const theme = useTheme();
+    const byId = new Map(rows.map((row) => [String(row.seq), row]));
+    const items = rows.map((row) => ({ id: String(row.seq), label: row.method || row.kind, tone: TONE[row.kind] }));
+    return (_jsx(List, { items: items, ...(selectedId ? { selectedId } : {}), ...(focusId ? { focusId } : {}), ...(autoFocus ? { autoFocus } : {}), ...(onSelect ? { onSelect: (id) => onSelect(id) } : {}), ...(onOpen ? { onActivate: (id) => onOpen(id) } : {}), emptyMessage: emptyMessage ?? 'Nothing on the wire yet', renderItem: (item, state) => {
+            const row = byId.get(item.id);
+            if (row === undefined)
+                return _jsx("text", { content: item.label });
+            const time = row.at.length >= 23 ? row.at.slice(11, 23) : row.at;
+            // Which way it went, drawn as an arrow between the two ends: the
+            // client is on the left, the host on the right, on every row.
+            const arrow = row.from === 'client' ? theme.glyphs.arrowRight : theme.glyphs.arrowLeft;
+            const what = row.kind === 'response' ? `${row.method} ${theme.glyphs.check}` : row.kind === 'error' ? `${row.method} ${theme.glyphs.cross}` : row.method || row.kind;
+            const dim = state.selected ? {} : { fg: 'subtle' };
+            return (_jsxs(Row, { gap: 1, children: [_jsx("text", { content: time, shrink: 0, ...dim }), _jsx("text", { content: arrow, shrink: 0, ...(state.selected ? {} : { fg: (row.from === 'client' ? 'accent' : 'info') }) }), _jsx("text", { content: what, shrink: 0, bold: row.kind === 'request' || row.kind === 'notification', ...(state.selected ? {} : { fg: TONE[row.kind] }) }), row.type ? _jsx("text", { content: row.type, shrink: 0, ...(state.selected ? {} : { fg: 'accent' }) }) : null, row.channel ? _jsx("text", { content: row.channel, shrink: 2, truncate: "start", ...dim }) : null, _jsx("text", { content: row.detail, flex: 1, truncate: "end", ...dim })] }));
+        }, ...rest }));
+});
+export const WireScreen = defineComponent('WireScreen', () => {
+    const app = useApp();
+    const theme = useTheme();
+    useFocusScope({ id: WIRE_SCOPE });
+    const rows = useStoreValue(WIRE_ROWS, []) ?? [];
+    const filter = useStoreValue(WIRE_FILTER, '') ?? '';
+    const selected = useStoreValue(WIRE_SELECTED, null) ?? null;
+    const following = useStoreValue(WIRE_FOLLOW, true) ?? true;
+    const file = useStoreValue(WIRE_FILE, '') ?? '';
+    const drawer = useStoreValue(WIRE_FRAME, false) ?? false;
+    const shown = visibleRows(rows, filter);
+    const width = useSize().width;
+    const wide = width >= SPLIT;
+    const open = wide || drawer;
+    // Following: the highlight stays on the newest row the filter keeps, so
+    // a live capture reads like a tail. Stopped by moving the highlight.
+    const last = shown.at(-1);
+    useEffect(() => {
+        if (shown.length === 0)
+            return;
+        if (following) {
+            app.store.set(WIRE_SELECTED, String(last?.seq ?? ''));
+            return;
+        }
+        if (selected !== null && shown.some((row) => String(row.seq) === selected))
+            return;
+        app.store.set(WIRE_SELECTED, String(last?.seq ?? ''));
+    }, [last?.seq ?? 0, following, filter]);
+    const current = shown.find((row) => String(row.seq) === selected) ?? null;
+    const aside = Math.max(40, Math.min(80, Math.round(width * 0.45)));
+    const list = (_jsxs(Panel, { title: "Wire", ...(open && wide ? { width: width - aside - 1 } : { flex: 1 }), meta: `${shown.length}${shown.length === rows.length ? '' : ` of ${rows.length}`} frames${following ? `  ${theme.glyphs.bulletFilled} following` : ''}`, children: [_jsx(SearchBox, { value: filter, placeholder: "method, action type, channel, id", focusId: "wire.filter", onChange: (value) => app.store.set(WIRE_FILTER, value) }), _jsx(WireList, { rows: shown, selectedId: selected, focusId: "wire.list", autoFocus: true, flex: 1, onSelect: (id) => {
+                    if (id !== selected && id !== String(last?.seq ?? ''))
+                        app.store.set(WIRE_FOLLOW, false);
+                    app.store.set(WIRE_SELECTED, id);
+                }, onOpen: () => { app.store.set(WIRE_FRAME, true); app.focus.focus('wire.frame'); }, emptyMessage: rows.length === 0 ? `Nothing in ${file || 'the capture'} yet` : 'Nothing matches' }), _jsx("text", { content: file, fg: "subtle", truncate: "start" })] }));
+    const frame = current ? (_jsxs(Panel, { title: `${current.from === 'client' ? 'client' : 'host'} ${current.from === 'client' ? theme.glyphs.arrowRight : theme.glyphs.arrowLeft} ${current.method || current.kind}`, ...(wide ? { width: aside } : { flex: 1 }), meta: current.id !== undefined ? `id ${current.id}` : current.kind, children: [_jsxs(Row, { gap: 1, children: [_jsx("text", { content: current.at, fg: "subtle", shrink: 0 }), current.peer ? _jsx("text", { content: current.peer, fg: "muted", flex: 1, truncate: "start" }) : null] }), _jsx(ScrollView, { flex: 1, focusId: "wire.frame", children: _jsx(Column, { children: linesOf(current.frame).map((line, index) => (_jsx("text", { content: line, wrap: "none", truncate: "end", ...(current.kind === 'error' && index === 0 ? { fg: 'danger' } : {}) }, index))) }) })] })) : (_jsx(Panel, { title: "Frame", ...(wide ? { width: aside } : { flex: 1 }), children: _jsx("text", { content: "No frame under the highlight.", fg: "subtle" }) }));
+    if (!wide)
+        return open ? frame : list;
+    return (_jsxs(Row, { flex: 1, gap: 1, children: [list, open ? frame : null] }));
+});
+const WireHeader = defineComponent('WireHeader', () => {
+    const theme = useTheme();
+    const file = useStoreValue(WIRE_FILE, '') ?? '';
+    return (_jsxs(Row, { gap: 1, children: [_jsx("text", { content: "Wire", bold: true, fg: "accent", shrink: 0 }), _jsx("text", { content: theme.glyphs.separator, fg: "subtle", shrink: 0 }), _jsx("text", { content: file, fg: "muted", flex: 1, truncate: "start" })] }));
+});
+const WireHints = defineComponent('WireHints', (props) => {
+    const theme = useTheme();
+    const following = useStoreValue(WIRE_FOLLOW, true) ?? true;
+    return (_jsx(KeyHints, { ...props, hints: [
+            { keys: `${theme.glyphs.arrowUp}${theme.glyphs.arrowDown}`, label: 'frame' },
+            { keys: 'enter', label: 'open' },
+            { keys: 'esc', label: 'back' },
+            { keys: 'f', label: following ? 'stop following' : 'follow' },
+            { keys: 'ctrl+f', label: 'filter' },
+            { keys: 'ctrl+c', label: 'quit' },
+        ] }));
+});
+/**
+ * The wire screen on an application, reading one file.
+ *
+ * The same shape as `registerChat`, and nothing shared with it: no host, no
+ * controller, no sessions. What comes back takes the reader down with it.
+ */
+export function registerWire(app, options) {
+    const bag = createBag();
+    if (options.builtins !== false)
+        bag.add(registerBuiltins(app));
+    app.store.set(WIRE_FILE, options.file);
+    app.store.set(WIRE_ROWS, []);
+    app.store.set(WIRE_FOLLOW, true);
+    app.store.set(WIRE_FRAME, false);
+    for (const [component, render] of [
+        ['WireList', WireList],
+        ['WireScreen', WireScreen],
+        ['WireHeader', WireHeader],
+        ['WireHints', WireHints],
+    ]) {
+        bag.add(app.components.register({ component, category: 'template', renderer: { kind: 'function', render: render } }));
+    }
+    bag.add(app.surfaces.open({ surface: 'header', key: 'title', target: { component: 'WireHeader' } }));
+    bag.add(app.surfaces.open({ surface: 'status', key: 'status', target: { component: 'WireHints' } }));
+    bag.add(app.screens.register({ id: 'wire', component: 'WireScreen' }));
+    bag.add(app.commands.register({
+        id: 'wire.follow',
+        title: 'Follow the wire',
+        category: 'Wire',
+        description: 'Keep the highlight on the newest frame',
+        slots: ['palette'],
+        keepOpen: true,
+        checked: WIRE_FOLLOW,
+        run: () => app.store.set(WIRE_FOLLOW, !(app.store.get(WIRE_FOLLOW) ?? true)),
+    }));
+    bag.add(app.commands.register({
+        id: 'wire.filter',
+        title: 'Filter the wire',
+        category: 'Wire',
+        description: 'Keep the frames whose method, action type or channel match',
+        slots: ['palette'],
+        run: () => app.focus.focus('wire.filter'),
+    }));
+    bag.add(app.commands.register({
+        id: 'wire.openFrame',
+        title: 'Open the frame',
+        category: 'Wire',
+        description: 'Read the frame under the highlight',
+        slots: ['palette'],
+        run: () => { app.store.set(WIRE_FRAME, true); app.focus.focus('wire.frame'); },
+    }));
+    bag.add(app.commands.register({
+        id: 'wire.closeFrame',
+        title: 'Back to the list',
+        category: 'Wire',
+        description: 'Put the frame away',
+        slots: ['palette'],
+        run: () => { app.store.set(WIRE_FRAME, false); app.focus.focus('wire.list'); },
+    }));
+    for (const binding of [
+        { keys: 'f', commandId: 'wire.follow', scopeId: WIRE_SCOPE },
+        { keys: 'ctrl+f', commandId: 'wire.filter' },
+        { keys: 'right', commandId: 'wire.openFrame', scopeId: WIRE_SCOPE },
+        { keys: 'left', commandId: 'wire.closeFrame', scopeId: WIRE_SCOPE },
+        { keys: 'escape', commandId: 'wire.closeFrame', scopeId: WIRE_SCOPE },
+    ])
+        bag.add(app.keybindings.register(binding));
+    // The file, folded in as it grows. Kept to the newest `KEPT`, and the
+    // sequence numbers keep counting so a row's name never changes under it.
+    const reader = follow(options.file, (rows) => {
+        const held = app.store.get(WIRE_ROWS) ?? [];
+        const next = [...held, ...rows];
+        app.store.set(WIRE_ROWS, next.length > KEPT ? next.slice(next.length - KEPT) : next);
+    }, options.interval === undefined ? {} : { interval: options.interval });
+    bag.add({ dispose: () => reader.close() });
+    app.screens.reset('wire');
+    return bag;
+}

package/dist/src/wire.d.ts

@@ -0,0 +1,70 @@
+/**
+ * A wire capture, read back.
+ *
+ * `--wire <file>` on either end writes one line per frame, `{ at, from, peer,
+ * frame }`, and this is the other half: the lines as rows a screen can list,
+ * and a reader that keeps up with a file still being written. Nothing here
+ * renders, and nothing here needs a host - a capture is a file, and the two
+ * ends of a conversation can be read from the same shell.
+ */
+/** One line of a capture, as written by `ahpd --wire` and `ahpc --wire`. */
+export interface WireLine {
+    at: string;
+    from: 'client' | 'host';
+    peer?: string;
+    frame: unknown;
+}
+/** One frame, described. Everything a row shows is decided here, once. */
+export interface WireRow {
+    /** Its line number in the file, which is the only name a frame has. */
+    seq: number;
+    at: string;
+    from: 'client' | 'host';
+    peer: string;
+    /** What kind of JSON-RPC message the frame is. */
+    kind: 'request' | 'response' | 'error' | 'notification' | 'text';
+    /** The method, or for a response the method of the request it answers. */
+    method: string;
+    /** The request id, where there is one. */
+    id?: string;
+    /** The channel the frame names, where it names one. */
+    channel?: string;
+    /** The action type, for a dispatch or an action. */
+    type?: string;
+    /** One line about the payload: the error message, the action, the text. */
+    detail: string;
+    frame: unknown;
+}
+/** One line parsed, or undefined for one that is not a capture line. */
+export declare function parseWireLine(text: string): WireLine | undefined;
+/**
+ * The frames described, in order.
+ *
+ * A response says nothing about what it answers, so the requests are held by
+ * id and direction until their answer goes by - which is what puts a method
+ * on a response row, and is why this is a reader with state rather than a
+ * function of one line.
+ */
+export declare function describer(): (line: WireLine, seq: number) => WireRow;
+/** Whether a row is one the filter keeps. A substring of anything a row shows, the way the catalogue filters. */
+export declare const matches: (row: WireRow, query: string) => boolean;
+export interface Follower {
+    /** Stop reading. */
+    close(): void;
+}
+/**
+ * The file, as it grows.
+ *
+ * Read from the top, then from wherever the last read stopped whenever the
+ * file changes - `fs.watch` where the platform has it, and a poll beside it
+ * because a watcher on a file being appended to by another process is not
+ * something every platform delivers. A line still being written is kept
+ * until its newline arrives, so a frame is never handed over in halves. A
+ * file cut back to nothing, which is what a new `--wire` run does, starts
+ * over rather than reading past its end.
+ */
+export declare function follow(path: string, onRows: (rows: WireRow[]) => void, options?: {
+    interval?: number;
+}): Follower;
+/** A row as one line of text, for a shell that is not a terminal. */
+export declare const rowText: (row: WireRow) => string;

package/dist/src/wire.js

@@ -0,0 +1,194 @@
+/**
+ * A wire capture, read back.
+ *
+ * `--wire <file>` on either end writes one line per frame, `{ at, from, peer,
+ * frame }`, and this is the other half: the lines as rows a screen can list,
+ * and a reader that keeps up with a file still being written. Nothing here
+ * renders, and nothing here needs a host - a capture is a file, and the two
+ * ends of a conversation can be read from the same shell.
+ */
+import { closeSync, openSync, readSync, statSync, watch } from 'node:fs';
+const bag = (value) => (typeof value === 'object' && value !== null ? value : {});
+const str = (value) => (typeof value === 'string' ? value : undefined);
+/** One line parsed, or undefined for one that is not a capture line. */
+export function parseWireLine(text) {
+    let held;
+    try {
+        held = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    const line = bag(held);
+    if (typeof line.at !== 'string' || (line.from !== 'client' && line.from !== 'host') || !('frame' in line))
+        return undefined;
+    return { at: line.at, from: line.from, ...(typeof line.peer === 'string' ? { peer: line.peer } : {}), frame: line.frame };
+}
+/**
+ * The frames described, in order.
+ *
+ * A response says nothing about what it answers, so the requests are held by
+ * id and direction until their answer goes by - which is what puts a method
+ * on a response row, and is why this is a reader with state rather than a
+ * function of one line.
+ */
+export function describer() {
+    /** Requests waiting for an answer, by the direction they went and their id. */
+    const pending = new Map();
+    return (line, seq) => {
+        const frame = bag(line.frame);
+        const peer = line.peer ?? '';
+        if (typeof line.frame !== 'object' || line.frame === null) {
+            return { seq, at: line.at, from: line.from, peer, kind: 'text', method: '', detail: String(line.frame), frame: line.frame };
+        }
+        const id = frame.id === undefined || frame.id === null ? undefined : String(frame.id);
+        const params = bag(frame.params);
+        const channel = str(params.channel);
+        const action = bag(params.action);
+        const type = str(action.type);
+        if (typeof frame.method === 'string') {
+            const method = frame.method;
+            if (id !== undefined)
+                pending.set(`${line.from}:${id}`, method);
+            return {
+                seq, at: line.at, from: line.from, peer,
+                kind: id === undefined ? 'notification' : 'request',
+                method, ...(id === undefined ? {} : { id }), ...(channel === undefined ? {} : { channel }), ...(type === undefined ? {} : { type }),
+                detail: detailOf(method, params, action),
+                frame: line.frame,
+            };
+        }
+        // An answer travels the other way from the question it answers.
+        const asked = line.from === 'client' ? 'host' : 'client';
+        const method = id === undefined ? '' : pending.get(`${asked}:${id}`) ?? '';
+        if (id !== undefined)
+            pending.delete(`${asked}:${id}`);
+        if ('error' in frame) {
+            const error = bag(frame.error);
+            return { seq, at: line.at, from: line.from, peer, kind: 'error', method, ...(id === undefined ? {} : { id }), detail: `${str(error.code) ?? String(error.code ?? '')} ${str(error.message) ?? ''}`.trim(), frame: line.frame };
+        }
+        return { seq, at: line.at, from: line.from, peer, kind: 'response', method, ...(id === undefined ? {} : { id }), detail: summaryOf(frame.result), frame: line.frame };
+    };
+}
+/** What a request or a notification is about, in a few words. */
+const detailOf = (method, params, action) => {
+    // The action type is the row's own field; what is left is what the action
+    // carried, where it carried words.
+    if (method === 'dispatchAction' || method === 'action') {
+        const text = str(bag(action.message).text) ?? str(action.text) ?? str(action.title);
+        return text === undefined ? '' : text.replace(/\s+/g, ' ').slice(0, 80);
+    }
+    if (method === 'initialize')
+        return str(params.clientId) ?? '';
+    if (method === 'createSession')
+        return `${str(params.provider) ?? ''} ${str(params.channel) ?? ''}`.trim();
+    // The channel is the row's own field too; what else the request names.
+    return str(params.uri) ?? str(params.session) ?? str(params.resource) ?? str(params.provider) ?? '';
+};
+/** What a result is, in a few words: its keys, or the value when it is one. */
+const summaryOf = (result) => {
+    if (result === undefined || result === null)
+        return '';
+    if (typeof result !== 'object')
+        return String(result);
+    if (Array.isArray(result))
+        return `${result.length} item${result.length === 1 ? '' : 's'}`;
+    const keys = Object.keys(result);
+    return keys.length === 0 ? '{}' : keys.slice(0, 6).join(', ') + (keys.length > 6 ? ', …' : '');
+};
+/** Whether a row is one the filter keeps. A substring of anything a row shows, the way the catalogue filters. */
+export const matches = (row, query) => {
+    const wanted = query.trim().toLowerCase();
+    if (wanted === '')
+        return true;
+    return [row.method, row.channel ?? '', row.type ?? '', row.kind, row.from, row.id ?? '', row.detail, row.peer]
+        .some((field) => field.toLowerCase().includes(wanted));
+};
+/**
+ * The file, as it grows.
+ *
+ * Read from the top, then from wherever the last read stopped whenever the
+ * file changes - `fs.watch` where the platform has it, and a poll beside it
+ * because a watcher on a file being appended to by another process is not
+ * something every platform delivers. A line still being written is kept
+ * until its newline arrives, so a frame is never handed over in halves. A
+ * file cut back to nothing, which is what a new `--wire` run does, starts
+ * over rather than reading past its end.
+ */
+export function follow(path, onRows, options = {}) {
+    const describe = describer();
+    let offset = 0;
+    let seq = 0;
+    let partial = '';
+    let closed = false;
+    const read = () => {
+        if (closed)
+            return;
+        let size;
+        try {
+            size = statSync(path).size;
+        }
+        catch {
+            return;
+        }
+        if (size < offset) {
+            offset = 0;
+            partial = '';
+        }
+        if (size === offset)
+            return;
+        const fd = openSync(path, 'r');
+        let chunk;
+        try {
+            chunk = Buffer.alloc(size - offset);
+            readSync(fd, chunk, 0, chunk.length, offset);
+        }
+        finally {
+            closeSync(fd);
+        }
+        offset = size;
+        const text = partial + chunk.toString('utf8');
+        const lines = text.split('\n');
+        partial = lines.pop() ?? '';
+        const rows = [];
+        for (const line of lines) {
+            if (line.trim() === '')
+                continue;
+            const parsed = parseWireLine(line);
+            seq += 1;
+            if (parsed === undefined) {
+                rows.push({ seq, at: '', from: 'client', peer: '', kind: 'text', method: '', detail: line.slice(0, 120), frame: line });
+                continue;
+            }
+            rows.push(describe(parsed, seq));
+        }
+        if (rows.length > 0)
+            onRows(rows);
+    };
+    read();
+    const timer = setInterval(read, options.interval ?? 250);
+    timer.unref?.();
+    let watcher;
+    try {
+        watcher = watch(path, () => { read(); });
+        watcher.unref?.();
+        watcher.on('error', () => { watcher = undefined; });
+    }
+    catch {
+        watcher = undefined;
+    }
+    return {
+        close: () => {
+            closed = true;
+            clearInterval(timer);
+            watcher?.close();
+        },
+    };
+}
+/** A row as one line of text, for a shell that is not a terminal. */
+export const rowText = (row) => {
+    const time = row.at.length >= 23 ? row.at.slice(11, 23) : row.at;
+    const arrow = row.from === 'client' ? '->' : '<-';
+    const what = row.kind === 'response' ? `${row.method} ok` : row.kind === 'error' ? `${row.method} error` : row.method;
+    return [time, arrow, what || row.kind, row.type ?? '', row.channel ?? '', row.detail].filter((one) => one !== '').join('  ');
+};

package/dist/src/wiretui.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `ahpc wire <file>`: a capture, watched.
+ *
+ * A screen with no host behind it. On a terminal it is the wire screen,
+ * reading the file as it grows; anywhere else it is one line per frame to
+ * stdout, which is what a shell wants from it. Loaded only when asked for,
+ * for the same reason the conversation screen is: it pulls in a renderer,
+ * and `ahpc session list` should not pay for one.
+ */
+export interface WireTuiOptions {
+    file: string;
+    theme?: string;
+    shell?: string;
+    /** Keep printing as the file grows, off a terminal. */
+    follow?: boolean;
+    /** One JSON object per row rather than a line for reading. */
+    json?: boolean;
+    /** Only the rows this matches, off a terminal; on one the filter box is the same thing. */
+    filter?: string;
+}
+/** The screen, or the lines. */
+export declare function wireTui(options: WireTuiOptions): Promise<void>;