opencode-courier 0.3.0 → 0.4.0

package/dist/index.js

@@ -3,70 +3,41 @@ import { Plugin as EffectPlugin } from "@opencode/plugin/effect";
 import { fromPromise } from "@opencode/plugin/promise/adapter";
 import { Effect } from "effect";
 import { randomUUID } from "node:crypto";
-import { dirtyOf, headOf, inspectWorktree } from "./cleanup.js";
-import { gate, hub, inbox, join, nudge, permissions, portsAt, track } from "./hub.js";
-import { readLimits, shapeContext } from "./limits.js";
-import { pendingOf } from "./relay.js";
-import { joinRelay, noticeCutOff, pendingQuestions, relayQuestions } from "./question/index.js";
-import { pruneExpired } from "./roster.js";
+import { watchFromHub } from "./platform/events.js";
+import { hub, openInProcess, permissions as domains, sharedState } from "./platform/hub.js";
+import { builtVersions, versionNotice } from "./platform/version.js";
+import { addSchedulingTools, cancelScheduled, dueJob, isScheduled } from "./scheduling/index.js";
+import { addPersonTools, asksPermission, asksQuestion, joinRelay, noticeCutOff, pendingOf, pendingQuestions, personEvents, portsAt, registerPersonRpc, relayQuestions, } from "./person/index.js";
 import { addSkill } from "./skill.js";
-import { addTools } from "./tools.js";
-import { watchFromHub } from "./watch.js";
-import { builtVersions, versionNotice } from "./version.js";
-import { listen, readConfig } from "./webhook.js";
+import { addTreeTools, deliverReleased, dirtyOf, headOf, inspectWorktree, pruneExpired, readLimits, readNativeChildren, registerTreeRpc, shapeContext, together, treeEvents, waitsOn, } from "./tree/index.js";
+import { addWebhookTools, joinReceiver, readConfig, receiving, subscribedSince, } from "./webhook/index.js";
+/** The spawns under way in the process, outside the hub, so spawns in other locations, copies and hub versions count them. */
+const gate = sharedState("spawning", () => ({ reserved: new Set(), turn: Promise.resolve() }));
+/** The type of each item enqueued for a spawned session, outside the hub like the gate. */
+const inbox = sharedState("inbox", () => new Map());
 /**
- * The webhook receiver, one per process: instances with a `webhook` option join `instances`, the first
- * starts the server and the last to unload stops it; one that could not listen is dropped for a retry.
+ * What each tick of the scheduler does, in order, through the first loaded member, of whichever copy:
+ * due `courier_later` messages, then released join groups. Every hub-v2 member's `later` is its LaterPorts.
  */
-const receivers = hub.receivers;
-const sameSettings = (a, b) => a.port === b.port && a.host === b.host && a.secret === b.secret && a.maxBytes === b.maxBytes;
-function startReceiver(config, log) {
-    const instances = new Set();
-    const receiver = {
-        config,
-        instances,
-        server: (receivers.closing ?? Promise.resolve())
-            .then(() => listen(config, () => instances.values().next().value))
-            .then((server) => {
-            log(`courier webhook: listening on http://${config.host}:${server.address().port}`);
-            return server;
-        }, (error) => {
-            log(`courier webhook: cannot listen on ${config.host}:${config.port}: ${String(error)}`);
-            if (receivers.current === receiver)
-                receivers.current = undefined;
-            return undefined;
-        }),
-    };
-    receivers.current = receiver;
-    return receiver;
-}
-function joinReceiver(config, ports) {
-    const receiver = receivers.current ?? startReceiver(config, ports.log);
-    if (!sameSettings(receiver.config, config))
-        ports.log(`courier webhook: already running on ${receiver.config.host}:${receiver.config.port} with other settings ` +
-            "(port, host, secret or maxBytes); this location's are ignored. Set the webhook option once, in the global config.");
-    receiver.instances.add(ports);
-    return async () => {
-        receiver.instances.delete(ports);
-        if (receiver.instances.size > 0 || receivers.current !== receiver)
-            return;
-        receivers.current = undefined;
-        const closing = receiver.server.then((server) => new Promise((resolve) => {
-            if (!server)
-                return resolve();
-            server.closeAllConnections();
-            server.close(() => resolve());
-        }));
-        receivers.closing = closing;
-        await closing;
-        if (receivers.closing === closing)
-            receivers.closing = undefined;
-    };
-}
+const jobs = [
+    dueJob,
+    (owner, claimed) => deliverReleased(owner.later, claimed),
+];
+const { join, track, nudge } = openInProcess(jobs);
+/** The permission domains of the loaded instances: every member's is its location's, whichever copy joined it. */
+const permissions = domains;
 // One set of handled events and of told permission requests for every instance in the process, since
 // several subscriptions and copies see the same events. The scheduler's claim set is the hub's own.
 const { watched } = hub;
