@softov/ahpc 0.1.0

package/dist/src/ahp/live.d.ts

@@ -0,0 +1,160 @@
+import type { Published } from './publish.js';
+import type { HostConnection } from './connection.js';
+/**
+ * The other implementation of the seam: a real agent host, over a WebSocket.
+ *
+ * `fakeHost` is a script and this is a socket, and nothing above either of them
+ * can tell which is which - that is what `HostConnection` is for. Point it at a
+ * host with `--host ws://…` and the same screens drive somebody's editor.
+ *
+ * **Reducers are the host's, not ours.** The protocol ships a client library
+ * with the transport, the subscription fan-out and a generated reducer per
+ * channel, and reimplementing eighty typed mutations here would be inventing a
+ * second answer to "what is the state now". So the package is loaded at
+ * runtime and everything below is translation: its state shapes into the
+ * flattened ones in `types.ts`, and back out as the actions a client is
+ * allowed to dispatch.
+ *
+ * It is an **optional** dependency, because the example has to run, and be
+ * checked, with nothing installed:
+ *
+ * ```
+ * npm install @microsoft/agent-host-protocol
+ * ```
+ *
+ * Written against protocol 0.9.0, from the package's own `src/types/`. What it
+ * speaks is the subset this client needs: `initialize`, `listSessions`,
+ * `subscribe`, `createSession`, `disposeSession`, `resolveSessionConfig`, and
+ * the seven client-dispatchable actions that drive and answer a turn.
+ */
+export interface LiveHostOptions {
+    /** `ws://host:port/…`, as the host advertises it. */
+    url: string;
+    /** A bearer token, if the host is behind one. Appended as `?tkn=`. */
+    token?: string;
+    clientId?: string;
+    /** Told when the socket drops, so the badge can stop claiming otherwise. */
+    onState?(state: 'connecting' | 'connected' | 'offline'): void;
+    /**
+     * Told when the host refuses one channel, in the host's own words.
+     *
+     * Separate from `onState` because they mean opposite things: a refusal is
+     * the host answering, and reporting it as a lost connection sends somebody
+     * to debug their network over a session whose agent has simply gone.
+     */
+    onRefusal?(uri: string, message: string): void;
+    /**
+     * Open a transport, in place of a WebSocket to `url`.
+     *
+     * The seam a test drives: a connection is the one thing here that cannot be
+     * scripted from above, because `fakeHost` implements the seam this file
+     * produces rather than the protocol underneath it. Called once per attempt,
+     * so a reconnect asks for a new one.
+     */
+    connect?(): Promise<unknown>;
+    /**
+     * How long to wait before each attempt to come back, in milliseconds.
+     *
+     * The last entry repeats for as long as the host stays away. Given in full
+     * rather than as a formula so a test can ask for no waiting at all, and so
+     * the schedule is a thing that can be read.
+     */
+    backoff?: readonly number[];
+    /** How often to ping an otherwise silent connection. `0` sends none. */
+    keepaliveMs?: number;
+    /** How long to hold a channel nobody is reading before letting it go. */
+    lingerMs?: number;
+    /**
+     * Told when this client stopped short of everything the host had.
+     *
+     * Not a refusal - the host answered, and answered fully. It is this client
+     * declining to walk a catalogue past the point where walking it is the
+     * wrong thing to be doing, and a person is owed the sentence.
+     */
+    onLimit?(message: string): void;
+    /**
+     * Work the host is doing, by its own token.
+     *
+     * `null` means that token is finished. The specification's own example is a
+     * harness being downloaded before a session can start, which is exactly the
+     * wait that looked like nothing happening.
+     */
+    onProgress?(token: string, message: string | null): void;
+    /**
+     * The host wants a token before it will go on.
+     *
+     * `reason: 'expired'` is the one that matters: `authentication.md` says the
+     * client MUST acquire a new credential and MUST NOT blindly replay the one
+     * that was challenged. Arrives either as the `auth/required` notification or
+     * as the `data` on any `-32007`, which the specification says may come back
+     * from **any** command rather than only from `authenticate`.
+     */
+    onAuthRequired?(resources: {
+        resource: string;
+        description?: string;
+    }[], reason?: string): void;
+    /**
+     * One log record the host emitted, flattened out of OTLP.
+     *
+     * `telemetry-channel.md` is a thin pass-through: the payload is an
+     * OTLP/JSON `ExportLogsServiceRequest` verbatim, nested resource by scope by
+     * record. What a reader wants is a line, so the nesting is walked here.
+     */
+    onLog?(record: {
+        at?: string;
+        severity?: string;
+        body: string;
+        attributes: Record<string, string>;
+    }): void;
+    /**
+     * What this client serves back, when it was told to serve anything.
+     *
+     * Absent means a `publish()` that refuses everything, which is the default
+     * and the safe one - a client that offers its filesystem to whichever host
+     * it connects to is a mistake, not a feature.
+     */
+    publish?: Published;
+}
+export declare class MissingProtocolPackage extends Error {
+    constructor();
+}
+/**
+ * The activity bits, from what this client can see rather than what it was told.
+ *
+ * There is no `session/statusChanged` in the protocol. A subscribed client is
+ * told `session/activityChanged` - a word - and the reducer keeps that word in
+ * `activity` and deliberately leaves `status` alone; the only actions that
+ * move `status` are the input-needed pair and the read and archived flags. So
+ * on a live session the activity bits only ever go up. Answering a question
+ * clears `InputNeeded` and leaves `InProgress` set, which the reducer's own
+ * comment calls falling back to in-progress, and nothing afterwards takes it
+ * off - a session goes on saying it is working through every turn that
+ * follows, until something re-reads the catalogue.
+ *
+ * Everything the bits are about is already here: whether a turn is running,
+ * whether something is waiting on a person, and whether the last turn failed.
+ * The order is the host's own - what is wanted, then what is happening, then
+ * what went wrong - and the session's own flags are carried through untouched,
+ * because read and archived are not about activity at all.
+ */
+export declare function activityOf(status: number, asked: boolean, running: boolean, failed: boolean): number;
+/**
+ * Reduce one action, or say so and go on listening.
+ *
+ * A reducer is handed whatever the host sent, and a host that sends a
+ * malformed action throws inside it - `session/inputNeededSet` without its
+ * `request` is `action.request.id` on undefined, which is a `TypeError` and
+ * not an RPC error. Thrown out of a `for await` it rejects the whole loop and
+ * takes the subscription with it, so the session goes deaf: the block waiting
+ * on a person never clears, the status never moves, and the only sign of any
+ * of it is a sentence about a property of undefined on the status bar.
+ *
+ * One word this client cannot read is not a reason to stop reading the rest
+ * of them. The action is dropped, the state it would have changed is left as
+ * it was, and it is said out loud - because a client quietly ignoring what a
+ * host tells it is the other way to be wrong here.
+ */
+export declare function applyAction<T>(reduce: (state: T, action: never) => unknown, state: T, action: unknown, onBad: (message: string) => void): T;
+export declare function liveHost(options: LiveHostOptions): Promise<HostConnection & {
+    close(): Promise<void>;
+}>;