opencode-courier 0.1.6

package/dist/relay.d.ts

@@ -0,0 +1,76 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import { type Pending } from "./courier.js";
+import { type RosterStorage } from "./roster.js";
+type Context = Plugin.Context;
+/** One location's pending permission requests. OpenCode keeps them per location, so an isolated child's are in its worktree's. */
+export type Permissions = Pick<Context["permission"], "list" | "reply">;
+/** The answers to a permission request, as OpenCode's own prompt offers them. */
+export declare const REPLIES: readonly ["once", "always", "reject"];
+export type Reply = (typeof REPLIES)[number];
+/**
+ * Sent with a rejection that has no reason of its own. OpenCode ends the child's turn on a bare
+ * rejection, and the child would never report back; with a message, the call fails and it carries on.
+ */
+export declare const REJECTED = "Refused by the session that started you. Do without it, or report back why you cannot.";
+/** The part of OpenCode's `permission.asked` event the notice is made from. */
+export interface PermissionAsked {
+    readonly id: string;
+    readonly data: {
+        readonly id: string;
+        readonly sessionID: string;
+        readonly action: string;
+        readonly resources: ReadonlyArray<string>;
+        readonly save?: ReadonlyArray<string> | undefined;
+        readonly message?: string | undefined;
+    };
+}
+/** The part of OpenCode's `permission.replied` event. */
+export interface PermissionReplied {
+    readonly id: string;
+    readonly data: {
+        readonly sessionID: string;
+        readonly requestID: string;
+        readonly reply: Reply;
+    };
+}
+/**
+ * Shared by every plugin instance in the process, like the handled event ids: the requests whose
+ * notice went to a parent and that courier_answer has not answered yet.
+ */
+export type Waiting = Set<string>;
+/** How a notice names where the asking session came from, to the session at the top of its lineage. */
+export declare const origin: (startedBy?: string) => string;
+/** For a notice that a session's turn ended without it finishing. */
+export declare const STAYS_QUIET = "and then it does not report back on its own: if it stays quiet, message it with courier_send to have it carry on.";
+/**
+ * What the session at the top is told. `startedBy` names the session that started the asking one
+ * when that is not the top session itself, but one started from it.
+ */
+export declare function permissionNotice(title: string, request: PermissionAsked["data"], startedBy?: string): string;
+export declare function settledNotice(title: string, requestID: string, reply: Reply): string;
+export interface AnswerPorts {
+    readonly storage: RosterStorage;
+    /** The permission domains of every loaded location; the request is answered where it is pending. */
+    readonly permissions: () => Iterable<Permissions>;
+}
+export interface AnswerInput {
+    readonly sessionID: string;
+    readonly requestID: string;
+    readonly reply: string;
+    readonly message?: string;
+}
+/**
+ * Answers a permission request of a session started, directly or through others, from the
+ * caller, which must be the session at the top: requests go there, to the person, so a session
+ * started with courier_spawn cannot approve what its own children ask. `answered` is false when
+ * nothing was waiting.
+ */
+export declare function answer(ports: AnswerPorts, waiting: Waiting, callerID: string, input: AnswerInput): Promise<{
+    sessionID: string;
+    requestID: string;
+    reply: "once" | "always" | "reject";
+    answered: boolean;
+}>;
+/** The requests a session waits on, in whichever location holds them, for courier_status. */
+export declare function pendingOf(permissions: Iterable<Permissions>, sessionID: string): Promise<Pending[]>;
+export {};

package/dist/relay.js

