opencode-courier 0.2.1 → 0.2.3

package/dist/question/answer.d.ts

@@ -0,0 +1,35 @@
+import { Effect } from "effect";
+import type { QuestionPorts } from "../hub.js";
+import { type Asked, type CutOff, type Outcome, type Prompt, type QuestionAnswered } from "../notices.js";
+import { type RosterStorage } from "../roster.js";
+import { type QuestionAnswerInput } from "./pure.js";
+export declare function tell(ports: QuestionPorts, asked: Asked, text: string, attributes: Record<string, string>): Promise<void>;
+/** Tells the top session that a question's call was cut off, once per question and process. */
+export declare function tellCutOff(ports: QuestionPorts, asked: Asked, cutOff: CutOff): Promise<void>;
+/**
+ * Passes the top session's answer, or the person's dismissal, to a question: as the result of the
+ * call that waits on it, or as a message when that call was cut off. Undefined when it was settled.
+ */
+export declare const deliver: (ports: QuestionPorts, asked: Asked, outcome: Outcome) => Effect.Effect<"result" | "message" | undefined, unknown>;
+/**
+ * Drops a stored question whose answer went out. If that fails, it is marked answered instead, so
+ * it is neither listed nor answered again, nor told about after a restart.
+ */
+export declare function forget(ports: QuestionPorts, asked: Asked): Promise<void>;
+/**
+ * Answers a question of a session started, directly or through others, from the caller, which must
+ * be the session at the top, as for permission requests. `answered` is false when it no longer waits.
+ */
+export declare function answerQuestion(ports: QuestionPorts, callerID: string, input: QuestionAnswerInput): Promise<QuestionAnswered>;
+/** The questions a session waits on, for courier_status; `stopped` when its call was cut off. */
+export declare function pendingQuestions(storage: RosterStorage, sessionID: string): Promise<{
+    type: "question";
+    requestID: string;
+    questions: Prompt[];
+    stopped?: true;
+}[]>;
+/**
+ * On loading: drops stored questions that are too old, whose session is no longer on a roster, or
+ * beyond the newest `MAX_STORED`, and tells the top session about the rest, which a restart cut off.
+ */
+export declare function noticeCutOff(ports: QuestionPorts): Promise<void>;

package/dist/question/answer.js

