@softov/ahpc 0.1.0

package/dist/src/ahp/types.js

@@ -0,0 +1,27 @@
+/**
+ * The protocol, as a client reads it.
+ *
+ * These are AHP's own names for AHP's own shapes - `SessionSummary.status` is
+ * the bitset the host sends, `responseParts` is one ordered stream, a pending
+ * input is either a tool confirmation or a question. Renaming them here would
+ * only mean translating twice, and the whole point of the example is to find
+ * out which components the *protocol's* shapes need.
+ *
+ * It is a subset: what a chat client has to render. The authority is the
+ * `@agent-host-protocol` package's own `src/types/`.
+ */
+/**
+ * Status is activity and client flags in one number.
+ *
+ * `InputNeeded` carries `InProgress`, so it has to be tested first - a turn
+ * waiting on a confirmation otherwise reads as merely running, and nobody
+ * goes to answer it.
+ */
+export const SessionFlag = {
+    Idle: 1,
+    Error: 2,
+    InProgress: 8,
+    InputNeeded: 24,
+    IsRead: 32,
+    IsArchived: 64,
+};

package/dist/src/app.d.ts

@@ -0,0 +1,54 @@
+import type { Disposable, TextUIApp } from '@textui/core';
+import type { HostConnection } from './ahp/connection.js';
+export interface ChatOptions {
+    builtins?: boolean;
+    /**
+     * Keys from the config file, over the ones this client ships with.
+     *
+     * A chord to a command id, or to `null` to take the chord away. Read once
+     * at startup: a binding is registered when the controller is, and this
+     * client has no reload.
+     */
+    keys?: Record<string, string | null>;
+    /**
+     * The header trades its own name for a seven-cell creature, on a session.
+     *
+     * Off unless asked for, and it is the config file that asks - `boodInline`
+     * in `~/.config/ahpc/config.json`.
+     */
+    boodInline?: boolean;
+    /**
+     * The creature roams the whole application, on the floating layer.
+     *
+     * Off unless asked for - `boodFloat` in the config file. A terminal has no
+     * per-cell transparency, so a figure that goes everywhere writes over what
+     * it stands on: it keeps off the composer and off anything opened on a
+     * layer, and a screen whose content runs to the bottom gets a cat on it.
+     */
+    boodFloat?: boolean;
+    /** The host. Omit for the scripted one, which is what the tests use. */
+    host?: HostConnection & {
+        pump?(): boolean;
+    };
+    /**
+     * Where a new session works, before anybody chooses otherwise.
+     *
+     * A path on the **host**, which is not this machine unless the host happens
+     * to be. Pass an empty string to say there is none and let the host decide;
+     * left out entirely it is the directory this process started in, which is
+     * the defensible guess only for a host that is this process.
+     */
+    workspace?: string;
+    /**
+     * How wide the terminal has to be before the catalogue shows both panes.
+     *
+     * Narrower than this and the detail pane starts hidden - left opens it,
+     * right puts it away - because a split that leaves both halves truncated is
+     * worse than either half whole. Settable here so it can be tuned without a
+     * rebuild; `140` is where a session list stops cutting its titles with a
+     * detail pane beside it.
+     */
+    splitAt?: number;
+}
+export declare function registerChat(app: TextUIApp, options?: ChatOptions): Disposable;
+export { CONTROLLER } from './control.js';

package/dist/src/app.js

