@ahpd/server 0.1.0 → 0.2.0

package/README.md

@@ -1,127 +1,133 @@
 # @ahpd/server
 
-A server library for the [Agent Host Protocol](https://github.com/microsoft/agent-host-protocol).
+[`@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 has no agent in it. You pass one in when you create the host.
+It runs agent sessions and serves them over a WebSocket, so several clients can watch and drive the same session at once.
+
+It is built on [@ahpd/sdk](https://www.npmjs.com/package/@ahpd/sdk) and currently ships with a Claude agent backend, which is the only one so far.
+
+- [`@ahpd/agent-claude`](https://www.npmjs.com/package/@ahpd/agent-claude) is the Claude backend.
+
+Backends are registered at startup, so adding another does not change the server.
+
+To serve a different agent, you can write your own server with [@ahpd/sdk](https://www.npmjs.com/package/@ahpd/sdk). Create an implementation of the `Agent` interface and pass it to `createHost`.
 
 ## Install
 
 ```bash
-pnpm add @ahpd/server @microsoft/agent-host-protocol
+npm i -g @ahpd/server
+ahpd --path /work/project
 ```
 
-The protocol package is a peer dependency. This package uses runtime values from it, so there should only be one copy in the dependency tree.
+Or run it without installing:
 
-## Use
+```bash
+npx @ahpd/server --path /work/project
+```
 
-A small host using the Claude backend looks like this:
+It listens on `ws://127.0.0.1:9187`. Run it with no arguments to serve the directory you are in.
 
-```ts
-import { createHost, listen } from '@ahpd/server';
-import { claude } from '@ahpd/agent-claude';
+Needs Node 22 or later. Also runs on Bun and Deno.
 
-const host = createHost({
-  path: process.cwd(),
-  agents: [claude({ paths: [process.cwd()] })],
-});
+## Commands
 
-const listener = await listen({ port: 9187 }, (peer) => host.accept(peer));
-console.log(`on ws://${listener.host}:${listener.port} (${listener.runtime})`);
+```
+ahpd [options]              run it in this terminal
+ahpd start [options]        run it in the background
+ahpd stop                   stop the background one
+ahpd status                 say whether one is running, and where
+ahpd config                 print the config file path and its contents
 ```
 
-`createHost()` creates the AHP host.
+`start` re-runs the same program detached. It writes its output to `daemon.log` and records the pid and URL in `daemon.json`, both next to the config, which is where `status` reads from and how you find out what happened after the fact.
 
-`listen()` is the WebSocket listener included for Node, Bun and Deno. The host itself is not tied to WebSockets.
+## Options
 
-Once a client is connected, the host takes care of version negotiation, snapshots, subscriptions, sequence numbers, transcript paging, completions, queued messages, shared drafts, read and archived flags, multiple chats per session, and turns.
+| flag | |
+| --- | --- |
+| `--port <n>` | Default `9187`. Use `0` for a free port |
+| `--host <addr>` | Default `127.0.0.1`. Use `0.0.0.0` to accept remote connections, which requires a token |
+| `--path <dir>` | A directory to serve. Repeatable. Defaults to the working directory |
+| `--connection-token <secret>` | Require this secret on every connection |
+| `--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 |
+| `--help`, `-h` | |
 
-`accept(peer)` takes anything that can `send`, `notify` and `close`, and returns a handler. `listen` is a WebSocket implementation for Node, Bun and Deno. Tests supply their own, which is why the test suite runs without a network.
+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.
 
-## Options
+## Directories
 
-`path` and `agents` are required. The rest are optional. If you leave one out, the host returns an error for the commands it cannot serve instead of an empty result.
+`--path` is repeatable:
 
+```bash
+ahpd --path ~/src/project-a --path ~/src/project-b
+```
 
-```ts
-import { 
-  createHost, 
-  fileResources, 
-  shellTerminals, 
-  gitChanges, 
-  gitBranches, 
-  gitWorktrees, 
-  hostTools, 
-  scheduledAutomations,
-} from '@ahpd/server'; 
-
-const host = createHost({ 
-  path, 
-  agents, 
-  resources: fileResources(), 
-  terminals: shellTerminals(), 
-  changes: gitChanges(), 
-  directories: gitBranches(), 
-  worktrees: gitWorktrees(), 
-  tools: hostTools(), 
-  automations: scheduledAutomations({ file: './automations.json', }),
-});
+The first is the default, and it is what a client gets when it names no directory. A directory that was not named is refused rather than served, so one daemon serves exactly the paths you gave it.
+
+## Remote connections
 
+It binds to loopback and needs no token there. Binding anywhere else does:
+
+```bash
+ahpd --host 0.0.0.0 --connection-token <secret>
 ```
 
-| option | |
-| --- | --- |
-| `path` | the directory whose sessions this host serves |
-| `agents` | the backends to serve, as `Agent` implementations |
-| `resources` | file reads, writes, and `@` completion. Use `fileResources()` |
-| `terminals` | a shell as a terminal channel. Use `shellTerminals()` |
-| `changes` | uncommitted changes as a changeset. Use `gitChanges()` |
-| `directories` | the current branch of each served directory. Use `gitBranches()` |
-| `automations` | triggered agents. Use `memoryAutomations()`, or `scheduledAutomations({ file })` for cron |
-| `worktrees` | sessions in their own git worktree. Use `gitWorktrees()` |
-| `tools` | tools the host adds to every session. Use `hostTools()` |
-| `onEvent` | called with one line per notable event, for logging |
+Or keep the secret in a file, which is written with a fresh one if it is not there yet:
+
+```bash
+ahpd --host 0.0.0.0 --connection-token-file ~/.config/ahpd/token
+```
 
-None of these are imported by the host itself. `fileResources` reads files, `shellTerminals` spawns shells, and `gitBranches` runs `git`, and you pass them in.
+Clients present it as `?tkn=<secret>` on the URL or as an `Authorization: Bearer <secret>` header.
 
-## Writing a backend
+`--without-connection-token` binds without one. Only do that when something else is already keeping the port to yourself.
 
-`Agent` has five required members: `provider`, `displayName`, `schema`, `defaults` and `create`.
+## What it serves
 
-```ts
-import type { Agent, Session, Start } from '@ahpd/server';
-
-export function parrot(): Agent {
-  return {
-    provider: 'parrot',
-    displayName: 'Parrot',
-    schema: () => ({ properties: {} }),
-    defaults: () => ({}),
-    create: (start: Start): Session => converse(start),
-  };
-}
+Sessions, chats and turns with streaming responses, tool calls and approvals, questions from the agent, file reads and writes, a shell as a terminal channel, git branches and changesets, sessions in their own worktree, scheduled automations, and OTLP telemetry.
+
+The Claude backend adds what Claude has: models and effort, permission modes, skills and slash commands, MCP servers, and OAuth sign-in.
+
+With the Claude backend, past sessions are read from Claude's transcript files. Opening one does not start anything. The agent process starts when you send a turn.
+
+## Connecting
+
+Any AHP client works. [`ahpc`](https://github.com/softov/ahpc) is one:
+
+```bash
+ahpc --host ws://127.0.0.1:9187
 ```
 
-`provider` is the id a client names in `createSession`. It has to be unique among the agents one host was given.
+## Packages
 
-`schema()` says what a session of this kind can be configured with, and `defaults()` says where those keys start. Both can be empty.
+`@ahpd/server` is a thin wrapper over two libraries:
 
-`create()` returns the session. The session holds the state of the session and chat channels, and calls `start.emit('chat', ...)` as things happen.
+- [`@ahpd/sdk`](https://www.npmjs.com/package/@ahpd/sdk) is the protocol and the ports. It has no backend in it.
+- [`@ahpd/agent-claude`](https://www.npmjs.com/package/@ahpd/agent-claude) is the Claude backend.
 
-Pass it to the host like any other backend: `createHost({ path, agents: [parrot()] })`. Your backend and [`@ahpd/agent-claude`](https://www.npmjs.com/package/@ahpd/agent-claude) register identically and can run side by side.
+The daemon is those two and a socket:
 
-See [docs/AGENT.md](https://github.com/softov/ahpd/blob/main/docs/AGENT.md) for the contract, and [examples/echo](https://github.com/softov/ahpd/tree/main/examples/echo) for a working backend in about two hundred lines.
+```ts
+import { createHost, listen } from '@ahpd/sdk';
+import { claude } from '@ahpd/agent-claude';
 
-## Types
+const host = createHost({ path, agents: [claude({ paths: [path] })] });
+await listen({ port: 9187 }, (peer) => host.accept(peer));
+```
 
-All types are exported. Nothing under `types/` imports a runtime value, so you can read the contract without loading the implementation.
+If you want a host of a different shape, build it from `@ahpd/sdk` and skip this package. To serve a different agent, write an `Agent` and add it to `agents`. See [docs/AGENT.md](https://github.com/softov/ahpd/blob/main/docs/AGENT.md).
 
 ## Documentation
 
 | | |
 | --- | --- |
-| [LIBRARY.md](https://github.com/softov/ahpd/blob/main/docs/LIBRARY.md) | `createHost` and the ports in full |
-| [AGENT.md](https://github.com/softov/ahpd/blob/main/docs/AGENT.md) | The `Agent` and `Session` contracts |
-| [AHP.md](https://github.com/softov/ahpd/blob/main/docs/AHP.md) | Protocol coverage action by action |
+| [DAEMON.md](https://github.com/softov/ahpd/blob/main/docs/DAEMON.md) | The CLI, config file, connection tokens, and Node/Bun/Deno |
+| [LIBRARY.md](https://github.com/softov/ahpd/blob/main/docs/LIBRARY.md) | Building a host with `@ahpd/sdk` |
+| [AGENT.md](https://github.com/softov/ahpd/blob/main/docs/AGENT.md) | Writing another agent backend |
+| [AHP.md](https://github.com/softov/ahpd/blob/main/docs/AHP.md) | Protocol coverage, and every action it emits |
+| [agent-host-protocol](https://github.com/microsoft/agent-host-protocol) | The protocol itself, and its [documentation](https://microsoft.github.io/agent-host-protocol/) |
 
 ## License
 

package/dist/config.d.ts

@@ -0,0 +1,65 @@
+/** What this daemon was told before anybody typed a flag, and where it is. */
+/** What a config file may say. Every key is what a flag would have said. */
+export interface Config {
+    /** TCP port to bind. 0 lets the OS choose. */
+    port?: number;
+    /** Address to bind. */
+    host?: string;
+    /** The directories whose sessions this host serves. */
+    paths?: string[];
+    /** The secret every connection must present. */
+    connectionToken?: string;
+    /** A file holding that secret, written with a fresh one if absent. */
+    connectionTokenFile?: string;
+    /** Accept any connection, with no secret at all. */
+    withoutConnectionToken?: boolean;
+}
+/**
+ * Where this tool's files live.
+ *
+ * XDG, and the environment variable before the fallback: `$XDG_CONFIG_HOME` is
+ * what somebody sets when their configuration is not in `~/.config`, and a
+ * tool that reads the fallback anyway is a tool that ignores them.
+ */
+export declare const configHome: () => string;
+/** The directory this tool owns inside it. */
+export declare const configDir: () => string;
+/** The file a person edits. */
+export declare const configPath: () => string;
+/**
+ * Where a detached daemon records itself.
+ *
+ * Beside the configuration rather than in a runtime directory, so everything
+ * about this tool is in one place a person can look at. It is written by the
+ * daemon and not by hand, which is the one thing that makes it different from
+ * its neighbour.
+ */
+export declare const daemonPath: () => string;
+/**
+ * Where a detached daemon's output goes.
+ *
+ * It has to go somewhere real. A background process whose stdout is a pipe
+ * dies the moment the thing holding the other end exits, and one whose stdout
+ * is discarded leaves nothing to read when it misbehaves.
+ */
+export declare const daemonLog: () => string;
+/**
+ * Where automations are kept.
+ *
+ * Beside the configuration and not inside it: `config.json` is a file a person
+ * edits and this one is written by the daemon every time somebody adds an
+ * automation, and a tool that rewrites a hand-edited file loses the comments
+ * and the ordering somebody put there.
+ */
+export declare const automationsPath: () => string;
+/** Make sure the directory is there, so a write into it can succeed. */
+export declare const ensureConfigDir: () => void;
+/**
+ * Read it, or answer that there was nothing to read.
+ *
+ * A file that is not there is not an error - most people have none. One that
+ * is there and is broken *is* one, and says so rather than starting on
+ * defaults nobody chose: silently ignoring a configuration somebody wrote is
+ * worse than refusing to start.
+ */
+export declare function loadConfig(named?: string): Config;

package/dist/config.js

@@ -0,0 +1,75 @@
+/** What this daemon was told before anybody typed a flag, and where it is. */
+import { mkdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Where this tool's files live.
+ *
+ * XDG, and the environment variable before the fallback: `$XDG_CONFIG_HOME` is
+ * what somebody sets when their configuration is not in `~/.config`, and a
+ * tool that reads the fallback anyway is a tool that ignores them.
+ */
+export const configHome = () => process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+/** The directory this tool owns inside it. */
+export const configDir = () => join(configHome(), 'ahpd');
+/** The file a person edits. */
+export const configPath = () => join(configDir(), 'config.json');
+/**
+ * Where a detached daemon records itself.
+ *
+ * Beside the configuration rather than in a runtime directory, so everything
+ * about this tool is in one place a person can look at. It is written by the
+ * daemon and not by hand, which is the one thing that makes it different from
+ * its neighbour.
+ */
+export const daemonPath = () => join(configDir(), 'daemon.json');
+/**
+ * Where a detached daemon's output goes.
+ *
+ * It has to go somewhere real. A background process whose stdout is a pipe
+ * dies the moment the thing holding the other end exits, and one whose stdout
+ * is discarded leaves nothing to read when it misbehaves.
+ */
+export const daemonLog = () => join(configDir(), 'daemon.log');
+/**
+ * Where automations are kept.
+ *
+ * Beside the configuration and not inside it: `config.json` is a file a person
+ * edits and this one is written by the daemon every time somebody adds an
+ * automation, and a tool that rewrites a hand-edited file loses the comments
+ * and the ordering somebody put there.
+ */
+export const automationsPath = () => join(configDir(), 'automations.json');
+/** Make sure the directory is there, so a write into it can succeed. */
+export const ensureConfigDir = () => { mkdirSync(configDir(), { recursive: true }); };
+/**
+ * Read it, or answer that there was nothing to read.
+ *
+ * A file that is not there is not an error - most people have none. One that
+ * is there and is broken *is* one, and says so rather than starting on
+ * defaults nobody chose: silently ignoring a configuration somebody wrote is
+ * worse than refusing to start.
+ */
+export function loadConfig(named) {
+    const path = named ?? configPath();
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        // Only a file asked for *by name* is worth complaining about.
+        if (named === undefined)
+            return {};
+        throw new Error(`No configuration at ${named}`);
+    }
+    try {
+        const found = JSON.parse(text);
+        if (typeof found !== 'object' || found === null || Array.isArray(found)) {
+            throw new Error('it is not an object');
+        }
+        return found;
+    }
+    catch (error) {
+        throw new Error(`${path} could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/daemon.d.ts

@@ -0,0 +1,26 @@
+/** Starting one of these in the background, and finding it again. */
+/** What a detached daemon records about itself. */
+export interface Running {
+    pid: number;
+    url: string;
+    paths: string[];
+    startedAt: string;
+}
+/**
+ * The daemon this user has running, if the record names one that still is.
+ *
+ * A stale record is cleared rather than reported: a `daemon.json` left behind
+ * by a crash would otherwise have `start` refuse for ever, on the strength of
+ * a process that is not there.
+ */
+export declare function running(): Running | undefined;
+/**
+ * Start one in the background, and wait until it says where it is.
+ *
+ * Detached and with its streams let go, so it outlives the shell that started
+ * it - which is the whole point, and the difference between this and running
+ * `ahpd` in a terminal you then have to keep open.
+ */
+export declare function start(argv: string[], self: string): Promise<Running>;
+/** Stop it, and forget where it was. Answers what was stopped, or nothing. */
+export declare function stop(): Running | undefined;

package/dist/daemon.js

@@ -0,0 +1,160 @@
+/** Starting one of these in the background, and finding it again. */
+import { spawn } from 'node:child_process';
+import { closeSync, openSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { daemonLog, daemonPath, ensureConfigDir } from './config.js';
+/** Is that process still there? A record outlives a crash, and says nothing about one. */
+const alive = (pid) => {
+    // `0` and the negatives are not processes: to `kill` they mean process
+    // *groups*, and pid 0 is the caller's own - which would report any record
+    // holding one as running, and then signal this process rather than it.
+    if (pid <= 0)
+        return false;
+    try {
+        // Signal 0 checks for existence without asking the process to do anything.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * The daemon this user has running, if the record names one that still is.
+ *
+ * A stale record is cleared rather than reported: a `daemon.json` left behind
+ * by a crash would otherwise have `start` refuse for ever, on the strength of
+ * a process that is not there.
+ */
+export function running() {
+    let found;
+    try {
+        found = JSON.parse(readFileSync(daemonPath(), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof found?.pid !== 'number' || !alive(found.pid)) {
+        try {
+            unlinkSync(daemonPath());
+        }
+        catch { /* it was already gone, which is what was wanted */ }
+        return undefined;
+    }
+    return found;
+}
+/**
+ * Start one in the background, and wait until it says where it is.
+ *
+ * Detached and with its streams let go, so it outlives the shell that started
+ * it - which is the whole point, and the difference between this and running
+ * `ahpd` in a terminal you then have to keep open.
+ */
+export async function start(argv, self) {
+    const already = running();
+    if (already)
+        throw new Error(`One is already running: ${already.url} (pid ${String(already.pid)})`);
+    ensureConfigDir();
+    /*
+     * Where this run's output will start.
+     *
+     * The log is appended to across runs, so reading the whole file for an
+     * address finds the *previous* daemon's - which is a record pointing at a
+     * port this process never bound, and was.
+     */
+    const from = (() => {
+        try {
+            return statSync(daemonLog()).size;
+        }
+        catch {
+            return 0;
+        }
+    })();
+    /*
+     * Its output goes to a file, not to a pipe held here.
+     *
+     * A pipe dies with the process holding its other end, and this process is
+     * about to exit - so the daemon's next log line would kill it. A file also
+     * leaves something to read when it misbehaves, which a background process
+     * with no output at all does not.
+     */
+    const log = openSync(daemonLog(), 'a');
+    const child = spawn(process.execPath, [self, ...argv], {
+        detached: true,
+        stdio: ['ignore', log, log],
+    });
+    child.unref();
+    closeSync(log);
+    /*
+     * Wait for it to say where it is, by reading what it wrote.
+     *
+     * Polling rather than listening, because nothing here is holding its
+     * output any more - which is exactly the point.
+     */
+    /** What it said about itself, so the record is its answer and not a guess. */
+    let announced = '';
+    const url = await new Promise((answer, fail) => {
+        const gaveUp = Date.now() + 20_000;
+        const look = () => {
+            let said = '';
+            try {
+                said = readFileSync(daemonLog(), 'utf8').slice(from);
+            }
+            catch { /* not written yet */ }
+            const found = /ws:\/\/[^\s,]+/.exec(said);
+            if (found) {
+                announced = said;
+                answer(found[0]);
+                return;
+            }
+            if (child.exitCode !== null) {
+                fail(new Error(`it exited with ${String(child.exitCode)}. See ${daemonLog()}`));
+                return;
+            }
+            if (Date.now() > gaveUp) {
+                fail(new Error(`it started but never said where it was listening. See ${daemonLog()}`));
+                return;
+            }
+            setTimeout(look, 100);
+        };
+        look();
+    }).catch((error) => {
+        if (child.pid !== undefined) {
+            try {
+                process.kill(child.pid, 'SIGKILL');
+            }
+            catch { /* already gone */ }
+        }
+        throw error;
+    });
+    // It announced where it was listening, so it started; this is for the type
+    // 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 record = {
+        pid: child.pid,
+        url,
+        // Off its own announcement rather than off the command line: the
+        // directories may have come from the configuration file, and a record
+        // built from argv would name none of them.
+        paths: (/sessions in (.+)/.exec(announced)?.[1] ?? '')
+            .trim().split(',').map((one) => one.trim()).filter((one) => one !== ''),
+        startedAt: new Date().toISOString(),
+    };
+    writeFileSync(daemonPath(), `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 });
+    return record;
+}
+/** Stop it, and forget where it was. Answers what was stopped, or nothing. */
+export function stop() {
+    const found = running();
+    if (!found)
+        return undefined;
+    try {
+        process.kill(found.pid, 'SIGTERM');
+    }
+    catch { /* it went between the check and the signal, which is a stop */ }
+    try {
+        unlinkSync(daemonPath());
+    }
+    catch { /* already gone */ }
+    return found;
+}

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};