@ahpd/server 0.3.0 → 0.5.0

package/README.md

@@ -1,5 +1,11 @@
 # @ahpd/server
 
+[![npm](https://img.shields.io/npm/v/%40ahpd%2Fserver)](https://www.npmjs.com/package/@ahpd/server)
+[![CI](https://github.com/softov/ahpd/actions/workflows/ci.yml/badge.svg)](https://github.com/softov/ahpd/actions/workflows/ci.yml)
+![license MIT](https://img.shields.io/badge/license-MIT-blue)
+![node >=22](https://img.shields.io/badge/node-%3E%3D22-5fa04e)
+![Agent Host Protocol 0.9.0](https://img.shields.io/badge/AHP-0.9.0-0b7285)
+
 [`@ahpd/server`](https://www.npmjs.com/package/@ahpd/server) is a ready-to-run [Agent Host Protocol](https://microsoft.github.io/agent-host-protocol/) server. It installs the `ahpd` command.
 
 It runs agent sessions and serves them over a WebSocket, so several clients can watch and drive the same session at once.
@@ -53,9 +59,11 @@ ahpd config                 print the config file path and its contents
 | `--without-connection-token` | Accept any connection |
 | `--config-file <p>` | Use this config file instead of the default |
 | `--automations <where>` | `file`, the default, keeps them beside the config and fires their schedules. `memory` keeps them until the process ends and fires nothing |
+| `--sessions <where>` | Where the read and archived bits and a session's settings go. `file`, the default, keeps them beside the config. `memory` forgets them when the process ends |
+| `--version`, `-v` | What version this is |
 | `--help`, `-h` | |
 
-Every flag also has a key in `config.json` under `$XDG_CONFIG_HOME/ahpd`, spelled the same way without the dashes. A flag beats the file. Run `ahpd config` to see the path and the current values.
+`--version` and `--help` are the two that are not configuration; every other flag also has a key in `config.json` under `$XDG_CONFIG_HOME/ahpd`, spelled the same way without the dashes. A flag beats the file. Run `ahpd config` to see the path and the current values.
 
 ## Directories
 

package/dist/config.d.ts

@@ -20,6 +20,13 @@ export interface Config {
      * definitions for the life of the process and fires nothing.
      */
     automations?: 'file' | 'memory';
+    /**
+     * Where the read and archived bits and a session's settings are kept: `file`
+     * beside this configuration, or `memory` until the process ends.
+     */
+    sessions?: 'file' | 'memory';
+    /** A file every frame is appended to, both directions, as JSON lines. */
+    wire?: string;
 }
 /**
  * Where this tool's files live.
@@ -59,6 +66,15 @@ export declare const daemonLog: () => string;
  * and the ordering somebody put there.
  */
 export declare const automationsPath: () => string;
+/**
+ * Where what this host adds on top of a backend is kept.
+ *
+ * The `IsRead` and `IsArchived` bits every client shares, and the settings a
+ * session is running under. Beside the automations for the same reason: this
+ * one is written whenever somebody archives a row, and `config.json` is a file
+ * a person edits.
+ */
+export declare const sessionsPath: () => string;
 /** Make sure the directory is there, so a write into it can succeed. */
 export declare const ensureConfigDir: () => void;
 /**

package/dist/config.js

@@ -40,6 +40,15 @@ export const daemonLog = () => join(configDir(), 'daemon.log');
  * and the ordering somebody put there.
  */
 export const automationsPath = () => join(configDir(), 'automations.json');
+/**
+ * Where what this host adds on top of a backend is kept.
+ *
+ * The `IsRead` and `IsArchived` bits every client shares, and the settings a
+ * session is running under. Beside the automations for the same reason: this
+ * one is written whenever somebody archives a row, and `config.json` is a file
+ * a person edits.
+ */
+export const sessionsPath = () => join(configDir(), 'sessions.json');
 /** Make sure the directory is there, so a write into it can succeed. */
 export const ensureConfigDir = () => { mkdirSync(configDir(), { recursive: true }); };
 /**

package/dist/main.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
-import { automationsPath, configPath, loadConfig } from './config.js';
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { automationsPath, configPath, daemonLog, loadConfig, sessionsPath } from './config.js';
+import { version } from './version.js';
 import { running, start, stop as stopDaemon } from './daemon.js';
 import { pty } from './pty.js';
 import { claude } from '@ahpd/agent-claude';
-import { createHost, fileResources, gitBranches, gitChanges, gitWorktrees, hostTools, listen, memoryAutomations, scheduledAutomations, shellTerminals } from '@ahpd/sdk';
+import { createHost, fileResources, gitBranches, gitChanges, gitWorktrees, githubPullRequests, hostTools, listen, fileSessions, memoryAutomations, memorySessions, scheduledAutomations, shellTerminals } from '@ahpd/sdk';
 const USAGE = `ahpd - an Agent Host Protocol server, with a Claude backend
 
   ahpd [options]              run it here, in this terminal
@@ -30,11 +31,20 @@ const USAGE = `ahpd - an Agent Host Protocol server, with a Claude backend
                                 configuration and fires their schedules;
                                 memory keeps them until this process ends and
                                 fires nothing.
+  --sessions <where>            Where the read and archived bits and a
+                                session's settings go. file, the default,
+                                keeps them beside the configuration; memory
+                                forgets them when this process ends.
+  --wire <file>                 Append every frame, both directions, to this
+                                file as JSON lines: { at, from, peer, frame }.
+                                pnpm wire -- <file> checks it against the
+                                protocol schema.
+  --version, -v                 What version this is
   --help, -h                    This
 
 Every option above can be a key in the configuration file instead, spelled the
 way it is here without the dashes: port, host, paths, connectionToken,
-connectionTokenFile, withoutConnectionToken, automations. A flag beats the file, because a
+connectionTokenFile, withoutConnectionToken, automations, sessions, wire. A flag beats the file, because a
 flag is this run and a file is every run until somebody edits it.
 
 Clients present the token as ?tkn=<secret> on the URL, or as an
@@ -49,8 +59,10 @@ function parse(argv) {
         host: '127.0.0.1',
         paths: [],
         automations: 'file',
+        sessions: 'file',
         open: false,
         help: false,
+        version: false,
     };
     for (let i = 0; i < argv.length; i++) {
         switch (argv[i]) {
@@ -88,10 +100,25 @@ function parse(argv) {
                     stop(`--automations takes file or memory, not ${said}.`);
                 break;
             }
+            case '--sessions': {
+                const said = String(argv[++i]);
+                if (said === 'file' || said === 'memory')
+                    options.sessions = said;
+                else
+                    stop(`--sessions takes file or memory, not ${said}.`);
+                break;
+            }
+            case '--wire':
+                options.wire = String(argv[++i]);
+                break;
             case '--help':
             case '-h':
                 options.help = true;
                 break;
+            case '--version':
+            case '-v':
+                options.version = true;
+                break;
             default:
                 if (argv[i]?.startsWith('-')) {
                     process.stderr.write(`Unknown option ${argv[i]}. Try --help.\n`);
@@ -124,6 +151,11 @@ function parse(argv) {
     if (!argv.includes('--automations') && (file.automations === 'file' || file.automations === 'memory')) {
         options.automations = file.automations;
     }
+    if (!argv.includes('--sessions') && (file.sessions === 'file' || file.sessions === 'memory')) {
+        options.sessions = file.sessions;
+    }
+    if (!argv.includes('--wire') && typeof file.wire === 'string')
+        options.wire = file.wire;
     if (options.paths.length === 0)
         options.paths.push(process.cwd());
     return options;
@@ -238,6 +270,10 @@ if (verb !== undefined) {
     process.exit(2);
 }
 const options = parse(argv);
+if (options.version) {
+    process.stdout.write(`${version()}\n`);
+    process.exit(0);
+}
 if (options.help) {
     process.stdout.write(USAGE);
     process.exit(0);
@@ -271,6 +307,7 @@ const host = createHost({
     directories: gitBranches(),
     changes: gitChanges(),
     worktrees: gitWorktrees(),
+    github: githubPullRequests(),
     /*
      * The host's own tools, offered to every session's model.
      *
@@ -293,6 +330,20 @@ const host = createHost({
      * not told which it was given - a host embedded in something that already
      * schedules passes a third of its own.
      */
+    /*
+     * What this host adds on top of a backend, kept between restarts.
+     *
+     * The bits every client shares and the settings a session runs under. A
+     * daemon is exactly the case the port was written for: it is restarted for
+     * an upgrade, and without this every archived session comes back into the
+     * catalogue and every read one is unread, for everybody, with nothing said.
+     */
+    sessions: options.sessions === 'memory'
+        ? memorySessions()
+        : fileSessions({
+            file: sessionsPath(),
+            onProblem: (message) => process.stdout.write(`${message}\n`),
+        }),
     automations: memory
         ? memoryAutomations()
         : scheduledAutomations({
@@ -316,18 +367,52 @@ const host = createHost({
      * `onEvent` hands it the message to do that with.
      */
     onEvent: (message) => process.stdout.write(`${new Date().toISOString()} ${message}\n`),
+    /*
+     * What the window's diagnostics get from this daemon.
+     *
+     * The version out of the manifest, the log a detached daemon writes to and
+     * the wire capture when there is one, and a shutdown that is the same
+     * signal handler `ahpd stop` reaches through `SIGTERM`.
+     */
+    diagnostics: {
+        version: version(),
+        logs: () => [daemonLog(), ...(options.wire === undefined ? [] : [options.wire])],
+        shutdown: () => { process.kill(process.pid, 'SIGTERM'); },
+    },
 });
 // Whichever runtime this is. `listen` is the only file that knows, and it
 // says which one it found - a daemon that silently ran somewhere unexpected
 // would be a daemon nobody could tell apart from the one they meant to start.
-const listener = await listen({ port: options.port, host: options.host, ...(token !== undefined ? { token } : {}) }, (peer) => host.accept(peer));
+/*
+ * The wire, written down as it happens.
+ *
+ * One line per frame, appended synchronously so the file is whole at the
+ * moment anything else is read: a capture that lags the crash it is meant to
+ * explain is no capture. `frame` is the message parsed, so `jq` reads the
+ * file; a frame that is not JSON is kept as the string it was, because a
+ * client that sent one is exactly what a capture is for.
+ */
+const tap = options.wire === undefined ? undefined : (() => {
+    const at = options.wire;
+    writeFileSync(at, '');
+    return (from, text, peer) => {
+        let frame = text;
+        try {
+            frame = JSON.parse(text);
+        }
+        catch { /* kept as text */ }
+        appendFileSync(at, `${JSON.stringify({ at: new Date().toISOString(), from, peer, frame })}\n`);
+    };
+})();
+const listener = await listen({ port: options.port, host: options.host, ...(token !== undefined ? { token } : {}), ...(tap ? { tap } : {}) }, (peer) => host.accept(peer));
 process.stdout.write(`ahpd on ws://${listener.host}:${listener.port} (${listener.runtime}), sessions in ${options.paths.join(', ')}\n`
     // Its own line rather than the end of the one above, which `daemon.ts`
     // reads the session directories off with a regular expression.
     + `automations ${memory ? 'in memory, schedules do not fire' : `in ${automationsPath()}, schedules fire`}\n`
     // Where the secret came from, never the secret: stdout is a log, and a log
     // is the one place a credential should not end up.
-    + `${from}\n`);
+    + `${from}\n`
+    + (options.wire === undefined ? '' : `wire to ${options.wire}\n`));
 const shutdown = () => {
     void Promise.resolve(listener.close()).finally(() => process.exit(0));
 };

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** The version in the nearest `package.json`, or `unknown` where there is none. */
+export declare const version: () => string;

package/dist/version.js

@@ -0,0 +1,34 @@
+/*
+ * What version this is, read from the manifest rather than written twice.
+ *
+ * A literal in the source is a literal that drifts, and a `--version` that
+ * lies is worse than no `--version` at all.
+ *
+ * Found by walking up from this module rather than by a fixed relative path,
+ * because the depth differs: `src/version.ts` in this checkout and
+ * `dist/version.js` in an install, and neither should have to know which it
+ * is. `package.json` is always at the package root and npm always ships it,
+ * so the first one above this file is the right one - which in a workspace is
+ * this package's rather than the repository's.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** The version in the nearest `package.json`, or `unknown` where there is none. */
+export const version = () => {
+    let at = dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        try {
+            const found = JSON.parse(readFileSync(join(at, 'package.json'), 'utf8'));
+            if (typeof found.version === 'string')
+                return found.version;
+        }
+        catch { /* not this directory */ }
+        const up = dirname(at);
+        // The root of the filesystem, which means there is no manifest anywhere
+        // above this file - a bundler inlined it, or something unpacked it wrong.
+        if (up === at)
+            return 'unknown';
+        at = up;
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahpd/server",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "An Agent Host Protocol server on Node, Bun or Deno. Ships with a Claude backend",
   "keywords": [
@@ -41,8 +41,8 @@
   },
   "dependencies": {
     "@microsoft/agent-host-protocol": "^0.9.0",
-    "@ahpd/agent-claude": "^0.3.0",
-    "@ahpd/sdk": "^0.3.0"
+    "@ahpd/agent-claude": "^0.5.0",
+    "@ahpd/sdk": "^0.5.0"
   },
   "publishConfig": {
     "access": "public"