@@ -0,0 +1,369 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "@textui/core/jsx-runtime";
+import { createBag, defineComponent, useApp, useTheme, useStoreSubtree, useStoreValue, } from '@textui/core';
+import { KeyHints, Row, registerBuiltins } from '@textui/widgets';
+import { CONTROLLER, createController } from './control.js';
+import { fakeHost } from './ahp/fake.js';
+import { BOOD, BOOD_FLOAT, BOOD_FLOOR, BOOD_INLINE, FOCUS, HOST, HOST_ERROR, INPUT, INPUT_STATUS, OPEN, RUNNING, SCREEN, SESSIONS, SPLIT_AT, SPLIT_DEFAULT, STATUS, WORKSPACE, boodFloor, openSession, workspaceName, } from './state.js';
+import { decodeStatus } from './ahp/status.js';
+import { AutomationsScreen, ChangesScreen, ChatScreen, FilesScreen, HostsScreen, McpScreen, NewAutomationScreen, NewSessionScreen, SessionsScreen, TerminalScreen, SettingsScreen, SkillsScreen, } from './screens.js';
+import { ChatBubble, ReasoningBlock, StreamingText } from './view/bubble.js';
+import { ChatComposer } from './view/composer.js';
+import { ChatHitl } from './view/hitl.js';
+import { ChatTranscript } from './view/transcript.js';
+import { BoodSprite, Creature, moodOf, pickBood } from './view/creature.js';
+import { ChangesList } from './view/changes.js';
+import { FileList } from './view/files.js';
+import { AutomationList } from './view/automations.js';
+import { ConnectionBadge, SessionList } from './view/sessions.js';
+import { ToolCallRow } from './view/toolcall.js';
+/**
+ * A chat client for an agent host.
+ *
+ * What it is here to find out is which components a chat application needs
+ * that a terminal UI catalog does not already have. The answer, by the end of
+ * writing it, is in `README.md` - and the shape of the answer is that the
+ * conversation is one component the catalog cannot stand in for, the composer
+ * is a second, and everything else is composition.
+ *
+ * The application takes a host rather than making one, so a test can mount it
+ * against a scripted one and drive time by hand.
+ */
+/**
+ * The creature, over the whole application.
+ *
+ * Mounted on the `floating` layer rather than inside a screen, so navigating
+ * moves the screen out from under it instead of unmounting it: escape from a
+ * session leaves the figure exactly where it was standing. This is the only
+ * place that knows both the store and the bood, which is what keeps
+ * `view/bood/` from having an opinion about sessions.
+ *
+ * The floor is the top of whatever the screen keeps at the bottom. A screen
+ * with a composer keeps a lot more of it than one with only a status bar, so
+ * the inset follows the screen rather than being one number that is wrong on
+ * half of them.
+ */
+/**
+ * What the bottom keeps when nothing down there has said otherwise.
+ *
+ * The hints row, the shell's own edge, and the closing border of whatever
+ * panel is there. Standing on that border put the figure through it and
+ * through the row above it; a row clear of it is the ground.
+ */
+const BOTTOM_CHROME = 3;
+const BoodOverlay = defineComponent('BoodOverlay', () => {
+    const app = useApp();
+    const name = useStoreValue(BOOD);
+    const roaming = useStoreValue(BOOD_FLOAT, false) ?? false;
+    useStoreSubtree(BOOD_FLOOR);
+    // Whatever is standing at the bottom says where it starts; the creature gets
+    // the row above the highest of them. Nothing down there and it takes the
+    // bottom of the terminal, less the chrome that is on every screen.
+    const standing = boodFloor(app.store);
+    const status = useStoreValue(STATUS, 1) ?? 1;
+    useStoreSubtree(SESSIONS);
+    const session = openSession(app.store);
+    if (!roaming || !name)
+        return null;
+    /*
+     * Out of the way of anything that was opened on purpose.
+     *
+     * A terminal has no per-cell transparency, so the figure writes over
+     * whatever it is standing on - which is a fair price for a mascot wandering
+     * across a list, and not a fair price for a menu. The completion popup is a
+     * layer, the palette is a layer, a dialog is a layer: if anything else is
+     * open, the creature is not on top of it.
+     */
+    if (app.layers.entries().some((entry) => entry.id !== 'bood'))
+        return null;
+    return (_jsx(BoodSprite, { name: name, mood: session ? moodOf(decodeStatus(status).activity) : 'happy', floor: standing !== undefined ? standing - 1 : undefined, inset: BOTTOM_CHROME }));
+});
+const Header = defineComponent('ChatHeader', () => {
+    const app = useApp();
+    const theme = useTheme();
+    const host = useStoreValue(HOST);
+    const status = useStoreValue(STATUS, 1) ?? 1;
+    // Subscribed, not asked. `screens.current()` is a method call in the middle
+    // of a render: it reads the right answer once and nothing tells this to look
+    // again, so a surface that navigating does not remount keeps the last
+    // screen's chrome for ever.
+    // Subscribed so the title follows what is open, without the header being
+    // remounted to notice.
+    useStoreValue(SCREEN, null);
+    useStoreValue(OPEN, null);
+    // And to the summaries themselves. `openSession` is a plain read, so a
+    // title or a status arriving from the host changed the store and left this
+    // row showing what it said when the session was opened - which is why the
+    // header only caught up when navigating away and back remounted it.
+    useStoreSubtree(SESSIONS);
+    const session = openSession(app.store);
+    const decoded = decodeStatus(status);
+    const bood = useStoreValue(BOOD);
+    const boodInline = useStoreValue(BOOD_INLINE, false) ?? false;
+    // Only on a session, because the seven cells are carrying that session's
+    // state - on the catalogue there is no one thing for them to be about, and
+    // a creature that means nothing where the name used to be is a worse trade.
+    // Truthiness, not a comparison with undefined: nothing open is `null` here,
+    // and the row beside this one has always tested it the same way.
+    const wearsBood = boodInline && Boolean(session);
+    return (
+    // Only the title gives way. Everything else on this row is fixed-width and
+    // says what the application *is* - a header that truncates its own name to
+    // "Assist…" in order to fit more of a session title has given up the one
+    // part that is the same on every screen. The workspace yields after the
+    // title, and the status glyph never does: it is one cell and it is the
+    // thing the row is scanned for.
+    _jsxs(Row, { gap: 1, children: [wearsBood
+                ? _jsx(Creature, { name: bood, form: "inline", mood: moodOf(decoded.activity), shrink: 0 })
+                : _jsx("text", { content: "Assistant", bold: true, fg: "accent", shrink: 0 }), _jsx("text", { content: theme.glyphs.separator, fg: "subtle", shrink: 0 }), session ? (_jsxs(_Fragment, { children: [_jsx("text", { content: theme.glyphs[decoded.glyph], fg: decoded.tone, shrink: 0 }), _jsx("text", { content: session.title, flex: 1, truncate: "end" }), _jsx("text", { content: workspaceName(session.workingDirectories[0]), fg: "muted", shrink: 4, truncate: "end" })] })) : (_jsx("text", { content: host?.url ?? 'no host', fg: "muted", flex: 1, truncate: "end" }))] }));
+});
+/**
+ * The keys, as the reader sees them.
+ *
+ * They change with where the focus is, because they *are* different there:
+ * while the composer has the keyboard, every letter is a letter.
+ */
+const Hints = defineComponent('ChatHints', (props) => {
+    const theme = useTheme();
+    /**
+     * Which key the footer names for a newline.
+     *
+     * `alt+enter`, which is `ESC CR` and the one encoding every terminal can
+     * express. The field also takes `ctrl+enter`, and that is deliberately not
+     * named here: it has three encodings - a bare LF, xterm's `CSI 27;5;13~`,
+     * kitty's `CSI 13;5u` - and a terminal that sends plain CR for it is
+     * sending the enter key, which nothing downstream can tell apart. VS Code's
+     * terminal is one such, so naming it offers a key that does not exist.
+     *
+     * One key in the row rather than two: the row elides every hint on a narrow
+     * terminal, and a hint nobody can read costs the same as a wrong one.
+     */
+    const newline = 'alt+enter';
+    const waiting = useStoreValue(INPUT, null);
+    const upDown = `${theme.glyphs.arrowUp}${theme.glyphs.arrowDown}`;
+    const leftRight = `${theme.glyphs.arrowLeft}${theme.glyphs.arrowRight}`;
+    // Which keys exist is a property of where you are, not of what is open: a
+    // session stays open while its changes are on screen, and `i write` there
+    // is an offer nothing honours.
+    const screen = useStoreValue(SCREEN, 'sessions') ?? 'sessions';
+    // Not `status > 1`: the bitset carries "a client has read this" in the same
+    // number, so an idle session somebody looked at is 33 and every hint would
+    // read "stop".
+    const running = useStoreValue(RUNNING, false) ?? false;
+    // Where the keyboard is decides what the keys mean. While the composer has
+    // it, escape leaves the field; from the transcript, escape leaves the
+    // screen - and a hint row that said one of those in both places is wrong
+    // half the time.
+    const focused = useStoreValue(FOCUS, null);
+    const composing = focused === 'chat.composer';
+    // A question is not a confirmation, and the keys are not the same either.
+    // Offering "a approve" over an elicitation is the same mistake as rendering
+    // one as the other, made in the one row that is supposed to explain it.
+    if (screen === 'chat' && waiting?.kind === 'toolConfirmation') {
+        return (_jsx(KeyHints, { ...props, hints: [
+                { keys: 'a', label: 'approve' },
+                { keys: 'd', label: 'deny' },
+                { keys: '1-9', label: 'option' },
+                { keys: 'esc', label: 'read' },
+            ] }));
+    }
+    if (screen === 'chat' && waiting) {
+        return (_jsx(KeyHints, { ...props, hints: [
+                { keys: 'tab', label: 'next question' },
+                { keys: 'space', label: 'choose' },
+                { keys: 'enter', label: 'send answers' },
+                { keys: 'esc', label: 'read' },
+            ] }));
+    }
+    if (screen === 'chat') {
+        return (_jsx(KeyHints, { ...props, hints: composing
+                ? [
+                    { keys: 'enter', label: 'send' },
+                    { keys: newline, label: 'newline' },
+                    { keys: 'esc', label: 'read' },
+                    { keys: 'ctrl+c', label: running ? 'stop' : 'quit' },
+                ]
+                : [
+                    { keys: upDown, label: 'move' },
+                    { keys: 'enter', label: 'expand' },
+                    { keys: 'i', label: 'write' },
+                    { keys: 'G', label: 'follow' },
+                    { keys: 'c', label: 'changes' },
+                    { keys: 'k', label: 'skills' },
+                    { keys: 'esc', label: 'back' },
+                    // The same key, and it says which: while a turn is running it
+                    // stops it, and when none is it leaves. A hint that always read
+                    // "stop" is wrong most of the time.
+                    { keys: 'ctrl+c', label: running ? 'stop' : 'quit' },
+                ] }));
+    }
+    if (screen === 'new') {
+        return (_jsx(KeyHints, { ...props, hints: [
+                { keys: 'enter', label: 'start' },
+                { keys: newline, label: 'newline' },
+                { keys: 'tab', label: 'options' },
+                { keys: 'esc', label: 'sessions' },
+                { keys: 'ctrl+c', label: 'quit' },
+            ] }));
+    }
+    // On the terminal, `ctrl+c` is the shell's - it is how a command is
+    // stopped, and saying "quit" there is how somebody closes the application
+    // trying to interrupt a `ping`.
+    if (screen === 'terminal') {
+        return (_jsx(KeyHints, { ...props, hints: [
+                { keys: 'enter', label: 'run' },
+                { keys: 'ctrl+c', label: 'interrupt' },
+                { keys: 'esc', label: 'back' },
+                { keys: 'ctrl+p', label: 'commands' },
+            ] }));
+    }
+    // The list screens. `tab move` is a form's answer and these are
+    // lists: what moves is the cursor, and enter is what a row is for.
+    if (screen === 'changes' || screen === 'skills' || screen === 'mcp' || screen === 'files'
+        || screen === 'automations') {
+        return (_jsx(KeyHints, { ...props, hints: [
+                { keys: upDown, label: 'move' },
+                { keys: 'enter', label: screen === 'changes' || screen === 'files' ? 'open' : screen === 'automations' ? 'run' : 'on / off' },
+                // Only where they do something. A hint for a key that is inert on
+                // this screen is worse than no hint.
+                ...(screen === 'changes'
+                    ? [{ keys: ']', label: 'changeset' }, { keys: 'r', label: 'read' }, { keys: 'x', label: 'do' }]
+                    : []),
+                // Named only where they do something. `enter` already runs one, so
+                // what is left is the switch and the one that does not come back.
+                ...(screen === 'automations'
+                    ? [{ keys: 'n', label: 'new' }, { keys: 'e', label: 'on / off' }, { keys: 'd', label: 'forget' }]
+                    : []),
+                { keys: 'esc', label: 'back' },
+                { keys: 'ctrl+p', label: 'commands' },
+                { keys: 'ctrl+c', label: 'quit' },
+            ] }));
+    }
+    if (screen !== 'sessions') {
+        return (_jsx(KeyHints, { ...props, hints: [
+                { keys: 'tab', label: 'move' },
+                { keys: 'esc', label: 'back' },
+                { keys: 'ctrl+p', label: 'commands' },
+                { keys: 'ctrl+c', label: 'quit' },
+            ] }));
+    }
+    return (_jsx(KeyHints, { ...props, hints: [
+            { keys: upDown, label: 'move' },
+            // Which one it is depends on where the detail pane is, and the pane is
+            // right there on the screen saying so. Naming both is what fits.
+            { keys: leftRight, label: 'detail' },
+            { keys: 'enter', label: 'open' },
+            { keys: 'n', label: 'new' },
+            // `a` archives and `delete` disposes, and neither is here: the row is
+            // one line and naming `ctrl+f` cost it the room. Both are a letter
+            // away in the palette, and the filter is the one nothing else offers.
+            { keys: 'ctrl+f', label: 'filter' },
+            { keys: 'ctrl+p', label: 'commands' },
+            { keys: 'ctrl+c', label: 'quit' },
+        ] }));
+});
+const Status = defineComponent('ChatStatus', () => {
+    const screen = useStoreValue(SCREEN, 'sessions');
+    // What the host last refused, where a person is already looking. A refusal
+    // that only reaches a log is a client that appears to have ignored the key
+    // you pressed.
+    //
+    // Unless the row above the composer is already saying it, which it does
+    // when the refusal was of an answer given to the block waiting there. Said
+    // twice on a narrow terminal it is one sentence in red on two of twenty
+    // rows, and the second one adds nothing to the first.
+    const said = useStoreValue(INPUT_STATUS, null) ?? null;
+    const refusal = useStoreValue(HOST_ERROR, null) ?? null;
+    const error = said?.state === 'failed' && said.text === refusal ? null : refusal;
+    return (_jsxs(Row, { gap: 2, children: [error
+                ? _jsx("text", { content: error, fg: "danger", flex: 1, truncate: "end" })
+                : _jsx(Hints, { flex: 1 }), _jsx("text", { content: screen ?? '-', fg: "muted" })] }));
+});
+export function registerChat(app, options = {}) {
+    const bag = createBag();
+    if (options.builtins !== false)
+        bag.add(registerBuiltins(app));
+    const host = options.host ?? fakeHost();
+    const controller = createController(app, host, options.keys);
+    app.store.set(WORKSPACE, options.workspace ?? process.cwd());
+    app.store.set(SPLIT_AT, options.splitAt ?? SPLIT_DEFAULT);
+    // Once, here, rather than per mount: two surfaces drawing two different
+    // animals would read as two mascots rather than one that gets about.
+    app.store.set(BOOD, pickBood());
+    app.store.set(BOOD_INLINE, options.boodInline ?? false);
+    app.store.set(BOOD_FLOAT, options.boodFloat ?? false);
+    bag.add(controller);
+    bag.add(app.services.provide(CONTROLLER, controller));
+    for (const [component, render] of [
+        ['ChatBubble', ChatBubble],
+        ['StreamingText', StreamingText],
+        ['ReasoningBlock', ReasoningBlock],
+        ['ToolCallRow', ToolCallRow],
+        ['ChatTranscript', ChatTranscript],
+        ['ChatComposer', ChatComposer],
+        ['ChatHitl', ChatHitl],
+        ['SessionList', SessionList],
+        ['ConnectionBadge', ConnectionBadge],
+        ['ChangesList', ChangesList],
+        ['FileList', FileList],
+        ['AutomationList', AutomationList],
+        ['SessionsScreen', SessionsScreen],
+        ['ChatScreen', ChatScreen],
+        ['NewSessionScreen', NewSessionScreen],
+        ['TerminalScreen', TerminalScreen],
+        ['ChangesScreen', ChangesScreen],
+        ['FilesScreen', FilesScreen],
+        ['AutomationsScreen', AutomationsScreen],
+        ['NewAutomationScreen', NewAutomationScreen],
+        ['SettingsScreen', SettingsScreen],
+        ['HostsScreen', HostsScreen],
+        ['SkillsScreen', SkillsScreen],
+        ['McpScreen', McpScreen],
+        ['BoodOverlay', BoodOverlay],
+        ['ChatHeader', Header],
+        ['ChatStatus', Status],
+        ['ChatHints', Hints],
+    ]) {
+        bag.add(app.components.register({
+            component,
+            category: 'template',
+            renderer: { kind: 'function', render: render },
+        }));
+    }
+    // Over every screen, for as long as the application is running.
+    bag.add(app.layers.open({
+        id: 'bood',
+        layer: 'floating',
+        node: { component: 'BoodOverlay' },
+        position: { kind: 'screen', rect: { x: 0, y: 0 } },
+    }));
+    bag.add(app.surfaces.open({ surface: 'header', key: 'title', target: { component: 'ChatHeader' } }));
+    bag.add(app.surfaces.open({ surface: 'status', key: 'status', target: { component: 'ChatStatus' } }));
+    for (const screen of [
+        { id: 'sessions', component: 'SessionsScreen' },
+        // Kept alive: coming back from the changes list to a conversation that
+        // had scrolled itself back to the top is losing your place in a document
+        // that is still being written.
+        { id: 'chat', component: 'ChatScreen', keepAlive: true },
+        { id: 'new', component: 'NewSessionScreen' },
+        { id: 'changes', component: 'ChangesScreen' },
+        { id: 'files', component: 'FilesScreen' },
+        { id: 'automations', component: 'AutomationsScreen' },
+        { id: 'automation.new', component: 'NewAutomationScreen' },
+        { id: 'settings', component: 'SettingsScreen' },
+        { id: 'hosts', component: 'HostsScreen' },
+        { id: 'skills', component: 'SkillsScreen' },
+        { id: 'mcp', component: 'McpScreen' },
+        // Kept alive: a shell you scrolled back through and then left is a shell
+        // that should still be where you left it.
+        { id: 'terminal', component: 'TerminalScreen', keepAlive: true },
+    ]) {
+        bag.add(app.screens.register(screen));
+    }
+    void controller.refresh();
+    // The composer, with nothing open. A client whose first screen is a
+    // catalogue makes "talk to an agent" a two-step errand; the first message is
+    // what creates the session, so the field is what the application opens on.
+    app.screens.reset('new');
+    return bag;
+}
+export { CONTROLLER } from './control.js';

