@softov/ahpc 0.1.0 → 0.3.0

package/README.md

@@ -1,5 +1,6 @@
 # ahpc
 
+[![CI](https://github.com/softov/ahpc/actions/workflows/ci.yml/badge.svg)](https://github.com/softov/ahpc/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/%40softov%2Fahpc)](https://www.npmjs.com/package/@softov/ahpc)
 ![license MIT](https://img.shields.io/badge/license-MIT-blue)
 ![node >=22](https://img.shields.io/badge/node-%3E%3D22-5fa04e)
@@ -7,7 +8,7 @@
 ![built with TextUI](https://img.shields.io/badge/built%20with-TextUI-7048e8)
 
 A terminal client for the [Agent Host Protocol](https://microsoft.github.io/agent-host-protocol/).
-It can be used as cli (commands) or tui (interactive chat).
+It can be used as cli (commands), tui (interactive chat), or a tool server that lets an agent elsewhere drive the sessions on your host.
 
 Connect to an AHP host, manage sessions, and work with agents directly from your terminal.
 
@@ -55,6 +56,7 @@ ahpc session list --host ws://127.0.0.1:9187
 | Automations | Scheduled and triggered runs, with their history. |
 | Customizations | Skills, prompts, agents and MCP servers, and which are enabled. |
 | Telemetry | Stream the host's log. |
+| Tool server | Serve those sessions to an agent somewhere else, over MCP or a plain JSON API. |
 
 ## Interactive
 
@@ -209,14 +211,80 @@ Writes are guarded by the file's etag unless you pass `--force`, so two clients
 | `automation enable <uri>` / `disable <uri>` | Enable or disable it | |
 | `automation rm <uri>` | Delete it | |
 
+### Serving these sessions to something else
+
+| Command | | |
+|---|---|---|
+| `mcp` | MCP on stdin and stdout, for a client that launches this process | `--mcp-tools G,…` |
+| `serve` | The same tools on a socket, shared | `--serve-host H` `--serve-port N` `--serve-token T` `--serve-origin URL` `--mcp-tools G,…` |
+
 ### Anything else
 
 | Command | | |
 |---|---|---|
 | `dispatch <uri> <type>` | Send a raw protocol action | `--field k=v` `--chat` |
 | `config` | Show the config file path and current values | `--json` |
+| `--version` | What version this is | |
 | `help` | Print this command list | |
 
+## As a tool server
+
+The other direction: an agent somewhere else driving the sessions on your host, through this client. Twelve tools - list, create and dispose a session, read its transcript, say something and wait for the answer, and answer what the agent stops to ask.
+
+`ahpc mcp` speaks MCP on stdin and stdout, which is what an MCP client that launches the process expects:
+
+```json
+{
+  "mcpServers": {
+    "ahp": { "command": "ahpc", "args": ["--host", "ws://127.0.0.1:9187", "mcp"] }
+  }
+}
+```
+
+`ahpc serve` is the same twelve tools on a socket that several callers share, and it stays up until it is stopped:
+
+```sh
+ahpc --host ws://127.0.0.1:9187 serve --serve-port 7431
+```
+
+`POST /mcp` is MCP for a client that speaks it. `POST /api/<tool>` is the same tool with the arguments as the body and the answer as the body, for everything that is not one - a shell script, a webhook, a program in another language. `GET /api` lists what there is.
+
+```sh
+curl -XPOST localhost:7431/api/new_session -d '{"workingDirectory":"/work"}'
+curl -XPOST localhost:7431/api/send_turn -d '{"session":"claude:/…","text":"what is in this directory"}'
+```
+
+### More than the twelve
+
+Files, terminals, automations and changesets are there too, one group at a time, and off unless asked for. That is on purpose: a tool table is read by a model alongside everything else it was given, and thirty tools is a worse server than twelve for the thing almost everybody wants, which is driving a session.
+
+```sh
+ahpc --host ws://127.0.0.1:9187 mcp --mcp-tools resources,changes
+```
+
+| Group | Tools |
+|---|---|
+| `resources` | `list_directory` `read_file` `write_file` `make_directory` `delete_path` `move_path` `copy_path` |
+| `terminals` | `list_terminals` `new_terminal` `send_to_terminal` `read_terminal` `dispose_terminal` |
+| `automations` | `list_automations` `run_automation` `set_automation_enabled` `remove_automation` |
+| `changes` | `list_changesets` `show_changes` |
+
+Repeatable as well as comma-separated. It is `--mcp-tools` rather than `--tools` because every other flag on this client is an AHP thing, and a bare `--tools` would read like it was choosing which tools the *agent* may call - a different question with a different answer.
+
+Calling a tool from a group nobody turned on is refused with the flag that would turn it on, rather than with "no such tool", because those are different problems and only the person who started the server can fix the first.
+
+Writing needs the host to have granted write access to that directory, and a host that has not refuses with `-32009` saying so. That is not something this client can grant on a model's behalf: it is the same question a person answers before a session may edit their repository.
+
+`read_file` and `write_file` take a `file://` URI on the *host*, not a path on the machine running `ahpc` - the two may not be the same machine. `write_file` reads the file's etag first and refuses a write if it changed in between, unless passed `force`; a model reading a file, thinking, and writing it back is a read-modify-write with a person editing in the middle of it.
+
+`send_turn` blocks until the turn ends and returns what the agent said. A turn that stops to ask a person something is not finished: `wait_for_attention` says what it wants, and `confirm_tool_call` and `answer_question` answer it.
+
+A caller that does not want to sit in silence for a minute puts a `progressToken` in the request's `_meta`, and gets a `notifications/progress` line for each tool the agent reaches for. On `serve` that also decides the shape of the reply: asked for, the POST is answered with an SSE stream carrying the notifications and then the result; not asked for, it is one JSON object. MCP has no shape for streaming partial *result* content, so the reply itself still arrives whole at the end - what this fixes is an agent that looked frozen, not one you want to watch write.
+
+It binds to `127.0.0.1` unless told otherwise, because anybody who can reach the port can drive every session on the host. `--serve-token` sets a bearer token, which is what makes `--serve-host 0.0.0.0` defensible.
+
+Requests carrying a browser `Origin` are refused unless the origin is this server's own or was named with `--serve-origin`, repeatable. That is the transport's own rule and it is not paranoia: loopback is not the protection it looks like, because a page on any site can POST to `127.0.0.1` from inside the browser of the person running this, and the request arrives from their own machine. A program - a script, a webhook, an MCP client - sends no `Origin` and is let through.
+
 ## AHP support
 
 All 30 client-to-server requests are implemented, and 21 of the 45 client-dispatchable actions are used. `ahpc` subscribes to the root, session, chat, terminal and automation channels, plus the telemetry channel the host advertises for its log.

package/dist/src/ahp/channels.js

@@ -21,7 +21,7 @@ export function openChannels(options) {
         const found = held.get(uri);
         if (found)
             return found;
-        const made = { uses: 0, consumers: new Set(), opened: false, told: false, waiting: [] };
+        const made = { uses: 0, consumers: new Set(), opened: false, known: false, told: false, waiting: [] };
         held.set(uri, made);
         return made;
     };
@@ -142,6 +142,7 @@ export function openChannels(options) {
         const asking = client.subscribe(uri).then(({ result }) => {
             if (era === generation && held.get(uri) === channel) {
                 channel.opened = true;
+                channel.known = true;
                 channel.fromSeq = result.snapshot?.fromSeq;
             }
             return bag(result.snapshot?.state);
@@ -320,7 +321,11 @@ export function openChannels(options) {
                     drop(uri);
             }
         },
-        held: () => [...held.keys()].filter((uri) => (held.get(uri)?.uses ?? 0) > 0),
+        // What the host can be asked to resume: held by a reader *and* opened at
+        // some point, because the host cannot restore a subscription it was never
+        // sent.
+        held: () => [...held.keys()]
+            .filter((uri) => (held.get(uri)?.uses ?? 0) > 0 && held.get(uri)?.known === true),
         seq: () => seen,
         refusal: (uri) => refused.get(uri),
         forget: (uri) => { if (uri === undefined)
@@ -368,7 +373,7 @@ export function openChannels(options) {
                 // subscriptions behind it are ones it restored itself and none of them
                 // needs asking for again.
                 for (const channel of held.values()) {
-                    if (channel.uses === 0 || channel.opened)
+                    if (channel.uses === 0 || channel.opened || !channel.known)
                         continue;
                     channel.opened = true;
                     channel.told = true;
@@ -386,6 +391,7 @@ export function openChannels(options) {
                 if (!channel)
                     continue;
                 channel.opened = true;
+                channel.known = true;
                 channel.told = true;
                 channel.waiting.length = 0;
                 for (const consumer of channel.consumers)
@@ -403,6 +409,7 @@ export function openChannels(options) {
         adopt: (uri, state) => {
             const channel = entry(uri);
             channel.opened = true;
+            channel.known = true;
             channel.told = false;
             channel.initial = state;
         },

package/dist/src/ahp/live.js

@@ -427,11 +427,12 @@ export function activityOf(status, asked, running, failed) {
  */
 function transcript(chat) {
     const out = [];
-    const add = (value, running) => {
+    const built = (value, running) => {
+        const rows = [];
         const found = bag(value);
         const said = str(bag(found.message).text);
         if (said) {
-            out.push({
+            rows.push({
                 id: `${str(found.id) ?? ''}:said`,
                 role: 'user',
                 message: said,
@@ -442,14 +443,70 @@ function transcript(chat) {
         }
         const agent = turn(found, running);
         delete agent.message;
-        out.push(agent);
+        rows.push(agent);
+        return rows;
     };
-    for (const entry of list(chat.turns))
-        add(entry, false);
+    const finished = list(chat.turns);
+    /*
+     * The whole finished prefix, when it is the same array it was last time.
+     *
+     * The per-turn cache below removes the building; this removes the walking.
+     * While a reply streams, only `activeTurn` changes - `turns` keeps its
+     * identity through every delta - so the history is copied once per turn
+     * rather than once per token, which is the difference between constant and
+     * linear on the path that runs most.
+     */
+    const whole = typeof chat.turns === 'object' && chat.turns !== null
+        ? prefixes.get(chat.turns)
+        : undefined;
+    if (whole !== undefined)
+        out.push(...whole);
+    else
+        for (const entry of finished) {
+            /*
+             * A finished turn is built once, and after that it is the same object.
+             *
+             * This runs after every reduced action, so a token arriving into a long
+             * conversation rebuilt every turn in it - measured at 2.5ms per token into
+             * two thousand turns, against a microsecond for the reduce that caused it.
+             *
+             * Keyed on the turn object rather than on its id, which is what makes the
+             * invalidation right by construction: the reducer is immutable, so a turn
+             * that changed is a new object and misses, and a turn that did not is the
+             * same one and hits. History loads, truncation and reconnect snapshots all
+             * build new objects, so there is nothing to remember to invalidate - which
+             * is the part of a cache like this that goes wrong.
+             *
+             * Weak, so nothing here keeps a conversation alive after the view on it
+             * has gone. Nothing mutates a `Turn` - every reader treats them as values -
+             * which is what makes handing the same array back twice safe.
+             */
+            if (typeof entry === 'object' && entry !== null) {
+                const had = ready.get(entry);
+                if (had !== undefined) {
+                    out.push(...had);
+                    continue;
+                }
+                const made = built(entry, false);
+                ready.set(entry, made);
+                out.push(...made);
+                continue;
+            }
+            out.push(...built(entry, false));
+        }
+    if (whole === undefined && typeof chat.turns === 'object' && chat.turns !== null) {
+        prefixes.set(chat.turns, [...out]);
+    }
+    // Never the running turn: it is a new object on every delta, so caching it
+    // would be a write per token and a hit never.
     if (chat.activeTurn)
-        add(chat.activeTurn, true);
+        out.push(...built(chat.activeTurn, true));
     return out;
 }
+/** What `transcript` has already built for a finished turn. See the note in it. */
+const ready = new WeakMap();
+/** And for a whole `turns` array, which is what a streaming reply does not change. */
+const prefixes = new WeakMap();
 const KINDS = {
     text: 'text', number: 'number', integer: 'integer', boolean: 'boolean',
     'single-select': 'single-select', 'multi-select': 'multi-select',

package/dist/src/ahp/publish.js

@@ -153,6 +153,26 @@ export function publish(options = {}) {
      * What is not deliberate is fixing one and not the other: everything here
      * was wrong in both at once, and was corrected in both at once.
      */
+    /*
+     * The destination half of a copy or a move.
+     *
+     * Two refusals the source does not have. A destination that is a symbolic
+     * link would carry the bytes to wherever it points, which is the same hole
+     * `O_NOFOLLOW` closes for a write. And `failIfExists` is the caller saying
+     * it does not want an overwrite, which is the whole reason the flag is on
+     * the wire - a copy that quietly replaced a file is the loss it exists to
+     * prevent. `ahpd` refuses both in its `pair`.
+     */
+    const pair = async (destination, failIfExists) => {
+        const to = await where(destination, true);
+        if (await lstat(to).then((found) => found.isSymbolicLink(), () => false)) {
+            throw new PublishRefusal(PERMISSION_DENIED, `${String(destination)} is a symbolic link.`);
+        }
+        if (failIfExists && await stat(to).then(() => true, () => false)) {
+            throw new PublishRefusal(ALREADY_EXISTS, `${String(destination)} already exists.`);
+        }
+        return to;
+    };
     const write = async (at, uri, params) => {
         const before = writes.get(at) ?? Promise.resolve();
         const operation = before.catch(() => { }).then(async () => {
@@ -323,7 +343,10 @@ export function publish(options = {}) {
             resourceWrite: async (params) => {
                 const input = params;
                 mutable();
-                await write(await where(input.uri), input.uri, input);
+                // The link itself, never its destination: `O_NOFOLLOW` in `write` can
+                // only refuse a final symbolic link if the path it is handed still
+                // has one. `ahpd` resolves only the parent for the same reason.
+                await write(await where(input.uri, true), input.uri, input);
                 return {};
             },
             resourceDelete: async (params) => {
@@ -334,20 +357,22 @@ export function publish(options = {}) {
             },
             resourceMkdir: async (params) => {
                 mutable();
-                await mkdir(await where(params.uri), { recursive: true });
+                await mkdir(await where(params.uri, true), { recursive: true });
                 return {};
             },
             resourceMove: async (params) => {
-                const { source, destination } = params;
+                const { source, destination, failIfExists } = params;
                 mutable();
-                await rename(await where(source, true), await where(destination, true));
+                const from = await where(source, true);
+                const to = await pair(destination, failIfExists === true);
+                await rename(from, to);
                 return {};
             },
             resourceCopy: async (params) => {
-                const { source, destination } = params;
+                const { source, destination, failIfExists } = params;
                 mutable();
                 const from = await where(source);
-                const to = await where(destination);
+                const to = await pair(destination, failIfExists === true);
                 const input = await open(from, constants.O_RDONLY | constants.O_NOFOLLOW);
                 try {
                     const output = await open(to, constants.O_WRONLY | constants.O_CREAT | constants.O_NOFOLLOW);

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\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";
+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";
 /** A message for the person, not a stack trace. */
 export declare class Fault extends Error {
 }

package/dist/src/cli/main.js

@@ -5,6 +5,11 @@ 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 { spoken, turn as runTurn, until } from '../wait.js';
+import { GROUPS, served } from '../mcp/tools.js';
+import { SERVER } from '../mcp/serve.js';
+import { stdio } from '../mcp/stdio.js';
+import { serve as serveHttp } from '../mcp/http.js';
 export const HELP = `ahpc - drive an agent host from a shell
 
   ahpc [--host ws://…] <command> [args]        the screen is 'ahpc' with no command
@@ -102,9 +107,21 @@ Recording
   AHPC_RECORD=<file>           append every frame, both directions, for
                                'npm run wire' to check against the protocol
 
+Serving these sessions to something else
+  mcp                          MCP on stdin and stdout, for a client that
+                               launches this process
+  serve                        the same tools on a socket, shared
+                               [--serve-host H] [--serve-port N] [--serve-token T]
+                               [--serve-origin URL]… a browser page allowed in
+                               /mcp is MCP; /api/<tool> is plain JSON
+  both take [--mcp-tools G,…]  extra tool groups to serve, on top of the
+                               sessions ones: resources, terminals,
+                               automations, changes
+
 Anything else
   dispatch <uri> <type>        send one action verbatim  [--field k=v]… [--chat]
   status                       what this client is connected to       [--json]
+  --version                    what version this is
   help                         this
 
 The host
@@ -221,50 +238,6 @@ const needs = (args, index, what) => {
         throw new Fault(`This wants ${what}.`);
     return found;
 };
-/**
- * Watch one session until it does something, then stop watching.
- *
- * Every streaming command is this with a different stopping condition, so it
- * is written once. The subscription is always closed - a CLI that left one
- * open would be a process that never exits, which is the one thing a shell
- * cannot work around.
- */
-function until(host, uri, done, options = {}) {
-    return new Promise((answer) => {
-        let closed = false;
-        /*
-         * The handle may not exist yet when this runs.
-         *
-         * A host is entitled to deliver the opening snapshot *synchronously*
-         * inside `subscribe` - the scripted one does, and it is the honest thing
-         * for a host holding the state already - so a condition satisfied by that
-         * first event fires before `subscribe` has returned anything to close.
-         * Reading the handle there threw, which made every waiting command fail
-         * against the scripted host and work against a socket, purely because one
-         * of them answers a tick later.
-         */
-        let handle;
-        const finish = (event) => {
-            if (closed)
-                return;
-            closed = true;
-            clearTimeout(timer);
-            handle?.close();
-            answer(event);
-        };
-        const timer = setTimeout(() => finish(undefined), Math.max(1, (options.timeoutSeconds ?? 900)) * 1000);
-        timer.unref?.();
-        handle = host.subscribe(uri, (event) => {
-            options.onEvent?.(event);
-            if (done(event))
-                finish(event);
-        });
-        // Already over, before there was a handle to close. Closing it now is what
-        // `finish` could not do.
-        if (closed)
-            handle.close();
-    });
-}
 /**
  * Ask again once the catalogue moves, for an answer that starts out empty.
  *
@@ -305,11 +278,6 @@ const snapshot = async (host, uri) => {
     const event = await until(host, uri, (e) => e.type === 'snapshot', { timeoutSeconds: 30 });
     return event?.type === 'snapshot' ? event : undefined;
 };
-/** A turn, as a line of prose rather than a tree of parts. */
-const spoken = (turn) => turn.parts
-    .map((part) => (part.kind === 'markdown' ? part.content : ''))
-    .join('')
-    .trim();
 /**
  * One command, and then the process is done.
  *
@@ -359,6 +327,50 @@ export async function cli(command, rest) {
                 line(`${rows.length} session(s)`);
                 break;
             }
+            /*
+             * The tool server, on whichever transport was asked for.
+             *
+             * Both serve the same table from `mcp/tools.ts`. `mcp` is stdio and is
+             * owned by the client that launched this process; `serve` is a socket
+             * several callers share, speaking MCP at `/mcp` and a plain JSON API at
+             * `/api/<tool>` for anything that is not an MCP client.
+             */
+            case 'mcp': {
+                const groups = wanted(args);
+                // Nothing but JSON-RPC on stdout, ever: a stray line here is a parse
+                // error at the other end of a pipe nobody can see.
+                process.stderr.write(`ahpc mcp on ${host.url || '(scripted host)'}, ${served(groups).length} tools\n`);
+                await stdio(host, { ...SERVER, groups, onProblem: (said) => process.stderr.write(`${said}\n`) });
+                return 0;
+            }
+            case 'serve': {
+                const groups = wanted(args);
+                const at = await serveHttp(host, {
+                    ...SERVER,
+                    groups,
+                    host: args.value('--serve-host') ?? '127.0.0.1',
+                    port: Number(args.value('--serve-port') ?? 7431),
+                    ...(args.value('--serve-token') === undefined ? {} : { token: args.value('--serve-token') }),
+                    // Repeatable, because a page and its API are often two origins.
+                    origins: args.every('--serve-origin'),
+                    onProblem: (said) => process.stderr.write(`${said}\n`),
+                });
+                line(`ahpc on http://${at.host}:${at.port} against ${host.url || '(scripted host)'}`);
+                line(`  /mcp        MCP, ${served(groups).length} tools`);
+                line('  /api/<tool> the same tools as plain JSON');
+                if (args.value('--serve-token') === undefined && at.host !== '127.0.0.1' && at.host !== '::1') {
+                    // Said rather than refused: binding wide open is a decision somebody
+                    // may have made on purpose behind something else.
+                    line('  no token: anyone who can reach this port can drive every session on the host');
+                }
+                // Until it is stopped. There is no work left to return to.
+                await new Promise((forever) => {
+                    const stop = () => { void at.close().then(() => forever()); };
+                    process.on('SIGINT', stop);
+                    process.on('SIGTERM', stop);
+                });
+                return 0;
+            }
             case 'session': return await sessions(host, args, wants);
             case 'chat': return await chats(host, args, wants);
             case 'terminal': return await shells(host, args, wants);
@@ -995,6 +1007,26 @@ async function chats(host, args, wants) {
     }
     throw new Fault(`No 'chat ${verb}'. Try 'ahpc help'.`);
 }
+/**
+ * The tool groups `--mcp-tools` asked for.
+ *
+ * Comma-separated and repeatable, because both are what people type. Named
+ * `--mcp-tools` and not `--tools`: every other flag on this client is an AHP
+ * thing, and a bare `--tools` reads like one - it would look like it was
+ * choosing which tools the *agent* may call, which is a different question
+ * with a different answer.
+ */
+function wanted(args) {
+    const said = args.every('--mcp-tools')
+        .flatMap((one) => one.split(','))
+        .map((one) => one.trim())
+        .filter((one) => one !== '');
+    const strange = said.filter((one) => !GROUPS.includes(one));
+    if (strange.length > 0) {
+        throw new Fault(`No tool group called ${strange.join(', ')}. There is ${GROUPS.join(', ')}.`);
+    }
+    return said;
+}
 /** Everything under `terminal`. */
 async function shells(host, args, wants) {
     const verb = args.positional(0) ?? 'list';
@@ -1343,56 +1375,26 @@ async function turns(host, command, args, wants) {
      * second answer to the same question. So "what is new" is the part of the
      * running turn not yet printed, which is a length rather than an event.
      */
+    /*
+     * Say something and wait for the answer, printing it as it arrives.
+     *
+     * The waiting is `wait.ts`, which the tool server uses too; what is here is
+     * the part that is about a terminal. `--json` prints the finished turn
+     * instead, so the stream is suppressed rather than interleaved with it.
+     */
     const run = async (uri, text) => {
-        let printed = 0;
-        let sawActive = false;
-        let before = new Set();
-        let first = true;
-        let noted;
-        let answer;
-        // Subscribed before saying anything: the first snapshot is the baseline
-        // that says which turns were already there, and one taken afterwards
-        // would count the new turn among them.
-        const finished = until(host, uri, (event) => {
-            if (event.type !== 'snapshot')
-                return false;
-            if (first) {
-                first = false;
-                before = new Set(event.turns.map((turn) => turn.id));
-            }
-            if (event.active) {
-                sawActive = true;
-                if (!wants) {
-                    const now = spoken(event.active);
-                    if (now.length > printed) {
-                        process.stdout.write(now.slice(printed));
-                        printed = now.length;
-                    }
-                    // On stderr, so a pipe still gets only the answer while a person
-                    // watching sees why it stopped.
-                    const call = event.active.parts.find((part) => part.kind === 'toolCall'
-                        && part.call.status === 'pending-confirmation');
-                    if (call?.kind === 'toolCall' && noted !== call.call.id) {
-                        noted = call.call.id;
-                        process.stderr.write(`  · waiting on ${call.call.name}  ${call.call.id}\n`);
-                    }
-                }
-                return false;
-            }
-            // Something wants a person. Not finished, and not this command's to answer.
-            if (event.input)
-                return false;
-            // Nothing running. Done once a turn of *ours* has finished - one that
-            // was not in the baseline, rather than merely the last in the list.
-            const fresh = event.turns.filter((turn) => turn.role === 'agent' && !before.has(turn.id));
-            if (!sawActive && fresh.length === 0)
-                return false;
-            answer = fresh[fresh.length - 1];
-            return true;
-        }, { timeoutSeconds: Number(args.value('--timeout') ?? 900) });
-        host.say(uri, text, selected(args));
-        await finished;
-        if (!wants && printed > 0)
+        let printed = false;
+        const answer = await runTurn(host, uri, text, {
+            model: selected(args),
+            timeoutSeconds: Number(args.value('--timeout') ?? 900),
+            ...(wants ? {} : {
+                onDelta: (part) => { printed = true; process.stdout.write(part); },
+                // On stderr, so a pipe still gets only the answer while a person
+                // watching sees why it stopped.
+                onWaiting: (call) => process.stderr.write(`  \u00b7 waiting on ${call.name}  ${call.id}\n`),
+            }),
+        });
+        if (!wants && printed)
             line();
         return answer;
     };

package/dist/src/flags.js

@@ -27,6 +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',
 ]);
 /**
  * Every flag that takes no value, in either front end.
@@ -40,6 +41,9 @@ export const COMMANDS = new Set([
 export const SWITCHES = new Set([
     // The screen's own.
     '--static', '-s', '--settled', '--approve', '--answer', '--bood', '--help', '-h',
+    // Answered by the entry point before either front end is loaded, and here
+    // so that neither swallows the word after it.
+    '--version', '-v',
     // Shape and scope, on both sides.
     '--json', '--full', '--all', '--archived', '--unread', '--undo',
     '--off', '--deny', '--reject', '--claude', '--chat',
@@ -52,6 +56,9 @@ export const SWITCHES = new Set([
     '--operations', '--markdown',
     // Asking rather than doing, and agreeing in advance.
     '--list', '--yes',
+    // Which transport the tool server speaks. Neither takes a value, and the
+    // ports it listens on are `--serve-host` and `--serve-port`, which do.
+    '--stdio', '--http',
 ]);
 /**
  * The command, wherever it is.

package/dist/src/main.js

@@ -12,8 +12,20 @@
 // does not load a front end, which is the reason they were copied here.
 import { commandIn } from './flags.js';
 const argv = process.argv.slice(2);
-const first = commandIn(argv);
-if (first !== undefined) {
+/*
+ * Answered before anything is loaded.
+ *
+ * `--version` with no command would otherwise open the screen, which is a
+ * question answered by a whole renderer starting up and then being read off a
+ * status bar. Neither front end is imported to answer it.
+ */
+const asked = argv.includes('--version') || argv.includes('-v');
+const first = asked ? undefined : commandIn(argv);
+if (asked) {
+    const { version } = await import('./version.js');
+    process.stdout.write(`${version()}\n`);
+}
+else if (first !== undefined) {
     /*
      * A closed pipe is not an error.
      *