-const watchState = { ...watched, forms: hub.forms, inbox };
+const watchState = { seen: watched.seen, inbox };
+const personState = { ...watched, forms: hub.forms };
+/**
+ * What a session waits on outside the tree, for the silent-turn rule, cheapest first: a request of its
+ * own to the person, then a scheduled message or a webhook it subscribed to since its last prompt.
+ */
+const outside = waitsOn(asksPermission, asksQuestion, together(isScheduled, subscribedSince));
+/** What the hub's subscriptions do with each event of OpenCode's, module by module, in this order. */
+const eventModules = [treeEvents(watchState, outside), personEvents(personState)];
 /**
  * The courier tools and webhook receiver, as a promise plugin joining the hub that runs the scheduler
  * and the watcher; its member carries the location by which the question relay finds its ports.
@@ -95,11 +66,13 @@ export const courier = () => Plugin.define({
             log,
         };
         const { limits, problems } = readLimits(ctx.options);
-        for (const problem of problems)
+        const { nativeChildren, problems: nativeProblems } = readNativeChildren(ctx.options);
+        for (const problem of [...problems, ...nativeProblems])
             log(`courier: ${problem}`);
         const roles = new Map();
         const ports = {
             limits,
+            nativeChildren,
             gate,
             roles,
             nudge,
@@ -138,19 +111,20 @@ export const courier = () => Plugin.define({
         catch (error) {
             later.log(`courier webhook: not started: ${error instanceof Error ? error.message : String(error)}`);
         }
-        const toolPorts = {
-            courier: ports,
-            cleanup: cleanupPorts,
-            stop: { courier: ports, later, cleanup: cleanupPorts },
-            later,
-            answer: answerPorts,
-            questions: questionPorts,
-            hooks,
-            waiting: watched.waiting,
-            receiving: async () => (await receivers.current?.server) !== undefined,
-        };
-        await ctx.tool.transform((tools) => addTools(tools, toolPorts));
+        const stopPorts = { courier: ports, cancelScheduled: (sessionID) => cancelScheduled(later, sessionID), cleanup: cleanupPorts };
+        // The tools in a fixed order: the tree's, then the person's, the scheduled messages' and the webhooks'.
+        await ctx.tool.transform((tools) => {
+            addTreeTools(tools, { courier: ports, cleanup: cleanupPorts, stop: stopPorts });
+            addPersonTools(tools, { answer: answerPorts, questions: questionPorts, waiting: watched.waiting });
+            addSchedulingTools(tools, later);
+            addWebhookTools(tools, { hooks, receiving });
+        });
         await ctx.skill.transform(addSkill);
+        // What the TUI part reads and its stop; a host that cannot register it still gets the rest, the tools included.
+        await Promise.resolve()
+            .then(() => registerTreeRpc(ctx.rpc, stopPorts))
+            .then(() => registerPersonRpc(ctx.rpc, { questions: questionPorts, permissions, maxTotal: limits.maxTotal }))
+            .catch((error) => log(`courier rpc: not registered, the TUI part shows nothing and cannot stop: ${String(error)}`));
         await ctx.session.hook("context", (event) => shapeContext({ storage: ctx.storage, limits, roles, log }, event));
         const pruned = pruneExpired(ctx.storage, Date.now()).catch((error) => log(`courier roster prune: ${String(error)}`));
         const leaveRelay = joinRelay(questionPorts);
@@ -164,8 +138,8 @@ export const courier = () => Plugin.define({
             log: later.log,
             nudge,
         };
-        // The hub's subscriptions to OpenCode's events, one and a standby, start with this copy's watcher.
-        watchFromHub(hub, watchState);
+        // The hub's subscriptions to OpenCode's events, one and a standby, start with this copy's modules.
+        watchFromHub(hub, eventModules);
         const member = {
             directory: ctx.location.directory,
             location: ctx.location,

package/dist/kernel/protocol.d.ts

@@ -0,0 +1,20 @@
+/**
+ * What every module of the plugin shares of the protocol with the models: the envelope a message arrives in,
+ * the phrase that ends a turn, the statuses of a report, the split line and the skill's id, and how outside
+ * text is clipped and defused.
+ */
+/** Closes a tool result after which the caller most likely has nothing left to do. */
+export declare const END_TURN = "If nothing else is left to do now, end your turn by replying without calling more tools.";
+/** The statuses a report carries: the task is done, partly done, waits on the parent, or failed. */
+export declare const STATUSES: readonly ["done", "partial", "blocked", "failed"];
+export type Status = (typeof STATUSES)[number];
+export declare const isStatus: (value: unknown) => value is Status;
+/** The one line a session states its split decision in, so a transcript tells a decision from one never made. */
+export declare const SPLIT_LINE = "split: no, because \u2026; considered: <the parts you weighed> or split: <n> parts: \u2026 (one phrase per part)";
+export declare const SKILL_ID = "courier-orchestrate";
+export declare function envelope(from: string, message: string, attributes?: Record<string, string>): string;
+export declare function clipText(text: string, max?: number): string;
+/** Defuses `<courier` and `</courier>` in outside text, so it cannot close the envelope or forge another. */
+export declare function defuse(text: string): string;
+/** A readable message for a failed courier call; OpenCode's own errors can carry an empty message. */
+export declare function describeFailure(tool: string, error: unknown): Error;

