opencode-courier 0.13.8 → 0.14.0

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

package/dist/tree/panel.d.ts

@@ -1,20 +1,12 @@
 import type { CourierPorts, ModelWindow, Pending, ShownForm } from "./ports.js";
 import type { Tree, Wait } from "./rpc.js";
 type Messages = Awaited<ReturnType<CourierPorts["session"]["context"]>>;
-/** The last tool call in a session's messages, and when it was made. */
 export declare function lastTool(messages: Messages): {
     name: string;
     at: number;
 } | undefined;
-/** How full a session's context is, as OpenCode's session view reads it (packages/tui/src/util/session.ts, v2.1.0): the last usage since the last compaction over its model's window. */
 export declare function contextOf(messages: Messages, windows: ReadonlyArray<ModelWindow>): number | undefined;
-/** A request as the panel says what a paused session waits on: a permission request, or its first question. */
 export declare const waitOf: (pending: Pending) => Wait;
-/** A form a session shows, as the panel says what it waits on. */
 export declare const formWait: (form: ShownForm) => Wait;
-/**
- * The tree panel's rows: the sessions under a session as courier_tree lists them, at most `maxTotal`, live ones first,
- * then the newest, each as `row` reads it; `top` the session itself, `truncated` the ones left out, `stalled` its stall.
- */
 export declare function panel(ports: CourierPorts, rootID: string): Promise<Tree>;
 export {};

package/dist/tree/panel.js

@@ -4,7 +4,6 @@ import { standingIn } from "./status.js";
 import { childStore } from "./store.js";
 import { readTop, readTree } from "./subtree.js";
 import { stalledAmong } from "./wake.js";
-/** The last tool call in a session's messages, and when it was made. */
 export function lastTool(messages) {
     for (const message of messages.toReversed()) {
         if (message.type !== "assistant")
@@ -15,7 +14,7 @@ export function lastTool(messages) {
     }
     return undefined;
 }
-/** How full a session's context is, as OpenCode's session view reads it (packages/tui/src/util/session.ts, v2.1.0): the last usage since the last compaction over its model's window. */
+// as OpenCode's session view reads it (packages/tui/src/util/session.ts)
 export function contextOf(messages, windows) {
     const compacted = messages.findLastIndex((message) => message.type === "compaction" && message.status === "completed");
     const last = messages.findLast((message, index) => index > compacted && message.type === "assistant" && message.tokens !== undefined);
@@ -26,13 +25,10 @@ export function contextOf(messages, windows) {
     const window = windows.find((model) => model.providerID === last.model.providerID && model.id === last.model.id)?.context;
     return used > 0 && window ? used / window : undefined;
 }
-/** A request as the panel says what a paused session waits on: a permission request, or its first question. */
 export const waitOf = (pending) => pending.type === "permission"
     ? { type: "permission", action: pending.action, resources: [...pending.resources] }
     : { type: "question", question: pending.questions[0]?.question ?? "" };
-/** A form a session shows, as the panel says what it waits on. */
 export const formWait = (form) => ({ type: "form", title: form.title });
-/** A session's report since its last prompt, as the panel shows it; none for one spawned before this was kept. */
 function reportRow(report, status) {
     if (!report)
         return {};
@@ -42,10 +38,6 @@ function reportRow(report, status) {
         return { report: { state: "ended", progressed: report.progressed } };
     return { report: { state: "reported", progressed: report.progressed, ...(status ? { status } : {}) } };
 }
-/**
- * What a session does: waiting on a request to the person or a form it shows them, stalled, running, idle, or gone when
- * OpenCode no longer knows it. A message waiting in its inbox is no turn (`runs`); a stalled one reads stalled.
- */
 function stateOf(info, waits, stalled, running) {
     if (!info)
         return "gone";
@@ -55,8 +47,7 @@ function stateOf(info, waits, stalled, running) {
         return "stalled";
     return running ? "running" : "idle";
 }
-/** One session of the panel: what it is doing, its report and group standing, its last tool call, context use and cost. */
-async function row(ports, windows, { entry, depth, info, running, endedAt, pending, forms, report }, stalled) {
+async function row(ports, windows, { entry, depth, subagent, info, running, endedAt, pending, forms, report }, stalled) {
     const { sessionID } = entry;
     const [messages, status, standing, stopped] = await Promise.all([
         ports.session.context({ sessionID }).catch(() => []),
@@ -67,7 +58,6 @@ async function row(ports, windows, { entry, depth, info, running, endedAt, pendi
     const tool = lastTool(messages);
     const context = contextOf(messages, windows);
     const state = stateOf(info, pending.length + forms.length, stalled !== undefined, running);
-    // A prompt since the failure drops it from the report, so `resumesAt` here is that of the last turn alone.
     const resumes = state === "idle" && !stopped && report?.resumesAt !== undefined && report.resumesAt > ports.now() ? report.resumesAt : undefined;
     return {
         sessionID,
@@ -82,6 +72,7 @@ async function row(ports, windows, { entry, depth, info, running, endedAt, pendi
         ...reportRow(report, status),
         ...(entry.group && standing ? { group: { name: entry.group, standing } } : {}),
         ...startedAs(entry),
+        ...(subagent ? { subagent } : {}),
         created: info?.time.created ?? entry.createdAt,
         ...(info && !running && endedAt !== undefined ? { idle: endedAt } : {}),
         ...(info ? { cost: info.cost } : {}),
@@ -90,10 +81,6 @@ async function row(ports, windows, { entry, depth, info, running, endedAt, pendi
         waits: [...pending.map(waitOf), ...forms.map(formWait)],
     };
 }
-/**
- * The tree panel's rows: the sessions under a session as courier_tree lists them, at most `maxTotal`, live ones first,
- * then the newest, each as `row` reads it; `top` the session itself, `truncated` the ones left out, `stalled` its stall.
- */
 export async function panel(ports, rootID) {
     const [{ kept, leftOut }, root] = await Promise.all([readTree(ports, rootID), readTop(ports, rootID)]);
     const stalled = await stalledAmong(ports, [rootID, ...kept.map((node) => node.entry.sessionID)]);