@@ -0,0 +1,217 @@
+import { Deferred, Effect, Semaphore } from "effect";
+import { cutOffAnswer, envelope, questionNotice } from "../notices.js";
+import { allEntries, answeringTop, lineageIn, RETENTION_MS } from "../roster.js";
+import { scanAll } from "../storage.js";
+import { within, run } from "./runtime.js";
+import { normalize } from "./pure.js";
+import { claim, isPassing, keyOf, MAX_STORED, PREFIX, shared, storedOf } from "./shared.js";
+export async function tell(ports, asked, text, attributes) {
+    await ports.session.synthetic({
+        sessionID: asked.top,
+        text: envelope(asked.sessionID, text, attributes),
+        description: `Session ${asked.sessionID} asks a question`,
+        metadata: { source: "courier", from: asked.sessionID, requestID: asked.requestID, ...attributes },
+        delivery: "steer",
+    });
+}
+/** Tells the top session that a question's call was cut off, once per question and process. */
+export async function tellCutOff(ports, asked, cutOff) {
+    // Not while an answer to it is being passed on, which makes the notice moot.
+    if (shared.noticed.has(asked.requestID) || isPassing(asked.requestID))
+        return;
+    // Claimed first, so two tellers at once send one notice; given back if it did not go out.
+    claim(shared.noticed, asked.requestID);
+    try {
+        await tell(ports, asked, questionNotice(asked, cutOff), { asks: "question", request: asked.requestID, [cutOff]: "true" });
+    }
+    catch (error) {
+        shared.noticed.delete(asked.requestID);
+        throw error;
+    }
+}
+const busy = (id) => new Error(`another answer to ${id} is still being passed on; try again in a while.`);
+/** This copy's lock per question, kept while an answer to it is passed on or waits its turn. */
+const locks = new Map();
+/**
+ * Runs `effect` holding the question's lock, once it is taken; fails if that takes more than `ms`.
+ * Only this copy of the plugin takes the lock: another copy's answer shows in `shared.passing`.
+ */
+const holding = (id, ms, effect) => Effect.acquireUseRelease(Effect.sync(() => {
+    const lock = locks.get(id) ?? { semaphore: Semaphore.makeUnsafe(1), users: 0 };
+    lock.users++;
+    locks.set(id, lock);
+    return lock;
+}), (lock) => {
+    const taken = Deferred.makeUnsafe();
+    // Whichever ends first: the effect, or the wait, which fails only if the lock was not taken by then.
+    const late = Effect.andThen(Effect.sleep(ms), Effect.suspend(() => (Deferred.isDoneUnsafe(taken) ? Effect.never : Effect.fail(busy(id)))));
+    return Effect.raceFirst(lock.semaphore.withPermit(Effect.andThen(Deferred.succeed(taken, undefined), effect)), late);
+}, (lock) => Effect.sync(() => {
+    if (--lock.users === 0)
+        locks.delete(id);
+}));
+/**
+ * Passes the top session's answer, or the person's dismissal, to a question: as the result of the
+ * call that waits on it, or as a message when that call was cut off. Undefined when it was settled.
+ */
+export const deliver = (ports, asked, outcome) => Effect.suspend(() => {
+    const id = asked.requestID;
+    const wait = ports.timing.passingWaitMs;
+    // One answer at a time, and once, per question in this process: storage cannot be claimed
+    // atomically. A second answer waits for the first, and is passed on if the first was not.
+    // While one is under way, nobody is told that the question was cut off, nor links to it.
+    const since = ports.now();
+    const left = () => wait - (ports.now() - since);
+    const turn = holding(id, wait, Effect.gen(function* () {
+        // An answer that another copy of the plugin, loaded beside this one, passes on.
+        for (let under = shared.passing.get(id); under; under = shared.passing.get(id)) {
+            if (left() <= 0)
+                return yield* Effect.fail(busy(id));
+            yield* within(under, left());
+        }
+        if (shared.answered.has(id))
+            return undefined;
+        const passing = passOn(ports, asked, outcome);
+        shared.passing.set(id, passing);
+        // Held while it is passed on. One that hangs, on a notice that never returns, gives way
+        // after a while, so the question can be answered again; should it still go through, the
+        // child is told twice.
+        yield* within(passing, wait).pipe(Effect.ensuring(Effect.sync(() => {
+            if (shared.passing.get(id) === passing)
+                shared.passing.delete(id);
+        })));
+        return passing;
+    }));
+    return Effect.flatMap(turn, (passing) => passing ? Effect.tryPromise({ try: () => passing, catch: (error) => error }) : Effect.succeed(undefined));
+});
+async function passOn(ports, asked, outcome) {
+    const id = asked.requestID;
+    let known = shared.questions.get(id);
+    // Taken only if the call ends with it: one already ending some other way, its turn being
+    // stopped or the person answering in its session, does not.
+    if (known?.call && (await known.call(outcome))) {
+        claim(shared.answered, id);
+        shared.questions.delete(id);
+        // A call of the top session linked to it, asking the person, is withdrawn: it is settled.
+        known.link?.({ by: "top", outcome });
+        return "result";
+    }
+    // Its call has just ended: whether it was cut off, and so stays registered, or was settled, and
+    // so is dropped, is known once settle is through. The registry decides, not storage, which a
+    // question whose record could not be written is missing from.
+    if (known) {
+        await known.settling;
+        if (shared.questions.get(id) !== known)
+            return undefined;
+    }
+    else {
+        // Not known to this process: stored by one before it, and not yet loaded here.
+        const stored = (await ports.storage.get(keyOf(id)));
+        if (!stored || stored.answered)
+            return undefined;
+        known = { ...stored };
+        shared.questions.set(id, known);
+    }
+    await sendAnswer(ports, asked, outcome);
+    // Dropped only once the message is out, so a failed send leaves it to be answered again; the
+    // linked call, if any, goes then too, not before the answer is out.
+    claim(shared.answered, id);
+    shared.questions.delete(id);
+    known.link?.({ by: "top", outcome });
+    await forget(ports, asked);
+    return "message";
+}
+/**
+ * Drops a stored question whose answer went out. If that fails, it is marked answered instead, so
+ * it is neither listed nor answered again, nor told about after a restart.
+ */
+export async function forget(ports, asked) {
+    try {
+        await ports.storage.remove(keyOf(asked.requestID));
+    }
+    catch (error) {
+        ports.log(`courier question: could not forget ${asked.requestID}: ${String(error)}`);
+        const marked = { ...storedOf(asked), answered: true };
+        await ports.storage.set(keyOf(asked.requestID), marked).catch(() => undefined);
+    }
+}
+async function sendAnswer(ports, asked, outcome) {
+    await ports.session.synthetic({
+        sessionID: asked.sessionID,
+        text: envelope(asked.top, cutOffAnswer(asked, outcome), { answers: asked.requestID, ...("answers" in outcome ? {} : { dismissed: "true" }) }),
+        description: `Answer from ${asked.top}`,
+        metadata: { source: "courier", from: asked.top, answers: asked.requestID },
+        delivery: "steer",
+    });
+}
+/**
+ * Answers a question of a session started, directly or through others, from the caller, which must
+ * be the session at the top, as for permission requests. `answered` is false when it no longer waits.
+ */
+export async function answerQuestion(ports, callerID, input) {
+    const { sessionID, requestID } = input;
+    await answeringTop(ports.storage, sessionID, callerID, "questions");
+    const asked = shared.questions.get(requestID) ?? (await ports.storage.get(keyOf(requestID)));
+    if (asked?.sessionID !== sessionID || asked.answered)
+        return { sessionID, requestID, answered: false };
+    const answers = normalize(asked, input.answers);
+    const by = await run(deliver(ports, asked, { answers }));
+    return by ? { sessionID, requestID, answered: true, by, answers } : { sessionID, requestID, answered: false };
+}
+/** The questions a session waits on, for courier_status; `stopped` when its call was cut off. */
+export async function pendingQuestions(storage, sessionID) {
+    const found = new Map();
+    const add = (asked, stopped) => found.set(asked.requestID, {
+        type: "question",
+        requestID: asked.requestID,
+        questions: [...asked.questions],
+        ...(stopped ? { stopped: true } : {}),
+    });
+    for (const question of shared.questions.values())
+        if (question.sessionID === sessionID && !isPassing(question.requestID))
+            add(question, !question.call);
+    for (const asked of await scanAll(storage, PREFIX))
+        if (asked.sessionID === sessionID && !asked.answered && !isPassing(asked.requestID) && !found.has(asked.requestID))
+            add(asked, true);
+    return [...found.values()];
+}
+/**
+ * On loading: drops stored questions that are too old, whose session is no longer on a roster, or
+ * beyond the newest `MAX_STORED`, and tells the top session about the rest, which a restart cut off.
+ */
+export async function noticeCutOff(ports) {
+    const stored = (await scanAll(ports.storage, PREFIX)).sort((a, b) => b.askedAt - a.askedAt);
+    if (!stored.length)
+        return;
+    const roster = await allEntries(ports.storage);
+    const now = ports.now();
+    let kept = 0;
+    // Which to keep is decided here, newest first; the drops and the notices, one per question, then
+    // go out together.
+    const work = [];
+    for (const asked of stored) {
+        const known = shared.questions.get(asked.requestID);
+        // Its call waits, or its top session is asking the person: nothing to tell.
+        if (known?.call || known?.link || known?.settling || shared.passing.has(asked.requestID)) {
+            kept++;
+            continue;
+        }
+        const current = !asked.answered &&
+            !shared.answered.has(asked.requestID) &&
+            kept < MAX_STORED &&
+            now - asked.askedAt <= RETENTION_MS &&
+            lineageIn(roster, asked.sessionID).length > 0;
+        if (!current) {
+            shared.questions.delete(asked.requestID);
+            work.push(ports.storage
+                .remove(keyOf(asked.requestID))
+                .catch((error) => ports.log(`courier question: could not drop ${asked.requestID}: ${String(error)}`)));
+            continue;
+        }
+        if (!known)
+            shared.questions.set(asked.requestID, { ...asked });
+        kept++;
+        work.push(tellCutOff(ports, known ?? asked, "restarted").catch((error) => ports.log(`courier question: could not tell ${asked.top} about ${asked.requestID}: ${String(error)}`)));
+    }
+    await Promise.all(work);
+}

