@softov/ahpc 0.3.0 → 0.4.0

package/dist/src/blocks.d.ts

@@ -1,4 +1,7 @@
-import type { QueuedMessage, ToolCall, Turn } from './ahp/types.js';
+import type { Block } from '@textui/chat';
+import type { QueuedMessage, Turn } from './ahp/types.js';
+export type { Block } from '@textui/chat';
+export { selectable } from '@textui/chat';
 /**
  * A conversation, flattened into the rows a viewport scrolls.
  *
@@ -12,77 +15,4 @@ import type { QueuedMessage, ToolCall, Turn } from './ahp/types.js';
  * 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

@@ -1,55 +1,17 @@
+export { selectable } from '@textui/chat';
 /**
- * Everything in a block that a person could be looking for.
+ * A conversation, flattened into the rows a viewport scrolls.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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 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) {

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

@@ -1,5 +1,5 @@
 /** 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\nServing these sessions to something else\n  mcp                          MCP on stdin and stdout, for a client that\n                               launches this process\n  serve                        the same tools on a socket, shared\n                               [--serve-host H] [--serve-port N] [--serve-token T]\n                               [--serve-origin URL]\u2026 a browser page allowed in\n                               /mcp is MCP; /api/<tool> is plain JSON\n  both take [--mcp-tools G,\u2026]  extra tool groups to serve, on top of the\n                               sessions ones: resources, terminals,\n                               automations, changes\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  --version                    what version this is\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";
+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  --wire <file>                append every frame, both directions, as JSON\n                               lines: { at, from, peer, frame }, for\n                               'npm run wire' to check against the protocol.\n                               AHPC_RECORD=<file> is the same, from a shell\n  wire <file>                  watch a capture as it is written, from either\n                               end: one row per frame, a row opens to the\n                               frame. Off a terminal, one line per frame\n                               [--follow] [--filter text] [--json]\n\nServing these sessions to something else\n  mcp                          MCP on stdin and stdout, for a client that\n                               launches this process\n  serve                        the same tools on a socket, shared\n                               [--serve-host H] [--serve-port N] [--serve-token T]\n                               [--serve-origin URL]\u2026 a browser page allowed in\n                               /mcp is MCP; /api/<tool> is plain JSON\n  both take [--mcp-tools G,\u2026]  extra tool groups to serve, on top of the\n                               sessions ones: resources, terminals,\n                               automations, changes\n\nAnything else\n  dispatch <uri> <type>        send one action verbatim  [--field k=v]\u2026 [--chat]\n  <uri>, anywhere above        a session URI, or the agent-host-session://\n                               link the host's session tools answer with\n  status                       what this client is connected to       [--json]\n  --version                    what version this is\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 {
 }

package/dist/src/cli/main.js

@@ -5,6 +5,7 @@ import { configPath, loadConfig } from '../config.js';
 import { ago, archived, branch, json, line, mark, project, table } from './render.js';
 import { operate } from '../ahp/operate.js';
 import { SWITCHES } from '../flags.js';
+import { parseSessionLink, sessionOfLink } from '../links.js';
 import { spoken, turn as runTurn, until } from '../wait.js';
 import { GROUPS, served } from '../mcp/tools.js';
 import { SERVER } from '../mcp/serve.js';
@@ -104,8 +105,14 @@ Terminals
   terminal watch <uri>         follow its output   [--timeout S]
 
 Recording
-  AHPC_RECORD=<file>           append every frame, both directions, for
-                               'npm run wire' to check against the protocol
+  --wire <file>                append every frame, both directions, as JSON
+                               lines: { at, from, peer, frame }, for
+                               'npm run wire' to check against the protocol.
+                               AHPC_RECORD=<file> is the same, from a shell
+  wire <file>                  watch a capture as it is written, from either
+                               end: one row per frame, a row opens to the
+                               frame. Off a terminal, one line per frame
+                               [--follow] [--filter text] [--json]
 
 Serving these sessions to something else
   mcp                          MCP on stdin and stdout, for a client that
@@ -120,6 +127,8 @@ Serving these sessions to something else
 
 Anything else
   dispatch <uri> <type>        send one action verbatim  [--field k=v]… [--chat]
+  <uri>, anywhere above        a session URI, or the agent-host-session://
+                               link the host's session tools answer with
   status                       what this client is connected to       [--json]
   --version                    what version this is
   help                         this
@@ -147,6 +156,24 @@ class Args {
     constructor(rest) {
         this.rest = rest;
     }
+    /** Every positional that is a link, replaced by what it names. */
+    async resolveLinks(resolve) {
+        const next = [...this.rest];
+        for (let i = 0; i < next.length; i++) {
+            const word = next[i];
+            if (word.startsWith('--')) {
+                if (!SWITCHES.has(word))
+                    i++;
+                continue;
+            }
+            if (!/^agent-host-session:\/\//i.test(word))
+                continue;
+            const found = await resolve(word);
+            if (found !== undefined)
+                next[i] = found;
+        }
+        this.rest = next;
+    }
     /** The nth thing that is not a flag or a flag's value. */
     positional(index) {
         const found = [];
@@ -209,6 +236,7 @@ const where = (args) => {
         // write into it. Both off unless asked for.
         ...(args.value('--publish') ? { publish: args.value('--publish') } : {}),
         ...(args.has('--publish-writable') ? { publishWritable: true } : {}),
+        ...(args.value('--wire') ? { wire: args.value('--wire') } : {}),
     };
 };
 /** A URI the command needs, said plainly when it is missing. */
@@ -314,8 +342,53 @@ export async function cli(command, rest) {
             table(rows);
         return 0;
     }
+    /*
+     * A capture is a file, not a host.
+     *
+     * `ahpc wire out.jsonl` reads what `--wire` wrote - here or on the host -
+     * and needs no connection to do it; needing one would make it useless on
+     * exactly the capture of a host that would not answer.
+     */
+    if (command === 'wire') {
+        const file = args.positional(0);
+        if (file === undefined)
+            throw new Fault('wire wants a file: ahpc wire <file>');
+        const settings = loadConfig('ahpc', args.value('--config-file'));
+        const { wireTui } = await import('../wiretui.js');
+        const theme = args.value('--theme') ?? settings.theme;
+        const shell = args.value('--shell') ?? settings.shell;
+        const filter = args.value('--filter');
+        await wireTui({
+            file,
+            follow: args.has('--follow'),
+            json: wants,
+            ...(filter === undefined ? {} : { filter }),
+            ...(theme === undefined ? {} : { theme }),
+            ...(shell === undefined ? {} : { shell }),
+        });
+        return 0;
+    }
     const host = await connect(where(args));
     try {
+        /*
+         * A link where a URI is wanted.
+         *
+         * The reference host's session tools answer with `agent-host-session://`
+         * links, and a person pasting one into `session show` should get the
+         * session it names rather than a refusal about the scheme. Resolved once,
+         * against the catalogue, before any command reads its arguments; a link
+         * nobody on this host answers to is a sentence rather than a lookup that
+         * silently found nothing.
+         */
+        await args.resolveLinks(async (link) => {
+            const parsed = parseSessionLink(link);
+            if (parsed === undefined)
+                return undefined;
+            const row = sessionOfLink(parsed, await host.listSessions());
+            if (row === undefined)
+                throw new Fault(`No session on this host matches ${link}.`);
+            return row.resource;
+        });
         switch (command) {
             case 'status': {
                 const rows = await host.listSessions().catch(() => []);

package/dist/src/connect.d.ts

@@ -29,6 +29,8 @@ export interface Where {
     publish?: string;
     /** Whether the published directory may be written to. Read-only otherwise. */
     publishWritable?: boolean;
+    /** A file every frame is appended to, both directions, as JSON lines. */
+    wire?: string;
 }
 /**
  * Where a refusal goes before there is an application to put it in.

package/dist/src/connect.js

@@ -27,6 +27,7 @@ export async function connect(options) {
         return await liveHost({
             url: options.host,
             ...(options.token ? { token: options.token } : {}),
+            ...(options.wire ? { wire: options.wire } : {}),
             onRefusal: (_uri, message) => sink.report(message),
             onLimit: (message) => sink.report(message),
             // Work the host is doing under a token of its own. Reported while it

package/dist/src/control.d.ts

@@ -17,6 +17,12 @@ import type { Agent, Answer, Automation, Changeset, ChangesetScope, ChatSource,
 export interface Controller {
     refresh(): Promise<void>;
     open(uri: SessionUri): void;
+    /**
+     * Open what an `agent-host-session://` link names: the session, and the
+     * chat in it when the link says one. False when this host has no such
+     * session, said out loud as well.
+     */
+    openLink(link: string): Promise<boolean>;
     close(): void;
     /** Send, or queue when a turn is already running. */
     send(text: string): void;

package/dist/src/control.js

@@ -3,12 +3,13 @@ import { spawn } from 'node:child_process';
 import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { confirm } from '@textui/widgets';
-import { findBlocks, toBlocks } from './blocks.js';
+import { confirm, pick } from '@textui/widgets';
+import { findBlocks, valueIcon } from '@textui/chat';
+import { toBlocks } from './blocks.js';
+import { chatMatches, linksIn, parseSessionLink, sessionOfLink } from './links.js';
 import { operate } from './ahp/operate.js';
 import { createTerminals } from './terminal.js';
 import { SessionFlag } from './ahp/types.js';
-import { valueIcon } from './view/icons.js';
 import { ARCHIVED, BOOD_FLOAT, CAN_ADD_CHAT, CAN_FORK, CAN_SIDE_CHAT, CHAT_URI, CHATS, CUSTOMIZATIONS, CURSOR, DRAFT, EXPANDED, FILTER, FIND, FINDING, FIND_AT, HAS_CHATS, HOST, HOST_ERROR, INPUT, MODEL, MODEL_CONFIG, OPEN_TERMINAL, AUTOMATIONS, AUTOMATION_ROW, CHANGES as CHANGES_AT_PATH, CHANGE_AT, CHANGE_ROW, CHANGE_SCOPES, FILES_AT, FILES_OPEN, OPEN, OPEN_FILE, PROVIDER, MARKDOWN, QUEUE, RUNNING, SCREEN, SELECTED, SETTINGS, SIDEBAR, SPLIT_AT, SPLIT_DEFAULT, TURNS, WORKSPACE, applyEvent, inputRefused, pendingInput, queue, reportHostError, sendingInput, sessions, turns, writeSessions, writeStatus, } from './state.js';
 export const CONTROLLER = serviceKey('chat.controller');
 /** The command that asks about one config key. Registered when a host offers it. */
@@ -427,6 +428,50 @@ export function createController(app, host, bindings) {
             if (next)
                 controller.openChat(next);
         },
+        async openLink(link) {
+            const parsed = parseSessionLink(link);
+            if (parsed === undefined) {
+                failed(new Error(`${link} is not an agent-host-session:// link`));
+                return false;
+            }
+            // The catalogue as held, then as the host has it now: a session the
+            // agent made a moment ago may not have reached the list yet.
+            let row = sessionOfLink(parsed, sessions(app.store));
+            if (row === undefined) {
+                await controller.refresh();
+                row = sessionOfLink(parsed, sessions(app.store));
+            }
+            if (row === undefined) {
+                failed(new Error(`No session on this host matches ${link}`));
+                return false;
+            }
+            controller.open(row.resource);
+            if (parsed.chatId === undefined)
+                return true;
+            /*
+             * The chat, once the session has said which chats it has.
+             *
+             * The list arrives with the snapshot, a moment after `open`, and a chat
+             * URI is not something to build here - the host names them. Waited for,
+             * briefly; a chat the session no longer has is the session itself,
+             * which is the reference window's answer too.
+             */
+            const wanted = parsed.chatId;
+            for (let i = 0; i < 40; i++) {
+                if (app.store.get(OPEN) !== row.resource)
+                    return true;
+                // Not before the default chat is known: `open` sets it when the
+                // detail lands, and a switch made earlier is a switch it undoes.
+                const settled = app.store.get(CHAT_URI) !== null;
+                const chat = (app.store.get(CHATS) ?? []).find((entry) => chatMatches(entry.resource, wanted));
+                if (settled && chat !== undefined) {
+                    controller.openChat(chat.resource);
+                    return true;
+                }
+                await new Promise((resolve) => { setTimeout(resolve, 50); });
+            }
+            return true;
+        },
         open(uri) {
             // Closing drops this consumer only. Unsubscribing the channel to shed a
             // duplicate is what silently kills the stream everything else reads.
@@ -805,6 +850,29 @@ connection) {
      */
     const provider = () => app.store.get(PROVIDER) ?? 'claude';
     const agent = () => known.agents.find((found) => found.provider === provider());
+    /**
+     * The keys of a session's config that are about its directory.
+     *
+     * The host's own, named in the reference client's `sessionConfigKeys.ts`:
+     * whether to work in a worktree, from which branch, and how that worktree
+     * is made. An answer to any of them is an answer about one repository.
+     */
+    const ABOUT_WHERE = ['isolation', 'branch', 'worktreeBranchPrefix', 'worktreeBranchTrack', 'worktreeCreateNewBranch', 'worktreeIncludeFiles'];
+    /**
+     * Point the next session somewhere else.
+     *
+     * What was answered about the old directory goes with it: `branch: main`
+     * chosen in one repository would be sent back to the host as the answer
+     * for the next, and the host echoes what it is told - so the composer
+     * would show a branch the new repository may not have, and start from it.
+     * The rest of the answers are about the harness, not the directory, and
+     * stay.
+     */
+    const workspace = (path) => {
+        app.store.set(WORKSPACE, path);
+        const held = app.store.get(SETTINGS) ?? {};
+        app.store.set(SETTINGS, Object.fromEntries(Object.entries(held).filter(([key]) => !ABOUT_WHERE.includes(key))));
+    };
     const listAgents = async () => {
         try {
             known.agents = await controller.agents();
@@ -1078,6 +1146,39 @@ connection) {
             slots: ['palette'],
             run: () => { app.screens.reset('new'); app.focus.focus('chat.composer'); },
         },
+        {
+            /*
+             * A link in the transcript, followed.
+             *
+             * The reference host's session tools answer with an
+             * `agent-host-session://` link, and its window makes one a click. A
+             * terminal has no click, so the links in the open transcript are the
+             * choices, and one chosen opens the session or the chat it names. One
+             * typed is followed the same way, which is how a link from somewhere
+             * else gets opened.
+             */
+            id: 'chat.openLink',
+            title: 'Open a session link',
+            category: 'Session',
+            description: 'Follow an agent-host-session:// link in this transcript',
+            slots: ['palette'],
+            when: `${OPEN}`,
+            args: [{
+                    name: 'link',
+                    type: 'string',
+                    required: true,
+                    description: 'The link to follow',
+                    choices: () => linksIn(app.store.get(TURNS) ?? []).map((found) => ({
+                        value: found.link,
+                        label: found.link.replace(/^agent-host-session:\/\//, ''),
+                        ...(found.context ? { description: found.context } : {}),
+                    })),
+                }],
+            run: (args) => {
+                void controller.openLink(String(args.link ?? '')).then((opened) => { if (opened)
+                    app.screens.push('chat'); });
+            },
+        },
         {
             id: 'go.changes',
             title: 'What this session changed',
@@ -1610,7 +1711,7 @@ connection) {
             id: 'terminal.new',
             title: 'Open a terminal',
             category: 'Terminal',
-            description: 'Start a shell on the host, in a directory it serves',
+            description: 'Start a shell on the host, in the workspace directory',
             slots: ['palette'],
             run: () => {
                 const where = app.store.get(WORKSPACE);
@@ -1684,13 +1785,41 @@ connection) {
             id: 'compose.workspace',
             title: 'Workspace',
             category: 'Compose',
-            description: 'Select the workspace',
+            description: 'Choose the directory the session works in, from the host\'s own',
+            slots: ['palette'],
+            when: `!${OPEN}`,
+            /*
+             * Picked by looking, the way the reference client picks a folder: it
+             * lists the host's directories over `resourceList`, and so does this,
+             * through the `file:` provider `registerChat` mounts. The dialog is
+             * textui's, which walks the resource registry and never the disk this
+             * client is on - a path typed blind was the only way before, and it
+             * had to be a path on a machine you could not see.
+             *
+             * Started where the chip already points, when the host will list it;
+             * a directory off the catalogue otherwise, which is somewhere on the
+             * host's machine that is known to exist.
+             */
+            run: async () => {
+                const held = app.store.get(WORKSPACE) ?? '';
+                const at = `file://${held}`;
+                const served = sessions(app.store).flatMap((one) => one.workingDirectories)[0];
+                const listable = held !== '' && await controller.files(at).then(() => true, () => false);
+                const start = listable ? at : served ?? at;
+                const picked = await pick(app, { start, wants: 'directory', title: 'Workspace', placeholder: 'Filter this directory…' });
+                if (picked !== null)
+                    workspace(decodeURIComponent(picked.replace(/^file:\/\//, '')));
+            },
+        },
+        {
+            id: 'compose.workspace.path',
+            title: 'Workspace path',
+            category: 'Compose',
+            description: 'Type the directory the session works in',
             slots: ['palette'],
             when: `!${OPEN}`,
-            // No `choices`, so the palette asks for it as text - the same overlay,
-            // with its field as the answer rather than as a filter. Give it a
-            // `choices` function later and the same chip becomes a list of
-            // workspaces without anything else changing.
+            // For a host that lists nothing - one without the `resource*` family -
+            // and for a path already known, which is quicker typed than walked to.
             args: [{
                     name: 'path',
                     type: 'string',
@@ -1700,7 +1829,7 @@ connection) {
             run: (args) => {
                 const path = String(args.path ?? '').trim();
                 if (path)
-                    app.store.set(WORKSPACE, path);
+                    workspace(path);
             },
         },
         {
@@ -2195,6 +2324,7 @@ function shipped() {
         // out of it is escape - the pair that makes every other letter reachable.
         { keys: 'c', commandId: 'go.changes', scopeId: CHAT_SCOPE },
         { keys: 'f', commandId: 'go.files', scopeId: CHAT_SCOPE },
+        { keys: 'l', commandId: 'chat.openLink', scopeId: CHAT_SCOPE },
         /*
          * On the changes screen, and nowhere else.
          *

package/dist/src/flags.js

@@ -27,7 +27,7 @@ export const COMMANDS = new Set([
     'agents', 'models', 'commands', 'customizations', 'completions', 'changes', 'content',
     'prompt', 'exec', 'cancel', 'queue', 'unqueue',
     'watch', 'confirm', 'answer', 'dispatch',
-    'mcp', 'serve',
+    'mcp', 'serve', 'wire',
 ]);
 /**
  * Every flag that takes no value, in either front end.

package/dist/src/links.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `agent-host-session://` links, which are how one session names another.
+ *
+ * The reference host's session tools answer with one - `create_session`,
+ * `list_sessions` and `send_message` each put an `openLink` in their result -
+ * and its window turns the link into a click that opens the session or the
+ * chat. A terminal has no click, so here the same link is something to pick:
+ * the links in the open transcript are offered as a list, and one chosen
+ * opens what it names. The shape is the reference host's
+ * (`common/openSessionLink.ts`): `agent-host-session://<provider>/<id>`, with
+ * `?chat=<chatId>` for one chat of it and `&turn=<turnId>` for one turn.
+ */
+import type { SessionSummary, Turn } from './ahp/types.js';
+export interface SessionLink {
+    provider: string;
+    id: string;
+    chatId?: string;
+    turnId?: string;
+}
+/** The link read, or undefined for text that is not one. */
+export declare function parseSessionLink(text: string): SessionLink | undefined;
+/** The id inside a session URI, whatever scheme it is under: `ahp-session:/x` and `claude:/x` are both `x`. */
+export declare const idOf: (uri: string) => string;
+/**
+ * The row a link names.
+ *
+ * Matched on the id and the provider, whichever scheme the row is under: a
+ * session this client started is `ahp-session:/` and one read off the host's
+ * catalogue is `<provider>:/`, and the link says neither.
+ */
+export declare const sessionOfLink: (link: SessionLink, rows: SessionSummary[]) => SessionSummary | undefined;
+/** One link found in a transcript, and where. */
+export interface FoundLink {
+    link: string;
+    /** What was around it, for the row that offers it. */
+    context: string;
+    turnId: string;
+}
+/**
+ * Every link in the transcript, once each, in the order they appear.
+ *
+ * Read from what a person can see: the prose, the tool calls' outcomes and
+ * outputs, and the host's notices. A tool answering `create_session` puts the
+ * link in its output, which is where somebody reading the transcript finds it.
+ */
+export declare function linksIn(turns: Turn[]): FoundLink[];
+/**
+ * Whether a chat URI is the chat a link names.
+ *
+ * The id is the URI's authority where it has one - `ahp-chat://<chatId>/<session>`,
+ * which is how the reference host and ahpd spell a chat - and the path
+ * otherwise, `ahp-chat:/<id>`, which is the protocol's own shape.
+ */
+export declare const chatMatches: (chatUri: string, chatId: string) => boolean;