@aivi/plugin 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# @aivi/plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This is the package you import to write an aivi plugin — not the package
+`aivi install` installs. A plugin is a plain npm package that exports a
+module the host composes, a `./setup` entry `aivi install` runs, and a
+`./cli` entry whose commands join `aivi --help`. The kit holds every
+contract a plugin author needs and nothing more; the host stays the
+runtime that implements them. The seam words — tracker, forge adapter,
+platform adapter, project contributor — are defined in
+[docs/vocabulary.md](docs/vocabulary.md).
+
+## Exports
+
+| Path | Contents |
+| --- | --- |
+| `@aivi/plugin` | the contracts: `PluginSetupContext`/`PluginSetupResult`/`PluginSetupCancelled` (the install-time subpath), `PluginCliContext` and `resolveBlocked` (the runtime one), and the module contract under its authoring names (`AiviModule`, `AiviServices`) |
+| `@aivi/plugin/api` | `createHostClient` — the fetch-only HTTP client for the aivi server, the one piece of runtime code a guest in someone else's process (the OpenCode plugin) may carry |
+| `@aivi/plugin/channel` | the channel kind's vocabulary: `ChannelModule` and the conversation-binding types — types only; the shared inbox, engine and turn runner are the host's |
+
+Rules the kit keeps:
+
+- The kit depends on `@aivi/core` only — never on `@aivi/host` at runtime.
+  Where a contract names a runtime type (`Store`, `ConversationStore`), the
+  import is type-only: the host implements the bag, plugins receive it typed.
+- Prompts: the runner hands over its own `@clack/prompts` module instance
+  (`ctx.prompts`); whoever is called owns the screen. There are no `ask.*`
+  wrappers — two clacks animating one terminal mangle each other.
+- A plugin kind gets a subpath (`./channel`, later `./tracker`); it is
+  promoted to its own package only if the kind ever needs runtime-shared
+  code.

package/dist/api.d.ts

@@ -0,0 +1,10 @@
+import type { HostClient } from '@aivi/core';
+export interface HostClientOptions {
+    /** Bearer token identifying the caller (a person token). Omit to stay anonymous. */
+    token?: string | undefined;
+}
+/**
+ * Fetch-only client for the aivi host API. Used by the OpenCode plugin, so it
+ * must stay free of SQLite, QMD, and other host-side dependencies.
+ */
+export declare function createHostClient(baseUrl: string, options?: HostClientOptions): HostClient;

package/dist/api.js

