@ahpd/server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luiz Fernando Softov <lfs@softov.dev>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# @ahpd/server
+
+A server library for the [Agent Host Protocol](https://github.com/microsoft/agent-host-protocol).
+
+It has no agent in it. You pass one in when you create the host.
+
+## Install
+
+```bash
+pnpm add @ahpd/server @microsoft/agent-host-protocol
+```
+
+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.
+
+## Use
+
+A small host using the Claude backend looks like this:
+
+```ts
+import { createHost, listen } from '@ahpd/server';
+import { claude } from '@ahpd/agent-claude';
+
+const host = createHost({
+  path: process.cwd(),
+  agents: [claude({ paths: [process.cwd()] })],
+});
+
+const listener = await listen({ port: 9187 }, (peer) => host.accept(peer));
+console.log(`on ws://${listener.host}:${listener.port} (${listener.runtime})`);
+```
+
+`createHost()` creates the AHP host.
+
+`listen()` is the WebSocket listener included for Node, Bun and Deno. The host itself is not tied to WebSockets.
+
+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.
+
+`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.
+
+## Options
+
+`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.
+
+
+```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', }),
+});
+
+```
+
+| 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 |
+
+None of these are imported by the host itself. `fileResources` reads files, `shellTerminals` spawns shells, and `gitBranches` runs `git`, and you pass them in.
+
+## Writing a backend
+
+`Agent` has five required members: `provider`, `displayName`, `schema`, `defaults` and `create`.
+
+```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),
+  };
+}
+```
+
+`provider` is the id a client names in `createSession`. It has to be unique among the agents one host was given.
+
+`schema()` says what a session of this kind can be configured with, and `defaults()` says where those keys start. Both can be empty.
+
+`create()` returns the session. The session holds the state of the session and chat channels, and calls `start.emit('chat', ...)` as things happen.
+
+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.
+
+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.
+
+## Types
+
+All types are exported. Nothing under `types/` imports a runtime value, so you can read the contract without loading the implementation.
+
+## 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 |
+
+## License
+
+MIT © Softov
+

package/dist/automations.d.ts

@@ -0,0 +1,4 @@
+/** Automations held in memory, run when somebody asks. */
+import type { AutomationStore } from './types/automations.js';
+export declare function memoryAutomations(): AutomationStore;
+//# sourceMappingURL=automations.d.ts.map

package/dist/automations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"automations.d.ts","sourceRoot":"","sources":["../src/automations.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAG1D,OAAO,KAAK,EAA6B,eAAe,EAAgB,MAAM,wBAAwB,CAAC;AAsBvG,wBAAgB,iBAAiB,IAAI,eAAe,CAkLnD"}

package/dist/automations.js

@@ -0,0 +1,191 @@
+/** Automations held in memory, run when somebody asks. */
+import { randomUUID } from 'node:crypto';
+/**
+ * The automations of a host that does not schedule.
+ *
+ * Deliberately half a store, and the half worth having first: definitions can
+ * be written, patched, listed and *run*, and nothing here holds a clock. An
+ * automation with a schedule trigger is accepted, kept and reported with no
+ * `nextRunAt` - which is the honest form of "this host will not fire that",
+ * and is what stops a client drawing a next-run time that will never arrive.
+ *
+ * Everything is in memory, so it goes when the process does. A store that
+ * outlives a restart is a different implementation of the same interface, and
+ * the reason the interface exists.
+ */
+const now = () => new Date().toISOString();
+/** How many runs a summary list carries before it needs a cursor. */
+const PAGE = 20;
+export function memoryAutomations() {
+    const held = new Map();
+    /** Runs by automation, newest first. */
+    const history = new Map();
+    /** Every run by its own URI, for the channel a client watches it on. */
+    const byRun = new Map();
+    const listeners = [];
+    const said = (event) => {
+        for (const listener of listeners)
+            listener(event);
+    };
+    /** The summary form of a run, which is what an automation carries. */
+    const summary = (run) => ({
+        resource: run.resource,
+        automation: run.automation,
+        origin: run.origin,
+        lifecycle: run.lifecycle,
+        sessionCount: run.sessions.length,
+        ...(run.primarySession !== undefined ? { primarySession: run.primarySession } : {}),
+    });
+    /** Rebuild the entry a client reads, so `runs` and `operations` are never stale. */
+    const entry = (automation) => {
+        const enabled = automation.definition.enabled !== false;
+        return {
+            ...automation,
+            runs: (history.get(automation.resource) ?? []).slice(0, PAGE).map(summary),
+            ...((history.get(automation.resource) ?? []).length > PAGE
+                ? { runsNextCursor: String(PAGE) }
+                : {}),
+            // `run` only where it would do something. A disabled automation is one
+            // somebody switched off, and offering the button anyway is a control
+            // that argues with the switch beside it.
+            operations: enabled ? ['update', 'remove', 'run'] : ['update', 'remove'],
+        };
+    };
+    return {
+        list: () => [...held.values()].map(entry),
+        get: (resource) => {
+            const found = held.get(resource);
+            return found && entry(found);
+        },
+        /*
+         * What this store understands, which is nothing.
+         *
+         * This command answers with *event* triggers. Schedule triggers are
+         * protocol-defined and never listed here, and manual is not a trigger at
+         * all - the protocol says an empty trigger list is what manual-only means.
+         * So a store with no event triggers answers with none, and a client reads
+         * "this host will not fire that" from the absent `nextRunAt` instead.
+         */
+        triggers: () => [],
+        create: (resource, definition) => {
+            const at = now();
+            const made = {
+                resource,
+                definition,
+                runs: [],
+                operations: [],
+                createdAt: at,
+                modifiedAt: at,
+            };
+            held.set(resource, made);
+            said({ automation: resource });
+            return entry(made);
+        },
+        update: (resource, changes) => {
+            const found = held.get(resource);
+            if (!found)
+                return undefined;
+            // A patch: absent keys are left alone, which is the whole difference
+            // between this and a write. A client sending the whole definition back
+            // would otherwise revert whatever another client changed meanwhile.
+            const after = {
+                ...found,
+                definition: { ...found.definition, ...changes },
+                modifiedAt: now(),
+            };
+            held.set(resource, after);
+            said({ automation: resource });
+            return entry(after);
+        },
+        remove: (resource) => {
+            if (!held.delete(resource))
+                return false;
+            for (const run of history.get(resource) ?? [])
+                byRun.delete(run.resource);
+            history.delete(resource);
+            said({ removed: resource });
+            return true;
+        },
+        run: async (resource, origin, start) => {
+            const found = held.get(resource);
+            if (!found)
+                return undefined;
+            if (found.definition.enabled === false)
+                return undefined;
+            const template = (typeof found.definition.session === 'object' && found.definition.session !== null
+                ? found.definition.session
+                : {});
+            const message = (typeof found.definition.message === 'object' && found.definition.message !== null
+                ? found.definition.message
+                : {});
+            const run = {
+                resource: `ahp-automation-run:/${randomUUID()}`,
+                automation: resource,
+                origin,
+                lifecycle: { status: 'pending', createdAt: now() },
+                sessions: [],
+            };
+            byRun.set(run.resource, run);
+            const past = history.get(resource) ?? [];
+            // Newest first, which is the order a client shows them in.
+            history.set(resource, [run, ...past]);
+            said({ automation: resource, run: run.resource });
+            const directories = Array.isArray(template.workingDirectories) ? template.workingDirectories : [];
+            const where = typeof directories[0] === 'string'
+                ? directories[0].replace(/^file:\/\//, '')
+                : undefined;
+            const options = {
+                ...(typeof template.provider === 'string' ? { provider: template.provider } : {}),
+                ...(where !== undefined ? { workingDirectory: where } : {}),
+                ...(typeof template.config === 'object' && template.config !== null
+                    ? { config: template.config }
+                    : {}),
+                text: typeof message.text === 'string' ? message.text : String(found.definition.title ?? ''),
+                origin: { kind: 'automation', automation: resource, run: run.resource },
+            };
+            try {
+                const session = await start(options);
+                run.sessions = [session];
+                run.primarySession = session;
+                run.lifecycle = { ...run.lifecycle, status: 'running', startedAt: now() };
+            }
+            catch (error) {
+                // Failed, and why. A run that vanished would be indistinguishable from
+                // one that never started.
+                run.lifecycle = {
+                    ...run.lifecycle,
+                    status: 'failed',
+                    endedAt: now(),
+                    error: { message: error instanceof Error ? error.message : String(error) },
+                };
+            }
+            said({ automation: resource, run: run.resource });
+            return run;
+        },
+        runOf: (resource) => byRun.get(resource),
+        unlink: (resource, session) => {
+            const run = byRun.get(resource);
+            if (run === undefined || !run.sessions.includes(session))
+                return false;
+            run.sessions = run.sessions.filter((one) => one !== session);
+            // The protocol says removing the primary clears it. A run pointing at a
+            // session that is gone is a run a client opens onto nothing.
+            if (run.primarySession === session)
+                delete run.primarySession;
+            said({ automation: run.automation, run: run.resource });
+            return true;
+        },
+        runs: (resource, cursor) => {
+            const all = history.get(resource) ?? [];
+            const from = cursor === undefined ? 0 : Number(cursor);
+            const at = Number.isFinite(from) && from >= 0 ? from : 0;
+            const page = all.slice(at, at + PAGE);
+            return {
+                items: page.map(summary),
+                ...(at + PAGE < all.length ? { nextCursor: String(at + PAGE) } : {}),
+            };
+        },
+        onChanged: (observer) => { listeners.push(observer); },
+    };
+}
+//# sourceMappingURL=automations.js.map

package/dist/automations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"automations.js","sourceRoot":"","sources":["../src/automations.ts"],"names":[],"mappings":"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"}

package/dist/catalog.d.ts

@@ -0,0 +1,48 @@
+/**
+ * How a session is named, and what its status bits are worth.
+ *
+ * URIs and numbers, and nothing that knows what a session *is*: the listing
+ * itself belongs to whichever backend wrote the sessions down, because only
+ * that one can say which exist. See `catalogue` in `@ahpd/agent-claude`.
+ */
+/**
+ * `SessionStatus`, as values.
+ *
+ * The protocol declares it as a `const enum`, which exists only in the type
+ * system - importing it at runtime is a value import of something that was
+ * erased. So the numbers are restated here, and they are the protocol's:
+ * `InputNeeded` is 24 and *carries* `InProgress` (8), which is why anything
+ * testing activity has to test it first.
+ */
+export declare const Status: {
+    readonly Idle: 1;
+    readonly Error: 2;
+    readonly InProgress: 8;
+    readonly InputNeeded: 24;
+    readonly IsRead: 32;
+    readonly IsArchived: 64;
+};
+/**
+ * A URI for a session this host found on disk. `ahp-session:/<uuid>`, and the
+ * SDK's id is already a uuid.
+ *
+ * Only for rows this host names itself. A session a *client* created is named
+ * by that client, in whatever scheme it likes - see {@link idOf}.
+ */
+export declare const uriFor: (sessionId: string) => string;
+/**
+ * The id inside a channel URI, whatever scheme the client chose.
+ *
+ * A channel URI is the **client's** to name and this host's to echo. VS Code
+ * names a session after its provider - `claude:/<uuid>`, with the provider as
+ * the *scheme* - and its terminals `agenthost-terminal:/<uuid>`. This used to
+ * strip a literal `ahp-session:/` and refuse anything else, so every session
+ * and every terminal VS Code opened was answered `is not a session URI`.
+ *
+ * So: everything after the scheme, without its leading slashes. The result is
+ * an opaque key, not something to parse further.
+ */
+export declare const idOf: (uri: string) => string;
+/** The same, and the name it goes by where a session rather than a chat is meant. */
+export declare const idFor: (uri: string) => string;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,MAAM;;;;;;;CAOT,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,GAAI,WAAW,MAAM,KAAG,MAAqC,CAAC;AAEjF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,IAAI,GAAI,KAAK,MAAM,KAAG,MAGlC,CAAC;AACF,qFAAqF;AACrF,eAAO,MAAM,KAAK,QALQ,MAAM,KAAG,MAKV,CAAC"}

package/dist/catalog.js

@@ -0,0 +1,51 @@
+/**
+ * How a session is named, and what its status bits are worth.
+ *
+ * URIs and numbers, and nothing that knows what a session *is*: the listing
+ * itself belongs to whichever backend wrote the sessions down, because only
+ * that one can say which exist. See `catalogue` in `@ahpd/agent-claude`.
+ */
+/**
+ * `SessionStatus`, as values.
+ *
+ * The protocol declares it as a `const enum`, which exists only in the type
+ * system - importing it at runtime is a value import of something that was
+ * erased. So the numbers are restated here, and they are the protocol's:
+ * `InputNeeded` is 24 and *carries* `InProgress` (8), which is why anything
+ * testing activity has to test it first.
+ */
+export const Status = {
+    Idle: 1,
+    Error: 2,
+    InProgress: 8,
+    InputNeeded: 24,
+    IsRead: 32,
+    IsArchived: 64,
+};
+/**
+ * A URI for a session this host found on disk. `ahp-session:/<uuid>`, and the
+ * SDK's id is already a uuid.
+ *
+ * Only for rows this host names itself. A session a *client* created is named
+ * by that client, in whatever scheme it likes - see {@link idOf}.
+ */
+export const uriFor = (sessionId) => `ahp-session:/${sessionId}`;
+/**
+ * The id inside a channel URI, whatever scheme the client chose.
+ *
+ * A channel URI is the **client's** to name and this host's to echo. VS Code
+ * names a session after its provider - `claude:/<uuid>`, with the provider as
+ * the *scheme* - and its terminals `agenthost-terminal:/<uuid>`. This used to
+ * strip a literal `ahp-session:/` and refuse anything else, so every session
+ * and every terminal VS Code opened was answered `is not a session URI`.
+ *
+ * So: everything after the scheme, without its leading slashes. The result is
+ * an opaque key, not something to parse further.
+ */
+export const idOf = (uri) => {
+    const colon = uri.indexOf(':');
+    return (colon < 0 ? uri : uri.slice(colon + 1)).replace(/^\/+/, '');
+};
+/** The same, and the name it goes by where a session rather than a chat is meant. */
+export const idFor = idOf;
+//# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;IACR,UAAU,EAAE,CAAC;IACb,WAAW,EAAE,EAAE;IACf,MAAM,EAAE,EAAE;IACV,UAAU,EAAE,EAAE;CACN,CAAC;AAEX;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,SAAiB,EAAU,EAAE,CAAC,gBAAgB,SAAS,EAAE,CAAC;AAEjF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,GAAW,EAAU,EAAE;IAC1C,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACtE,CAAC,CAAC;AACF,qFAAqF;AACrF,MAAM,CAAC,MAAM,KAAK,GAAG,IAAI,CAAC"}

package/dist/changes.d.ts

@@ -0,0 +1,4 @@
+/** What git says a directory has changed, as a host's `ChangesetSource`. */
+import type { ChangesetSource } from './types/changes.js';
+export declare function gitChanges(): ChangesetSource;
+//# sourceMappingURL=changes.d.ts.map

package/dist/changes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changes.d.ts","sourceRoot":"","sources":["../src/changes.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAI5E,OAAO,KAAK,EACyC,eAAe,EACnE,MAAM,oBAAoB,CAAC;AAuJ5B,wBAAgB,UAAU,IAAI,eAAe,CAud5C"}