@ahpd/server 0.1.0

package/src/index.ts

@@ -0,0 +1,40 @@
+/**
+ * The host: the protocol, and the parts to build your own out of.
+ *
+ * There is no backend in here, and that is the point of it being its own
+ * package. `rpc` is JSON-RPC and holds no socket, `listen` is the only file
+ * that knows which runtime it is on, and `createHost` is the protocol and
+ * imports nothing that runs an agent. A harness is an `Agent` handed to
+ * `createHost` from outside - `@ahpd/agent-claude` is one, `examples/` has one
+ * written from nothing - and adding another is not a fork of this.
+ *
+ * Anything that touches the machine is the same shape again: `fileResources`
+ * reads files, `shellTerminals` spawns shells and `gitBranches` spawns `git`,
+ * and all three are passed to `createHost` rather than reached for by it. So
+ * the protocol imports no runtime, and a host without one of them refuses the
+ * commands it cannot answer instead of pretending to.
+ *
+ * Every shape lives in `types/` and nothing there imports a runtime value, so
+ * the contract can be read without loading any of this.
+ */
+
+export { createHost, ROOT } from './host.js';
+export { within } from './paths.js';
+export { listen } from './listen.js';
+export {
+  createPeer, receive, RpcError, RpcTimeout, RpcClosed, ANSWER_TIMEOUT,
+  PARSE_ERROR, INVALID_REQUEST, METHOD_NOT_FOUND, INTERNAL_ERROR,
+} from './rpc.js';
+export { gitBranches } from './git.js';
+export { gitChanges } from './changes.js';
+export { fileResources } from './resources.js';
+export { shellTerminals } from './terminals.js';
+export { hostTools } from './tools.js';
+export { gitWorktrees, worktreesOf, worktreeFor } from './worktrees.js';
+export { memoryAutomations } from './automations.js';
+export { scheduledAutomations } from './scheduled.js';
+export type { ScheduledOptions } from './scheduled.js';
+export { uriFor, idFor, idOf, Status } from './catalog.js';
+export { tail, older, PAGE } from './paging.js';
+
+export type * from './types/index.js';

package/src/listen.ts

