@monosmith/plugin-sdk 0.0.0-stage → 0.2.0

package/framing/frame-message.algorithm.d.ts

@@ -0,0 +1,5 @@
+/**
+ * One message as the protocol frames it: `Content-Length: <bytes>`, a blank
+ * line (CRLF CRLF), then the body. The length counts bytes of UTF-8, not characters.
+ */
+export declare function frameMessage(body: string): Buffer;

package/framing/frame-message.algorithm.js

@@ -0,0 +1,8 @@
+/**
+ * One message as the protocol frames it: `Content-Length: <bytes>`, a blank
+ * line (CRLF CRLF), then the body. The length counts bytes of UTF-8, not characters.
+ */
+export function frameMessage(body) {
+    const bytes = Buffer.from(body, 'utf8');
+    return Buffer.concat([Buffer.from(`Content-Length: ${bytes.length}\r\n\r\n`, 'ascii'), bytes]);
+}

package/framing/frame-reader.store.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Cuts a byte stream into the bodies of its frames. Bytes arrive in chunks of
+ * any size; {@link FrameReader.push} returns every body a chunk completed.
+ * Headers end at a blank line (CRLF or LF alone, as the Go SDK reads them),
+ * `Content-Length` is matched without regard to case, and a header that is not
+ * `Name: value`, a length that is not a number from 0 to 64 MiB, or a header
+ * block without a length is a {@link FramingError}.
+ */
+export declare class FrameReader {
+    #private;
+    /** Bytes received that are not part of a complete frame yet. */
+    get pending(): number;
+    /** Adds the bytes that arrived and returns the body of every frame they completed, in order. */
+    push(chunk: Uint8Array): string[];
+}

package/framing/frame-reader.store.js

@@ -0,0 +1,59 @@
+import { MAX_MESSAGE_BYTES } from '../protocol/index.js';
+import { FramingError } from './framing.error.js';
+/**
+ * Cuts a byte stream into the bodies of its frames. Bytes arrive in chunks of
+ * any size; {@link FrameReader.push} returns every body a chunk completed.
+ * Headers end at a blank line (CRLF or LF alone, as the Go SDK reads them),
+ * `Content-Length` is matched without regard to case, and a header that is not
+ * `Name: value`, a length that is not a number from 0 to 64 MiB, or a header
+ * block without a length is a {@link FramingError}.
+ */
+export class FrameReader {
+    #buffer = Buffer.alloc(0);
+    /** The length and where the body starts, or null while the header is incomplete. */
+    #readHeader() {
+        let length = -1;
+        let position = 0;
+        for (;;) {
+            const newline = this.#buffer.indexOf(0x0A, position);
+            if (newline === -1)
+                return null;
+            const line = this.#buffer.subarray(position, newline).toString('ascii').replace(/[\r\n]+$/, '');
+            position = newline + 1;
+            if (line === '')
+                break;
+            const colon = line.indexOf(':');
+            if (colon === -1)
+                throw new FramingError(`malformed header "${line}"`);
+            if (line.slice(0, colon).trim().toLowerCase() !== 'content-length')
+                continue;
+            const text = line.slice(colon + 1).trim();
+            const parsed = /^\d+$/.test(text) ? Number(text) : NaN;
+            if (!Number.isSafeInteger(parsed) || parsed > MAX_MESSAGE_BYTES)
+                throw new FramingError(`invalid Content-Length "${line.slice(colon + 1)}"`);
+            length = parsed;
+        }
+        if (length < 0)
+            throw new FramingError('message without Content-Length');
+        return { length, bodyStart: position };
+    }
+    /** Bytes received that are not part of a complete frame yet. */
+    get pending() {
+        return this.#buffer.length;
+    }
+    /** Adds the bytes that arrived and returns the body of every frame they completed, in order. */
+    push(chunk) {
+        this.#buffer = this.#buffer.length === 0 ? Buffer.from(chunk) : Buffer.concat([this.#buffer, chunk]);
+        const bodies = [];
+        for (;;) {
+            const header = this.#readHeader();
+            if (header === null)
+                return bodies;
+            const end = header.bodyStart + header.length;
+            if (this.#buffer.length < end)
+                return bodies;
+            bodies.push(this.#buffer.subarray(header.bodyStart, end).toString('utf8'));
+            this.#buffer = this.#buffer.subarray(end);
+        }
+    }
+}

package/framing/framing.error.d.ts

@@ -0,0 +1,4 @@
+/** The bytes on the stream are not a sequence of frames: a malformed header, a missing or invalid Content-Length. The stream cannot be trusted after it. */
+export declare class FramingError extends Error {
+    constructor(message: string);
+}

package/framing/framing.error.js

@@ -0,0 +1,7 @@
+/** The bytes on the stream are not a sequence of frames: a malformed header, a missing or invalid Content-Length. The stream cannot be trusted after it. */
+export class FramingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FramingError';
+    }
+}

