@chipschat/harness 0.0.0-stage → 1.0.0

package/dist/connect.js

@@ -0,0 +1,883 @@
+/**
+ * `connect`: one socket to `chipsd`, the handshake, a subscription that resumes from where it
+ * got to, and the outbox that makes every send safe to repeat. Node 22's own `WebSocket` is
+ * enough; there is nothing to install beyond `@chipschat/protocol`. Two calls go over HTTP, with
+ * Node 22's own `fetch` and the same token: the rooms a person asked this harness for, read at
+ * connect, and the claim that makes one of them the harness's own.
+ */
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { createIdGenerator, PROTOCOL_VERSION, } from "@chipschat/protocol";
+import { Asks, firstWords } from "./asks.js";
+import { Emitter } from "./events.js";
+import { download, upload } from "./files.js";
+import { createOutbox, RefusedError } from "./outbox.js";
+import { Project } from "./project.js";
+import { Run } from "./run.js";
+import { acceptsFor, Settings } from "./settings.js";
+function agentOf(body) {
+    return {
+        agentId: String(body["agent_id"]),
+        key: String(body["key"]),
+        name: String(body["name"]),
+        lead: body["lead"] === true,
+        state: body["state"] === "archived" ? "archived" : "active",
+        spaces: Array.isArray(body["spaces"]) ? body["spaces"] : [],
+        room: typeof body["room"] === "string" ? body["room"] : null,
+        releasedFrom: typeof body["released_from"] === "string" ? body["released_from"] : null,
+        held: typeof body["held"] === "number" ? body["held"] : 0,
+        forkedFrom: typeof body["forked_from"] === "string" ? body["forked_from"] : null,
+    };
+}
+export class ConnectError extends Error {
+    name = "ConnectError";
+}
+export class Chips {
+    options;
+    emitter = new Emitter();
+    outbox = createOutbox();
+    ids = createIdGenerator();
+    waiters = new Set();
+    activeRuns = new Map();
+    /** Pings in flight, by their `ts`, for `subscribed`. */
+    pongs = new Map();
+    /** Makes each ping's `ts` its own, so two in one millisecond are still told apart. */
+    pings = 0;
+    /**
+     * Events held back, and why: one hold until the harness could attach a handler after connect,
+     * and one for each catch-up on asked rooms still reading, so that a room's first words heard
+     * live and read from its history are handed over once. Delivered in order when none is left.
+     */
+    held = [];
+    holds = 1;
+    askHandlers = new Emitter();
+    asks = new Asks(() => this.me()?.harness_id, {
+        listening: () => this.askHandlers.count("asked") > 0,
+        hand: (asked) => this.askHandlers.emit("asked", asked),
+    });
+    socket;
+    ready = false;
+    closed = false;
+    retry = 0;
+    timer;
+    since;
+    connectionState = "connecting";
+    helloEvent;
+    /** What this harness last said is wrong on its side, said again whenever it reconnects. */
+    trouble;
+    /** The runs this process started or took up and has not ended, for the store. */
+    openRuns = new Map();
+    /** Runs a process before this one left open, ended once this one has said hello. */
+    orphans = [];
+    saving;
+    constructor(options) {
+        this.options = options;
+        const kept = options.store?.load();
+        this.since = options.since ?? kept?.since;
+        for (const event of kept?.outbox ?? []) {
+            this.outbox.add(String(event["idempotency_key"]), event).catch(() => undefined);
+        }
+        this.orphans = [...(kept?.runs ?? [])];
+        this.settings = new Settings((path, body) => this.request("PUT", path, body), () => this.harnessId, options.settings, (path, body) => this.request("POST", path, body));
+    }
+    /**
+     * The harness's copies of what a person changes from an agent's page (ADRs 0134, 0140, 0143,
+     * 0146): send each when connected and whenever it changes on the harness's side. Handlers for
+     * a person's changes are `connect({ settings })`'s.
+     */
+    settings;
+    /** Open the socket, say hello, subscribe. Resolves once the server has said who you are. */
+    static async connect(options) {
+        const chips = new Chips(options);
+        await chips.open(true);
+        chips.endOrphans();
+        // What `since` replayed during the handshake is delivered on the next tick, so handlers
+        // attached right after `await connect(...)` hear it rather than missing it.
+        setTimeout(() => chips.release(), 0);
+        return chips;
+    }
+    get state() {
+        return this.connectionState;
+    }
+    /** The server's half of the handshake: who this connection is, and what it may do. */
+    get hello() {
+        if (this.helloEvent === undefined)
+            throw new ConnectError("not connected yet");
+        return this.helloEvent;
+    }
+    get harnessId() {
+        const me = this.me();
+        if (me === undefined)
+            throw new ConnectError("the server presented no harness");
+        return me.harness_id;
+    }
+    /** Who this connection is: `hello.harness`, or the list's first from a server before it. */
+    me() {
+        return this.helloEvent?.harness ?? this.helloEvent?.harnesses[0];
+    }
+    get workspaceId() {
+        return this.hello.workspace_id;
+    }
+    /**
+     * The harness's agents (ADR 0087): `register` makes one, or finds it by your key for it,
+     * renames it when the name has changed, and archives it or brings it back as `state` says;
+     * `list` reads them with their rooms; `attach` puts one in a room in the place of another of
+     * yours there, or of the harness itself. One connection speaks for all of them:
+     * `chips.as(agentId)`. A harness that declares `agents` is told them at `hello` too
+     * (`chips.hello.agents`).
+     */
+    agents = {
+        register: async (input) => {
+            const answer = await this.request("POST", `/v1/harnesses/${this.harnessId}/agents`, {
+                key: input.key,
+                name: input.name,
+                ...(input.lead === undefined ? {} : { lead: input.lead }),
+                ...(input.state === undefined ? {} : { state: input.state }),
+                ...(input.forkedFrom === undefined ? {} : { forked_from: input.forkedFrom }),
+                ...(input.madeFor === undefined ? {} : { made_for: input.madeFor }),
+                ...(input.spaceId === undefined ? {} : { space_id: input.spaceId }),
+            });
+            return {
+                ...agentOf(answer),
+                created: answer["created"] === true,
+                renamed: answer["renamed"] === true,
+                ...(typeof answer["attached"] === "boolean" ? { attached: answer["attached"] } : {}),
+                ...(typeof answer["why"] === "string" ? { why: answer["why"] } : {}),
+            };
+        },
+        list: async () => {
+            const answer = await this.request("GET", `/v1/harnesses/${this.harnessId}/agents`);
+            return (Array.isArray(answer["agents"]) ? answer["agents"] : []).map((each) => agentOf(each));
+        },
+        /**
+         * An agent of yours in a room, in the place of `replacing`: the harness's own id, or another
+         * of its agents there. What that one said in the room reads as the agent's from then on.
+         * `attached` is false when it was there already.
+         */
+        attach: async (agentId, where) => {
+            const answer = await this.request("POST", `/v1/agents/${agentId}/attach`, {
+                space_id: where.spaceId,
+                replacing: where.replacing,
+            });
+            return { attached: answer["attached"] === true };
+        },
+    };
+    /**
+     * Speak as one of this harness's agents (ADR 0087): a post, and a run with everything sent on
+     * it, carry the agent as their actor. A harness with one agent in a room need not say which:
+     * what it sends as itself is read as that agent there. Where it has several, it must.
+     */
+    as(agentId) {
+        const actor = { kind: "agent", id: agentId };
+        return {
+            post: (input) => this.postAs(input, actor),
+            runs: { start: (input) => this.startAs(input, actor) },
+        };
+    }
+    /**
+     * A room's project for one of this harness's agents (ADR 0221): its copy in the agent's folder,
+     * brought up to date before each turn (`pull`) and sent after it (`push`).
+     */
+    project(input) {
+        return new Project({ ...input, url: this.options.url, token: this.options.token });
+    }
+    get autonomy() {
+        return this.hello.autonomy;
+    }
+    get policy() {
+        return this.hello.policy;
+    }
+    /** The highest `seq` heard, to persist for `since` on the next start. */
+    get lastSeq() {
+        return this.since;
+    }
+    on(name, handler) {
+        return this.emitter.on(name, handler);
+    }
+    /** Say something in a space. */
+    post(input) {
+        return this.postAs(input, undefined);
+    }
+    postAs(input, actor) {
+        return this.send("message.post", {
+            space_id: input.spaceId,
+            ...(input.runId === undefined ? {} : { run_id: input.runId }),
+            ...(actor === undefined ? {} : { actor }),
+        }, {
+            text: input.text,
+            ...(input.uploadIds === undefined ? {} : { upload_ids: input.uploadIds }),
+            ...(input.replaces === undefined ? {} : { replaces: input.replaces }),
+            ...(input.change === undefined ? {} : { change: input.change }),
+            ...(input.replyTo === undefined ? {} : { reply_to: input.replyTo }),
+            ...(input.to === undefined ? {} : { to: input.to }),
+        });
+    }
+    /**
+     * A room a person asked this harness for: their first words in it, once per room. Registering
+     * reads the rooms asked while the harness was away (`GET /v1/harnesses/:id/spaces`) and their
+     * history, and every reconnect reads them again; a room asked while connected is heard live.
+     * The first words are the ask's, and are not heard again as `message.new`; what is said in the
+     * room after them is. Only a harness that declares `new_spaces` is ever asked. Make what the
+     * room is for, then `claimSpace` it under a key of your own and answer in it.
+     */
+    onSpaceAsked(handler) {
+        const off = this.askHandlers.on("asked", handler);
+        if (this.ready)
+            void this.catchUp();
+        return off;
+    }
+    /**
+     * Make a room a person asked for this harness's own, under `key`, the harness's name for what
+     * it made of it: an agent, a session, a Space. The title names the room unless a person named
+     * it first. Asking for the key afterwards finds the room, as for a room the harness opened.
+     * A retry with the same key finds the room claimed already; a refusal throws `RefusedError`.
+     */
+    async claimSpace(spaceId, key, title) {
+        const answer = await this.request("POST", `/v1/harnesses/${this.harnessId}/spaces`, {
+            key,
+            space_id: spaceId,
+            ...(title === undefined ? {} : { title }),
+        });
+        return {
+            spaceId: String(answer["space_id"]),
+            claimed: answer["claimed"] === true,
+            retitled: answer["retitled"] === true,
+        };
+    }
+    /**
+     * A room of this harness's own, under `key`: opened the first time, found again after. Chips puts
+     * the agent registered under the same key in it, or the harness's default agent (ADR 0087's
+     * addendum of 30 September, point 5). The title names a new room; untitled, it is called what
+     * its agent is.
+     */
+    async openSpace(key, title) {
+        const answer = await this.request("POST", `/v1/harnesses/${this.harnessId}/spaces`, {
+            key,
+            ...(title === undefined ? {} : { title }),
+        });
+        return String(answer["space_id"]);
+    }
+    /**
+     * A room's lines, older than `before` (a line's `seq`, or a context's `before`), up to `limit`
+     * of them: 20 unless said otherwise, 200 at most (ADR 0088). Only a room this harness is in.
+     * What a harness reads to catch up on a room it was just added to, or to look further back
+     * than a message's context went.
+     */
+    async roomContext(spaceId, page = {}) {
+        const query = new URLSearchParams();
+        if (page.before !== undefined)
+            query.set("before", String(page.before));
+        if (page.limit !== undefined)
+            query.set("limit", String(page.limit));
+        const search = query.toString();
+        const path = `/v1/spaces/${spaceId}/context${search === "" ? "" : `?${search}`}`;
+        const answer = await this.request("GET", path);
+        return answer;
+    }
+    /**
+     * Send a file, for a post's `uploadIds`: in pieces when it is large, picking up where it got to
+     * after a piece is lost (ADR 0052). Resolves with what the server stored.
+     */
+    upload(input) {
+        return upload((method, path, body) => this.request(method, path, body), input);
+    }
+    /** Send a file from disk, under its own name unless given another. */
+    async uploadFile(path, filename) {
+        const bytes = new Uint8Array(await readFile(path));
+        return await this.upload({ bytes, filename: filename ?? basename(path) });
+    }
+    /**
+     * An attachment's bytes: a message's, or a room file's. Its URL is bound to this harness's
+     * token, so it is fetched with it.
+     */
+    download(attachment) {
+        return download(this.options.fetch ?? fetch, this.options.token, attachment);
+    }
+    /**
+     * Say what is wrong on this harness's side: the part Chips cannot see, such as a back end it
+     * cannot reach (ADR 0083). People see the agent marked, and these words under a message it
+     * hasn't picked up. One line, up to 200 characters. It holds until `reportOk`, or until the
+     * connection closes; the SDK says it again whenever it reconnects, so say it once.
+     */
+    async reportTrouble(reason) {
+        this.trouble = reason;
+        await this.status({ state: "trouble", reason });
+    }
+    /** Say that nothing is wrong on this harness's side any more (ADR 0083). */
+    async reportOk() {
+        this.trouble = undefined;
+        await this.status({ state: "ok" });
+    }
+    async status(body) {
+        await this.request("PUT", `/v1/harnesses/${this.harnessId}/status`, body);
+    }
+    /** The lane side of the connection, for the `Lane` a `run.task()` hands back. */
+    lanes = {
+        hear: (laneId, handler) => this.emitter.on("lane.updated", (event) => {
+            if (event.lane_id === laneId)
+                handler(event);
+        }),
+        accept: (runId, spaceId, laneId) => this.runFor(runId, spaceId, laneId),
+    };
+    /** A `Run` over the wire for this run id, registered so what people do to it reaches it. */
+    runFor(runId, spaceId, laneId, actor) {
+        const known = this.activeRuns.get(runId);
+        if (known !== undefined)
+            return known;
+        // Everything sent on a run an agent started is that agent's (ADR 0087).
+        const envelope = {
+            space_id: spaceId,
+            run_id: runId,
+            ...(actor === undefined ? {} : { actor }),
+        };
+        const run = new Run(runId, spaceId, {
+            send: (type, payload, key) => this.send(type, envelope, payload, key),
+            newId: (kind) => this.ids.next(kind),
+            waitFor: (match) => this.waitFor(match),
+            lanes: this.lanes,
+        }, laneId);
+        this.activeRuns.set(runId, run);
+        return run;
+    }
+    /**
+     * Runs: `chips.runs.start({...})` opens one and resolves once the server has accepted it;
+     * `chips.runs.accept(requested)` takes up the run a lead routed here as a lane (M3.5) — the
+     * run is already seeded, so nothing is sent — and everything sent on it is the lane's.
+     */
+    runs = {
+        start: (input) => this.startAs(input, undefined),
+        accept: (requested) => {
+            if (requested.run_id === undefined || requested.space_id === undefined) {
+                throw new ConnectError("a run.requested names the lane's run and its home");
+            }
+            this.opened({ runId: requested.run_id, spaceId: requested.space_id });
+            return this.runFor(requested.run_id, requested.space_id, requested.lane_id);
+        },
+    };
+    async startAs(input, actor) {
+        {
+            const runId = input.runId ?? this.ids.next("run");
+            const envelope = {
+                space_id: input.spaceId,
+                run_id: runId,
+                ...(actor === undefined ? {} : { actor }),
+            };
+            const run = this.runFor(runId, input.spaceId, undefined, actor);
+            this.opened({ runId, spaceId: input.spaceId, agentId: actor?.id });
+            try {
+                await this.send("run.started", envelope, {
+                    goal: input.goal,
+                    ...(input.plan === undefined
+                        ? {}
+                        : { plan: input.plan.map((step) => ({ step_id: step.stepId, title: step.title })) }),
+                    ...(input.sessionRef === undefined ? {} : { session_ref: input.sessionRef }),
+                });
+            }
+            catch (error) {
+                this.activeRuns.delete(runId);
+                this.ended(runId);
+                throw error;
+            }
+            return run;
+        }
+    }
+    /** Send any event. The envelope's actor, ts and workspace are the server's to fill in. */
+    send(type, envelope, payload, key = `${this.options.client?.name ?? "harness"}-${this.ids.next("event").slice(4)}`) {
+        if (this.closed)
+            return Promise.reject(new RefusedError("closed", "the connection is closed", key));
+        const event = { type, ...envelope, idempotency_key: key, ...payload };
+        const answer = this.outbox.add(key, event);
+        if (type === "run.completed" || type === "run.failed")
+            this.ended(String(envelope["run_id"]));
+        this.save();
+        if (this.ready && this.socket !== undefined) {
+            this.socket.send(JSON.stringify({ frame: "event", event }));
+        }
+        return answer;
+    }
+    // ------------------------------------------------------------------ what survives a restart
+    opened(run) {
+        this.openRuns.set(run.runId, run);
+        this.save();
+    }
+    ended(runId) {
+        if (this.openRuns.delete(runId))
+            this.save();
+    }
+    /**
+     * End the runs a process before this one left open: its work died with it, and a run nobody
+     * ends keeps its thinking bubble until the harness's next one. Refused for one Chips had ended
+     * already, which is just as well.
+     */
+    endOrphans() {
+        const orphans = this.orphans.filter((run) => !this.openRuns.has(run.runId));
+        this.orphans = [];
+        for (const run of orphans) {
+            this.send("run.failed", {
+                space_id: run.spaceId,
+                run_id: run.runId,
+                ...(run.agentId === undefined ? {} : { actor: { kind: "agent", id: run.agentId } }),
+            }, { error: "The harness restarted before this run ended.", retryable: true }, `restarted-${run.runId}`).catch(() => undefined);
+        }
+        this.save();
+    }
+    /** Keep the state soon, once for however many changes come together. */
+    save() {
+        if (this.options.store === undefined || this.saving !== undefined)
+            return;
+        this.saving = setTimeout(() => {
+            this.saving = undefined;
+            this.saveNow();
+        }, 50);
+        this.saving.unref?.();
+    }
+    saveNow() {
+        this.options.store?.save({
+            ...(this.since === undefined ? {} : { since: this.since }),
+            outbox: this.outbox.unanswered(),
+            runs: [...this.openRuns.values(), ...this.orphans],
+        });
+    }
+    /** Resolve with the first event that matches, now or later. */
+    waitFor(match) {
+        return new Promise((resolve) => {
+            this.waiters.add({ match, resolve: resolve });
+        });
+    }
+    close() {
+        this.closed = true;
+        clearTimeout(this.timer);
+        // What was unanswered is kept for the next start before the outbox lets it go.
+        clearTimeout(this.saving);
+        this.saving = undefined;
+        this.saveNow();
+        this.socket?.close();
+        this.outbox.abandon("the connection was closed");
+        this.setState("closed");
+    }
+    // ------------------------------------------------------------------ the socket
+    /**
+     * The socket's URL, with a single-use ticket in it (SEC-22). The token goes to
+     * `POST /v1/socket-tickets` in a header, as every other call sends it; what comes back is
+     * spent on the upgrade and worth nothing afterwards. Node's `WebSocket` sets no headers on
+     * the upgrade, and a token in the URL would be a durable credential in every proxy log the
+     * URL crosses.
+     */
+    async socketUrl() {
+        const base = this.options.url.replace(/\/$/, "").replace(/^http/, "ws");
+        const { ticket } = await this.request("POST", "/v1/socket-tickets");
+        return `${base}/v1/ws?ticket=${encodeURIComponent(String(ticket))}`;
+    }
+    open(first) {
+        return new Promise((resolve, reject) => {
+            this.setState("connecting");
+            // Before a socket exists, a failure tells the first caller. A reconnect has nobody to
+            // tell, so it tries again: a server still down on this attempt may be up by the next.
+            const failed = (what, error) => {
+                if (first)
+                    reject(new ConnectError(`${what}: ${describe(error)}`));
+                else
+                    this.scheduleReconnect();
+            };
+            void this.socketUrl().then((url) => {
+                let socket;
+                try {
+                    socket = (this.options.createSocket ?? openSocket)(url);
+                }
+                catch (error) {
+                    failed("could not open a socket", error);
+                    return;
+                }
+                this.socket = socket;
+                this.listen(socket, {
+                    settled: (hello) => this.settled(socket, hello, first, resolve, reject),
+                });
+            }, (error) => failed("could not get a socket ticket", error));
+        });
+    }
+    /** The handshake's outcome: the hello, a refusal, or the socket gone before either. */
+    settled(socket, hello, first, resolve, reject) {
+        if (hello === undefined) {
+            if (first)
+                reject(new ConnectError("the server closed the socket before saying hello"));
+            else
+                this.scheduleReconnect();
+            return;
+        }
+        if (hello instanceof ConnectError) {
+            if (first)
+                reject(hello);
+            return;
+        }
+        this.onHello(socket, hello);
+        void this.subscribed(socket).then(resolve);
+    }
+    /** The socket's four events. `settled` fires once: with the hello, a refusal, or nothing. */
+    listen(socket, on) {
+        let settled = false;
+        const settle = (outcome) => {
+            if (settled)
+                return;
+            settled = true;
+            on.settled(outcome);
+        };
+        socket.addEventListener("open", () => {
+            socket.send(JSON.stringify({
+                frame: "hello",
+                protocol: { min: PROTOCOL_VERSION, max: PROTOCOL_VERSION },
+                client: this.options.client ?? { name: "chips-harness", version: "0.0.0" },
+                ...(this.options.context === undefined ? {} : { context: this.options.context }),
+                ...this.accepts(),
+            }));
+        });
+        socket.addEventListener("message", (message) => {
+            const frame = JSON.parse(String(message.data));
+            if (settled) {
+                this.handleFrame(frame);
+                return;
+            }
+            const outcome = this.handshakeOutcome(frame);
+            if (outcome !== undefined)
+                settle(outcome);
+            else
+                this.handleFrame(frame);
+        });
+        let gone = false;
+        const onGone = () => {
+            if (gone)
+                return;
+            gone = true;
+            this.ready = false;
+            const wasSettled = settled;
+            settle(undefined);
+            if (!wasSettled)
+                return;
+            this.setState("closed");
+            this.scheduleReconnect();
+        };
+        socket.addEventListener("close", onGone);
+        // An error is the socket gone, not a prelude to `close`: Node 22's WebSocket (undici 6) fires
+        // only `error` when the server refuses the handshake, so waiting for `close` hangs there. Where
+        // `close` does follow, it finds the work done.
+        socket.addEventListener("error", onGone);
+    }
+    /** The frames beyond the base set this connection takes: a restart, and the settings it handles. */
+    accepts() {
+        const accepts = [
+            ...(this.options.onRestart === undefined ? [] : ["restart"]),
+            ...acceptsFor(this.options.settings),
+        ];
+        return accepts.length === 0 ? {} : { accepts };
+    }
+    /** During the handshake: the server's hello, or its refusal. Anything else is a frame. */
+    handshakeOutcome(frame) {
+        if (frame["frame"] === "event") {
+            const event = frame["event"];
+            return event["type"] === "hello" ? event : undefined;
+        }
+        if (frame["frame"] === "error") {
+            return new ConnectError(`${String(frame["code"])}: ${String(frame["message"])}`);
+        }
+        return undefined;
+    }
+    onHello(socket, hello) {
+        this.helloEvent = hello;
+        this.emitter.emit("hello", hello);
+        socket.send(JSON.stringify({
+            frame: "subscribe",
+            workspace_id: hello.workspace_id,
+            ...(this.since === undefined ? {} : { since: this.since }),
+        }));
+        // Whatever the last socket did not get an answer for goes first: the server acks a resend
+        // it already applied as a duplicate, so sending twice is safe by design.
+        for (const event of this.outbox.unanswered()) {
+            socket.send(JSON.stringify({ frame: "event", event }));
+        }
+        this.ready = true;
+        this.retry = 0;
+        this.setState("open");
+        // A reconnect reads again what was asked while the socket was down.
+        if (this.askHandlers.count("asked") > 0)
+            void this.catchUp();
+        // And says again what is wrong, which ended when the last socket closed (ADR 0083).
+        const trouble = this.trouble;
+        if (trouble !== undefined) {
+            void this.status({ state: "trouble", reason: trouble }).catch(() => undefined);
+        }
+    }
+    /**
+     * The server answers frames in order, so a pong to a ping sent after `subscribe` means the
+     * subscription is live: an event appended from here on is delivered, not missed as history.
+     */
+    subscribed(socket) {
+        // An integer: the frame's schema says so, and a `ts` with a fraction is refused rather than
+        // answered — which cost every connect the whole two-second wait until M3.5 found it.
+        this.pings += 1;
+        const ts = Date.now() + this.pings;
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.pongs.delete(ts);
+                resolve();
+            }, 2000);
+            this.pongs.set(ts, () => {
+                clearTimeout(timer);
+                this.pongs.delete(ts);
+                resolve();
+            });
+            socket.send(JSON.stringify({ frame: "ping", ts }));
+        });
+    }
+    /** Hand a person's ask to the harness's own restart; what it does after is its business. */
+    restart(frame) {
+        const handler = this.options.onRestart;
+        if (handler === undefined)
+            return;
+        const ask = { askedBy: String(frame["asked_by"]), askedAt: String(frame["asked_at"]) };
+        void Promise.resolve()
+            .then(() => handler(ask))
+            .catch(() => undefined);
+    }
+    handleFrame(frame) {
+        switch (frame["frame"]) {
+            case "ping":
+                this.socket?.send(JSON.stringify({ frame: "pong", ts: frame["ts"] }));
+                return;
+            case "pong":
+                this.pongs.get(Number(frame["ts"]))?.();
+                return;
+            case "event":
+                this.onEvent(frame["event"]);
+                return;
+            case "ack":
+                this.outbox.acked({
+                    idempotencyKey: String(frame["idempotency_key"]),
+                    seq: Number(frame["seq"]),
+                    duplicate: frame["duplicate"] === true,
+                    ...laneOf(frame["lane"]),
+                    ...heldOf(frame),
+                });
+                this.save();
+                return;
+            case "error": {
+                const key = frame["idempotency_key"];
+                this.outbox.refused(new RefusedError(String(frame["code"]), String(frame["message"]), typeof key === "string" ? key : undefined));
+                this.save();
+                return;
+            }
+            case "restart":
+                this.restart(frame);
+                return;
+            case "receipt":
+                this.emitter.emit("receipt", {
+                    idempotencyKey: String(frame["idempotency_key"]),
+                    disposition: frame["disposition"] === "steered" ? "steered" : "queued",
+                });
+                return;
+            default:
+                this.settings.hear(frame);
+                return;
+        }
+    }
+    /** Let one hold go; with none left, deliver what was held, in order. */
+    release() {
+        this.holds -= 1;
+        if (this.holds > 0)
+            return;
+        const held = this.held;
+        this.held = [];
+        for (const event of held)
+            this.onEvent(event);
+    }
+    onEvent(event) {
+        if (this.holds > 0) {
+            this.held.push(event);
+            return;
+        }
+        const seq = event["seq"];
+        if (typeof seq === "number") {
+            this.since = Math.max(this.since ?? 0, seq);
+            this.save();
+        }
+        if (event["type"] === "run.cancel" && typeof event["run_id"] === "string") {
+            this.ended(event["run_id"]);
+        }
+        this.settleWaiters(event);
+        this.emitter.emit("event", event);
+        this.routeToRuns(event);
+        const asked = this.asks.heard(event);
+        const type = event["type"];
+        if (typeof type === "string" && type in this.named && !asked) {
+            this.emitter.emit(type, event);
+        }
+    }
+    // ------------------------------------------------------------------ over HTTP
+    /**
+     * The rooms asked of this harness and not yet claimed, each with its history, handed over
+     * when their first words are there. Live events wait meanwhile. A failure is left for the next
+     * connect: a room stays asked until it is claimed.
+     */
+    async catchUp() {
+        this.holds += 1;
+        try {
+            const listing = await this.request("GET", `/v1/harnesses/${this.harnessId}/spaces`);
+            const asked = Array.isArray(listing["asked"]) ? listing["asked"] : [];
+            for (const room of asked) {
+                if (this.asks.handed(room.space_id))
+                    continue;
+                this.asks.caughtUp(room, await this.firstWordsIn(room.space_id));
+            }
+        }
+        catch {
+            // Nothing to hand over this time; the room is listed again at the next connect.
+        }
+        finally {
+            this.release();
+        }
+    }
+    /** What a person first said in a room, read from its beginning a page at a time. */
+    async firstWordsIn(spaceId) {
+        let since = 0;
+        for (;;) {
+            const page = await this.request("GET", `/v1/events?space_id=${encodeURIComponent(spaceId)}&since=${since}&limit=100`);
+            const first = firstWords(page["events"] ?? []);
+            const next = page["next_cursor"];
+            if (first !== undefined || typeof next !== "number")
+                return first;
+            since = next;
+        }
+    }
+    /**
+     * One call to chipsd with the harness's token: JSON, or a file's bytes. A refusal throws with
+     * the server's words.
+     */
+    /**
+     * Any route, with this harness's token: for one the SDK has no call for yet. The answer's JSON,
+     * or `RefusedError` with the server's code and words.
+     */
+    async request(method, path, body) {
+        const base = this.options.url.replace(/\/$/, "").replace(/^ws/, "http");
+        const bytes = body instanceof Uint8Array;
+        const response = await (this.options.fetch ?? fetch)(`${base}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${this.options.token}`,
+                ...(body === undefined
+                    ? {}
+                    : { "content-type": bytes ? "application/octet-stream" : "application/json" }),
+            },
+            ...(body === undefined
+                ? {}
+                : { body: bytes ? body : JSON.stringify(body) }),
+        });
+        const answer = (await response.json().catch(() => ({})));
+        if (response.ok)
+            return answer;
+        const error = (answer["error"] ?? {});
+        throw new RefusedError(typeof error.code === "string" ? error.code : String(response.status), typeof error.message === "string" ? error.message : `${method} ${path}: ${response.status}`);
+    }
+    settleWaiters(event) {
+        for (const waiter of [...this.waiters]) {
+            const value = waiter.match(event);
+            if (value !== undefined) {
+                this.waiters.delete(waiter);
+                waiter.resolve(value);
+            }
+        }
+    }
+    /**
+     * An event into a run reaches that run; a message for this harness in a run's room reaches the
+     * run too. One it overheard does not: it was for somebody else (ADR 0081).
+     */
+    routeToRuns(event) {
+        if (event["type"] === "message.overheard")
+            return;
+        const runId = event["run_id"];
+        if (typeof runId === "string") {
+            this.activeRuns.get(runId)?.hear(event);
+            return;
+        }
+        if (event["type"] !== "message.new")
+            return;
+        for (const run of this.activeRuns.values()) {
+            if (run.spaceId === event["space_id"] && !run.over)
+                run.hear(event);
+        }
+    }
+    named = {
+        "message.new": true,
+        "message.overheard": true,
+        "approval.resolved": true,
+        "question.answered": true,
+        "run.steer": true,
+        "run.pause": true,
+        "run.resume": true,
+        "run.cancel": true,
+        "run.requested": true,
+        "lane.updated": true,
+        "policy.updated": true,
+        "budget.warning": true,
+        "agent.attached": true,
+        "agent.released": true,
+        "agent.fork": true,
+        "agent.asked": true,
+        feedback: true,
+    };
+    setState(state) {
+        if (this.connectionState === state)
+            return;
+        this.connectionState = state;
+        this.emitter.emit("state", state);
+    }
+    scheduleReconnect() {
+        if (this.closed || this.options.reconnect === false) {
+            if (!this.closed)
+                this.outbox.abandon("the connection dropped and reconnect is off");
+            return;
+        }
+        this.retry += 1;
+        clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            void this.open(false).catch(() => undefined);
+        }, Math.min(500 * this.retry, 5000));
+    }
+}
+/** The lane an ack names, in the SDK's words, or nothing when the frame names none. */
+/** Node's own `WebSocket`, as a `SocketLike`. */
+function openSocket(url) {
+    return new WebSocket(url);
+}
+/** A refusal by its code and words, anything else as it says itself. */
+function describe(error) {
+    return error instanceof RefusedError ? `${error.code}: ${error.message}` : String(error);
+}
+function heldOf(frame) {
+    if (frame["held"] !== true)
+        return {};
+    const exchange = frame["exchange"];
+    if (typeof exchange?.count !== "number")
+        return { held: true };
+    return {
+        held: true,
+        exchange: {
+            count: exchange.count,
+            ...(typeof exchange.allowance === "number" ? { allowance: exchange.allowance } : {}),
+        },
+    };
+}
+function laneOf(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return {};
+    const lane = raw;
+    if (typeof lane["lane_id"] !== "string" ||
+        typeof lane["run_id"] !== "string" ||
+        typeof lane["space_id"] !== "string") {
+        return {};
+    }
+    return { lane: { laneId: lane["lane_id"], runId: lane["run_id"], spaceId: lane["space_id"] } };
+}
+/** Connect to chipsd. `const chips = await connect({ url, token })`. */
+export function connect(options) {
+    return Chips.connect(options);
+}
+//# sourceMappingURL=connect.js.map