package/dist/src/blocks.d.ts

@@ -0,0 +1,88 @@
+import type { QueuedMessage, ToolCall, Turn } from './ahp/types.js';
+/**
+ * A conversation, flattened into the rows a viewport scrolls.
+ *
+ * A turn is not a box. It is a run of rows - a header, some prose, a tool
+ * call, more prose - and the transcript has to be able to put its cursor on
+ * one of them, measure it, and scroll to it. Nesting each turn inside a
+ * container would mean the transcript could only ever scroll to a whole turn,
+ * and a turn can be four hundred rows long.
+ *
+ * The order is the host's order. `responseParts` interleaves prose and calls
+ * in one stream, and "let me search for those" means something before the
+ * searches and nothing after them.
+ */
+export type Block = {
+    kind: 'said';
+    id: string;
+    turnId: string;
+    text: string;
+} | {
+    kind: 'header';
+    id: string;
+    turnId: string;
+    model?: string;
+    /**
+     * What the turn was asked for besides the model, in the host's words.
+     *
+     * The values rather than the keys: `thinkingLevel` is one host's name for
+     * a property whose *answers* are what a person reads, and a header that
+     * spelled out the key would be twice as long and no clearer.
+     */
+    settings?: string;
+    meta: string;
+    state: Turn['state'];
+} | {
+    kind: 'prose';
+    id: string;
+    turnId: string;
+    content: string;
+    streaming: boolean;
+} | {
+    kind: 'reasoning';
+    id: string;
+    turnId: string;
+    content: string;
+    streaming: boolean;
+} | {
+    kind: 'notice';
+    id: string;
+    turnId: string;
+    content: string;
+} | {
+    kind: 'failure';
+    id: string;
+    turnId: string;
+    content: string;
+    resumable: boolean;
+} | {
+    kind: 'tool';
+    id: string;
+    turnId: string;
+    call: ToolCall;
+} | {
+    kind: 'queued';
+    id: string;
+    messageId: string;
+    text: string;
+};
+/**
+ * Everything in a block that a person could be looking for.
+ *
+ * A tool call is its name, its command and what came back, because all three
+ * are things somebody searches a transcript for - the file a command touched
+ * is in the output and nowhere else. A header is the model and the settings,
+ * which is how "where did I switch to opus" is answered.
+ */
+export declare function blockText(block: Block): string;
+/**
+ * Where in the conversation a query appears, as block indices in order.
+ *
+ * Case-insensitive, and a blank query matches nothing rather than everything:
+ * a find with no term is a find that has not been typed yet, and lighting up
+ * every block for it is the opposite of what the box is for.
+ */
+export declare function findBlocks(blocks: Block[], query: string): number[];
+/** Blocks the cursor stops on: the ones that do something when activated. */
+export declare function selectable(block: Block): boolean;
+export declare function toBlocks(turns: Turn[], queued?: QueuedMessage[]): Block[];

