opencode-courier 0.2.1 → 0.2.3

package/dist/watch.js

@@ -1,28 +1,14 @@
-import { envelope } from "./courier.js";
-import { eventsFollowed, eventsLeft, formShown, formsMayHaveBeenMissed, locationClosing } from "./question.js";
-import { permissionNotice, settledNotice } from "./relay.js";
+import { addBounded, setBounded } from "./bounded.js";
+import { envelope, failureNotice, formNotice, formSettledNotice, kindOf, permissionNotice, permissionSettledNotice, } from "./notices.js";
+import { eventsFollowed, eventsLeft, formShown, formsMayHaveBeenMissed, locationClosing } from "./question/index.js";
+import { listEverywhere, QUESTION_FORM, } from "./relay.js";
 import { allEntries, entriesOf, lineage } from "./roster.js";
 /** How long to wait before subscribing again after the event stream ended or broke. */
 export const RESUBSCRIBE_MS = 5_000;
 /** How many handled event ids, and waiting or answered requests, are remembered. */
 const SEEN_MAX = 1_000;
-export function failureNotice(title, error) {
-    const status = error.status === undefined ? "" : `, status ${error.status}`;
-    return [
-        `This session, "${title}", which you started with courier_spawn, failed: ${error.message} (${error.type}${status}).`,
-        "Its turn ended without finishing, so it will not report back on its own.",
-        "Message it with courier_send to have it try again, start a replacement, or carry on without it.",
-    ].join("\n");
-}
-/** Adds to a bounded set, dropping the oldest entry; false when the value was there already. */
-export function claim(set, value) {
-    if (set.has(value))
-        return false;
-    set.add(value);
-    if (set.size > SEEN_MAX)
-        set.delete(set.values().next().value);
-    return true;
-}
+/** Claims a value in one of the shared sets; false when it was claimed already. */
+const claim = (set, value) => addBounded(set, value, SEEN_MAX);
 /**
  * Tells the parent of a child whose turn failed, since a child that cannot reach its model cannot
  * call courier_send. Returns the parents told.
@@ -32,14 +18,13 @@ export async function reportFailure(ports, seen, event) {
         return [];
     const { sessionID, error } = event.data;
     const entries = await entriesOf(ports.storage, sessionID);
-    for (const entry of entries)
-        await ports.session.synthetic({
-            sessionID: entry.parentID,
-            text: envelope(sessionID, failureNotice(entry.title, error), { failed: error.type }),
-            description: `Session ${sessionID} failed`,
-            metadata: { source: "courier", from: sessionID, failed: true },
-            delivery: "steer",
-        });
+    await Promise.all(entries.map((entry) => ports.session.synthetic({
+        sessionID: entry.parentID,
+        text: envelope(sessionID, failureNotice(entry.title, error), { failed: error.type }),
+        description: `Session ${sessionID} failed`,
+        metadata: { source: "courier", from: sessionID, failed: true },
+        delivery: "steer",
+    })));
     return entries.map((entry) => entry.parentID);
 }
 /** The session at the top of a lineage: where its permission requests go, since that is where the person is. */
