@softov/ahpc 0.2.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)
@@ -214,8 +215,8 @@ Writes are guarded by the file's etag unless you pass `--force`, so two clients
 
 | 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` |
+| `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
 
@@ -223,6 +224,7 @@ Writes are guarded by the file's etag unless you pass `--force`, so two clients
 |---|---|---|
 | `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
@@ -252,10 +254,37 @@ 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/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/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                               /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";
+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

@@ -6,7 +6,7 @@ import { ago, archived, branch, json, line, mark, project, table } from './rende
 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 { 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';
@@ -112,11 +112,16 @@ Serving these sessions to something else
                                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
@@ -331,22 +336,27 @@ export async function cli(command, rest) {
              * `/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)'}, ${TOOLS.length} tools\n`);
-                await stdio(host, { ...SERVER, onProblem: (said) => process.stderr.write(`${said}\n`) });
+                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, ${TOOLS.length} tools`);
+                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
@@ -997,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';

package/dist/src/flags.js

@@ -41,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',

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.
      *

package/dist/src/mcp/http.d.ts

@@ -12,6 +12,16 @@ export interface ServeOptions {
      * token is what makes binding anywhere else defensible.
      */
     token?: string;
+    /**
+     * Browser origins allowed to reach this, beyond its own.
+     *
+     * Empty is the safe default and the usual answer: a shell script, a webhook
+     * and an MCP client send no `Origin` at all, so nothing legitimate is turned
+     * away by allowing none. This is for a page somebody serves themselves.
+     */
+    origins?: readonly string[];
+    /** The opt-in tool groups to serve, beyond the core table. */
+    groups?: readonly string[];
     onProblem?(said: string): void;
 }
 /** What this is listening on, and how to stop it. */

package/dist/src/mcp/http.js

@@ -12,7 +12,7 @@
  * client that launched it, this is shared and outlives any of them.
  */
 import { createServer } from 'node:http';
-import { answer, call, listing } from './serve.js';
+import { SPOKEN, 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) => {
@@ -24,6 +24,39 @@ const body = async (request) => {
     }
     return read;
 };
+/**
+ * Answer a request with a stream rather than one object.
+ *
+ * The transport allows either, and this is the branch that lets anything be
+ * said before the result: notifications go out as they happen and the response
+ * is the last event, after which the stream closes. Only opened where the
+ * caller asked for progress, because a stream is worse for everybody else -
+ * more to parse, and a connection held open for a request that answers at once.
+ */
+const stream = (response) => {
+    response.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache, no-transform',
+        connection: 'keep-alive',
+    });
+    const event = (value) => { response.write(`data: ${JSON.stringify(value)}\n\n`); };
+    return {
+        event,
+        end: (value) => { event(value); response.end(); },
+    };
+};
+/**
+ * Whether this request asked to be told what is happening while it waits.
+ *
+ * A `progressToken` in `_meta`, which is the only way a caller asks. Read here
+ * rather than inside `answer`, because the decision it drives - a stream or an
+ * object - has to be made before a single byte of the response is written.
+ */
+const wantsProgress = (message) => {
+    const params = message.params;
+    const token = params?._meta?.progressToken;
+    return typeof token === 'string' || typeof token === 'number';
+};
 const send = (response, code, value) => {
     const text = JSON.stringify(value);
     response.writeHead(code, {
@@ -44,6 +77,52 @@ const allowed = (request, token) => {
     const said = request.headers.authorization;
     return typeof said === 'string' && said.trim() === `Bearer ${token}`;
 };
+/**
+ * Whether a browser may talk to this.
+ *
+ * The transport says a server **MUST** validate `Origin` to stop DNS
+ * rebinding, and the reason it says so is that binding to loopback is not the
+ * protection it looks like: a page on any website can POST to
+ * `http://127.0.0.1:7431` from inside the browser of the person running this,
+ * and the request arrives from their own machine looking exactly like theirs.
+ * Without this, opening a tab would be enough to drive every session on the
+ * host.
+ *
+ * No header at all is allowed. A browser always sends one on a request like
+ * these; a program does not, and refusing those would refuse every real
+ * caller to guard against a thing that cannot happen.
+ */
+const sameOrigin = (request, url, extra) => {
+    const said = request.headers.origin;
+    if (typeof said !== 'string' || said === '')
+        return true;
+    if (extra.includes(said))
+        return true;
+    try {
+        const from = new URL(said);
+        // The host and port this request came in on, whatever name was used to
+        // reach it - `localhost` and `127.0.0.1` are the same server and a person
+        // typing either should not be told no.
+        return from.host === url.host;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Whether this can speak the version the client says it is using.
+ *
+ * The transport says an invalid or unsupported `MCP-Protocol-Version` **MUST**
+ * be a 400. Absent is not unsupported: the same paragraph says to assume
+ * `2025-03-26` where there is no header, which is a client from before it
+ * existed.
+ */
+const speakable = (request) => {
+    const said = request.headers['mcp-protocol-version'];
+    if (said === undefined)
+        return true;
+    return typeof said === 'string' && SPOKEN.includes(said);
+};
 /** Start listening. Answers once the socket is up. */
 export async function serve(host, options) {
     const server = createServer((request, response) => {
@@ -51,6 +130,18 @@ export async function serve(host, options) {
             try {
                 const url = new URL(request.url ?? '/', `http://${request.headers.host ?? 'localhost'}`);
                 const path = url.pathname.replace(/\/+$/, '') || '/';
+                if (!sameOrigin(request, url, options.origins ?? [])) {
+                    // 403 rather than 401: a token would not make this request
+                    // acceptable, so inviting one would be the wrong thing to say.
+                    send(response, 403, { error: `This server does not serve requests from ${String(request.headers.origin)}.` });
+                    return;
+                }
+                if (!speakable(request)) {
+                    send(response, 400, {
+                        error: `This server does not speak MCP ${String(request.headers['mcp-protocol-version'])}. It speaks ${SPOKEN.join(', ')}.`,
+                    });
+                    return;
+                }
                 if (!allowed(request, options.token)) {
                     send(response, 401, { error: 'This server needs a bearer token.' });
                     return;
@@ -59,7 +150,7 @@ export async function serve(host, options) {
                 // 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());
+                    send(response, 200, listing(options.groups));
                     return;
                 }
                 if (path === '/mcp') {
@@ -77,6 +168,22 @@ export async function serve(host, options) {
                         send(response, 400, { jsonrpc: '2.0', id: null, error: { code: -32700, message: 'That is not JSON.' } });
                         return;
                     }
+                    if (wantsProgress(message)) {
+                        const open = stream(response);
+                        const reply = await answer(host, message, {
+                            ...options,
+                            notify: (notification) => open.event({ jsonrpc: '2.0', ...notification }),
+                        });
+                        // A notification that also carried a progress token has nothing to
+                        // end the stream with, so it is closed rather than left open on a
+                        // response that is never coming.
+                        if (reply === undefined) {
+                            response.end();
+                            return;
+                        }
+                        open.end(reply);
+                        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.
@@ -105,7 +212,7 @@ export async function serve(host, options) {
                             return;
                         }
                     }
-                    const result = await call(host, name, input);
+                    const result = await call(host, name, input, undefined, options.groups);
                     // 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`.

package/dist/src/mcp/serve.d.ts

@@ -1,17 +1,26 @@
 import type { HostConnection } from '../ahp/connection.js';
-/** The version of MCP this speaks, and the one it answers `initialize` with. */
+/** The newest version of MCP this speaks, and what it answers an unknown one with. */
 export declare const PROTOCOL = "2025-06-18";
+/**
+ * Every version this will serve, newest first.
+ *
+ * Both of these describe the same tools, and this server uses nothing either
+ * of them added or removed - no sessions, no resources, no sampling - so
+ * refusing the older one would be refusing a client for a difference that
+ * cannot reach it. `2024-11-05` is *not* here: its HTTP transport is a
+ * different shape, with an `endpoint` event and a second URL.
+ */
+export declare const SPOKEN: readonly string[];
 /**
  * What this server calls itself.
  *
- * MCP requires a version where AHP's `clientInfo` does not, so this is the
- * only version string in the source. Cosmetic - a client displays it and
- * nothing branches on it - and deliberately not read out of `package.json`,
- * which sits at a different depth in the published tree than it does here.
+ * MCP requires a version where AHP's `clientInfo` does not. Read from the
+ * manifest rather than written here: the literal that used to be here said
+ * 0.1 while the package said 0.2, within a day of being written.
  */
 export declare const SERVER: {
-    readonly name: "ahpc";
-    readonly version: "0.1";
+    name: string;
+    version: string;
 };
 /** A JSON-RPC request or notification, as far as this needs to read one. */
 export interface Incoming {
@@ -20,6 +29,21 @@ export interface Incoming {
     method?: unknown;
     params?: unknown;
 }
+/**
+ * One progress notification, as `notifications/progress` puts it on the wire.
+ *
+ * `progress` MUST increase on every one, `total` is left out because an
+ * agent's reply has no length known in advance, and `message` is what a person
+ * reads - which is the tool name a session stopped on, or the host's own words
+ * for what it is doing.
+ */
+export interface Progress {
+    progressToken: string | number;
+    progress: number;
+    message?: string;
+}
+/** Somewhere to put progress while a tool runs, or nothing where nobody asked. */
+export type Report = ((said: string) => void) | undefined;
 /** What goes back, or nothing at all where the message was a notification. */
 export type Outgoing = {
     jsonrpc: '2.0';
@@ -35,7 +59,7 @@ export type Outgoing = {
     result?: never;
 });
 /** The tools, in the shape `tools/list` puts them on the wire. */
-export declare const listing: () => unknown;
+export declare const listing: (groups?: readonly string[]) => unknown;
 /**
  * Run one tool and shape the answer the way `tools/call` wants it.
  *
@@ -45,7 +69,7 @@ export declare const listing: () => unknown;
  * fault it can only give up over. So a refusal from the host - a session that
  * is gone, a directory it does not serve - comes back as content.
  */
-export declare function call(host: HostConnection, name: string, input: unknown): Promise<unknown>;
+export declare function call(host: HostConnection, name: string, input: unknown, report?: Report, groups?: readonly string[]): Promise<unknown>;
 /**
  * Answer one message.
  *
@@ -55,4 +79,18 @@ export declare function call(host: HostConnection, name: string, input: unknown)
 export declare function answer(host: HostConnection, message: Incoming, options: {
     name: string;
     version: string;
+    /** The opt-in tool groups this server was started with, if any. */
+    groups?: readonly string[];
+    /**
+     * Somewhere to send a notification while this is being answered.
+     *
+     * Given by a transport that has one: stdio always does, and HTTP does only
+     * once it has decided to answer with a stream. Absent means there is
+     * nowhere to say anything until the result, which is the ordinary case and
+     * why every progress path here is optional.
+     */
+    notify?(notification: {
+        method: string;
+        params: unknown;
+    }): void;
 }): Promise<Outgoing | undefined>;