opencode-courier 0.2.3 → 0.4.0

package/dist/person/ports.d.ts

@@ -0,0 +1,58 @@
+import type { Plugin } from "@opencode/plugin";
+import type { FormsTold } from "../platform/hub.js";
+import type { RosterEntry, RosterStorage } from "../tree/index.js";
+import type { Waiting } from "./permission.js";
+export type { PermissionAnswered, PermissionRequest, Reply } from "./permission.js";
+export type { Asked, Elsewhere, Outcome, Prompt, QuestionAnswered, Withdrawal } from "./question/index.js";
+type Context = Plugin.Context;
+/** What the person events need of a member's `watch` ports, which are a `WatchPorts` at runtime. */
+export interface PersonPorts {
+    readonly storage: RosterStorage;
+    readonly session: Pick<Context["session"], "synthetic">;
+    readonly event: Pick<Context["event"], "subscribe">;
+    /**
+     * The permission domains of every loaded location, whose pending requests are relayed when the
+     * watcher (re)subscribes: one watcher serves them all, and an isolated child's are in its worktree's.
+     */
+    readonly permissions: () => Iterable<Pick<Context["permission"], "list">>;
+    /** The clock a location shutdown is recorded by: the question relay's, which judges it. */
+    readonly now: () => number;
+    readonly log: (message: string) => void;
+}
+/**
+ * What every plugin instance in the process shares of the person events: the handled event ids, shared
+ * with the tree's, and the requests and forms the top sessions were told about or that were answered first.
+ */
+export interface PersonState {
+    readonly seen: Set<string>;
+    readonly waiting: Waiting;
+    readonly answered: Set<string>;
+    readonly forms: FormsTold;
+}
+/** The session at the top of a lineage: where its permission requests go, since that is where the person is. */
+export declare const topOf: (chain: RosterEntry[]) => string;
+/** One field of an OpenCode form, as much of it as a notice shows. */
+export interface FormField {
+    readonly key: string;
+    readonly type: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly options?: ReadonlyArray<{
+        readonly value: string;
+        readonly label: string;
+        readonly description?: string;
+    }>;
+    readonly url?: string;
+    /** Not shown to the person. */
+    readonly hidden?: boolean;
+    /** Conditions on earlier answers; the field is shown only when they hold. */
+    readonly when?: ReadonlyArray<unknown>;
+}
+/** An OpenCode form, as its `form.created` event carries it. */
+export interface Form {
+    readonly id: string;
+    readonly sessionID: string;
+    readonly title: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly fields: ReadonlyArray<FormField>;
+}

package/dist/person/ports.js