package/framing/index.d.ts

@@ -0,0 +1,3 @@
+export { frameMessage } from './frame-message.algorithm.ts';
+export { FrameReader } from './frame-reader.store.ts';
+export { FramingError } from './framing.error.ts';

package/framing/index.js

@@ -0,0 +1,3 @@
+export { frameMessage } from './frame-message.algorithm.js';
+export { FrameReader } from './frame-reader.store.js';
+export { FramingError } from './framing.error.js';

package/host/call-interrupted.error.d.ts

@@ -0,0 +1,16 @@
+import type { RpcError } from '../protocol/index.ts';
+/** Why the host stopped waiting for a call. */
+export type InterruptionReason = 'cancelled' | 'timeout';
+/**
+ * A call the host gave up on, because its `signal` aborted (`cancelled`) or its
+ * time ran out (`timeout`). `killed` says the plugin did not stop in time
+ * and was killed, which also fails every other call in flight to it. When the
+ * plugin answered while being stopped, `response` is its error (the
+ * request-cancelled code, usually).
+ */
+export declare class CallInterruptedError extends Error {
+    readonly reason: InterruptionReason;
+    readonly killed: boolean;
+    readonly response?: RpcError;
+    constructor(message: string, reason: InterruptionReason, killed: boolean, response?: RpcError);
+}

package/host/call-interrupted.error.js

@@ -0,0 +1,20 @@
+/**
+ * A call the host gave up on, because its `signal` aborted (`cancelled`) or its
+ * time ran out (`timeout`). `killed` says the plugin did not stop in time
+ * and was killed, which also fails every other call in flight to it. When the
+ * plugin answered while being stopped, `response` is its error (the
+ * request-cancelled code, usually).
+ */
+export class CallInterruptedError extends Error {
+    reason;
+    killed;
+    response;
+    constructor(message, reason, killed, response) {
+        super(message, response === undefined ? undefined : { cause: response });
+        this.name = 'CallInterruptedError';
+        this.reason = reason;
+        this.killed = killed;
+        if (response !== undefined)
+            this.response = response;
+    }
+}

package/host/connect-plugin.use-case.d.ts

@@ -0,0 +1,26 @@
+import type { SmithPlugin } from '../serve/index.ts';
+import type { HostOptions } from './host-options.contract.ts';
+import { PluginClient } from './plugin-client.client.ts';
+/** The streams of a plugin that is somewhere else: its responses to read, its requests to write. */
+export interface PluginStreams {
+    /** What the plugin writes (its standard output). */
+    input: AsyncIterable<Uint8Array>;
+    /** What the plugin reads (its standard input). */
+    output: {
+        write: (chunk: Buffer, callback: (error?: Error | null) => void) => unknown;
+        end: () => unknown;
+    };
+}
+/**
+ * Performs the handshake with a plugin reachable through a pair of streams.
+ * Closing the client shuts the plugin down and ends the streams; there is no
+ * process to kill.
+ */
+export declare function connectPlugin(streams: PluginStreams, options: HostOptions): Promise<PluginClient>;
+/**
+ * Serves a plugin object in this process over pipes and connects to it, the way
+ * the Go SDK's tests serve a plugin with `serve.Serve` over `io.Pipe`: the
+ * real framing, handshake and dispatch, no process. Closing the client waits
+ * for the serve loop to end.
+ */
+export declare function connectInProcess(plugin: SmithPlugin, options: HostOptions): Promise<PluginClient>;

