opencode-courier 0.3.0 → 0.4.0

package/dist/person/text.js

@@ -0,0 +1,262 @@
+/** The permission, form and question notices and the result of courier_answer, snapshotted with the other texts. */
+import { END_TURN } from "../kernel/protocol.js";
+export function answerText(result) {
+    // A permission request is pending only in the server running the session's turn; a question is
+    // stored where every server on the data directory finds it.
+    if (!result.answered && "reply" in result)
+        return (`Nothing was passed on: no request ${result.requestID} of ${result.sessionID} is pending in this OpenCode server. ` +
+            "It was answered some other way, or the session stopped waiting, or it waits in another OpenCode server on the " +
+            "same data directory, which this one cannot reach; only the person can see which. Tell them: \"Your answer was " +
+            "not passed on. If the session still waits, its request is in another OpenCode server: answer it there, in that " +
+            `session." Do not message the session about it or answer it again from here. ${END_TURN}`);
+    if (!result.answered)
+        return (`${result.sessionID} no longer waits on question ${result.requestID}: it was answered some other way, or the ` +
+            "session stopped waiting. Nothing was passed on; tell the person their answer is not needed.");
+    if ("reply" in result)
+        return `Passed on ${result.reply} for request ${result.requestID} of ${result.sessionID}, which carries on and reports back with courier_send. ${END_TURN}`;
+    const how = result.by === "message" ? " as a message, since its question had been cut off" : "";
+    return `Passed the answers to question ${result.requestID} on to ${result.sessionID}${how}; it carries on and reports back with courier_send. ${END_TURN}`;
+}
+// Permission requests.
+/**
+ * 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, native = false) {
+    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}`] : []),
+        "",
+        ...(native ? NATIVE_PERMISSION : PERMISSION_ASK),
+        "- 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");
+}
+const PERMISSION_ASK = [
+    "Do not decide this yourself. Ask the person you are working with (with your question tool, if you have one), offering exactly these choices:",
+];
+/** For a native child's request, which OpenCode shows the person itself, in the top session's view. */
+const NATIVE_PERMISSION = [
+    "OpenCode already shows this request to the person you are working with, as its own permission prompt in your session (and in the paired app's request dock), where they answer it; you will be told once it is answered.",
+    "Do not ask them yourself, with your question tool or in your reply, and do not decide it: at most tell them in one line that this session waits on their permission, then end your turn.",
+    "Only if they ask you to answer it for them, these are the choices:",
+];
+/** What the session told about a permission request is told once it is answered without courier_answer. */
+export function permissionSettledNotice(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");
+}
+// Forms.
+/** The `metadata.kind` of the forms OpenCode's web search asks its provider with. */
+export const WEBSEARCH_FORM = "websearch.provider";
+/** A form's `metadata.kind`, when it has one that can go in a notice's envelope. */
+export const kindOf = (form) => {
+    const kind = form.metadata?.kind;
+    return typeof kind === "string" && /^[\w.-]{1,60}$/.test(kind) ? kind : undefined;
+};
+function fieldLines(field) {
+    const label = [field.title, field.description].filter(Boolean).join(": ") || field.key;
+    const options = (field.options ?? []).slice(0, MAX_RESOURCES).map((option) => `  - ${clip(option.label)}`);
+    if ((field.options?.length ?? 0) > MAX_RESOURCES)
+        options.push(`  - and ${field.options.length - MAX_RESOURCES} more`);
+    let kind = ` (${field.type})`;
+    if (field.type === "external" && field.url)
+        kind = `, opens ${clip(field.url)}`;
+    else if (field.options?.length)
+        kind = "";
+    const when = field.when?.length ? " (only for some earlier answers)" : "";
+    return [`- ${clip(label)}${kind}${when}`, ...options];
+}
+/** The fields the person sees, as notice lines. */
+function formLines(fields) {
+    const shown = fields.filter((field) => !field.hidden);
+    const lines = shown.slice(0, MAX_RESOURCES).flatMap(fieldLines);
+    if (shown.length > MAX_RESOURCES)
+        lines.push(`- and ${shown.length - MAX_RESOURCES} more fields`);
+    return lines;
+}
+const WEBSEARCH_NOTE = [
+    "This is OpenCode asking whether to search the web, and through which provider.",
+    'It waits at most a minute; then the session\'s search fails with "Web search cancelled" and it carries on without it.',
+    "The choice is kept for every session: once it is made, in any session, no session is asked again.",
+    'Besides answering the form, the person can make it by running a web search in their own session, or under OpenCode\'s "Third-party search" setting.',
+];
+/**
+ * Where the person answers a form: in its own session, or, for a native child, in the view of `shownIn`, the
+ * top of its native tree, where OpenCode lists the asks of the sessions under it; `top` is the session told.
+ */
+function formPlace(sessionID, shownIn, top) {
+    if (shownIn === sessionID)
+        return { where: `in session ${sessionID} itself`, which: "that session" };
+    const lists = "where OpenCode shows the forms of the sessions under it";
+    if (shownIn === top)
+        return { where: `in your own session, ${lists}`, which: "your session" };
+    return { where: `in session ${shownIn}, ${lists}`, which: `session ${shownIn}` };
+}
+/**
+ * What the session at the top is told about a form OpenCode shows in a session started with
+ * courier_spawn, which the plugin cannot pass on or answer: only the person can, where OpenCode shows it.
+ */
+export function formNotice(title, form, startedBy, shownIn = form.sessionID, top = "") {
+    const { where, which } = formPlace(form.sessionID, shownIn, top);
+    return [
+        `This session, "${title}", ${origin(startedBy)} shows a form, "${clip(form.title)}", and waits until it is answered.`,
+        ...formLines(form.fields),
+        ...(kindOf(form) === WEBSEARCH_FORM ? ["", ...WEBSEARCH_NOTE] : []),
+        "",
+        `Neither you nor courier_answer can answer it: only the person you are working with can, ${where}.`,
+        `Do not choose for them. Tell them ${which} shows this form and waits on them, then carry on.`,
+    ].join("\n");
+}
+/** What the session told about a form is told once it is answered or withdrawn. */
+export function formSettledNotice(title, formID, settled) {
+    return [
+        settled === "answered"
+            ? `The form ${formID} of this session, "${title}", has been answered, so it no longer waits on it.`
+            : `The form ${formID} of this session, "${title}", has been withdrawn unanswered: dismissed, given up on or cut off, so it no longer waits on it.`,
+        "If you told someone about it, tell them it is settled; there is nothing to pass on.",
+    ].join("\n");
+}
+// Questions.
+/** What OpenCode's question tool tells the asking model once it has the answers. */
+export function answeredText(questions, answers) {
+    const formatted = questions
+        .map((prompt, index) => `"${prompt.question}"="${answers[index]?.length ? answers[index].join(", ") : "Unanswered"}"`)
+        .join(", ");
+    return `User has answered your questions: ${formatted}. You can now continue with the user's answers in mind.`;
+}
+const describeOption = (option) => option.description ? `   - ${option.label}: ${option.description}` : `   - ${option.label}`;
+const describeQuestions = (questions) => questions.flatMap((prompt, index) => [
+    `${index + 1}. ${prompt.header}: ${prompt.question} (${prompt.multiple ? "any of" : "one of"}, or an answer of their own:)`,
+    ...prompt.options.map(describeOption),
+]);
+const CUT_OFF = {
+    stopped: "its turn was stopped (interrupted, or ended by OpenCode after an hour without activity)",
+    restarted: "OpenCode restarted, or closed the session's project",
+};
+/** What the top session is told about a question, when it is asked or after its call was cut off. */
+export function questionNotice(asked, cutOff) {
+    return [
+        cutOff
+            ? `This session, "${asked.title}", ${origin(asked.startedBy)} was asking the question below when ${CUT_OFF[cutOff]}. The question is no longer shown anywhere, and the session does nothing until it gets the answer.`
+            : `This session, "${asked.title}", ${origin(asked.startedBy)} asks the question below and waits for the answer.`,
+        ...describeQuestions(asked.questions),
+        "",
+        "Do not answer it yourself. Ask the person you are working with, using your question tool with exactly these questions:",
+        JSON.stringify({ questions: asked.questions }),
+        `What they choose there is passed on to the session${cutOff ? " as a message, which wakes it" : ""}. If you cannot use your question tool, or they answer some other way, call courier_answer with sessionID "${asked.sessionID}", requestID "${asked.requestID}" and answers: one entry per question, in order, each the label they chose or the text they gave (a list of labels where a question allows several).`,
+    ].join("\n");
+}
+/**
+ * What the top session is told about a native child's question, which OpenCode shows the person in the
+ * top session's own view: they answer it there, so the top session does not ask them again.
+ */
+export function nativeQuestionNotice(asked) {
+    return [
+        `This session, "${asked.title}", ${origin(asked.startedBy)} asks the question below and waits for the answer.`,
+        ...describeQuestions(asked.questions),
+        "",
+        "OpenCode shows this question to the person you are working with in your own session, and they answer it there; you will be told once it is answered.",
+        "Do not ask them yourself, with your question tool or in your reply, and do not answer it: at most tell them in one line that this session's question waits for them, then end your turn.",
+        `If they give you the answer some other way, call courier_answer with sessionID "${asked.sessionID}", requestID "${asked.requestID}" and answers: one entry per question, in order, each the label they chose or the text they gave (a list of labels where a question allows several).`,
+    ].join("\n");
+}
+/** How a question was settled without the top session, as its settled notice puts it. */
+function settledHow(asked, how) {
+    const where = asked.native || (how.by === "child" && how.via === "inbox") ? "by the person" : "in its own session";
+    if (how.by === "child")
+        return `answered ${where} (${answeredText(asked.questions, how.answers)})`;
+    if (how.by === "dismissed")
+        return `dismissed ${where}, without an answer`;
+    return `ended without an answer: its question call failed (${how.error})`;
+}
+/** What the top session is told about a question settled without it. */
+export function questionSettledNotice(asked, how) {
+    const what = settledHow(asked, how);
+    return [
+        `The question ${asked.requestID} of this session, "${asked.title}", was ${what}, so it no longer waits on you.`,
+        "If you asked someone about it, tell them it is settled; there is nothing to pass on.",
+        ...(how.by === "child"
+            ? []
+            : [`That ends the session's turn, ${STAYS_QUIET}`]),
+    ].join("\n");
+}
+/** The result of a spawned session's question call that the person dismissed through the top session. */
+export const DISMISSED = "The person dismissed this question without answering it. Carry on without the answers, or report back with courier_send to the session that started you why you cannot.";
+/** The message a spawned session whose question call was cut off gets, with the top session's outcome. */
+export function cutOffAnswer(asked, outcome) {
+    return "answers" in outcome
+        ? `Your question ${asked.requestID} was cut off before it was answered; here is the answer. ${answeredText(asked.questions, outcome.answers)}`
+        : `Your question ${asked.requestID} was cut off before it was answered, and then dismissed without an answer. Carry on without the answers, or report back with courier_send why you cannot.`;
+}
+/**
+ * What a top session's question call that no waiting question was linked to adds to its result, when
+ * questions with the same choices wait: `waiting` lists them.
+ */
+export function unlinkedNote(waiting) {
+    const which = waiting.map((question) => `session ${question.sessionID} (requestID "${question.requestID}")`).join(", ");
+    return `If you asked this for ${which}, these answers were not passed on by themselves: pass them on with courier_answer.`;
+}
+/** How a linked call's question was settled without it, as its withdrawn result puts it. */
+function withdrawnHow(linked, how) {
+    switch (how.by) {
+        case "top":
+            return "answers" in how.outcome
+                ? `already answered with courier_answer (${answeredText(linked.questions, how.outcome.answers)})`
+                : "already dismissed in your session, so it carries on without the answers";
+        case "child":
+            return `answered ${how.via === "inbox" ? "by the person" : "in its own session"} (${answeredText(linked.questions, how.answers)})`;
+        case "dismissed":
+            return "dismissed in its own session, which ends its turn; message it with courier_send if it should carry on";
+        case "failed":
+            return `ended: its question call failed (${how.error})`;
+    }
+}
+/** The result of a linked call withdrawn because its question was settled without it. */
+export function withdrawnText(linked, how) {
+    return `Session ${linked.sessionID} no longer waits on this question: it was ${withdrawnHow(linked, how)}. There is nothing to pass on; tell the person it is settled.`;
+}
+/**
+ * What a linked call adds to the person's answers about passing them on: `passed` is "result",
+ * "message", undefined when it no longer waited, or the error as `error: <message>`.
+ */
+export function passedNote(linked, passed) {
+    if (passed === "result")
+        return `These answers were passed on to session ${linked.sessionID}, which carries on with them; do not call courier_answer for ${linked.requestID}. ${END_TURN}`;
+    if (passed === "message")
+        return `These answers were passed on to session ${linked.sessionID} as a message, since its question had been cut off; it carries on with them. Do not call courier_answer for ${linked.requestID}. ${END_TURN}`;
+    if (passed === undefined)
+        return `Session ${linked.sessionID} no longer waits on this question: it had already been answered or settled, so these answers were not passed on; tell the person so.`;
+    return `Passing these answers on to session ${linked.sessionID} failed (${passed.slice(7)}); call courier_answer with requestID "${linked.requestID}" to pass them on.`;
+}