package/dist/question/index.d.ts

@@ -0,0 +1,6 @@
+export { answerQuestion, noticeCutOff, pendingQuestions } from "./answer.js";
+export { eventsFollowed, eventsLeft, formShown, formsMayHaveBeenMissed, joinRelay, locationClosing, shutdownReportedAt } from "./lifecycle.js";
+export { byCodeUnit, type QuestionAnswerInput } from "./pure.js";
+export { relayQuestions } from "./relay.js";
+export { isQuestion, MAX_STORED, QUESTION_TOOL } from "./shared.js";
+export type { QuestionPorts, QuestionTiming } from "../hub.js";

package/dist/question/index.js

@@ -0,0 +1,7 @@
+// The question relay: what the rest of the plugin uses of it. The relay's state is kept in the hub
+// (`../hub.ts`), shared by every plugin instance in the process.
+export { answerQuestion, noticeCutOff, pendingQuestions } from "./answer.js";
+export { eventsFollowed, eventsLeft, formShown, formsMayHaveBeenMissed, joinRelay, locationClosing, shutdownReportedAt } from "./lifecycle.js";
+export { byCodeUnit } from "./pure.js";
+export { relayQuestions } from "./relay.js";
+export { isQuestion, MAX_STORED, QUESTION_TOOL } from "./shared.js";

