@softov/ahpc 0.1.0 → 0.2.0

package/README.md

@@ -7,7 +7,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 +55,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,6 +210,13 @@ 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 | |
+| `serve` | The same tools on a socket, shared | `--serve-host H` `--serve-port N` `--serve-token T` |
+
 ### Anything else
 
 | Command | | |
@@ -217,6 +225,37 @@ Writes are guarded by the file's etag unless you pass `--force`, so two clients
 | `config` | Show the config file path and current values | `--json` |
 | `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"}'
+```
+
+`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.
+
+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.
+
 ## 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/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                               /mcp is MCP; /api/<tool> is plain JSON\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 {
 }

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 { TOOLS } 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,6 +107,13 @@ 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]
+                               /mcp is MCP; /api/<tool> is plain JSON
+
 Anything else
   dispatch <uri> <type>        send one action verbatim  [--field k=v]… [--chat]
   status                       what this client is connected to       [--json]
@@ -221,50 +233,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 +273,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 +322,45 @@ 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': {
+                // 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)'}, ${TOOLS.length} tools\n`);
+                await stdio(host, { ...SERVER, onProblem: (said) => process.stderr.write(`${said}\n`) });
+                return 0;
+            }
+            case 'serve': {
+                const at = await serveHttp(host, {
+                    ...SERVER,
+                    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') }),
+                    onProblem: (said) => process.stderr.write(`${said}\n`),
+                });
+                line(`ahpc on http://${at.host}:${at.port} against ${host.url || '(scripted host)'}`);
+                line(`  /mcp        MCP, ${TOOLS.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);
@@ -1343,56 +1345,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.
@@ -52,6 +53,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/mcp/http.d.ts

@@ -0,0 +1,24 @@
+import type { HostConnection } from '../ahp/connection.js';
+export interface ServeOptions {
+    host: string;
+    port: number;
+    name: string;
+    version: string;
+    /**
+     * A bearer token every request must carry, if any.
+     *
+     * Absent means anybody who can reach the port can drive every session on the
+     * host, which is why `--serve-host` defaults to the loopback address. A
+     * token is what makes binding anywhere else defensible.
+     */
+    token?: string;
+    onProblem?(said: string): void;
+}
+/** What this is listening on, and how to stop it. */
+export interface Serving {
+    host: string;
+    port: number;
+    close(): Promise<void>;
+}
+/** Start listening. Answers once the socket is up. */
+export declare function serve(host: HostConnection, options: ServeOptions): Promise<Serving>;

package/dist/src/mcp/http.js

@@ -0,0 +1,140 @@
+/*
+ * The same tools over a socket, twice.
+ *
+ * `POST /mcp` is MCP's streamable HTTP transport, which for a tools-only
+ * server is a JSON-RPC request in and a JSON-RPC response out. `POST
+ * /api/<tool>` is the same tool with the arguments as the body and the answer
+ * as the body, for everything that is not an MCP client - a shell script, a
+ * webhook, a program in another language. `GET /api` lists what there is.
+ *
+ * One process, one connection to the host, however many callers. That is the
+ * difference from `stdio`, and the reason both exist: stdio is owned by the
+ * client that launched it, this is shared and outlives any of them.
+ */
+import { createServer } from 'node:http';
+import { answer, call, listing } from './serve.js';
+/** How much of a request body is read before it is refused, in bytes. */
+const LIMIT = 1_000_000;
+const body = async (request) => {
+    let read = '';
+    for await (const chunk of request) {
+        read += String(chunk);
+        if (read.length > LIMIT)
+            throw new Error('That request is too big.');
+    }
+    return read;
+};
+const send = (response, code, value) => {
+    const text = JSON.stringify(value);
+    response.writeHead(code, {
+        'content-type': 'application/json',
+        'content-length': String(Buffer.byteLength(text)),
+    });
+    response.end(text);
+};
+/**
+ * Whether a request carries the token, where one was set.
+ *
+ * `Authorization: Bearer <token>`, which is what MCP's own HTTP transport
+ * says, and what every client that speaks it already sends.
+ */
+const allowed = (request, token) => {
+    if (token === undefined)
+        return true;
+    const said = request.headers.authorization;
+    return typeof said === 'string' && said.trim() === `Bearer ${token}`;
+};
+/** Start listening. Answers once the socket is up. */
+export async function serve(host, options) {
+    const server = createServer((request, response) => {
+        void (async () => {
+            try {
+                const url = new URL(request.url ?? '/', `http://${request.headers.host ?? 'localhost'}`);
+                const path = url.pathname.replace(/\/+$/, '') || '/';
+                if (!allowed(request, options.token)) {
+                    send(response, 401, { error: 'This server needs a bearer token.' });
+                    return;
+                }
+                // What is here, for somebody who has just started it and wants to know
+                // what to call. Every tool with its schema, which is also what an MCP
+                // client gets from `tools/list`.
+                if (request.method === 'GET' && (path === '/api' || path === '/')) {
+                    send(response, 200, listing());
+                    return;
+                }
+                if (path === '/mcp') {
+                    if (request.method !== 'POST') {
+                        // No SSE stream: this server sends nothing a client did not ask
+                        // for, so there is nothing for a GET to hold open.
+                        send(response, 405, { error: 'POST a JSON-RPC message here.' });
+                        return;
+                    }
+                    let message;
+                    try {
+                        message = JSON.parse(await body(request));
+                    }
+                    catch {
+                        send(response, 400, { jsonrpc: '2.0', id: null, error: { code: -32700, message: 'That is not JSON.' } });
+                        return;
+                    }
+                    const reply = await answer(host, message, options);
+                    // A notification is answered with 202 and no body, which is what the
+                    // transport says and what a client waiting on one would hang over.
+                    if (reply === undefined) {
+                        response.writeHead(202);
+                        response.end();
+                        return;
+                    }
+                    send(response, 200, reply);
+                    return;
+                }
+                if (path.startsWith('/api/')) {
+                    if (request.method !== 'POST') {
+                        send(response, 405, { error: 'POST to call a tool.' });
+                        return;
+                    }
+                    const name = path.slice('/api/'.length);
+                    const raw = await body(request);
+                    let input = {};
+                    if (raw.trim() !== '') {
+                        try {
+                            input = JSON.parse(raw);
+                        }
+                        catch {
+                            send(response, 400, { error: 'That is not JSON.' });
+                            return;
+                        }
+                    }
+                    const result = await call(host, name, input);
+                    // Shaped for a program rather than for a model: the answer itself,
+                    // or the refusal as an error, without MCP's content envelope around
+                    // it. A caller that wants the envelope has `/mcp`.
+                    if (result.isError === true) {
+                        send(response, 400, { error: result.content?.[0]?.text ?? 'That did not work.' });
+                        return;
+                    }
+                    send(response, 200, result.structuredContent ?? {});
+                    return;
+                }
+                send(response, 404, { error: `Nothing at ${path}. Try GET /api.` });
+            }
+            catch (error) {
+                options.onProblem?.(error instanceof Error ? error.message : String(error));
+                if (!response.headersSent)
+                    send(response, 500, { error: 'Something went wrong here.' });
+                else
+                    response.end();
+            }
+        })();
+    });
+    await new Promise((up, fail) => {
+        server.once('error', fail);
+        server.listen(options.port, options.host, () => { server.off('error', fail); up(); });
+    });
+    const found = server.address();
+    return {
+        host: typeof found === 'object' && found !== null ? found.address : options.host,
+        port: typeof found === 'object' && found !== null ? found.port : options.port,
+        close: () => new Promise((done) => { server.close(() => done()); }),
+    };
+}