@@ -0,0 +1,147 @@
+/**
+ * The HTTP client for the aivi server, for whoever talks to it from outside:
+ * the OpenCode-side plugin (a guest in someone else's process) and a plugin's
+ * own tool surface. It ships in the kit, not in the host, so reaching the
+ * server never pulls SQLite, QMD or other host-side weight into the caller.
+ */
+import { createRequire } from 'node:module';
+/**
+ * The version of this `@aivi/plugin` installation — read from its own
+ * `package.json` at runtime, so the number can never drift from the package
+ * that carries it. It travels as `x-aivi-client`; the host serves a client at
+ * or behind its own version, and `@aivi/cli`, `@aivi/host` and `@aivi/plugin`
+ * move in lockstep through the changesets `fixed` group, so the two sides of
+ * the wire agree. The gate's rules are in the host's `api/gate.ts`.
+ */
+const clientVersion = createRequire(import.meta.url)('../package.json').version;
+/**
+ * Fetch-only client for the aivi host API. Used by the OpenCode plugin, so it
+ * must stay free of SQLite, QMD, and other host-side dependencies.
+ */
+export function createHostClient(baseUrl, options = {}) {
+    const base = new URL(baseUrl);
+    if (!['http:', 'https:'].includes(base.protocol) || base.username || base.password) {
+        throw new Error('Expected an HTTP host URL without embedded credentials');
+    }
+    const headers = {
+        // The version the host negotiates against; a host that cannot speak to
+        // this client answers 403 with the version that would pass, and the
+        // error below carries that answer. Read from this package's own
+        // package.json: this module must stay free of SQLite, QMD, and other
+        // host-side weight.
+        'x-aivi-client': clientVersion,
+        ...(options.token ? { authorization: `Bearer ${options.token}` } : {}),
+    };
+    async function request(path, init) {
+        const { timeoutMs, ...rest } = init;
+        let response;
+        try {
+            response = await fetch(new URL(path, base), {
+                ...rest,
+                headers: { ...headers, ...rest.headers },
+                signal: AbortSignal.timeout(timeoutMs),
+                redirect: 'error',
+            });
+        }
+        catch (error) {
+            // Every aivi tool goes through the host; the usual cause is simply that `aivi serve` is not running.
+            if (error instanceof Error && error.name === 'TimeoutError')
+                throw error;
+            throw new Error(`aivi is not reachable at ${base.origin}. Is \`aivi serve\` running?`, { cause: error });
+        }
+        if (!response.ok)
+            throw new Error(await describeFailure(response));
+        return (await response.json());
+    }
+    const get = (path) => request(path, { timeoutMs: 10_000 });
+    return {
+        search(query) {
+            const params = new URLSearchParams({ q: query.query });
+            if (query.limit !== undefined)
+                params.set('limit', String(query.limit));
+            appendSelection(params, query);
+            return get(`/knowledge/search?${params}`);
+        },
+        status: () => get('/status'),
+        sources(selection = {}) {
+            const params = new URLSearchParams();
+            appendSelection(params, selection);
+            return get(`/sources?${params}`);
+        },
+        projects: () => get('/projects'),
+        async listTools() {
+            return (await get('/tools')).tools;
+        },
+        callTool(id, call) {
+            // One budget per tool comes from its descriptor: a browser action may
+            // wait behind other tabs, a status read must not.
+            return request('/tools', {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({
+                    tool: id,
+                    sessionId: call.sessionId,
+                    ...(call.messageId ? { messageId: call.messageId } : {}),
+                    input: call.input,
+                }),
+                timeoutMs: call.timeoutMs ?? 10_000,
+            });
+        },
+        health: () => request('/health', { timeoutMs: 3_000 }),
+        runMembership: sessionId => request(`/run?${new URLSearchParams({ session: sessionId })}`, { timeoutMs: 3_000 }),
+        context: sessionId => request(`/context?${new URLSearchParams({ session: sessionId })}`, { timeoutMs: 20_000 }),
+        wake: () => request('/wake', { method: 'POST', timeoutMs: 3_000 }),
+        whoami: () => get('/whoami'),
+        people: () => get('/people'),
+        createPerson(input) {
+            return request('/people', {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(input),
+                timeoutMs: 10_000,
+            });
+        },
+        createPersonToken(personId, label) {
+            return request(`/people/${encodeURIComponent(personId)}/tokens`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ label }),
+                timeoutMs: 10_000,
+            });
+        },
+        jobs(body) {
+            // Creating a job checks the calling session and agent against OpenCode; a few seconds at most.
+            return request('/jobs', {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(body),
+                timeoutMs: 30_000,
+            });
+        },
+    };
+}
+function appendSelection(params, selection) {
+    for (const project of selection.projects ?? [])
+        params.append('project', project);
+    // An explicit empty selection means core only.
+    if (selection.projects?.length === 0)
+        params.set('coreOnly', 'true');
+    if (selection.includeCore === false)
+        params.set('includeCore', 'false');
+    for (const kind of selection.kinds ?? [])
+        params.append('kind', kind);
+}
+async function describeFailure(response) {
+    let detail = '';
+    try {
+        const body = (await response.json());
+        if (typeof body?.error === 'string')
+            detail = `: ${body.error}`;
+    }
+    catch {
+        // Non-JSON error body; the status is enough.
+    }
+    if (response.status === 401)
+        return `aivi host rejected the request (401)${detail}. This endpoint needs a bearer token that names a person.`;
+    return `aivi host returned HTTP ${response.status}${detail}`;
+}

package/dist/channel.d.ts

