opencode-courier 0.13.8 → 0.14.0

package/dist/person/rpc.js

@@ -1,55 +1,39 @@
-/**
- * The person's RPC, the contract its TUI part, the asks inbox, and its server half share. Standard Schema values,
- * as the tree's; imports only `@opencode/plugin/rpc` and `effect`.
- */
 import { Rpc } from "@opencode/plugin/rpc";
 import { Schema } from "effect";
 const Count = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
-/** A session of the tree, as the inbox names where an ask comes from. */
 const Session = Schema.Struct({
     sessionID: Schema.String,
     title: Schema.String,
     parentID: Schema.String,
-    /** A child of the tree's top session is at depth 1. */
     depth: Count,
     group: Schema.optionalKey(Schema.String),
 });
-/** A permission request a session of the tree, the top among them, waits on. */
 const Permission = Schema.Struct({
     sessionID: Schema.String,
     requestID: Schema.String,
     action: Schema.String,
     resources: Schema.Array(Schema.String),
-    /** What "always" would allow from now on; absent when it is not offered. */
     save: Schema.optionalKey(Schema.Array(Schema.String)),
-    /** The request below that allowing this one passes on: the top's courier_answer prompt. */
     passesOn: Schema.optionalKey(Schema.Struct({ sessionID: Schema.String, requestID: Schema.String })),
 });
-/** One question of OpenCode's question tool. */
 const Prompt = Schema.Struct({
     question: Schema.String,
     header: Schema.String,
     options: Schema.Array(Schema.Struct({ label: Schema.String, description: Schema.String })),
     multiple: Schema.optionalKey(Schema.Boolean),
 });
-/** A question a session of the tree waits on; `stopped` when its call was cut off and the answer goes as a message. */
 const Question = Schema.Struct({
     sessionID: Schema.String,
     requestID: Schema.String,
     questions: Schema.Array(Prompt),
     stopped: Schema.optionalKey(Schema.Boolean),
 });
-/** What the sessions of a courier tree wait on the person for, but forms, which the TUI lists itself. */
 const Asks = Schema.Struct({
-    /** The session at the top of the tree, which the sessions below were started from. */
     top: Schema.String,
-    /** The sessions below the top, in the order a tree is drawn. */
     sessions: Schema.Array(Session),
-    /** The top session's own requests first, then those of the sessions below. */
     permissions: Schema.Array(Permission),
     questions: Schema.Array(Question),
 });
