@ahpd/server 0.1.0

package/dist/types/worktrees.d.ts

@@ -0,0 +1,86 @@
+/** A working tree of its own, so two sessions in one repository do not collide. */
+/** What to make, and from where. */
+export interface Worktree {
+    /** The repository to make it from. A path, not a URI. */
+    repository: string;
+    /** The branch to start from. */
+    base: string;
+    /**
+     * The branch to create and check out, or nothing to check out `base` itself.
+     *
+     * Absent is what `worktreeCreateNewBranch: false` means: the session
+     * continues an existing branch rather than starting one. Git refuses a
+     * second worktree on a branch already checked out somewhere, which is the
+     * right refusal - two sessions on one branch is the collision worktrees
+     * exist to prevent.
+     */
+    branch?: string;
+    /**
+     * Whether the created branch tracks the upstream of the one it started from.
+     *
+     * Off unless asked. A tracking branch pushes at its upstream by default, so
+     * a `git push` inside a session's worktree would go at the branch it was
+     * started *from* - which is the one mistake in here that reaches a shared
+     * repository.
+     */
+    track?: boolean;
+    /** Where to put it. */
+    path: string;
+    /**
+     * Git-ignored files to copy in, as glob patterns relative to the repository.
+     *
+     * A checkout carries what git tracks and nothing else, so a worktree of an
+     * ordinary project has no `.env`, no `node_modules`, and none of the local
+     * configuration the thing needs to run. Without these the isolation works
+     * and the session inside it cannot build - which is a failure the person
+     * meets after choosing it rather than while choosing it.
+     */
+    include?: string[];
+}
+/**
+ * Making and unmaking git worktrees.
+ *
+ * A port for the reason `DirectoryFacts` and `ChangesetSource` are ports: it
+ * spawns `git`, which is a binary rather than a runtime API and may not be
+ * installed. A host given none advertises no `isolation` at all, which is the
+ * honest answer - a client draws the control a host says it has.
+ *
+ * Deliberately not part of `ChangesetSource`. That port describes changes; a
+ * worktree is a directory, and the two happen to share an implementation
+ * rather than a subject.
+ */
+export interface Worktrees {
+    /**
+     * The repository root above this directory, if it is in one.
+     *
+     * The root and not the directory: a worktree is made from the repository,
+     * and a session pointed at `src/` inside one is still a session in it.
+     * Undefined means there is no repository here and no isolation to offer.
+     */
+    repository(dir: string): Promise<string | undefined>;
+    /**
+     * The branches this repository has, most useful first.
+     *
+     * What a client draws the base-branch picker from. An empty list is a real
+     * answer - a repository with no commits has no branches - and leaves the
+     * control with nothing to choose but the default.
+     */
+    branches(repository: string): Promise<string[]>;
+    /** Make one. Answers the path it made, which is where the session runs. */
+    create(worktree: Worktree): Promise<void>;
+    /**
+     * Whether anything in it is uncommitted.
+     *
+     * Asked before it is removed, and the answer decides whether it is: work
+     * nobody committed is work this daemon cannot judge the value of.
+     */
+    dirty(path: string): Promise<boolean>;
+    /**
+     * Take one away, and the branch with it if nothing else points at it.
+     *
+     * Only ever called for a worktree this host made and only when `dirty`
+     * answered no.
+     */
+    remove(repository: string, path: string, branch?: string): Promise<void>;
+}
+//# sourceMappingURL=worktrees.d.ts.map

package/dist/types/worktrees.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktrees.d.ts","sourceRoot":"","sources":["../../src/types/worktrees.ts"],"names":[],"mappings":"AAAA,mFAAmF;AAEnF,oCAAoC;AACpC,MAAM,WAAW,QAAQ;IACvB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;OAMG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAErD;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEhD,2EAA2E;IAC3E,MAAM,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C;;;;;OAKG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtC;;;;;OAKG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1E"}

package/dist/types/worktrees.js

@@ -0,0 +1,3 @@
+/** A working tree of its own, so two sessions in one repository do not collide. */
+export {};
+//# sourceMappingURL=worktrees.js.map

