@ahpd/server 0.1.0 → 0.3.0

package/src/types/host.ts

@@ -1,386 +0,0 @@
-/** The protocol server: channels, subscriptions and requests. */
-
-import type { ToolDefinition } from '@microsoft/agent-host-protocol';
-import type { Agent } from './agent.js';
-import type { Entry, Metadata, Read, ResourceChange, WatchOptions, Watcher, Write as WriteContent } from './resources.js';
-import type { Terminal, TerminalOptions } from './terminals.js';
-import type { ChangesetSource } from './changes.js';
-import type { Worktrees } from './worktrees.js';
-import type { AutomationStore } from './automations.js';
-import type { Peer, Request } from './rpc.js';
-
-/**
- * What a host can say about a directory beyond its path.
- *
- * Injected rather than built in. The interesting answers come from outside the
- * protocol - a branch is a `git` subprocess, and `git` is a binary that may
- * not be installed - and a host embedded in something that already knows them
- * should not have them read a second time. A host given none says only what a
- * path alone can tell it, which is the project's name.
- */
-export interface DirectoryFacts {
-  /**
-   * What is known about a directory now, as the session's `_meta`.
-   *
-   * Synchronous and cheap, because it is asked for every description of every
-   * session - a catalogue of a hundred rows asks a hundred times. Anything
-   * that has to be fetched is fetched by `refresh` and cached here.
-   *
-   * The keys are the protocol's: `git` is the well-known one, and anything of
-   * an implementation's own belongs under a namespace.
-   */
-  meta(dir: string): Record<string, unknown> | undefined;
-  /**
-   * Look again, answering whether anything actually moved.
-   *
-   * Asked once per served directory at startup and again whenever a turn
-   * ends. Only a true answer reaches a client, so a directory that has not
-   * changed costs nothing but the look.
-   */
-  refresh?(dir: string): Promise<boolean>;
-}
-
-/**
- * The files a client may read through this host.
- *
- * A port, for the same reason `DirectoryFacts` is one: reading a directory is
- * `node:fs` on one runtime and something else on another, and a host embedded
- * in an editor may already have the file open. `roots` arrives per call rather
- * than being captured, because a backend may learn of a directory after the
- * host started and the answer has to move with it.
- *
- * A host given none serves no `resource*` command at all - `-32601`, the same
- * answer it gives for anything else it does not have - and completes no `@`.
- */
-export interface ResourceStore {
-  /** One directory's entries. */
-  list(uri: string, roots: string[], ): Promise<Entry[]>;
-  /** One file's bytes, or the range of them that was asked for. */
-  read(uri: string, roots: string[], wanted?: string): Promise<Read>;
-  /** What a URI is, without reading it. */
-  resolve(uri: string, roots: string[], followSymlinks?: boolean): Promise<Metadata>;
-  /** Paths under `base` that start with what is typed. */
-  complete(typed: string, base: string, roots: string[], limit?: number): Promise<string[]>;
-
-  /*
-   * The half that writes.
-   *
-   * Every one is optional and they are optional together: a store that has
-   * none is a read-only filesystem, and the host answers `-32601` for each,
-   * which is a different thing from refusing a particular path. `fileResources()`
-   * has them all; a store over something that cannot be written - an archive,
-   * a read-only mount, a fixture - simply leaves them out and says so by
-   * omission rather than by throwing on every call.
-   *
-   * The host has already checked the client's `resourceRequest` grant before
-   * any of these is reached. What is left to each is the path check, which is
-   * a store's own business because only it knows what a path means.
-   */
-
-  /** Write, create or splice one file. */
-  write?(uri: string, roots: string[], content: WriteContent): Promise<void>;
-  /** Remove a file, or a directory when `recursive`. */
-  remove?(uri: string, roots: string[], recursive?: boolean): Promise<void>;
-  /** Make a directory, and the parents it needs. */
-  mkdir?(uri: string, roots: string[]): Promise<void>;
-  /** Rename, within the served directories on both ends. */
-  move?(source: string, destination: string, roots: string[], failIfExists?: boolean): Promise<void>;
-  /** Copy, within the served directories on both ends. */
-  copy?(source: string, destination: string, roots: string[], failIfExists?: boolean): Promise<void>;
-
-  /**
-   * Tell me when that changes.
-   *
-   * Optional on its own rather than with the write half: watching is a read,
-   * and a store may perfectly well serve bytes it cannot subscribe to - a
-   * remote filesystem, an archive, a fixture. A host whose store has none
-   * answers `-32601` for `createResourceWatch`, and the protocol's own client
-   * treats that as a reason to degrade rather than to fail.
-   *
-   * `onChange` is called with a *batch*, because the filesystem reports one
-   * event per file and a save is several: the protocol says a server coalesces
-   * them, and an empty batch MUST NOT be dispatched. Closing the returned
-   * handle is the only way to stop it - there is no dispose command, and
-   * `unsubscribe` is what the host turns into this call.
-   */
-  watch?(
-    uri: string,
-    roots: string[],
-    options: WatchOptions,
-    onChange: (changes: ResourceChange[]) => void,
-  ): Promise<Watcher>;
-}
-
-/**
- * The shells this host can open.
- *
- * A port, because a terminal is a subprocess: which one, and how it is
- * spawned, is the runtime's business rather than the protocol's. A host given
- * none serves neither `createTerminal` nor `disposeTerminal`, and says so with
- * `-32601` rather than opening nothing and reporting success.
- */
-export interface TerminalStore {
-  /** Open one, in a directory the host has already checked. */
-  create(options: TerminalOptions): Terminal;
-}
-
-/** How to construct a host. */
-export interface HostOptions {
-  /**
-   * The directory whose sessions this host serves, on the machine it runs on.
-   *
-   * Also the catalogue's scope: sessions outside it are neither listed nor
-   * openable.
-   */
-  path: string;
-  /**
-   * The backends this host serves.
-   *
-   * At least one, and each with a `provider` no other has. The first is what
-   * a client gets when it names none - which is the ordinary case, since a
-   * client that has read the root channel names one and one that has not
-   * cannot.
-   *
-   * Nothing in the host knows what any of them are. `claude()` is one that
-   * ships with it; anything satisfying `Agent` is another.
-   */
-  agents: Agent[];
-  /**
-   * The files a client may read, and complete an `@` into.
-   *
-   * Left out, no `resource*` command is served. `fileResources()` is the one
-   * that ships with this package, and the daemon uses it.
-   */
-  resources?: ResourceStore;
-  /**
-   * How to open a shell.
-   *
-   * Left out, no terminal can be created. `shellTerminals()` is the one that
-   * ships with this package, and the daemon uses it.
-   */
-  terminals?: TerminalStore;
-  /**
-   * Where the file changes a session made come from.
-   *
-   * Left out, no session advertises a changeset and the changes screen is
-   * honestly empty rather than emptily wrong. `gitChanges()` is the one that
-   * ships with this package, and the daemon uses it.
-   */
-  changes?: ChangesetSource;
-  /**
-   * What this host can say about the directories it serves.
-   *
-   * Left out, sessions carry their project and nothing more. `gitBranches()`
-   * is the one that ships with this package, and the daemon uses it.
-   */
-  directories?: DirectoryFacts;
-  /**
-   * Whether a session can be given a working tree of its own.
-   *
-   * Left out, every session runs in the folder it was pointed at and this host
-   * advertises no `isolation` - so a client draws no control for it, which is
-   * the honest form of "not offered". `gitWorktrees()` is the one that ships
-   * with this package, and the daemon uses it.
-   *
-   * The reason to wire it in: two agents in one repository is the ordinary
-   * case for a sessions server, and without this they share a working tree.
-   * The second turn's changeset then contains the first turn's edits, and
-   * discarding a file discards somebody else's work.
-   */
-  worktrees?: Worktrees;
-  /**
-   * The automations this host offers.
-   *
-   * Left out, no `ahp-automations://` channel is advertised and all three
-   * automation commands answer `-32601` - which is the right answer for a
-   * daemon that runs the sessions somebody asks for and schedules nothing.
-   * `memoryAutomations()` is the one that ships with this package: it holds
-   * definitions, runs them when asked, and holds no clock.
-   */
-  automations?: AutomationStore;
-  /**
-   * Tools this host contributes to every session it runs.
-   *
-   * The protocol's `serverTools`: tools that are the *host's* rather than a
-   * backend's or a client's, reported on `SessionState.serverTools` and given
-   * to the backend to offer the model. What they are is the host's to decide
-   * - `hostTools()` is the set that ships with this package - and a host that
-   * passes none contributes none, which is what an absent `serverTools` says.
-   */
-  tools?: HostTool[];
-  /** Called with one line per notable event, for a log. */
-  onEvent?(message: string): void;
-}
-
-/**
- * One tool the host contributes, and what running it does.
- *
- * `definition` is what a client draws and what the model is offered;
- * `run` is called when the model calls it, with the arguments it passed and
- * the chat it called from. Returning a string is the answer; throwing is a
- * tool that failed, and the message reaches the model.
- */
-export interface HostTool {
-  /** What the model is offered. `name` is the id it calls. */
-  definition: ToolDefinition;
-  /** What running it does. */
-  run(input: Record<string, unknown>, at: ToolCall): Promise<string> | string;
-}
-
-/**
- * Where a host tool was called from, and what the host knows.
- *
- * The reason a tool is the host's rather than the backend's: an agent inside
- * a session cannot see the sessions beside it or the terminals a person is
- * watching, and the host can. A tool that wants neither ignores both.
- */
-export interface ToolCall {
-  /** The session channel URI the call was made in. */
-  session: string;
-  /** The chat channel URI it was made from. */
-  chat: string;
-  /** Every session this host is running, including the calling one. */
-  sessions(): { uri: string; provider: string; title: string; workingDirectories: string[] }[];
-  /** Every terminal this host has open. */
-  terminals(): { uri: string; title: string; cwd: string; running: boolean }[];
-  /**
-   * Read a resource this host serves, as text.
-   *
-   * Including one it does not have: a URI a connected client published is
-   * fetched from that client, which is the only way an agent reaches a
-   * plugin's virtual files or an editor's unsaved buffers. Rejects when
-   * nothing serves it, in the words of whatever refused.
-   */
-  read(uri: string): Promise<string>;
-}
-
-/** One connected client and what it is watching. */
-export interface Connection {
-  /** Where to write messages for this client. */
-  peer: Peer;
-  /** The identifier the client gave at `initialize`. */
-  clientId: string;
-  /**
-   * Channel URIs this client subscribed to.
-   *
-   * Per connection: two clients can watch one channel, and dropping one must
-   * not stop the other's stream.
-   */
-  watching: Set<string>;
-  /**
-   * Resource access this client has been granted, as `read:<uri>` / `write:<uri>`.
-   *
-   * Per connection and never per host: `resourceRequest` is a negotiation
-   * between two peers, and a grant one client talked its way into is not one
-   * every other client on the port inherits. Emptied when the connection goes,
-   * because it goes with the set.
-   */
-  grants: Set<string>;
-  /**
-   * Tokens this client pushed, by protected resource identifier.
-   *
-   * Per connection for the same reason grants are, and the specification says
-   * so outright: authentication status is per connection, each client
-   * authenticating independently. A token one client offered is theirs, spent
-   * only on sessions they ask for, and gone when they hang up.
-   *
-   * Which is also why an automation that fires with nobody connected has
-   * none: it is the host's own work rather than any client's, and it runs on
-   * the credentials the daemon was started with.
-   */
-  tokens: Map<string, string>;
-  /**
-   * Channels this client named in a shape of its own, by the channel they mean.
-   *
-   * A client may address a chat by a URI this host did not mint - see
-   * `chatFor` - and it then expects to be answered about *that* URI: its
-   * subscription is keyed by the string it sent, and an action arriving under
-   * any other name belongs to a channel it is not watching. So the spelling is
-   * remembered per connection and every notification is addressed back the way
-   * it was asked for.
-   */
-  aliases: Map<string, string>;
-}
-
-/**
- * The clients connected to this host, as places a resource can come from.
- *
- * The protocol is symmetrical about `resource*`: the ten methods a client
- * calls on a host are the ten a host may call on a client, with the same
- * params and the same results, and the receiver decides whether to allow the
- * operation whichever way round it went. What that is *for* is a client that
- * publishes something the host has no way to reach - a plugin's virtual
- * files, an editor's unsaved buffers, a filesystem provider - and addresses
- * it as `<scheme>://<clientId>/…`.
- *
- * So this is not a port handed in: it is built out of the connections a host
- * already has, and a URI naming one of them is answered by that client rather
- * than by the host's own filesystem.
- */
-export interface Clients {
-  /** Every client currently connected, by the id it gave at `initialize`. */
-  ids(): string[];
-  /**
-   * The client a URI belongs to, if a connected one publishes it.
-   *
-   * `<scheme>://<clientId>/…`, which is how the reference host addresses one.
-   * `file:` is never a client's, and neither is any `ahp-` channel scheme -
-   * those are this protocol's own and their authority is not a client id.
-   */
-  owner(uri: string): string | undefined;
-
-  /** Read a file the client serves. */
-  read(client: string, uri: string, encoding?: string): Promise<unknown>;
-  /** List a directory the client serves. */
-  list(client: string, uri: string): Promise<unknown>;
-  /** Ask the client what a URI actually is. */
-  resolve(client: string, uri: string): Promise<unknown>;
-  /** Write a file the client serves. */
-  write(client: string, uri: string, content: { data: string; encoding?: string; create?: boolean; overwrite?: boolean }): Promise<unknown>;
-  /** Remove one. */
-  remove(client: string, uri: string, recursive?: boolean): Promise<unknown>;
-  /** Move one. Both URIs must be the same client's. */
-  move(client: string, source: string, destination: string, failIfExists?: boolean): Promise<unknown>;
-  /** Copy one. Both URIs must be the same client's. */
-  copy(client: string, source: string, destination: string, failIfExists?: boolean): Promise<unknown>;
-  /** Make a directory. */
-  mkdir(client: string, uri: string): Promise<unknown>;
-  /** Ask to watch one, and get back the channel the client will report on. */
-  watch(client: string, uri: string, options?: Record<string, unknown>): Promise<unknown>;
-  /** Ask the client for access to one of its resources. */
-  request(client: string, uri: string, access: { read?: boolean; write?: boolean }): Promise<unknown>;
-}
-
-/** A protocol server. One host serves many connections. */
-export interface Host {
-  /**
-   * Take a new client and return what answers it.
-   *
-   * The result's `handle` answers requests; its `close` must be called when
-   * the connection drops, or the client's subscriptions leak.
-   */
-  accept(peer: Peer): {
-    /** Answer one request from this client. */
-    handle(request: Request): Promise<unknown>;
-    /** Drop this client's subscriptions and state. */
-    close(): void;
-  };
-  /** How many clients are currently connected. */
-  connections(): number;
-  /**
-   * The connected clients, as places a resource can come from.
-   *
-   * Used by this host to answer a `resource*` command naming a URI a client
-   * published, and exposed so an embedder can read one directly.
-   */
-  clients: Clients;
-  /**
-   * Replace the tools this host contributes.
-   *
-   * Full replacement, which is what `session/serverToolsChanged` means, and
-   * every running session is told. Sessions started after this get the new
-   * set; the ones already running get it on their next turn, because a
-   * backend is offered its tools when its process starts.
-   */
-  setTools(tools: HostTool[]): void;
-}

