opencode-courier 0.13.7 → 0.14.0

package/dist/tree/domain.d.ts

@@ -1,37 +1,23 @@
-/**
- * The tree's pure rules, on plain data: the limits, a session's lineage, whether it runs, and a group
- * member's standing. Imports nothing of the plugin's but `kernel/` and `platform/json.ts`.
- */
 import type { Plugin } from "@opencode/plugin";
 import type { Status } from "../kernel/protocol.js";
 type Context = Plugin.Context;
-/** The limits on the tree of sessions courier_spawn builds, from the plugin's options. */
 export interface Limits {
     readonly maxDepth: number;
     readonly maxChildren: number;
     readonly maxTotal: number;
 }
 export declare const DEFAULT_LIMITS: Limits;
-/** The limits in the plugin's options; one that is not a positive integer keeps its default and is named in `problems`. */
 export declare function readLimits(options: unknown): {
     limits: Limits;
     problems: string[];
 };
-/** The `nativeChildren` option: whether a child started without isolate or `native` gets OpenCode's own `parentID`; off unless `true`. */
 export declare function readNativeChildren(options: unknown): {
     nativeChildren: boolean;
     problems: string[];
 };
-/** A session's times, as `session.get` gives them. */
 type Times = Awaited<ReturnType<Context["session"]["get"]>>["time"];
-/** A session's times as `busy` reads them; `busy`, when its latest execution started, is stamped since OpenCode 2.2.2. */
 export type BusyTimes = Pick<Times, "updated" | "idle" | "busy">;
-/**
- * Whether a session may run by its times: it has never finished a turn, or its latest execution started after the last one ended
- * (`busy`; without it `updated`, which a rename, an archive or a waiting inbox item also stamp); only its transcript then tells.
- */
 export declare const busy: (time: BusyTimes) => boolean;