@@ -0,0 +1,118 @@
+import { describeFailure } from "./courier.js";
+import { answeringTop } from "./roster.js";
+/** The answers to a permission request, as OpenCode's own prompt offers them. */
+export const REPLIES = ["once", "always", "reject"];
+/**
+ * Sent with a rejection that has no reason of its own. OpenCode ends the child's turn on a bare
+ * rejection, and the child would never report back; with a message, the call fails and it carries on.
+ */
+export const REJECTED = "Refused by the session that started you. Do without it, or report back why you cannot.";
+const MAX_RESOURCES = 20;
+const MAX_RESOURCE_LENGTH = 300;
+const clip = (text) => (text.length > MAX_RESOURCE_LENGTH ? `${text.slice(0, MAX_RESOURCE_LENGTH - 3)}...` : text);
+function alwaysChoice(request) {
+    const save = request.save ?? [];
+    if (!save.length)
+        return [];
+    const scope = save.length === 1 && save[0] === "*" ? `every ${request.action} request` : `requests matching ${save.join(", ")}`;
+    return [`- always: allow it, and from now on ${scope} in this project`];
+}
+/** How a notice names where the asking session came from, to the session at the top of its lineage. */
+export const origin = (startedBy) => startedBy ? `which ${startedBy} started with courier_spawn, a session started from yours,` : "which you started with courier_spawn,";
+/** For a notice that a session's turn ended without it finishing. */
+export const STAYS_QUIET = "and then it does not report back on its own: if it stays quiet, message it with courier_send to have it carry on.";
+/**
+ * What the session at the top is told. `startedBy` names the session that started the asking one
+ * when that is not the top session itself, but one started from it.
+ */
+export function permissionNotice(title, request, startedBy) {
+    const resources = request.resources.slice(0, MAX_RESOURCES).map((resource) => `- ${clip(resource)}`);
+    if (request.resources.length > MAX_RESOURCES)
+        resources.push(`- and ${request.resources.length - MAX_RESOURCES} more`);
+    return [
+        `This session, "${title}", ${origin(startedBy)} is waiting for permission and does nothing until it is answered.`,
+        `It asks for: ${request.action}`,
+        ...(resources.length ? ["On:", ...resources] : []),
+        ...(request.message ? [`Note: ${request.message}`] : []),
+        "",
+        "Do not decide this yourself. Ask the person you are working with (with your question tool, if you have one), offering exactly these choices:",
+        "- once: allow this request only",
+        ...alwaysChoice(request),
+        "- reject: refuse it, with a reason if they give one; the session's call fails and it carries on",
+        `When they have chosen, call courier_answer with sessionID "${request.sessionID}", requestID "${request.id}", reply set to their choice and, with reject, message set to their reason.`,
+    ].join("\n");
+}
+export function settledNotice(title, requestID, reply) {
+    return [
+        `The permission request ${requestID} of this session, "${title}", has been answered (${reply}) without courier_answer, so it no longer waits on you.`,
+        "If you asked someone about it, tell them it is settled; there is nothing to pass on.",
+        ...(reply === "reject"
+            ? [`A refusal without a reason ends the session's turn, ${STAYS_QUIET}`]
+            : []),
+    ].join("\n");
+}
+/** A session's pending requests in every location, with the domain holding each; a location that cannot be read gives its error. */
+function listEverywhere(permissions, sessionID) {
+    return Promise.all([...permissions].map((domain) => domain.list({ sessionID }).then((requests) => ({ domain, requests: requests.filter((request) => request.sessionID === sessionID) }), (error) => ({ domain, requests: [], error }))));
+}
+/** The location holding a pending request, and the request; undefined when none does, and an error when one could not be read. */
+async function locate(ports, sessionID, requestID) {
+    const listed = await listEverywhere(ports.permissions(), sessionID);
+    for (const { domain, requests } of listed) {
+        const request = requests.find((item) => item.id === requestID);
+        if (request)
+            return { domain, request };
+    }
+    const failed = listed.find((item) => "error" in item);
+    if (failed && "error" in failed)
+        throw failed.error;
+    return undefined;
+}
+/**
+ * Answers a permission request of a session started, directly or through others, from the
+ * caller, which must be the session at the top: requests go there, to the person, so a session
+ * started with courier_spawn cannot approve what its own children ask. `answered` is false when
+ * nothing was waiting.
+ */
+export async function answer(ports, waiting, callerID, input) {
+    const reply = input.reply;
+    if (!REPLIES.includes(reply))
+        throw new Error(`reply must be once, always or reject, not "${input.reply}".`);
+    const { sessionID, requestID } = input;
+    await answeringTop(ports.storage, sessionID, callerID, "permission requests");
+    const found = await locate(ports, sessionID, requestID);
+    if (!found) {
+        waiting.delete(requestID);
+        return { sessionID, requestID, reply, answered: false };
+    }
+    if (reply === "always" && !found.request.save?.length)
+        throw new Error(`always is not offered for ${requestID}: it has nothing to save. Ask again with once or reject.`);
+    // Off the waiting list first, so the reply event this answer causes does not come back as a notice.
+    waiting.delete(requestID);
+    const message = reply === "reject" ? input.message || REJECTED : undefined;
+    try {
+        await found.domain.reply({ sessionID, requestID, reply, ...(message ? { message } : {}) });
+    }
+    catch (error) {
+        if (await locate(ports, sessionID, requestID).catch(() => found)) {
+            waiting.add(requestID);
+            throw error;
+        }
+        throw new Error(`${describeFailure("permission.reply", error).message}, but ${requestID} no longer waits, so it was answered, possibly by this call.`);
+    }
+    return { sessionID, requestID, reply, answered: true };
+}
+/** The requests a session waits on, in whichever location holds them, for courier_status. */
+export async function pendingOf(permissions, sessionID) {
+    const found = new Map();
+    for (const { requests } of await listEverywhere(permissions, sessionID))
+        for (const request of requests)
+            found.set(request.id, {
+                type: "permission",
+                requestID: request.id,
+                action: request.action,
+                resources: [...request.resources],
+                ...(request.save?.length ? { save: [...request.save] } : {}),
+            });
+    return [...found.values()];
+}