package/src/types/index.ts

@@ -1,27 +0,0 @@
-/**
- * Every shape this daemon speaks.
- *
- * Nothing under `types/` imports a runtime value, so the contract can be read
- * without loading the server, a socket or the agent SDK.
- */
-
-export type { Bag } from './common.js';
-/*
- * The protocol's own shapes, as this host builds them.
- *
- * On the public surface because the port names them: `Agent.transcript`
- * answers with `WireTurn<Turn>[]`, and a backend written against this library
- * cannot implement that without being able to say it.
- */
-export type { OnWire, WireTurn } from './wire.js';
-export type { Request, Wire, Peer, Handler } from './rpc.js';
-export type { Summary } from './catalog.js';
-export type { Emit, SessionOptions, Session, Ran, Chosen } from './session.js';
-export type { HostOptions, Connection, Host } from './host.js';
-export type { Page } from './paging.js';
-export type { Connected, OnConnect, Runtime, Listener } from './listen.js';
-export type { Offered } from './probe.js';
-export type { Agent, Listed, Start, BoundTool } from './agent.js';
-export type { Entry, Metadata, Read } from './resources.js';
-export type { Claim, Terminal, TerminalOptions, SpawnPty } from './terminals.js';
-export type { Worktree, Worktrees } from './worktrees.js';