package/host/connect-plugin.use-case.js

@@ -0,0 +1,44 @@
+import { PassThrough } from 'node:stream';
+import { serveStreams } from '../serve/index.js';
+import { PluginClient } from './plugin-client.client.js';
+/**
+ * Performs the handshake with a plugin reachable through a pair of streams.
+ * Closing the client shuts the plugin down and ends the streams; there is no
+ * process to kill.
+ */
+export function connectPlugin(streams, options) {
+    return PluginClient.open({
+        input: streams.input,
+        output: streams.output,
+        kill: () => { streams.output.end(); },
+        finish: () => Promise.resolve(null),
+    }, options);
+}
+/**
+ * Serves a plugin object in this process over pipes and connects to it, the way
+ * the Go SDK's tests serve a plugin with `serve.Serve` over `io.Pipe`: the
+ * real framing, handshake and dispatch, no process. Closing the client waits
+ * for the serve loop to end.
+ */
+export async function connectInProcess(plugin, options) {
+    const toPlugin = new PassThrough();
+    const fromPlugin = new PassThrough();
+    const served = (async () => {
+        try {
+            await serveStreams(plugin, { input: toPlugin, output: fromPlugin, log: () => { } });
+            return null;
+        }
+        catch (error) {
+            return error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            fromPlugin.end();
+        }
+    })();
+    return await PluginClient.open({
+        input: fromPlugin,
+        output: toPlugin,
+        kill: () => { toPlugin.end(); },
+        finish: () => served,
+    }, options);
+}

package/host/host-options.contract.d.ts

@@ -0,0 +1,34 @@
+import type { Peer } from '../protocol/index.ts';
+/** What the host tells the plugin, and how long it waits. */
+export interface HostOptions {
+    /** The absolute workspace root sent in `initialize`. A plugin that reads manifests resolves them against it. */
+    workspaceRoot: string;
+    /** The host's name and version. Default: `smith`, `dev`. */
+    host?: Peer;
+    /** How long `initialize` may take. Default: 30 seconds. */
+    initializeTimeoutMs?: number;
+    /** How long a plugin has to answer after it was asked to stop (or, for one that cannot be asked, after the caller cancelled) before it is killed. Default: 5 seconds. */
+    cancelGraceMs?: number;
+}
+/** Options of {@link startPlugin}: a plugin process to launch. */
+export interface StartOptions extends HostOptions {
+    /** The plugin's argv: the program and its arguments. */
+    command: string[];
+    /** The environment. Default: the current one. `SMITH_PLUGIN=1` is set in it unless it already has a value, as smith does. */
+    env?: NodeJS.ProcessEnv;
+    /** The plugin's working directory. Default: the current one. */
+    cwd?: string;
+    /** What happens to the plugin's standard error, where it logs. Default: it goes to this process's standard error. */
+    stderr?: 'inherit' | 'ignore';
+}
+/** How long a plugin has to answer after it was asked to stop, before the host kills it. */
+export declare const DEFAULT_CANCEL_GRACE_MS = 5000;
+/** The longest a call may take unless the caller says otherwise: generate and publish run real toolchains. */
+export declare const DEFAULT_CALL_TIMEOUT_MS: number;
+/** Options of one {@link PluginClient.call}. */
+export interface CallOptions {
+    /** How long the plugin may take. On expiry the plugin process is killed: its stream can no longer be trusted. Default: 2 minutes. */
+    timeoutMs?: number;
+    /** Aborting it cancels the call: the plugin is sent `cancel` if it advertised it, and the call ends within the grace period. */
+    signal?: AbortSignal;
+}

package/host/host-options.contract.js

@@ -0,0 +1,4 @@
+/** How long a plugin has to answer after it was asked to stop, before the host kills it. */
+export const DEFAULT_CANCEL_GRACE_MS = 5000;
+/** The longest a call may take unless the caller says otherwise: generate and publish run real toolchains. */
+export const DEFAULT_CALL_TIMEOUT_MS = 2 * 60 * 1000;

package/host/index.d.ts