package/dist/kernel/protocol.js

@@ -0,0 +1,36 @@
+/**
+ * What every module of the plugin shares of the protocol with the models: the envelope a message arrives in,
+ * the phrase that ends a turn, the statuses of a report, the split line and the skill's id, and how outside
+ * text is clipped and defused.
+ */
+/** Closes a tool result after which the caller most likely has nothing left to do. */
+export const END_TURN = "If nothing else is left to do now, end your turn by replying without calling more tools.";
+/** The statuses a report carries: the task is done, partly done, waits on the parent, or failed. */
+export const STATUSES = ["done", "partial", "blocked", "failed"];
+export const isStatus = (value) => typeof value === "string" && STATUSES.includes(value);
+/** The one line a session states its split decision in, so a transcript tells a decision from one never made. */
+export const SPLIT_LINE = "split: no, because …; considered: <the parts you weighed> or split: <n> parts: … (one phrase per part)";
+export const SKILL_ID = "courier-orchestrate";
+export function envelope(from, message, attributes = {}) {
+    const extra = Object.entries(attributes)
+        .map(([name, value]) => ` ${name}="${value}"`)
+        .join("");
+    return `<courier from="${from}"${extra}>\n${message}\n</courier>`;
+}
+/** Longest piece of free text (a review body, a generic payload) copied into a delivered message. */
+const MAX_TEXT = 1500;
+export function clipText(text, max = MAX_TEXT) {
+    return text.length > max ? `${text.slice(0, max)}… [${text.length - max} more characters]` : text;
+}
+/** Defuses `<courier` and `</courier>` in outside text, so it cannot close the envelope or forge another. */
+export function defuse(text) {
+    return text.replace(/<(\/?)(courier)/gi, "&lt;$1$2");
+}
+/** A readable message for a failed courier call; OpenCode's own errors can carry an empty message. */
+export function describeFailure(tool, error) {
+    const tagged = error;
+    const message = (typeof tagged?.message === "string" && tagged.message) ||
+        [tagged?._tag, tagged?.sessionID].filter((item) => typeof item === "string").join(" ") ||
+        String(error);
+    return new Error(`${tool} failed: ${message}`);
+}