-/** A stored message as `turnEnd` reads it: an assistant message's `error` says how its step ended. */
 type Stored = {
     readonly type: string;
     readonly error?: {
@@ -42,50 +28,26 @@ type Stored = {
         readonly completed?: unknown;
     };
 };
-/**
- * The message a transcript's last turn ended on, unless one runs, past asides made since: an `idle` message, or a step
- * interrupted with none after it, as a declined permission or dismissed question ends a turn, recording no `idle` (#326).
- */
 export declare function turnEnd<M extends Stored>(messages: ReadonlyArray<M>): M | undefined;
 export declare const endsIdle: (messages: ReadonlyArray<Stored>) => boolean;
-/** When the turn `end` ended: the session's idle time for an `idle` message, else when its interrupted step ended. */
 export declare function endedAt(end: Stored, time: BusyTimes): number | undefined;
-/**
- * Whether a session of a tree read is live, for a cut listing's order: it runs (its turn not failed or interrupted since its last
- * prompt), waits on a request or form, or owes a report, but not, unlike for the limits, for a message waiting in its inbox.
- */
 export declare const isLive: (running: boolean | undefined, waits: number, report: {
     readonly owes: boolean;
     readonly ended: boolean;
 } | undefined) => boolean;
-/** A session of a tree read, as `cut` takes it: where it is in the tree, when it was started, and whether it is live. */
 export interface Cuttable {
     readonly sessionID: string;
     readonly parentID: string;
     readonly createdAt: number;
     readonly live: boolean;
 }
-/**
- * Which sessions a listing of at most `max` keeps, of a tree read in the order it is drawn: the live ones first, then
- * the newest, each with the sessions above it so the tree still draws; `leftOut` counts the rest.
- */
 export declare function cut<T extends Cuttable>(nodes: ReadonlyArray<T>, max: number): {
     kept: T[];
     leftOut: number;
 };
-/**
- * Entries older than this are dropped when their parent's roster is read, and on plugin setup,
- * except isolated children whose worktree is still there: those stay until courier_cleanup.
- */
 export declare const RETENTION_MS: number;
-/** Whether a directory still exists; tests pass a fake. */
 export type Exists = (directory: string) => boolean;
-/**
- * Whether an entry is past retention at `now`: recorded more than `RETENTION_MS` before, unless it is an isolated
- * child whose worktree exists, which is kept so it can still be cleaned up.
- */
 export declare const isExpired: (entry: RosterEntry, now: number, exists: Exists) => boolean;
-/** A session started with courier_spawn, recorded under the session that started it. */
 export interface RosterEntry {
     readonly sessionID: string;
     readonly parentID: string;
@@ -93,49 +55,30 @@ export interface RosterEntry {
     readonly directory: string;
     readonly isolated: boolean;
     readonly createdAt: number;
-    /** For an isolated child, the directory its worktree was made from; for the record, nothing acts on it. */
     readonly source?: string;
-    /** For an isolated child, the project its worktree belongs to; courier_cleanup removes it from there. */
     readonly project?: string;
-    /** For an isolated child, the commit its worktree was made from; its own work is what came after. */
     readonly base?: string;
-    /** `"status"` when its brief asked for a report with a status; absent for a child an earlier release briefed. */
     readonly reports?: "status";
-    /** The join group courier_spawn put it in, whose release holds its report; absent for a child in none. */
     readonly group?: string;
-    /** Created with OpenCode's own `parentID` (courier_spawn's `native`, else the `nativeChildren` option), so OpenCode shows its asks in its parent's view. */
     readonly native?: true;
-    /** The model it was started on, as `modelName` writes it, when that is not the model its parent was on. */
     readonly model?: string;
 }
-/** How a child was started, as courier_children and the panel show it: isolated, native when it is, and its model when not its parent's. */
 export declare function startedAs(entry: RosterEntry): {
     model?: string | undefined;
     native?: true | undefined;
     isolated: boolean;
 };
-/** A model as a session names it: its provider, its id, and its variant, which `"default"` and none both leave to the provider. */
 export interface ModelRef {
     readonly providerID: string;
     readonly id: string;
     readonly variant?: string;
 }
-/** `provider/model` as `courier_spawn` takes it: one slash, nothing empty on either side. */
 export declare function parseModelName(text: string): Pick<ModelRef, "providerID" | "id"> | undefined;
-/** A model as the roster, the panel and the results name it: `provider/model`, with `#variant` for a variant that is not the default. */
 export declare function modelName(model: ModelRef): string;
-/** `lineage` over roster entries already read. */
 export declare function lineageIn(entries: ReadonlyArray<RosterEntry>, sessionID: string): RosterEntry[];
-/** Roster entries by their session, for `lineageBy`. */
 export declare function bySession(entries: ReadonlyArray<RosterEntry>): Map<string, RosterEntry>;
-/** `lineage` over roster entries already read and mapped by `bySession`. */
 export declare function lineageBy(bySession: ReadonlyMap<string, RosterEntry>, sessionID: string): RosterEntry[];
-/**
- * The session whose view OpenCode shows the asks of a lineage's first session in: up its native parents, to the
- * first session that is not a native child (an isolated one, or the top). The session itself when it is not native.
- */
 export declare function nativeRootOf(chain: ReadonlyArray<RosterEntry>): string;
-/** What a report lists besides its text; `checks` are the commands the session ran and what each gave. */
 export interface Artifacts {
     readonly branch?: string;
     readonly commits?: ReadonlyArray<string>;
@@ -145,21 +88,18 @@ export interface Artifacts {
         readonly result: string;
     }>;
 }
-/** A report held with its group: its status, text and artifacts, as courier_send was given them, and when. */
 export interface HeldReport {
     readonly at: number;
     readonly status: Status;
     readonly message: string;
     readonly artifacts?: Artifacts;
 }
-/** A member of a group that left it without a report, and why: its turn failed or was interrupted, it was deleted, or courier_cleanup dropped it. */
 export interface LeftMember {
     readonly sessionID: string;
     readonly title: string;
     readonly by: "failed" | "interrupted" | "deleted" | "dropped";
 }
 export declare const isGroupName: (value: unknown) => value is string;
-/** A member of a group, as stored: its title for the release notice, and its report or how it left. */
 export interface Member {
     readonly title: string;
     readonly joinedAt: number;
@@ -169,13 +109,9 @@ export interface Member {
         readonly by: LeftMember["by"];
     };
 }
-/** What is known of a member's standing: its report is held, still out, or it left, or it is no longer in an open group. */
 export type Standing = "held" | "out" | LeftMember["by"] | "released";
-/** A member's standing from its stored value, or `released` when there is none. */
 export declare function standingOf(member: Member | undefined): Standing;
-/** Whether every member of a group has a held report or has left: released once the parent's turn has ended. */
 export declare const complete: (members: ReadonlyArray<Member>) => boolean;
-/** How long the provider asked to wait after a failed turn, if it did: a positive number of milliseconds, at most `RETRY_MAX_MS`. */
 export declare function retryDelay(error: {
     readonly retryAfterMs?: unknown;
 }): number | undefined;

package/dist/tree/domain.js

@@ -1,6 +1,5 @@
 import { millis, obj } from "../platform/json.js";
 export const DEFAULT_LIMITS = { maxDepth: 5, maxChildren: 5, maxTotal: 30 };
-/** The limits in the plugin's options; one that is not a positive integer keeps its default and is named in `problems`. */
 export function readLimits(options) {
     const given = obj(options);
     const problems = [];
@@ -16,43 +15,27 @@ export function readLimits(options) {
     const limits = { maxDepth: read("maxDepth"), maxChildren: read("maxChildren"), maxTotal: read("maxTotal") };
     return { limits, problems };
 }
-/** The `nativeChildren` option: whether a child started without isolate or `native` gets OpenCode's own `parentID`; off unless `true`. */
 export function readNativeChildren(options) {
     const value = obj(options).nativeChildren;
     if (value === undefined || typeof value === "boolean")
         return { nativeChildren: value === true, problems: [] };
     return { nativeChildren: false, problems: [`nativeChildren must be true or false, not ${JSON.stringify(value)}; using false`] };
 }
-/**
- * Whether a session may run by its times: it has never finished a turn, or its latest execution started after the last one ended
- * (`busy`; without it `updated`, which a rename, an archive or a waiting inbox item also stamp); only its transcript then tells.
- */
+// time.busy exists since 2.2.2; time.updated is no sign of activity (api-notes)
 export const busy = (time) => time.idle === undefined || millis(time.busy ?? time.updated) > millis(time.idle);
-/** The messages the person's switch of agent or model, move or shell command appends, at rest or mid-turn alike. */
+// a person's switches and shell commands append these, at rest or mid-turn
 const ASIDES = new Set(["agent-switched", "model-switched", "location-switched", "shell"]);
-/**
- * The message a transcript's last turn ended on, unless one runs, past asides made since: an `idle` message, or a step
- * interrupted with none after it, as a declined permission or dismissed question ends a turn, recording no `idle` (#326).
- */
+// a decline or dismissed question ends on an aborted step, no idle (api-notes)
 export function turnEnd(messages) {
     const last = messages.findLast((message) => !ASIDES.has(message.type));
     return last?.type === "idle" || (last?.type === "assistant" && last.error?.type === "aborted") ? last : undefined;
 }
 export const endsIdle = (messages) => turnEnd(messages) !== undefined;
-/** When the turn `end` ended: the session's idle time for an `idle` message, else when its interrupted step ended. */
 export function endedAt(end, time) {
     const at = end.type === "idle" ? millis(time.idle) : millis(end.time?.completed ?? end.time?.created);
     return Number.isFinite(at) ? at : undefined;
 }
-/**
- * Whether a session of a tree read is live, for a cut listing's order: it runs (its turn not failed or interrupted since its last
- * prompt), waits on a request or form, or owes a report, but not, unlike for the limits, for a message waiting in its inbox.
- */
 export const isLive = (running, waits, report) => running !== undefined && ((running && !report?.ended) || waits > 0 || (report?.owes ?? false));
-/**
- * Which sessions a listing of at most `max` keeps, of a tree read in the order it is drawn: the live ones first, then
- * the newest, each with the sessions above it so the tree still draws; `leftOut` counts the rest.
- */
 export function cut(nodes, max) {
     const byID = new Map(nodes.map((node) => [node.sessionID, node]));
     const ranked = nodes
@@ -70,51 +53,34 @@ export function cut(nodes, max) {
     }
     return { kept: nodes.filter((node) => kept.has(node.sessionID)), leftOut: nodes.length - kept.size };
 }
-/**
- * Entries older than this are dropped when their parent's roster is read, and on plugin setup,
- * except isolated children whose worktree is still there: those stay until courier_cleanup.
- */
 export const RETENTION_MS = 14 * 24 * 60 * 60_000;
-/**
- * Whether an entry is past retention at `now`: recorded more than `RETENTION_MS` before, unless it is an isolated
- * child whose worktree exists, which is kept so it can still be cleaned up.
- */
 export const isExpired = (entry, now, exists) => now - entry.createdAt > RETENTION_MS && !(entry.isolated && exists(entry.directory));
-/** How a child was started, as courier_children and the panel show it: isolated, native when it is, and its model when not its parent's. */
 export function startedAs(entry) {
     return { isolated: entry.isolated, ...(entry.native ? { native: true } : {}), ...(entry.model ? { model: entry.model } : {}) };
 }
-/** `provider/model` as `courier_spawn` takes it: one slash, nothing empty on either side. */
 export function parseModelName(text) {
     const slash = text.indexOf("/");
     if (slash <= 0 || slash === text.length - 1)
         return undefined;
     return { providerID: text.slice(0, slash), id: text.slice(slash + 1) };
 }
-/** A model as the roster, the panel and the results name it: `provider/model`, with `#variant` for a variant that is not the default. */
 export function modelName(model) {
     const variant = model.variant && model.variant !== "default" ? `#${model.variant}` : "";
     return `${model.providerID}/${model.id}${variant}`;
 }
-/** `lineage` over roster entries already read. */
 export function lineageIn(entries, sessionID) {
     return lineageBy(bySession(entries), sessionID);
 }
-/** Roster entries by their session, for `lineageBy`. */
 export function bySession(entries) {
     return new Map(entries.map((entry) => [entry.sessionID, entry]));
 }
-/** `lineage` over roster entries already read and mapped by `bySession`. */
 export function lineageBy(bySession, sessionID) {
     const chain = [];
     for (let entry = bySession.get(sessionID); entry && !chain.includes(entry); entry = bySession.get(entry.parentID))
         chain.push(entry);
     return chain;
 }
-/**
- * The session whose view OpenCode shows the asks of a lineage's first session in: up its native parents, to the
- * first session that is not a native child (an isolated one, or the top). The session itself when it is not native.
- */
+// OpenCode shows a native child's asks in its root's view (api-notes)
 export function nativeRootOf(chain) {
     let root = chain[0].sessionID;
     for (const entry of chain) {
@@ -124,10 +90,8 @@ export function nativeRootOf(chain) {
     }
     return root;
 }
-/** What a group may be called: short, and with no `/`, which separates the parts of its keys, or `"`, which closes an attribute. */
-const NAME = /^[\w.-]{1,60}$/;
-export const isGroupName = (value) => typeof value === "string" && NAME.test(value);
-/** A member's standing from its stored value, or `released` when there is none. */
+const GROUP_NAME = /^[\w.-]{1,60}$/;
+export const isGroupName = (value) => typeof value === "string" && GROUP_NAME.test(value);
 export function standingOf(member) {
     if (!member)
         return "released";
@@ -135,11 +99,9 @@ export function standingOf(member) {
         return "held";
     return member.left?.by ?? "out";
 }
-/** Whether every member of a group has a held report or has left: released once the parent's turn has ended. */
 export const complete = (members) => members.every((member) => member.report || member.left);
-/** Longer than this is no wait a notice can plan around; OpenCode clamps a header to 2^53 ms, past what a `Date` holds. */
+// OpenCode clamps retry-after to 2^53 ms, past what a Date holds
 const RETRY_MAX_MS = 30 * 24 * 3_600_000;
-/** How long the provider asked to wait after a failed turn, if it did: a positive number of milliseconds, at most `RETRY_MAX_MS`. */
 export function retryDelay(error) {
     const wait = error.retryAfterMs;
     return typeof wait === "number" && Number.isFinite(wait) && wait > 0 && wait <= RETRY_MAX_MS ? wait : undefined;

package/dist/tree/events.d.ts

@@ -1,16 +1,13 @@
 import type { EventModule } from "../platform/events.js";
 import type { ExecutionError, Waits, WatchPorts, WatchState } from "./ports.js";
-/** The part of OpenCode's `session.execution.failed` event the notice is made from. */
 export interface ExecutionFailed {
     readonly id: string;
-    /** When OpenCode published it, in epoch milliseconds. */
     readonly created?: number;
     readonly data: {
         readonly sessionID: string;
         readonly error: ExecutionError;
     };
 }
-/** OpenCode's events that concern one session's turns and inbox: `session.execution.succeeded` and the like. */
 export interface SessionEvent {
     readonly id: string;
     readonly created?: number;
@@ -19,12 +16,7 @@ export interface SessionEvent {
         readonly reason?: string;
     };
 }
-/**
- * Tells the parent of a child whose turn failed, since a child that cannot reach its model cannot
- * call courier_send. Returns the parents told.
- */
 export declare function reportFailure(ports: WatchPorts, seen: Set<string>, event: ExecutionFailed): Promise<string[]>;
-/** OpenCode's `session.inbox.enqueued`: the item's type, which its `session.inbox.delivered` does not carry. */
 export interface InboxEnqueued {
     readonly data: {
         readonly sessionID: string;
@@ -34,43 +26,15 @@ export interface InboxEnqueued {
         };
     };
 }
-/** Remembers the type of an item enqueued for a spawned session, for `notePrompt`; other sessions cost one read. */
 export declare function noteEnqueued(ports: WatchPorts, inbox: Map<string, string>, event: InboxEnqueued): Promise<boolean>;
-/**
- * Notes that a message reached a spawned session, which then owes its parent a report, unless `inbox` knows it for one of
- * `UNOWED` (`spawn` notes the task itself); reads the reverse index alone, and claims nothing: the note is the same twice.
- */
 export declare function notePrompt(ports: WatchPorts, event: SessionEvent & {
     readonly data: {
         readonly inboxID?: string;
     };
 }, inbox?: Map<string, string>): Promise<boolean>;
-/**
- * Notes that a spawned session's turn was stopped, which takes it out of its group without a report; a
- * shutdown's is left to `reportDeclined`, as one stopped between steps resumes on the next start.
- */
 export declare function noteInterrupted(ports: WatchPorts, event: SessionEvent): Promise<boolean>;
-/**
- * Forgets what a deleted session leaves (report state, groups) and, unless isolated or a parent on the roster, its
- * entry. Returns the sessions forgotten.
- */
 export declare function noteDeleted(ports: WatchPorts, event: SessionEvent): Promise<string[]>;
-/** A `Waits` asking `suppliers` one after another, cheapest first: the first that waits answers. */
 export declare const waitsOn: (...suppliers: Waits[]) => Waits;
-/** A `Waits` asking `suppliers` at once, as cheap as each other: it waits when one does, and fails when one fails. */
-export declare const together: (...suppliers: Waits[]) => Waits;
-/**
- * Tells the parent of a spawned session whose turn ended without reporting to it since its last
- * prompt, unless it waits; finds the session by the reverse index alone. Returns the parents told.
- */
 export declare function reportSilent(ports: WatchPorts, seen: Set<string>, event: SessionEvent, outside: Waits): Promise<string[]>;
-/**
- * A session's turn that OpenCode reports as a shutdown ended in a plain decline, if its transcript ends on an aborted step: its
- * parent is told as for a turn that succeeded without a report. A real shutdown during a step reads the same, and is told too.
- */
 export declare function reportDeclined(ports: WatchPorts, seen: Set<string>, event: SessionEvent, outside: Waits): Promise<string[]>;
-/**
- * Tells parents of a child's failed or silent turn, unless it waits on what `outside` says, and notes
- * its prompts, interruptions and deletion; `after` a turn's end, seals the groups of its session.
- */
 export declare function treeEvents(state: WatchState, outside: Waits): EventModule<WatchPorts>;

package/dist/tree/events.js

@@ -10,10 +10,6 @@ import { childStore, groupStore } from "./store.js";
 import { lastReply } from "./status.js";
 import { failureNotice, silentNotice } from "./text.js";
 import { forgetWakes, settleWake, wakeEnded, wakeStarted, watchWake } from "./wake.js";
-/**
- * Tells the parent of a child whose turn failed, since a child that cannot reach its model cannot
- * call courier_send. Returns the parents told.
- */
 export async function reportFailure(ports, seen, event) {
     if (!claim(seen, event.id))
         return [];
@@ -22,14 +18,10 @@ export async function reportFailure(ports, seen, event) {
     const entries = await children.entriesOf(sessionID);
     const at = event.created ?? ports.now();
     const wait = retryDelay(error);
-    // Not in the way of the notice: kept only so the limits stop counting the child, and the panel can say when its limit lifts.
     if (entries.length)
         await children.settled(sessionID, "failed", at, undefined, wait === undefined ? undefined : at + wait).catch((error) => ports.log(`courier watch: could not note the failed turn of ${sessionID}: ${String(error)}`));
     const out = await Promise.all(entries.map((entry) => outIn(ports, entry)));
-    // Left before the notice, so the parent waits on the group meanwhile; nudged after it, so the group's
-    // message does not overtake the notice, short of an interval tick falling in between.
     const completed = await Promise.all(out.map((member) => (member ? leave(ports, member, "failed", at) : Promise.resolve(false))));
-    // A session courier_stop stopped is not a failure to tell: its parent was told of the stop, or ordered it.
     const quiet = entries.length > 0 && (await stoppedSincePrompt(children, sessionID).catch(() => false));
     try {
         if (quiet)
@@ -49,9 +41,8 @@ export async function reportFailure(ports, seen, event) {
     }
     return entries.map((entry) => entry.parentID);
 }
-/** Inbox items that are not courier's or the parent's business: the person's own prompts, compactions and moves. */
+// only inbox.enqueued carries the item's type (api-notes)
 const UNOWED = new Set(["user", "compaction", "move"]);
-/** Remembers the type of an item enqueued for a spawned session, for `notePrompt`; other sessions cost one read. */
 export async function noteEnqueued(ports, inbox, event) {
     const { sessionID, inboxID, item } = event.data;
     if ((await childStore(ports.storage).indexedParent(sessionID)) === undefined)
@@ -59,30 +50,21 @@ export async function noteEnqueued(ports, inbox, event) {
     setBounded(inbox, inboxID, item.type, SEEN_MAX);
     return true;
 }
-/**
- * Notes that a message reached a spawned session, which then owes its parent a report, unless `inbox` knows it for one of
- * `UNOWED` (`spawn` notes the task itself); reads the reverse index alone, and claims nothing: the note is the same twice.
- */
 export async function notePrompt(ports, event, inbox) {
     const { sessionID, inboxID } = event.data;
-    // Kept, not deleted: the hub's other subscription looks it up for the same delivery.
     if (inboxID !== undefined && UNOWED.has(inbox?.get(inboxID) ?? ""))
         return false;
     const children = childStore(ports.storage);
     const parentID = await children.indexedParent(sessionID);
     if (parentID === undefined)
         return false;
-    // The reminder to report is not a prompt: it asks for the report the last one owes.
+    // the idle hook's reminder still publishes inbox.delivered (api-notes)
     if (inboxID !== undefined && (await children.nudgeOf(sessionID)).inboxID === inboxID)
         return false;
     await children.prompted(sessionID, event.created ?? ports.now());
     await syncStanding(ports, parentID);
     return true;
 }
-/**
- * Notes that a spawned session's turn was stopped, which takes it out of its group without a report; a
- * shutdown's is left to `reportDeclined`, as one stopped between steps resumes on the next start.
- */
 export async function noteInterrupted(ports, event) {
     if (event.data.reason === "shutdown")
         return false;
@@ -99,10 +81,6 @@ export async function noteInterrupted(ports, event) {
     await syncStanding(ports, entry.parentID);
     return true;
 }
-/**
- * Forgets what a deleted session leaves (report state, groups) and, unless isolated or a parent on the roster, its
- * entry. Returns the sessions forgotten.
- */
 export async function noteDeleted(ports, event) {
     const { sessionID } = event.data;
     const children = childStore(ports.storage);
@@ -117,33 +95,23 @@ export async function noteDeleted(ports, event) {
         await syncStanding(ports, parentID);
     return forgotten;
 }
-/** A `Waits` asking `suppliers` one after another, cheapest first: the first that waits answers. */
 export const waitsOn = (...suppliers) => async (ports, sessionID, since) => {
     for (const supplier of suppliers)
         if (await supplier(ports, sessionID, since))
             return true;
     return false;
 };
-/** A `Waits` asking `suppliers` at once, as cheap as each other: it waits when one does, and fails when one fails. */
-export const together = (...suppliers) => async (ports, sessionID, since) => (await Promise.all(suppliers.map((supplier) => supplier(ports, sessionID, since)))).includes(true);
-/**
- * Tells the parent of a spawned session whose turn ended without reporting to it since its last
- * prompt, unless it waits; finds the session by the reverse index alone. Returns the parents told.
- */
 export async function reportSilent(ports, seen, event, outside) {
     const { sessionID } = event.data;
     const children = childStore(ports.storage);
     const entry = await children.indexedEntry(sessionID);
-    // Claimed after the lookup, so other sessions' turns do not crowd `seen`, and before anything is told.
     if (!entry || !claim(seen, event.id))
         return [];
     const report = await owedUnwaited(ports, children, outside, sessionID);
     if (!report)
         return [];
-    // The notice goes out without the reply rather than not at all.
     const lastText = await ports.session.context({ sessionID }).then(lastReply, () => undefined);
     const group = (await outIn(ports, entry))?.group;
-    // Before the notice, which may end the parent's turn at once: once told, it no longer waits for this one.
     const toldAt = event.created ?? ports.now();
     await children.told(sessionID, toldAt).catch((error) => ports.log(`courier watch: could not note that the parent of ${sessionID} was told: ${String(error)}`));
     try {
@@ -156,17 +124,13 @@ export async function reportSilent(ports, seen, event, outside) {
         });
     }
     catch (error) {
-        // Not told after all: the parent still waits for it.
         await children.untold(sessionID, toldAt).catch(() => undefined);
         throw error;
     }
     await syncStanding(ports, entry.parentID);
     return [entry.parentID];
 }
-/**
- * A session's turn that OpenCode reports as a shutdown ended in a plain decline, if its transcript ends on an aborted step: its
- * parent is told as for a turn that succeeded without a report. A real shutdown during a step reads the same, and is told too.
- */
+// a plain decline ends as a shutdown, on an aborted step (api-notes)
 export async function reportDeclined(ports, seen, event, outside) {
     if (event.data.reason !== "shutdown" || (await childStore(ports.storage).indexedParent(event.data.sessionID)) === undefined)
         return [];
@@ -175,7 +139,6 @@ export async function reportDeclined(ports, seen, event, outside) {
     return reportSilent(ports, seen, event, outside);
 }
 const TURN_ENDS = new Set(["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"]);
-/** What `route` and `after` dispatch on; the wake watch needs `inbox.enqueued` and `execution.started` both. */
 const TREE_TYPES = [
     "session.execution.started",
     "session.execution.succeeded",
@@ -186,8 +149,8 @@ const TREE_TYPES = [
     "session.inbox.cancelled",
     "session.deleted",
 ];
-/** A session's turn ended, sealing its groups: one that is complete has the scheduler deliver it now; not a shutdown's, which stamps no idle time. */
 async function sealGroups(ports, event) {
+    // a shutdown stamps no time.idle (api-notes)
     if (event.data.reason === "shutdown")
         return;
     try {
@@ -198,7 +161,6 @@ async function sealGroups(ports, event) {
         ports.log(`courier watch: could not read the groups of ${event.data.sessionID}: ${String(error)}`);
     }
 }
-/** The events of spawned sessions' turns and inboxes, and their deletion: the tree's. */
 function routeTree(ports, state, outside, event) {
     if (event.type === "session.execution.failed")
         return reportFailure(ports, state.seen, event);
@@ -216,7 +178,6 @@ function routeTree(ports, state, outside, event) {
         return noteDeleted(ports, event);
     return undefined;
 }
-/** The events that move a courier message waiting in a session's inbox: enqueued, taken, cancelled, and the turns around it. */
 function routeWake(ports, event) {
     if (event.type === "session.inbox.enqueued")
         return watchWake(ports, event);
@@ -230,7 +191,6 @@ function routeWake(ports, event) {
         return forgetWakes(ports, event.data.sessionID);
     return undefined;
 }
-/** The tree's handling of an event alongside the wake watch's, which touches other keys and never fails the tree's. */
 async function route(ports, state, outside, event) {
     const watched = routeWake(ports, event)?.catch((error) => ports.log(`courier watch: wake of ${event.type}: ${String(error)}`));
     try {
@@ -240,15 +200,10 @@ async function route(ports, state, outside, event) {
         await watched;
     }
 }
-/**
- * Tells parents of a child's failed or silent turn, unless it waits on what `outside` says, and notes
- * its prompts, interruptions and deletion; `after` a turn's end, seals the groups of its session.
- */
 export function treeEvents(state, outside) {
     return {
         types: TREE_TYPES,
         handle: (ports, event) => route(ports, state, outside, event),
-        // After: a silent end is judged while the group the nudge may deliver is still there to wait on.
         after: (ports, event) => (TURN_ENDS.has(event.type) ? sealGroups(ports, event) : undefined),
     };
 }

package/dist/tree/forget.d.ts

@@ -1,24 +1,9 @@
 import type { CleanupPorts, GroupStore, Membership, ReportKeys, RosterEntry, RosterStorage, WatchPorts } from "./ports.js";
-/** Drops a member from its group as its roster entry goes, unless its report is held: that still goes to the parent. True when dropped. */
 export declare function dropMember(groups: GroupStore, parentID: string, group: string, sessionID: string): Promise<boolean>;
-/** Drops every group of a parent, whose members' reports can no longer be delivered. */
 export declare function dropGroups(groups: GroupStore, parentID: string): Promise<void>;
-/**
- * Forgets a child: its roster entry, its reverse key, its report state and, given its group, its membership. Only
- * the entry's removal can fail it: keys left behind lead nowhere, and the next load drops them.
- */
 export declare function forgetChild(storage: RosterStorage, parentID: string, sessionID: string, group?: string): Promise<{
     droppedFromGroup: boolean;
 }>;
-/**
- * Drops a member still out from its group as `dropped`, so the group is released without it, then the roster entry
- * and report state. A held report stays with its group. Returns the group it was dropped from.
- */
 export declare function forgetDropped(ports: Pick<CleanupPorts, "storage" | "now" | "nudge">, entry: RosterEntry): Promise<string | undefined>;
-/**
- * Forgets what a session OpenCode deleted leaves: the report state of `forgotten`, itself and the sessions it started,
- * and its groups; `member`, its place in its own group, it leaves at `created`, or now.
- */
 export declare function forgetDeleted(ports: WatchPorts, sessionID: string, forgotten: ReadonlyArray<string>, member: Membership | undefined, created?: number): Promise<void>;
-/** Removes report keys of sessions with no roster entry; a key that will not go is left for the next load. */
 export declare function forgetReports(storage: RosterStorage, keys: ReportKeys, sessions: ReadonlyArray<string>): Promise<void>;

package/dist/tree/forget.js

@@ -1,8 +1,5 @@
 import { leave, markLeft, membershipFor } from "./group.js";
 import { childStore, groupStore } from "./store.js";
-// Forgetting a child and what it leaves behind. Its roster entry and report state go together; its group is another
-// aggregate, left best effort and alongside, so a report held there outlives the entry and still reaches the parent.
-/** Drops a member from its group as its roster entry goes, unless its report is held: that still goes to the parent. True when dropped. */
 export async function dropMember(groups, parentID, group, sessionID) {
     const member = await groups.member(parentID, group, sessionID);
     if (!member || member.report)
@@ -10,15 +7,10 @@ export async function dropMember(groups, parentID, group, sessionID) {
     await groups.remove(parentID, group, sessionID);
     return true;
 }
-/** Drops every group of a parent, whose members' reports can no longer be delivered. */
 export async function dropGroups(groups, parentID) {
     const members = await groups.ofParent(parentID);
     await Promise.all(members.map((member) => groups.remove(parentID, member.group, member.sessionID)));
 }
-/**
- * Forgets a child: its roster entry, its reverse key, its report state and, given its group, its membership. Only
- * the entry's removal can fail it: keys left behind lead nowhere, and the next load drops them.
- */
 export async function forgetChild(storage, parentID, sessionID, group) {
     const [, dropped] = await Promise.all([
         childStore(storage).remove(parentID, sessionID),
@@ -26,10 +18,6 @@ export async function forgetChild(storage, parentID, sessionID, group) {
     ]);
     return { droppedFromGroup: dropped };
 }
-/**
- * Drops a member still out from its group as `dropped`, so the group is released without it, then the roster entry
- * and report state. A held report stays with its group. Returns the group it was dropped from.
- */
 export async function forgetDropped(ports, entry) {
     const groups = groupStore(ports.storage);
     const member = await membershipFor(groups, entry);
@@ -38,13 +26,8 @@ export async function forgetDropped(ports, entry) {
     await forgetChild(ports.storage, entry.parentID, entry.sessionID);
     return member?.out ? member.group : undefined;
 }
-/**
- * Forgets what a session OpenCode deleted leaves: the report state of `forgotten`, itself and the sessions it started,
- * and its groups; `member`, its place in its own group, it leaves at `created`, or now.
- */
 export async function forgetDeleted(ports, sessionID, forgotten, member, created) {
     const children = childStore(ports.storage);
-    // Its groups go whether or not it has children on the roster: a held report outlives the member's entry.
     const [completed] = await Promise.all([
         member ? leave(ports, member, "deleted", created ?? ports.now()) : Promise.resolve(false),
         ...forgotten.map((id) => children.forgetReport(id)),
@@ -53,7 +36,6 @@ export async function forgetDeleted(ports, sessionID, forgotten, member, created
     if (completed)
         ports.nudge();
 }
-/** Removes report keys of sessions with no roster entry; a key that will not go is left for the next load. */
 export async function forgetReports(storage, keys, sessions) {
     await childStore(storage).dropReported(sessions.flatMap((sessionID) => keys.get(sessionID) ?? []));
 }