@@ -0,0 +1,9 @@
+export { PluginClient } from './plugin-client.client.ts';
+export type { PluginConnection } from './plugin-client.client.ts';
+export { startPlugin } from './start-plugin.use-case.ts';
+export { connectInProcess, connectPlugin } from './connect-plugin.use-case.ts';
+export type { PluginStreams } from './connect-plugin.use-case.ts';
+export { CallInterruptedError } from './call-interrupted.error.ts';
+export type { InterruptionReason } from './call-interrupted.error.ts';
+export { DEFAULT_CALL_TIMEOUT_MS, DEFAULT_CANCEL_GRACE_MS } from './host-options.contract.ts';
+export type { CallOptions, HostOptions, StartOptions } from './host-options.contract.ts';

package/host/index.js

@@ -0,0 +1,5 @@
+export { PluginClient } from './plugin-client.client.js';
+export { startPlugin } from './start-plugin.use-case.js';
+export { connectInProcess, connectPlugin } from './connect-plugin.use-case.js';
+export { CallInterruptedError } from './call-interrupted.error.js';
+export { DEFAULT_CALL_TIMEOUT_MS, DEFAULT_CANCEL_GRACE_MS } from './host-options.contract.js';

package/host/plugin-client.client.d.ts

@@ -0,0 +1,61 @@
+import type { InitializeResult, MethodName, ParamsOf, ResultOf } from '../protocol/index.ts';
+import type { CallOptions, HostOptions } from './host-options.contract.ts';
+/** The two ends of the pipe to a plugin, and what to do with the plugin when the stream cannot be trusted. */
+export interface PluginConnection {
+    /** The plugin's responses. */
+    input: AsyncIterable<Uint8Array>;
+    /** The plugin's requests. */
+    output: {
+        write: (chunk: Buffer, callback: (error?: Error | null) => void) => unknown;
+        end: () => unknown;
+    };
+    /** Called when the plugin did not answer in time: ends the plugin, if it is a process. */
+    kill: () => void;
+    /** Resolves once the plugin has gone, with the reason it did not end well (or `null`). Called by {@link PluginClient.close}. */
+    finish: (graceMs: number) => Promise<string | null>;
+}
+/**
+ * The host's side of a connection to one initialized plugin, for a plugin
+ * author's tests (smith itself is the host in real use). It never has more
+ * requests in flight than the plugin declared in `concurrency`, as smith does:
+ * with the default of one, calls are serialised, each waiting for the one
+ * before it to be answered. Each call has a timeout and may be cancelled with
+ * an `AbortSignal`. Open one with {@link startPlugin} (a process),
+ * {@link connectPlugin} (streams) or {@link connectInProcess} (a plugin object
+ * served in this process).
+ */
+export declare class PluginClient {
+    #private;
+    /** Performs the handshake on a connection. */
+    static open(connection: PluginConnection, options: HostOptions): Promise<PluginClient>;
+    /** What the plugin answered to `initialize`: identity, kind, roles, capabilities. */
+    info: InitializeResult;
+    private constructor();
+    /**
+     * Sends one request and resolves with its decoded result. An error answer
+     * rejects with an {@link RpcError} carrying its code. The call waits for a
+     * place first, so the plugin never has more requests in flight than it
+     * declared; the timeout counts from the moment the request is sent.
+     *
+     * When `options.signal` aborts or the time runs out the host stops waiting.
+     * A plugin that advertised `cancel` is sent the notification and has the
+     * grace period to answer: with the result it had already (the call resolves),
+     * or an error (the call rejects with a {@link CallInterruptedError} carrying
+     * it). A plugin that does not answer in time is killed, because its stream can
+     * no longer be trusted, and the call rejects; a plugin that cannot be asked
+     * to stop is killed at once on a timeout, and after the grace period when
+     * the caller cancelled.
+     */
+    call<M extends MethodName>(method: M, params: ParamsOf<M>, options?: CallOptions): Promise<ResultOf<M>>;
+    call(method: string, params?: unknown, options?: CallOptions): Promise<unknown>;
+    /** How long the plugin has to answer after it was asked to stop. */
+    get cancelGraceMs(): number;
+    /** The most requests this client has had in flight at once. */
+    get peakInFlight(): number;
+    /** Sends a message that gets no answer, such as `cancel`. */
+    notify(method: string, params: unknown): Promise<void>;
+    /** Whether the plugin advertised a method: `initialize` and `shutdown` always, the others by their capability. */
+    supports(method: string): boolean;
+    /** Asks the plugin to shut down and waits briefly for it to go. Rejects if it did not go quietly. */
+    close(): Promise<void>;
+}

