opencode-courier 0.3.0 → 0.4.0

package/dist/{question → person/question}/answer.d.ts

@@ -1,16 +1,36 @@
 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 { Answers, Asked, Outcome, Prompt, QuestionPorts, Withdrawal } from "./types.js";
+import { type CutOff } from "../text.js";
+import { type RosterStorage } from "../../tree/index.js";
 import { type QuestionAnswerInput } from "./pure.js";
+/** What answering a question did; `answered` is false when it no longer waited. */
+export type QuestionAnswered = {
+    readonly sessionID: string;
+    readonly requestID: string;
+    readonly answered: false;
+} | {
+    readonly sessionID: string;
+    readonly requestID: string;
+    readonly answered: true;
+    readonly by: "result" | "message";
+    readonly answers: Answers;
+};
 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>;
+/**
+ * What a linked call of the top session is withdrawn with once an answer is passed on, `withdrawal`, and
+ * whether one was: `linked`, set once it is withdrawn.
+ */
+export interface Linked {
+    readonly withdrawal: Withdrawal;
+    linked: boolean;
+}
 /**
  * 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>;
+export declare const deliver: (ports: QuestionPorts, asked: Asked, outcome: Outcome, given?: Linked) => 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.
@@ -21,6 +41,15 @@ export declare function forget(ports: QuestionPorts, asked: Asked): Promise<void
  * 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>;
+/**
+ * Answers a question for the person, from the TUI's inbox, as courier_answer does; the top session hears it once, as
+ * answered by the person: its linked call is withdrawn, or else, if it was told of it, it is told settled.
+ */
+export declare function answerForPerson(ports: QuestionPorts, input: QuestionAnswerInput): Promise<QuestionAnswered>;
+/** Whether a session waits on a question of its own, open or cut off and not yet answered. */
+export declare function asksQuestion(ports: {
+    readonly storage: RosterStorage;
+}, sessionID: string): Promise<boolean>;
 /** 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";

package/dist/{question → person/question}/answer.js

@@ -1,7 +1,8 @@
 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 { envelope } from "../../kernel/protocol.js";
+import { cutOffAnswer, questionNotice, questionSettledNotice } from "../text.js";
+import { allEntries, answeringTop, lineageIn, RETENTION_MS } from "../../tree/index.js";
+import { scanAll } from "../../platform/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";
@@ -54,7 +55,8 @@ const holding = (id, ms, effect) => Effect.acquireUseRelease(Effect.sync(() => {
  * 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(() => {
+export const deliver = (ports, asked, outcome, given) => Effect.suspend(() => {
+    const linked = given ?? { withdrawal: { by: "top", outcome }, linked: false };
     const id = asked.requestID;
     const wait = ports.timing.passingWaitMs;
     // One answer at a time, and once, per question in this process, since storage cannot be claimed
@@ -70,7 +72,7 @@ export const deliver = (ports, asked, outcome) => Effect.suspend(() => {
         }
         if (shared.answered.has(id))
             return undefined;
-        const passing = passOn(ports, asked, outcome);
+        const passing = passOn(ports, asked, outcome, linked);
         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, and the child may then be told twice.
@@ -82,7 +84,14 @@ export const deliver = (ports, asked, outcome) => Effect.suspend(() => {
     }));
     return Effect.flatMap(turn, (passing) => passing ? Effect.tryPromise({ try: () => passing, catch: (error) => error }) : Effect.succeed(undefined));
 });
-async function passOn(ports, asked, outcome) {
+/** Withdraws the top session's call linked to a question, if any, now that it is settled. */
+function withdraw(known, linked) {
+    if (!known.link)
+        return;
+    linked.linked = true;
+    known.link(linked.withdrawal);
+}
+async function passOn(ports, asked, outcome, linked) {
     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
@@ -91,7 +100,7 @@ async function passOn(ports, asked, 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 });
+        withdraw(known, linked);
         return "result";
     }
     // Its call just ended: whether it was cut off and stays or was settled and is dropped is known once
@@ -114,7 +123,7 @@ async function passOn(ports, asked, outcome) {
     // 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 });
+    withdraw(known, linked);
     await forget(ports, asked);
     return "message";
 }