package/dist/types/worktrees.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktrees.js","sourceRoot":"","sources":["../../src/types/worktrees.ts"],"names":[],"mappings":"AAAA,mFAAmF"}

package/dist/worktrees.d.ts

@@ -0,0 +1,27 @@
+/** Git worktrees, so two sessions in one repository do not edit under each other. */
+import type { Worktrees } from './types/worktrees.js';
+/**
+ * Where a repository's worktrees live: `<repo>.worktrees`, beside it.
+ *
+ * Beside rather than inside, because a worktree inside its own repository is
+ * a directory git then has to be told to ignore, and every tool that walks the
+ * tree finds the same project twice. The name is the one VS Code's host uses,
+ * so a worktree either of them makes is one the other finds.
+ */
+export declare const worktreesOf: (repository: string) => string;
+/** The directory name for a branch: no slashes, since it has to be one segment. */
+export declare const worktreeFor: (branch: string) => string;
+/**
+ * Git worktrees, as a host's `Worktrees` port.
+ *
+ * Deliberately not part of `createHost`: it spawns `git`, which is a binary
+ * rather than a runtime API and may not be installed at all. A host without it
+ * offers no isolation and every session runs in the folder it was pointed at,
+ * which is what this daemon did before there was a choice.
+ *
+ * ```ts
+ * createHost({ path, agents: [claude({ paths })], worktrees: gitWorktrees() });
+ * ```
+ */
+export declare function gitWorktrees(): Worktrees;
+//# sourceMappingURL=worktrees.d.ts.map

package/dist/worktrees.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktrees.d.ts","sourceRoot":"","sources":["../src/worktrees.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAKrF,OAAO,KAAK,EAAY,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAchE;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,GAAI,YAAY,MAAM,KAAG,MACe,CAAC;AAEjE,mFAAmF;AACnF,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,KAAG,MACQ,CAAC;AAEtD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,IAAI,SAAS,CAmFxC"}

package/dist/worktrees.js

