opencode-courier 0.2.2 → 0.3.0

package/dist/question/relay.js

@@ -0,0 +1,269 @@
+import { Deferred, Effect, Exit, Fiber } from "effect";
+import { answeredText, DISMISSED, passedNote, questionNotice, questionSettledNotice, unlinkedNote, } from "../notices.js";
+import { lineage } from "../roster.js";
+import { deliver, forget, tell, tellCutOff } from "./answer.js";
+import { closingSoon } from "./lifecycle.js";
+import { choices, isDismissal, normalize, promptsOf, settledIn, withdrawnResult, wording, } from "./pure.js";
+import { background, run, within } from "./runtime.js";
+import { anyLoaded, isPassing, keyOf, QUESTION_TOOL, shared, storedOf } from "./shared.js";
+/**
+ * Tells the top session about a question its closing location cut off, after the closing grace of
+ * `ports`, through any instance still loaded then; without one, the next load tells it.
+ */
+function tellLater(ports, question) {
+    const tellNow = Effect.suspend(() => {
+        const later = anyLoaded();
+        if (!later || question.call || question.link || shared.questions.get(question.requestID) !== question)
+            return Effect.void;
+        return Effect.promise(() => tellCutOff(later, question, "restarted").catch((error) => later.log(`courier question: could not tell ${question.top} about ${question.requestID}: ${String(error)}`)));
+    });
+    void background(Effect.andThen(Effect.sleep(ports.timing.closingGraceMs), tellNow), (error) => ports.log(`courier question: could not tell ${question.top} about ${question.requestID}: ${String(error)}`));
+}
+/** Registers a question, stores it and tells the top session; false when storing or telling failed. */
+async function relay(ports, question) {
+    shared.questions.set(question.requestID, question);
+    try {
+        await ports.storage.set(keyOf(question.requestID), storedOf(question));
+        await tell(ports, question, questionNotice(question), { asks: "question", request: question.requestID });
+        return true;
+    }
+    catch (error) {
+        // The question stays registered and the call waits on: courier_status lists it, and an answer
+        // that comes anyway, through a link or courier_answer, still reaches the call.
+        ports.log(`courier question: could not tell ${question.top} about ${question.requestID}: ${String(error)}`);
+        return false;
+    }
+}
+/**
+ * After a relayed call ended: tidies up, and tells the top session if it was settled without it.
+ * `loaded` says whether the plugin instance that ran the call is still loaded.
+ */
+const settle = (ports, question, exit, loaded) => Effect.gen(function* () {
+    const unloaded = !loaded();
+    // A dismissal is held from now, alongside the wait below, so the grace is not spent waiting.
+    const dismissed = Exit.isFailure(exit) && isDismissal(exit.cause);
+    const held = dismissed && !unloaded ? yield* Effect.forkChild(closingSoon(ports, loaded, question.directory), { startImmediately: true }) : undefined;
+    // The top session is told first, for a while only, so what follows neither overtakes the notice
+    // nor waits forever on one that never returns; `told` is false when it was not told, or not yet.
+    const told = (yield* within(question.relaying, ports.timing.relayWaitMs)) === true;
+    // Answered by the top session.
+    if (Exit.isSuccess(exit) && exit.value.by === "top") {
+        if (shared.questions.get(question.requestID) === question)
+            shared.questions.delete(question.requestID);
+        return yield* Effect.promise(() => forget(ports, question));
+    }
+    // Never relayed, or dropped meanwhile.
+    if (shared.questions.get(question.requestID) !== question) {
+        return yield* Effect.promise(() => forget(ports, question));
+    }
+    // Cut off: the turn was stopped, or the closing location withdrew its forms as if dismissed, so a
+    // dismissal is held for a following shutdown or unload; the question stays, answered by message.
+    const closing = unloaded || !loaded() || (held !== undefined && (yield* Fiber.join(held)));
+    if (Exit.isFailure(exit) && (closing || (!dismissed && Exit.hasInterrupts(exit))))
+        return closing ? tellLater(ports, question) : yield* Effect.promise(() => stopped(ports, question));
+    yield* Effect.promise(() => settledElsewhere(ports, question, settledIn(exit), told));
+});
+/** A relayed call cut off by its stopped turn: the top session is told now, unless it asks the person. */
+async function stopped(ports, question) {
+    if (!question.link)
+        await tellCutOff(ports, question, "stopped");
+}
+/** A relayed call settled in the asking session: `told` says whether the top session was told about it. */
+async function settledElsewhere(ports, question, how, told) {
+    // Its record goes before its registration, so an answer that finds the question gone does not
+    // find the record still there and send it on.
+    await forget(ports, question);
+    shared.questions.delete(question.requestID);
+    if (question.link)
+        return question.link(how);
+    // A top session never told about the question is not told that it is settled either.
+    if (!told)
+        return;
+    await tell(ports, question, questionSettledNotice(question, how), {
+        answered: how.by === "child" ? "elsewhere" : how.by,
+        request: question.requestID,
+    });
+}
+/**
+ * Starts settling a relayed call that ended, kept on the question until it is through: an answer
+ * the call did not take waits for it.
+ */
+function startSettling(ports, question, exit, loaded) {
+    question.settling = background(settle(ports, question, exit, loaded), (error) => ports.log(`courier question: could not settle ${question.requestID}: ${String(error)}`)).finally(() => {
+        question.settling = undefined;
+    });
+}
+/**
+ * A spawned session's question call: once its form is shown the top session is told, and whichever
+ * answer comes first ends the call, the other side's question withdrawn. Other calls run unchanged.
+ */
+function asking(ports, directory, original) {
+    return (input, context) => Effect.gen(function* () {
+        const current = ports();
+        const chain = current ? yield* Effect.promise(() => lineage(current.storage, context.sessionID).catch(() => [])) : [];
+        if (!current || !chain.length)
+            return yield* original(input, context);
+        const byTop = Deferred.makeUnsafe();
+        const accepted = Deferred.makeUnsafe();
+        // For a copy of the plugin that answers through `call`, which takes promises.
+        let acceptancePromise;
+        const acceptance = () => (acceptancePromise ??= Effect.runPromise(Deferred.await(accepted)));
+        // Handed one outcome only: a second, while the first still ends the call, is not taken.
+        let handed = false;
+        const question = {
+            requestID: current.newID(),
+            sessionID: context.sessionID,
+            top: chain.at(-1).parentID,
+            title: chain[0].title,
+            ...(chain.length > 1 ? { startedBy: chain[0].parentID } : {}),
+            questions: promptsOf(input),
+            askedAt: current.now(),
+            directory,
+            call: (outcome) => {
+                if (handed)
+                    return acceptance().then(() => false);
+                handed = true;
+                Deferred.doneUnsafe(byTop, Exit.succeed(outcome));
+                return acceptance();
+            },
+        };
+        // The form is shown only once OpenCode's permission check for the call has passed; a call
+        // refused there never reaches the top session.
+        const key = `${context.sessionID} ${context.id}`;
+        const loaded = () => ports() === current;
+        const shown = Deferred.makeUnsafe();
+        // Called as a plain function, by this copy's watcher or another copy's.
+        shared.shown.set(key, () => Deferred.doneUnsafe(shown, Exit.void));
+        const fromTop = Effect.gen(function* () {
+            yield* Deferred.await(shown);
+            // Started, not waited for: a store or a notice that hangs must not keep the top session's
+            // answer from the call. Kept on the question, so settle can wait for it.
+            question.relaying = relay(current, question);
+            return { by: "top", outcome: yield* Deferred.await(byTop) };
+        });
+        const ended = yield* Effect.raceFirst(original(input, context).pipe(Effect.map((result) => ({ by: "child", result }))), fromTop).pipe(
+        // Not waited for, so storing or a notice that hangs cannot hold the call up.
+        Effect.onExit((exit) => Effect.sync(() => {
+            shared.shown.delete(key);
+            // The call no longer waits, whatever settle makes of it: an answer from now on waits for settle.
+            const byTopSession = Exit.isSuccess(exit) && exit.value.by === "top";
+            if (!byTopSession)
+                question.call = undefined;
+            startSettling(current, question, exit, loaded);
+            // After settling is set, which an answer the call did not take then waits for.
+            Deferred.doneUnsafe(accepted, Exit.succeed(byTopSession));
+        })));
+        if (ended.by === "child")
+            return ended.result;
+        const outcome = ended.outcome;
+        if ("dismissed" in outcome)
+            return {
+                output: { answers: question.questions.map(() => []) },
+                content: DISMISSED,
+                metadata: { answers: question.questions.map(() => []), relayed: question.requestID, dismissed: true },
+            };
+        return {
+            output: { answers: outcome.answers },
+            content: answeredText(question.questions, outcome.answers),
+            metadata: { answers: outcome.answers, relayed: question.requestID, answeredIn: question.top },
+        };
+    });
+}
+/**
+ * The waiting question a top session's call asks again, the oldest if several: the same question with
+ * the same choices, in any order. Choices alone would let an unrelated yes-or-no answer a child's.
+ */
+function linkFor(sessionID, questions) {
+    const asked = { choices: choices(questions), wording: wording(questions) };
+    return [...shared.questions.values()]
+        .filter((question) => question.top === sessionID &&
+        !question.link &&
+        !isPassing(question.requestID) &&
+        choices(question.questions) === asked.choices &&
+        wording(question.questions) === asked.wording)
+        .sort((a, b) => a.askedAt - b.askedAt)[0];
+}
+/**
+ * The result of a top session's question call that no waiting question was linked to: when one waits
+ * with the same choices, reworded or asked earlier, it says how to pass the answers on.
+ */
+function unlinkedResult(result, sessionID, questions) {
+    if (typeof result.content !== "string")
+        return result;
+    const asked = choices(questions);
+    const similar = [...shared.questions.values()].filter((question) => question.top === sessionID && !question.link && !isPassing(question.requestID) && choices(question.questions) === asked);
+    if (!similar.length)
+        return result;
+    return { ...result, content: `${result.content}\n${unlinkedNote(similar)}` };
+}
+/**
+ * After a linked call failed with its location still loaded: a dismissal by the person dismisses the
+ * child's question too, or is logged if answered meanwhile; a stop while cut off tells the top.
+ */
+const linkedCallFailed = (ports, linked, cause, loaded, directory) => Effect.gen(function* () {
+    if (isDismissal(cause)) {
+        if (yield* closingSoon(ports, loaded, directory))
+            return;
+        if ((yield* deliver(ports, linked, { dismissed: true })) === undefined)
+            ports.log(`courier question: the dismissal of ${linked.requestID} was not passed on: it had already been answered or settled`);
+    }
+    else if (!linked.call && shared.questions.get(linked.requestID) === linked)
+        yield* Effect.promise(() => tellCutOff(ports, linked, "stopped"));
+});
+/** Logs that what happened to a linked call could not be passed on. */
+const notPassedOn = (ports, linked) => (error) => ports.log(`courier question: could not pass on what happened to ${linked.requestID}: ${String(error)}`);
+/**
+ * The question call of a session that a waiting question was relayed to, asking the person the
+ * same: what they choose is passed on, and the call is withdrawn if the question is settled first.
+ */
+function linking(ports, directory, ask) {
+    return (input, context) => Effect.gen(function* () {
+        const current = ports();
+        const questions = promptsOf(input);
+        const linked = current ? linkFor(context.sessionID, questions) : undefined;
+        if (!current || !linked) {
+            const result = yield* ask(input, context);
+            return current ? unlinkedResult(result, context.sessionID, questions) : result;
+        }
+        const loaded = () => ports() === current;
+        const elsewhere = Deferred.makeUnsafe();
+        // Called as a plain function, by this copy or another one.
+        const settled = (how) => void Deferred.doneUnsafe(elsewhere, Exit.succeed(how));
+        linked.link = settled;
+        const ended = yield* Effect.raceFirst(ask(input, context).pipe(Effect.map((result) => ({ by: "person", result }))), Deferred.await(elsewhere).pipe(Effect.map((how) => ({ by: "elsewhere", how })))).pipe(Effect.onExit((exit) => Effect.sync(() => {
+            if (linked.link === settled)
+                linked.link = undefined;
+            // Unloaded: OpenCode is closing the location, which withdraws the form; nobody dismissed it.
+            if (Exit.isSuccess(exit) || !loaded())
+                return;
+            // Not waited for, as in asking.
+            void background(linkedCallFailed(current, linked, exit.cause, loaded, directory), notPassedOn(current, linked));
+        })));
+        if (ended.by === "elsewhere")
+            return withdrawnResult(linked, ended.how);
+        const result = ended.result;
+        const answers = result.output?.answers ?? [];
+        const passed = yield* Effect.promise(() => Promise.resolve()
+            .then(() => run(deliver(current, linked, { answers: normalize(linked, answers) })))
+            .catch((error) => {
+            current.log(`courier question: could not pass on the answer to ${linked.requestID}: ${String(error)}`);
+            return `error: ${error instanceof Error ? error.message : String(error)}`;
+        }));
+        const note = passedNote(linked, passed);
+        return {
+            ...result,
+            content: typeof result.content === "string" ? `${result.content}\n${note}` : note,
+            metadata: { ...result.metadata, relayed: linked.requestID, passed: passed === "result" || passed === "message" },
+        };
+    });
+}
+/** Wraps OpenCode's question tool for the relay. A tool by that id that is missing is left alone. */
+export function relayQuestions(host, ports) {
+    // The wrapped tool runs the calls of the host's location: its shutdown is what withdraws their forms.
+    const { directory } = host.location;
+    return host.tool.transform((editor) => {
+        editor.update(QUESTION_TOOL, (tool) => {
+            tool.execute = linking(ports, directory, asking(ports, directory, tool.execute));
+        });
+    });
+}