package/dist/roster.d.ts

@@ -0,0 +1,51 @@
+import { type Storage } from "./storage.js";
+/**
+ * Entries older than this are dropped when their parent's roster is read, and on plugin setup,
+ * except isolated children whose worktree is still there: those stay until courier_cleanup.
+ */
+export declare const RETENTION_MS: number;
+/** A session started with courier_spawn, recorded under the session that started it. */
+export interface RosterEntry {
+    readonly sessionID: string;
+    readonly parentID: string;
+    readonly title: string;
+    readonly directory: string;
+    readonly isolated: boolean;
+    readonly createdAt: number;
+    /** For an isolated child, the directory its worktree was made from; courier_cleanup removes it through there. */
+    readonly source?: string;
+    /** For an isolated child, the commit its worktree was made from; its own work is what came after. */
+    readonly base?: string;
+}
+export type RosterStorage = Storage;
+export declare function rosterKey(parentID: string, sessionID: string): string;
+export declare function record(storage: RosterStorage, entry: RosterEntry): Promise<void>;
+/** Removes a child from its parent's roster; false when it was not there. */
+export declare function forget(storage: RosterStorage, parentID: string, sessionID: string): Promise<boolean>;
+/** A parent's children, oldest first. */
+export declare function children(storage: RosterStorage, parentID: string): Promise<RosterEntry[]>;
+/** Every parent's children. */
+export declare function allEntries(storage: RosterStorage): Promise<RosterEntry[]>;
+/** A session's roster entries: one for the parent that started it, none if courier_spawn did not. */
+export declare function entriesOf(storage: RosterStorage, sessionID: string): Promise<RosterEntry[]>;
+/**
+ * The roster entries from a session up to the top, its own first: the session's, its parent's, and
+ * so on, ending with the entry whose parent courier_spawn did not start. Empty when courier_spawn
+ * did not start the session.
+ */
+export declare function lineage(storage: RosterStorage, sessionID: string): Promise<RosterEntry[]>;
+/** `lineage` over roster entries already read. */
+export declare function lineageIn(entries: ReadonlyArray<RosterEntry>, sessionID: string): RosterEntry[];
+/**
+ * The session at the top of a spawned session's lineage, where its permission requests and
+ * questions go, since that is where the person is; only it may answer them. Throws when the
+ * session was not started with courier_spawn or `callerID` is another session. `what` names
+ * what is being answered.
+ */
+export declare function answeringTop(storage: RosterStorage, sessionID: string, callerID: string, what: string): Promise<string>;
+/** Whether a directory still exists; tests pass a fake. */
+export type Exists = (directory: string) => boolean;
+/** A parent's children, oldest first, after dropping the expired ones. */
+export declare function current(storage: RosterStorage, parentID: string, now: number, exists?: Exists): Promise<RosterEntry[]>;
+/** Drops expired entries of every parent, so parents that never list their children don't keep them forever. */
+export declare function pruneExpired(storage: RosterStorage, now: number, exists?: Exists): Promise<void>;