package/src/types/listen.ts

@@ -1,53 +0,0 @@
-/** Accepting connections, on whichever JavaScript runtime is running. */
-
-import type { Peer, Request } from './rpc.js';
-
-/** One accepted client, for as long as its connection lasts. */
-export interface Connected {
-  /** Answer one request from this client. */
-  handle(request: Request): Promise<unknown>;
-  /** Release what the connection held. Called once, when it drops. */
-  close(): void;
-}
-
-/** Called per connection, to hand it to whatever will answer it. */
-export type OnConnect = (peer: Peer) => Connected;
-
-/** The runtimes a listener can be running on. */
-export type Runtime = 'node' | 'bun' | 'deno';
-
-/** A running server. */
-export interface Listener {
-  /** Which runtime was detected. */
-  readonly runtime: Runtime;
-  /** The address it bound. */
-  readonly host: string;
-  /** The port it accepted. */
-  readonly port: number;
-  /** Whether a connection token is required. */
-  readonly guarded: boolean;
-  /** Stop accepting and drop open connections. */
-  close(): void | Promise<void>;
-}
-
-/** Where to accept connections, and who may open one. */
-export interface ListenOptions {
-  /** TCP port to bind. */
-  port: number;
-  /**
-   * Address to bind.
-   *
-   * Loopback by default, which is the only address that needs no secret:
-   * anything reaching it is already on this machine. `0.0.0.0` is every
-   * interface, and is what a connection token is for.
-   */
-  host?: string;
-  /**
-   * A secret every connection must present, or nothing to accept any.
-   *
-   * Given as `?tkn=<token>` on the WebSocket URL or as an
-   * `Authorization: Bearer <token>` header. Browsers cannot set headers on a
-   * WebSocket, which is why the query string is the one that always works.
-   */
-  token?: string;
-}