package/dist/question/lifecycle.d.ts

@@ -0,0 +1,52 @@
+import { Effect } from "effect";
+import type { QuestionPorts } from "../hub.js";
+/**
+ * For tests: when the location at `directory` was last reported shutting down, if at all; a shutdown
+ * reported without a location counts for every directory, and with none given, any location's counts.
+ */
+export declare const shutdownReportedAt: (directory?: string) => number | undefined;
+/**
+ * Called for OpenCode's `location.shutdown`: the location at `directory` is closing, which
+ * withdraws its open forms as if the person had dismissed them (before unloading the plugin
+ * there, since OpenCode 2.0.22). The event's location is optional in the schema; without it,
+ * the shutdown counts for every location. `at` is when, by the watcher's clock (epoch milliseconds).
+ */
+export declare function locationClosing(at: number, directory?: string): void;
+/**
+ * Whether a dismissal just seen in the location at `directory` was that location closing rather
+ * than the person: true when it shut down within the dismissal grace before, or does so, or this
+ * instance unloads, within the grace from now, by the clock of `ports`. A shutdown reported without a location counts for every
+ * location, and with the directory unknown, any location's shutdown counts.
+ */
+export declare const closingSoon: (ports: QuestionPorts, loaded: () => boolean, directory: string | undefined) => Effect.Effect<boolean>;
+/**
+ * Adds a plugin instance's ports to `loaded`, which copies of other versions read to tell a cut-off
+ * question through it, until the returned function is called. A location loading again forgets the
+ * shutdown recorded for it, so a dismissal there is not mistaken for that shutdown. One recorded for
+ * every location is left alone, since a dismissal held in another location may still need it; it
+ * ages out with the grace.
+ */
+export declare function joinRelay(ports: QuestionPorts): () => void;
+/** Called for OpenCode's `form.created`: a question call's form is shown, so its question can be relayed. */
+export declare function formShown(event: {
+    readonly data: {
+        readonly form: {
+            readonly sessionID: string;
+            readonly metadata?: unknown;
+        };
+    };
+}): void;
+/**
+ * Called when an event stream may have missed forms being shown: every call still waiting for its
+ * form is taken as shown. One still waiting for its permission check is relayed early, which is the
+ * lesser harm.
+ */
+export declare function formsMayHaveBeenMissed(): void;
+/**
+ * Called when an instance starts following OpenCode's events. Every instance is sent every event,
+ * so a form shown is missed only while none follows them; then the calls waiting are released, and
+ * true is returned, for the caller to release them again on its first event, once it is connected.
+ */
+export declare function eventsFollowed(): boolean;
+/** Called when an instance's event stream ended or broke. */
+export declare function eventsLeft(): void;