package/dist/kernel/tool.d.ts

@@ -0,0 +1,5 @@
+import type { Plugin } from "@opencode/plugin";
+/** The editor OpenCode hands a tool transform. */
+export type ToolEditor = Parameters<Parameters<Plugin.Context["tool"]["transform"]>[0]>[0];
+/** A `.catch` handler that rethrows a failure of `tool` as the error the model reads. */
+export declare const rethrow: (tool: string) => (error: unknown) => never;

package/dist/kernel/tool.js

@@ -0,0 +1,5 @@
+import { describeFailure } from "./protocol.js";
+/** A `.catch` handler that rethrows a failure of `tool` as the error the model reads. */
+export const rethrow = (tool) => (error) => {
+    throw describeFailure(tool, error);
+};

package/dist/person/events.d.ts

@@ -0,0 +1,23 @@
+import type { EventModule } from "../platform/events.js";
+import { type PermissionAsked, type PermissionReplied } from "./permission.js";
+import { type PersonPorts, type PersonState } from "./ports.js";
+/**
+ * Tells the session at the top, the parent of a child or the session a chain of children started
+ * from, what a waiting child asks and which answers there are, waking it. Returns the sessions told.
+ */
+export declare function reportAsked(ports: PersonPorts, state: PersonState, event: PermissionAsked): Promise<string[]>;
+/**
+ * Tells the session told about a request that it was answered some other way, so it does not pass on
+ * a stale question; requests answered through courier_answer no longer wait and are skipped.
+ */
+export declare function reportReplied(ports: PersonPorts, state: PersonState, event: PermissionReplied): Promise<string[]>;
+/**
+ * Relays the requests that spawned sessions already wait on, in every loaded location, which the
+ * event stream does not repeat: those asked while it was down, before the watcher (re)subscribed.
+ */
+export declare function relayPending(ports: PersonPorts, state: PersonState): Promise<void>;
+/**
+ * Tells the top session of a spawned child's pending permission or form, relays the requests already
+ * pending on every (re)subscribe, and tells the question relay when events are followed and when not.
+ */
+export declare function personEvents(state: PersonState): EventModule<PersonPorts>;

package/dist/person/events.js