package/src/types/paging.ts

@@ -1,11 +0,0 @@
-/** Serving a long list of turns a page at a time, walking backwards. */
-
-import type { Bag } from './common.js';
-
-/** One page of turns, newest page first, walking backwards. */
-export interface Page {
-  /** The turns in this page, oldest first. */
-  turns: Bag[];
-  /** Cursor for the next older page. Absent when the page reaches the start. */
-  turnsNextCursor?: string;
-}

package/src/types/probe.ts

@@ -1,42 +0,0 @@
-/** What the agent backend offers, read once before any session exists. */
-
-/** The harness-wide capabilities, used until a session reports its own. */
-export interface Offered {
-  /**
-   * Models a turn can run on.
-   *
-   * `id` is what the wire carries and `name` what a person reads.
-   * `configSchema` is what the *model* can be told to do differently, as
-   * `SessionModelInfo.configSchema`: a client draws it as a form beside the
-   * model rather than as a session-wide control, which matters because
-   * different models take different options. A model that takes none omits
-   * it, and a client then draws no form for that one.
-   */
-  models: { id: string; name: string; configSchema?: Record<string, unknown> }[];
-  /**
-   * Skills, commands, subagents and MCP servers the harness offers here.
-   *
-   * What a new session starts out reporting, so its info pane is answered at
-   * once rather than several seconds later when its own agent replies.
-   */
-  customizations: Record<string, unknown>[];
-  /**
-   * Output styles this harness has, and the one in force.
-   *
-   * Optional because it is a real answer for a backend to have no such
-   * notion: left out, no output-style control is drawn at all rather than an
-   * empty picker being offered.
-   */
-  outputStyles?: string[];
-  /** The style the harness starts on, when it has them. */
-  outputStyle?: string;
-  /** Commands available after a slash. */
-  commands: {
-    /** The command name, without its leading slash. */
-    name: string;
-    /** One line describing what it does. */
-    description?: string;
-    /** What its argument is, e.g. `<id>`, when it takes one. */
-    argumentHint?: string;
-  }[];
-}