package/dist/person/tools.d.ts

@@ -0,0 +1,20 @@
+import { Schema } from "effect";
+import { type ToolEditor } from "../kernel/tool.js";
+import { type AnswerPorts, type Waiting } from "./permission.js";
+import { type QuestionPorts } from "./question/index.js";
+export declare const AnswerInput: Schema.Struct<{
+    readonly sessionID: Schema.String;
+    readonly requestID: Schema.String;
+    readonly reply: Schema.optional<Schema.Literals<readonly ["once", "always", "reject"]>>;
+    readonly message: Schema.optional<Schema.String>;
+    readonly answers: Schema.optional<Schema.$Array<Schema.Union<readonly [Schema.String, Schema.$Array<Schema.String>]>>>;
+}>;
+/** What the person's tool runs on. */
+export interface PersonToolPorts {
+    readonly answer: AnswerPorts;
+    readonly questions: QuestionPorts;
+    /** The permission requests sessions were told about and have not answered. */
+    readonly waiting: Waiting;
+}
+/** Adds `courier_answer`. */
+export declare function addPersonTools(tools: ToolEditor, ports: PersonToolPorts): void;

package/dist/person/tools.js

@@ -0,0 +1,55 @@
+import { Schema } from "effect";
+import { rethrow } from "../kernel/tool.js";
+import { answer, REPLIES } from "./permission.js";
+import { answerQuestion, isQuestion } from "./question/index.js";
+import { answerText } from "./text.js";
+export const AnswerInput = Schema.Struct({
+    sessionID: Schema.String.annotate({ description: "The session you started that is waiting, as its notice names it." }),
+    requestID: Schema.String.annotate({ description: "The request id from the notice." }),
+    reply: Schema.optional(Schema.Literals(REPLIES).annotate({
+        description: "For a permission request: the choice the person made, once, always (only when the notice offers it) or reject.",
+    })),
+    message: Schema.optional(Schema.String.annotate({ description: "For a permission request, with reject: the person's reason, passed on with the refusal." })),
+    answers: Schema.optional(Schema.Array(Schema.Union([Schema.String, Schema.Array(Schema.String)])).annotate({
+        description: "For a question: one entry per question, in order, each the label the person chose or the text they gave, " +
+            "or a list of labels where the question allows several.",
+    })),
+});
+// One tool answers both: a question's id is the plugin's own, a permission request's OpenCode's.
+async function answerRequest(ports, callerID, input) {
+    const { sessionID, requestID } = input;
+    if (isQuestion(requestID)) {
+        if (input.reply !== undefined || input.message !== undefined)
+            throw new Error(`${requestID} is a question: pass the person's answers in answers, not reply or message.`);
+        if (input.answers === undefined)
+            throw new Error(`${requestID} is a question: answers is required, one entry per question.`);
+        return answerQuestion(ports.questions, callerID, { sessionID, requestID, answers: input.answers });
+    }
+    if (input.answers !== undefined)
+        throw new Error(`${requestID} is a permission request: pass the person's choice in reply (once, always or reject), not answers.`);
+    if (input.reply === undefined)
+        throw new Error(`${requestID} is a permission request: reply is required, once, always or reject.`);
+    return answer(ports.answer, ports.waiting, callerID, {
+        sessionID,
+        requestID,
+        reply: input.reply,
+        ...(input.message !== undefined ? { message: input.message } : {}),
+    });
+}
+/** Adds `courier_answer`. */
+export function addPersonTools(tools, ports) {
+    tools.add({
+        name: "courier_answer",
+        options: { codemode: false },
+        description: "Pass on the answer to a permission request or a question that a session you started with courier_spawn (or " +
+            "one started from it) waits on, after a notice from it named the request. The answer is the person's, not yours: " +
+            "first ask the person you are working with, offering the choices the notice lists, then call this with what " +
+            "they chose: reply for a permission request, answers for a question. Never choose for them. The session " +
+            "carries on once it has the answer.",
+        input: AnswerInput,
+        execute: async (input, context) => {
+            const result = await answerRequest(ports, context.sessionID, input).catch(rethrow("courier_answer"));
+            return { content: answerText(result), metadata: result };
+        },
+    });
+}