@@ -88,7 +73,7 @@ export async function reportReplied(ports, state, event) {
         return [];
     await ports.session.synthetic({
         sessionID: topOf(chain),
-        text: envelope(sessionID, settledNotice(chain[0].title, requestID, reply), { answered: reply, request: requestID }),
+        text: envelope(sessionID, permissionSettledNotice(chain[0].title, requestID, reply), { answered: reply, request: requestID }),
         description: `Session ${sessionID} no longer asks for permission`,
         metadata: { source: "courier", from: sessionID, answered: reply, requestID },
         delivery: "steer",
@@ -96,14 +81,77 @@ export async function reportReplied(ports, state, event) {
     return [topOf(chain)];
 }
 /**
- * Relays the requests that spawned sessions in this location already wait on, which the event
- * stream does not repeat: those asked while it was down, before the watcher (re)subscribed.
+ * Tells the session at the top about a form OpenCode shows in a spawned session, such as web
+ * search asking for its provider, which only the person can answer there. Question forms are
+ * left to the question relay, which passes every question of a spawned session on.
+ */
+export async function reportForm(ports, state, event) {
+    if (!claim(state.seen, event.id))
+        return [];
+    const form = event.data.form;
+    if (kindOf(form) === QUESTION_FORM)
+        return [];
+    const chain = await lineage(ports.storage, form.sessionID);
+    // As with a permission request, claimed after the lookup, so a form settled meanwhile is not told.
+    if (!chain.length || state.forms.settled.has(form.id) || state.forms.told.has(form.id))
+        return [];
+    const startedBy = chain.length > 1 ? chain[0].parentID : undefined;
+    const kind = kindOf(form);
+    const telling = ports.session.synthetic({
+        sessionID: topOf(chain),
+        text: envelope(form.sessionID, formNotice(chain[0].title, form, startedBy), {
+            asks: "form",
+            form: form.id,
+            ...(kind ? { kind } : {}),
+        }),
+        description: `Session ${form.sessionID} shows a form`,
+        metadata: { source: "courier", from: form.sessionID, asks: "form", formID: form.id, ...(kind ? { kind } : {}) },
+        delivery: "steer",
+    });
+    setBounded(state.forms.told, form.id, telling, SEEN_MAX);
+    await telling;
+    return [topOf(chain)];
+}
+/** Tells the session told about a form that it was answered or withdrawn, so it does not send the person to a form that is gone. */
+export async function reportFormSettled(ports, state, event) {
+    if (!claim(state.seen, event.id))
+        return [];
+    const { id, sessionID } = event.data;
+    const telling = state.forms.told.get(id);
+    if (!telling) {
+        claim(state.forms.settled, id);
+        return [];
+    }
+    state.forms.told.delete(id);
+    const settled = event.type === "form.replied" ? "answered" : "cancelled";
+    // After the notice that the form is shown, which another instance may still be sending, so the
+    // settling never arrives first; and not at all when that notice did not go out.
+    const [chain, told] = await Promise.all([lineage(ports.storage, sessionID), telling.then(() => true, () => false)]);
+    if (!chain.length || !told)
+        return [];
+    await ports.session.synthetic({
+        sessionID: topOf(chain),
+        text: envelope(sessionID, formSettledNotice(chain[0].title, id, settled), { settled, form: id }),
+        description: `Session ${sessionID} no longer shows a form`,
+        metadata: { source: "courier", from: sessionID, settled, formID: id },
+        delivery: "steer",
+    });
+    return [topOf(chain)];
+}
+/**
+ * Relays the requests that spawned sessions already wait on, in every loaded location, which the
+ * event stream does not repeat: those asked while it was down, before the watcher (re)subscribed.
  */
 export async function relayPending(ports, state) {
     const sessions = new Set((await allEntries(ports.storage)).map((entry) => entry.sessionID));
-    for (const sessionID of sessions)
-        for (const request of await ports.permission.list({ sessionID }).catch(() => []))
-            await reportAsked(ports, state, { id: `pending:${request.id}`, data: request });
+    const domains = [...ports.permissions()];
+    // Each request is claimed before its notice goes out, so relaying them all at once tells each
+    // once, however many locations list it; a location that cannot be read lists none.
+    const relay = async (sessionID) => {
+        const listed = (await listEverywhere(domains, sessionID)).flatMap((found) => found.requests);
+        await Promise.all(listed.map((request) => reportAsked(ports, state, { id: `pending:${request.id}`, data: request })));
+    };
+    await Promise.all([...sessions].map(relay));
 }
 const pause = (ms, signal) => new Promise((resolve) => {
     const timer = setTimeout(done, ms);
@@ -125,42 +173,87 @@ async function handle(ports, state, event) {
         return reportAsked(ports, state, event);
     if (event.type === "permission.replied")
         return reportReplied(ports, state, event);
-    // Not claimed: every instance may resolve the same waiting call, which is harmless.
-    if (event.type === "form.created")
+    if (event.type === "form.created") {
+        // Not claimed: the hub's other subscription, or another copy's watcher, may resolve the same
+        // waiting call, which is harmless.
         formShown(event);
+        return reportForm(ports, state, event);
+    }
+    if (event.type === "form.replied" || event.type === "form.cancelled")
+        return reportFormSettled(ports, state, event);
     // Not claimed either: a location closing withdraws its forms, which must not pass for dismissals.
     // The event's location is optional; without one, the shutdown counts for every location.
     if (event.type === "location.shutdown") {
         const directory = event.location?.directory;
-        locationClosing(typeof directory === "string" ? directory : undefined);
+        locationClosing(ports.now(), typeof directory === "string" ? directory : undefined);
     }
     return [];
 }
+const ENDED = { done: true, value: undefined };
+/**
+ * The events of `events` until it ends or `signal` aborts, whichever comes first; the stream is not
+ * closed. Each wait for the next event listens for the abort only while it waits, so a watcher that
+ * follows events for the life of the process holds nothing per event it has seen.
+ */
+const until = (events, signal) => ({
+    [Symbol.asyncIterator]: () => ({
+        next: () => new Promise((resolve, reject) => {
+            if (signal.aborted)
+                return resolve(ENDED);
+            const stop = () => resolve(ENDED);
+            signal.addEventListener("abort", stop, { once: true });
+            // Once the signal has aborted, whatever the stream ends this wait with is not wanted.
+            events.next().then((next) => {
+                signal.removeEventListener("abort", stop);
+                resolve(next);
+            }, (error) => {
+                signal.removeEventListener("abort", stop);
+                reject(error);
+            });
+        }),
+    }),
+});
+/** Relays the requests already pending, kept in `relaying` until done, for the watcher's end to wait for. */
+function relayAlongside(ports, state, relaying) {
+    const relayed = relayPending(ports, state)
+        .catch((error) => ports.log(`courier watch: could not relay pending requests: ${String(error)}`))
+        .finally(() => relaying.delete(relayed));
+    relaying.add(relayed);
+}
+/** Handles one event, logging a failure rather than ending the watch. */
+function handleLogged(ports, state, event) {
+    return handle(ports, state, event).catch((error) => {
+        const data = event.data;
+        const sessionID = data?.sessionID ?? data?.form?.sessionID;
+        ports.log(`courier watch: could not handle ${event.type} of ${sessionID}: ${String(error)}`);
+    });
+}
 /**
  * Follows OpenCode's events until `signal` aborts, telling parents when a spawned child's turn
- * fails, when it waits for a permission and when that request is answered without them, and
+ * fails, when it waits for a permission or on a form and when that is answered without them, and
  * noting for the question relay the question forms shown, which it waits for, and the locations
- * shutting down, whose withdrawn forms must not pass for dismissals.
+ * shutting down, whose withdrawn forms must not pass for dismissals. Once `signal` aborts it ends
+ * as soon as the event it is handling, and the relay of the requests already pending, are done,
+ * without waiting for the stream to close: an unloading instance's leave waits for that.
  */
 export async function watchChildren(ports, state, signal, retryMs = RESUBSCRIBE_MS) {
+    const relaying = new Set();
     while (!signal.aborted) {
         let following = false;
+        let events;
         try {
-            const events = ports.event.subscribe({ signal });
+            events = ports.event.subscribe({ signal })[Symbol.asyncIterator]();
             // Question forms shown while no instance followed the events were not seen: released now,
             // and again on the first event, by when the stream is surely connected.
             let missed = eventsFollowed();
             following = true;
             // Alongside the new subscription; a request both relays see is relayed once.
-            void relayPending(ports, state).catch((error) => ports.log(`courier watch: could not relay pending requests: ${String(error)}`));
-            for await (const event of events) {
+            relayAlongside(ports, state, relaying);
+            for await (const event of until(events, signal)) {
                 if (missed)
                     formsMayHaveBeenMissed();
                 missed = false;
-                await handle(ports, state, event).catch((error) => {
-                    const sessionID = event.data?.sessionID;
-                    ports.log(`courier watch: could not handle ${event.type} of ${sessionID}: ${String(error)}`);
-                });
+                await handleLogged(ports, state, event);
             }
         }
         catch (error) {
@@ -170,8 +263,27 @@ export async function watchChildren(ports, state, signal, retryMs = RESUBSCRIBE_
         finally {
             if (following)
                 eventsLeft();
+            // Closed without waiting: the subscription's own signal has aborted, or the stream ended, and
+            // closing the adapter's stream waits on OpenCode's side, which may not answer while a location
+            // closes; the leave that waits for this watcher must not wait for that too.
+            void events?.return?.().catch(() => { });
         }
         if (!signal.aborted)
             await pause(retryMs, signal);
     }
+    await Promise.allSettled(relaying);
+}
+/**
+ * Makes the hub start its subscriptions to OpenCode's events with this copy's watcher, the copy loaded
+ * last's, as after an update; `join` starts them. Every instance in the process is sent every event,
+ * so one subscription would serve them all; the second is a standby, already connected when the
+ * first one's member leaves, so no event goes unseen then. Both handle every event, and the claim
+ * sets tell each once. Like any (re)subscription, a new one relays the requests already pending,
+ * which the claim sets tell once too.
+ */
+export function watchFromHub(hub, state, retryMs = RESUBSCRIBE_MS) {
+    hub.subscribe = (member) => {
+        const stop = new AbortController();
+        return { member, stop, done: watchChildren(member.watch, state, stop.signal, retryMs) };
+    };
 }

package/dist/webhook.d.ts

@@ -48,7 +48,6 @@ export interface Event {
     readonly topics: readonly string[];
     readonly summary: string;
 }
-export declare function clip(text: string, max?: number): string;
 /**
  * Maps a GitHub delivery to its topics (`github:owner/repo` and, for pull requests and issues,
  * `github:owner/repo#N`) and a summary. Undefined for deliveries nobody should be woken for: pings,
@@ -57,8 +56,6 @@ export declare function clip(text: string, max?: number): string;
 export declare function githubEvent(name: string, payload: unknown): Event | undefined;
 /** A delivery to `/hook/<topic>`: a JSON body's `text`, `summary` or `message` field, else the body itself. */
 export declare function genericEvent(topic: string, body: string): Event;
-/** Defuses `<courier` and `</courier>` in outside text, so it cannot close the envelope or forge another. */
-export declare function defuse(text: string): string;
 /**
  * Delivers an event to every session subscribed to one of its topics, once per session. A session
  * OpenCode no longer knows loses its subscriptions.
@@ -77,21 +74,12 @@ export interface Response {
     readonly status: number;
     readonly body: string;
 }
-/** Digests of accepted deliveries, newest last; shared by every receiver in the process. */
-export declare class Seen {
-    private readonly limit;
-    private readonly items;
-    constructor(limit?: number);
-    has(digest: string): boolean;
-    add(digest: string): void;
-    delete(digest: string): void;
-}
 /**
  * Handles one request: `POST /github` with GitHub's headers, or `POST /hook/<name>` signed over
  * the name and the body. Anything not signed with the secret is refused before its body is parsed,
  * and a signature already accepted is ignored, so a captured delivery cannot be replayed.
  */
-export declare function receive(ports: WebhookPorts, secret: string, request: Request, seen?: Seen): Promise<Response>;
+export declare function receive(ports: WebhookPorts, secret: string, request: Request, seen?: Set<string>): Promise<Response>;
 /** Starts the HTTP receiver; `ports()` picks a live plugin instance for each request. */
 export declare function listen(config: WebhookConfig, ports: () => WebhookPorts | undefined): Promise<Server<typeof IncomingMessage, typeof import("node:http").ServerResponse>>;
 /**