@@ -0,0 +1,240 @@
+import { createPeer, receive } from './rpc.js';
+import type { Connected, Listener, ListenOptions, OnConnect, Runtime } from './types/listen.js';
+
+/**
+ * Accepts WebSocket connections on Node, Bun or Deno.
+ *
+ * The runtime is detected at startup and the matching server is used: `ws` on
+ * Node, which has no WebSocket server of its own, and the built-in servers on
+ * Bun and Deno. `ws` is an optional dependency and is imported only on Node.
+ *
+ * This is the only module that knows which runtime it is on. Supporting
+ * another one is a case added here.
+ */
+
+const runtimeOf = (): Runtime => {
+  const g = globalThis as { Bun?: unknown; Deno?: unknown };
+  if (g.Bun !== undefined) return 'bun';
+  if (g.Deno !== undefined) return 'deno';
+  return 'node';
+};
+
+/** What a runtime's socket has to look like once it is wired up. */
+interface Bound {
+  peer: ReturnType<typeof createPeer>;
+  connected: Connected;
+}
+
+/**
+ * The token a connection presented, if it presented one.
+ *
+ * Two places, because only one of them always works: a browser cannot set
+ * headers on a WebSocket handshake, so the query string is the portable form
+ * and the header is for clients that can.
+ */
+const presented = (url: string | undefined, authorization: string | null): string | undefined => {
+  const query = /[?&]tkn=([^&]*)/.exec(url ?? '');
+  if (query) return decodeURIComponent(query[1] ?? '');
+  const bearer = /^Bearer\s+(.+)$/i.exec(authorization ?? '');
+  return bearer?.[1];
+};
+
+/**
+ * Compares two secrets without returning early on the first difference.
+ *
+ * The lengths still differ observably, which is why a token is generated
+ * rather than chosen: they are all the same length.
+ */
+const same = (a: string, b: string): boolean => {
+  if (a.length !== b.length) return false;
+  let differing = 0;
+  for (let i = 0; i < a.length; i++) differing |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return differing === 0;
+};
+
+export async function listen(options: ListenOptions, onConnect: OnConnect): Promise<Listener> {
+  const runtime = runtimeOf();
+  const host = options.host ?? '127.0.0.1';
+  const token = options.token;
+  /** Whether this handshake may proceed. No token configured accepts any. */
+  const allowed = (url: string | undefined, authorization: string | null): boolean =>
+    token === undefined || same(token, presented(url, authorization) ?? '');
+
+  if (runtime === 'bun') {
+    const Bun = (globalThis as unknown as { Bun: {
+      serve(options: Record<string, unknown>): { stop(closeActive?: boolean): void; port: number };
+    } }).Bun;
+    // Per socket, because Bun's handler table is one set of callbacks for
+    // every connection - `ws` is the only thing distinguishing them.
+    const bound = new Map<object, Bound>();
+    const server = Bun.serve({
+      port: options.port,
+      hostname: host,
+      fetch(request: Request_, server_: { upgrade(r: Request_): boolean }) {
+        // Refused before the upgrade, so an unauthorised client is told in
+        // HTTP rather than handed a socket that closes on its first message.
+        if (!allowed(request.url, request.headers.get('authorization'))) {
+          return new Response('A connection token is required', { status: 401 });
+        }
+        if (server_.upgrade(request)) return undefined;
+        return new Response('ahpd speaks the Agent Host Protocol over WebSocket', { status: 426 });
+      },
+      websocket: {
+        open(ws: BunSocket) {
+          const peer = createPeer({
+            send: (text) => { ws.send(text); },
+            close: () => ws.close(),
+            isOpen: () => ws.readyState === 1,
+          });
+          bound.set(ws, { peer, connected: onConnect(peer) });
+        },
+        message(ws: BunSocket, raw: string | Uint8Array) {
+          const held = bound.get(ws);
+          if (!held) return;
+          const text = typeof raw === 'string' ? raw : new TextDecoder().decode(raw);
+          receive(text, held.peer, (request) => held.connected.handle(request));
+        },
+        close(ws: BunSocket) {
+          const held = bound.get(ws);
+          // The peer first: a question this host asked is still pending, and
+          // the socket that would have answered it is gone.
+          held?.peer.close();
+          held?.connected.close();
+          bound.delete(ws);
+        },
+      },
+    });
+    return { runtime, host, port: server.port, guarded: token !== undefined, close: () => server.stop(true) };
+  }
+
+  if (runtime === 'deno') {
+    const Deno = (globalThis as unknown as { Deno: {
+      serve(options: { port: number; hostname: string }, handler: (r: Request_) => Response): {
+        shutdown(): Promise<void>;
+        addr: { port: number };
+      };
+      upgradeWebSocket(r: Request_): { socket: DenoSocket; response: Response };
+    } }).Deno;
+    const server = Deno.serve({ port: options.port, hostname: host }, (request) => {
+      if (!allowed(request.url, request.headers.get('authorization'))) {
+        return new Response('A connection token is required', { status: 401 });
+      }
+      if ((request.headers.get('upgrade') ?? '').toLowerCase() !== 'websocket') {
+        return new Response('ahpd speaks the Agent Host Protocol over WebSocket', { status: 426 });
+      }
+      const { socket, response } = Deno.upgradeWebSocket(request);
+      let held: Bound | undefined;
+      socket.onopen = () => {
+        const peer = createPeer({
+          send: (text) => { socket.send(text); },
+          close: () => socket.close(),
+          isOpen: () => socket.readyState === 1,
+        });
+        held = { peer, connected: onConnect(peer) };
+      };
+      socket.onmessage = (event) => {
+        const open = held;
+        if (!open) return;
+        receive(String(event.data), open.peer, (request_) => open.connected.handle(request_));
+      };
+      socket.onclose = () => { held?.peer.close(); held?.connected.close(); held = undefined; };
+      return response;
+    });
+    return {
+      runtime,
+      host,
+      port: server.addr.port,
+      guarded: token !== undefined,
+      close: () => server.shutdown(),
+    };
+  }
+
+  let WebSocketServer: new (options: NodeOptions) => NodeServer;
+  try {
+    ({ WebSocketServer } = await import('ws') as unknown as {
+      WebSocketServer: new (options: NodeOptions) => NodeServer;
+    });
+  } catch {
+    throw new Error(
+      'Running on Node needs the `ws` package, which has no server in the standard library.\n'
+      + '  npm install ws\n'
+      + 'Bun and Deno have one built in and need nothing.',
+    );
+  }
+
+  const server = new WebSocketServer({
+    port: options.port,
+    host,
+    // `ws` answers a rejected handshake with the status this passes back, so
+    // an unauthorised client reads 401 rather than a socket that opened and
+    // then closed for no stated reason.
+    verifyClient: (info, accept) => {
+      if (allowed(info.req.url, info.req.headers.authorization ?? null)) accept(true);
+      else accept(false, 401, 'A connection token is required');
+    },
+  });
+  server.on('connection', (socket) => {
+    const peer = createPeer({
+      send: (text) => { socket.send(text); },
+      close: () => socket.close(),
+      isOpen: () => socket.readyState === 1,
+    });
+    const connected = onConnect(peer);
+    socket.on('message', (raw) => {
+      receive(typeof raw === 'string' ? raw : raw.toString('utf8'), peer, (request) => connected.handle(request));
+    });
+    socket.on('close', () => { peer.close(); connected.close(); });
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once('listening', () => resolve());
+    server.once('error', (error) => reject(error instanceof Error ? error : new Error(String(error))));
+  });
+  return {
+    runtime,
+    host,
+    // What was bound, not what was asked for: port 0 means the OS chooses.
+    port: server.address()?.port ?? options.port,
+    guarded: token !== undefined,
+    close: () => { server.close(); },
+  };
+}
+
+// --- the shapes each runtime hands back, named so the code above reads ------
+
+type Request_ = { url: string; headers: { get(name: string): string | null } };
+
+interface BunSocket { send(text: string): unknown; close(): void; readyState: number }
+
+interface DenoSocket {
+  send(text: string): void;
+  close(): void;
+  readyState: number;
+  onopen: (() => void) | null;
+  onmessage: ((event: { data: unknown }) => void) | null;
+  onclose: (() => void) | null;
+}
+
+interface NodeOptions {
+  port: number;
+  host: string;
+  verifyClient(
+    info: { req: { url?: string; headers: { authorization?: string } } },
+    accept: (allow: boolean, code?: number, message?: string) => void,
+  ): void;
+}
+
+interface NodeServer {
+  on(event: 'connection', handler: (socket: NodeSocket) => void): void;
+  once(event: 'listening' | 'error', handler: (error?: unknown) => void): void;
+  address(): { port: number } | null;
+  close(): void;
+}
+
+interface NodeSocket {
+  send(text: string): void;
+  close(): void;
+  readyState: number;
+  on(event: 'message', handler: (raw: string | Buffer) => void): void;
+  on(event: 'close', handler: () => void): void;
+}