@@ -0,0 +1,2 @@
+/** The session at the top of a lineage: where its permission requests go, since that is where the person is. */
+export const topOf = (chain) => chain.at(-1).parentID;

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,12 +55,12 @@ 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: 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.
+    // One answer at a time, and once, per question in this process, since storage cannot be claimed
+    // atomically: a second waits, going only if the first did not; meanwhile no cut-off notice or link.
     const since = ports.now();
     const left = () => wait - (ports.now() - since);
     const turn = holding(id, wait, Effect.gen(function* () {
@@ -71,11 +72,10 @@ 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; should it still go through, the
-        // child is told twice.
+        // 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.
         yield* within(passing, wait).pipe(Effect.ensuring(Effect.sync(() => {
             if (shared.passing.get(id) === passing)
                 shared.passing.delete(id);
@@ -84,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
@@ -93,12 +100,11 @@ 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 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.
+    // Its call just ended: whether it was cut off and stays or was settled and is dropped is known once
+    // settle is through, from the registry, not storage, which lacks a question whose write failed.
     if (known) {
         await known.settling;
         if (shared.questions.get(id) !== known)
@@ -117,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";
 }
@@ -158,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/person/question/lifecycle.d.ts

@@ -0,0 +1,43 @@
+import { Effect } from "effect";
+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.
+ */
+export declare const shutdownReportedAt: (directory?: string) => number | undefined;
+/**
+ * Called for `location.shutdown`: the location at `directory` is closing, which withdraws its open
+ * forms as if dismissed; with no location it counts for all. `at` is the watcher's clock, epoch ms.
+ */
+export declare function locationClosing(at: number, directory?: string): void;
+/**
+ * Whether a dismissal just seen at `directory` was the location closing rather than the person: it
+ * shut down within the grace, before or after, or this instance unloads in it; unknown matches any.
+ */
+export declare const closingSoon: (ports: QuestionPorts, loaded: () => boolean, directory: string | undefined) => Effect.Effect<boolean>;
+/**
+ * Adds an instance's ports to `loaded`, which other copies tell cut-off questions through, until the
+ * returned function is called. A location loading again forgets the shutdown recorded for it alone.
+ */
+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 shown: every call still waiting for its form is
+ * taken as shown; one still waiting for its permission check is relayed early, the lesser harm.
+ */
+export declare function formsMayHaveBeenMissed(): void;
+/**
+ * Called when an instance starts following OpenCode's events: a shown form is missed only while none
+ * follows, so waiting calls are released; true tells the caller to release again on its first event.
+ */
+export declare function eventsFollowed(): boolean;
+/** Called when an instance's event stream ended or broke. */
+export declare function eventsLeft(): void;

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

@@ -12,10 +12,8 @@ const shutdownAt = (directory) => directory === undefined
  */
 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).
+ * Called for `location.shutdown`: the location at `directory` is closing, which withdraws its open
+ * forms as if dismissed; with no location it counts for all. `at` is the watcher's clock, epoch ms.
  */
 export function locationClosing(at, directory) {
     shared.shutdowns.set(directory ?? ANYWHERE, at);
@@ -23,10 +21,8 @@ export function locationClosing(at, directory) {
         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.
+ * Whether a dismissal just seen at `directory` was the location closing rather than the person: it
+ * shut down within the grace, before or after, or this instance unloads in it; unknown matches any.
  */
 export const closingSoon = (ports, loaded, directory) => Effect.suspend(() => {
     const ms = ports.timing.dismissalGraceMs;
@@ -47,11 +43,8 @@ export const closingSoon = (ports, loaded, directory) => Effect.suspend(() => {
     }), () => (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.
+ * Adds an instance's ports to `loaded`, which other copies tell cut-off questions through, until the
+ * returned function is called. A location loading again forgets the shutdown recorded for it alone.
  */
 export function joinRelay(ports) {
     shared.loaded.add(ports);
@@ -72,9 +65,8 @@ export function formShown(event) {
     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.
+ * Called when an event stream may have missed forms shown: every call still waiting for its form is
+ * taken as shown; one still waiting for its permission check is relayed early, the lesser harm.
  */
 export function formsMayHaveBeenMissed() {
     for (const shown of shared.shown.values())
@@ -82,9 +74,8 @@ export function formsMayHaveBeenMissed() {
     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.
+ * Called when an instance starts following OpenCode's events: a shown form is missed only while none
+ * follows, so waiting calls are released; true tells the caller to release again on its first event.
  */
 export function eventsFollowed() {
     const missed = shared.following === 0 && shared.followed;

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"];
@@ -28,11 +27,10 @@ export type CallExit = Exit.Exit<{
 /** 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.
+ * Orders strings by UTF-16 code units, the default sort's order, stated: it only has to come out the
+ * same on both sides of a comparison; a locale-aware compare may rank two different labels as equal.
  */
-export declare function byCodeUnit(a: string, b: string): 1 | 0 | -1;
+export declare function byCodeUnit(a: string, b: string): 0 | 1 | -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. */

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 ?? [];
@@ -40,9 +40,8 @@ export function settledIn(exit) {
     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.
+ * Orders strings by UTF-16 code units, the default sort's order, stated: it only has to come out the
+ * same on both sides of a comparison; a locale-aware compare may rank two different labels as equal.
  */
 export function byCodeUnit(a, b) {
     if (a === b)

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";
@@ -8,8 +8,7 @@ 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` (the instance whose call was cut off), through an instance still loaded then, if any (any will do: a notice reaches a session in any location).
- * Without one, the next load tells it.
+ * `ports`, through any instance still loaded then; without one, the next load tells it.
  */
 function tellLater(ports, question) {
     const tellNow = Effect.suspend(() => {
@@ -25,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) {
@@ -44,9 +46,8 @@ const settle = (ports, question, exit, loaded) => Effect.gen(function* () {
     // 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;
-    // Telling the top session first, so what follows does not overtake the notice or come before it
-    // is stored; for a while only, so a notice that never returns does not hold everything else up.
-    // `told` is false when the top session was not told, or not yet.
+    // 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") {
@@ -58,15 +59,8 @@ const settle = (ports, question, exit, loaded) => Effect.gen(function* () {
     if (shared.questions.get(question.requestID) !== question) {
         return yield* Effect.promise(() => forget(ports, question));
     }
-    // Cut off: the turn was stopped, or OpenCode is closing the location, which withdraws every open
-    // form there as if the person had dismissed it (on a server shutdown, say), before unloading the
-    // plugin there (since 2.0.22) or after (the beta). So a dismissal is held for a moment, to see
-    // whether the location's shutdown or this instance's unload follows it. The question stays,
-    // answered by message from now on; a top session already asking the person passes their answer
-    // on that way. A closing location is not told now: the next load tells it, in this process or
-    // after a restart, or an instance still loaded does, a little later, when the process is still
-    // running then. The unload is looked at again here: it may have come during the wait above, after
-    // a held dismissal had already been taken for the person's.
+    // 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));
@@ -103,9 +97,8 @@ function startSettling(ports, question, exit, loaded) {
     });
 }
 /**
- * The question call of a session started with courier_spawn: once its form is shown, the session at
- * the top is told, and whichever answer comes first ends the call, the other side's question being
- * withdrawn. Other sessions' calls run unchanged.
+ * 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* () {
@@ -120,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)
@@ -179,40 +175,36 @@ 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 questions
- * with the same choices, in any order. Matching choices alone are not enough, or an unrelated
- * yes-or-no question of the top session would answer a child's.
+ * 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) &&
+        .filter((question) => linkable(question, sessionID) &&
         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 before that session asked, it says how to pass
- * the answers on.
+ * 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);
+    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)}` };
 }
 /**
- * After a linked call failed, its location still loaded: a dismissal by the person, unless the
- * location is closing (see settle), dismisses the question they were asked for too, or is logged
- * when the question was answered meanwhile; a call stopped while the asking call was cut off as
- * well tells the top session, which nobody has told yet.
+ * 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)) {

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

@@ -1,8 +1,7 @@
 import { Clock, Effect } from "effect";
 /**
- * Runs an effect of the relay in a fiber of its own, by the relay's clock, which is the clock of
- * its ports (`ports.now`): the promise settles as the effect ends, and is rejected if it fails or
- * is interrupted. Interrupting what waits on the promise does not stop the fiber.
+ * 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>;
 /**

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

@@ -38,9 +38,8 @@ let scope = Scope.makeUnsafe();
  */
 const start = (effect) => Effect.runFork(Effect.provideService(effect, Clock.Clock, clock)).pipe(Fiber.runIn(scope));
 /**
- * Runs an effect of the relay in a fiber of its own, by the relay's clock, which is the clock of
- * its ports (`ports.now`): the promise settles as the effect ends, and is rejected if it fails or
- * is interrupted. Interrupting what waits on the promise does not stop the fiber.
+ * 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)));

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;