@@ -0,0 +1,113 @@
+import { envelope } from "../kernel/protocol.js";
+import { claim } from "../platform/bounded.js";
+import { allEntries, lineage, nativeRootOf } from "../tree/index.js";
+import { reportForm, reportFormSettled } from "./form.js";
+import { listEverywhere } from "./permission.js";
+import { topOf } from "./ports.js";
+import { eventsFollowed, eventsLeft, formShown, formsMayHaveBeenMissed, locationClosing } from "./question/index.js";
+import { permissionNotice, permissionSettledNotice } from "./text.js";
+/**
+ * Tells the session at the top, the parent of a child or the session a chain of children started
+ * from, what a waiting child asks and which answers there are, waking it. Returns the sessions told.
+ */
+export async function reportAsked(ports, state, event) {
+    if (!claim(state.seen, event.id))
+        return [];
+    const request = event.data;
+    const chain = await lineage(ports.storage, request.sessionID);
+    // Claimed only now, after the lookup: a request answered meanwhile is in `answered`, and one
+    // already relayed, from the event or from the pending list, is in `waiting`.
+    if (!chain.length || state.answered.has(request.id) || !claim(state.waiting, request.id))
+        return [];
+    const startedBy = chain.length > 1 ? chain[0].parentID : undefined;
+    // A native child's request shows as OpenCode's own prompt in its native root's view: when that is the top's, it is not asked again.
+    const native = nativeRootOf(chain) === topOf(chain);
+    await ports.session.synthetic({
+        sessionID: topOf(chain),
+        text: envelope(request.sessionID, permissionNotice(chain[0].title, request, startedBy, native), {
+            asks: "permission",
+            request: request.id,
+            ...(native ? { shown: "native" } : {}),
+        }),
+        description: `Session ${request.sessionID} asks for permission`,
+        metadata: { source: "courier", from: request.sessionID, asks: "permission", requestID: request.id, ...(native ? { shown: "native" } : {}) },
+        delivery: "steer",
+    });
+    return [topOf(chain)];
+}
+/**
+ * Tells the session told about a request that it was answered some other way, so it does not pass on
+ * a stale question; requests answered through courier_answer no longer wait and are skipped.
+ */
+export async function reportReplied(ports, state, event) {
+    if (!claim(state.seen, event.id))
+        return [];
+    const { sessionID, requestID, reply } = event.data;
+    if (!state.waiting.delete(requestID)) {
+        claim(state.answered, requestID);
+        return [];
+    }
+    const chain = await lineage(ports.storage, sessionID);
+    if (!chain.length)
+        return [];
+    await ports.session.synthetic({
+        sessionID: topOf(chain),
+        text: envelope(sessionID, permissionSettledNotice(chain[0].title, requestID, reply), { answered: reply, request: requestID }),
+        description: `Session ${sessionID} no longer asks for permission`,
+        metadata: { source: "courier", from: sessionID, answered: reply, requestID },
+        delivery: "steer",
+    });
+    return [topOf(chain)];
+}
+/**
+ * Relays the requests that spawned sessions already wait on, in every loaded location, which the
+ * event stream does not repeat: those asked while it was down, before the watcher (re)subscribed.
+ */
+export async function relayPending(ports, state) {
+    const sessions = new Set((await allEntries(ports.storage)).map((entry) => entry.sessionID));
+    const domains = [...ports.permissions()];
+    // Each request is claimed before its notice goes out, so relaying them all at once tells each
+    // once, however many locations list it; a location that cannot be read lists none.
+    const relay = async (sessionID) => {
+        const listed = (await listEverywhere(domains, sessionID)).flatMap((found) => found.requests);
+        await Promise.all(listed.map((request) => reportAsked(ports, state, { id: `pending:${request.id}`, data: request })));
+    };
+    await Promise.all([...sessions].map(relay));
+}
+/** The events of what a spawned session asks the person: permission requests, forms, and locations closing on them. */
+function routePerson(ports, state, event) {
+    if (event.type === "permission.asked")
+        return reportAsked(ports, state, event);
+    if (event.type === "permission.replied")
+        return reportReplied(ports, state, event);
+    if (event.type === "form.created") {
+        // Not claimed: the hub's other subscription, or another copy's watcher, may resolve the same
+        // waiting call, which is harmless.
+        formShown(event);
+        return reportForm(ports, state, event);
+    }
+    if (event.type === "form.replied" || event.type === "form.cancelled")
+        return reportFormSettled(ports, state, event);
+    // Not claimed either: a location closing withdraws its forms, which must not pass for dismissals.
+    // The event's location is optional; without one, the shutdown counts for every location.
+    if (event.type === "location.shutdown") {
+        const directory = event.location?.directory;
+        locationClosing(ports.now(), typeof directory === "string" ? directory : undefined);
+    }
+    return undefined;
+}
+/**
+ * Tells the top session of a spawned child's pending permission or form, relays the requests already
+ * pending on every (re)subscribe, and tells the question relay when events are followed and when not.
+ */
+export function personEvents(state) {
+    return {
+        handle: (ports, event) => routePerson(ports, state, event),
+        // Question forms shown while no instance followed the events were not seen: released now,
+        // and again on the first event, by when the stream is surely connected.
+        followed: () => (eventsFollowed() ? formsMayHaveBeenMissed : undefined),
+        // Alongside the new subscription; a request both relays see is relayed once.
+        subscribed: (ports) => relayPending(ports, state).catch((error) => ports.log(`courier watch: could not relay pending requests: ${String(error)}`)),
+        left: eventsLeft,
+    };
+}

package/dist/person/form.d.ts