package/dist/question/runtime.d.ts

@@ -0,0 +1,20 @@
+import { Clock, Effect } from "effect";
+/**
+ * Runs a relay effect in its own fiber by the relay's clock (`ports.now`): the promise settles as the
+ * effect ends, rejecting on failure or interruption; interrupting the waiter does not stop the fiber.
+ */
+export declare function run<A, E>(effect: Effect.Effect<A, E>): Promise<A>;
+/**
+ * Runs an effect of the relay in the background, as `run` does; the promise resolves once it ended,
+ * however it ended. A failure is logged with `failed`; an interruption, by a test ending, is not.
+ */
+export declare function background(effect: Effect.Effect<unknown, unknown>, failed: (error: unknown) => void): Promise<void>;
+/** The promise's value, or undefined once `ms` have passed or it failed. */
+export declare const within: <T>(promise: Promise<T> | undefined, ms: number) => Effect.Effect<T | undefined>;
+/**
+ * For tests: the clock the relay runs by from now on, a `TestClock` whose time `ports.now` reads,
+ * or the system clock again with none.
+ */
+export declare function useClock(next?: Clock.Clock): void;
+/** For tests: interrupts every fiber the relay started, and goes back to the system clock. */
+export declare function stopRelay(): Promise<void>;

package/dist/question/runtime.js