package/dist/src/blocks.js

@@ -0,0 +1,102 @@
+/**
+ * Everything in a block that a person could be looking for.
+ *
+ * A tool call is its name, its command and what came back, because all three
+ * are things somebody searches a transcript for - the file a command touched
+ * is in the output and nowhere else. A header is the model and the settings,
+ * which is how "where did I switch to opus" is answered.
+ */
+export function blockText(block) {
+    switch (block.kind) {
+        case 'said':
+        case 'queued':
+            return block.text;
+        case 'prose':
+        case 'reasoning':
+        case 'notice':
+        case 'failure':
+            return block.content;
+        case 'header':
+            return [block.model, block.settings, block.meta].filter(Boolean).join(' ');
+        case 'tool':
+            return [
+                block.call.name, block.call.toolName, block.call.input,
+                block.call.intention, block.call.outcome, block.call.output,
+                ...(block.call.files ?? []),
+            ].filter(Boolean).join(' ');
+    }
+}
+/**
+ * Where in the conversation a query appears, as block indices in order.
+ *
+ * Case-insensitive, and a blank query matches nothing rather than everything:
+ * a find with no term is a find that has not been typed yet, and lighting up
+ * every block for it is the opposite of what the box is for.
+ */
+export function findBlocks(blocks, query) {
+    const needle = query.trim().toLowerCase();
+    if (needle === '')
+        return [];
+    const found = [];
+    blocks.forEach((block, index) => {
+        if (blockText(block).toLowerCase().includes(needle))
+            found.push(index);
+    });
+    return found;
+}
+/** Blocks the cursor stops on: the ones that do something when activated. */
+export function selectable(block) {
+    // A queued message among them, because taking one back is something you do
+    // to it - and the cursor is how anything in the transcript is reached.
+    return block.kind === 'tool' || block.kind === 'reasoning' || block.kind === 'queued';
+}
+export function toBlocks(turns, queued = []) {
+    const blocks = [];
+    for (const turn of turns) {
+        if (turn.role === 'user') {
+            blocks.push({ kind: 'said', id: `${turn.id}:said`, turnId: turn.id, text: turn.message ?? '' });
+            continue;
+        }
+        const running = turn.state === 'running';
+        blocks.push({
+            kind: 'header',
+            id: `${turn.id}:head`,
+            turnId: turn.id,
+            ...(turn.model ? { model: turn.model.id } : {}),
+            ...(turn.model?.config ? { settings: Object.values(turn.model.config).join(' · ') } : {}),
+            meta: running ? 'running' : turn.elapsedMs ? `${(turn.elapsedMs / 1000).toFixed(1)}s` : '',
+            state: turn.state,
+        });
+        turn.parts.forEach((part, index) => {
+            const last = index === turn.parts.length - 1;
+            switch (part.kind) {
+                case 'markdown':
+                    blocks.push({ kind: 'prose', id: part.id, turnId: turn.id, content: part.content, streaming: running && last });
+                    break;
+                case 'reasoning':
+                    blocks.push({ kind: 'reasoning', id: part.id, turnId: turn.id, content: part.content, streaming: running && last });
+                    break;
+                case 'systemNotification':
+                    blocks.push({ kind: 'notice', id: part.id, turnId: turn.id, content: part.content });
+                    break;
+                case 'toolCall':
+                    blocks.push({ kind: 'tool', id: part.id, turnId: turn.id, call: part.call });
+                    break;
+                case 'error':
+                    blocks.push({ kind: 'failure', id: part.id, turnId: turn.id, content: part.message, resumable: part.resumable });
+                    break;
+                default:
+                    break;
+            }
+        });
+    }
+    // What the person typed while the agent was busy. Below the conversation
+    // because that is when it will be said, and visibly not sent yet.
+    // Keyed by the host's own id, not by position: the queue is the host's, the
+    // head leaves it whenever the running turn ends, and an index would name a
+    // different message every time one did.
+    for (const message of queued) {
+        blocks.push({ kind: 'queued', id: `queued:${message.id}`, messageId: message.id, text: message.text });
+    }
+    return blocks;
+}