@@ -155,6 +164,32 @@ export async function answerQuestion(ports, callerID, input) {
     const by = await run(deliver(ports, asked, { answers }));
     return by ? { sessionID, requestID, answered: true, by, answers } : { sessionID, requestID, answered: false };
 }
+/**
+ * Answers a question for the person, from the TUI's inbox, as courier_answer does; the top session hears it once, as
+ * answered by the person: its linked call is withdrawn, or else, if it was told of it, it is told settled.
+ */
+export async function answerForPerson(ports, input) {
+    const { sessionID, requestID } = input;
+    const known = shared.questions.get(requestID);
+    const asked = known ?? (await ports.storage.get(keyOf(requestID)));
+    if (asked?.sessionID !== sessionID || asked.answered)
+        return { sessionID, requestID, answered: false };
+    const answers = normalize(asked, input.answers);
+    const settled = { by: "child", answers, via: "inbox" };
+    const linked = { withdrawal: settled, linked: false };
+    const by = await run(deliver(ports, asked, { answers }, linked));
+    if (!by)
+        return { sessionID, requestID, answered: false };
+    // A question whose notice did not go out is not settled with one either; a stored one was told when cut off.
+    const told = !known?.relaying || (await run(within(known.relaying, ports.timing.relayWaitMs))) === true;
+    if (!linked.linked && told)
+        await tell(ports, asked, questionSettledNotice(asked, settled), { answered: "elsewhere", request: requestID }).catch((error) => ports.log(`courier question: could not tell ${asked.top} that ${requestID} is settled: ${String(error)}`));
+    return { sessionID, requestID, answered: true, by, answers };
+}
+/** Whether a session waits on a question of its own, open or cut off and not yet answered. */
+export async function asksQuestion(ports, sessionID) {
+    return (await pendingQuestions(ports.storage, sessionID)).length > 0;
+}
 /** 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();

package/dist/person/question/index.d.ts

@@ -0,0 +1,7 @@
+export { answerForPerson, answerQuestion, asksQuestion, 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, portsAt, QUESTION_TOOL } from "./shared.js";
+export type { Answers, Asked, Elsewhere, Outcome, Prompt, QuestionPorts, QuestionTiming, Withdrawal } from "./types.js";
+export type { QuestionAnswered } from "./answer.js";

package/dist/{question → person/question}/index.js

@@ -1,7 +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";
+// (`../../platform/hub.ts`), under a process-wide key of its own; `types.ts` types it.
+export { answerForPerson, answerQuestion, asksQuestion, 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";
+export { isQuestion, MAX_STORED, portsAt, QUESTION_TOOL } from "./shared.js";

package/dist/{question → person/question}/lifecycle.d.ts

@@ -1,5 +1,5 @@
 import { Effect } from "effect";
-import type { QuestionPorts } from "../hub.js";
+import type { QuestionPorts } from "./types.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.

package/dist/{question → person/question}/pure.d.ts

@@ -1,7 +1,6 @@
 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";
+import type { Answers, Asked, Elsewhere, Prompt, Question, Withdrawal } from "./types.js";
 type ToolEditor = Parameters<Parameters<EffectPlugin.Context["tool"]["transform"]>[0]>[0];
 type HostTool = Parameters<Parameters<ToolEditor["update"]>[1]>[0];
 export type Execute = HostTool["execute"];

package/dist/{question → person/question}/pure.js

@@ -1,5 +1,5 @@
 import { Cause, Exit, Result } from "effect";
-import { withdrawnText } from "../notices.js";
+import { withdrawnText } from "../text.js";
 /** The questions of a call, without anything the tool does not define. */
 export function promptsOf(input) {
     const questions = input?.questions ?? [];

package/dist/{question → person/question}/relay.d.ts

@@ -1,5 +1,5 @@
 import type { Plugin as EffectPlugin } from "@opencode/plugin/effect";
 import { Effect } from "effect";
-import type { QuestionPorts } from "../hub.js";
+import type { QuestionPorts } from "./types.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>;

package/dist/{question → person/question}/relay.js

@@ -1,6 +1,6 @@
 import { Deferred, Effect, Exit, Fiber } from "effect";
-import { answeredText, DISMISSED, passedNote, questionNotice, questionSettledNotice, unlinkedNote, } from "../notices.js";
-import { lineage } from "../roster.js";
+import { answeredText, DISMISSED, nativeQuestionNotice, passedNote, questionNotice, questionSettledNotice, unlinkedNote, } from "../text.js";
+import { lineage, nativeRootOf } from "../../tree/index.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";
@@ -24,7 +24,10 @@ 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 });
+        if (question.native)
+            await tell(ports, question, nativeQuestionNotice(question), { asks: "question", request: question.requestID, shown: "native" });
+        else
+            await tell(ports, question, questionNotice(question), { asks: "question", request: question.requestID });
         return true;
     }
     catch (error) {
@@ -110,14 +113,17 @@ function asking(ports, directory, original) {
         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 top = chain.at(-1).parentID;
         const question = {
             requestID: current.newID(),
             sessionID: context.sessionID,
-            top: chain.at(-1).parentID,
+            top,
             title: chain[0].title,
             ...(chain.length > 1 ? { startedBy: chain[0].parentID } : {}),
             questions: promptsOf(input),
             askedAt: current.now(),
+            // OpenCode shows a native child's form in its native root's view: when that is the top's, the person answers there.
+            ...(nativeRootOf(chain) === top ? { native: true } : {}),
             directory,
             call: (outcome) => {
                 if (handed)
@@ -169,6 +175,8 @@ function asking(ports, directory, original) {
         };
     });
 }
+/** Whether the top session's question call may be linked to a question: not a native child's while its own form is shown. */
+const linkable = (question, sessionID) => question.top === sessionID && !question.link && !isPassing(question.requestID) && !(question.native && question.call);
 /**
  * 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.
@@ -176,9 +184,7 @@ function asking(ports, directory, original) {
 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) &&
+        .filter((question) => linkable(question, sessionID) &&
         choices(question.questions) === asked.choices &&
         wording(question.questions) === asked.wording)
         .sort((a, b) => a.askedAt - b.askedAt)[0];
@@ -191,7 +197,7 @@ 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);
+    const similar = [...shared.questions.values()].filter((question) => linkable(question, sessionID) && choices(question.questions) === asked);
     if (!similar.length)
         return result;
     return { ...result, content: `${result.content}\n${unlinkedNote(similar)}` };

package/dist/{question → person/question}/shared.d.ts

@@ -1,5 +1,5 @@
-import { type Question, type QuestionPorts } from "../hub.js";
-import type { Asked } from "../notices.js";
+import type { Registry } from "../../platform/storage.js";
+import type { Asked, Question, QuestionPorts, QuestionState } from "./types.js";
 /** OpenCode's own question tool, which the relay wraps. */
 export declare const QUESTION_TOOL = "question";
 export declare const PREFIX = "question/";
@@ -11,12 +11,22 @@ export type Stored = Asked & {
 };
 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 relay's state in `registry`, the hub's `questions`, with the fields it lacks made: field by
+ * field, since a copy before the hub may have made it without the fields added later.
+ */
+export declare function questionState(registry?: Registry): QuestionState;
+export declare const shared: 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;
+/**
+ * The question ports of the member that just joined at `location`, while it is loaded: resolved once,
+ * so a later instance at the same location does not take its place while this one is still loaded.
+ */
+export declare function portsAt(location: object): () => 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;

package/dist/person/question/shared.js

@@ -0,0 +1,52 @@
+import { addBounded } from "../../platform/bounded.js";
+import { hub, memberAt, sharedState } from "../../platform/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);
+/**
+ * The relay's state in `registry`, the hub's `questions`, with the fields it lacks made: field by
+ * field, since a copy before the hub may have made it without the fields added later.
+ */
+export function questionState(registry) {
+    const state = sharedState("questions", () => ({}), registry);
+    state.questions ??= new Map();
+    state.noticed ??= new Set();
+    state.shown ??= new Map();
+    state.passing ??= new Map();
+    state.answered ??= new Set();
+    state.loaded ??= new Set();
+    state.following ??= 0;
+    state.followed ??= false;
+    state.shutdowns ??= new Map();
+    state.closingWaiters ??= new Set();
+    return state;
+}
+// Shared by every plugin instance in the process, since a child and the session it asks can be in
+// different locations.
+export const shared = questionState();
+/** A member's question ports: every hub-v2 member's `questions` are its instance's, whichever copy joined it. */
+const portsOf = (member) => member?.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 = () => portsOf(hub.members.values().next().value) ?? shared.loaded.values().next().value;
+/**
+ * The question ports of the member that just joined at `location`, while it is loaded: resolved once,
+ * so a later instance at the same location does not take its place while this one is still loaded.
+ */
+export function portsAt(location) {
+    const own = memberAt(location);
+    return () => (own && hub.members.has(own) ? portsOf(own) : undefined);
+}
+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/person/question/types.d.ts

@@ -0,0 +1,121 @@
+import type { Plugin } from "@opencode/plugin";
+import type { Storage } from "../../platform/storage.js";
+type Context = Plugin.Context;
+/** One question of OpenCode's question tool, as the asking model wrote it. */
+export interface Prompt {
+    readonly question: string;
+    readonly header: string;
+    readonly options: ReadonlyArray<{
+        readonly label: string;
+        readonly description: string;
+    }>;
+    readonly multiple?: boolean;
+}
+/** The answers to a question call, as the question tool returns them: one list per question. */
+export type Answers = string[][];
+/** A question a spawned session asked with its question tool, stored until it is answered. */
+export interface Asked {
+    readonly requestID: string;
+    readonly sessionID: string;
+    /** The session told, at the top of the sessions started with courier_spawn; it alone answers. */
+    readonly top: string;
+    readonly title: string;
+    /** The session that started the asking one, when that is not the top session itself. */
+    readonly startedBy?: string;
+    readonly questions: ReadonlyArray<Prompt>;
+    readonly askedAt: number;
+    /** A native child's, whose form OpenCode shows the person in the top session's own view; not linked while shown. */
+    readonly native?: true;
+}
+/**
+ * How a question was settled without the top session: in the asking session (or, `via` "inbox", by the
+ * person in the TUI's asks inbox), or not at all.
+ */
+export type Elsewhere = {
+    readonly by: "child";
+    readonly answers: Answers;
+    readonly via?: "inbox";
+} | {
+    readonly by: "dismissed";
+} | {
+    readonly by: "failed";
+    readonly error: string;
+};
+/** What the top session's answer does to a call that waits: answers it, or dismisses it. */
+export type Outcome = {
+    readonly answers: Answers;
+} | {
+    readonly dismissed: true;
+};
+/**
+ * Why a linked call is withdrawn: its question was settled elsewhere, or the top session's outcome
+ * reached it another way (courier_answer, or a dismissal through an earlier call linked to it).
+ */
+export type Withdrawal = Elsewhere | {
+    readonly by: "top";
+    readonly outcome: Outcome;
+};
+/**
+ * A question this process knows: its call waits (`call`), or was cut off and is answered by message.
+ * `link` withdraws the top session's call passing the answer on, once settled without that call.
+ */
+export interface Question extends Asked {
+    /** The directory of the location the call runs in, whose shutdown withdraws its form. */
+    directory?: string;
+    /** Hands the waiting call the top session's outcome; true once the call has ended with it. */
+    call?: (outcome: Outcome) => Promise<boolean>;
+    link?: (how: Withdrawal) => void;
+    /** Storing the question and telling the top session, while that is under way. */
+    relaying?: Promise<boolean>;
+    /** Working out what became of it once its call ended without the top session's answer. */
+    settling?: Promise<void>;
+}
+/**
+ * The relay's timings, carried by its ports: the closing grace before a cut-off question is told, the
+ * wait for an answer still being passed on, the wait for a notice to go out, and the dismissal hold.
+ */
+export interface QuestionTiming {
+    readonly closingGraceMs: number;
+    readonly passingWaitMs: number;
+    readonly relayWaitMs: number;
+    readonly dismissalGraceMs: number;
+}
+export interface QuestionPorts {
+    readonly storage: Storage;
+    readonly session: Pick<Context["session"], "synthetic">;
+    /** The directory of the instance's location. */
+    readonly directory: string;
+    /** The clock, in epoch milliseconds, as OpenCode's location shutdowns are recorded. */
+    readonly now: () => number;
+    readonly timing: QuestionTiming;
+    readonly newID: () => string;
+    readonly log: (message: string) => void;
+}
+/**
+ * The question relay's state, shared by every instance, as a child and the session it asks can be in
+ * different locations: open questions, cut-off ones already told, and calls waiting for their form.
+ */
+export interface QuestionState {
+    readonly questions: Map<string, Question>;
+    readonly noticed: Set<string>;
+    readonly shown: Map<string, () => void>;
+    /** The questions whose answer is being passed on, each until that is done, and those whose answer went out. */
+    readonly passing: Map<string, Promise<unknown>>;
+    readonly answered: Set<string>;
+    /**
+     * The ports of every loaded instance of every copy. A release before the hub picks one here to tell
+     * a cut-off question through, so every copy fills it; this copy reads it only for another copy.
+     */
+    readonly loaded: Set<QuestionPorts>;
+    /** How many instances follow OpenCode's events now, and whether any has since the process started. */
+    following: number;
+    followed: boolean;
+    /**
+     * When OpenCode last reported each location shutting down (`location.shutdown`), by directory
+     * in epoch milliseconds by the clock of the watcher that saw it; under `""` when the event named no location.
+     */
+    readonly shutdowns: Map<string, number>;
+    /** Woken when a location shuts down or an instance unloads: dismissals held to see whether one follows. */
+    readonly closingWaiters: Set<() => void>;
+}
+export {};

package/dist/person/question/types.js

@@ -0,0 +1 @@
+export {};

package/dist/person/rpc-handlers.d.ts

@@ -0,0 +1,160 @@
+import type { Plugin } from "@opencode/plugin";
+import { type Permissions } from "./permission.js";
+import { type QuestionPorts } from "./question/index.js";
+import { type Answered, type Asks } from "./rpc.js";
+/** What the person's RPC reads and answers through: the relay's ports, which carry the storage, and every location's permissions. */
+export interface PersonRpcPorts {
+    readonly questions: QuestionPorts;
+    readonly permissions: () => Iterable<Permissions>;
+    /** At most this many sessions of a tree are read, as courier_tree reads them. */
+    readonly maxTotal: number;
+}
+/**
+ * The permission requests and questions waiting in the courier tree a session is in, from the roster: read from the
+ * top of its lineage down, so each session of the tree sees the same inbox.
+ */
+export declare function asks(ports: PersonRpcPorts, sessionID: string): Promise<Asks>;
+/** Passes the person's answers to a question on, as courier_answer does; a refusal, such as answers that do not fit, comes back as `problem`. */
+export declare function answer(ports: PersonRpcPorts, input: {
+    sessionID: string;
+    requestID: string;
+    answers: ReadonlyArray<ReadonlyArray<string>>;
+}): Promise<Answered>;
+/** Serves the person's RPC at the plugin's location; disposed with the plugin. */
+export declare function registerPersonRpc(rpc: Pick<Plugin.Context["rpc"], "register">, ports: PersonRpcPorts): Promise<import("@opencode/plugin/promise/rpc").RpcRegistration<{
+    readonly id: "courier-person";
+    readonly methods: {
+        readonly asks: {
+            readonly input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly sessionID: string;
+            }, {
+                readonly sessionID: string;
+            }> & import("effect/Schema").Struct<{
+                readonly sessionID: import("effect/Schema").String;
+            }>;
+            readonly output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly questions: readonly {
+                    readonly questions: readonly {
+                        readonly options: readonly {
+                            readonly label: string;
+                            readonly description: string;
+                        }[];
+                        readonly question: string;
+                        readonly header: string;
+                        readonly multiple?: boolean | undefined;
+                    }[];
+                    readonly sessionID: string;
+                    readonly requestID: string;
+                    readonly stopped?: boolean | undefined;
+                }[];
+                readonly permissions: readonly {
+                    readonly sessionID: string;
+                    readonly resources: readonly string[];
+                    readonly action: string;
+                    readonly requestID: string;
+                    readonly save?: readonly string[] | undefined;
+                }[];
+                readonly top: string;
+                readonly sessions: readonly {
+                    readonly sessionID: string;
+                    readonly title: string;
+                    readonly parentID: string;
+                    readonly depth: number;
+                    readonly group?: string | undefined;
+                }[];
+                readonly truncated?: number | undefined;
+            }, {
+                readonly questions: readonly {
+                    readonly questions: readonly {
+                        readonly options: readonly {
+                            readonly label: string;
+                            readonly description: string;
+                        }[];
+                        readonly question: string;
+                        readonly header: string;
+                        readonly multiple?: boolean | undefined;
+                    }[];
+                    readonly sessionID: string;
+                    readonly requestID: string;
+                    readonly stopped?: boolean | undefined;
+                }[];
+                readonly permissions: readonly {
+                    readonly sessionID: string;
+                    readonly resources: readonly string[];
+                    readonly action: string;
+                    readonly requestID: string;
+                    readonly save?: readonly string[] | undefined;
+                }[];
+                readonly top: string;
+                readonly sessions: readonly {
+                    readonly sessionID: string;
+                    readonly title: string;
+                    readonly parentID: string;
+                    readonly depth: number;
+                    readonly group?: string | undefined;
+                }[];
+                readonly truncated?: number | undefined;
+            }> & import("effect/Schema").Struct<{
+                readonly top: import("effect/Schema").String;
+                readonly sessions: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+                    readonly sessionID: import("effect/Schema").String;
+                    readonly title: import("effect/Schema").String;
+                    readonly parentID: import("effect/Schema").String;
+                    readonly depth: import("effect/Schema").Int;
+                    readonly group: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                }>>;
+                readonly permissions: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+                    readonly sessionID: import("effect/Schema").String;
+                    readonly requestID: import("effect/Schema").String;
+                    readonly action: import("effect/Schema").String;
+                    readonly resources: import("effect/Schema").$Array<import("effect/Schema").String>;
+                    readonly save: import("effect/Schema").optionalKey<import("effect/Schema").$Array<import("effect/Schema").String>>;
+                }>>;
+                readonly questions: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+                    readonly sessionID: import("effect/Schema").String;
+                    readonly requestID: import("effect/Schema").String;
+                    readonly questions: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+                        readonly question: import("effect/Schema").String;
+                        readonly header: import("effect/Schema").String;
+                        readonly options: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+                            readonly label: import("effect/Schema").String;
+                            readonly description: import("effect/Schema").String;
+                        }>>;
+                        readonly multiple: import("effect/Schema").optionalKey<import("effect/Schema").Boolean>;
+                    }>>;
+                    readonly stopped: import("effect/Schema").optionalKey<import("effect/Schema").Boolean>;
+                }>>;
+                readonly truncated: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
+            }>;
+        };
+        readonly answer: {
+            readonly input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly sessionID: string;
+                readonly requestID: string;
+                readonly answers: readonly (readonly string[])[];
+            }, {
+                readonly sessionID: string;
+                readonly requestID: string;
+                readonly answers: readonly (readonly string[])[];
+            }> & import("effect/Schema").Struct<{
+                readonly sessionID: import("effect/Schema").String;
+                readonly requestID: import("effect/Schema").String;
+                readonly answers: import("effect/Schema").$Array<import("effect/Schema").$Array<import("effect/Schema").String>>;
+            }>;
+            readonly output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly answered: boolean;
+                readonly by?: "message" | "result" | undefined;
+                readonly problem?: string | undefined;
+            }, {
+                readonly answered: boolean;
+                readonly by?: "message" | "result" | undefined;
+                readonly problem?: string | undefined;
+            }> & import("effect/Schema").Struct<{
+                readonly answered: import("effect/Schema").Boolean;
+                readonly by: import("effect/Schema").optionalKey<import("effect/Schema").Literals<readonly ["result", "message"]>>;
+                readonly problem: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+            }>;
+        };
+    };
+    readonly events: {};
+}>>;