@@ -0,0 +1,74 @@
+import { Cause, Clock, Duration, Effect, Exit, Fiber, Option, Scope } from "effect";
+// What the relay's own fibers run with: this copy's state, not the hub's. A copy of the plugin
+// loaded next to this one has its own, and they meet only in the shared fields of the hub.
+const system = Effect.runSync(Clock.clockWith(Effect.succeed));
+/** Largest delay a timer takes; a longer one would fire at once, so it is slept in parts. */
+const MAX_TIMER_MS = 2_147_483_647;
+/**
+ * The system clock, whose sleeps do not keep the process running: OpenCode exits without waiting
+ * for a dismissal held, a notice told later or an answer waiting its turn.
+ */
+const live = {
+    currentTimeMillisUnsafe: () => system.currentTimeMillisUnsafe(),
+    currentTimeMillis: system.currentTimeMillis,
+    currentTimeNanosUnsafe: () => system.currentTimeNanosUnsafe(),
+    currentTimeNanos: system.currentTimeNanos,
+    monotonicTimeNanosUnsafe: () => system.monotonicTimeNanosUnsafe(),
+    monotonicTimeNanos: system.monotonicTimeNanos,
+    sleep: (duration) => sleep(Duration.toMillis(duration)),
+};
+function sleep(ms) {
+    if (ms <= 0)
+        return Effect.yieldNow;
+    if (!Number.isFinite(ms))
+        return Effect.never;
+    const rest = ms > MAX_TIMER_MS ? Effect.suspend(() => sleep(ms - MAX_TIMER_MS)) : Effect.void;
+    return Effect.callback((resume) => {
+        const timer = setTimeout(() => resume(rest), Math.min(ms, MAX_TIMER_MS));
+        timer.unref?.();
+        return Effect.sync(() => clearTimeout(timer));
+    });
+}
+let clock = live;
+/** The fibers the relay starts, which run as long as the process unless a test ends them. */
+let scope = Scope.makeUnsafe();
+/**
+ * Starts an effect of the relay in a fiber of its own, by the relay's clock, in the relay's scope:
+ * at once, up to its first wait, as an async function would.
+ */
+const start = (effect) => Effect.runFork(Effect.provideService(effect, Clock.Clock, clock)).pipe(Fiber.runIn(scope));
+/**
+ * Runs a relay effect in its own fiber by the relay's clock (`ports.now`): the promise settles as the
+ * effect ends, rejecting on failure or interruption; interrupting the waiter does not stop the fiber.
+ */
+export function run(effect) {
+    return Effect.runPromise(Fiber.join(start(effect)));
+}
+/**
+ * Runs an effect of the relay in the background, as `run` does; the promise resolves once it ended,
+ * however it ended. A failure is logged with `failed`; an interruption, by a test ending, is not.
+ */
+export function background(effect, failed) {
+    return Effect.runPromise(Fiber.await(start(effect))).then((exit) => {
+        if (Exit.isFailure(exit) && !Cause.hasInterruptsOnly(exit.cause))
+            failed(Cause.squash(exit.cause));
+    });
+}
+/** The promise's value, or undefined once `ms` have passed or it failed. */
+export const within = (promise, ms) => promise
+    ? Effect.promise(() => promise.then((value) => value, () => undefined)).pipe(Effect.timeoutOption(ms), Effect.map(Option.getOrUndefined))
+    : Effect.succeed(undefined);
+/**
+ * For tests: the clock the relay runs by from now on, a `TestClock` whose time `ports.now` reads,
+ * or the system clock again with none.
+ */
+export function useClock(next) {
+    clock = next ?? live;
+}
+/** For tests: interrupts every fiber the relay started, and goes back to the system clock. */
+export async function stopRelay() {
+    const ended = scope;
+    scope = Scope.makeUnsafe();
+    clock = live;
+    await Effect.runPromise(Scope.close(ended, Exit.void));
+}