package/host/plugin-client.client.js

@@ -0,0 +1,297 @@
+import { decodeResult, encodeParams, parseResponse, writeNotification, writeRequest } from '../codec/index.js';
+import { inFlightLimit } from '../concurrency/index.js';
+import { FrameReader, frameMessage } from '../framing/index.js';
+import { PROTOCOL_VERSION, RpcError, protocolSchema } from '../protocol/index.js';
+import { CallInterruptedError } from './call-interrupted.error.js';
+import { DEFAULT_CALL_TIMEOUT_MS, DEFAULT_CANCEL_GRACE_MS } from './host-options.contract.js';
+function writeFrame(output, frame) {
+    return new Promise((resolve, reject) => {
+        output.write(frame, (error) => {
+            if (error === null || error === undefined)
+                resolve();
+            else
+                reject(error);
+        });
+    });
+}
+function messageOf(thrown) {
+    return thrown instanceof Error ? thrown.message : String(thrown);
+}
+/**
+ * The host's side of a connection to one initialized plugin, for a plugin
+ * author's tests (smith itself is the host in real use). It never has more
+ * requests in flight than the plugin declared in `concurrency`, as smith does:
+ * with the default of one, calls are serialised, each waiting for the one
+ * before it to be answered. Each call has a timeout and may be cancelled with
+ * an `AbortSignal`. Open one with {@link startPlugin} (a process),
+ * {@link connectPlugin} (streams) or {@link connectInProcess} (a plugin object
+ * served in this process).
+ */
+export class PluginClient {
+    /** Performs the handshake on a connection. */
+    static async open(connection, options) {
+        const client = new PluginClient(connection, options.cancelGraceMs ?? DEFAULT_CANCEL_GRACE_MS);
+        try {
+            client.info = await client.call('initialize', {
+                protocolVersions: [PROTOCOL_VERSION],
+                host: options.host ?? { name: 'smith', version: 'dev' },
+                workspaceRoot: options.workspaceRoot,
+            }, { timeoutMs: options.initializeTimeoutMs ?? 30_000 });
+        }
+        catch (error) {
+            connection.kill();
+            throw new Error(`initializing plugin: ${messageOf(error)}`, { cause: error });
+        }
+        if (client.info.protocolVersion !== PROTOCOL_VERSION) {
+            connection.kill();
+            throw new Error(`plugin ${client.info.plugin.name} chose protocol version ${client.info.protocolVersion}, host speaks ${PROTOCOL_VERSION}`);
+        }
+        client.#limit = inFlightLimit(client.info.concurrency);
+        return client;
+    }
+    #connection;
+    #waiters = new Map();
+    #queue = [];
+    #graceMs;
+    #lost;
+    #nextId = 0;
+    #limit = 1;
+    #inFlight = 0;
+    #peak = 0;
+    /** What the plugin answered to `initialize`: identity, kind, roles, capabilities. */
+    info;
+    constructor(connection, graceMs) {
+        this.#connection = connection;
+        this.#graceMs = graceMs;
+        void this.#readResponses();
+    }
+    /** Waits for a place among the requests that may be in flight; rejects if `signal` aborts first. */
+    #acquire(signal) {
+        if (signal?.aborted === true)
+            return Promise.reject(new CallInterruptedError('cancelled before it was sent', 'cancelled', false));
+        if (this.#inFlight < this.#limit) {
+            this.#take();
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            const entry = {
+                grant: () => {
+                    signal?.removeEventListener('abort', onAbort);
+                    this.#take();
+                    resolve();
+                },
+            };
+            const onAbort = () => {
+                const at = this.#queue.indexOf(entry);
+                if (at !== -1)
+                    this.#queue.splice(at, 1);
+                reject(new CallInterruptedError('cancelled before it was sent', 'cancelled', false));
+            };
+            signal?.addEventListener('abort', onAbort, { once: true });
+            this.#queue.push(entry);
+        });
+    }
+    #take() {
+        this.#inFlight++;
+        this.#peak = Math.max(this.#peak, this.#inFlight);
+    }
+    #release() {
+        this.#inFlight--;
+        this.#queue.shift()?.grant();
+    }
+    async #send(method, params, timeoutMs, signal) {
+        if (this.#lost !== undefined)
+            throw new Error(`${method}: plugin stopped answering: ${this.#lost.message}`, { cause: this.#lost });
+        const id = ++this.#nextId;
+        const body = writeRequest(id, method, params === undefined ? undefined : encodeParams(method, params));
+        const answer = new Promise((resolve) => { this.#waiters.set(id, { settle: resolve }); });
+        try {
+            await writeFrame(this.#connection.output, frameMessage(body));
+        }
+        catch (error) {
+            this.#waiters.delete(id);
+            throw new Error(`${method}: plugin is not accepting requests: ${messageOf(error)}`, { cause: error });
+        }
+        let timer;
+        let onAbort;
+        const interrupted = new Promise((resolve) => {
+            timer = setTimeout(() => { resolve('timeout'); }, timeoutMs);
+            onAbort = () => { resolve('cancelled'); };
+            if (signal?.aborted === true)
+                resolve('cancelled');
+            else
+                signal?.addEventListener('abort', onAbort, { once: true });
+        });
+        try {
+            const winner = await Promise.race([answer, interrupted]);
+            if (typeof winner !== 'string') {
+                this.#waiters.delete(id);
+                return this.#decode(method, winner);
+            }
+            return await this.#giveUp(method, id, answer, winner, timeoutMs);
+        }
+        finally {
+            clearTimeout(timer);
+            if (onAbort !== undefined)
+                signal?.removeEventListener('abort', onAbort);
+        }
+    }
+    #decode(method, outcome) {
+        if ('error' in outcome)
+            throw new Error(`${method}: plugin stopped answering: ${outcome.error.message}`, { cause: outcome.error });
+        try {
+            const response = parseResponse(outcome.body);
+            if (response.error !== null)
+                throw new RpcError(response.error.code, response.error.message);
+            return decodeResult(method, response.result);
+        }
+        catch (error) {
+            if (error instanceof RpcError)
+                throw error;
+            throw new Error(`${method}: plugin stopped answering: ${messageOf(error)}`, { cause: error });
+        }
+    }
+    /**
+     * The end of a call whose signal aborted or whose time ran out. A plugin that
+     * advertised cancel is sent the notification and has the grace period to
+     * answer; one that cannot be asked is killed at once when the time ran out,
+     * and after the grace period when the caller cancelled. A plugin that does not
+     * answer in time is killed, and every other call in flight to it fails.
+     */
+    async #giveUp(method, id, answer, reason, timeoutMs) {
+        const asked = this.supports('cancel');
+        if (asked) {
+            try {
+                await this.notify('cancel', { id });
+            }
+            catch {
+                // The plugin is gone; waiting for the answer below reports how it went.
+            }
+        }
+        if (asked || reason === 'cancelled') {
+            let timer;
+            const grace = new Promise((resolve) => {
+                timer = setTimeout(() => { resolve('expired'); }, this.#graceMs);
+            });
+            const winner = await Promise.race([answer, grace]);
+            clearTimeout(timer);
+            if (winner !== 'expired') {
+                this.#waiters.delete(id);
+                return this.#answeredAfterStopping(method, winner, reason, timeoutMs);
+            }
+        }
+        this.#waiters.delete(id);
+        this.#connection.kill();
+        if (reason === 'timeout')
+            throw new CallInterruptedError(`${method}: plugin did not answer within ${timeoutMs}ms`, reason, true);
+        throw new CallInterruptedError(`${method}: cancelled; the plugin did not stop within ${this.#graceMs}ms and was killed`, reason, true);
+    }
+    /** The plugin answered while the host was giving up: a result is the work finished in time, and is the call's result. */
+    #answeredAfterStopping(method, outcome, reason, timeoutMs) {
+        try {
+            return this.#decode(method, outcome);
+        }
+        catch (error) {
+            const what = reason === 'timeout' ? `did not answer within ${timeoutMs}ms` : 'cancelled';
+            throw new CallInterruptedError(`${method}: ${what}: ${messageOf(error)}`, reason, false, error instanceof RpcError ? error : undefined);
+        }
+    }
+    async #readResponses() {
+        const reader = new FrameReader();
+        try {
+            for await (const chunk of this.#connection.input) {
+                for (const body of reader.push(chunk))
+                    this.#deliver(body);
+            }
+            this.#lose(new Error('EOF'));
+        }
+        catch (error) {
+            this.#lose(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    #deliver(body) {
+        let id;
+        try {
+            id = parseResponse(body).id;
+        }
+        catch (error) {
+            // A malformed response cannot be attributed to a call: the stream is lost.
+            this.#lose(new Error(`malformed response: ${messageOf(error)}`, { cause: error }));
+            return;
+        }
+        if (id === null)
+            return;
+        const waiter = this.#waiters.get(id);
+        if (waiter === undefined)
+            return;
+        this.#waiters.delete(id);
+        waiter.settle({ body });
+    }
+    #lose(error) {
+        this.#lost = error;
+        const waiting = this.#waiters;
+        this.#waiters = new Map();
+        for (const waiter of waiting.values())
+            waiter.settle({ error });
+    }
+    async call(method, params, options = {}) {
+        const timeoutMs = options.timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
+        if (method === 'shutdown')
+            return await this.#send(method, params, timeoutMs, options.signal); // it must reach a plugin that is busy
+        try {
+            await this.#acquire(options.signal);
+        }
+        catch (error) {
+            if (error instanceof CallInterruptedError)
+                throw new CallInterruptedError(`${method}: ${error.message}`, error.reason, false);
+            throw error;
+        }
+        try {
+            return await this.#send(method, params, timeoutMs, options.signal);
+        }
+        finally {
+            this.#release();
+        }
+    }
+    /** How long the plugin has to answer after it was asked to stop. */
+    get cancelGraceMs() {
+        return this.#graceMs;
+    }
+    /** The most requests this client has had in flight at once. */
+    get peakInFlight() {
+        return this.#peak;
+    }
+    /** Sends a message that gets no answer, such as `cancel`. */
+    async notify(method, params) {
+        if (this.#lost !== undefined)
+            throw new Error(`${method}: plugin stopped answering: ${this.#lost.message}`, { cause: this.#lost });
+        try {
+            const body = writeNotification(method, encodeParams(method, params));
+            await writeFrame(this.#connection.output, frameMessage(body));
+        }
+        catch (error) {
+            throw new Error(`${method}: plugin is not accepting requests: ${messageOf(error)}`, { cause: error });
+        }
+    }
+    /** Whether the plugin advertised a method: `initialize` and `shutdown` always, the others by their capability. */
+    supports(method) {
+        if (method === 'initialize' || method === 'shutdown')
+            return true;
+        const capability = Object.hasOwn(protocolSchema['x-methods'], method) ? protocolSchema['x-methods'][method].capability : null;
+        const advertised = this.info?.capabilities;
+        return capability !== null && advertised?.[capability] === true;
+    }
+    /** Asks the plugin to shut down and waits briefly for it to go. Rejects if it did not go quietly. */
+    async close() {
+        try {
+            await this.call('shutdown', {}, { timeoutMs: 5000 });
+        }
+        catch {
+            // A plugin that is already gone cannot be asked; waiting for it below reports how it went.
+        }
+        this.#connection.output.end();
+        const trouble = await this.#connection.finish(5000);
+        if (trouble !== null)
+            throw new Error(trouble);
+    }
+}

package/host/start-plugin.use-case.d.ts

@@ -0,0 +1,10 @@
+import type { StartOptions } from './host-options.contract.ts';
+import { PluginClient } from './plugin-client.client.ts';
+/**
+ * Launches a plugin process and performs the handshake, as smith does: the
+ * plugin's argv, `SMITH_PLUGIN=1` in its environment, its standard input and
+ * output as the protocol's channel, its standard error forwarded to this
+ * process's. Close the client when done: it asks the plugin to shut down and
+ * kills it if it does not go.
+ */
+export declare function startPlugin(options: StartOptions): Promise<PluginClient>;