@ahpd/server 0.1.0

package/dist/types/changes.d.ts

@@ -0,0 +1,272 @@
+/** What a session changed, as the protocol's changeset channel carries it. */
+import type { ChangesetOperationScope as Scope, ChangesetOperationTargetKind as TargetKind, ChangesetStatus } from '@microsoft/agent-host-protocol';
+/** A pointer to content the state tree does not carry. */
+export interface ContentRef {
+    uri: string;
+    sizeHint?: number;
+    contentType?: string;
+}
+/**
+ * One file, on both sides of the change.
+ *
+ * `before` absent is a creation and `after` absent a deletion, which is how
+ * the protocol says both rather than carrying a status word for them.
+ */
+export interface FileEdit {
+    before?: {
+        uri: string;
+        content: ContentRef;
+    };
+    after?: {
+        uri: string;
+        content: ContentRef;
+    };
+    diff?: {
+        added?: number;
+        removed?: number;
+    };
+}
+/** One row of a changeset. `id` is stable within it. */
+export interface ChangesetFile {
+    id: string;
+    edit: FileEdit;
+    reviewed?: boolean;
+}
+/** What a client subscribed to a changeset URI is looking at. */
+export interface ChangesetState {
+    /**
+     * Where the computation is, in the protocol's own three words.
+     *
+     * Taken from `ChangesetStatus` rather than written out. This port said
+     * `computing | complete | error` for the life of the project and the
+     * protocol says `computing | ready | error`, so every changeset ever served
+     * carried a status word no client could recognise - and nothing caught it,
+     * because a hand-copied union is checked against nothing.
+     */
+    status: `${ChangesetStatus}`;
+    files: ChangesetFile[];
+}
+/** The roll-up a catalogue row carries, so a list needs no subscription. */
+export interface ChangesSummary {
+    files?: number;
+    additions?: number;
+    deletions?: number;
+}
+/**
+ * One scope of change a directory can be asked about.
+ *
+ * The protocol nests changesets under the session's own URI - `uncommitted`,
+ * `session`, `turn/<id>` - so a scope is the last part and the host composes
+ * the rest. Keeping it that way round means a source never has to know what a
+ * session is called.
+ */
+export interface ChangesetScope {
+    /** The path segment, e.g. `uncommitted`. */
+    id: string;
+    /** What a client shows, e.g. `Uncommitted Changes`. */
+    label: string;
+    description?: string;
+    /**
+     * What kind of changeset this is, so a client can group and sort without
+     * parsing the URI. The protocol names `session`, `branch`, `uncommitted`,
+     * `turn` and `compare-turns`, and says a client should fall back sensibly
+     * on one it does not know.
+     */
+    changeKind: string;
+    /**
+     * Whether files in this changeset can be marked reviewed.
+     *
+     * A presence flag on the catalogue entry, which is what lets a client decide
+     * whether to draw the checkbox *before* it subscribes to anything. Review is
+     * not an operation: the client dispatches `changeset/filesReviewChanged` and
+     * the server keeps the flag.
+     */
+    reviewable?: boolean;
+}
+/**
+ * Where an operation may be invoked.
+ *
+ * The protocol's three: the whole changeset, one file in it, or a line range
+ * within one file. A source declares which it accepts and the host refuses an
+ * invocation whose target is not among them.
+ */
+export type ChangesetOperationScope = `${Scope}`;
+/** The file, or the lines of it, an operation was pointed at. */
+export interface ChangesetOperationTarget {
+    kind: `${TargetKind}`;
+    /** The `ChangesetFile.id` of the row, which is a `file://` URI. */
+    resource: string;
+    /** Which side of the edit, where an operation can act on either. */
+    side?: 'before' | 'after';
+    /** Present iff `kind` is `range`. Lines are 1-based, as the protocol has them. */
+    range?: {
+        startLine: number;
+        startColumn?: number;
+        endLine: number;
+        endColumn?: number;
+    };
+}
+/**
+ * A verb a client may run against a changeset.
+ *
+ * Server-advertised, and that is the whole access model: `invokeChangesetOperation`
+ * carries an `operationId` that must match one this source already offered for
+ * this scope, so a client can ask for nothing that was not put in front of it.
+ *
+ * There is no `status` here because status is not the source's. Whether an
+ * operation is disabled depends on whether the session is mid-turn, and whether
+ * it is running depends on an invocation in flight - both of which the host
+ * knows and a source does not.
+ */
+export interface ChangesetOperation {
+    /** Stable within the changeset, and what an invocation names. */
+    id: string;
+    /** The button. */
+    label: string;
+    /** Longer text, for a tooltip. */
+    description?: string;
+    /** The targets this operation accepts. */
+    scopes: ChangesetOperationScope[];
+    /**
+     * The question to ask before running it.
+     *
+     * Its presence is also how the protocol says "this is destructive": a client
+     * MUST show it, and SHOULD style the affirmative button as a warning.
+     */
+    confirmation?: string;
+    /** A hint, e.g. `git-commit` or `discard`. */
+    icon?: string;
+    /** Operations sharing one are drawn together. */
+    group?: string;
+    /**
+     * Whether running it writes to the working tree.
+     *
+     * What the host gates on: an operation that writes needs a write grant on the
+     * resource, negotiated through `resourceRequest`, and is refused with `-32009`
+     * until one is held. Declared here rather than inferred from the id, because
+     * the host cannot know what a source's verbs do.
+     */
+    writes?: boolean;
+}
+/** One invocation, as the host hands it to the source. */
+export interface ChangesetOperationRequest {
+    dir: string;
+    session: string;
+    /** The scope segment, e.g. `uncommitted` or `turn/abc`. */
+    scope: string;
+    operationId: string;
+    /** Absent for a changeset-scoped operation. */
+    target?: ChangesetOperationTarget;
+    /**
+     * What the session is called, offered as a commit subject.
+     *
+     * The host's to know and not this source's: a changeset is a set of files and
+     * a session is a conversation, and the sentence somebody would write on a
+     * commit is in the second one.
+     */
+    subject?: string;
+}
+/** What an invocation says for itself. Thrown errors are the failure path. */
+export interface ChangesetOperationResult {
+    /** One line for the client to show. */
+    message?: string;
+    /**
+     * Something to open afterwards, when the operation produced one.
+     *
+     * A `ContentRef` - a URI, a size hint, a content type - and whether the
+     * client should open it in a browser rather than inline. A pull request a
+     * commit-and-push produced is the case this exists for: the operation
+     * succeeded, and the useful thing about it is a page somewhere.
+     */
+    followUp?: {
+        content: {
+            uri: string;
+            sizeHint?: number;
+            contentType?: string;
+            nonce?: string;
+        };
+        external?: boolean;
+    };
+}
+/**
+ * Where a host's file changes come from.
+ *
+ * A port, like the filesystem and the shell, and for the sharpest version of
+ * the same reason: a diff comes from `git`, which is a binary that may not be
+ * installed, against a directory that may not be a repository. A host given
+ * none advertises no changesets, which is a true answer rather than an empty
+ * screen.
+ */
+export interface ChangesetSource {
+    /**
+     * Which scopes can be answered here. Empty for a directory that has none.
+     *
+     * `session` is passed because two of the protocol's scopes are a session's
+     * rather than a directory's - what *this conversation* changed is not what
+     * the working tree looks like, and a directory with three sessions in it has
+     * three different answers.
+     */
+    scopes(dir: string, session: string): ChangesetScope[];
+    /** The state behind one of them. */
+    state(dir: string, session: string, scope: string): Promise<ChangesetState | undefined>;
+    /** The roll-up for a catalogue row, cheap enough to ask per row. */
+    summary(dir: string): ChangesSummary | undefined;
+    /**
+     * Content behind a ref this source minted.
+     *
+     * The `before` side of an edit is not a file on disk - it is what the file
+     * used to be - so it cannot be served by the filesystem port. Undefined for
+     * a URI this source does not own, which is how the host knows to try the
+     * filesystem instead.
+     */
+    read?(uri: string): Promise<{
+        data: string;
+        encoding: string;
+    } | undefined>;
+    /** Look again, answering whether anything moved. */
+    refresh?(dir: string): Promise<boolean>;
+    /**
+     * Mark files reviewed, or clear them.
+     *
+     * A person's bookkeeping about a diff they are reading, not a change to
+     * anything on disk - which is why it is the one thing here a client may
+     * write. Answers whether anything moved, so an idempotent toggle tells
+     * nobody about a state it already had.
+     */
+    review?(dir: string, session: string, scope: string, files: string[], reviewed: boolean): boolean;
+    /**
+     * A file an agent is about to change, and the same file once it has.
+     *
+     * What makes a *turn's* changeset the turn's. Git can only ever say what a
+     * working tree looks like now, so a turn asked about later would be handed
+     * every turn after it as well; capturing both sides as the tool runs is the
+     * only way the answer stays the turn's own.
+     *
+     * Reading the file is this source's business - it is the thing here that
+     * has a filesystem - and the session only says which one and when.
+     */
+    observe?(dir: string, session: string, turnId: string, path: string, phase: 'before' | 'after'): void;
+    /**
+     * The verbs this source offers on one scope, in the order to draw them.
+     *
+     * Asked per scope because the answer differs by scope: the working tree can
+     * be committed and a turn cannot, and what a turn changed can be put back
+     * because both sides of every file in it were captured.
+     *
+     * Empty is a real answer and the one to give for a scope with nothing to do
+     * to it. A source with no method at all advertises none anywhere, which is
+     * what a host serving a directory it may not write looks like.
+     */
+    operations?(dir: string, session: string, scope: string): ChangesetOperation[];
+    /**
+     * Run one.
+     *
+     * The host has already checked that `operationId` is among what this source
+     * offered for this scope, that the target's kind is one the operation
+     * accepts, and that a write grant is held where the operation says it writes.
+     * What is left is doing it, and throwing if it did not work - the protocol
+     * signals failure by rejecting the request, not by a field on the result.
+     */
+    invoke?(request: ChangesetOperationRequest): Promise<ChangesetOperationResult>;
+}
+//# sourceMappingURL=changes.d.ts.map

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

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

package/dist/types/changes.js

@@ -0,0 +1,3 @@
+/** What a session changed, as the protocol's changeset channel carries it. */
+export {};
+//# sourceMappingURL=changes.js.map

package/dist/types/changes.js.map

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

package/dist/types/common.d.ts

@@ -0,0 +1,9 @@
+/** Shapes shared by more than one channel. */
+/**
+ * An object with no declared shape.
+ *
+ * Used for JSON arriving off the wire and for the agent SDK's frames, both of
+ * which are read field by field rather than trusted as a type.
+ */
+export type Bag = Record<string, unknown>;
+//# sourceMappingURL=common.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/types/common.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAE9C;;;;;GAKG;AACH,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC"}

package/dist/types/common.js

@@ -0,0 +1,3 @@
+/** Shapes shared by more than one channel. */
+export {};
+//# sourceMappingURL=common.js.map

package/dist/types/common.js.map

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

package/dist/types/host.d.ts

@@ -0,0 +1,372 @@
+/** 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[]>;
+    /** 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;
+}
+//# sourceMappingURL=host.d.ts.map