package/dist/question/shared.d.ts

@@ -0,0 +1,24 @@
+import { type Question, type QuestionPorts } from "../hub.js";
+import type { Asked } from "../notices.js";
+/** OpenCode's own question tool, which the relay wraps. */
+export declare const QUESTION_TOOL = "question";
+export declare const PREFIX = "question/";
+/** At most this many questions are kept in storage; the oldest go first. */
+export declare const MAX_STORED = 100;
+/** A question as stored; `answered` marks one whose answer went out but that could not be dropped. */
+export type Stored = Asked & {
+    readonly answered?: true;
+};
+export declare const storedOf: ({ directory: _directory, call: _call, link: _link, relaying: _relaying, settling: _settling, ...asked }: Question) => Asked;
+export declare const isPassing: (requestID: string) => boolean;
+export declare const shared: import("../hub.js").QuestionState;
+/**
+ * The ports of an instance still loaded, if any: a member of this copy's hub, or else one that a
+ * copy of another hub version, or a release before the hub, keeps in `loaded`.
+ */
+export declare const anyLoaded: () => QuestionPorts | undefined;
+export declare const keyOf: (requestID: string) => string;
+/** Whether a request id is a question's rather than a permission request's. */
+export declare const isQuestion: (requestID: string) => boolean;
+/** Adds to one of the shared bounded sets. */
+export declare const claim: (set: Set<string>, value: string) => boolean;