package/dist/src/cli/main.d.ts

@@ -0,0 +1,13 @@
+/** Every command, and the argv reading that picks one. */
+export declare const HELP = "ahpc - drive an agent host from a shell\n\n  ahpc [--host ws://\u2026] <command> [args]        the screen is 'ahpc' with no command\n\nSessions\n  session list                 the catalogue, newest first   [--archived] [--json]\n  session show <uri>           what the host says about one  [--full] [--json]\n  session new                  start one   [--agent P] [--cwd DIR] [--set k=v]\u2026 [--json]\n  session rm <uri>             dispose it\n  session history <uri>        its turns               [--all] [--full] [--json]\n  session config <uri>         the schema and what is in force        [--json]\n  session set <uri> <k> <v>    change one config key\n  session read <uri>           mark read                     [--unread]\n  session archive <uri>        put it away                   [--undo]\n  session customizations <uri> skills, prompts, agents, servers        [--json]\n  session export <uri>         the whole session as one document\n                               [--json] [--markdown]\n  session toggle <uri> <id>    turn one on                   [--off]\n\nTurns\n  prompt <uri> <text>          say it and stream the answer  [--model M] [--json]\n  exec <text>                  a session, one turn, and dispose it\n                                       [--agent P] [--cwd DIR] [--model M] [--json]\n  cancel <uri>                 stop the running turn\n  queue <uri> <text>           say it after the one running  [--model M]\n  unqueue <uri> <id>           take it back\n\nAnswering\n  watch <uri>                  BLOCK until something wants a person, print, exit\n                                       [--until turn|input|idle] [--timeout S] [--json]\n  confirm <uri> <toolCallId>   approve a tool call           [--deny] [--option ID]\n  answer <uri> <requestId>     answer a question      [--field k=v]\u2026 [--reject]\n\nChats\n  chat list <uri>              the conversations in a session         [--json]\n  chat new <uri> [text]        another one beside it\n  chat rm <chatUri>            close one\n\nThe harness\n  agents                       what it serves, and each one's models  [--json]\n  models                       every model, by harness                [--json]\n  commands                     what a slash offers                    [--json]\n  customizations               skills, prompts, agents and MCP servers,\n                               before any session exists     [--kind k] [--json]\n  completions <uri> <text>     what the host would complete  [--offset N] [--json]\n\nChanges and files\n  changes <uri>                the files a session touched            [--json]\n                               [--list] [--scope s] [--<variable> v]\n                               [--reviewed f] [--unreviewed f]\n                               [--operations]           what may be done to it\n                               [--run id] [--file f] [--yes]      do one of them\n                               [--list] every changeset it offers\n                               [--scope <name>] one of them, e.g. turn\n                               [--turnId <id>] what a chosen scope still needs\n                               [--reviewed <file>] tick one off, repeatable\n                               [--unreviewed <file>] and clear one\n  content <uri> <file>         one of them, in full\n  resource list <uri>          a directory the host serves            [--json]\n  resource read <uri>          a file on the host\n  resource stat <uri>          what it is, without reading it         [--json]\n  resource write <uri> [file]  from a file, or from stdin      [--create-only]\n                               guarded by the file's etag unless      [--force]\n  resource rm <uri>            delete it                        [--recursive]\n  resource mkdir <uri>         make a directory\n  resource mv <uri> <to>       move it                     [--fail-if-exists]\n  resource cp <uri> <to>       copy it                     [--fail-if-exists]\n\nAutomations\n  automation list              what runs on its own                   [--json]\n  automation show <uri>        one of them                            [--json]\n  automation triggers          what this host can trigger on          [--json]\n  automation runs <uri>        its history, every page                [--json]\n  automation run <uri>         start it now\n  automation enable <uri>      switch it on\n  automation disable <uri>     switch it off\n  automation rm <uri>          forget it\n\nThe host's own log\n  logs                         what the daemon is saying  [--level L] [--follow]\n\nSigning in\n  auth                         what this host protects                [--json]\n  auth <resource>              push a token   [--token T] [--expires-in S]\n                               or set AHPC_TOKEN_<RESOURCE>, or pipe one in\n\nTerminals\n  terminal list                what is running                        [--json]\n  terminal new                 open a shell        [--cwd DIR] [--name N]\n  terminal rm <uri>            kill it\n  terminal send <uri> <text>   type into it\n  terminal watch <uri>         follow its output   [--timeout S]\n\nRecording\n  AHPC_RECORD=<file>           append every frame, both directions, for\n                               'npm run wire' to check against the protocol\n\nAnything else\n  dispatch <uri> <type>        send one action verbatim  [--field k=v]\u2026 [--chat]\n  status                       what this client is connected to       [--json]\n  help                         this\n\nThe host\n  --host <url>    ws://host:port, or AHPC_HOST, or the config file\n  --token <tkn>   a bearer token for it, or AHPC_TOKEN, or the config file\n  --config-file   read this instead of the one below\n  (none)          the scripted host, which needs nothing installed\n\nConfiguration\n  config          where the file is, and what is in force  [--json]\n\nOutput is for reading. --json is the same answer for a program.\n";
+/** A message for the person, not a stack trace. */
+export declare class Fault extends Error {
+}
+/**
+ * One command, and then the process is done.
+ *
+ * A switch rather than a registry: every branch is a few lines against
+ * `HostConnection`, and the shape of the whole surface being readable in one
+ * file is worth more than the indirection a registry would buy.
+ */
+export declare function cli(command: string, rest: string[]): Promise<number>;