package/dist/roster.js

@@ -0,0 +1,83 @@
+import { existsSync } from "node:fs";
+import { scanAll } from "./storage.js";
+/**
+ * Entries older than this are dropped when their parent's roster is read, and on plugin setup,
+ * except isolated children whose worktree is still there: those stay until courier_cleanup.
+ */
+export const RETENTION_MS = 14 * 24 * 60 * 60_000;
+const PREFIX = "roster/";
+export function rosterKey(parentID, sessionID) {
+    return `${PREFIX}${parentID}/${sessionID}`;
+}
+export async function record(storage, entry) {
+    await storage.set(rosterKey(entry.parentID, entry.sessionID), { ...entry });
+}
+/** Removes a child from its parent's roster; false when it was not there. */
+export async function forget(storage, parentID, sessionID) {
+    const key = rosterKey(parentID, sessionID);
+    if ((await storage.get(key)) === undefined)
+        return false;
+    await storage.remove(key);
+    return true;
+}
+/** A parent's children, oldest first. */
+export async function children(storage, parentID) {
+    const entries = await scanAll(storage, `${PREFIX}${parentID}/`);
+    return entries.sort((a, b) => a.createdAt - b.createdAt);
+}
+/** Every parent's children. */
+export async function allEntries(storage) {
+    return scanAll(storage, PREFIX);
+}
+/** A session's roster entries: one for the parent that started it, none if courier_spawn did not. */
+export async function entriesOf(storage, sessionID) {
+    return (await scanAll(storage, PREFIX)).filter((entry) => entry.sessionID === sessionID);
+}
+/**
+ * The roster entries from a session up to the top, its own first: the session's, its parent's, and
+ * so on, ending with the entry whose parent courier_spawn did not start. Empty when courier_spawn
+ * did not start the session.
+ */
+export async function lineage(storage, sessionID) {
+    return lineageIn(await allEntries(storage), sessionID);
+}
+/** `lineage` over roster entries already read. */
+export function lineageIn(entries, sessionID) {
+    const bySession = new Map(entries.map((entry) => [entry.sessionID, entry]));
+    const chain = [];
+    for (let entry = bySession.get(sessionID); entry && !chain.includes(entry); entry = bySession.get(entry.parentID))
+        chain.push(entry);
+    return chain;
+}
+/**
+ * The session at the top of a spawned session's lineage, where its permission requests and
+ * questions go, since that is where the person is; only it may answer them. Throws when the
+ * session was not started with courier_spawn or `callerID` is another session. `what` names
+ * what is being answered.
+ */
+export async function answeringTop(storage, sessionID, callerID, what) {
+    const chain = await lineage(storage, sessionID);
+    if (!chain.length)
+        throw new Error(`${sessionID} was not started with courier_spawn, so courier_answer cannot answer for it.`);
+    const top = chain.at(-1).parentID;
+    if (top !== callerID)
+        throw new Error(`${sessionID}'s ${what} go to ${top}, the session at the top of the sessions started from it with courier_spawn; ${callerID} cannot answer them.`);
+    return top;
+}
+/**
+ * Removes the given entries that were recorded more than `RETENTION_MS` before `now`, and returns
+ * the rest. An isolated child is kept while its worktree exists, so it can still be cleaned up.
+ */
+async function dropExpired(storage, entries, now, exists) {
+    const expired = new Set(entries.filter((entry) => now - entry.createdAt > RETENTION_MS && !(entry.isolated && exists(entry.directory))));
+    await Promise.all([...expired].map((entry) => storage.remove(rosterKey(entry.parentID, entry.sessionID))));
+    return entries.filter((entry) => !expired.has(entry));
+}
+/** A parent's children, oldest first, after dropping the expired ones. */
+export async function current(storage, parentID, now, exists = existsSync) {
+    return dropExpired(storage, await children(storage, parentID), now, exists);
+}
+/** Drops expired entries of every parent, so parents that never list their children don't keep them forever. */
+export async function pruneExpired(storage, now, exists = existsSync) {
+    await dropExpired(storage, await scanAll(storage, PREFIX), now, exists);
+}