package/dist/question/shared.js

@@ -0,0 +1,24 @@
+import { addBounded } from "../bounded.js";
+import { hub } from "../hub.js";
+/** OpenCode's own question tool, which the relay wraps. */
+export const QUESTION_TOOL = "question";
+export const PREFIX = "question/";
+/** At most this many questions are kept in storage; the oldest go first. */
+export const MAX_STORED = 100;
+export const storedOf = ({ directory: _directory, call: _call, link: _link, relaying: _relaying, settling: _settling, ...asked }) => asked;
+export const isPassing = (requestID) => shared.passing.has(requestID) || shared.answered.has(requestID);
+// Shared by every plugin instance in the process, since a child and the session it asks can be in
+// different locations.
+export const shared = hub.questions;
+/**
+ * The ports of an instance still loaded, if any: a member of this copy's hub, or else one that a
+ * copy of another hub version, or a release before the hub, keeps in `loaded`.
+ */
+export const anyLoaded = () => hub.members.values().next().value?.questions ?? shared.loaded.values().next().value;
+export const keyOf = (requestID) => `${PREFIX}${requestID}`;
+/** Whether a request id is a question's rather than a permission request's. */
+export const isQuestion = (requestID) => requestID.startsWith("question_");
+/** How many noticed and answered questions are remembered. */
+const REMEMBERED = 1_000;
+/** Adds to one of the shared bounded sets. */
+export const claim = (set, value) => addBounded(set, value, REMEMBERED);