package/src/types/resources.ts

@@ -1,107 +0,0 @@
-/** The host's filesystem, as far as a client is allowed to see it. */
-
-import type {
-  ContentEncoding, ResourceChangeType, ResourceType, ResourceWriteMode,
-} from '@microsoft/agent-host-protocol';
-
-/*
- * The vocabularies below are the protocol's own, taken as `${Enum}` rather
- * than written out.
- *
- * A template literal over a string enum is the string union it declares, so
- * `'ready'` still assigns and `'complete'` is a compile error - and the words
- * come from the installed package rather than from a copy somebody made once.
- * A copy is what let a changeset report `status: 'complete'` for the life of
- * this host: the protocol says `ready`, nothing checked the difference, and a
- * conformant client read a changeset that never finished computing.
- *
- * Type-only, so nothing here imports a runtime value.
- */
-
-/** One entry in a directory listing. */
-export interface Entry {
-  /** Base name, not a path. */
-  name: string;
-  /** Which of the two it is. A symlink is reported as what it points at. */
-  type: Exclude<`${ResourceType}`, 'symlink'>;
-}
-
-/** What a path is, without opening it. */
-export interface Metadata {
-  /** The canonical URI, after symlinks unless they were not followed. */
-  uri: string;
-  /** Resource kind. */
-  type: `${ResourceType}`;
-  /** Size in bytes. Omitted for directories. */
-  size?: number;
-  /** ISO 8601 last-modified time. */
-  mtime: string;
-  /** ISO 8601 creation time. */
-  ctime: string;
-  /**
-   * A weak validator for the bytes, as `resourceWrite`'s `ifMatch` reads it.
-   *
-   * Derived from size and modification time rather than from a hash of the
-   * content: it exists to catch a lost update, so it has to be cheap enough to
-   * produce on every stat, and two writes a millisecond apart that leave the
-   * file the same length are not the case anybody is guarding against.
-   */
-  etag?: string;
-}
-
-/**
- * Where `data` goes in the file, as `ResourceWriteMode` has it.
- *
- * All three read `position` differently, which is the part worth stating: two
- * of them are rooted at the start of the file and `append` is rooted at its
- * end, so `position: 5` means "five bytes in" for the first two and "five
- * bytes before EOF" for the third.
- */
-export type WriteMode = `${ResourceWriteMode}`;
-
-/** One write, with everything the protocol lets a client ask for. */
-export interface Write {
-  /** The content, encoded as `encoding` says. */
-  data: string;
-  /** How to read `data`. Binary content MUST arrive base64. */
-  encoding: `${ContentEncoding}`;
-  /** How `data` is placed. `truncate` when the client says nothing. */
-  mode?: WriteMode;
-  /** The offset, read as `mode` says. Zero when the client says nothing. */
-  position?: number;
-  /** Refuse with `-32010` if the file is already there. */
-  createOnly?: boolean;
-  /** Refuse with `-32011` unless the file's current `etag` is this one. */
-  ifMatch?: string;
-}
-
-/** One file's bytes, in whichever encoding was meaningful. */
-export interface Read {
-  /** The content, encoded as `encoding` says. */
-  data: string;
-  /** How `data` is encoded. Reported rather than assumed. */
-  encoding: `${ContentEncoding}`;
-  /** Sniffed MIME type, where there is one worth reporting. */
-  contentType?: string;
-}
-
-/** What happened to one path, in the protocol's three words. */
-export interface ResourceChange {
-  uri: string;
-  type: `${ResourceChangeType}`;
-}
-
-/** What a watch was asked to report. */
-export interface WatchOptions {
-  /** Report descendants too. Without it, the path itself and its direct children. */
-  recursive?: boolean;
-  /** Globs, relative to the watched root, whose matches are not reported. */
-  excludes?: string[];
-  /** Globs the reported set is restricted to. Absent reports everything not excluded. */
-  includes?: string[];
-}
-
-/** A watch, for as long as somebody wants it. */
-export interface Watcher {
-  close(): void;
-}