opencode-courier 0.13.8 → 0.15.0

package/dist/tree/text.js

@@ -1,13 +1,8 @@
-/** The tree's model-facing texts: the child brief, the role part, refusals, reports, notices and tool results. */
 import { obj, str } from "../platform/json.js";
 import { clipText, defuse, defuseBlock, END_TURN, ROOT_SPLIT_LINE, SKILL_ID, SPLIT_LINE, STATUSES } from "../kernel/protocol.js";
 import { retryDelay } from "./domain.js";
-// The envelope and the child brief.
-/** How a text names the statuses a report may carry. */
 const STATUS_LIST = `${STATUSES.slice(0, -1).join(", ")} or ${STATUSES.at(-1)}`;
-/** The branch an isolated child commits its work on, and names in the `branch` of its report. */
 export const childBranch = (sessionID) => `courier/${sessionID}`;
-/** What a spawned session at `depth` is told; `depth` 1 is a child of a session nobody spawned. `branch` is for an isolated one. */
 export function childBrief(parentID, task, depth, limits, branch) {
     return [
         `You were started by session ${parentID} through opencode-courier.`,
@@ -21,10 +16,12 @@ export function childBrief(parentID, task, depth, limits, branch) {
             "A message without a status is progress, not your report: if you end your turn without a report, the parent is told so.",
         "If you find something the other parts of the job need (an assumption of the split that is wrong, a shared file or API " +
             "that behaves otherwise), send it to the parent at once with courier_send without a status, then carry on: it passes " +
-            "it on to the sessions it affects. Progress alone is not worth a message.",
+            "it on to the sessions it affects. Do the same with one a session you started sends you, when it reaches past your own " +
+            "part. Progress alone is not worth a message.",
         "A message the person writes in your session, outside a <courier> envelope, is for the whole job: before you act on it, " +
-            "send it to the parent at once with courier_send without a status, quoting it as the person's, then carry on.",
-        "If you need the person to decide something, use your question tool; it reaches them through the session that started you.",
+            "send it to the parent at once with courier_send without a status, quoting it as the person's, then carry on. The " +
+            "person's words a session you started passes you are for the whole job too: send them on to the parent the same way.",
+        "If you need the person to decide something, use your question tool; it reaches them through the top session of the tree.",
         "",
         ...(branch ? [...isolationRule(branch, depth < limits.maxDepth), ""] : []),
         ...splitRule(parentID, depth, limits),
@@ -63,14 +60,8 @@ function splitRule(parentID, depth, limits) {
             `session), then send ${parentID} one combined report.`,
     ];
 }
-/** How every role part begins, in the role entry and in the part the context hook adds without one, so no second copy is added. */
 export const ROLE_PREFIX = "opencode-courier role:";
-/** The key of the session instruction entry carrying a spawned session's role part, `<context key="role">` in its system prompt. */
 export const ROLE_KEY = "role";
-/**
- * The system part naming a session's place in its tree: `depth` 0 for a session nobody spawned that
- * has started one, `null` for one that has started none, which is pointed to the skill. The same on every request.
- */
 export function rolePart(depth, limits) {
     const { maxDepth, maxChildren, maxTotal } = limits;
     const budget = `At most ${maxChildren} of the sessions you start run at once, and ${maxTotal} in the whole tree.`;
@@ -79,24 +70,20 @@ export function rolePart(depth, limits) {
             `${SKILL_ID} skill, call courier_recall once for how earlier trees in this project were split and how they went, ` +
             `and decide whether to split it across sessions (doing it yourself is fine; so is handing a heavy task, with long ` +
             `reading, many edits or long runs, whole to one session to keep your context, but never a small one), and say ` +
-            `which in one line of your reply: ${ROOT_SPLIT_LINE}`);
+            `which in one line of your reply: ${ROOT_SPLIT_LINE}.`);
     if (depth === 0)
         return (`${ROLE_PREFIX} root orchestrator. You started sessions with courier_spawn, and they may start their own, ` +
-            `down to ${maxDepth} levels below you. ${budget} Check and integrate what each one reports yourself.`);
+            `down to ${maxDepth} levels below you. ${budget} Check and integrate what each one reports yourself. ` +
+            `Load the ${SKILL_ID} skill if it is not in your context.`);
     if (depth < maxDepth)
-        return (`${ROLE_PREFIX} sub-orchestrator, at depth ${depth} of at most ${maxDepth}. Before you split, load the ${SKILL_ID} ` +
+        return (`${ROLE_PREFIX} sub-orchestrator, at depth ${depth} of at most ${maxDepth}. Before you decide whether to split, load the ${SKILL_ID} ` +
             `skill. Split your task with courier_spawn or do it yourself, as your brief says; sessions can be started ${count(maxDepth - depth, "level")} below you. ${budget}`);
     return (`${ROLE_PREFIX} leaf, at depth ${depth}, the deepest the session tree goes. You cannot start sessions: do your ` +
         "task yourself and report with courier_send to the session that started you.");
 }
-// The standing entry: what a parent's system prompt says of the sessions it started.
-/** The key of the session instruction entry on a parent listing the sessions it started, `<context key="standing">`. */
 export const STANDING_KEY = "standing";
-/** How every standing entry begins. */
 export const STANDING_PREFIX = "opencode-courier standing:";
-/** How many children the entry lists; older ones past that are counted. */
 export const STANDING_MAX = 10;
-/** The most characters of a child's title the entry shows. */
 const TITLE_MAX = 40;
 function stateWords(state) {
     const progressed = state.progressed ? ", sent progress" : "";
@@ -132,10 +119,6 @@ function groupWords(name, standing) {
             return `out of ${group} (${LEFT_HOW[standing]})`;
     }
 }
-/**
- * The standing entry: one line per session the parent started, oldest first, with its state and its place in its join group,
- * in the same words for the same state, so an unchanged standing is not put again.
- */
 export function standingEntry(rows) {
     const shown = rows.slice(-STANDING_MAX);
     const older = rows.length - shown.length;
@@ -150,22 +133,19 @@ export function standingEntry(rows) {
         ...(older ? [`${count(older, "older session")} not listed; courier_children lists them.`] : []),
     ].join("\n");
 }
-// courier_spawn's refusals, one per limit.
 export const depthRefusal = (depth, maxDepth) => `Not started: this session is at depth ${depth} of its session tree, and the tree goes at most ${maxDepth} deep ` +
     "(maxDepth), so it cannot start sessions. Do the task yourself, and report with courier_send.";
-/** How a refusal names sessions that count against a limit: those running, and those that have not reported yet. */
 const live = (n) => (n === 1 ? "is running or has not reported yet" : "are running or have not reported yet");
 export const childrenRefusal = (running, maxChildren) => `Not started: ${count(running, "session")} you started ${live(running)}, the most allowed at once ` +
-    `(maxChildren ${maxChildren}). Do this part yourself, or end your turn and start it once one of them has reported.`;
-export const totalRefusal = (running, maxTotal) => `Not started: ${count(running, "session")} in this session tree ${live(running)}, the most allowed at once ` +
-    `(maxTotal ${maxTotal}). Do this part yourself, or end your turn and try again once a report has arrived.`;
-// courier_spawn's refusals of a model or a variant OpenCode does not list.
-/** How many models, or providers, a refusal names before it counts the rest. */
-const NAMED = 12;
-const some = (items) => (items.length > NAMED ? `${items.slice(0, NAMED).join(", ")} and ${items.length - NAMED} more` : items.join(", "));
+    `(maxChildren ${maxChildren}). Do this part yourself, or end your turn and start it once one of them has reported, not in a loop.`;
+export const totalRefusal = (running, maxTotal, yours) => `Not started: ${count(running, "session")} in this session tree ${live(running)}, the most allowed at once (maxTotal ${maxTotal}). ` +
+    (yours === 0
+        ? "Do this part yourself: none of the sessions you started is running, so no report will wake you."
+        : "Do this part yourself, or end your turn and try again once a report has arrived, not in a loop.");
+const LISTED_MAX = 12;
+const some = (items) => (items.length > LISTED_MAX ? `${items.slice(0, LISTED_MAX).join(", ")} and ${items.length - LISTED_MAX} more` : items.join(", "));
 export const modelFormatRefusal = (given) => `Not started: model must be provider/model, as OpenCode names them (opencode/gpt-5-nano, anthropic/claude-sonnet-4-5), not ${JSON.stringify(given)}. ` +
     "Leave it unset to run the session on your own model.";
-/** The model is not among those OpenCode lists; `named` says the caller named it, rather than inherited it and named a variant. */
 export function unknownModelRefusal(model, known, named) {
     const name = `${model.providerID}/${model.id}`;
     const ids = known.filter((item) => item.providerID === model.providerID).map((item) => item.id);
@@ -184,19 +164,12 @@ export function unknownVariantRefusal(model, variants) {
     return (`Not started: the model ${model.providerID}/${model.id} has no variant ${JSON.stringify(model.variant)}. ` +
         `Its variants are ${listed}; leave variant unset for the model's default.`);
 }
-/** A variant was named, but the model it would apply to could not be read: the named agent's, else the caller's own or OpenCode's default. */
 export function variantWithoutModelRefusal(variant, agent) {
     const why = agent ? `the agent ${agent} could not be looked up` : "neither your own model nor OpenCode's default could be read";
     return `Not started: variant ${JSON.stringify(variant)} needs a model to apply to, and ${why}. Name a model as provider/model, or leave variant unset.`;
 }
-/** The strings of a list given as artifacts, whatever else the model put in it. */
 const strings = (value) => (Array.isArray(value) ? value.flatMap((item) => (typeof item === "string" ? [item.trim()] : [])) : []).filter(Boolean);
-/** A list's line in the artifacts block, or none when it is empty. */
 const listed = (name, items) => (items.length ? [`- ${name}: ${items.join(", ")}`] : []);
-/**
- * The body of a report: its text, then the artifacts in a fixed layout, the same for every report,
- * so a parent finds the branch, the commits, the files and the checks without reading prose.
- */
 export function reportBody(message, artifacts) {
     const given = obj(artifacts);
     const checks = (Array.isArray(given.checks) ? given.checks : []).flatMap((check) => {
@@ -211,27 +184,27 @@ export function reportBody(message, artifacts) {
     ];
     return lines.length ? [message, "", "Artifacts:", ...lines].join("\n") : message;
 }
-// Tool results.
-/** courier_spawn's refusal of `native: true` with `isolate: true`: OpenCode gives a session a worktree or a parent, never both. */
 export const nativeIsolateRefusal = () => "Not started: native: true and isolate: true cannot go together. OpenCode runs a session in a worktree of its own or as a " +
     "subagent of its parent, never both. Start it with isolate: true alone for a worktree of its own, or with native: true alone for a subagent in your directory.";
 export function spawnText(child) {
     const warning = (child.fromParent ? " Its worktree starts from the commit your own worktree is on." : "") +
         (child.uncommitted
-            ? " Your worktree has uncommitted changes, which it does not see: commit them and tell it, or send them to it, if it needs them."
+            ? " Your working tree has uncommitted changes, which it does not see: commit them and tell it, or send them to it, if it needs them."
             : "") +
         (child.rosterError ? ` It is not on your courier_children list: ${child.rosterError}` : "") +
         (child.groupError ? ` It is in no group, so its report comes on its own: ${child.groupError}` : "");
+    const asks = child.belowTop
+        ? " Its permission requests and questions go to the top session of the tree, not to you, so a child slow to report may be waiting on the person."
+        : "";
     const reports = child.group
         ? `Its report is held with group "${child.group}": once every session you started in that group has reported and your ` +
-            "turn has ended, you get their reports in one message, which starts a new turn for you; a blocked report, a question " +
-            "or a failed turn still reaches you at once."
-        : "It will report back with courier_send, which starts a new turn for you.";
+            `turn has ended, you get their reports in one message, which starts a new turn for you; a blocked report${child.belowTop ? "" : ", a question"} ` +
+            `or a failed turn still reaches you at once.${asks}`
+        : `It will report back with courier_send, which starts a new turn for you.${asks}`;
     const on = child.model ? `, on ${child.model}` : "";
     return (`Started session ${child.sessionID} in ${child.directory}${on}. ${reports} Once you have started every session you need, ` +
         `end your turn: reply without calling more tools. That does not drop the task; you carry on with it when the reports arrive.${warning}`);
 }
-/** courier_send's result: for a message to the session that started the sender, whether it was its report; below it, the status dropped. */
 export function sendText(sessionID, sent = {}) {
     if (sent.dropped)
         return (`Delivered to ${sessionID}, without the status ${sent.dropped}: a status belongs on a report to the session that ` +
@@ -266,7 +239,6 @@ export function cleanupText(result) {
         return done;
     return `${done} Dropped it from group "${result.group}" without a report: the group's other reports reach you once they are in and your turn has ended, the message naming it, and a report it sends after all comes on its own.`;
 }
-/** courier_tree's result: the sessions under a session, drawn depth first, as JSON. */
 export function treeText(tree) {
     if (!tree.sessions.length)
         return "No sessions started with courier_spawn.";
@@ -276,15 +248,18 @@ export function treeText(tree) {
     const note = `\n${older} not listed: at most maxTotal are, the live ones first, then the newest; courier_tree on a listed session lists what is under it.`;
     return JSON.stringify(tree, null, 2) + note;
 }
-/** What courier_stop did to each session, and to the messages and worktrees. */
+const IDLE_STOPPED = "Stopping an idle session does not settle it: one that owed a report still owes it, stays in its join group and " +
+    "counts toward maxChildren and maxTotal until the session that started it drops it with courier_cleanup.";
 export function stopText(result) {
     const interrupted = result.stopped.filter((one) => one.outcome === "interrupted").length;
     const failed = result.stopped.filter((one) => one.outcome === "failed");
+    const idle = result.stopped.some((one) => one.outcome === "idle" && !one.subagent);
     return [
         `Stopped ${result.sessionID} and ${count(result.stopped.length - 1, "session")} under it, deepest first: ${interrupted} had a turn running and was interrupted, ` +
             `${result.stopped.filter((one) => one.outcome === "idle" || one.outcome === "gone").length} did not run.`,
-        ...result.stopped.map((one) => `- ${one.sessionID}: ${one.outcome}${one.error ? " (" + one.error + ")" : ""}`),
+        ...result.stopped.map((one) => `- ${one.sessionID}${one.subagent ? " (subagent)" : ""}: ${one.outcome}${one.error ? " (" + one.error + ")" : ""}`),
         ...(failed.length ? ["Those that failed may still run: try courier_stop again."] : []),
+        ...(idle ? [IDLE_STOPPED] : []),
         result.cancelled.length
             ? `Cancelled ${count(result.cancelled.length, "scheduled message")}: ${result.cancelled.join(", ")}.`
             : "No scheduled messages were pending for them.",
@@ -293,7 +268,6 @@ export function stopText(result) {
     ].join("\n");
 }
 const FORCE_HINT = " Commit or branch what you want to keep, or call courier_cleanup again with force: true to discard it.";
-/** courier_stop's lines on the worktrees it was asked to remove. */
 function worktreeLines(cleanup) {
     if (!cleanup.length)
         return ["None of them ran in a worktree of its own."];
@@ -301,12 +275,10 @@ function worktreeLines(cleanup) {
         ? `Worktree of ${one.sessionID}: not removed (${one.error}).`
         : cleanupText(one).replace(FORCE_HINT, " Kept; courier_cleanup with force: true discards it."));
 }
-/** What the parent of a stopped session is told when the stop was ordered by a session above both. */
 export const stoppedNotice = (title, by) => [
     `This session, "${title}", which you started with courier_spawn, was stopped by ${by}, a session above you, together with the sessions under it.`,
     "It was not a failure and it will not report back. Carry on without it, or start a replacement if you still need what it was doing.",
 ].join("\n");
-/** Why a worktree in this state must be kept, or undefined when removing it loses nothing. */
 export function keepReason(state) {
     const reasons = [
         state.changes.length ? `${count(state.changes.length, "uncommitted change")} (${preview(state.changes)})` : "",
@@ -322,8 +294,6 @@ function count(n, noun) {
 function preview(items) {
     return items.length > 5 ? `${items.slice(0, 5).join(", ")}, ...` : items.join(", ");
 }
-// Turn failures.
-/** A wait in whole minutes, rounded up: "1 minute", "45 minutes", "2 hours 5 minutes". */
 function wait(ms) {
     const minutes = Math.ceil(ms / 60_000);
     if (minutes < 60)
@@ -331,31 +301,32 @@ function wait(ms) {
     const rest = minutes % 60;
     return [count(Math.floor(minutes / 60), "hour"), rest ? count(rest, "minute") : ""].filter(Boolean).join(" ");
 }
-/** A time as the notices say it, in UTC, with its date when it is not the day of `from`. */
 function clock(at, from) {
     const iso = new Date(at).toISOString();
     return iso.slice(0, 10) === new Date(from).toISOString().slice(0, 10) ? `${iso.slice(11, 16)} UTC` : `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC`;
 }
-/** The line saying how long the provider asked to wait, and until when if the failure's time `at` is known. */
 function waitLine(delay, at) {
     const until = at === undefined ? "" : `, until about ${clock(at + delay, at)}`;
     return `The provider asked to wait about ${wait(delay)} before trying again${until}.`;
 }
-/**
- * What the parent is told when a session it started failed its turn; `at` is when the failure happened, which the provider's
- * retry time (`retryAfterMs`) counts from. Message the child before that and it fails again, so the notice says to wait.
- */
-export function failureNotice(title, error, group, at) {
+function belowLine(below) {
+    const titles = below.map((title) => `"${title}"`).join(", ");
+    return (`It has ${count(below.length, "session")} of its own still running (${titles}), whose reports will wake it, and it still counts ` +
+        "toward your limits: message it rather than replace it, or stop it with courier_stop first, which stops the sessions under it too.");
+}
+export function failureNotice(title, error, group, at, below = []) {
     const status = error.status === undefined ? "" : `, status ${error.status}`;
     const delay = retryDelay(error);
+    const replace = below.length ? "" : " start a replacement,";
     return [
         `This session, "${title}", which you started with courier_spawn, failed: ${error.message} (${error.type}${status}).`,
         ...(delay === undefined ? [] : [waitLine(delay, at)]),
-        "Its turn ended without finishing, so it will not report back on its own.",
+        below.length ? "Its turn ended without finishing." : "Its turn ended without finishing, so it will not report back on its own.",
         delay === undefined
-            ? "Message it with courier_send to have it try again, start a replacement, or carry on without it."
-            : "Do not message it with courier_send before then, as the turn would fail again. Message it after, start a replacement, or carry on without it; " +
+            ? `Message it with courier_send to have it try again,${replace} or carry on without it.`
+            : `Do not message it with courier_send before then, as the turn would fail again. Message it after,${replace} or carry on without it; ` +
                 "courier_later can remind you when the wait is over.",
+        ...(below.length ? [belowLine(below)] : []),
         ...(group
             ? [
                 `It is a member of group "${group}", which no longer waits for it: its other members' reports reach you once they have ` +
@@ -364,7 +335,6 @@ export function failureNotice(title, error, group, at) {
             : []),
     ].join("\n");
 }
-/** The one reminder a spawned session gets as it is about to end its turn owing its parent a report; it carries on in the same turn. */
 export function reportReminder(parentID) {
     return [
         `You are about to end your turn without reporting to session ${parentID}, which started you.`,
@@ -373,12 +343,7 @@ export function reportReminder(parentID) {
         "This reminder comes once: if you end your turn without a report, the session that started you is told.",
     ].join("\n");
 }
-/** Longest last reply a notice that a session ended its turn without reporting quotes. */
-const MAX_REPLY = 2000;
-/**
- * What the parent is told when a session it started ends its turn without a report to it;
- * `progressed` when it messaged the parent without a status since its last prompt.
- */
+const QUOTED_REPLY_MAX = 2000;
 export function silentNotice(title, lastText, progressed = false, group) {
     const reply = lastText?.trim();
     return [
@@ -386,9 +351,11 @@ export function silentNotice(title, lastText, progressed = false, group) {
         ...(progressed
             ? [`Its last message to you had no status, so it was progress, not its report: a report carries status ${STATUS_LIST}.`]
             : []),
-        ...(reply ? ["Its last reply:", defuse(clipText(reply, MAX_REPLY))] : ["It ended without a reply."]),
+        ...(reply ? ["Its last reply:", defuse(clipText(reply, QUOTED_REPLY_MAX))] : ["It ended without a reply."]),
         "",
-        "Decide what it needs: message it with courier_send to have it carry on, or to report if its last reply is what you needed; or start a replacement.",
+        reply
+            ? "Decide what it needs: message it with courier_send to have it carry on, or to report if its last reply is what you needed; or start a replacement."
+            : "Decide what it needs: message it with courier_send to have it carry on; or start a replacement.",
         "Until it reports, it counts toward your limits on the sessions you run at once.",
         ...(group
             ? [
@@ -398,8 +365,6 @@ export function silentNotice(title, lastText, progressed = false, group) {
             : []),
     ].join("\n");
 }
-// Join groups.
-/** How a release names each status among its reports: `2 done, 1 failed`. */
 function statusCounts(reports) {
     return STATUSES.flatMap((status) => {
         const n = reports.filter((report) => report.status === status).length;
@@ -412,10 +377,6 @@ const LEFT_HOW = {
     deleted: "it was deleted",
     dropped: "you dropped it with courier_cleanup",
 };
-/**
- * What the parent gets when a group it named is released: every report, with its status, text and artifacts in
- * `reportBody`'s layout, and the members that left without one, in the order they joined.
- */
 export function groupNotice(group, reports, left = []) {
     const total = reports.length + left.length;
     const listed = reports.flatMap((report, index) => [

package/dist/tree/tools.d.ts

@@ -1,10 +1,6 @@
 import { Schema } from "effect";
 import { type ToolEditor } from "../kernel/tool.js";
 import type { CleanupPorts, CourierPorts, StopPorts } from "./ports.js";
-/**
- * The tree's courier tools: their input schemas, descriptions, and what each returns. The descriptions are
- * model-facing like the texts in `text.ts`, and snapshotted with them in `test/notices.test.ts`.
- */
 export declare const SpawnInput: Schema.Struct<{
     readonly task: Schema.String;
     readonly title: Schema.optional<Schema.String>;
@@ -44,11 +40,9 @@ export declare const CleanupInput: Schema.Struct<{
     readonly sessionID: Schema.String;
     readonly force: Schema.optional<Schema.Boolean>;
 }>;
-/** What the tree's tools run on: one plugin instance's ports. */
 export interface TreeToolPorts {
     readonly courier: CourierPorts;
     readonly cleanup: CleanupPorts;
     readonly stop: StopPorts;
 }
-/** Adds the tree's courier tools, each a direct tool rather than a code-mode one. */
 export declare function addTreeTools(tools: ToolEditor, ports: TreeToolPorts): void;

package/dist/tree/tools.js

@@ -8,10 +8,6 @@ import { listChildren } from "./status.js";
 import { stop } from "./stop.js";
 import { tree } from "./subtree.js";
 import { childrenText, cleanupText, sendText, spawnText, stopText, treeText } from "./text.js";
-/**
- * The tree's courier tools: their input schemas, descriptions, and what each returns. The descriptions are
- * model-facing like the texts in `text.ts`, and snapshotted with them in `test/notices.test.ts`.
- */
 export const SpawnInput = Schema.Struct({
     task: Schema.String.annotate({ description: "What the new session should do. It is told who started it and how to report back." }),
     title: Schema.optional(Schema.String.annotate({ description: "Session title; defaults to the task's first line." })),
@@ -25,21 +21,23 @@ export const SpawnInput = Schema.Struct({
             "it unset for the chosen model's own; with a model of your own choosing, that is the model's default. Refused when " +
             "the model has no such variant.",
     })),
-    isolate: Schema.optional(Schema.Boolean.annotate({ description: "Run the session in its own git worktree so parallel sessions don't share files. From a session that is itself " +
-            "isolated, the worktree starts from your current commit, not your uncommitted changes: commit first. The session " +
+    isolate: Schema.optional(Schema.Boolean.annotate({ description: "Run the session in its own git worktree so parallel sessions don't share files. Commit first: its worktree " +
+            "starts from your last commit and sees only committed files and project skills, not your uncommitted changes. The session " +
             "commits on a branch named courier/<its session ID> and names it in its report; merge that branch yourself.",
     })),
     native: Schema.optional(Schema.Boolean.annotate({
         description: "true starts the session as your OpenCode subagent: it leaves OpenCode's session lists for your subagent tab, the " +
             "person answers its permission requests and questions in the view of the nearest session above it that is not a " +
-            "subagent, usually the top one, and deleting your session deletes it. false starts a standalone session, whatever the " +
+            "subagent, usually the top one (only OpenCode's TUI or paired app shows them; under opencode run without --auto " +
+            "or a bare API client they are rejected or wait unseen), and deleting your session deletes it. false starts a standalone session, whatever the " +
             "plugin's nativeChildren option says; unset, that option decides. Refused with isolate: true, as a subagent runs in " +
             "its parent's directory.",
     })),
     group: Schema.optional(Schema.String.annotate({
         description: "A join group: start the sessions of one batch with the same name, and their reports are held and delivered " +
             "to you in one message once every one of them has reported and your turn has ended, instead of one turn per " +
-            "report. A blocked report, a question, a permission request or a failed turn still reaches you at once. Letters, " +
+            "report. A blocked report or a failed turn still reaches you at once, and so do a question and a permission request " +
+            "(at the top of the tree; below it they go to the top). Letters, " +
             "digits, dots, dashes and underscores, up to 60; the name is free again once the group has been delivered.",
     })),
 });
@@ -80,7 +78,6 @@ export const CleanupInput = Schema.Struct({
         description: "Remove it even with uncommitted changes or commits on no branch; that work is lost.",
     })),
 });
-/** Adds the tree's courier tools, each a direct tool rather than a code-mode one. */
 export function addTreeTools(tools, ports) {
     tools.add({
         name: "courier_spawn",
@@ -88,11 +85,13 @@ export function addTreeTools(tools, ports) {
         description: "Start a new OpenCode session on a task and return immediately. It runs on your model, unless you name a model or a " +
             "variant (reasoning effort) fit for the task. The session reports " +
             "back with courier_send, which wakes this session, and you are told if its turn fails or ends without a report " +
-            "instead, it waits for a permission or it asks a question. Give a batch of parallel sessions one group name to " +
+            "instead, or it waits for a permission or asks a question (at the top of the tree; below it they go to the top). " +
+            "Give a batch of parallel sessions one group name to " +
             "be woken once, with all their reports, instead of once per report. DO NOT poll it or call courier_children in a " +
             "loop: once you have started the sessions you need, end your turn by replying without calling more tools; each " +
-            "report, or each group's reports, starts a new turn in which you carry on. For long tasks, also courier_later a " +
-            "check-in for yourself in case it never reports, and courier_cancel it when it does.",
+            "report, or each group's reports, starts a new turn in which you carry on. For a long task or batch, also " +
+            "courier_later one check-in for yourself per group (per session when ungrouped) in case the reports never come, " +
+            "and courier_cancel it when they arrive: a report does not cancel it.",
         input: SpawnInput,
         execute: async (input, context) => {
             const child = await spawn(ports.courier, context.sessionID, input).catch(rethrow("courier_spawn"));
@@ -132,7 +131,8 @@ export function addTreeTools(tools, ports) {
         options: { codemode: false },
         description: "List the whole tree of sessions under this one (or under sessionID): every session started with courier_spawn " +
             "from it, directly or through others, each with its depth, what courier_children shows, and whether it still " +
-            "owes a report, sent progress, or ended without one. For a one-off look, not for waiting. A long tree lists at most " +
+            "owes a report, sent progress, or ended without one, and the subagents OpenCode's subagent tool started in it, " +
+            "marked subagent: true, which owe no report. For a one-off look, not for waiting. A long tree lists at most " +
             "maxTotal sessions, the live ones first, then the newest, and says how many older ones are left out.",
         input: TreeInput,
         execute: async (input, context) => {
@@ -143,8 +143,8 @@ export function addTreeTools(tools, ports) {
     tools.add({
         name: "courier_stop",
         options: { codemode: false },
-        description: "Stop a session you started, directly or through others, and every session under it: each running turn is " +
-            "interrupted, deepest first, and the messages scheduled for them with courier_later are cancelled. Use it when a " +
+        description: "Stop a session you started, directly or through others, and every session under it, subagents included: each " +
+            "running turn is interrupted, deepest first, and the messages scheduled for them with courier_later are cancelled. Use it when a " +
             "subtree went wrong or is no longer needed. They do not report back, and you are not told of what you stopped; a " +
             "session between you and the target is. A stopped session can be woken again with courier_send. With " +
             "cleanup: true their worktrees are removed too, unless they hold work that is on no branch.",

package/dist/tree/tui.d.ts

@@ -4,106 +4,62 @@ import { type Accessor } from "solid-js";
 import { type MascotState, type Token } from "./mascot.js";
 import { type Forgotten, type Row, type Stopped, type Summary, type Wait } from "./rpc.js";
 type Context = Plugin.Context;
-/**
- * The events after which a summary may read differently: a turn started or ended, a request or form, a session made, removed,
- * archived or unarchived.
- */
 export declare const CHANGES: Set<string>;
-/** How long after the first of a burst of changes the entry asks the server again. */
 export declare const SETTLE_MS = 250;
-/** The panel's settle: each of its asks reads every row's messages, so a busy tree is asked at most once a second. */
 export declare const PANEL_SETTLE_MS = 1000;
-/** The name of the tree panel in the `session.panel` slot. */
 export declare const PANEL = "courier-tree";
-/** How often the panel redraws its running times and how long ago each last tool call was. */
 export declare const TICK_MS = 1000;
-/** The panel's animation frame: the spinner's step, and how often a flash or the bar's easing moves. */
 export declare const FRAME_MS = 90;
-/** How long a row's background takes to fade back from its flash after its report arrives: the report's hold. */
 export declare const FLASH_MS = 1500;
-/** How long the header's bar takes to grow, or shrink, to its new length. */
 export declare const BAR_MS = 450;
-/** Whether the panel animates: unless the TUI part's options say `"animations": false`, as the plugin API has no TUI setting for it. */
 export declare function animationsOn(options: Readonly<Record<string, unknown>> | undefined): boolean;
-/** A value eased over the panel's frames by OpenTUI's `Timeline`; reading it in a computation follows the frames. */
 export type Tween = {
     readonly value: () => number;
     readonly done: () => boolean;
 };
-/**
- * The panel's one timer: a frame every `FRAME_MS` while a tween moves or an `animates` predicate holds, every `every` while
- * only slower ones do, none otherwise, with animations off or once the panel is gone. `frame` counts in `FRAME_MS`.
- */
 export type Motion = {
     readonly enabled: boolean;
     readonly frame: Accessor<number>;
     readonly animates: (when: Accessor<boolean>, every?: number) => void;
     readonly tween: (from: number, to: number, duration: number, ease: EasingFunctions) => Tween;
 };
-/** The panel's `Motion`, owned by the computation it is made in. */
 export declare function createMotion(enabled: boolean): Motion;
-/**
- * Each row's flash, by session, from a read of the rows to the next that finds its report turned to `reported`; not on
- * the first read. `strength` is a row's, 1 when its report arrives down to 0; `reported` holds for `FLASH_MS` after one.
- */
 export declare function createFlashes(motion: Motion, rows: Accessor<ReadonlyArray<Row>>): {
     strength: (sessionID: string) => number;
     reported: () => boolean;
 };
-/** The header bar's filled cells, eased over `BAR_MS` to its new length once it is shown, at once when it first is. */
 export declare function createBarFill(motion: Motion, counts: Accessor<{
     reported: number;
     started: number;
 }>): () => number;
-/** True for `FLASH_MS` after a read of the tree finds a session the one before it did not have; not on the first read. */
 export declare function createSpawns(motion: Motion, rows: Accessor<ReadonlyArray<Row> | undefined>): () => boolean;
-/**
- * Digby's state for the tree's rows and its `top`, by `summaryLine`'s priority, unless a report or a spawn just arrived;
- * gone when every row under the top is.
- */
 export declare function mascotState(rows: ReadonlyArray<Row>, { top, reported, spawned }?: {
     top?: Row;
     reported?: boolean;
     spawned?: boolean;
 }): MascotState;
-/** What the tree's sessions do, as the header's second line says it: "1 waiting on you · 2 running"; empty with none live. */
 export declare function countsLine(rows: ReadonlyArray<Row>): string;
-/** The panel's size below which it shows no header glyph, so the header keeps to one line and its bar is not cut. */
 export declare const GLYPH_ROWS = 12;
 export declare const GLYPH_COLUMNS = 54;
-/** The empty panel's height from which it shows the 16×16. */
 export declare const ART_ROWS = 14;
-/** The rows left free below the tree's last row from which the 16×16 shows there. */
 export declare const BELOW_ROWS = 10;
-/** `tint` over `rest` by `amount`, from 0 (all `rest`) to 1 (all `tint`). */
 export declare function blend(tint: RGBA, rest: RGBA, amount: number): RGBA;
-/**
- * The status entry's text, such as "courier 1 waiting on you · 2 running · group pair 1/2"; empty when there is nothing to show.
- * Within `maxWidth` it keeps whole parts, most important first, and counts the groups it drops: "· +2 groups".
- */
 export declare function summaryLine(summary: Summary, maxWidth?: number): string;
-/** A span of time, coarsest first: "45s", "3m 05s", "2h 07m". */
 export declare function duration(ms: number): string;
-/** How many of a session's children have reported, out of those it started, among the rows read. */
 export declare function parts(rows: ReadonlyArray<Row>, parentID: string): {
     reported: number;
     started: number;
 };
-/** How many of a bar's `width` cells are filled for the parts reported. */
 export declare function filledCells({ reported, started }: {
     reported: number;
     started: number;
 }, width?: number): number;
-/** A bar of parts reported, `width` cells wide: "[████░░░░░░] 2/5 reported"; `filled` cells of it while it eases to its length. */
 export declare function bar(counts: {
     reported: number;
     started: number;
 }, width?: number, filled?: number): string;
-/** What a paused session waits on, such as "asks permission: shell echo hi" or "shows a form: Web Search". */
 export declare function waitLine(wait: Wait): string;
-/** What a row's session is doing, its report and its group standing: "idle · reported done · group pair held". */
 export declare function statusLine(row: Row, now?: number): string;
-/** The parts of `statusLine`, each with the row part the panel colours it as. */
 export declare function statusParts(row: Row, now?: number): {
     text: string;
     kind: "state" | "report" | "plain";
@@ -115,72 +71,35 @@ type Feedback<Color> = {
         }>;
     };
 };
-/** The running mark's frames, one every `FRAME_MS`. */
 export declare const SPINNER: string[];
-/**
- * The one cell a row's state shows and its theme colour, the blank cell of one with no mark: this is the only place that
- * chooses them. A running row spins through `SPINNER` at the panel's `frame`, and shows `•` with none (animations off).
- */
 export declare function rowMark<Color>(row: Row, theme: Feedback<Color>, frame?: number): {
     mark: string;
     color: Color | undefined;
 };
-/** Past this fraction of its window, a session's context use is shown in the warning colour. */
 export declare const CONTEXT_WARN = 0.8;
-/** A leaf's activity: how long it has run, its last tool call and how long ago, its context use and its cost. */
 export declare function activityParts(row: Row, now: number): string[];
 export declare const activityLine: (row: Row, now: number) => string;
-/** What a stalled session's row, or the panel of one, says of it: "a message waits in its inbox since 2m 05s, woken again in vain". */
 export declare function stalledLine(since: number, now: number): string;
-/** The lines a row shows under its title: an orchestrator's bar, a paused or stalled session's wait, or else a live leaf's activity. */
 export declare function detailLines(row: Row, rows: ReadonlyArray<Row>, now: number): string[];
-/**
- * Each row's tree guides, by session, for rows in the order a tree is drawn, below depth `base`: before its mark ("│ ├ "),
- * and before its detail lines, which carry a line down to its first child ("│ │ ").
- */
 export declare function guides(rows: ReadonlyArray<Row>, base: number): Map<string, {
     row: string;
     detail: string;
 }>;
-/** How often the footer and the panel ask again with no event: the scheduler flags a stalled session without one. */
 export declare const REREAD_MS = 15000;
-/**
- * Adds the tree's entry to the prompt's footer: what the sessions under the open session do, asked of the RPC after each
- * change and every `REREAD_MS`; nothing on the home screen. Clicked while some wait on the person, it calls `onWaiting`.
- */
 export declare function addTreeStatus(ctx: Context, onWaiting?: (sessionID: string) => void): () => void;
-/** The toast after a stop: how many sessions were interrupted, and how many scheduled messages were cancelled. */
 export declare function stoppedLine({ stopped, cancelled }: Stopped): string;
-/** The toast after a forget, as courier_cleanup reports it: forgotten, its worktree removed or already gone, or kept and why. */
 export declare function forgottenLine(title: string, result: Forgotten): string;
-/** The one place Digby's pixel tokens take a theme colour. */
 export declare const digbyColours: (theme: Context["theme"]) => Record<Token, RGBA>;
-/**
- * A row's background at rest: the selection's while the panel has the keyboard, else one step quieter under the pointer,
- * else none, the panel's.
- */
 export declare function restBackground(theme: Context["theme"], { selected, hovered }: {
     selected: boolean;
     hovered: boolean;
 }): RGBA | undefined;
-/** The usage the `/courier` command shows for an input it does not know, before the further verbs' lines. */
 export declare const USAGE = "/courier tree opens the session tree; /courier stop [session] stops a session and those under it";
-/** A further verb of the `/courier` command, which another module's TUI part supplies: what it runs, and its line of the usage. */
 export type Verb = {
     readonly run: () => void;
     readonly usage: string;
 };
-/** The usage with the further verbs' lines. */
 export declare const usageWith: (verbs: Readonly<Record<string, Verb>>) => string;
-/**
- * Adds the tree panel to the `session.panel` slot, opened by `/courier tree` or the palette, which follows the person
- * between sessions until closed, and `/courier stop <session>`, which stops a session under the open one once confirmed;
- * `verbs` are the command's further verbs, by name.
- */
 export declare function addTreePanel(ctx: Context, verbs?: Readonly<Record<string, Verb>>): () => void;
-/**
- * Draws the person's attention when reports arrive: a join group's reports, released to the session that started them,
- * and a child's report to its parent, with the `subagent_done` sound. Read from the courier's own delivery metadata.
- */
 export declare function addTreeAttention(ctx: Context): () => void;
 export {};