opencode-courier 0.2.3 → 0.3.0

package/dist/tree.js

@@ -0,0 +1,58 @@
+import { described } from "./courier.js";
+import { lastStatus, reportOf } from "./report.js";
+import { children } from "./roster.js";
+/**
+ * The sessions started from a session, directly or through others, read one prefix scan per parent, at most `max`
+ * (`truncated` if more), in the order a tree is drawn.
+ */
+export async function subtree(storage, rootID, max = Number.POSITIVE_INFINITY) {
+    const byParent = new Map();
+    const seen = new Set([rootID]);
+    let truncated = false;
+    const expand = async (level, depth) => {
+        if (!level.length || truncated)
+            return;
+        const found = await Promise.all(level.map((parentID) => children(storage, parentID)));
+        const next = [];
+        for (const [index, entries] of found.entries()) {
+            const fresh = entries.filter((entry) => !seen.has(entry.sessionID));
+            const kept = fresh.slice(0, Math.max(0, max - (seen.size - 1)));
+            truncated ||= kept.length < fresh.length;
+            for (const entry of kept)
+                seen.add(entry.sessionID);
+            if (kept.length)
+                byParent.set(level[index], kept.map((entry) => ({ entry, depth })));
+            next.push(...kept.map((entry) => entry.sessionID));
+        }
+        return expand(next, depth + 1);
+    };
+    await expand([rootID], 1);
+    return { nodes: drawn(byParent, rootID), truncated };
+}
+/** The nodes in the order a tree is drawn: each followed by what it started. */
+function drawn(byParent, parentID) {
+    return (byParent.get(parentID) ?? []).flatMap((node) => [node, ...drawn(byParent, node.entry.sessionID)]);
+}
+/**
+ * The subtree under a session, at most `maxTotal` sessions: what courier_children shows of each, plus its depth,
+ * its parent and its report state.
+ */
+export async function tree(ports, rootID) {
+    const { nodes, truncated } = await subtree(ports.storage, rootID, ports.limits.maxTotal);
+    const listed = await Promise.all(nodes.map(async ({ entry, depth }) => {
+        const [info, report, last] = await Promise.all([
+            described(ports, entry),
+            reportOf(ports.storage, entry.sessionID).catch(() => undefined),
+            lastStatus(ports.storage, entry.sessionID).catch(() => undefined),
+        ]);
+        return {
+            ...info,
+            parentID: entry.parentID,
+            depth,
+            ...(report
+                ? { report: { owes: report.owes, progressed: report.progressed, ended: report.ended, ...(last ? { status: last } : {}) } }
+                : {}),
+        };
+    }));
+    return { sessionID: rootID, sessions: listed, ...(truncated ? { truncated: ports.limits.maxTotal } : {}) };
+}

package/dist/version.d.ts

@@ -5,18 +5,12 @@ export interface BuiltVersions {
     readonly opencode: string;
 }
 /**
- * Reads the versions from the package's own package.json, which sits next to `dist/` in the
- * published package as it does next to `src/` in the repository: `version`, and the exact
- * `@opencode/plugin` version under devDependencies, the one installed for the build and both test
- * suites; the peer dependency names the same exact version, as the copy of the plugin API that
- * `opencode plugin add` installs next to the plugin. Throws when the file cannot be read or does
- * not hold both.
+ * Reads from the package's own package.json, next to `dist/` as to `src/`: `version` and the exact
+ * `@opencode/plugin` devDependency version, which the peer repeats. Throws if either is missing.
  */
 export declare function builtVersions(): BuiltVersions;
 /**
- * The line for the server log when the running OpenCode is not the one the plugin was built
- * against; undefined when it is. Logged once per plugin load, never in a tool result. An OpenCode
- * whose plugin context does not report a version, as one from before the pinned API or after a
- * change to it may not, is the case the line is for, so it still names the pin then.
+ * The server-log line for an OpenCode other than the plugin was built against, undefined when it is;
+ * logged once per load, never in a tool result. A context without a version is still told the pin.
  */
 export declare function versionNotice(built: BuiltVersions, app: Partial<Pick<App, "version" | "channel">> | undefined): string | undefined;

