opencode-courier 0.13.8 → 0.14.0

package/dist/scheduling/tools.d.ts

@@ -10,5 +10,4 @@ export declare const LaterInput: Schema.Struct<{
 export declare const CancelInput: Schema.Struct<{
     readonly id: Schema.String;
 }>;
-/** Adds `courier_later` and `courier_cancel`. */
 export declare function addSchedulingTools(tools: ToolEditor, later: LaterPorts): void;

package/dist/scheduling/tools.js

@@ -4,10 +4,7 @@ import { cancel, schedule } from "./later.js";
 import { cancelText, laterText } from "./text.js";
 export const LaterInput = Schema.Struct({
     message: Schema.String.annotate({ description: "The message to deliver." }),
-    delayMinutes: Schema.optional(
-    // Some models send the number as a string ("3", "3.0") whatever the schema says, and resend it
-    // unchanged after the error, so a string is accepted and schedule reads it as a number.
-    Schema.Union([Schema.Number, Schema.String]).annotate({
+    delayMinutes: Schema.optional(Schema.Union([Schema.Number, Schema.String]).annotate({
         description: "Deliver this many minutes from now. Give this or at.",
     })),
     at: Schema.optional(Schema.String.annotate({ description: "Deliver at this ISO 8601 time. Give this or delayMinutes." })),
@@ -16,7 +13,6 @@ export const LaterInput = Schema.Struct({
 export const CancelInput = Schema.Struct({
     id: Schema.String.annotate({ description: "The id courier_later returned." }),
 });
-/** Adds `courier_later` and `courier_cancel`. */
 export function addSchedulingTools(tools, later) {
     tools.add({
         name: "courier_later",

package/dist/skill.d.ts

@@ -1,20 +1,12 @@
 import type { Plugin } from "@opencode/plugin";
-/** Why a model loads the skill, listed with every session's available skills. */
 export declare const SKILL_DESCRIPTION: string;
-/**
- * The skill's text: how the tools behave, not how to plan or review the parts, which is left to the person's own skills.
- * It names no limits, which the role part and the brief give; it repeats the brief's split rule, since the root has no brief.
- */
 export declare const SKILL_CONTENT: string;
-/** The editor OpenCode hands a skill transform. */
 export type SkillEditor = Parameters<Parameters<Plugin.Context["skill"]["transform"]>[0]>[0];
-/** The courier-orchestrate skill as OpenCode lists it: its id, name and description, and the text the model loads. */
 export declare const orchestrateSkill: () => {
     readonly id: "courier-orchestrate";
     readonly name: "courier-orchestrate";
     readonly description: string;
-    readonly path: "/opencode-courier/courier-orchestrate.md";
+    readonly path: "skill://courier-orchestrate/SKILL.md";
     readonly content: string;
 };
-/** Adds the courier-orchestrate skill; every instance adds the same one, under the same id. */
 export declare function addSkill(skills: SkillEditor): void;

package/dist/skill.js

@@ -1,13 +1,7 @@
 import { ONE_PART_LINE, SKILL_ID, SPLIT_LINE } from "./kernel/protocol.js";
-// The courier-orchestrate skill: the text a session loads with its skill tool.
-/** Why a model loads the skill, listed with every session's available skills. */
 export const SKILL_DESCRIPTION = "How opencode-courier's session tools work. Load before you split a task with courier_spawn: when it has 2 or more " +
     "independent, substantial parts touching separate files or areas. Starting the parts, waiting without polling, " +
     "relaying questions and permissions, reading reports, merging and reporting upward.";
-/**
- * The skill's text: how the tools behave, not how to plan or review the parts, which is left to the person's own skills.
- * It names no limits, which the role part and the brief give; it repeats the brief's split rule, since the root has no brief.
- */
 export const SKILL_CONTENT = [
     "# How opencode-courier's session tools work",
     "",
@@ -103,8 +97,8 @@ export const SKILL_CONTENT = [
     "## When a part goes wrong",
     "",
     '- A failed turn (failed="...") or a silent end (ended="without-report", quoting the session\'s last reply): message ' +
-        "the session with courier_send to carry on, to report, or to try again; or start a replacement. Until it reports, " +
-        "it counts toward the limits.",
+        "the session with courier_send to carry on, to report, or to try again; or start a replacement. A silent end counts " +
+        "toward the limits until it reports; a failed turn does not, until you message it again.",
     "- A refusal from courier_spawn naming maxDepth, maxChildren or maxTotal: do that part yourself, or end your turn and " +
         "start it once a report has arrived. Do not retry it in a loop.",
     "- Lost track, after a compaction or a restart: one courier_tree shows every session under you with its depth, its " +
@@ -112,11 +106,9 @@ export const SKILL_CONTENT = [
     "- A subtree that went wrong or is no longer needed: courier_stop its top session; everything under it is stopped " +
         "too, and nothing in it reports back. cleanup: true removes their worktrees.",
 ].join("\n");
-/** A skill's path is where OpenCode would look for its files; this one has none, so a path of the plugin's own. */
-const SKILL_PATH = `/opencode-courier/${SKILL_ID}.md`;
-/** The courier-orchestrate skill as OpenCode lists it: its id, name and description, and the text the model loads. */
+// A skill:// path: the read tool serves it from the registry (api-notes)
+const SKILL_PATH = `skill://${SKILL_ID}/SKILL.md`;
 export const orchestrateSkill = () => ({ id: SKILL_ID, name: SKILL_ID, description: SKILL_DESCRIPTION, path: SKILL_PATH, content: SKILL_CONTENT });
-/** Adds the courier-orchestrate skill; every instance adds the same one, under the same id. */
 export function addSkill(skills) {
     skills.add(orchestrateSkill());
 }

package/dist/tree/cleanup.d.ts

@@ -3,31 +3,11 @@ export interface CleanupInput {
     readonly sessionID: string;
     readonly force?: boolean;
 }
-/** At most this many changes and commits are returned; the reason still counts them all. */
 export declare const MAX_LISTED = 50;
-/**
- * Forgets a child the parent started, removing its worktree if it is isolated. A worktree with uncommitted changes
- * or commits found nowhere else is kept unless `force` is set; the result says so.
- */
 export declare function cleanup(ports: CleanupPorts, parentID: string, input: CleanupInput): Promise<CleanupResult>;
-/** Names the git to run, by absolute path, overriding the places `GIT_LOCATIONS` lists. */
 export declare const GIT_ENV = "OPENCODE_COURIER_GIT";
-/**
- * Where git is looked for, in order: its usual install locations, never `PATH`, so a writable
- * directory early in `PATH` cannot put another program in its place.
- */
 export declare const GIT_LOCATIONS: Readonly<Record<"posix" | "win32", readonly string[]>>;
-/**
- * The git to run: `OPENCODE_COURIER_GIT` when it is an absolute path, otherwise the first of
- * `GIT_LOCATIONS` that exists. Throws when there is none.
- */
 export declare function findGit(env?: Readonly<Record<string, string | undefined>>, platform?: NodeJS.Platform, exists?: (path: string) => boolean): string;
-/** The commit a worktree is on, or undefined when git cannot tell. */
 export declare function headOf(directory: string): Promise<string | undefined>;
-/** Whether a worktree has uncommitted changes, untracked files included; undefined when git cannot tell. */
 export declare function dirtyOf(directory: string): Promise<boolean | undefined>;
-/**
- * Reads a worktree's state with git; undefined when the directory is gone. Commits reachable from
- * `base`, the commit the worktree was made from, are not its own work and are not listed.
- */
 export declare function inspectWorktree(directory: string, base?: string): Promise<WorktreeState | undefined>;

package/dist/tree/cleanup.js

@@ -5,18 +5,12 @@ import { forgetDropped } from "./forget.js";
 import { syncStanding } from "./standing.js";
 import { childStore } from "./store.js";
 import { keepReason } from "./text.js";
-/** At most this many changes and commits are returned; the reason still counts them all. */
 export const MAX_LISTED = 50;
-/**
- * Forgets a child the parent started, removing its worktree if it is isolated. A worktree with uncommitted changes
- * or commits found nowhere else is kept unless `force` is set; the result says so.
- */
 export async function cleanup(ports, parentID, input) {
     const entry = await childStore(ports.storage).entry(parentID, input.sessionID);
     if (!entry)
         throw new Error(`${input.sessionID} is not on the courier_children list of ${parentID}.`);
     const { directory } = entry;
-    // A member still out is dropped from its group, so the group is released without it; the result names that group.
     const forget = async () => {
         const group = await forgetDropped(ports, entry);
         await syncStanding(ports, parentID);
@@ -24,8 +18,6 @@ export async function cleanup(ports, parentID, input) {
     };
     if (!entry.isolated)
         return { sessionID: input.sessionID, directory, outcome: "forgotten", ...(await forget()) };
-    // With force the state only decides whether there is anything left to remove, so a worktree git
-    // can no longer read is still removed.
     const state = await ports
         .inspect(directory, entry.base)
         .catch((error) => (input.force ? { changes: [], commits: [] } : Promise.reject(error)));
@@ -48,26 +40,16 @@ export async function cleanup(ports, parentID, input) {
     });
     return { sessionID: input.sessionID, directory, outcome: "removed", ...(await forget()) };
 }
-/** Names the git to run, by absolute path, overriding the places `GIT_LOCATIONS` lists. */
 export const GIT_ENV = "OPENCODE_COURIER_GIT";
-/**
- * Where git is looked for, in order: its usual install locations, never `PATH`, so a writable
- * directory early in `PATH` cannot put another program in its place.
- */
 export const GIT_LOCATIONS = {
     posix: [
         "/usr/bin/git",
         "/usr/local/bin/git",
         "/opt/homebrew/bin/git",
-        // NixOS, and nix-darwin.
         "/run/current-system/sw/bin/git",
     ],
     win32: [String.raw `C:\Program Files\Git\cmd\git.exe`, String.raw `C:\Program Files (x86)\Git\cmd\git.exe`],
 };
-/**
- * The git to run: `OPENCODE_COURIER_GIT` when it is an absolute path, otherwise the first of
- * `GIT_LOCATIONS` that exists. Throws when there is none.
- */
 export function findGit(env = process.env, platform = process.platform, exists = existsSync) {
     const named = env[GIT_ENV]?.trim();
     if (named) {
@@ -84,29 +66,21 @@ export function findGit(env = process.env, platform = process.platform, exists =
 function git(directory, args) {
     return new Promise((resolve, reject) => execFile(findGit(), ["-C", directory, ...args], { maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => error ? reject(new Error(`git ${args[0]} in ${directory}: ${stderr.trim() || error.message}`)) : resolve(stdout)));
 }
-/** The commit a worktree is on, or undefined when git cannot tell. */
 export function headOf(directory) {
     return git(directory, ["rev-parse", "HEAD"]).then((out) => out.trim() || undefined, () => undefined);
 }
-/** Whether a worktree has uncommitted changes, untracked files included; undefined when git cannot tell. */
 export function dirtyOf(directory) {
     return git(directory, ["status", "--porcelain"]).then((out) => out.trim().length > 0, () => undefined);
 }
-/**
- * Reads a worktree's state with git; undefined when the directory is gone. Commits reachable from
- * `base`, the commit the worktree was made from, are not its own work and are not listed.
- */
 export async function inspectWorktree(directory, base) {
     if (!existsSync(directory))
         return undefined;
-    // An untracked directory is one entry, not every file in it.
     const status = await git(directory, ["status", "--porcelain=v1", "-z", "--untracked-files=normal"]);
     const changes = [];
     const records = status.split("\0").filter(Boolean);
     for (let i = 0; i < records.length; i++) {
         const record = records[i];
         changes.push(record.slice(3));
-        // A rename or copy is followed by its source path in a record of its own.
         if ("RC".includes(record[0]) || "RC".includes(record[1]))
             i++;
     }

package/dist/tree/context.d.ts

@@ -1,5 +1,4 @@
 import type { ContextPorts } from "./ports.js";
-/** The part of a session context this hook changes. */
 export interface Shaped {
     readonly sessionID: string;
     tools: Record<string, unknown>;
@@ -8,8 +7,4 @@ export interface Shaped {
         text: string;
     }>;
 }
-/**
- * The `context` hook: hides courier_spawn and the tools named `hiddenFromLeaf` from a session at `maxDepth`, and names a
- * session's role in a system part unless its `role` entry does; a session nobody spawned that has started none is pointed to the skill.
- */
 export declare function shapeContext(ports: ContextPorts, event: Shaped): Promise<void>;

package/dist/tree/context.js

@@ -1,14 +1,8 @@
 import { setBounded } from "../platform/bounded.js";
 import { childStore } from "./store.js";
 import { ROLE_KEY, ROLE_PREFIX, rolePart } from "./text.js";
-/** How many sessions' roles an instance remembers. */
 const ROLES_MAX = 1000;
-/** A role part, or the role entry's block, already in the system prompt, wherever its part begins. */
 const ROLE_LINE = new RegExp(`^${ROLE_PREFIX}`, "m");
-/**
- * The `context` hook: hides courier_spawn and the tools named `hiddenFromLeaf` from a session at `maxDepth`, and names a
- * session's role in a system part unless its `role` entry does; a session nobody spawned that has started none is pointed to the skill.
- */
 export async function shapeContext(ports, event) {
     try {
         const { depth, entry } = await roleOf(ports, event.sessionID);
@@ -29,7 +23,6 @@ async function roleOf(ports, sessionID) {
     const known = ports.roles.get(sessionID);
     if (known !== undefined)
         return known;
-    // The reverse index alone: a scan here would run for every session's first request, courier or not.
     const children = childStore(ports.storage);
     const chain = await children.indexedLineage(sessionID);
     const depth = chain.length || ((await children.children(sessionID)).length ? 0 : null);
@@ -37,7 +30,6 @@ async function roleOf(ports, sessionID) {
     setBounded(ports.roles, sessionID, role, ROLES_MAX);
     return role;
 }
-/** Whether the session carries the role entry, listed when its role is looked up; one that cannot be read gets the part. */
 async function hasEntry(ports, sessionID) {
     if (!ports.instructions)
         return false;

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