-/** What answering a question did; `problem` says why nothing was passed on, when it was refused. */
 const Answered = Schema.Struct({
     answered: Schema.Boolean,
     by: Schema.optionalKey(Schema.Literals(["result", "message"])),

package/dist/person/text.d.ts

@@ -1,73 +1,28 @@
 import type { Asked, Elsewhere, Form, Outcome, PermissionAnswered, PermissionRequest, Prompt, QuestionAnswered, Reply, Withdrawal } from "./ports.js";
-/**
- * What courier_answer did: a permission request's result carries the reply, a question's whether its
- * answers went out as the result of its call or, since that call had been cut off, as a message.
- */
 export type AnswerResult = PermissionAnswered | QuestionAnswered;
 export declare function answerText(result: AnswerResult): string;
-/**
- * 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 failure of a courier_answer whose proposed once OpenCode refused in the caller's session: a rule
- * denies the action there, or the person rejected the prompt with a reason, which the child was given.
- */
 export declare function refusedText(sessionID: string, requestID: string, reason: string): 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: PermissionRequest, startedBy?: string, native?: boolean): string;
-/** What the session told about a permission request is told once it is answered without courier_answer. */
 export declare function permissionSettledNotice(title: string, requestID: string, reply: Reply): string;
-/** The `metadata.kind` of the forms OpenCode's web search asks its provider with. */
 export declare const WEBSEARCH_FORM = "websearch.provider";
-/** A form's `metadata.kind`, when it has one that can go in a notice's envelope. */
 export declare const kindOf: (form: Form) => string | undefined;
-/**
- * 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 declare function formNotice(title: string, form: Form, startedBy?: string, shownIn?: string, top?: string): string;
-/** What the session told about a form is told once it is answered or withdrawn. */
 export declare function formSettledNotice(title: string, formID: string, settled: "answered" | "cancelled"): string;
-/** What OpenCode's question tool tells the asking model once it has the answers. */
 export declare function answeredText(questions: ReadonlyArray<Prompt>, answers: ReadonlyArray<ReadonlyArray<string>>): string;
 declare const CUT_OFF: {
     stopped: string;
     restarted: string;
 };
-/** Why a question's call was cut off: its turn was stopped, or OpenCode restarted or closed its location. */
 export type CutOff = keyof typeof CUT_OFF;
-/** What the top session is told about a question, when it is asked or after its call was cut off. */
 export declare function questionNotice(asked: Asked, cutOff?: CutOff): string;
-/**
- * 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 declare function nativeQuestionNotice(asked: Asked): string;
-/** What the top session is told about a question settled without it. */
 export declare function questionSettledNotice(asked: Asked, how: Elsewhere): string;
-/** The result of a spawned session's question call that the person dismissed through the top session. */
 export declare 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 declare function cutOffAnswer(asked: Asked, outcome: Outcome): string;
-/**
- * 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 declare function unlinkedNote(waiting: ReadonlyArray<Pick<Asked, "sessionID" | "requestID">>): string;
-/** The result of a linked call withdrawn because its question was settled without it. */
 export declare function withdrawnText(linked: Asked, how: Withdrawal): string;
-/**
- * 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 declare function passedNote(linked: Asked, passed: string | undefined): string;
 export {};

package/dist/person/text.js

@@ -1,8 +1,6 @@
-/** 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.
+    // a permission request is pending only in the server running the turn
     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 " +
@@ -19,30 +17,16 @@ export function answerText(result) {
     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.
- */
+// a bare rejection ends the child's turn (api-notes)
 export const REJECTED = "Refused by the session that started you. Do without it, or report back why you cannot.";
-/**
- * The failure of a courier_answer whose proposed once OpenCode refused in the caller's session: a rule
- * denies the action there, or the person rejected the prompt with a reason, which the child was given.
- */
 export function refusedText(sessionID, requestID, reason) {
     return `not allowed in your session (${reason}). The refusal was passed on with that reason to request ${requestID} of ${sessionID}, so its call fails and it carries on; it reports back with courier_send. Tell the person, and do not propose it again unless they ask.`;
 }
 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);
-/** 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)
@@ -63,13 +47,11 @@ const permissionAsk = (request) => [
     `Call courier_answer with sessionID "${request.sessionID}", requestID "${request.id}", reply set to the choice and, with reject, message set to the reason.`,
     "Propose once unless the person has told you to refuse it, or the request plainly goes against what they asked of you; with once, the call returns when they have answered the prompt (or your rules allow the action without one). A refusal there with a reason fails the call with it, which the session is given; one without a reason ends your turn, and the session waits on.",
 ];
-/** For a native child's request, which OpenCode shows the person itself, in the top session's view: nothing to call. */
 const nativePermission = (request) => [
     "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 call courier_answer for it, which would only ask them a second time: at most tell them in one line that this session waits on their permission, then end your turn.",
     `Only if they tell you to answer it for them, call courier_answer with sessionID "${request.sessionID}", requestID "${request.id}" and reply set to once or reject (with reject, message set to the reason); with once, OpenCode asks them again in your session before it is passed on.`,
 ];