package/dist/version.js

@@ -1,12 +1,8 @@
 import { readFileSync } from "node:fs";
 const README_TABLE = "https://github.com/ivopogace/opencode-courier#supported-opencode-version";
 /**
- * Reads the versions from the package's own package.json, which sits next to `dist/` in the
- * published package as it does next to `src/` in the repository: `version`, and the exact
- * `@opencode/plugin` version under devDependencies, the one installed for the build and both test
- * suites; the peer dependency names the same exact version, as the copy of the plugin API that
- * `opencode plugin add` installs next to the plugin. Throws when the file cannot be read or does
- * not hold both.
+ * Reads from the package's own package.json, next to `dist/` as to `src/`: `version` and the exact
+ * `@opencode/plugin` devDependency version, which the peer repeats. Throws if either is missing.
  */
 export function builtVersions() {
     const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -19,10 +15,8 @@ export function builtVersions() {
     return { plugin, opencode };
 }
 /**
- * The line for the server log when the running OpenCode is not the one the plugin was built
- * against; undefined when it is. Logged once per plugin load, never in a tool result. An OpenCode
- * whose plugin context does not report a version, as one from before the pinned API or after a
- * change to it may not, is the case the line is for, so it still names the pin then.
+ * The server-log line for an OpenCode other than the plugin was built against, undefined when it is;
+ * logged once per load, never in a tool result. A context without a version is still told the pin.
  */
 export function versionNotice(built, app) {
     const version = typeof app?.version === "string" ? app.version : undefined;

package/dist/watch.d.ts

@@ -7,31 +7,76 @@ export declare const RESUBSCRIBE_MS = 5000;
 /** The part of OpenCode's `session.execution.failed` event the notice is made from. */
 export interface ExecutionFailed {
     readonly id: string;
+    /** When OpenCode published it, in epoch milliseconds. */
+    readonly created?: number;
     readonly data: {
         readonly sessionID: string;
         readonly error: ExecutionError;
     };
 }
+/** OpenCode's events that concern one session's turns and inbox: `session.execution.succeeded` and the like. */
+export interface SessionEvent {
+    readonly id: string;
+    readonly created?: number;
+    readonly data: {
+        readonly sessionID: string;
+        readonly reason?: string;
+    };
+}
 /**
  * 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.
  */
 export declare function reportFailure(ports: WatchPorts, seen: Set<string>, event: ExecutionFailed): Promise<string[]>;
+/** OpenCode's `session.inbox.enqueued`: the item's type, which its `session.inbox.delivered` does not carry. */
+export interface InboxEnqueued {
+    readonly data: {
+        readonly sessionID: string;
+        readonly inboxID: string;
+        readonly item: {
+            readonly type: string;
+        };
+    };
+}
+/** Remembers the type of an item enqueued for a spawned session, for `notePrompt`; other sessions cost one read. */
+export declare function noteEnqueued(ports: WatchPorts, inbox: Map<string, string>, event: InboxEnqueued): Promise<boolean>;
+/**
+ * Notes that a message reached a spawned session, which then owes its parent a report, unless `inbox` knows it for one of
+ * `UNOWED` (`spawn` notes the task itself); reads the reverse index alone, and claims nothing: the note is the same twice.
+ */
+export declare function notePrompt(ports: WatchPorts, event: SessionEvent & {
+    readonly data: {
+        readonly inboxID?: string;
+    };
+}, inbox?: Map<string, string>): Promise<boolean>;
+/**
+ * Notes that a spawned session's turn was stopped, which takes it out of its group without a report; one
+ * stopped by a shutdown resumes on the next start.
+ */
+export declare function noteInterrupted(ports: WatchPorts, event: SessionEvent): Promise<boolean>;
+/**
+ * Drops the report state, and the groups, of a session OpenCode deleted, and the report state of the sessions it
+ * started, whose reports can no longer be delivered; it leaves its own group. Returns the sessions forgotten.
+ */
+export declare function noteDeleted(ports: WatchPorts, event: SessionEvent): Promise<string[]>;
+/**
+ * Tells the parent of a spawned session whose turn ended without reporting to it since its last
+ * prompt, unless it waits; finds the session by the reverse index alone. Returns the parents told.
+ */
+export declare function reportSilent(ports: WatchPorts, seen: Set<string>, event: SessionEvent): Promise<string[]>;
 /**
  * Tells the session at the top, the parent of a child or the session a chain of children started
  * from, what a waiting child asks and which answers there are, waking it. Returns the sessions told.
  */
 export declare function reportAsked(ports: WatchPorts, state: WatchState, event: PermissionAsked): Promise<string[]>;
 /**
- * Tells the session that was told about a request that it has been answered some other way, in the
- * child's own session or along with another answer, so it does not pass on a stale question.
- * Requests answered through courier_answer are no longer waiting and are skipped.
+ * Tells the session told about a request that it was answered some other way, so it does not pass on
+ * a stale question; requests answered through courier_answer no longer wait and are skipped.
  */
 export declare function reportReplied(ports: WatchPorts, state: WatchState, event: PermissionReplied): Promise<string[]>;
 /**
- * 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.
+ * Tells the top session about a form OpenCode shows in a spawned session, such as web search asking
+ * for its provider, which only the person can answer; question forms are left to the question relay.
  */
 export declare function reportForm(ports: WatchPorts, state: WatchState, event: FormCreated): Promise<string[]>;
 /** 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. */
@@ -42,20 +87,12 @@ export declare function reportFormSettled(ports: WatchPorts, state: WatchState,
  */
 export declare function relayPending(ports: WatchPorts, state: WatchState): Promise<void>;
 /**
- * Follows OpenCode's events until `signal` aborts, telling parents when a spawned child's turn
- * 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. 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.
+ * Follows OpenCode's events until `signal` aborts: tells parents of a spawned child's failed or silent
+ * turn, its pending permission or form, notes forms and shutdowns for the relay; ends after its current event.
  */
 export declare function watchChildren(ports: WatchPorts, state: WatchState, signal: AbortSignal, retryMs?: number): Promise<void>;
 /**
- * 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.
+ * Makes the hub start its subscriptions to OpenCode's events with this copy's watcher, the one loaded
+ * last; `join` starts them. The second is a standby, connected before the first's member leaves.
  */
 export declare function watchFromHub(hub: Pick<Hub, "subscribe">, state: WatchState, retryMs?: number): void;

package/dist/watch.js

@@ -1,8 +1,13 @@
 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 { lastReply } from "./courier.js";
+import { dropGroups, hasCompleteGroup, markLeft, membershipOf } from "./group.js";
+import { envelope, failureNotice, formNotice, formSettledNotice, kindOf, permissionNotice, permissionSettledNotice, silentNotice, } from "./notices.js";
+import { eventsFollowed, eventsLeft, formShown, formsMayHaveBeenMissed, locationClosing, pendingQuestions } from "./question/index.js";
 import { listEverywhere, QUESTION_FORM, } from "./relay.js";
-import { allEntries, entriesOf, lineage } from "./roster.js";
+import { scheduledFor } from "./later.js";
+import { awaited, forgetReport, prompted, reportOf, settled, stoppedSincePrompt, told, untold } from "./report.js";
+import { allEntries, children, entriesOf, entryUnder, indexedEntry, indexedParent, lineage } from "./roster.js";
+import { subscriptions } from "./webhook.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. */
@@ -18,15 +23,174 @@ export async function reportFailure(ports, seen, event) {
         return [];
     const { sessionID, error } = event.data;
     const entries = await entriesOf(ports.storage, sessionID);
-    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",
-    })));
+    const at = event.created ?? ports.now();
+    // Not in the way of the notice: kept only so the limits stop counting the child.
+    if (entries.length)
+        await settled(ports.storage, sessionID, "failed", at).catch((error) => ports.log(`courier watch: could not note the failed turn of ${sessionID}: ${String(error)}`));
+    const out = await Promise.all(entries.map((entry) => outIn(ports, entry)));
+    // Left before the notice, so the parent waits on the group meanwhile; nudged after it, so the group's
+    // message does not overtake the notice, short of an interval tick falling in between.
+    const completed = await Promise.all(out.map((member) => (member ? leave(ports, member, "failed", at) : Promise.resolve(false))));
+    // A session courier_stop stopped is not a failure to tell: its parent was told of the stop, or ordered it.
+    const quiet = entries.length > 0 && (await stoppedSincePrompt(ports.storage, sessionID).catch(() => false));
+    try {
+        if (quiet)
+            return [];
+        await Promise.all(entries.map((entry, index) => ports.session.synthetic({
+            sessionID: entry.parentID,
+            text: envelope(sessionID, failureNotice(entry.title, error, out[index]?.group), { failed: error.type }),
+            description: `Session ${sessionID} failed`,
+            metadata: { source: "courier", from: sessionID, failed: true },
+            delivery: "steer",
+        })));
+    }
+    finally {
+        if (completed.includes(true))
+            ports.nudge();
+    }
     return entries.map((entry) => entry.parentID);
 }