package/dist/person/tui.d.ts

@@ -0,0 +1,46 @@
+import type { Plugin } from "@opencode/plugin/tui";
+import type { AttentionSoundName } from "@opencode/plugin/tui/context";
+import { type AskedPermission, type AskedQuestion, type Asks, type TreeSession } from "./rpc.js";
+type Context = Plugin.Context;
+type FormInfo = NonNullable<ReturnType<Context["data"]["session"]["form"]["list"]>>[number];
+type FormField = FormInfo["fields"][number];
+type FormAnswer = Parameters<Context["data"]["session"]["form"]["reply"]>[0]["answer"];
+/** Something a session of the tree waits on the person for; `key` is unique across kinds. */
+export type Ask = {
+    readonly key: string;
+    readonly session: TreeSession;
+} & ({
+    readonly kind: "permission";
+    readonly request: AskedPermission;
+} | {
+    readonly kind: "question";
+    readonly question: AskedQuestion;
+} | {
+    readonly kind: "form";
+    readonly form: FormInfo;
+});
+/** The command that opens the inbox, from its key, its slash command, the palette or the footer. */
+export declare const INBOX_COMMAND = "courier.asks";
+/** How long after the first of a burst of asks the inbox reads the tree again, to sound the new ones. */
+export declare const SETTLE_MS = 250;
+/** The asks of a tree in the order the inbox lists them: by the tree's order, each session's permissions, questions, then forms. */
+export declare function asksOf(asks: Asks, forms: ReadonlyMap<string, ReadonlyArray<FormInfo>>): Ask[];
+/** Where an ask comes from: the titles from the top session down to the asking one, as "root › child › grandchild". */
+export declare function pathOf(asks: Asks, sessionID: string, topTitle: string): string;
+/** What an ask is, in one line. */
+export declare function askTitle(ask: Ask): string;
+/** The line under an ask: its depth and group, and that a question's call was cut off. */
+export declare function askFooter(ask: Ask): string;
+/** The sound an ask arriving plays: a permission request's, or a question's for questions and forms. */
+export declare const soundOf: (ask: Ask) => AttentionSoundName;
+/** Whether a form field is shown, given the answers so far: hidden ones never, conditional ones when their conditions hold. */
+export declare function shown(field: FormField, answers: FormAnswer): boolean;
+/**
+ * Adds the asks inbox: what the open session's courier tree waits on the person for, read through the person's RPC and
+ * answered in dialogs, opened by its command; a sound for each new ask. Returns its opener and its cleanup.
+ */
+export declare function addAsksInbox(ctx: Context): {
+    open: (sessionID?: string | undefined) => Promise<void>;
+    cleanup: () => void;
+};
+export {};