@@ -0,0 +1,184 @@
+/**
+ * The **channel** contract: how aivi carries a conversation on a chat
+ * platform. A channel is a core aivi concept shared with plugins, so the
+ * vocabulary is declared here — the host's engine and the platform modules
+ * both import it and follow it; nobody owns it by implementing it.
+ *
+ * What a module keeps is its gateway, routing, sending and commands; what
+ * the shared machinery owns is the inbox tables, the engine and the turn
+ * runner — those ship in the host, and the two narrow interfaces below are
+ * the contract's view of them: what the shared sequences call, and what the
+ * host's classes are checked against.
+ */
+import type { Run, RunState } from '@aivi/core';
+export interface DeliveryContext {
+    /** The run whose outcome this text delivers; absent on a module's own notice. */
+    run?: Run;
+    /** How that run ended; absent on a notice. */
+    state?: RunState;
+    /** Thread title for a notice without a run; a run's report is titled by its job. */
+    title?: string;
+}
+/** A re-entry is a job's result coming back: it always carries its run. */
+export type ReentryContext = DeliveryContext & {
+    run: Run;
+};
+/**
+ * What a chat platform adapter registers with the host (`services.channels.register`).
+ * Registering is what makes the module a report destination and a session owner:
+ * outcomes for sessions it owns re-enter its conversations as turns, and
+ * `report.to: "channel"` with its id posts through it.
+ */
+export interface ChannelModule {
+    /** What a conversation is **on**: `report.module`, table prefix, lease owner,
+     *  `metadata.aivi.origin`. Not the plugin registry's module id — that one is
+     *  the package name (`channel-discord`) and keys `config.json`, while this one
+     *  is the platform's short name (`discord`) and keys the database, so renaming
+     *  it would orphan every bound conversation that already exists. */
+    id: string;
+    /** This session is one of the module's conversations (bound or adopted). */
+    ownsSession(sessionId: string): boolean;
+    /** Bring a job outcome into the conversation bound to `sessionId` as a turn of kind `job`. */
+    reenter(sessionId: string, text: string, context: ReentryContext): Promise<void>;
+    /** Post text to a platform channel. Throw if aivi may not post there. */
+    post(channel: string, text: string, context: DeliveryContext): Promise<void>;
+    /** Whether a report to `channel` could be delivered; refuses a job before it spends anything. */
+    accepts(channel: string): boolean;
+    /** The platform channel a conversation lives in (a thread's parent, a DM itself), for "post it to this channel". */
+    channelOf(sessionId: string): Promise<string | undefined>;
+    /**
+     * How a person spends a link code on this platform, shown by `aivi link`
+     * ("DM the bot: /link <code>."). Redemption itself is the shared
+     * `redeemLink` helper — this is only the wording.
+     */
+    linkHint?: string;
+}
+/**
+ * How the shared engine talks back to a platform conversation. `edit` and
+ * `delete` power the progress placeholder; without `edit` progress falls back
+ * to silent, without `delete` the placeholder is edited into the reply.
+ */
+export interface ChannelDelivery {
+    /** Post the answer (or a chunk of it); return the platform's message id when it has one. */
+    send(conversation: string, text: string): Promise<string | undefined>;
+    edit?(conversation: string, messageId: string, text: string): Promise<void>;
+    delete?(conversation: string, messageId: string): Promise<void>;
+    /** Post the progress placeholder when it is not an ordinary message on this platform (Linear: an ephemeral thought); default `send`. */
+    placeholder?(conversation: string, text: string): Promise<string | undefined>;
+    /** Post a notice that is not an answer (a stop, a failure, going offline); default: edit the placeholder, else `send`. */
+    notice?(conversation: string, text: string): Promise<void>;
+}
+/**
+ * What differs between platforms in the shared machinery. `id` prefixes the
+ * inbox tables (`<id>_turns`), owns the leases (`<id>:<turn>`), the session ids
+ * (`ses_<id>_…`), the native message ids (`msg_<id>_…`) and is the session origin.
+ */
+export interface ChannelPlatform {
+    id: string;
+    /** Human name for session titles, prompt prefixes and error messages. */
+    label: string;
+    /** Message size limit in UTF-16 units; replies are split below it. */
+    replyLimit: number;
+    /** How a person's message is introduced to the agent; default `[<label> message from <name> (user <id>)]`. */
+    describeSpeaker?: (turn: {
+        name: string;
+        user: string;
+    }) => string;
+    /**
+     * What a turn changes besides its reply. `reply` (default, chat): an interrupted turn is
+     * discarded. `work` (workers editing a checkout): a turn interrupted by a restart ends
+     * `blocked` because nobody can tell whether the agent stopped; stops by choice still release.
+     */
+    effects?: 'reply' | 'work';
+    /** Platform wording for the engine's notices; the chat defaults otherwise. */
+    notices?: Partial<EngineNotices>;
+}
+/** The texts the shared engine posts into a conversation when a turn does not end with an answer. */
+export interface EngineNotices {
+    /** A chat turn ended knowably (the engine appends the short reason); Linear overrides via `notices` and never uses it. */
+    failed: string;
+    stopped: string;
+    notStarted: string;
+    offline: string;
+    offlineMidReply: string;
+    offlineQueued: string;
+    blocked: string;
+}
+export interface ChatCommandArgument {
+    name: string;
+    description: string;
+    required: boolean;
+    /** Discord offers choices for this argument from the named catalogue. */
+    autocomplete?: 'model';
+}
+/** One chat command, the same on every platform; the adapters translate names and arguments. */
+export interface ChatCommand {
+    name: string;
+    /** Under 100 characters: Discord's limit for a command description. */
+    description: string;
+    /** Acts on one conversation: refused where a slash command cannot name one (a threads-mode channel). */
+    conversation: boolean;
+    arguments: ChatCommandArgument[];
+}
+/**
+ * The name of a built-in chat command. The commands are shared channel
+ * vocabulary — the host's `CHAT_COMMANDS` list is typed against this union,
+ * so a name added here without a command, or a command without a name here,
+ * is a compile error.
+ */
+export type ChatCommandName = 'new' | 'status' | 'context' | 'search' | 'model' | 'stop' | 'queue' | 'jobs' | 'link' | 'help';
+/** A catalogue model as OpenCode names it, with an optional variant (`high`, `max`). */
+export interface ModelRef {
+    providerID: string;
+    modelID: string;
+    variant?: string;
+}
+export type TurnState = 'queued' | 'running' | 'replying' | 'sent' | 'blocked' | 'discarded';
+export type TurnKind = 'message' | 'job';
+/** One message's whole trip through the inbox, from a person's text to a sent reply. */
+export interface Turn {
+    id: string;
+    channel: string;
+    user: string;
+    name: string;
+    text: string;
+    session: string;
+    ready: boolean;
+    state: TurnState;
+    result: string | null;
+    error: string | null;
+    /** `message`: a person wrote it. `job`: aivi brings a job's outcome back into the conversation. */
+    kind: TurnKind;
+    /** Set when the conversation adopted a job's session: that session runs this agent in this directory, not the module's. */
+    agent: string | null;
+    directory: string | null;
+    /** Text posted in the conversation before any session existed (a script's output); context for the first turn. */
+    seed: string | null;
+    /** The conversation's model override (`/model`), applied to the session before each prompt; null means the agent's default. */
+    model: ModelRef | null;
+    /** Set by `bind` for workers: one turn at a time per issue across the module's conversations. */
+    project: string | null;
+    issue: string | null;
+}
+/**
+ * The conversation store as the shared sequences touch it. Every channel's
+ * `resolve` command ends the same way (release the blocked record, print
+ * the receipt, wake the host — the sequence in `./cli.ts`), and that is the
+ * one member the contract may name. The store itself is the host's
+ * `ConversationStore` class, checked against this interface; a module opens
+ * it with its own platform and binding.
+ */
+export interface ConversationStore {
+    /** Release the turn blocked on `id`, with the reason a person gave. */
+    resolve(id: string, reason: string): void;
+}
+/**
+ * The channel registry as a module meets it: registering is what makes a
+ * chat platform adapter a report destination and a session owner. The
+ * registry itself is the host's `Channels` class, checked against this
+ * interface; what the host does with a registered module is the engine's.
+ */
+export interface Channels {
+    /** Register once at module start; the returned function unregisters. */
+    register(module: ChannelModule): () => void;
+}