package/dist/relay.d.ts

@@ -1,28 +1,14 @@
 import type { Plugin } from "@opencode/plugin";
 import { type Pending } from "./courier.js";
+import { type Form, type PermissionAnswered, type PermissionRequest, type Reply } from "./notices.js";
 import { type RosterStorage } from "./roster.js";
 type Context = Plugin.Context;
 /** One location's pending permission requests. OpenCode keeps them per location, so an isolated child's are in its worktree's. */
 export type Permissions = Pick<Context["permission"], "list" | "reply">;
-/** The answers to a permission request, as OpenCode's own prompt offers them. */
-export declare const REPLIES: readonly ["once", "always", "reject"];
-export type Reply = (typeof REPLIES)[number];
-/**
- * Sent with a rejection that has no reason of its own. OpenCode ends the child's turn on a bare
- * rejection, and the child would never report back; with a message, the call fails and it carries on.
- */
-export declare const REJECTED = "Refused by the session that started you. Do without it, or report back why you cannot.";
 /** The part of OpenCode's `permission.asked` event the notice is made from. */
 export interface PermissionAsked {
     readonly id: string;
-    readonly data: {
-        readonly id: string;
-        readonly sessionID: string;
-        readonly action: string;
-        readonly resources: ReadonlyArray<string>;
-        readonly save?: ReadonlyArray<string>;
-        readonly message?: string;
-    };
+    readonly data: PermissionRequest;
 }
 /** The part of OpenCode's `permission.replied` event. */
 export interface PermissionReplied {
@@ -38,16 +24,6 @@ export interface PermissionReplied {
  * notice went to a parent and that courier_answer has not answered yet.
  */
 export type Waiting = Set<string>;
-/** How a notice names where the asking session came from, to the session at the top of its lineage. */
-export declare const origin: (startedBy?: string) => string;
-/** For a notice that a session's turn ended without it finishing. */
-export declare const STAYS_QUIET = "and then it does not report back on its own: if it stays quiet, message it with courier_send to have it carry on.";
-/**
- * What the session at the top is told. `startedBy` names the session that started the asking one
- * when that is not the top session itself, but one started from it.
- */
-export declare function permissionNotice(title: string, request: PermissionAsked["data"], startedBy?: string): string;
-export declare function settledNotice(title: string, requestID: string, reply: Reply): string;
 export interface AnswerPorts {
     readonly storage: RosterStorage;
     /** The permission domains of every loaded location; the request is answered where it is pending. */
@@ -59,18 +35,38 @@ export interface AnswerInput {
     readonly reply: string;
     readonly message?: string;
 }
+/** A session's pending requests in every location, with the domain holding each; a location that cannot be read gives its error. */
+export declare function listEverywhere<D extends Pick<Permissions, "list">>(permissions: Iterable<D>, sessionID: string): Promise<({
+    domain: D;
+    requests: never[];
+    error: unknown;
+} | {
+    domain: D;
+    requests: import("@opencode/client").PermissionRequest[];
+})[]>;
 /**
- * Answers a permission request of a session started, directly or through others, from the
- * caller, which must be the session at the top: requests go there, to the person, so a session
- * started with courier_spawn cannot approve what its own children ask. `answered` is false when
- * nothing was waiting.
+ * Answers a permission request of a session started, directly or through others, from the caller,
+ * which must be the top session; `answered` is false when no location loaded here holds the request.
  */
-export declare function answer(ports: AnswerPorts, waiting: Waiting, callerID: string, input: AnswerInput): Promise<{
-    sessionID: string;
-    requestID: string;
-    reply: "once" | "always" | "reject";
-    answered: boolean;
-}>;
+export declare function answer(ports: AnswerPorts, waiting: Waiting, callerID: string, input: AnswerInput): Promise<PermissionAnswered>;
 /** The requests a session waits on, in whichever location holds them, for courier_status. */
 export declare function pendingOf(permissions: Iterable<Permissions>, sessionID: string): Promise<Pending[]>;
+/** The `metadata.kind` of the forms OpenCode's question tool asks with; the question relay passes those on. */
+export declare const QUESTION_FORM = "question";
+/** The part of OpenCode's `form.created` event the notice is made from. */
+export interface FormCreated {
+    readonly id: string;
+    readonly data: {
+        readonly form: Form;
+    };
+}
+/** OpenCode's `form.replied` or `form.cancelled` event: the form is no longer shown. */
+export interface FormSettled {
+    readonly id: string;
+    readonly type: string;
+    readonly data: {
+        readonly id: string;
+        readonly sessionID: string;
+    };
+}
 export {};

package/dist/relay.js

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

package/dist/report.d.ts

@@ -0,0 +1,48 @@
+import { type Status } from "./notices.js";
+import type { Storage } from "./storage.js";
+export declare const promptKey: (sessionID: string) => string;
+export declare const settledKey: (sessionID: string) => string;
+export declare const progressKey: (sessionID: string) => string;
+export declare const toldKey: (sessionID: string) => string;
+export declare const stoppedKey: (sessionID: string) => string;
+/** How a session's wait for a report ended: it reported to its parent, or its turn failed or was interrupted. */
+export type Settled = "report" | "failed" | "interrupted";
+/**
+ * Notes that a prompt or message reached a spawned session at `at`, in epoch milliseconds, unless a
+ * later one is noted: both of the hub's subscriptions note each event, one of them maybe behind.
+ */
+export declare function prompted(storage: Pick<Storage, "get" | "set">, sessionID: string, at: number): Promise<void>;
+/**
+ * Notes that a spawned session reported to its parent, with `status` when its report carried one, or
+ * its turn failed or was interrupted, at `at`, unless a later end is noted.
+ */
+export declare function settled(storage: Pick<Storage, "get" | "set">, sessionID: string, by: Settled, at: number, status?: Status): Promise<void>;
+/** Notes that a spawned session messaged its parent without a status at `at`, which is progress, not its report. */
+export declare function progressed(storage: Pick<Storage, "get" | "set">, sessionID: string, at: number): Promise<void>;
+/** Notes that a spawned session's parent was told, at `at`, that a turn of it ended without a report, unless a later telling is noted. */
+export declare function told(storage: Pick<Storage, "get" | "set">, sessionID: string, at: number): Promise<void>;
+/** Takes back the note `told` made at `at`, whose notice did not go out; a later one stays, and one that cannot be read goes. */
+export declare function untold(storage: Pick<Storage, "get" | "remove">, sessionID: string, at: number): Promise<void>;
+/** Notes that courier_stop stopped a spawned session at `at`, so the failure and silent-end notices stay quiet for it. */
+export declare function stopped(storage: Pick<Storage, "set">, sessionID: string, at: number): Promise<void>;
+/** Whether courier_stop stopped a session after its last prompt, or with none noted, at all. */
+export declare function stoppedSincePrompt(storage: Pick<Storage, "get">, sessionID: string): Promise<boolean>;
+/** The status of a spawned session's last report to its parent, if it has reported with one. */
+export declare function lastStatus(storage: Pick<Storage, "get">, sessionID: string): Promise<Status | undefined>;
+/**
+ * What is known of a spawned session's report: when a prompt last reached it, and whether since then it owes one, has
+ * messaged its parent without a status, or failed or was interrupted. Undefined for one spawned before this was kept.
+ */
+export declare function reportOf(storage: Pick<Storage, "get">, sessionID: string): Promise<{
+    prompt: number;
+    owes: boolean;
+    progressed: boolean;
+    ended: boolean;
+} | undefined>;
+/**
+ * Whether its parent still waits on a spawned session's report: it owes one, and the parent has not
+ * been told since its last prompt that it ended a turn without one.
+ */
+export declare function awaited(storage: Pick<Storage, "get">, sessionID: string): Promise<boolean>;
+/** Drops what is kept about a session, with its roster entry. */
+export declare function forgetReport(storage: Pick<Storage, "remove">, sessionID: string): Promise<void>;