@@ -0,0 +1,26 @@
+import { type Form, type PersonPorts, type PersonState } from "./ports.js";
+/** 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;
+    };
+}
+/**
+ * Tells the top session about a form OpenCode shows in a spawned session, such as web search asking
+ * for its provider, which only the person can answer; question forms are left to the question relay.
+ */
+export declare function reportForm(ports: PersonPorts, state: PersonState, event: FormCreated): Promise<string[]>;
+/** Tells the session told about a form that it was answered or withdrawn, so it does not send the person to a form that is gone. */
+export declare function reportFormSettled(ports: PersonPorts, state: PersonState, event: FormSettled): Promise<string[]>;

package/dist/person/form.js

@@ -0,0 +1,64 @@
+import { envelope } from "../kernel/protocol.js";
+import { claim, SEEN_MAX, setBounded } from "../platform/bounded.js";
+import { lineage, nativeRootOf } from "../tree/index.js";
+import { topOf } from "./ports.js";
+import { formNotice, formSettledNotice, kindOf } from "./text.js";
+/** The `metadata.kind` of the forms OpenCode's question tool asks with; the question relay passes those on. */
+export const QUESTION_FORM = "question";
+/**
+ * Tells the top session about a form OpenCode shows in a spawned session, such as web search asking
+ * for its provider, which only the person can answer; question forms are left to the question relay.
+ */
+export async function reportForm(ports, state, event) {
+    if (!claim(state.seen, event.id))
+        return [];
+    const form = event.data.form;
+    if (kindOf(form) === QUESTION_FORM)
+        return [];
+    const chain = await lineage(ports.storage, form.sessionID);
+    // As with a permission request, claimed after the lookup, so a form settled meanwhile is not told.
+    if (!chain.length || state.forms.settled.has(form.id) || state.forms.told.has(form.id))
+        return [];
+    const startedBy = chain.length > 1 ? chain[0].parentID : undefined;
+    const kind = kindOf(form);
+    const telling = ports.session.synthetic({
+        sessionID: topOf(chain),
+        text: envelope(form.sessionID, formNotice(chain[0].title, form, startedBy, nativeRootOf(chain), topOf(chain)), {
+            asks: "form",
+            form: form.id,
+            ...(kind ? { kind } : {}),
+        }),
+        description: `Session ${form.sessionID} shows a form`,
+        metadata: { source: "courier", from: form.sessionID, asks: "form", formID: form.id, ...(kind ? { kind } : {}) },
+        delivery: "steer",
+    });
+    setBounded(state.forms.told, form.id, telling, SEEN_MAX);
+    await telling;
+    return [topOf(chain)];
+}
+/** Tells the session told about a form that it was answered or withdrawn, so it does not send the person to a form that is gone. */
+export async function reportFormSettled(ports, state, event) {
+    if (!claim(state.seen, event.id))
+        return [];
+    const { id, sessionID } = event.data;
+    const telling = state.forms.told.get(id);
+    if (!telling) {
+        claim(state.forms.settled, id);
+        return [];
+    }
+    state.forms.told.delete(id);
+    const settled = event.type === "form.replied" ? "answered" : "cancelled";
+    // After the notice that the form is shown, which another instance may still be sending, so the
+    // settling never arrives first; and not at all when that notice did not go out.
+    const [chain, told] = await Promise.all([lineage(ports.storage, sessionID), telling.then(() => true, () => false)]);
+    if (!chain.length || !told)
+        return [];
+    await ports.session.synthetic({
+        sessionID: topOf(chain),
+        text: envelope(sessionID, formSettledNotice(chain[0].title, id, settled), { settled, form: id }),
+        description: `Session ${sessionID} no longer shows a form`,
+        metadata: { source: "courier", from: sessionID, settled, formID: id },
+        delivery: "steer",
+    });
+    return [topOf(chain)];
+}

package/dist/person/index.d.ts