package/dist/{bounded.d.ts → platform/bounded.d.ts}

@@ -6,3 +6,7 @@
 export declare function addBounded<T>(set: Set<T>, value: T, max: number): boolean;
 /** Sets an entry of a bounded map, dropping the oldest entry past `max`; an existing key keeps its place. */
 export declare function setBounded<K, V>(map: Map<K, V>, key: K, value: V, max: number): void;
+/** How many handled event ids, and waiting or answered requests and forms, are remembered. */
+export declare const SEEN_MAX = 1000;
+/** Claims a value in one of the shared sets; false when it was claimed already. */
+export declare const claim: (set: Set<string>, value: string) => boolean;

package/dist/{bounded.js → platform/bounded.js}

@@ -17,3 +17,7 @@ export function setBounded(map, key, value, max) {
     if (map.size > max)
         map.delete(map.keys().next().value);
 }
+/** How many handled event ids, and waiting or answered requests and forms, are remembered. */
+export const SEEN_MAX = 1_000;
+/** Claims a value in one of the shared sets; false when it was claimed already. */
+export const claim = (set, value) => addBounded(set, value, SEEN_MAX);

package/dist/platform/events.d.ts

@@ -0,0 +1,34 @@
+import type { Plugin } from "@opencode/plugin";
+import type { Hub } from "./hub.js";
+/** One of OpenCode's events, as a subscription yields it. */
+export interface HostEvent {
+    readonly type: string;
+    readonly data?: unknown;
+}
+/** What following OpenCode's events needs of a member's ports: the stream, and a log. */
+export interface EventPorts {
+    readonly event: Pick<Plugin.Context["event"], "subscribe">;
+    readonly log: (message: string) => void;
+}
+/** What a module does with OpenCode's events, by phase; each phase runs the modules in list order. */
+export interface EventModule<P extends EventPorts> {
+    /** For each event; the first to throw ends the phase. */
+    readonly handle?: (ports: P, event: HostEvent) => Promise<unknown> | undefined;
+    /** For each event, once the `handle` phase has ended, however it did; the first to throw ends this one too. */
+    readonly after?: (ports: P, event: HostEvent) => Promise<void> | undefined;
+    /** As a subscription starts; returns what to run at its first event, if anything. */
+    readonly followed?: () => (() => void) | undefined;
+    /** Alongside each (re)subscription; the watcher's end waits for it. */
+    readonly subscribed?: (ports: P) => Promise<void>;
+    /** Once a subscription has ended or broken. */
+    readonly left?: () => void;
+}
+/** How long to wait before subscribing again after the event stream ended or broke. */
+export declare const RESUBSCRIBE_MS = 5000;
+/** Follows OpenCode's events through `ports`, subscribing again after `retryMs` when a subscription ends, until `signal` aborts. */
+export declare function follow<P extends EventPorts>(ports: P, modules: readonly EventModule<P>[], signal: AbortSignal, retryMs?: number): Promise<void>;
+/**
+ * Makes the hub start its subscriptions to OpenCode's events with this copy's modules, the copy loaded
+ * last; `join` starts them. The second is a standby, connected before the first's member leaves.
+ */
+export declare function watchFromHub<P extends EventPorts>(hub: Pick<Hub, "subscribe">, modules: readonly EventModule<P>[], retryMs?: number): void;

