opencode-courier 0.13.8 → 0.15.0

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,58 +16,30 @@ 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;
         readonly inboxID: string;
         readonly item: {
             readonly type: string;
+            readonly payload?: {
+                readonly metadata?: {
+                    readonly [key: string]: unknown;
+                };
+            };
         };
     };
 }
-/** 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

@@ -3,17 +3,14 @@ import { claim, SEEN_MAX, setBounded } from "../platform/bounded.js";
 import { endsIdle, retryDelay } from "./domain.js";
 import { forgetChild, forgetDeleted } from "./forget.js";
 import { hasCompleteGroup, leave, outIn } from "./group.js";
+import { liveBelow } from "./limits.js";
 import { owedUnwaited } from "./nudge.js";
-import { stoppedSincePrompt } from "./report.js";
+import { reportedSincePrompt, stoppedSincePrompt } from "./report.js";
 import { syncStanding } from "./standing.js";
 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,21 +19,21 @@ 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)
             return [];
+        const below = await liveBelow(ports, sessionID).then((live) => live.map((entry) => entry.title), (error) => {
+            ports.log(`courier watch: could not read the sessions under ${sessionID}: ${String(error)}`);
+            return [];
+        });
         await Promise.all(entries.map((entry, index) => ports.session.synthetic({
             sessionID: entry.parentID,
-            text: envelope(sessionID, failureNotice(entry.title, error, out[index]?.group, at), { failed: error.type }),
+            text: envelope(sessionID, failureNotice(entry.title, error, out[index]?.group, at, below), { failed: error.type }),
             description: `Session ${sessionID} failed`,
             metadata: { source: "courier", from: sessionID, failed: true },
             delivery: "steer",
@@ -49,40 +46,38 @@ 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. */
+const GROUP = "group";
+function kindOf(item) {
+    const metadata = item.payload?.metadata;
+    return item.type === "synthetic" && metadata?.source === "courier" && typeof metadata.group === "string" ? GROUP : item.type;
+}
 export async function noteEnqueued(ports, inbox, event) {
     const { sessionID, inboxID, item } = event.data;
     if ((await childStore(ports.storage).indexedParent(sessionID)) === undefined)
         return false;
-    setBounded(inbox, inboxID, item.type, SEEN_MAX);
+    setBounded(inbox, inboxID, kindOf(item), 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) ?? ""))
+    const kind = inboxID === undefined ? undefined : inbox?.get(inboxID);
+    if (UNOWED.has(kind ?? ""))
         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.
+    if (kind === GROUP && (await reportedSincePrompt(children, sessionID)))
+        return false;
+    // 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 +94,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 +108,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 +137,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 +152,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,11 +162,11 @@ 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) {
-    if (event.data.reason === "shutdown")
-        return;
     try {
+        // a shutdown ends a turn only on a plain decline's aborted step (api-notes)
+        if (event.data.reason === "shutdown" && !endsIdle(await ports.session.context({ sessionID: event.data.sessionID }).catch(() => [])))
+            return;
         if (await hasCompleteGroup(groupStore(ports.storage), event.data.sessionID))
             ports.nudge();
     }
@@ -198,7 +174,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 +191,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 +204,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 +213,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) ?? []));
 }

package/dist/tree/group.d.ts

@@ -1,25 +1,19 @@
 import { type HeldReport, type LeftMember, type RosterEntry } from "./domain.js";
 import type { GroupPorts, GroupStore, Membership, WatchPorts } from "./ports.js";
-/** Makes a spawned session a member of its parent's group, opening the group if it was not. */
 export declare function joinGroup(groups: GroupStore, parentID: string, group: string, sessionID: string, title: string, at: number): Promise<void>;
-/** Whether a parent has a complete group with a report in it, which the scheduler delivers once the parent's turn has ended. */
 export declare function hasCompleteGroup(groups: GroupStore, parentID: string): Promise<boolean>;
-/** Holds a member's report with its group, in place of an earlier one, or of how it had left. */
 export declare function holdReport(groups: GroupStore, membership: Membership, report: HeldReport): Promise<void>;
-/** How many members of a group have reported and how many have not left, and whether the group is complete. */
 export declare function groupStanding(groups: GroupStore, parentID: string, group: string): Promise<{
     reported: number;
     members: number;
     complete: boolean;
 }>;
-/** `groupStanding` of each open group of a parent, by name, from one read of its members. */
 export declare function groupStandings(groups: Pick<GroupStore, "ofParent">, parentID: string): Promise<{
     reported: number;
     members: number;
     complete: boolean;
     name: string;
 }[]>;
-/** A session's membership of a parent's group, if it is a member; `out` says whether the group still waits for its report. */
 export declare function membershipOf(groups: Pick<GroupStore, "member">, parentID: string, group: string, sessionID: string): Promise<{
     parentID: string;
     group: string;
@@ -33,7 +27,6 @@ export declare function membershipOf(groups: Pick<GroupStore, "member">, parentI
         readonly by: LeftMember["by"];
     };
 } | undefined>;
-/** A child's membership of the group its roster entry names; none without one. A failed read is the caller's to handle. */
 export declare function membershipFor(groups: Pick<GroupStore, "member">, entry: RosterEntry): Promise<{
     parentID: string;
     group: string;
@@ -47,14 +40,8 @@ export declare function membershipFor(groups: Pick<GroupStore, "member">, entry:
         readonly by: LeftMember["by"];
     };
 } | undefined>;
-/**
- * Notes that a member left its group without a report: its turn failed or was interrupted, it was deleted or dropped. Read
- * again first: one whose report is held meanwhile keeps it, one that left keeps why. True when that completes the group.
- */
 export declare function markLeft(groups: GroupStore, membership: Membership, by: LeftMember["by"], at: number): Promise<boolean>;
-/** `markLeft` for a member not read yet; undefined when it is in no open group. */
 export declare function leaveGroup(groups: GroupStore, parentID: string, group: string, sessionID: string, by: LeftMember["by"], at: number): Promise<boolean | undefined>;
-/** A child's membership of an open group it is still out in: the group waits for it, and its end takes it out without a report. */
 export declare function outIn(ports: Pick<WatchPorts, "storage" | "log">, entry: RosterEntry): Promise<{
     parentID: string;
     group: string;
@@ -68,15 +55,6 @@ export declare function outIn(ports: Pick<WatchPorts, "storage" | "log">, entry:
         readonly by: LeftMember["by"];
     };
 } | undefined>;
-/** Takes a member out of its group without a report; true when that completes the group, for the caller to nudge the scheduler. */
 export declare function leave(ports: Pick<WatchPorts, "storage" | "log">, member: Membership, by: "failed" | "interrupted" | "deleted", at: number): Promise<boolean>;
-/**
- * Puts a member whose report is held back among those out: its latest word to the parent was a blocked report. Read
- * again first: a group released meanwhile is not opened again, and a report held since is kept.
- */
 export declare function unholdForBlocked(groups: GroupStore, membership: Membership): Promise<void>;
-/**
- * Delivers every released group once, from the scheduler's tick: claimed in the shared `claimed`, re-read,
- * delivered and only then dropped, so a failed delivery is tried again at the next tick, and a crash in between delivers it again.
- */
 export declare function deliverReleased(ports: GroupPorts, claimed: Set<string>): Promise<void>;