package/dist/channel.js

@@ -0,0 +1,13 @@
+/**
+ * The **channel** contract: how aivi carries a conversation on a chat
+ * platform. A channel is a core aivi concept shared with plugins, so the
+ * vocabulary is declared here — the host's engine and the platform modules
+ * both import it and follow it; nobody owns it by implementing it.
+ *
+ * What a module keeps is its gateway, routing, sending and commands; what
+ * the shared machinery owns is the inbox tables, the engine and the turn
+ * runner — those ship in the host, and the two narrow interfaces below are
+ * the contract's view of them: what the shared sequences call, and what the
+ * host's classes are checked against.
+ */
+export {};

package/dist/cli.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The operator-CLI contract an installable plugin package fills. Where
+ * `./setup` is the install-time subpath, `./cli` is the runtime one: a
+ * package that default-exports a factory `(ctx) => Command` from its `./cli`
+ * subpath has its command subtree mounted into the server CLI whenever the
+ * package is installed. The factory builds real commander — parsing, help,
+ * choices and variadics are commander's own, and the plugin declares
+ * `commander` itself — while `ctx` carries everything the plugin cannot
+ * know: the home, the store door, the host poke and the streams. The
+ * contract stays testable without a terminal.
+ */
+import type { LoadedConfig, OutputBlock } from '@aivi/core';
+import type * as prompts from '@clack/prompts';
+import type { ConversationStore } from './channel.ts';
+import type { Store } from './module.ts';
+/** What the machine this CLI runs on *is*: the one fact that decides command
+ *  membership. `home` is the aivi home this machine has, or absent when it has
+ *  none. The CLI resolves it once per run (AIVI_HOME, then the client record)
+ *  and hands it to every command provider; a provider that cannot run without
+ *  a home simply does not register the command — membership is decided by the
+ *  provider at mount time, never by hiding a command after the fact. */
+export interface MachineStatus {
+    home?: string | undefined;
+    /** The client record's path when this machine has one — the file `configure`
+     *  edits (where the host is, who signs in). The command exists only where
+     *  the file exists; `setup` creates the first one. Existence, not
+     *  parseability: a broken record is exactly what `configure` is for. */
+    clientConfig?: string | undefined;
+    /** True when this process is the far end of an exec session: the host
+     *  spawned it (`AIVI_EXEC_SESSION`) to run commands someone typed on
+     *  another machine. Providers decide from it — the plan's sets are carried
+     *  by the commands' own declarations, not by the channel: commands that
+     *  act on the machine you type on answer their guard line here, and
+     *  commands that would fight the session itself refuse theirs. */
+    remote?: boolean | undefined;
+}
+/** What the CLI hands a plugin's command factory: the same home the built-ins
+ *  see, the same stdout contract, and nothing platform-specific. */
+export interface PluginCliContext {
+    /** The machine's state, for commands that decide whether to exist here. */
+    machine: MachineStatus;
+    /** The aivi home that owns `config.json` and `.env`. */
+    home: string;
+    configPath: string;
+    /** The loaded, validated config; a command reads its own module block from it. */
+    loaded(): Promise<LoadedConfig>;
+    /** The home's SQLite store, open for the callback and closed after. */
+    withStore<T>(fn: (store: Store) => T | Promise<T>): Promise<T>;
+    /** The record on stdout — JSON whenever stdout is a pipe; on a terminal the
+     *  optional `output` renders as readable blocks (core's `print`). */
+    print(value: unknown, output?: OutputBlock[] | string): void;
+    /** A note on stderr: what was saved, what to restart, what survived. */
+    log(message: string): void;
+    /** Wake the running host so saved work dispatches without waiting. */
+    poke(): Promise<void>;
+    /** The very `@clack/prompts` module the runner renders with. One rule
+     *  across both plugin contracts: the runner hands its own module instance;
+     *  whoever is called owns the screen (two clacks animating one terminal
+     *  mangle each other), so a command opens one animation at a time and
+     *  settles it before returning. */
+    prompts: typeof prompts;
+}
+/**
+ * Open the module's own conversation store against the home store, release the
+ * blocked record, print the receipt, and wake the host so the freed worker
+ * dispatches without waiting. Every channel's `resolve` command ends with this
+ * exact sequence; keeping it in one place is what stops the poke from being
+ * dropped or the receipt from drifting when the contract changes. `openStore`
+ * supplies the module-specific store (it may close over the module's config).
+ */
+export declare function resolveBlocked(ctx: PluginCliContext, id: string | undefined, reason: unknown, openStore: (store: Store) => ConversationStore): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,26 @@
+/**
+ * The operator-CLI contract an installable plugin package fills. Where
+ * `./setup` is the install-time subpath, `./cli` is the runtime one: a
+ * package that default-exports a factory `(ctx) => Command` from its `./cli`
+ * subpath has its command subtree mounted into the server CLI whenever the
+ * package is installed. The factory builds real commander — parsing, help,
+ * choices and variadics are commander's own, and the plugin declares
+ * `commander` itself — while `ctx` carries everything the plugin cannot
+ * know: the home, the store door, the host poke and the streams. The
+ * contract stays testable without a terminal.
+ */
+/**
+ * Open the module's own conversation store against the home store, release the
+ * blocked record, print the receipt, and wake the host so the freed worker
+ * dispatches without waiting. Every channel's `resolve` command ends with this
+ * exact sequence; keeping it in one place is what stops the poke from being
+ * dropped or the receipt from drifting when the contract changes. `openStore`
+ * supplies the module-specific store (it may close over the module's config).
+ */
+export async function resolveBlocked(ctx, id, reason, openStore) {
+    await ctx.withStore(store => {
+        openStore(store).resolve(String(id), String(reason));
+        ctx.print({ resolved: true });
+    });
+    await ctx.poke();
+}