@@ -0,0 +1,152 @@
+/** Git worktrees, so two sessions in one repository do not edit under each other. */
+import { execFile } from 'node:child_process';
+import { basename, dirname, join } from 'node:path';
+import { cp, mkdir, readdir, stat } from 'node:fs/promises';
+/** Run git, and answer what it said. Rejects with git's own words. */
+const git = (dir, args, ms = 60_000) => new Promise((resolve, reject) => {
+    execFile('git', ['-C', dir, ...args], { timeout: ms, maxBuffer: 8 << 20 }, (error, out, bad) => {
+        if (!error)
+            return resolve(out.toString());
+        // git's own message, not node's: "fatal: a branch named x already
+        // exists" is something a person can act on and `Command failed` is not.
+        const said = bad.toString().trim() || error.message;
+        reject(new Error(said));
+    });
+});
+/**
+ * Where a repository's worktrees live: `<repo>.worktrees`, beside it.
+ *
+ * Beside rather than inside, because a worktree inside its own repository is
+ * a directory git then has to be told to ignore, and every tool that walks the
+ * tree finds the same project twice. The name is the one VS Code's host uses,
+ * so a worktree either of them makes is one the other finds.
+ */
+export const worktreesOf = (repository) => join(dirname(repository), `${basename(repository)}.worktrees`);
+/** The directory name for a branch: no slashes, since it has to be one segment. */
+export const worktreeFor = (branch) => branch.replace(/^agents\//, '').replace(/\//g, '-');
+/**
+ * Git worktrees, as a host's `Worktrees` port.
+ *
+ * Deliberately not part of `createHost`: it spawns `git`, which is a binary
+ * rather than a runtime API and may not be installed at all. A host without it
+ * offers no isolation and every session runs in the folder it was pointed at,
+ * which is what this daemon did before there was a choice.
+ *
+ * ```ts
+ * createHost({ path, agents: [claude({ paths })], worktrees: gitWorktrees() });
+ * ```
+ */
+export function gitWorktrees() {
+    return {
+        repository: async (dir) => {
+            const found = await git(dir, ['rev-parse', '--show-toplevel'], 5_000).catch(() => undefined);
+            const root = found?.trim();
+            return root === undefined || root === '' ? undefined : root;
+        },
+        branches: async (repository) => {
+            /*
+             * Local branches by most recent commit, then the remote ones.
+             *
+             * Ordered rather than alphabetical because the useful answer is almost
+             * always near the top of the first list, and a picker that opens on
+             * `archive/2019-cleanup` is one somebody has to search.
+             */
+            const said = await git(repository, ['for-each-ref', '--sort=-committerdate', '--format=%(refname:short)', 'refs/heads', 'refs/remotes'], 10_000).catch(() => '');
+            const seen = new Set();
+            for (const line of said.split('\n')) {
+                const name = line.trim();
+                // `origin/HEAD` is a symbolic ref rather than a branch, and checking
+                // it out is a detached head instead of the branch somebody meant.
+                if (name === '' || name.endsWith('/HEAD'))
+                    continue;
+                seen.add(name.replace(/^origin\//, ''));
+            }
+            return [...seen];
+        },
+        create: async (worktree) => {
+            await mkdir(dirname(worktree.path), { recursive: true });
+            /*
+             * A new branch, or the one that was chosen.
+             *
+             * `--no-track` unless asked, because the new branch is this session's
+             * own: tracking would make it push to the base branch's upstream by
+             * default, so a `git push` inside a worktree session would go at the
+             * branch it was started *from*. That is the one mistake in here that
+             * reaches a shared repository.
+             *
+             * No branch at all is `worktreeCreateNewBranch: false` - the session
+             * continues `base` rather than starting something. Git refuses a second
+             * worktree on a branch already checked out, and that refusal is right.
+             */
+            await git(worktree.repository, worktree.branch === undefined
+                ? ['worktree', 'add', worktree.path, worktree.base]
+                : [
+                    'worktree', 'add', worktree.track === true ? '--track' : '--no-track',
+                    '-b', worktree.branch, worktree.path, worktree.base,
+                ]);
+            for (const pattern of worktree.include ?? []) {
+                // Best effort, one pattern at a time: a `.env` that is not there is
+                // the ordinary case, and a session that refused to start over a
+                // missing optional file would be worse than one without it.
+                await copy(worktree.repository, worktree.path, pattern).catch(() => undefined);
+            }
+        },
+        dirty: async (path) => {
+            // `--porcelain` says nothing at all about a clean tree, which makes the
+            // empty answer the reliable one. Untracked files count: a file the
+            // agent wrote and never added is exactly the work worth keeping.
+            const said = await git(path, ['status', '--porcelain'], 10_000).catch(() => 'unknown');
+            return said.trim() !== '';
+        },
+        remove: async (repository, path, branch) => {
+            await git(repository, ['worktree', 'remove', path]);
+            /*
+             * The branch too, and only the one this host made.
+             *
+             * Named by the caller rather than derived from the directory: a branch
+             * prefix a client asked for changes the name, and guessing it wrong
+             * either deletes nothing or - far worse - names somebody else's. `-d`
+             * refuses to delete a branch carrying commits nothing else has, which
+             * is the same judgement the dirty check makes about uncommitted work.
+             */
+            if (branch !== undefined)
+                await git(repository, ['branch', '-d', branch]).catch(() => undefined);
+        },
+    };
+}
+/**
+ * Copy one git-ignored path into the new worktree, keeping its place.
+ *
+ * A glob only in the shallow sense the reference uses it: a literal path, or
+ * one trailing `*` in the last segment. A full matcher here would be a
+ * dependency and a surprise - the patterns clients send are `.env`,
+ * `.env.local` and `node_modules`.
+ */
+const copy = async (from, to, pattern) => {
+    if (pattern.includes('..') || pattern.startsWith('/'))
+        return;
+    const star = pattern.lastIndexOf('*');
+    if (star === -1) {
+        await cp(join(from, pattern), join(to, pattern), { recursive: true, errorOnExist: false });
+        return;
+    }
+    const at = pattern.lastIndexOf('/');
+    const dir = at === -1 ? '' : pattern.slice(0, at);
+    const leaf = at === -1 ? pattern : pattern.slice(at + 1);
+    if (leaf.indexOf('*') !== leaf.lastIndexOf('*'))
+        return;
+    const [before, after] = leaf.split('*');
+    const entries = await readdir(join(from, dir)).catch(() => []);
+    for (const entry of entries) {
+        if (!entry.startsWith(before ?? '') || !entry.endsWith(after ?? ''))
+            continue;
+        const source = join(from, dir, entry);
+        // Directories as well as files: `node_modules` is the pattern that makes
+        // the difference between a worktree that builds and one that does not.
+        const what = await stat(source).catch(() => undefined);
+        if (!what)
+            continue;
+        await cp(source, join(to, dir, entry), { recursive: what.isDirectory(), errorOnExist: false });
+    }
+};
+//# sourceMappingURL=worktrees.js.map

package/dist/worktrees.js.map

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

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@ahpd/server",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A server library for the Agent Host Protocol. No agent inside, you pass one in",
+  "keywords": [
+    "ahp",
+    "agent-host-protocol",
+    "agent-host",
+    "agent",
+    "ai",
+    "protocol",
+    "json-rpc",
+    "websocket",
+    "server",
+    "host",
+    "daemon"
+  ],
+  "author": "Luiz Fernando Softov <lfs@softov.dev>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/softov/ahpd#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/softov/ahpd.git",
+    "directory": "packages/server"
+  },
+  "bugs": {
+    "url": "https://github.com/softov/ahpd/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "optionalDependencies": {
+    "ws": "^8.18.0",
+    "node-pty": "^1.1.0-beta40"
+  },
+  "peerDependencies": {
+    "@microsoft/agent-host-protocol": "^0.9.0"
+  },
+  "devDependencies": {
+    "@microsoft/agent-host-protocol": "^0.9.0"
+  },
+  "scripts": {}
+}

package/src/automations.ts

@@ -0,0 +1,204 @@
+/** Automations held in memory, run when somebody asks. */
+
+import { randomUUID } from 'node:crypto';
+import type { Automation, AutomationRun, AutomationStore, StartSession } from './types/automations.js';
+import type { Bag } from './types/common.js';
+
+/**
+ * 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 = (): string => new Date().toISOString();
+
+/** How many runs a summary list carries before it needs a cursor. */
+const PAGE = 20;
+
+export function memoryAutomations(): AutomationStore {
+  const held = new Map<string, Automation>();
+  /** Runs by automation, newest first. */
+  const history = new Map<string, AutomationRun[]>();
+  /** Every run by its own URI, for the channel a client watches it on. */
+  const byRun = new Map<string, AutomationRun>();
+  const listeners: ((event: { automation?: string; run?: string; removed?: string }) => void)[] = [];
+  const said = (event: { automation?: string; run?: string; removed?: string }): void => {
+    for (const listener of listeners) listener(event);
+  };
+
+  /** The summary form of a run, which is what an automation carries. */
+  const summary = (run: AutomationRun): Bag => ({
+    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: Automation): 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: Automation = {
+        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: Automation = {
+        ...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
+        : {}) as Bag;
+      const message = (typeof found.definition.message === 'object' && found.definition.message !== null
+        ? found.definition.message
+        : {}) as Bag;
+
+      const run: AutomationRun = {
+        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] as string).replace(/^file:\/\//, '')
+        : undefined;
+      const options: StartSession = {
+        ...(typeof template.provider === 'string' ? { provider: template.provider } : {}),
+        ...(where !== undefined ? { workingDirectory: where } : {}),
+        ...(typeof template.config === 'object' && template.config !== null
+          ? { config: template.config as Record<string, string> }
+          : {}),
+        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); },
+  };
+}

package/src/catalog.ts

@@ -0,0 +1,53 @@
+/**
+ * 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,
+} as const;
+
+/**
+ * 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: string): string => `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: string): string => {
+  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;