package/src/paging.ts

@@ -0,0 +1,56 @@
+import type { Bag } from './types/common.js';
+import type { Page } from './types/paging.js';
+
+/**
+ * A long list of turns, served a page at a time.
+ *
+ * Nothing here knows what a turn is beyond it being one of many, which is why
+ * it is not in `transcript.ts`: reading a transcript is the backend's, because
+ * only the thing that ran the session knows the shape its frames are in.
+ * Paging is the host's, and it is the same paging whichever backend produced
+ * them.
+ */
+
+/**
+ * How many turns a snapshot carries.
+ *
+ * A session in this directory has eight hundred and fifty turns. Sending them
+ * all works and will not keep working: a snapshot is what a client waits for
+ * before it can draw anything, and the oldest turns are the ones nobody is
+ * looking at.
+ */
+export const PAGE = 50;
+
+/**
+ * The newest page, and where the rest begins.
+ *
+ * The cursor is the index of the oldest turn served - opaque to a client, and
+ * deliberately so, but it has to mean something here or `fetchTurns` cannot
+ * answer twice in a row.
+ */
+export function tail(turns: Bag[], size = PAGE): Page {
+  const start = Math.max(0, turns.length - size);
+  return {
+    turns: turns.slice(start),
+    ...(start > 0 ? { turnsNextCursor: String(start) } : {}),
+  };
+}
+
+/**
+ * The page before a cursor, or nothing when the cursor is not one of ours.
+ *
+ * The protocol requires an unrecognised cursor to be rejected rather than
+ * guessed at: a host that quietly returned its newest page for a cursor it
+ * did not issue would answer a question about old turns with new ones, and
+ * the client would page forever without noticing.
+ */
+export function older(turns: Bag[], cursor: string, size = PAGE): Page | undefined {
+  if (!/^\d+$/.test(cursor)) return undefined;
+  const at = Number(cursor);
+  if (at <= 0 || at > turns.length) return undefined;
+  const start = Math.max(0, at - size);
+  return {
+    turns: turns.slice(start, at),
+    ...(start > 0 ? { turnsNextCursor: String(start) } : {}),
+  };
+}

package/src/paths.ts

@@ -0,0 +1,19 @@
+import { isAbsolute, relative } from 'node:path';
+
+/**
+ * Whether a path is a served root or under one.
+ *
+ * By `relative` rather than by string: `startsWith(root + '/')` is wrong for
+ * `/` - it asks whether the path begins `//` and refuses the whole filesystem -
+ * and `root === path` alone is wrong for everything else. Three places check
+ * this and they used to do it three ways, of which one was exact equality: a
+ * host told to serve `/home/you` served that directory and refused every
+ * project inside it, which is the only kind of directory anybody opens.
+ *
+ * Textual, so callers that can resolve symlinks resolve first and pass the
+ * real path - `served/link` pointing at `/etc` passes any textual test.
+ */
+export const within = (root: string, path: string): boolean => {
+  const step = relative(root, path);
+  return step === '' || (!step.startsWith('..') && !isAbsolute(step));
+};