@@ -0,0 +1,17 @@
+import type { PendingPrompt, WatchPorts } from "../tree/index.js";
+import type { PersonPorts } from "./ports.js";
+import type { Prompt } from "./question/index.js";
+export { personEvents } from "./events.js";
+export { asksPermission, pendingOf } from "./permission.js";
+export type { AnswerPorts, Permissions, Waiting } from "./permission.js";
+export type { PersonPorts, PersonState } from "./ports.js";
+export { registerPersonRpc } from "./rpc-handlers.js";
+export { asksQuestion, joinRelay, noticeCutOff, pendingQuestions, portsAt, relayQuestions } from "./question/index.js";
+export type { QuestionPorts } from "./question/index.js";
+export { addPersonTools } from "./tools.js";
+export type { PersonToolPorts } from "./tools.js";
+type Satisfies<T extends U, U> = T;
+/** The tree declares the question shape its `Pending` needs; this fails to compile once `Prompt` and it differ. */
+export type PromptMatchesPending = [Satisfies<Prompt, PendingPrompt>, Satisfies<PendingPrompt, Prompt>];
+/** The watcher's ports are the ones the person events run on; this fails to compile once `WatchPorts` stops satisfying `PersonPorts`. */
+export type WatchPortsArePersonPorts = Satisfies<WatchPorts, PersonPorts>;

package/dist/person/index.js

@@ -0,0 +1,5 @@
+export { personEvents } from "./events.js";
+export { asksPermission, pendingOf } from "./permission.js";
+export { registerPersonRpc } from "./rpc-handlers.js";
+export { asksQuestion, joinRelay, noticeCutOff, pendingQuestions, portsAt, relayQuestions } from "./question/index.js";
+export { addPersonTools } from "./tools.js";

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

@@ -1,7 +1,27 @@
 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";
+import { type Pending, type RosterStorage } from "../tree/index.js";
+/** 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];
+/** A permission request, as OpenCode's `permission.asked` event carries it. */
+export interface PermissionRequest {
+    readonly id: string;
+    readonly sessionID: string;
+    readonly action: string;
+    readonly resources: ReadonlyArray<string>;
+    readonly save?: ReadonlyArray<string>;
+    readonly message?: string;
+}
+/**
+ * What answering a permission request did; `answered` is false when no location loaded here held the
+ * request: answered already, no longer waited for, or waiting in another server on the same data dir.
+ */
+export interface PermissionAnswered {
+    readonly sessionID: string;
+    readonly requestID: string;
+    readonly reply: Reply;
+    readonly answered: boolean;
+}
 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">;
@@ -44,6 +64,10 @@ export declare function listEverywhere<D extends Pick<Permissions, "list">>(perm
     domain: D;
     requests: import("@opencode/client").PermissionRequest[];
 })[]>;
+/** Whether a session waits on a permission request of its own, in any loaded location. */
+export declare function asksPermission(ports: {
+    readonly permissions: () => Iterable<Pick<Permissions, "list">>;
+}, sessionID: string): Promise<boolean>;
 /**
  * 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.
@@ -51,22 +75,4 @@ export declare function listEverywhere<D extends Pick<Permissions, "list">>(perm
 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 → person/permission.js}

@@ -1,10 +1,16 @@
-import { describeFailure } from "./courier.js";
-import { REJECTED, REPLIES } from "./notices.js";
-import { answeringTop } from "./roster.js";
+import { describeFailure } from "../kernel/protocol.js";
+import { REJECTED } from "./text.js";
+import { answeringTop } from "../tree/index.js";
+/** The answers to a permission request, as OpenCode's own prompt offers them. */
+export const REPLIES = ["once", "always", "reject"];
 /** A session's pending requests in every location, with the domain holding each; a location that cannot be read gives its error. */
 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 }))));
 }
+/** Whether a session waits on a permission request of its own, in any loaded location. */
+export async function asksPermission(ports, sessionID) {
+    return (await listEverywhere([...ports.permissions()], sessionID)).some((found) => found.requests.length > 0);
+}
 /** The location holding a pending request, and the request; undefined when none does, and an error when one could not be read. */
 async function locate(ports, sessionID, requestID) {
     const listed = await listEverywhere(ports.permissions(), sessionID);
@@ -64,5 +70,3 @@ 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/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;