@ahpd/server 0.2.0 → 0.4.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.
@@ -52,9 +58,12 @@ ahpd config                 print the config file path and its contents
 | `--connection-token-file <p>` | Require the secret in this file. Writes a new one if the file is missing |
 | `--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

@@ -13,6 +13,18 @@ export interface Config {
     connectionTokenFile?: string;
     /** Accept any connection, with no secret at all. */
     withoutConnectionToken?: boolean;
+    /**
+     * Where automations are kept: `file` beside this configuration, or `memory`.
+     *
+     * `file` is the default and is the one with a clock in it. `memory` holds
+     * 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';
 }
 /**
  * Where this tool's files live.
@@ -52,6 +64,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/daemon.d.ts

@@ -5,6 +5,11 @@ export interface Running {
     url: string;
     paths: string[];
     startedAt: string;
+    /**
+     * Where automations are kept and whether their schedules fire, in the
+     * daemon's own words. Absent from a record an older daemon wrote.
+     */
+    automations?: string;
 }
 /**
  * The daemon this user has running, if the record names one that still is.

package/dist/daemon.js

@@ -130,6 +130,7 @@ export async function start(argv, self) {
     // rather than for the case, and `0` must never reach the record.
     if (child.pid === undefined)
         throw new Error('it started but has no process id');
+    const automations = /^automations (.+)$/m.exec(announced)?.[1]?.trim();
     const record = {
         pid: child.pid,
         url,
@@ -139,6 +140,7 @@ export async function start(argv, self) {
         paths: (/sessions in (.+)/.exec(announced)?.[1] ?? '')
             .trim().split(',').map((one) => one.trim()).filter((one) => one !== ''),
         startedAt: new Date().toISOString(),
+        ...(automations !== undefined ? { automations } : {}),
     };
     writeFileSync(daemonPath(), `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
     return record;

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 { automationsPath, configPath, 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, scheduledAutomations, shellTerminals } from '@ahpd/sdk';
+import { createHost, fileResources, gitBranches, gitChanges, gitWorktrees, 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
@@ -26,11 +27,20 @@ const USAGE = `ahpd - an Agent Host Protocol server, with a Claude backend
   --without-connection-token    Accept any connection. Only when the port is
                                 already reachable by nobody else.
   --config-file <p>             Read this instead of the file below.
+  --automations <where>         file, the default, keeps them beside the
+                                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.
+  --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. A flag beats the file, because a
+connectionTokenFile, withoutConnectionToken, automations, sessions. 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
@@ -44,8 +54,11 @@ function parse(argv) {
         port: 9187,
         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]) {
@@ -75,10 +88,30 @@ function parse(argv) {
             case '--config-file':
                 options.configFile = String(argv[++i]);
                 break;
+            case '--automations': {
+                const said = String(argv[++i]);
+                if (said === 'file' || said === 'memory')
+                    options.automations = said;
+                else
+                    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 '--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`);
@@ -108,6 +141,12 @@ function parse(argv) {
         options.tokenFile = file.connectionTokenFile;
     if (!options.open && file.withoutConnectionToken === true)
         options.open = true;
+    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 (options.paths.length === 0)
         options.paths.push(process.cwd());
     return options;
@@ -179,6 +218,8 @@ if (verb !== undefined) {
         try {
             const begun = await start(rest, process.argv[1]);
             process.stdout.write(`ahpd on ${begun.url} (pid ${String(begun.pid)}), sessions in ${begun.paths.join(', ') || process.cwd()}\n`);
+            if (begun.automations !== undefined)
+                process.stdout.write(`automations ${begun.automations}\n`);
             process.exit(0);
         }
         catch (error) {
@@ -200,6 +241,10 @@ if (verb !== undefined) {
         process.stdout.write(`ahpd on ${found.url} (pid ${String(found.pid)}), started ${found.startedAt}\n`);
         if (found.paths.length > 0)
             process.stdout.write(`sessions in ${found.paths.join(', ')}\n`);
+        // Absent from a record written by an older daemon, which is the one case
+        // where saying nothing is better than guessing which store it was given.
+        if (found.automations !== undefined)
+            process.stdout.write(`automations ${found.automations}\n`);
         process.exit(0);
     }
     if (verb === 'config') {
@@ -216,11 +261,24 @@ 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);
 }
 const { token, from } = secret(options);
+/*
+ * Whether a clock is running, decided once and then said out loud.
+ *
+ * Both stores take a schedule trigger and only one of them ever fires it, and
+ * what tells a client which it got is a `nextRunAt` that is simply absent.
+ * That is too quiet for somebody who has just written a schedule, so the
+ * startup line says it in words and `ahpd status` repeats it.
+ */
+const memory = options.automations === 'memory';
 const host = createHost({
     path: options.paths[0],
     // The daemon serves Claude Code. The host serves whatever it is given -
@@ -249,7 +307,7 @@ const host = createHost({
      */
     tools: hostTools(),
     /*
-     * Automations, with a clock.
+     * Automations, with a clock unless asked otherwise.
      *
      * A daemon is the case the port was written for: it is already running at
      * nine in the morning, which is the only way an automation fires with
@@ -257,15 +315,33 @@ const host = createHost({
      * come back on a restart; the runs do not, because they name sessions that
      * went when the process did.
      *
-     * A host embedded in something that already schedules passes its own store
-     * instead, and one that should fire nothing passes `memoryAutomations()`.
+     * `--automations memory` is the same store without either half: nothing is
+     * written and nothing fires. Both are an `AutomationStore`, so the host is
+     * 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.
      */
-    automations: scheduledAutomations({
-        // Beside the configuration, which is this daemon's decision to make and
-        // not the store's - see `ScheduledOptions.file`.
-        file: automationsPath(),
-        onProblem: (message) => process.stdout.write(`${message}\n`),
-    }),
+    sessions: options.sessions === 'memory'
+        ? memorySessions()
+        : fileSessions({
+            file: sessionsPath(),
+            onProblem: (message) => process.stdout.write(`${message}\n`),
+        }),
+    automations: memory
+        ? memoryAutomations()
+        : scheduledAutomations({
+            // Beside the configuration, which is this daemon's decision to make and
+            // not the store's - see `ScheduledOptions.file`.
+            file: automationsPath(),
+            onProblem: (message) => process.stdout.write(`${message}\n`),
+        }),
     /*
      * When, as well as what.
      *
@@ -287,6 +363,9 @@ const host = createHost({
 // 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));
 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`);

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.2.0",
+  "version": "0.4.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.2.0",
-    "@ahpd/sdk": "^0.2.0"
+    "@ahpd/agent-claude": "^0.4.0",
+    "@ahpd/sdk": "^0.4.0"
   },
   "publishConfig": {
     "access": "public"