-/** 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.`,
@@ -79,10 +61,7 @@ export function permissionSettledNotice(title, requestID, reply) {
             : []),
     ].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;
@@ -100,7 +79,6 @@ function fieldLines(field) {
     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);
@@ -114,10 +92,6 @@ const WEBSEARCH_NOTE = [
     "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" };
@@ -126,10 +100,6 @@ function formPlace(sessionID, 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 [
@@ -141,7 +111,6 @@ export function formNotice(title, form, startedBy, shownIn = form.sessionID, top
         `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"
@@ -150,8 +119,6 @@ export function formSettledNotice(title, formID, settled) {
         "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"}"`)
@@ -167,7 +134,6 @@ 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
@@ -180,10 +146,6 @@ export function questionNotice(asked, cutOff) {
         `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.`,
@@ -194,7 +156,6 @@ export function nativeQuestionNotice(asked) {
         `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")
@@ -203,7 +164,6 @@ function settledHow(asked, how) {
         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 [
@@ -214,23 +174,16 @@ export function questionSettledNotice(asked, how) {
             : [`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":
@@ -245,14 +198,9 @@ function withdrawnHow(linked, how) {
             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}`;

package/dist/person/tools.d.ts

@@ -9,12 +9,9 @@ export declare const AnswerInput: Schema.Struct<{
     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

@@ -16,7 +16,6 @@ export const AnswerInput = Schema.Struct({
             "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, call) {
     const { sessionID, requestID } = input;
     if (isQuestion(requestID)) {
@@ -38,7 +37,6 @@ async function answerRequest(ports, callerID, input, call) {
         ...(call ? { call } : {}),
     });
 }
-/** Adds `courier_answer`. */
 export function addPersonTools(tools, ports) {
     tools.add({
         name: "courier_answer",
@@ -55,7 +53,7 @@ export function addPersonTools(tools, ports) {
         execute: async (input, context) => {
             const call = { messageID: context.messageID, callID: context.id };
             const result = await answerRequest(ports, context.sessionID, input, call).catch((error) => {
-                // A plain rejection of the caller's prompt ends its step, as OpenCode's own tools do: it goes back as it is.
+                // rethrown untouched, a plain decline ends the step (api-notes)
                 if (isDeclined(error))
                     throw error;
                 return rethrow("courier_answer")(error);

package/dist/person/tui.d.ts

@@ -5,10 +5,6 @@ type FormInfo = NonNullable<ReturnType<Context["data"]["session"]["form"]["list"
 type FormField = FormInfo["fields"][number];
 type FormAnswer = Parameters<Context["data"]["session"]["form"]["reply"]>[0]["answer"];
 type FormValue = FormAnswer[string];
-/**
- * Something a session of the tree waits on the person for; `key` is unique across kinds. `prompted` marks a permission
- * request the top session's courier_answer prompt asks about.
- */
 export type Ask = {
     readonly key: string;
     readonly session: TreeSession;
@@ -23,33 +19,16 @@ export type Ask = {
     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 top session, at depth 0, as its own permission requests name it. */
 export declare const topSession: (asks: Asks) => TreeSession;
-/**
- * The asks of a tree in the order the inbox lists them: the top session's own permission requests, then 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", each as the TUI knows it now, else as spawned. */
 export declare function pathOf(asks: Asks, sessionID: string, topTitle: string, currentTitle?: (sessionID: string) => string | undefined): string;
-/** What an ask is, in one line. */
 export declare function askTitle(ask: Ask): string;
-/** The line under an ask: its depth (the top's own say so) and group, that a question's call was cut off, or that the top's courier_answer prompt asks for it. */
 export declare function askFooter(ask: Ask): string;
-/** Whether a form field applies, given the answers so far (a hidden field's default among them): its `when` conditions hold, as OpenCode reads them (a condition on an unanswered field is false; on a multiselect, `eq` means includes). */
 export declare function active(field: FormField, answers: FormAnswer): boolean;
-/** What is wrong with a field's answer by the limits OpenCode's form service checks on reply, worded as its form view does; undefined when it fits. */
 export declare function misfit(field: FormField, value: FormValue): string | undefined;
-/** The limits of a typed field as a prompt's placeholder: "1-5", "at least 3 characters", "email"; undefined without any. */
 export declare function limitsOf(field: FormField): string | undefined;
-/**
- * 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, its open list read again on `follows`; a sound for each new ask.
- */
 export declare function addAsksInbox(ctx: Context, follows: ReadonlySet<string>): {
     open: (sessionID?: string | undefined) => Promise<void>;
     cleanup: () => void;

package/dist/platform/bounded.d.ts

@@ -1,12 +1,4 @@
-/**
- * Bounded `Set`s and `Map`s of remembered ids that drop their oldest entry past a bound. Functions
- * on the built-ins, not a class, as older plugin copies call `.has` and `.add` on the shared ones.
- */
-/** Adds to a bounded set, dropping the oldest entry past `max`; false when the value was there already. */
 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/platform/bounded.js

@@ -1,8 +1,3 @@
-/**
- * Bounded `Set`s and `Map`s of remembered ids that drop their oldest entry past a bound. Functions
- * on the built-ins, not a class, as older plugin copies call `.has` and `.add` on the shared ones.
- */
-/** Adds to a bounded set, dropping the oldest entry past `max`; false when the value was there already. */
 export function addBounded(set, value, max) {
     if (set.has(value))
         return false;
@@ -11,13 +6,10 @@ export function addBounded(set, value, max) {
         set.delete(set.values().next().value);
     return true;
 }
-/** Sets an entry of a bounded map, dropping the oldest entry past `max`; an existing key keeps its place. */
 export function setBounded(map, key, value, max) {
     map.set(key, value);
     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

@@ -1,42 +1,24 @@
 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;
 }
-/** An event type `event.subscribe` can filter on: any of OpenCode's but `server.connected`, which a plugin never receives. */
 export type EventType = NonNullable<NonNullable<Parameters<EventPorts["event"]["subscribe"]>[0]>["types"]>[number];
-/** What a module does with OpenCode's events, by phase; each phase runs the modules in list order. */
 export interface EventModule<P extends EventPorts> {
-    /** The event types it handles; without them, every event, so the subscription is not filtered. */
     readonly types?: readonly EventType[];
-    /** 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 once the stream is surely connected, 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;
-/** How long after subscribing the stream is taken as connected, should no event come first: a plugin's reports no connection. */
 export declare const CONNECTED_MS = 1000;
-/** The types `modules` declare, sorted; undefined, every type, once one of them declares none. */
 export declare function typesOf(modules: readonly EventModule<never>[]): EventType[] | undefined;
-/** 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, connectedMs?: 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

@@ -1,6 +1,5 @@
-/** How long to wait before subscribing again after the event stream ended or broke. */
 export const RESUBSCRIBE_MS = 5_000;
-/** How long after subscribing the stream is taken as connected, should no event come first: a plugin's reports no connection. */
+// a plugin's event stream never says it connected (api-notes)
 export const CONNECTED_MS = 1_000;
 const pause = (ms, signal) => new Promise((resolve) => {
     const timer = setTimeout(done, ms);
@@ -12,10 +11,6 @@ const pause = (ms, signal) => new Promise((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) => {
@@ -23,7 +18,6 @@ const until = (events, signal) => ({
                 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);
@@ -34,7 +28,6 @@ const until = (events, signal) => ({
         }),
     }),
 });
-/** The types `modules` declare, sorted; undefined, every type, once one of them declares none. */
 export function typesOf(modules) {
     const types = new Set();
     for (const module of modules) {
@@ -45,7 +38,6 @@ export function typesOf(modules) {
     }
     return [...types].sort((a, b) => Number(a > b) - Number(a < b));
 }
-/** 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) {
@@ -62,7 +54,6 @@ async function handle(ports, modules, event) {
         }
     }
 }
-/** 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;
@@ -70,7 +61,6 @@ function handleLogged(ports, modules, event) {
         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)
@@ -82,13 +72,11 @@ function subscribed(ports, modules, alongside) {
         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, connectedMs) {
     let following = false;
     let events;
     let first = [];
     let timer;
-    // The stream is surely connected at its first event, filtered or not, or `connectedMs` after subscribing.
     const connected = () => {
         clearTimeout(timer);
         for (const run of first.splice(0))
@@ -105,7 +93,7 @@ async function subscription(ports, modules, signal, alongside, connectedMs) {
         subscribed(ports, modules, alongside);
         for await (const event of until(events, signal)) {
             connected();
-            // A host that ignores `types` sends every event; none outside them reaches a module.
+            // a host may ignore the types filter (api-notes)
             if (wanted && !wanted.has(event.type))
                 continue;
             await handleLogged(ports, modules, event);
@@ -121,12 +109,10 @@ async function subscription(ports, modules, signal, alongside, connectedMs) {
         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.
+        // not awaited: closing waits on OpenCode, stuck while a location closes
         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, connectedMs = CONNECTED_MS) {
     const alongside = new Set();
     while (!signal.aborted) {
@@ -136,16 +122,11 @@ export async function follow(ports, modules, signal, retryMs = RESUBSCRIBE_MS, c
     }
     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) {
     const types = typesOf(modules);
     hub.subscribe = (member) => {
         const stop = new AbortController();
         member.log(`courier watch: following ${types ? types.join(", ") : "every event"} through ${member.directory}`);
-        // 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) };
     };
 }