package/dist/platform/events.js

@@ -0,0 +1,121 @@
+/** How long to wait before subscribing again after the event stream ended or broke. */
+export const RESUBSCRIBE_MS = 5_000;
+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);
+});
+const ENDED = { done: true, value: undefined };
+/**
+ * `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]: () => ({
+        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);
+            });
+        }),
+    }),
+});
+/** One event through the `handle` phase, then, however that ended, the `after` phase. */
+async function handle(ports, modules, event) {
+    try {
+        for (const module of modules) {
+            const handling = module.handle?.(ports, event);
+            if (handling)
+                await handling;
+        }
+    }
+    finally {
+        for (const module of modules) {
+            const after = module.after?.(ports, event);
+            if (after)
+                await after;
+        }
+    }
+}
+/** Handles one event, logging a failure rather than ending the watch. */
+function handleLogged(ports, modules, event) {
+    return handle(ports, modules, 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)}`);
+    });
+}
+/** Runs each module's `subscribed` alongside the new subscription, kept in `alongside` until done. */
+function subscribed(ports, modules, alongside) {
+    for (const module of modules) {
+        if (!module.subscribed)
+            continue;
+        const running = module
+            .subscribed(ports)
+            .catch((error) => ports.log(`courier watch: ${String(error)}`))
+            .finally(() => alongside.delete(running));
+        alongside.add(running);
+    }
+}
+/** One subscription, its events through `modules`' phases, until its stream ends or breaks or `signal` aborts. */
+async function subscription(ports, modules, signal, alongside) {
+    let following = false;
+    let events;
+    try {
+        events = ports.event.subscribe({ signal })[Symbol.asyncIterator]();
+        let first = modules.flatMap((module) => module.followed?.() ?? []);
+        following = true;
+        subscribed(ports, modules, alongside);
+        for await (const event of until(events, signal)) {
+            for (const run of first)
+                run();
+            first = [];
+            await handleLogged(ports, modules, event);
+        }
+    }
+    catch (error) {
+        if (!signal.aborted)
+            ports.log(`courier watch: event stream broke: ${String(error)}`);
+    }
+    finally {
+        if (following)
+            for (const module of modules)
+                module.left?.();
+        // 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(() => { });
+    }
+}
+/** Follows OpenCode's events through `ports`, subscribing again after `retryMs` when a subscription ends, until `signal` aborts. */
+export async function follow(ports, modules, signal, retryMs = RESUBSCRIBE_MS) {
+    const alongside = new Set();
+    while (!signal.aborted) {
+        await subscription(ports, modules, signal, alongside);
+        if (!signal.aborted)
+            await pause(retryMs, signal);
+    }
+    await Promise.allSettled(alongside);
+}
+/**
+ * Makes the hub start its subscriptions to OpenCode's events with this copy's modules, the copy loaded
+ * last; `join` starts them. The second is a standby, connected before the first's member leaves.
+ */
+export function watchFromHub(hub, modules, retryMs = RESUBSCRIBE_MS) {
+    hub.subscribe = (member) => {
+        const stop = new AbortController();
+        // A member of any copy runs them: every hub-v2 member's `watch` ports are the same shape.
+        return { member, stop, done: follow(member.watch, modules, stop.signal, retryMs) };
+    };
+}