opencode-courier 0.13.7 → 0.14.0

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>;

package/dist/tree/group.js

@@ -4,11 +4,9 @@ import { complete, standingOf } from "./domain.js";
 import { syncStanding } from "./standing.js";
 import { groupStore } from "./store.js";
 import { groupNotice } from "./text.js";
-/** Makes a spawned session a member of its parent's group, opening the group if it was not. */
 export async function joinGroup(groups, parentID, group, sessionID, title, at) {
     await groups.put(parentID, group, sessionID, { title, joinedAt: at });
 }
-/** The members of each group among `members`, by the claim key of the group. */
 function byGroup(members) {
     const groups = new Map();
     for (const member of members) {
@@ -21,45 +19,34 @@ function byGroup(members) {
     }
     return groups;
 }
-/** Whether a parent has a complete group with a report in it, which the scheduler delivers once the parent's turn has ended. */
 export async function hasCompleteGroup(groups, parentID) {
     return [...byGroup(await groups.ofParent(parentID)).values()].some((members) => complete(members) && members.some((member) => member.report));
 }
-/** Holds a member's report with its group, in place of an earlier one, or of how it had left. */
 export async function holdReport(groups, membership, report) {
     const { parentID, group, sessionID, title, joinedAt } = membership;
     await groups.put(parentID, group, sessionID, { title, joinedAt, report });
 }
-/** How many of these members of a group have reported and how many have not left, and whether the group is complete. */
 const tally = (members) => ({
     reported: members.filter((member) => member.report).length,
     members: members.filter((member) => !member.left).length,
     complete: complete(members),
 });
-/** How many members of a group have reported and how many have not left, and whether the group is complete. */
 export async function groupStanding(groups, parentID, group) {
     return tally(await groups.ofGroup(parentID, group));
 }
-/** `groupStanding` of each open group of a parent, by name, from one read of its members. */
 export async function groupStandings(groups, parentID) {
     const byName = new Map();
     for (const member of await groups.ofParent(parentID))
         byName.set(member.group, [...(byName.get(member.group) ?? []), member]);
     return [...byName].map(([name, members]) => ({ name, ...tally(members) }));
 }
-/** 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 async function membershipOf(groups, parentID, group, sessionID) {
     const member = await groups.member(parentID, group, sessionID);
     return member && { ...member, parentID, group, sessionID, out: standingOf(member) === "out" };
 }
-/** A child's membership of the group its roster entry names; none without one. A failed read is the caller's to handle. */
 export async function membershipFor(groups, entry) {
     return entry.group ? membershipOf(groups, entry.parentID, entry.group, entry.sessionID) : 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 async function markLeft(groups, membership, by, at) {
     const { parentID, group, sessionID } = membership;
     const current = await groups.member(parentID, group, sessionID);
@@ -68,12 +55,10 @@ export async function markLeft(groups, membership, by, at) {
     await groups.put(parentID, group, sessionID, { title: current.title, joinedAt: current.joinedAt, left: { at, by } });
     return (await groupStanding(groups, parentID, group)).complete;
 }
-/** `markLeft` for a member not read yet; undefined when it is in no open group. */
 export async function leaveGroup(groups, parentID, group, sessionID, by, at) {
     const membership = await membershipOf(groups, parentID, group, sessionID);
     return membership && (await markLeft(groups, membership, by, at));
 }
-/** 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 async function outIn(ports, entry) {
     try {
         const member = await membershipFor(groupStore(ports.storage), entry);
@@ -84,7 +69,6 @@ export async function outIn(ports, entry) {
         return 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 async function leave(ports, member, by, at) {
     try {
         return await markLeft(groupStore(ports.storage), member, by, at);
@@ -94,10 +78,6 @@ export async function leave(ports, member, by, at) {
         return false;
     }
 }
-/**
- * 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 async function unholdForBlocked(groups, membership) {
     const { parentID, group, sessionID, title, joinedAt } = membership;
     if (!membership.report)
@@ -107,15 +87,9 @@ export async function unholdForBlocked(groups, membership) {
         return;
     await groups.put(parentID, group, sessionID, { title, joinedAt });
 }
-/** The claim key of a group's release, in the hub's shared set of deliveries under way. */
 const claimKey = (parentID, group) => `group:${parentID}/${group}`;
-/**
- * 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 async function deliverReleased(ports, claimed) {
     const groups = [...byGroup(await groupStore(ports.storage).all())].filter(([key, members]) => complete(members) && !claimed.has(key));
-    // Claimed all at once, before any delivery, so a tick alongside claims none of these.
     for (const [key] of groups)
         claimed.add(key);
     await Promise.all(groups.map(([key, members]) => releaseClaimed(ports, claimed, key, members[0])));
@@ -131,15 +105,11 @@ async function releaseClaimed(ports, claimed, key, { parentID, group }) {
         claimed.delete(key);
     }
 }
-/**
- * Whether the parent's turn that started a group's last member has ended, so no more join it; `gone` when OpenCode no longer knows the
- * parent. Only a turn ending stamps `time.idle`: a shutdown, or a plain permission decline reported as one, holds it until the next ends.
- */
 async function sealed(ports, parentID, members) {
     const joined = Math.max(...members.map((member) => member.joinedAt));
     try {
         const { time } = await ports.session.get({ sessionID: parentID });
-        // NaN, for a parent that has ended no turn yet, holds it.
+        // only a turn's end stamps time.idle, not a shutdown (api-notes)
         return millis(time.idle) >= joined;
     }
     catch (error) {
@@ -149,7 +119,6 @@ async function sealed(ports, parentID, members) {
     }
 }
 async function release(ports, parentID, group) {
-    // Re-read: another server may have delivered and dropped it since the scan.
     const members = (await groupStore(ports.storage).ofGroup(parentID, group)).sort((a, b) => a.joinedAt - b.joinedAt);
     if (!members.length || !complete(members))
         return;
@@ -174,7 +143,6 @@ async function release(ports, parentID, group) {
             });
         }
         catch (error) {
-            // A parent OpenCode no longer knows will never take it: dropped, like the children of a deleted session.
             if (!isNotFound(error)) {
                 ports.log(`courier group ${group} of ${parentID} not delivered, held for another try: ${String(error)}`);
                 return;
@@ -183,21 +151,17 @@ async function release(ports, parentID, group) {
         }
     }
     await drop(ports, parentID, group, members);
-    // Delivered: the members read as released in the parent's standing, which its next step shows.
     await syncStanding(ports, parentID);
 }
-/** Drops a group's members once delivered, or unsent, saying why. */
 async function drop(ports, parentID, group, members, unsent) {
     if (unsent)
         ports.log(`courier group ${group} of ${parentID} dropped: ${unsent}`);
-    // A member left behind here is delivered again at the next tick, as after a crash: logged, so it can be seen.
     const groups = groupStore(ports.storage);
     const dropped = await Promise.allSettled(members.map((member) => dropDelivered(groups, member)));
     for (const [index, result] of dropped.entries())
         if (result.status === "rejected")
             ports.log(`courier group ${group} of ${parentID}: delivered, but ${members[index].sessionID} could not be dropped: ${String(result.reason)}`);
 }
-/** Drops a delivered member's key, unless it was written again since it was read: that report is still to deliver. */
 async function dropDelivered(groups, delivered) {
     const { parentID, group, sessionID, ...read } = delivered;
     if (JSON.stringify(await groups.member(parentID, group, sessionID)) !== JSON.stringify(read))

package/dist/tree/index.d.ts

@@ -1,11 +1,11 @@
 export { dirtyOf, headOf, inspectWorktree } from "./cleanup.js";
 export { shapeContext } from "./context.js";
 export { endsIdle, lineageIn, nativeRootOf, readLimits, readNativeChildren } from "./domain.js";
-export { together, treeEvents, waitsOn } from "./events.js";
+export { treeEvents, waitsOn } from "./events.js";
 export { deliverReleased } from "./group.js";
 export { onIdle } from "./nudge.js";
 export { contextOf } from "./panel.js";
-export type { CleanupPorts, CourierPorts, Entries, Entry, Instructions, ModelWindow, Pending, PendingPrompt, Role, RosterEntry, RosterStorage, ShownForm, SpawnGate, Waits, WatchPorts, WatchState, } from "./ports.js";
+export type { CleanupPorts, CourierPorts, Entries, Entry, Instructions, Lister, ModelWindow, Pending, PendingPrompt, Role, RosterEntry, RosterStorage, ShownForm, SpawnGate, Waits, WatchPorts, WatchState, } from "./ports.js";
 export { allEntries, answeringTop, childrenOf, indexedLineage, lineage, pruneExpired, reportState, RETENTION_MS, type ReportState } from "./roster.js";
 export { runs, turnIn, turnOf, type Turn } from "./running.js";
 export { subtree, type Below } from "./subtree.js";

package/dist/tree/index.js

@@ -1,9 +1,7 @@
-// What the rest of the plugin uses of the session tree: its tools, RPC, event module, context hook and tick jobs
-// for `src/index.ts`, the lineage and subtree queries and types `person/` reads, and what `memory/` reads of each session.
 export { dirtyOf, headOf, inspectWorktree } from "./cleanup.js";
 export { shapeContext } from "./context.js";
 export { endsIdle, lineageIn, nativeRootOf, readLimits, readNativeChildren } from "./domain.js";
-export { together, treeEvents, waitsOn } from "./events.js";
+export { treeEvents, waitsOn } from "./events.js";
 export { deliverReleased } from "./group.js";
 export { onIdle } from "./nudge.js";
 export { contextOf } from "./panel.js";

package/dist/tree/limits.d.ts

@@ -1,8 +1,4 @@
 import type { LimitPorts, Reservation } from "./ports.js";
-/**
- * Checks the limits for a spawn from `parentID`, then holds its place in `gate` until `release`;
- * throws a refusal naming the limit. Checks run one at a time, so spawns made together count each other.
- */
 export declare function admit(ports: LimitPorts, parentID: string): Promise<{
     depth: number;
     reservation: Reservation;

package/dist/tree/limits.js

@@ -5,10 +5,6 @@ import { runs } from "./running.js";
 import { childStore } from "./store.js";
 import { childrenRefusal, depthRefusal, totalRefusal } from "./text.js";
 import { waitsInInbox } from "./wake.js";
-/**
- * Whether a spawned session counts against the limits: it runs (its turn not failed or interrupted since its last prompt), owes
- * its parent a report, or has a courier message waiting in its inbox that it is to be woken for. One OpenCode no longer knows does not.
- */
 async function live(ports, sessionID) {
     const [time, report] = await Promise.all([
         ports.session.get({ sessionID }).then((info) => info.time, (error) => (isNotFound(error) ? null : undefined)),
@@ -16,15 +12,10 @@ async function live(ports, sessionID) {
     ]);
     if (time === null)
         return false;
-    // One whose first prompt failed never ran, and has no idle time to tell so.
     const running = time !== undefined && !report?.ended && (await runs(ports.session, sessionID, time));
-    // A waiting message is in no transcript until delivered, so `runs` misses it; a stalled one, which nothing wakes it for, is not counted.
+    // a waiting inbox item is in no transcript until delivered (api-notes)
     return running || (report?.owes ?? false) || (await waitsInInbox(ports, sessionID, { stalled: false }).catch(() => true));
 }
-/**
- * Checks the limits for a spawn from `parentID`, then holds its place in `gate` until `release`;
- * throws a refusal naming the limit. Checks run one at a time, so spawns made together count each other.
- */
 export async function admit(ports, parentID) {
     const gate = ports.gate;
     const checked = gate.turn.then(() => check(ports, parentID));
@@ -46,10 +37,8 @@ async function check(ports, parentID) {
     const chains = new Map(entries.map((entry) => [entry.sessionID, lineageBy(parents, entry.sessionID)]));
     const tree = entries.filter((entry) => chains.get(entry.sessionID).at(-1)?.parentID === top);
     const counting = await Promise.all(tree.map((entry) => live(ports, entry.sessionID)));
-    // A session waiting on a live descendant is live too: the brief tells it to end its turn meanwhile.
     const active = new Set(tree.filter((_, i) => counting[i]).flatMap((entry) => [entry.sessionID, ...chains.get(entry.sessionID).map((above) => above.parentID)]));
     const counted = tree.filter((entry) => active.has(entry.sessionID));
-    // A spawn whose child is on the roster already is counted there, if it is live, not by its reservation.
     const recorded = new Set(tree.map((entry) => entry.sessionID));
     const pending = [...ports.gate.reserved].filter((held) => held.top === top && !(held.sessionID && recorded.has(held.sessionID)));
     const mine = counted.filter((entry) => entry.parentID === parentID).length + pending.filter((held) => held.parentID === parentID).length;

package/dist/tree/mascot.d.ts

@@ -1,37 +1,17 @@
-/**
- * A pixel of Digby, the tree panel's mole, as the theme colour it takes: `b` body, `k` background (eyes), `g` mound,
- * `m` muted (paws, dirt, post, arm), `a` accent (snout, letter), `w`, `e` and `s` warning, error and success (sign, dots, spark).
- */
 export type Token = "b" | "k" | "g" | "m" | "a" | "w" | "e" | "s";
-/** What Digby shows: the tree's state, or for a while after one arrives, a spawn or a report. */
 export type MascotState = "idle" | "spawn" | "running" | "waiting" | "stalled" | "report" | "gone";
-/** One cell of a drawing: `▀` the top pixel's colour over the bottom's, `▄` only a bottom pixel, `█` both alike, or a character. */
 export type Cell = {
     readonly char: string;
     readonly fg?: Token;
     readonly bg?: Token;
 };
-/** Digby's frames take one panel frame in this many, about every 450 ms. */
 export declare const MASCOT_EVERY = 5;
-/** He blinks on every this-many-th of his frames where his eyes are open. */
 export declare const BLINK_EVERY = 11;
-/** Running, he is still and awake for this many of his frames, about 8 s, then digs for one cycle of six. */
 export declare const DIG_EVERY = 18;
-/**
- * The 8×4 glyph's frames by state, pixel rows top to bottom; a state with several cycles through them, one per mascot frame.
- * No muted pixel touches the mound, here or in the 16×16, as `text.muted` is close to `background.raised.max`.
- */
 export declare const GLYPH: Readonly<Record<MascotState, ReadonlyArray<ReadonlyArray<string>>>>;
-/** The 8×4 glyph's pixels for `state` at mascot frame `frame`, its first frame with none: animations off. */
 export declare function glyph(state: MascotState, frame?: number): ReadonlyArray<string>;
-/** Pixel rows, two to a line of cells, by the half-block rule; an odd last row has nothing under it. */
 export declare function cells(pixels: ReadonlyArray<string>): ReadonlyArray<ReadonlyArray<Cell>>;
-/** How his eyes are drawn: one pixel each, `wide` two tall, `shut` two wide, or `none` (blinking). */
 export type Eyes = "open" | "wide" | "shut" | "none";
-/**
- * The 16×16 Digby, his head raised by `rise` (0 in the hole, 1 fully up; below 0 out of sight) over a body in the hole,
- * then the mound (its top row `top` wide, `shift` columns over) and the ground, both `mound`, drawn over it but for the hole.
- */
 export declare function digby(rise: number, { top, eyes, slump, shift, mound }?: {
     top?: number;
     eyes?: Eyes;
@@ -39,14 +19,9 @@ export declare function digby(rise: number, { top, eyes, slump, shift, mound }?:
     shift?: number;
     mound?: "g" | "m";
 }): ReadonlyArray<string>;
-/** A spot of `pixels` with its first at row `row`, column `column`; `.` leaves what is under it. */
 type Spot = readonly [row: number, column: number, pixels: string];
-/** `pixels` with `spots` drawn over them. */
 export declare function paint(pixels: ReadonlyArray<string>, spots: ReadonlyArray<Spot>): ReadonlyArray<string>;
-/** The 16×16's frames by state but idle, each its pixels with the eyes open or, for a blink, not; the first reads alone. */
 export declare const ART: Readonly<Record<Exclude<MascotState, "idle">, ReadonlyArray<(open: boolean) => ReadonlyArray<string>>>>;
-/** The 16×16 idle Digby at mascot frame `frame`, its first with none: the mound breathing, a `z` drifting up beside it. */
 export declare function idleArt(frame?: number): ReadonlyArray<ReadonlyArray<Cell>>;
-/** The 16×16 Digby for `state` at mascot frame `frame`, its first frame with none: animations off. */
 export declare function art(state: MascotState, frame?: number): ReadonlyArray<ReadonlyArray<Cell>>;
 export {};

package/dist/tree/mascot.js

@@ -1,13 +1,7 @@
-/** Digby's frames take one panel frame in this many, about every 450 ms. */
 export const MASCOT_EVERY = 5;
-/** He blinks on every this-many-th of his frames where his eyes are open. */
 export const BLINK_EVERY = 11;
-/** Running, he is still and awake for this many of his frames, about 8 s, then digs for one cycle of six. */
 export const DIG_EVERY = 18;
-/**
- * The 8×4 glyph's frames by state, pixel rows top to bottom; a state with several cycles through them, one per mascot frame.
- * No muted pixel touches the mound, here or in the 16×16, as `text.muted` is close to `background.raised.max`.
- */
+// text.muted is close to background.raised.max: no muted pixel on the mound
 export const GLYPH = {
     idle: [["........", "........", "..gggg..", "gggggggg"]],
     spawn: [
@@ -33,9 +27,7 @@ export const GLYPH = {
     ],
     gone: [["........", ".mmmmmm.", ".mkmmkm.", "mmmmmmmm"]],
 };
-/** The states in which his eyes are open, so he blinks. */
 const OPEN_EYES = new Set(["waiting", "report", "running"]);
-/** The 8×4 glyph's pixels for `state` at mascot frame `frame`, its first frame with none: animations off. */
 export function glyph(state, frame) {
     const frames = GLYPH[state];
     const pixels = frames[(frame ?? 0) % frames.length];
@@ -45,10 +37,8 @@ export function glyph(state, frame) {
         return [...pixels.slice(0, 2), ".gggggg.", ...pixels.slice(3)];
     return OPEN_EYES.has(state) && blinks(frame) ? pixels.map((row) => row.replaceAll("k", "b")) : pixels;
 }
-/** The mound's top row widens for two frames in four. */
 const breathesOut = (frame) => Math.floor(frame / 2) % 2 === 1;
 const blinks = (frame) => frame % BLINK_EVERY === BLINK_EVERY - 1;
-/** Pixel rows, two to a line of cells, by the half-block rule; an odd last row has nothing under it. */
 export function cells(pixels) {
     const lines = [];
     for (let row = 0; row < pixels.length; row += 2) {
@@ -68,14 +58,8 @@ function cell(top, bottom) {
         return { char: "█", fg: top };
     return bottom ? { char: "▀", fg: top, bg: bottom } : { char: "▀", fg: top };
 }
-/** The 16×16's size, in pixels. */
 const SIZE = 16;
-/** How far each of the head's rows leans right when he slumps. */
 const SLUMP = [2, 2, 2, 1, 1, 0, 0];
-/**
- * The 16×16 Digby, his head raised by `rise` (0 in the hole, 1 fully up; below 0 out of sight) over a body in the hole,
- * then the mound (its top row `top` wide, `shift` columns over) and the ground, both `mound`, drawn over it but for the hole.
- */
 export function digby(rise, { top = 6, eyes = "open", slump = false, shift = 0, mound = "g" } = {}) {
     const grid = Array.from({ length: SIZE }, () => new Array(SIZE).fill("."));
     const span = (row, width, pixel, skip = (_column) => false, by = 0) => {
@@ -104,7 +88,6 @@ export function digby(rise, { top = 6, eyes = "open", slump = false, shift = 0,
         span(row, SIZE, mound);
     return grid.map((row) => row.join(""));
 }
-/** `pixels` with `spots` drawn over them. */
 export function paint(pixels, spots) {
     const grid = pixels.map((row) => [...row]);
     for (const [row, column, drawn] of spots)
@@ -114,42 +97,32 @@ export function paint(pixels, spots) {
         });
     return grid.map((row) => row.join(""));
 }
-/** A column of `length` pixels of `pixel` from row `row`. */
 const post = (row, column, length, pixel) => Array.from({ length }, (_, at) => [row + at, column, pixel]);
-/** The head's top row at `rise`. */
 const headTop = (rise) => Math.round(10 - 8 * rise);
-/** Up and awake at `rise`, his eyes `shift` columns over (0 straight ahead) when `open`. */
 const awake = (rise, shift) => (open) => {
     const row = headTop(rise) + 3;
     return paint(digby(rise, { eyes: "open" }), [[row, 6, "b"], [row, 9, "b"], ...(open ? [[row, 6 + shift, "k"], [row, 9 + shift, "k"]] : [])]);
 };
-/** Where a clod flies on each side, frame by frame: out of the hole, up, over and down, a row clear of the mound's rim. */
 const CLOD_LEFT = [[8, 3], [7, 2], [6, 1], [5, 0], [7, 0], [9, 0]];
 const CLOD_RIGHT = [[8, 12], [7, 13], [6, 14], [5, 15], [7, 15], [9, 15]];
 const CLODS = [[CLOD_LEFT, 0], [CLOD_LEFT, 3], [CLOD_RIGHT, 1], [CLOD_RIGHT, 4]];
-/** Digging at frame `at`: up with his eyes open, the mound still, four clods on their arcs, one always in the air. */
 const digging = (at) => (open) => paint(digby(0.6, { eyes: open ? "open" : "none" }), CLODS.map(([path, phase]) => {
     const [row, column] = path[(at + phase) % path.length];
     return [row, column, "m"];
 }));
-/** Running: still and awake, a glance left then right over twelve frames, then one dig cycle; the mound never moves. */
 const running = [
     ...Array.from({ length: DIG_EVERY }, (_, at) => [0, 0, 0, 0, 0, -1, -1, 0, 0, 0, 1, 1][at % 12]).map((shift) => awake(0.6, shift)),
     ...Array.from({ length: CLOD_LEFT.length }, (_, at) => digging(at)),
 ];
-/** A child's head peeking out of a side mound at columns `column`–`column + 2`, `up` or half sunk. */
 const peek = (column, up) => [
     ...(up ? [[8, column, ".b."], [9, column, "bkb"]] : [[9, column, ".b."]]),
     [10, column, "gbg"],
     [11, column, "ggg"],
 ];
 const spawn = (up, dirt) => paint(digby(0.1), [...peek(0, up), ...peek(13, up), [12, 0, "gg"], [12, 14, "gg"], ...dirt]);
-/** The sign on its post, which stops a pixel above the ground so the muted post does not sit on it. */
 const sign = (shown) => [...(shown ? [[2, 13, "www"], [3, 13, "wkw"], [4, 13, "www"]] : []), ...post(5, 14, 7, "m")];
-/** His paws, held a pixel above the mound's rim so the muted pixels do not touch it. */
 const waiting = (shown) => (open) => paint(digby(1, { eyes: open ? "wide" : "none" }), [[8, 4, "mm"], [8, 10, "mm"], ...sign(shown)]);
 const stalled = (dots) => () => paint(digby(0.7, { eyes: "shut", slump: true }), [[5, 0, dots]]);
-/** The letter held up on his arm, which stops a pixel above the mound so it does not touch it, and the spark beside him. */
 const report = (rise, spark) => (open) => paint(digby(rise, { eyes: open ? "open" : "none" }), [
     [0, 12, "aaaa"],
     [1, 12, "akka"],
@@ -157,7 +130,6 @@ const report = (rise, spark) => (open) => paint(digby(rise, { eyes: open ? "open
     ...post(3, 13, 8, "m"),
     ...spark.map((row, at) => [1 + at, 0, row]),
 ]);
-/** The 16×16's frames by state but idle, each its pixels with the eyes open or, for a blink, not; the first reads alone. */
 export const ART = {
     spawn: [
         () => spawn(true, [[3, 1, "m"], [5, 3, "m"], [2, 14, "m"], [5, 12, "m"]]),
@@ -169,9 +141,7 @@ export const ART = {
     report: [report(1, [".s.", "sss", ".s."]), report(1.25, ["s.s", ".s.", "s.s"]), report(1.1, [".s.", "sss", ".s."])],
     gone: [() => digby(-0.3, { mound: "m" })],
 };
-/** Where idle's `z` drifts up, by cell line, one step per mascot frame, then gone a frame. */
 const Z_LINES = [3, 2, 1, undefined];
-/** The 16×16 idle Digby at mascot frame `frame`, its first with none: the mound breathing, a `z` drifting up beside it. */
 export function idleArt(frame) {
     const lines = cells(digby(-0.3, { top: frame !== undefined && breathesOut(frame) ? 8 : 6 }));
     const line = Z_LINES[(frame ?? 0) % Z_LINES.length];
@@ -179,7 +149,6 @@ export function idleArt(frame) {
         return lines;
     return lines.map((cellsOf, at) => (at === line ? cellsOf.map((one, column) => (column === 13 ? { char: "z", fg: "m" } : one)) : cellsOf));
 }
-/** The 16×16 Digby for `state` at mascot frame `frame`, its first frame with none: animations off. */
 export function art(state, frame) {
     if (state === "idle")
         return idleArt(frame);

package/dist/tree/model.d.ts

@@ -1,14 +1,9 @@
 import { type ModelRef } from "./domain.js";
 import type { CourierPorts } from "./ports.js";
-/** What courier_spawn says of the model: `provider/model`, and the variant of whichever model is chosen. */
 export interface ModelChoice {
     readonly model?: string;
     readonly variant?: string;
 }
-/**
- * The model a child runs on: the `model` named, else the agent's, else the one its parent runs on, with the `variant`
- * named; `parent` is the parent's own, for the roster to tell a child on another one.
- */
 export declare function chooseModel(ports: CourierPorts, parentID: string, choice: ModelChoice, agent: string | undefined): Promise<{
     model: undefined;
     parent: ModelRef | undefined;

package/dist/tree/model.js

@@ -1,18 +1,13 @@
 import { modelName, parseModelName } from "./domain.js";
 import { modelFormatRefusal, unknownModelRefusal, unknownVariantRefusal, variantWithoutModelRefusal } from "./text.js";
-/**
- * The model a child runs on: the `model` named, else the agent's, else the one its parent runs on, with the `variant`
- * named; `parent` is the parent's own, for the roster to tell a child on another one.
- */
 export async function chooseModel(ports, parentID, choice, agent) {
-    // Some models send null, or an empty string, for an optional field they leave out.
     const named = trimmed(choice.model);
     const variant = trimmed(choice.variant);
     const own = named === undefined ? undefined : parseModelName(named);
     if (named !== undefined && !own)
         throw new Error(modelFormatRefusal(named));
     const parent = await parentModel(ports, parentID);
-    // An agent that cannot be looked up may name a model of its own, which OpenCode applies when none is passed.
+    // with no model passed, OpenCode applies the agent's own (api-notes)
     const inherited = own ? undefined : await inheritedModel(ports, parent, agent).catch(() => undefined);
     const base = own ?? inherited;
     if (!base) {
@@ -26,27 +21,19 @@ export async function chooseModel(ports, parentID, choice, agent) {
         await check(ports, model, own !== undefined);
     return { model, parent };
 }
-/**
- * The model the parent runs on: its session's, else OpenCode's default. A failed lookup must not keep a child on no
- * particular model from starting, so it reads as none, and the child then runs on OpenCode's default.
- */
 async function parentModel(ports, parentID) {
     const session = await ports.session.get({ sessionID: parentID }).catch(() => undefined);
     if (!session)
         return undefined;
     return session.model ?? (await ports.defaultModel().catch(() => undefined));
 }
-/** The named agent's model, if it names one; else the parent's. */
 async function inheritedModel(ports, parent, agent) {
     if (!agent)
         return parent;
     const named = await ports.agent.get({ agentID: agent, location: { directory: ports.directory } });
     return named.data.model ?? parent;
 }
-/**
- * Refuses a model OpenCode does not list, or a variant its model has not; `"default"` is every model's. A listing that
- * cannot be read checks nothing: OpenCode refuses what it does not know at the child's first turn, which is reported.
- */
+// OpenCode refuses an unknown model at the child's first turn (api-notes)
 async function check(ports, model, named) {
     let known;
     try {

package/dist/tree/nudge.d.ts

@@ -1,17 +1,11 @@
 import type { ChildStore, Waits, WatchPorts } from "./ports.js";
-/** OpenCode's `experimental.idle` hook event: a session about to go idle, and the background work still running for it or below it. */
 export interface Idle {
     readonly sessionID: string;
     readonly background: ReadonlyArray<{
         readonly sessionID: string;
     }>;
 }
-/** The ports the reminder is sent through: the watcher's. */
 export type NudgePorts = Pick<WatchPorts, "storage" | "session" | "permissions" | "now" | "log">;
-/**
- * The report a spawned session owes since its last prompt, unless it waits or courier_stop stopped it since: what the
- * silent-turn notice tells the parent of, and the reminder reminds the session of.
- */
 export declare function owedUnwaited(ports: NudgePorts, children: ChildStore, outside: Waits, sessionID: string): Promise<{
     resumesAt?: number | undefined;
     prompt: number;
@@ -19,10 +13,5 @@ export declare function owedUnwaited(ports: NudgePorts, children: ChildStore, ou
     progressed: boolean;
     ended: boolean;
 } | undefined>;
-/**
- * Reminds a spawned session about to go idle owing a report it does not wait on, once per prompt, so it reports in the
- * same execution; one with background work of its own is woken again by it. Returns whether it was reminded.
- */
 export declare function nudgeSilent(ports: NudgePorts, seen: Set<string>, outside: Waits, idle: Idle): Promise<boolean>;
-/** `nudgeSilent` as the hook runs it: a hook that fails fails the execution, so a failure is logged, never thrown. */
 export declare function onIdle(ports: NudgePorts, seen: Set<string>, outside: Waits, idle: Idle): Promise<boolean>;

package/dist/tree/nudge.js

@@ -4,24 +4,15 @@ import { hasCompleteGroup } from "./group.js";
 import { awaited, reportOf, stoppedSincePrompt } from "./report.js";
 import { childStore, groupStore } from "./store.js";
 import { reportReminder } from "./text.js";
-/**
- * Whether a session prompted at `prompt` waits: on an untold report of a session it started, a complete group of
- * its about to be delivered, or what `outside` says it waits on. Cheapest first.
- */
 async function waits(ports, outside, sessionID, prompt) {
     const children = childStore(ports.storage);
     const started = await children.children(sessionID);
     if ((await Promise.all(started.map((entry) => awaited(children, entry.sessionID)))).includes(true))
         return true;
-    // A group with a member still out is waited on through that member, above; one whose every out member was told of is not.
     if (started.some((entry) => entry.group) && (await hasCompleteGroup(groupStore(ports.storage), sessionID)))
         return true;
     return outside(ports, sessionID, prompt);
 }
-/**
- * The report a spawned session owes since its last prompt, unless it waits or courier_stop stopped it since: what the
- * silent-turn notice tells the parent of, and the reminder reminds the session of.
- */
 export async function owedUnwaited(ports, children, outside, sessionID) {
     const report = await reportOf(children, sessionID);
     if (!report?.owes || (await waits(ports, outside, sessionID, report.prompt)))
@@ -30,10 +21,6 @@ export async function owedUnwaited(ports, children, outside, sessionID) {
         return undefined;
     return report;
 }
-/**
- * Reminds a spawned session about to go idle owing a report it does not wait on, once per prompt, so it reports in the
- * same execution; one with background work of its own is woken again by it. Returns whether it was reminded.
- */
 export async function nudgeSilent(ports, seen, outside, idle) {
     const { sessionID } = idle;
     if (idle.background.some((work) => work.sessionID === sessionID))
@@ -49,7 +36,7 @@ export async function nudgeSilent(ports, seen, outside, idle) {
     if ((nudgedAt !== undefined && nudgedAt >= report.prompt) || !claim(seen, `nudge/${sessionID}/${report.prompt}`))
         return false;
     const at = Math.max(ports.now(), report.prompt);
-    // Noted before it is sent, so a second hook never sends another, and with its id after, before the turn takes it.
+    // every instance's idle hook runs; delivery matches by inbox id (api-notes)
     await children.nudged(sessionID, at);
     const { id } = await ports.session.synthetic({
         sessionID,
@@ -57,13 +44,13 @@ export async function nudgeSilent(ports, seen, outside, idle) {
         description: "Reminded to report",
         metadata: { source: "courier", reminder: "report", resume: false },
         delivery: "steer",
-        // The hook's own execution takes it: no wake, and the missed-wake watch leaves it be.
+        // input the idle hook admits continues its execution (api-notes)
         resume: false,
     });
     await children.nudged(sessionID, at, id);
     return true;
 }
-/** `nudgeSilent` as the hook runs it: a hook that fails fails the execution, so a failure is logged, never thrown. */
+// a throwing idle hook fails the execution (api-notes)
 export async function onIdle(ports, seen, outside, idle) {
     try {
         return await nudgeSilent(ports, seen, outside, idle);