package/dist/question/lifecycle.js

@@ -0,0 +1,100 @@
+import { Deferred, Effect, Exit } from "effect";
+import { shared } from "./shared.js";
+/** The key of a shutdown reported without a location: it counts for every location. */
+const ANYWHERE = "";
+/** When the location at `directory` (any location, with none) was last reported shutting down; 0 if never. */
+const shutdownAt = (directory) => directory === undefined
+    ? Math.max(0, ...shared.shutdowns.values())
+    : Math.max(shared.shutdowns.get(directory) ?? 0, shared.shutdowns.get(ANYWHERE) ?? 0);
+/**
+ * For tests: when the location at `directory` was last reported shutting down, if at all; a shutdown
+ * reported without a location counts for every directory, and with none given, any location's counts.
+ */
+export const shutdownReportedAt = (directory) => shutdownAt(directory) || undefined;
+/**
+ * Called for OpenCode's `location.shutdown`: the location at `directory` is closing, which
+ * withdraws its open forms as if the person had dismissed them (before unloading the plugin
+ * there, since OpenCode 2.0.22). The event's location is optional in the schema; without it,
+ * the shutdown counts for every location. `at` is when, by the watcher's clock (epoch milliseconds).
+ */
+export function locationClosing(at, directory) {
+    shared.shutdowns.set(directory ?? ANYWHERE, at);
+    for (const wake of shared.closingWaiters)
+        wake();
+}
+/**
+ * Whether a dismissal just seen in the location at `directory` was that location closing rather
+ * than the person: true when it shut down within the dismissal grace before, or does so, or this
+ * instance unloads, within the grace from now, by the clock of `ports`. A shutdown reported without a location counts for every
+ * location, and with the directory unknown, any location's shutdown counts.
+ */
+export const closingSoon = (ports, loaded, directory) => Effect.suspend(() => {
+    const ms = ports.timing.dismissalGraceMs;
+    const closing = () => !loaded() || ports.now() - shutdownAt(directory) <= ms;
+    if (closing())
+        return Effect.succeed(true);
+    const closed = Deferred.makeUnsafe();
+    // Woken by any shutdown or unload: only one that answers the question ends the wait.
+    const wake = () => {
+        if (closing())
+            Deferred.doneUnsafe(closed, Exit.succeed(true));
+    };
+    return Effect.acquireUseRelease(
+    // Looked at as the waiter is added, so a shutdown cannot come in between unseen.
+    Effect.sync(() => {
+        shared.closingWaiters.add(wake);
+        wake();
+    }), () => (Deferred.isDoneUnsafe(closed) ? Effect.succeed(true) : Effect.raceFirst(Deferred.await(closed), Effect.as(Effect.sleep(ms), false))), () => Effect.sync(() => shared.closingWaiters.delete(wake)));
+});
+/**
+ * Adds a plugin instance's ports to `loaded`, which copies of other versions read to tell a cut-off
+ * question through it, until the returned function is called. A location loading again forgets the
+ * shutdown recorded for it, so a dismissal there is not mistaken for that shutdown. One recorded for
+ * every location is left alone, since a dismissal held in another location may still need it; it
+ * ages out with the grace.
+ */
+export function joinRelay(ports) {
+    shared.loaded.add(ports);
+    shared.shutdowns.delete(ports.directory);
+    return () => {
+        shared.loaded.delete(ports);
+        for (const wake of shared.closingWaiters)
+            wake();
+    };
+}
+/** Called for OpenCode's `form.created`: a question call's form is shown, so its question can be relayed. */
+export function formShown(event) {
+    const call = event.data.form.metadata?.tool?.id;
+    if (typeof call !== "string")
+        return;
+    const key = `${event.data.form.sessionID} ${call}`;
+    shared.shown.get(key)?.();
+    shared.shown.delete(key);
+}
+/**
+ * Called when an event stream may have missed forms being shown: every call still waiting for its
+ * form is taken as shown. One still waiting for its permission check is relayed early, which is the
+ * lesser harm.
+ */
+export function formsMayHaveBeenMissed() {
+    for (const shown of shared.shown.values())
+        shown();
+    shared.shown.clear();
+}
+/**
+ * Called when an instance starts following OpenCode's events. Every instance is sent every event,
+ * so a form shown is missed only while none follows them; then the calls waiting are released, and
+ * true is returned, for the caller to release them again on its first event, once it is connected.
+ */
+export function eventsFollowed() {
+    const missed = shared.following === 0 && shared.followed;
+    shared.following++;
+    shared.followed = true;
+    if (missed)
+        formsMayHaveBeenMissed();
+    return missed;
+}
+/** Called when an instance's event stream ended or broke. */
+export function eventsLeft() {
+    shared.following = Math.max(0, shared.following - 1);
+}

