opencode-courier 0.13.8 → 0.14.0

package/dist/memory/text.js

@@ -1,13 +1,9 @@
-/** The memory's model-facing texts: what courier_recall and courier_note say. */
 import { clipText, clipWords, defuseBlock } from "../kernel/protocol.js";
 import { LESSON_MAX, oneLine, PART_STATUSES, splitProse } from "./domain.js";
-/** The tool's name, which the skill and the role part name too. */
 export const RECALL_TOOL = "courier_recall";
-/** The lesson tool's name, which the skill's last step names. */
 export const NOTE_TOOL = "courier_note";
 const count = (n, noun) => `${n} ${noun}${n === 1 ? "" : "s"}`;
 const DAY_MS = 86_400_000;
-/** A duration in milliseconds as a model reads it: seconds under half a minute, else whole minutes, else hours and minutes. */
 export function duration(ms) {
     const minutes = Math.round(ms / 60_000);
     if (minutes < 1)
@@ -16,39 +12,33 @@ export function duration(ms) {
         return `${minutes} min`;
     return `${Math.floor(minutes / 60)} h ${minutes % 60} min`;
 }
-/** How long ago a record last moved: a duration under a day, else whole days, which a record kept for months is read in. */
 export function age(ms) {
     const days = Math.floor(ms / DAY_MS);
     return days < 1 ? duration(ms) : count(days, "day");
 }
-/** How a listing counts the parts of a record: by status, in the order of `PART_STATUSES`, plus how many were isolated and how many spawns were refused. */
-function partsLine(parts) {
-    if (!parts.length)
-        return "no parts";
+function partsLine(all) {
+    const parts = all.filter((part) => !part.subagent);
+    const subagents = all.length - parts.length;
     const statuses = PART_STATUSES.flatMap((status) => {
         const n = parts.filter((part) => part.status === status).length;
         return n ? [`${n} ${status}`] : [];
     }).join(", ");
     const isolated = parts.filter((part) => part.isolated).length;
     const refused = parts.reduce((n, part) => n + (part.refused ?? 0), 0);
-    const deepest = Math.max(...parts.map((part) => part.depth));
+    const deepest = Math.max(0, ...all.map((part) => part.depth));
     return [
-        `${count(parts.length, "part")}: ${statuses}`,
+        parts.length ? `${count(parts.length, "part")}: ${statuses}` : "no parts",
         ...(deepest > 1 ? [`${deepest} levels deep`] : []),
         ...(isolated ? [`${isolated} isolated`] : []),
         ...(refused ? [`${count(refused, "spawn")} refused`] : []),
+        ...(subagents ? [count(subagents, "subagent")] : []),
     ].join(", ");
 }
 const day = (at) => new Date(at).toISOString().slice(0, 10);
-/** A lesson as the listing and the note's result show it: dated, and from which depth when a session below the top wrote it. */
 export function lessonLine(lesson) {
     const from = lesson.depth === undefined ? "" : `, from depth ${lesson.depth}`;
     return `lesson (${day(lesson.at)}${from}): "${clipText(oneLine(lesson.text), LESSON_MAX)}"`;
 }
-/**
- * One record as the listing shows it: its top, when it started, its title, its split line and its latest revision as prose,
- * its parts, how long it ran, how long ago it last moved, what it cost, and whether the person pinned it.
- */
 export function recordLine(record, top, now) {
     const cost = record.parts.reduce((sum, part) => sum + (part.cost ?? 0), 0);
     const costed = record.parts.some((part) => part.cost !== undefined);
@@ -67,14 +57,8 @@ export function recordLine(record, top, now) {
         ...(record.lesson ? [lessonLine(record.lesson)] : []),
     ].join(" · ");
 }
-/** What the listing says of pinned records, when it holds one. */
 const PINNED = "A record marked \"pinned\" is one the person chose to keep and listed first: weigh it before the rest.";
-/** What courier_recall says when the memory option is off. */
 export const RECALL_OFF = "Memory is off: the plugin's memory option is false, so no record of a session tree is kept or listed in this project. Decide from the task alone.";
-/**
- * The listing: every record of the project, the pinned first and then newest first, the caller's own tree marked, each
- * aged against `now`.
- */
 export function recallListText(records, top, now) {
     const others = records.filter((record) => record.sessionID !== top);
     const pinned = records.some((record) => record.pinned);
@@ -87,14 +71,11 @@ export function recallListText(records, top, now) {
         : "No earlier tree is recorded in this project: a tree's record is written by a courier_recall call and as each turn in it ends, and kept 90 days. Decide from the task alone.";
     return [intro, ...records.map((record) => recordLine(record, top, now))].join("\n");
 }
-/** One record in full, as JSON: durations in milliseconds, times in epoch milliseconds, context use as a share of the model's window. */
 export function recallRecordText(record) {
     return `Record of the tree under ${record.sessionID}, in project ${record.projectID} (durations in milliseconds, context use as a share of the model's window):\n${JSON.stringify(record, null, 2)}`;
 }
 export const recallMissingText = (sessionID) => `No record of a tree whose top session is ${sessionID} in this project. courier_recall without sessionID lists the records there are.`;
-/** What a lesson is for, which the tool's description and the note's result both say. */
 const NOT_A_RULE = "A lesson that holds every time belongs in AGENTS.md or the skill, which only the person puts there: tell them instead of noting it.";
-/** What courier_note says once the lesson is written: where, and what it replaced. */
 export function noteText(top, lesson, replaced) {
     return [
         `Noted on the record of the tree under ${top} as its ${lessonLine(lesson)}.`,
@@ -102,29 +83,18 @@ export function noteText(top, lesson, replaced) {
         `${RECALL_TOOL} lists it after the tree's facts; a second ${NOTE_TOOL} replaces it. ${NOT_A_RULE}`,
     ].join(" ");
 }
-/** What courier_note says when the memory option is off. */
 export const NOTE_OFF = "Not noted: the plugin's memory option is false, so no record of a session tree is kept in this project to write a lesson on.";
 export const noteLeafRefusal = (depth, maxDepth) => `Not noted: this session is a leaf, at depth ${depth} of a session tree that goes at most ${maxDepth} deep (maxDepth). A lesson is ` +
     "written by the session that verified the tree, the top or one that started sessions; put what you learned in your report instead.";
-/** What a lesson holds, which the empty and the long refusal both ask for. */
 const ONE_LINE = "what the next orchestrator in this project should know about running a tree like this one, with the job it comes from and the reason";
 export const NOTE_EMPTY = `Not noted: text is empty. Write one line, ${ONE_LINE}, or nothing.`;
-/** The refusal of a lesson longer than `LESSON_MAX` as one line: nothing is written, and the earlier lesson stays. */
 export const noteLongRefusal = (length) => `Not noted: the lesson is ${length} characters, at most ${LESSON_MAX}; write it shorter. Nothing was written, and the earlier lesson, ` +
     `if there was one, stays. Keep one line, ${ONE_LINE}, and leave out what the record's facts already say.`;
 export const noteUnrecordedRefusal = (top) => `Not noted: the tree under ${top} has no record in this project to write a lesson on. A record is written by a ${RECALL_TOOL} call ` +
     "and as each turn in the tree ends, so call it once first, or note once a session you started has reported.";
-// The lessons entry: what a spawned session's system prompt says of the project's earlier trees.
-/** The key of the session instruction entry carrying the project's lessons, `<context key="lessons">`. */
 export const LESSONS_KEY = "lessons";
-/** How every lessons entry begins. */
 export const LESSONS_PREFIX = "opencode-courier lessons:";
-/** How many lessons the entry carries: the records' order, pinned first, then newest first. */
 export const LESSONS_MAX = 5;
-/**
- * The lessons entry: the lessons of the project's records as courier_recall lists them, pinned first and then newest first,
- * at most `LESSONS_MAX`, each with its tree's title; undefined while no record holds one.
- */
 export function lessonsEntry(records) {
     const lessons = records.filter((record) => record.lesson).slice(0, LESSONS_MAX);
     if (!lessons.length)

package/dist/memory/tools.d.ts

@@ -7,10 +7,8 @@ export declare const RecallInput: Schema.Struct<{
 export declare const NoteInput: Schema.Struct<{
     readonly text: Schema.String;
 }>;
-/** What the memory's tools run on: one instance's ports and the process's shared state. */
 export interface MemoryToolPorts {
     readonly memory: MemoryPorts;
     readonly state: Pick<MemoryState, "tops">;
 }
-/** Adds `courier_recall` and `courier_note`, direct tools rather than code-mode ones. */
 export declare function addMemoryTools(tools: ToolEditor, ports: MemoryToolPorts): void;

package/dist/memory/tools.js

@@ -15,7 +15,6 @@ export const NoteInput = Schema.Struct({
             "with the job it comes from and the reason.",
     }),
 });
-/** Adds `courier_recall` and `courier_note`, direct tools rather than code-mode ones. */
 export function addMemoryTools(tools, ports) {
     tools.add({
         name: RECALL_TOOL,
@@ -56,7 +55,6 @@ export function addMemoryTools(tools, ports) {
         input: NoteInput,
         execute: async (input, context) => {
             const result = await note(ports.memory, context.sessionID, input).catch(rethrow(NOTE_TOOL));
-            // A refusal is the tool's failure, as courier_spawn's are, so the step ends on it and the model reads why.
             const refuse = (text) => describeFailure(NOTE_TOOL, new Error(text));
             switch (result.kind) {
                 case "noted": {

package/dist/memory/tui.d.ts

@@ -1,50 +1,26 @@
 import type { Plugin } from "@opencode/plugin/tui";
 import { type Forgotten, type MemoryLesson, type MemoryPart, type MemoryReads, type MemoryRecord, type Pinned } from "./rpc.js";
 type Context = Plugin.Context;
-/** The command that opens the memory view: `/courier memory`, or the palette. */
 export declare const MEMORY_COMMAND = "courier.memory";
-/** The memory view's line of the `/courier` command's usage. */
 export declare const MEMORY_USAGE = "/courier memory lists this project's tree records, to read, pin or forget";
-/** What the view says, in a toast, with the memory option off in the project asked. */
 export declare const MEMORY_OFF = "Memory is off in this project: the plugin's memory option is false, so no record of a session tree is kept or listed here.";
-/** What the view says, in a toast, when the project has no record: when none was written yet, or the last was forgotten. */
 export declare const NO_RECORDS = "No record of a session tree in this project: one is written as each turn in a tree ends, and kept 90 days.";
-/** The most characters of a lesson a list row's line under it shows; the record in full has it whole. */
 export declare const LESSON_LINE_MAX = 160;
-/** The most characters of a title a list row shows, so that "(this session)" after it fits the host's 61. */
 export declare const ROW_TITLE_MAX = 46;
-/** The group of the records moved on the current local day, over the others' local dates, as the host's Sessions dialog has it. */
 export declare const TODAY = "Today";
-/** The group of the records the person pinned, above the days, shown only while there is one. */
 export declare const PINNED = "Pinned";
-/** The widest a row of the lesson in a record in full is; a longer lesson wraps over rows. */
 export declare const LESSON_ROW = 90;
-/** A record's name, as its rows and confirms show it: its title on one line, else its top session. */
 export declare const nameOf: (record: MemoryRecord) => string;
-/** A record's parts counted by status, in the order of `PART_STATUSES`: "3 parts: 2 done, 1 partial"; "no parts" with none. */
-export declare function partsCounted(parts: ReadonlyArray<MemoryPart>): string;
-/** The parts' costs summed, when any is known. */
+export declare function partsCounted(all: ReadonlyArray<MemoryPart>): string;
 export declare function costOf(record: MemoryRecord): number | undefined;
-/** A list row's title: the tree's title, its top session's id without one; the open session's own tree says so. */
 export declare function recordTitle(record: MemoryRecord, open?: string): string;
-/**
- * A list row's group: `Pinned` for a pinned record, `Today` for a tree last moved on the local day of `now`, else that
- * local date; the RPC's order, pinned first and then by the last move, keeps the groups in that order.
- */
 export declare function recordCategory(record: MemoryRecord, now?: number): string;
-/** How often other trees' courier_recall calls listed the record and opened it in full: "shown 7 times, opened once"; "shown 7 times" alone when none opened it. */
 export declare function readsLine(reads: MemoryReads): string;
-/** A lesson as the view shows it: dated on the local day, from which depth when a session below the top wrote it, and its text. */
 export declare function lessonHeading(lesson: MemoryLesson): string;
-/** A list row's description: its parts by status, how long the tree ran, what its parts cost, that it is not finished when it is not, and how often other trees read it. */
 export declare function recordDescription(record: MemoryRecord): string;
-/** The lines under a list row: the lesson, dated and from which depth, clipped; none without a lesson. */
 export declare function recordDetails(record: MemoryRecord): string[];
-/** One part as the record in full describes it: its status, depth, isolation, group, duration, cost, context use and spawns refused. */
 export declare function partLine(part: MemoryPart): string;
-/** `text` in rows of at most `width` characters, broken at spaces where it can be. */
 export declare function wrap(text: string, width: number): string[];
-/** A row of a record in full: a fact of the tree, one of its parts, or a row of its lesson (0 its heading), which `x` forgets alone. */
 export type Line = {
     readonly kind: "fact";
     readonly key: string;
@@ -55,27 +31,17 @@ export type Line = {
     readonly kind: "lesson";
     readonly row: number;
 };
-/** Where the cursor goes in a record in full after its lesson is forgotten: the lesson's first row, or the row that replaced it. */
 export declare const lessonLine: (record: MemoryRecord) => Line;
-/** The records the list's cursor tries, in order, after one is forgotten, kept or left: it, unless forgotten, then those after it, then those before it, nearest first. */
 export declare function nearby(sessionIDs: ReadonlyArray<string>, sessionID: string, forgotten: boolean): string[];
-/** The rows of a record in full, in three categories: the tree's facts, its parts and its lesson. */
 export declare function detailOptions(record: MemoryRecord): Array<{
     title: string;
     value: Line;
     category: string;
     description?: string;
 }>;
-/** What the confirm asks before a forget: the record named, with the local day it last moved, and what goes and what stays. */
 export declare function forgetMessage(record: MemoryRecord, lesson: boolean): string;
-/** The toast after a forget, as the server reports it. */
 export declare function forgottenLine(record: MemoryRecord, outcome: Forgotten["outcome"]): string;
-/** The toast after a pin, as the server reports it. */
 export declare function pinnedLine(record: MemoryRecord, outcome: Pinned["outcome"]): string;
-/**
- * Adds the memory view: the project's records (the open session's location, else the TUI's, else the server's default) under
- * `Pinned`, `Today` and the days they last moved; `enter` shows one in full, `p` pins or unpins one, `x` forgets one or its lesson after a confirm.
- */
 export declare function addMemoryView(ctx: Context): {
     open: () => Promise<void>;
 };

package/dist/person/events.d.ts

@@ -1,23 +1,7 @@
 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 are skipped. Sent with `resume: false`, so it starts no turn.
- */
 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

@@ -6,21 +6,15 @@ 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.
+    // a native child's request shows in its native root's view (api-notes)
     const native = nativeRootOf(chain) === topOf(chain);
     await ports.session.synthetic({
         sessionID: topOf(chain),
@@ -35,10 +29,6 @@ export async function reportAsked(ports, state, event) {
     });
     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 are skipped. Sent with `resume: false`, so it starts no turn.
- */
 export async function reportReplied(ports, state, event) {
     if (!claim(state.seen, event.id))
         return [];
@@ -60,57 +50,40 @@ export async function reportReplied(ports, state, event) {
     });
     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.
- */
+// the event stream does not replay requests asked before it 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));
 }
-/** What `routePerson` dispatches on. */
 const PERSON_TYPES = ["permission.asked", "permission.replied", "form.created", "form.replied", "form.cancelled", "location.shutdown"];
-/** 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.
+    // location.shutdown may name no location: it then counts for all
     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 {
         types: PERSON_TYPES,
         handle: (ports, event) => routePerson(ports, state, event),
-        // Question forms shown while no instance followed the events were not seen: released now,
-        // and again once 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

@@ -1,15 +1,12 @@
 import { type ShownForm } from "../tree/index.js";
 import { type Form, type FormsShown, 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;
@@ -18,12 +15,6 @@ export interface FormSettled {
         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[]>;
-/** The forms a session shows now, oldest first, as the tree's `forms` port lists them. */
 export declare const formsShown: (shown: FormsShown, sessionID: string) => ShownForm[];

package/dist/person/form.js

@@ -3,12 +3,7 @@ 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 [];
@@ -18,7 +13,6 @@ export async function reportForm(ports, state, event) {
     if (!state.forms.settled.has(form.id))
         setBounded(state.shown, form.id, { sessionID: form.sessionID, title: form.title }, SEEN_MAX);
     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;
@@ -38,7 +32,6 @@ export async function reportForm(ports, state, event) {
     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 [];
@@ -51,8 +44,6 @@ export async function reportFormSettled(ports, state, event) {
     }
     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 [];
@@ -65,5 +56,4 @@ export async function reportFormSettled(ports, state, event) {
     });
     return [topOf(chain)];
 }
-/** The forms a session shows now, oldest first, as the tree's `forms` port lists them. */
 export const formsShown = (shown, sessionID) => [...shown].flatMap(([id, form]) => (form.sessionID === sessionID ? [{ id, title: form.title }] : []));

package/dist/person/index.d.ts

@@ -12,7 +12,5 @@ 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/permission.d.ts

@@ -1,15 +1,9 @@
 import type { Plugin } from "@opencode/plugin";
 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];
-/**
- * What courier_answer passes on: `once`, which OpenCode first asks the person about in the caller's
- * session, or `reject`. Never `always`: the plugin grants no standing rule to the caller or the child.
- */
 export declare const PROPOSALS: readonly ["once", "reject"];
 export type Proposal = (typeof PROPOSALS)[number];
-/** A permission request, as OpenCode's `permission.asked` event carries it. */
 export interface PermissionRequest {
     readonly id: string;
     readonly sessionID: string;
@@ -19,10 +13,6 @@ export interface PermissionRequest {
     readonly message?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
-/**
- * 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;
@@ -30,16 +20,12 @@ export interface PermissionAnswered {
     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">;
-/** OpenCode's check of a session's permission rules, which asks the person in that session when they say so. */
 export type Assert = Context["permission"]["assert"];
-/** The part of OpenCode's `permission.asked` event the notice is made from. */
 export interface PermissionAsked {
     readonly id: string;
     readonly data: PermissionRequest;
 }
-/** The part of OpenCode's `permission.replied` event. */
 export interface PermissionReplied {
     readonly id: string;
     readonly data: {
@@ -48,19 +34,12 @@ export interface PermissionReplied {
         readonly reply: Reply;
     };
 }
-/**
- * Shared by every plugin instance in the process, like the handled event ids: the requests whose
- * notice went to a parent and that courier_answer has not answered yet.
- */
 export type Waiting = Set<string>;
 export interface AnswerPorts {
     readonly storage: RosterStorage;
-    /** The permission domains of every loaded location; the request is answered where it is pending. */
     readonly permissions: () => Iterable<Permissions>;
-    /** The caller's location's check, which prompts the person in the caller's session. */
     readonly assert: Assert;
 }
-/** The courier_answer call a proposal comes from, which OpenCode's prompt in the caller's session is bound to. */
 export interface AnswerCall {
     readonly messageID: string;
     readonly callID: string;
@@ -72,7 +51,6 @@ export interface AnswerInput {
     readonly message?: string;
     readonly call?: AnswerCall;
 }
-/** A session's pending requests in every location, with the domain holding each; a location that cannot be read gives its error. */
 export declare function listEverywhere<D extends Pick<Permissions, "list">>(permissions: Iterable<D>, sessionID: string): Promise<({
     domain: D;
     requests: never[];
@@ -81,26 +59,15 @@ 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>;
-/**
- * Whether `permission.assert` failed because the person rejected the caller's prompt without a reason,
- * which OpenCode ends the caller's step on; the tool rethrows it as it is, and the child's request waits on.
- */
 export declare const isDeclined: (error: unknown) => boolean;
-/**
- * Answers a permission request of a session started, directly or through others, from the caller, which must be the top
- * session, a proposed `once` only once OpenCode allowed it there; `answered` is false when no location loaded here holds it.
- */
 export declare function answer(ports: AnswerPorts, waiting: Waiting, callerID: string, input: AnswerInput): Promise<PermissionAnswered>;
-/** The child's request a prompt of courier_answer's asks about, read from the metadata `askCaller` gives it; undefined for any other request. */
 export declare function passedOn(metadata: Readonly<Record<string, unknown>> | undefined): {
     sessionID: string;
     requestID: string;
 } | undefined;
-/** The requests a session waits on of its own, in whichever location holds them, each with the child's request it passes on when courier_answer asks it. */
 export declare function ownRequests(permissions: Iterable<Permissions>, sessionID: string): Promise<{
     request: PermissionRequest;
     passesOn: {
@@ -108,6 +75,5 @@ export declare function ownRequests(permissions: Iterable<Permissions>, sessionI
         requestID: string;
     } | undefined;
 }[]>;
-/** The requests a session waits on, in whichever location holds them, for courier_children. */
 export declare function pendingOf(permissions: Iterable<Permissions>, sessionID: string): Promise<Pending[]>;
 export {};

package/dist/person/permission.js

@@ -1,22 +1,14 @@
 import { describeFailure } from "../kernel/protocol.js";
 import { REJECTED, refusedText } 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"];
-/**
- * What courier_answer passes on: `once`, which OpenCode first asks the person about in the caller's
- * session, or `reject`. Never `always`: the plugin grants no standing rule to the caller or the child.
- */
 export const PROPOSALS = ["once", "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);
     for (const { domain, requests } of listed) {
@@ -30,12 +22,8 @@ async function locate(ports, sessionID, requestID) {
     return undefined;
 }
 const tagOf = (value) => value?._tag;
-/**
- * Whether `permission.assert` failed because the person rejected the caller's prompt without a reason,
- * which OpenCode ends the caller's step on; the tool rethrows it as it is, and the child's request waits on.
- */
 export const isDeclined = (error) => tagOf(error) === "Permission.DeclinedError";
-/** Why `permission.assert` refused: the caller's rules deny the action, or the person rejected the prompt with a reason. */
+// the host's Tool.Error message is the deny rule's or the feedback (api-notes)
 function refusalOf(error) {
     if (tagOf(error) !== "Tool.Error")
         return undefined;
@@ -45,12 +33,9 @@ function refusalOf(error) {
         return undefined;
     return typeof message === "string" && message ? message : "not allowed";
 }
-/**
- * OpenCode's check of the child's request under the caller's rules, which asks the person in the caller's session, with the
- * request's own action and resources and nothing to save: the reason when refused with one, nothing when allowed, else thrown.
- */
 async function askCaller(ports, callerID, request, call) {
     try {
+        // no save: always would answer the other requests it covers (api-notes)
         await ports.assert({
             sessionID: callerID,
             action: request.action,
@@ -67,17 +52,14 @@ async function askCaller(ports, callerID, request, call) {
         return reason;
     }
 }
-/** The reply as a proposal courier_answer passes on; anything else, `always` in particular, is refused. */
 function proposalOf(reply) {
     if (PROPOSALS.includes(reply))
         return reply;
     const always = reply === "always" ? ": courier_answer grants no standing rule; the person grants one in OpenCode's own prompt, in the asking session or the asks inbox" : "";
     throw new Error(`reply must be once or reject, not "${reply}"${always}.`);
 }
-/** Replies where the request is pending; a reply that fails leaves the request waiting, unless it no longer does. */
 async function passOn(ports, waiting, found, reply) {
     const { sessionID, requestID, decision, message } = reply;
-    // Off the waiting list first, so the reply event this answer causes does not come back as a notice.
     waiting.delete(requestID);
     try {
         await found.domain.reply({ sessionID, requestID, decision, ...(message ? { message } : {}) });
@@ -90,10 +72,6 @@ async function passOn(ports, waiting, found, reply) {
         throw new Error(`${describeFailure("permission.reply", error).message}, but ${requestID} no longer waits, so it was answered, possibly by this call.`);
     }
 }
-/**
- * Answers a permission request of a session started, directly or through others, from the caller, which must be the top
- * session, a proposed `once` only once OpenCode allowed it there; `answered` is false when no location loaded here holds it.
- */
 export async function answer(ports, waiting, callerID, input) {
     const reply = proposalOf(input.reply);
     const { sessionID, requestID } = input;
@@ -102,7 +80,6 @@ export async function answer(ports, waiting, callerID, input) {
     let refused;
     if (found && reply === "once") {
         refused = await askCaller(ports, callerID, found.request, input.call);
-        // Answered meanwhile, in the child's session or the asks inbox, while the person was asked.
         found = await locate(ports, sessionID, requestID);
     }
     if (!found) {
@@ -115,14 +92,12 @@ export async function answer(ports, waiting, callerID, input) {
         throw new Error(refusedText(sessionID, requestID, refused));
     return { sessionID, requestID, reply, answered: true };
 }
-/** The child's request a prompt of courier_answer's asks about, read from the metadata `askCaller` gives it; undefined for any other request. */
 export function passedOn(metadata) {
     const { source, asks, from, requestID } = metadata ?? {};
     if (source !== "courier" || asks !== "permission" || typeof from !== "string" || typeof requestID !== "string")
         return undefined;
     return { sessionID: from, requestID };
 }
-/** The requests a session waits on of its own, in whichever location holds them, each with the child's request it passes on when courier_answer asks it. */
 export async function ownRequests(permissions, sessionID) {
     const found = new Map();
     for (const { requests } of await listEverywhere(permissions, sessionID))
@@ -130,7 +105,6 @@ export async function ownRequests(permissions, sessionID) {
             found.set(request.id, request);
     return [...found.values()].map((request) => ({ request, passesOn: passedOn(request.metadata) }));
 }
-/** The requests a session waits on, in whichever location holds them, for courier_children. */
 export async function pendingOf(permissions, sessionID) {
     const found = new Map();
     for (const { requests } of await listEverywhere(permissions, sessionID))