package/dist/storage.d.ts

@@ -0,0 +1,6 @@
+import type { Plugin } from "@opencode-ai/plugin";
+type Context = Plugin.Context;
+export type Storage = Pick<Context["storage"], "get" | "set" | "remove" | "scan">;
+/** Every value stored under `prefix`, following the scan's pages. */
+export declare function scanAll<T>(storage: Pick<Storage, "scan">, prefix: string): Promise<T[]>;
+export {};

package/dist/storage.js

@@ -0,0 +1,12 @@
+/** Every value stored under `prefix`, following the scan's pages. */
+export async function scanAll(storage, prefix) {
+    const values = [];
+    let after;
+    do {
+        const page = await storage.scan({ prefix, ...(after ? { after } : {}) });
+        for (const entry of page.entries)
+            values.push(entry.value);
+        after = page.next;
+    } while (after);
+    return values;
+}

package/dist/watch.d.ts

@@ -0,0 +1,69 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import { type PermissionAsked, type PermissionReplied, type Waiting } from "./relay.js";
+import { type RosterStorage } from "./roster.js";
+type Context = Plugin.Context;
+/** How long to wait before subscribing again after the event stream ended or broke. */
+export declare const RESUBSCRIBE_MS = 5000;
+export interface WatchPorts {
+    readonly storage: RosterStorage;
+    readonly session: Pick<Context["session"], "synthetic">;
+    readonly event: Pick<Context["event"], "subscribe">;
+    /** This location's pending permission requests, relayed when the watcher (re)subscribes. */
+    readonly permission: Pick<Context["permission"], "list">;
+    readonly log: (message: string) => void;
+}
+/**
+ * What every plugin instance in the process shares: OpenCode sets the plugin up once per project
+ * location, all in one process, and each instance may see the same event, so an event id is
+ * claimed synchronously and handled once. `waiting` holds the permission requests a session was
+ * told about and has not answered; `answered`, requests answered before anyone was told, so a
+ * notice whose roster lookup was overtaken by the answer is not sent.
+ */
+export interface WatchState {
+    readonly seen: Set<string>;
+    readonly waiting: Waiting;
+    readonly answered: Set<string>;
+}
+/** The part of OpenCode's `session.execution.failed` event the notice is made from. */
+export interface ExecutionFailed {
+    readonly id: string;
+    readonly data: {
+        readonly sessionID: string;
+        readonly error: {
+            readonly type: string;
+            readonly message: string;
+            readonly status?: number | undefined;
+        };
+    };
+}
+export declare function failureNotice(title: string, error: ExecutionFailed["data"]["error"]): string;
+/** Adds to a bounded set, dropping the oldest entry; false when the value was there already. */
+export declare function claim(set: Set<string>, value: string): boolean;
+/**
+ * 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[]>;
+/**
+ * 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.
+ */
+export declare function reportReplied(ports: WatchPorts, state: WatchState, event: PermissionReplied): Promise<string[]>;
+/**
+ * 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.
+ */
+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 and when that request is answered without them, and
+ * noting the question forms shown, which the question relay waits for.
+ */
+export declare function watchChildren(ports: WatchPorts, state: WatchState, signal: AbortSignal, retryMs?: number): Promise<void>;
+export {};