package/dist/question/pure.d.ts

@@ -0,0 +1,49 @@
+import type { Plugin as EffectPlugin } from "@opencode/plugin/effect";
+import { Cause, Exit, type Effect } from "effect";
+import type { Question } from "../hub.js";
+import { type Answers, type Asked, type Elsewhere, type Prompt, type Withdrawal } from "../notices.js";
+type ToolEditor = Parameters<Parameters<EffectPlugin.Context["tool"]["transform"]>[0]>[0];
+type HostTool = Parameters<Parameters<ToolEditor["update"]>[1]>[0];
+export type Execute = HostTool["execute"];
+export type ToolResult = Effect.Success<ReturnType<Execute>>;
+/** The questions of a call, without anything the tool does not define. */
+export declare function promptsOf(input: unknown): Prompt[];
+export interface QuestionAnswerInput {
+    readonly sessionID: string;
+    readonly requestID: string;
+    /** One entry per question: a label or the text the person gave, or a list of them. */
+    readonly answers: ReadonlyArray<string | ReadonlyArray<string>>;
+}
+/** The answers in the question tool's shape, checked against the questions. */
+export declare function normalize(asked: Asked, answers: QuestionAnswerInput["answers"]): Answers;
+/** OpenCode's question tool dies with this when the person dismisses the question. */
+export declare const isDismissal: (cause: Cause.Cause<unknown>) => boolean;
+/** How a relayed call ended. */
+export type CallExit = Exit.Exit<{
+    by: "child";
+    result: ToolResult;
+} | {
+    by: "top";
+}, unknown>;
+/** How a relayed call that the top session did not answer was settled in the asking session. */
+export declare function settledIn(exit: CallExit): Elsewhere;
+/**
+ * Orders strings by their UTF-16 code units, the default sort's order, stated. The order is never
+ * shown; it only has to come out the same on both sides of a comparison, which a locale-aware
+ * compare would not promise: it can rank two different labels as equal and leave them as listed.
+ */
+export declare function byCodeUnit(a: string, b: string): 1 | 0 | -1;
+export declare const choices: (questions: ReadonlyArray<Prompt>) => string;
+export declare const wording: (questions: ReadonlyArray<Prompt>) => string;
+/** The result of a linked call withdrawn because its question was settled without it. */
+export declare function withdrawnResult(linked: Question, how: Withdrawal): {
+    output: {
+        answers: Answers;
+    };
+    content: string;
+    metadata: {
+        relayed: string;
+        withdrawn: boolean;
+    };
+};
+export {};