package/dist/dispatcher.d.ts

@@ -0,0 +1,67 @@
+/** The dispatcher contract: capacity as named pools. The dispatcher is the
+ *  host's capacity system — every pool is an endpoint (capacity, an optional
+ *  model, an optional fallback), and every service that works asks it for a
+ *  slot before working. Ticket work drew it first; voice rooms draw the same
+ *  pools, so a local box and a remote endpoint are pools like any other.
+ *
+ *  This is the narrow view a room holder needs (the host's `Dispatcher`
+ *  satisfies it): ask, be provided a session, work, release. The queue is
+ *  the dispatcher's memory, not yours: a full pool answers `queued` with an
+ *  id, and the callback you registered hears when that request lands as a
+ *  lease. No timers, no polling — capacity moves, you are told.
+ */
+export interface DispatcherLeaseRef {
+    id: string;
+    /** The pool whose slot this holds; a session keeps the pool it was born in. */
+    pool: string;
+    /** `preparing` means the session is not attached yet: `provide` it. */
+    state: 'preparing' | 'active' | 'expiring';
+    sessionId?: string;
+}
+export type DispatcherGrant = {
+    lease: DispatcherLeaseRef;
+}
+/** The pool is full and took the request: the callback hears when it lands. */
+ | {
+    queued: string;
+}
+/** `waiting`: the service already holds the pool's one queue place. */
+ | {
+    refused: 'full' | 'pool-gone' | 'waiting';
+    pool: string;
+};
+export interface Dispatcher {
+    /** Ask for a slot in a pool (absent: the `default` pool). A resume returns
+     *  to the pool its session was created in — that is what keeps a room's
+     *  conversation on the endpoint that made it. */
+    request(input: {
+        service: string;
+        pool?: string;
+        resume?: string;
+    }): DispatcherGrant;
+    /** Provide a preparing lease with its session: created with the pool's
+     *  model, or resumed with whatever it was born with. `create` says the
+     *  named session does not exist yet: make it real under that id, with the
+     *  pool's model — a caller that pre-allocates ids keeps them. `title` and
+     *  `metadata` ride the create: the aivi origin that dreaming reviews and
+     *  the name OpenCode's list shows are set where the session is born. */
+    provide(leaseId: string, work: {
+        agent: string;
+        directory: string;
+        sessionId?: string;
+        create?: boolean;
+        title?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<DispatcherLeaseRef>;
+    /** End the lease and open its slot to the queue. `pending` means the slot
+     *  stays held until a kill is confirmed — the dispatcher keeps watching. */
+    release(leaseId: string): Promise<{
+        ended: DispatcherLeaseRef;
+    } | {
+        pending: DispatcherLeaseRef;
+    }>;
+    /** Hear when one of this service's queued requests becomes a lease. */
+    registerCallback(service: string, callback: (requestId: string, lease: DispatcherLeaseRef) => void): void;
+    /** Lose a queue place and nothing more. */
+    cancel(requestId: string): void;
+}

package/dist/dispatcher.js

@@ -0,0 +1,13 @@
+/** The dispatcher contract: capacity as named pools. The dispatcher is the
+ *  host's capacity system — every pool is an endpoint (capacity, an optional
+ *  model, an optional fallback), and every service that works asks it for a
+ *  slot before working. Ticket work drew it first; voice rooms draw the same
+ *  pools, so a local box and a remote endpoint are pools like any other.
+ *
+ *  This is the narrow view a room holder needs (the host's `Dispatcher`
+ *  satisfies it): ask, be provided a session, work, release. The queue is
+ *  the dispatcher's memory, not yours: a full pool answers `queued` with an
+ *  id, and the callback you registered hears when that request lands as a
+ *  lease. No timers, no polling — capacity moves, you are told.
+ */
+export {};