package/dist/watch.js

@@ -0,0 +1,167 @@
+import { envelope } from "./courier.js";
+import { eventsFollowed, eventsLeft, formShown, formsMayHaveBeenMissed } from "./question.js";
+import { permissionNotice, settledNotice } 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;
+}
+/**
+ * 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 async function reportFailure(ports, seen, event) {
+    if (!claim(seen, event.id))
+        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",
+        });
+    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. */
+const topOf = (chain) => chain.at(-1).parentID;
+/**
+ * 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 async function reportAsked(ports, state, event) {
+    if (!claim(state.seen, event.id))
+        return [];
+    const request = event.data;
+    const chain = await lineage(ports.storage, request.sessionID);
+    // Claimed only now, after the lookup: a request answered meanwhile is in `answered`, and one
+    // already relayed, from the event or from the pending list, is in `waiting`.
+    if (!chain.length || state.answered.has(request.id) || !claim(state.waiting, request.id))
+        return [];
+    const startedBy = chain.length > 1 ? chain[0].parentID : undefined;
+    await ports.session.synthetic({
+        sessionID: topOf(chain),
+        text: envelope(request.sessionID, permissionNotice(chain[0].title, request, startedBy), {
+            asks: "permission",
+            request: request.id,
+        }),
+        description: `Session ${request.sessionID} asks for permission`,
+        metadata: { source: "courier", from: request.sessionID, asks: "permission", requestID: request.id },
+        delivery: "steer",
+    });
+    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.
+ */
+export async function reportReplied(ports, state, event) {
+    if (!claim(state.seen, event.id))
+        return [];
+    const { sessionID, requestID, reply } = event.data;
+    if (!state.waiting.delete(requestID)) {
+        claim(state.answered, requestID);
+        return [];
+    }
+    const chain = await lineage(ports.storage, sessionID);
+    if (!chain.length)
+        return [];
+    await ports.session.synthetic({
+        sessionID: topOf(chain),
+        text: envelope(sessionID, settledNotice(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",
+    });
+    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.
+ */
+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 pause = (ms, signal) => new Promise((resolve) => {
+    const timer = setTimeout(done, ms);
+    function done() {
+        clearTimeout(timer);
+        signal.removeEventListener("abort", done);
+        resolve();
+    }
+    signal.addEventListener("abort", done);
+});
+/** Handles one event of OpenCode's stream; those that cannot concern a spawned child are ignored. */
+async function handle(ports, state, event) {
+    if (event.type === "session.execution.failed")
+        return reportFailure(ports, state.seen, event);
+    if (event.type === "permission.asked")
+        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")
+        formShown(event);
+    return [];
+}
+/**
+ * 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
+ * noting the question forms shown, which the question relay waits for.
+ */
+export async function watchChildren(ports, state, signal, retryMs = RESUBSCRIBE_MS) {
+    while (!signal.aborted) {
+        let following = false;
+        try {
+            const events = ports.event.subscribe({ signal });
+            // 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) {
+                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)}`);
+                });
+            }
+        }
+        catch (error) {
+            if (!signal.aborted)
+                ports.log(`courier watch: event stream broke: ${String(error)}`);
+        }
+        finally {
+            if (following)
+                eventsLeft();
+        }
+        if (!signal.aborted)
+            await pause(retryMs, signal);
+    }
+}