package/dist/question/pure.js

@@ -0,0 +1,75 @@
+import { Cause, Exit, Result } from "effect";
+import { withdrawnText } from "../notices.js";
+/** The questions of a call, without anything the tool does not define. */
+export function promptsOf(input) {
+    const questions = input?.questions ?? [];
+    return questions.map((prompt) => ({
+        question: prompt.question,
+        header: prompt.header,
+        options: prompt.options.map((option) => ({ label: option.label, description: option.description })),
+        ...(prompt.multiple ? { multiple: true } : {}),
+    }));
+}
+/** The answers in the question tool's shape, checked against the questions. */
+export function normalize(asked, answers) {
+    if (answers.length !== asked.questions.length)
+        throw new Error(`answers needs one entry per question, ${asked.questions.length} in all, not ${answers.length}.`);
+    return answers.map((answer, index) => {
+        const list = typeof answer === "string" ? [answer] : [...answer];
+        const prompt = asked.questions[index];
+        if (!prompt.multiple && list.length > 1)
+            throw new Error(`question ${index + 1} ("${prompt.header}") takes one answer, not ${list.length}.`);
+        return list;
+    });
+}
+const defectTag = (cause) => {
+    const defect = Cause.findDefect(cause);
+    return Result.isSuccess(defect) ? defect.success?._tag : undefined;
+};
+/** OpenCode's question tool dies with this when the person dismisses the question. */
+export const isDismissal = (cause) => defectTag(cause) === "QuestionTool.CancelledError";
+/** How a relayed call that the top session did not answer was settled in the asking session. */
+export function settledIn(exit) {
+    if (Exit.isSuccess(exit))
+        return {
+            by: "child",
+            answers: exit.value.result?.output?.answers ?? [],
+        };
+    if (isDismissal(exit.cause))
+        return { by: "dismissed" };
+    return { by: "failed", error: String(Cause.squash(exit.cause)) };
+}
+/**
+ * Orders strings by their UTF-16 code units, the default sort's order, stated. The order is never
+ * shown; it only has to come out the same on both sides of a comparison, which a locale-aware
+ * compare would not promise: it can rank two different labels as equal and leave them as listed.
+ */
+export function byCodeUnit(a, b) {
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
+}
+// The labels in any order: the answers are labels, so a top session listing them differently still asks the same.
+export const choices = (questions) => JSON.stringify(questions.map((prompt) => [!!prompt.multiple, prompt.options.map((option) => option.label).sort(byCodeUnit)]));
+export const wording = (questions) => JSON.stringify(questions.map((prompt) => prompt.question.trim().replace(/\s+/g, " ").toLowerCase()));
+/** The answers that count once a linked call's question was settled without it: none unless it was answered. */
+function withdrawnAnswers(linked, how) {
+    const none = () => linked.questions.map(() => []);
+    switch (how.by) {
+        case "top":
+            return "answers" in how.outcome ? how.outcome.answers : none();
+        case "child":
+            return how.answers;
+        case "dismissed":
+        case "failed":
+            return none();
+    }
+}
+/** The result of a linked call withdrawn because its question was settled without it. */
+export function withdrawnResult(linked, how) {
+    return {
+        output: { answers: withdrawnAnswers(linked, how) },
+        content: withdrawnText(linked, how),
+        metadata: { relayed: linked.requestID, withdrawn: true },
+    };
+}

package/dist/question/relay.d.ts

@@ -0,0 +1,5 @@
+import type { Plugin as EffectPlugin } from "@opencode/plugin/effect";
+import { Effect } from "effect";
+import type { QuestionPorts } from "../hub.js";
+/** Wraps OpenCode's question tool for the relay. A tool by that id that is missing is left alone. */
+export declare function relayQuestions(host: Pick<EffectPlugin.Context, "tool" | "location">, ports: () => QuestionPorts | undefined): Effect.Effect<import("@opencode/plugin/effect/registration").Registration, never, import("effect/Scope").Scope>;