+/** A child's membership of an open group it is still out in: the group waits for it, and its end takes it out without a report. */
+async function outIn(ports, entry) {
+    if (!entry.group)
+        return undefined;
+    try {
+        const member = await membershipOf(ports.storage, entry.parentID, entry.group, entry.sessionID);
+        return member?.out ? member : undefined;
+    }
+    catch (error) {
+        ports.log(`courier watch: could not read ${entry.sessionID}'s place in group ${entry.group}: ${String(error)}`);
+        return undefined;
+    }
+}
+/** Takes a member out of its group without a report; true when that completes the group, for the caller to nudge the scheduler. */
+async function leave(ports, member, by, at) {
+    try {
+        return await markLeft(ports.storage, member, by, at);
+    }
+    catch (error) {
+        ports.log(`courier watch: could not take ${member.sessionID} out of group ${member.group}: ${String(error)}`);
+        return false;
+    }
+}
+/** Inbox items that are not courier's or the parent's business: the person's own prompts, compactions and moves. */
+const UNOWED = new Set(["user", "compaction", "move"]);
+/** Remembers the type of an item enqueued for a spawned session, for `notePrompt`; other sessions cost one read. */
+export async function noteEnqueued(ports, inbox, event) {
+    const { sessionID, inboxID, item } = event.data;
+    if ((await indexedParent(ports.storage, sessionID)) === undefined)
+        return false;
+    setBounded(inbox, inboxID, item.type, SEEN_MAX);
+    return true;
+}
+/**
+ * Notes that a message reached a spawned session, which then owes its parent a report, unless `inbox` knows it for one of
+ * `UNOWED` (`spawn` notes the task itself); reads the reverse index alone, and claims nothing: the note is the same twice.
+ */
+export async function notePrompt(ports, event, inbox) {
+    const { sessionID, inboxID } = event.data;
+    // Kept, not deleted: the hub's other subscription looks it up for the same delivery.
+    if (inboxID !== undefined && UNOWED.has(inbox?.get(inboxID) ?? ""))
+        return false;
+    if ((await indexedParent(ports.storage, sessionID)) === undefined)
+        return false;
+    await prompted(ports.storage, sessionID, event.created ?? ports.now());
+    return true;
+}
+/**
+ * Notes that a spawned session's turn was stopped, which takes it out of its group without a report; one
+ * stopped by a shutdown resumes on the next start.
+ */
+export async function noteInterrupted(ports, event) {
+    if (event.data.reason === "shutdown")
+        return false;
+    const { sessionID } = event.data;
+    const entry = await indexedEntry(ports.storage, sessionID);
+    if (entry === undefined)
+        return false;
+    const at = event.created ?? ports.now();
+    await settled(ports.storage, sessionID, "interrupted", at);
+    const member = await outIn(ports, entry);
+    if (member && (await leave(ports, member, "interrupted", at)))
+        ports.nudge();
+    return true;
+}
+/**
+ * Drops the report state, and the groups, of a session OpenCode deleted, and the report state of the sessions it
+ * started, whose reports can no longer be delivered; it leaves its own group. Returns the sessions forgotten.
+ */
+export async function noteDeleted(ports, event) {
+    const { sessionID } = event.data;
+    const [parentID, started] = await Promise.all([indexedParent(ports.storage, sessionID), children(ports.storage, sessionID)]);
+    const forgotten = [...(parentID === undefined ? [] : [sessionID]), ...started.map((child) => child.sessionID)];
+    const entry = parentID === undefined ? undefined : await entryUnder(ports.storage, parentID, sessionID);
+    const member = entry && (await outIn(ports, entry));
+    // Its groups go whether or not it has children on the roster: a held report outlives the member's entry.
+    const [completed] = await Promise.all([
+        member ? leave(ports, member, "deleted", event.created ?? ports.now()) : Promise.resolve(false),
+        ...forgotten.map((id) => forgetReport(ports.storage, id)),
+        dropGroups(ports.storage, sessionID),
+    ]);
+    if (completed)
+        ports.nudge();
+    return forgotten;
+}
+/**
+ * Whether a session prompted at `prompt` waits: on an untold report of a session it started, a complete group of
+ * its about to be delivered, a request of its own, a scheduled message, or a webhook it subscribed to since. Cheapest first.
+ */
+async function waits(ports, sessionID, prompt) {
+    const started = await children(ports.storage, sessionID);
+    if ((await Promise.all(started.map((entry) => awaited(ports.storage, entry.sessionID)))).includes(true))
+        return true;
+    if ((await listEverywhere([...ports.permissions()], sessionID)).some((found) => found.requests.length))
+        return true;
+    // A group with a member still out is waited on through that member, above; one whose every out member was told of is not.
+    if (started.some((entry) => entry.group) && (await hasCompleteGroup(ports.storage, sessionID)))
+        return true;
+    if ((await pendingQuestions(ports.storage, sessionID)).length)
+        return true;
+    const [scheduled, subscribed] = await Promise.all([scheduledFor(ports.storage, sessionID), subscriptions(ports)]);
+    // An older subscription is no wait: a prompt, most likely its delivery, has come since.
+    return scheduled.length > 0 || subscribed.some((subscription) => subscription.sessionID === sessionID && subscription.createdAt >= prompt);
+}
+/**
+ * Tells the parent of a spawned session whose turn ended without reporting to it since its last
+ * prompt, unless it waits; finds the session by the reverse index alone. Returns the parents told.
+ */
+export async function reportSilent(ports, seen, event) {
+    const { sessionID } = event.data;
+    const entry = await indexedEntry(ports.storage, sessionID);
+    // Claimed after the lookup, so other sessions' turns do not crowd `seen`, and before anything is told.
+    if (!entry || !claim(seen, event.id))
+        return [];
+    const report = await reportOf(ports.storage, sessionID);
+    if (!report?.owes || (await waits(ports, sessionID, report.prompt)))
+        return [];
+    if (await stoppedSincePrompt(ports.storage, sessionID).catch(() => false))
+        return [];
+    // The notice goes out without the reply rather than not at all.
+    const lastText = await ports.session.context({ sessionID }).then(lastReply, () => undefined);
+    const group = (await outIn(ports, entry))?.group;
+    // Before the notice, which may end the parent's turn at once: once told, it no longer waits for this one.
+    const toldAt = event.created ?? ports.now();
+    await told(ports.storage, sessionID, toldAt).catch((error) => ports.log(`courier watch: could not note that the parent of ${sessionID} was told: ${String(error)}`));
+    try {
+        await ports.session.synthetic({
+            sessionID: entry.parentID,
+            text: envelope(sessionID, silentNotice(entry.title, lastText, report.progressed, group), { ended: "without-report" }),
+            description: `Session ${sessionID} ended without a report`,
+            metadata: { source: "courier", from: sessionID, ended: "without-report" },
+            delivery: "steer",
+        });
+    }
+    catch (error) {
+        // Not told after all: the parent still waits for it.
+        await untold(ports.storage, sessionID, toldAt).catch(() => undefined);
+        throw error;
+    }
+    return [entry.parentID];
+}
 /** The session at the top of a lineage: where its permission requests go, since that is where the person is. */
 const topOf = (chain) => chain.at(-1).parentID;
 /**
@@ -56,9 +220,8 @@ export async function reportAsked(ports, state, event) {
     return [topOf(chain)];
 }
 /**
- * Tells the session that was told about a request that it has been answered some other way, in the
- * child's own session or along with another answer, so it does not pass on a stale question.
- * Requests answered through courier_answer are no longer waiting and are skipped.
+ * Tells the session told about a request that it was answered some other way, so it does not pass on
+ * a stale question; requests answered through courier_answer no longer wait and are skipped.
  */
 export async function reportReplied(ports, state, event) {
     if (!claim(state.seen, event.id))
@@ -81,9 +244,8 @@ export async function reportReplied(ports, state, event) {
     return [topOf(chain)];
 }
 /**
- * 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.
+ * Tells the top session about a form OpenCode shows in a spawned session, such as web search asking
+ * for its provider, which only the person can answer; question forms are left to the question relay.
  */
 export async function reportForm(ports, state, event) {
     if (!claim(state.seen, event.id))
@@ -162,13 +324,46 @@ const pause = (ms, signal) => new Promise((resolve) => {
     }
     signal.addEventListener("abort", done);
 });
+const TURN_ENDS = new Set(["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"]);
+/** A session's turn ended, sealing its groups: one that is complete has the scheduler deliver it now. */
+async function sealGroups(ports, event) {
+    if (event.data.reason === "shutdown")
+        return;
+    try {
+        if (await hasCompleteGroup(ports.storage, event.data.sessionID))
+            ports.nudge();
+    }
+    catch (error) {
+        ports.log(`courier watch: could not read the groups of ${event.data.sessionID}: ${String(error)}`);
+    }
+}
 /**
  * Handles one event of OpenCode's stream; those that cannot concern a spawned child, or a question
  * relayed for one, are ignored.
  */
 async function handle(ports, state, event) {
+    try {
+        return await route(ports, state, event);
+    }
+    finally {
+        // After: a silent end is judged while the group the nudge may deliver is still there to wait on.
+        if (TURN_ENDS.has(event.type))
+            await sealGroups(ports, event);
+    }
+}
+async function route(ports, state, event) {
     if (event.type === "session.execution.failed")
         return reportFailure(ports, state.seen, event);
+    if (event.type === "session.execution.succeeded")
+        return reportSilent(ports, state.seen, event);
+    if (event.type === "session.execution.interrupted")
+        return noteInterrupted(ports, event);
+    if (event.type === "session.inbox.enqueued")
+        return noteEnqueued(ports, state.inbox, event);
+    if (event.type === "session.inbox.delivered")
+        return notePrompt(ports, event, state.inbox);
+    if (event.type === "session.deleted")
+        return noteDeleted(ports, event);
     if (event.type === "permission.asked")
         return reportAsked(ports, state, event);
     if (event.type === "permission.replied")
@@ -191,9 +386,8 @@ async function handle(ports, state, event) {
 }
 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.
+ * `events` until it ends or `signal` aborts, the stream left open; each wait hears the abort only while
+ * it waits, so a watcher that follows events for the life of the process holds nothing per event.
  */
 const until = (events, signal) => ({
     [Symbol.asyncIterator]: () => ({
@@ -229,12 +423,8 @@ function handleLogged(ports, state, event) {
     });
 }
 /**
- * Follows OpenCode's events until `signal` aborts, telling parents when a spawned child's turn
- * 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. 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.
+ * Follows OpenCode's events until `signal` aborts: tells parents of a spawned child's failed or silent
+ * turn, its pending permission or form, notes forms and shutdowns for the relay; ends after its current event.
  */
 export async function watchChildren(ports, state, signal, retryMs = RESUBSCRIBE_MS) {
     const relaying = new Set();
@@ -263,9 +453,8 @@ 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.
+            // Closed without waiting: closing the adapter's stream waits on OpenCode, which may not answer
+            // while a location closes, and the leave waiting for this watcher must not wait for that too.
             void events?.return?.().catch(() => { });
         }
         if (!signal.aborted)
@@ -274,12 +463,8 @@ export async function watchChildren(ports, state, signal, retryMs = RESUBSCRIBE_
     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.
+ * Makes the hub start its subscriptions to OpenCode's events with this copy's watcher, the one loaded
+ * last; `join` starts them. The second is a standby, connected before the first's member leaves.
  */
 export function watchFromHub(hub, state, retryMs = RESUBSCRIBE_MS) {
     hub.subscribe = (member) => {

package/dist/webhook.d.ts

@@ -22,9 +22,8 @@ export interface WebhookConfig {
     readonly maxBytes: number;
 }
 /**
- * Normalises a topic: `owner/repo` or `owner/repo#12` (optionally prefixed `github:`) is a GitHub
- * repository or one of its pull requests or issues; any other name of letters, digits, `.`, `_` and
- * `-` is a generic topic, posted to `/hook/<name>`.
+ * Normalises a topic: `owner/repo` or `owner/repo#12` (optionally `github:`-prefixed) is a GitHub
+ * repo, PR or issue; any other name of letters, digits, `.`, `_` and `-` is posted to `/hook/<name>`.
  */
 export declare function parseTopic(input: string): string;
 /** Subscribes an existing session to a topic; throws for a session OpenCode does not know. */
@@ -34,9 +33,8 @@ export declare function unsubscribe(ports: WebhookPorts, sessionID: string, topi
 /** Every subscription, or those to one topic. */
 export declare function subscriptions(ports: Pick<WebhookPorts, "storage">, topic?: string): Promise<Subscription[]>;
 /**
- * Checks an `X-Hub-Signature-256` header (`sha256=` and exactly 64 hex digits) in constant time and
- * returns the digest in canonical lowercase hex, or undefined when it does not match. Replays are
- * keyed by that digest, never by the header text, which could be re-cased or padded.
+ * Checks an `X-Hub-Signature-256` header (`sha256=` + 64 hex digits) in constant time, returning the
+ * digest in lowercase hex, or undefined; replays are keyed by that digest, never by the header text.
  */
 export declare function checkSignature(secret: string, body: Uint8Array, header: string | undefined, name?: string): string | undefined;
 /** The `X-Hub-Signature-256` value for a body; give the topic name for `/hook/<name>`. */
@@ -49,9 +47,8 @@ export interface Event {
     readonly summary: 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,
- * CI events that have not completed, and pull request or issue actions outside `ITEM_ACTIONS`.
+ * Maps a GitHub delivery to its topics (`github:owner/repo`, plus `github:owner/repo#N` for PRs and
+ * issues) and a summary; undefined for pings, unfinished CI events and actions outside `ITEM_ACTIONS`.
  */
 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. */
@@ -75,17 +72,15 @@ export interface Response {
     readonly body: string;
 }
 /**
- * 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.
+ * Handles one request: `POST /github` with GitHub's headers, or `POST /hook/<name>` signed over name
+ * and body; anything unsigned is refused before parsing, and a signature already accepted is ignored.
  */
 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>>;
 /**
- * Reads the plugin's `webhook` option. The secret comes from the file named by `secretFile`, or
- * else the environment variable named by `secretEnv` (default `COURIER_WEBHOOK_SECRET`); never from
- * the option itself, so it stays out of opencode.json. Undefined when the receiver is not configured.
+ * Reads the `webhook` option, undefined when the receiver is not configured; the secret comes from
+ * `secretFile` or the env var `secretEnv` (default `COURIER_WEBHOOK_SECRET`), never from the option.
  */
 export declare function readConfig(options: unknown, env?: Record<string, string | undefined>): WebhookConfig | undefined;
 export {};