opencode-courier 0.2.3 → 0.4.0

package/dist/tree/text.js

@@ -0,0 +1,287 @@
+/** 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, END_TURN, SKILL_ID, SPLIT_LINE, STATUSES } from "../kernel/protocol.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.`,
+        "",
+        `When you finish, send exactly one report: call courier_send with sessionID "${parentID}", a short account of what you did and ` +
+            "status done, partial (say what is left and why) or failed (say what went wrong). Add artifacts where there are any: " +
+            "branch, commits, files, checks (each command you ran and its result).",
+        "If you need a decision from the session that started you, which you cannot make yourself, send status blocked with a " +
+            "concrete ask, then end your turn and wait for its answer; never end quietly.",
+        "A report with a status wakes the parent and is the only way it hears from you, so do not end without sending one. " +
+            "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 need the person to decide something, use your question tool; it reaches them through the session that started you.",
+        "",
+        ...(branch ? [...isolationRule(branch, depth < limits.maxDepth), ""] : []),
+        ...splitRule(parentID, depth, limits),
+        "",
+        "Task:",
+        task,
+    ].join("\n");
+}
+function isolationRule(branch, mayPass) {
+    return [
+        "You work in a git worktree of your own, on a detached HEAD. Commit your work on the branch " +
+            `${branch}: create it first (git switch -c ${branch}), and name it in the branch of your report's artifacts, so the ` +
+            "session that started you can merge it. Uncommitted work is not in your report.",
+        ...(mayPass
+            ? [
+                `If you split your task and start a session with isolate: true, commit first: its worktree starts from your current HEAD, ` +
+                    "not from your uncommitted changes. Merge each branch it reports into yours before you report.",
+            ]
+            : []),
+    ];
+}
+function splitRule(parentID, depth, limits) {
+    if (depth >= limits.maxDepth)
+        return [`You are at depth ${depth}, the deepest the session tree goes, so you cannot start sessions: do the task yourself.`];
+    return [
+        `You are at depth ${depth} of a session tree that goes at most ${limits.maxDepth} deep. Split your task or do it yourself:`,
+        "- Split it when it has 2 or more independent parts, each substantial and touching separate files or areas: start one " +
+            `session per part with courier_spawn, at most ${limits.maxChildren} of yours running at once and ${limits.maxTotal} in the whole tree.`,
+        "- Do it yourself when it is small, sequential or tightly coupled. Never start exactly one session.",
+        `- Say which in one line of your reply: ${SPLIT_LINE}.`,
+        "- If you split, you orchestrate: end your turn while they work, check and integrate each part yourself when it " +
+            `reports (never hand that checking to another session), then send ${parentID} one combined report.`,
+    ];
+}
+/** How every part the context hook adds begins, so a second copy of the plugin does not add its own. */
+export const ROLE_PREFIX = "opencode-courier 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.`;
+    if (depth === null)
+        return (`${ROLE_PREFIX} root, no sessions started yet. Before a task that touches several files or areas, load the ` +
+            `${SKILL_ID} skill and decide whether to split it across sessions (doing it yourself is fine), and say ` +
+            `which in one line of your reply: ${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.`);
+    if (depth < maxDepth)
+        return (`${ROLE_PREFIX} sub-orchestrator, at depth ${depth} of at most ${maxDepth}. 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.");
+}
+// 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.`;
+/** 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) => {
+        const command = str(obj(check).command)?.trim();
+        return command ? [`  - ${command}: ${str(obj(check).result)?.trim() || "(no result given)"}`] : [];
+    });
+    const lines = [
+        ...listed("branch", strings([given.branch])),
+        ...listed("commits", strings(given.commits)),
+        ...listed("files", strings(given.files)),
+        ...(checks.length ? ["- checks:", ...checks] : []),
+    ];
+    return lines.length ? [message, "", "Artifacts:", ...lines].join("\n") : message;
+}
+// Tool results.
+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."
+            : "") +
+        (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 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.";
+    return (`Started session ${child.sessionID} in ${child.directory}. ${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. */
+export function sendText(sessionID, sent = {}) {
+    const status = sent.status ? `, status ${sent.status}` : "";
+    if (sent.held) {
+        const { group, reported, members } = sent.held;
+        const counted = reported !== undefined && members !== undefined;
+        let when = `once ${sessionID}'s turn has ended, yours being the last.`;
+        if (!counted || reported < members) {
+            const have = counted ? ` (${reported} of ${members} have)` : "";
+            when = `once every member of the group has reported${have}. Nothing more is needed from you for it.`;
+        }
+        return `Recorded as your report${status}. It is held with group "${group}" and goes to ${sessionID} in one message with the group's other reports, ${when} ${END_TURN}`;
+    }
+    if (sent.report === true)
+        return `Delivered to ${sessionID} as your report${status}. ${END_TURN}`;
+    if (sent.report === false)
+        return `Delivered to ${sessionID}. Without a status it is progress, not your report: when you finish, send one with status ${STATUS_LIST}.`;
+    return `Delivered to ${sessionID}.`;
+}
+/** courier_status's result: the session's state, as JSON. */
+export const statusText = (status) => JSON.stringify(status, null, 2);
+export const childrenText = (listed) => listed.length ? JSON.stringify(listed, null, 2) : "No sessions started with courier_spawn.";
+export function cleanupText(result) {
+    if (result.outcome === "kept")
+        return `Kept the worktree ${result.directory} of ${result.sessionID}: it has ${result.reason}. Commit or branch what you want to keep, or call courier_cleanup again with force: true to discard it.`;
+    const done = {
+        removed: `Removed the worktree ${result.directory} of ${result.sessionID}.`,
+        gone: `The worktree ${result.directory} of ${result.sessionID} was already gone; dropped it from courier_children.`,
+        forgotten: `${result.sessionID} ran in ${result.directory}, with no worktree of its own to remove; dropped it from courier_children.`,
+    }[result.outcome];
+    if (!result.group)
+        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.";
+    const note = tree.truncated === undefined ? "" : `\nOnly the first ${tree.truncated} sessions are listed (maxTotal); courier_tree on one of them 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. */
+export function stopText(result) {
+    const interrupted = result.stopped.filter((one) => one.outcome === "interrupted").length;
+    const failed = result.stopped.filter((one) => one.outcome === "failed");
+    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 + ")" : ""}`),
+        ...(failed.length ? ["Those that failed may still run: try courier_stop again."] : []),
+        result.cancelled.length
+            ? `Cancelled ${count(result.cancelled.length, "scheduled message")}: ${result.cancelled.join(", ")}.`
+            : "No scheduled messages were pending for them.",
+        ...(result.told ? [`Told ${result.told}, which started ${result.sessionID}, that it was stopped.`] : []),
+        ...(result.cleanup ? worktreeLines(result.cleanup) : []),
+    ].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."];
+    return cleanup.map((one) => one.outcome === "failed"
+        ? `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)})` : "",
+        state.commits.length
+            ? `${count(state.commits.length, "commit")} on no branch, tag or remote (${preview(state.commits)})`
+            : "",
+    ].filter(Boolean);
+    return reasons.length ? reasons.join(" and ") : undefined;
+}
+function count(n, noun) {
+    return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+function preview(items) {
+    return items.length > 5 ? `${items.slice(0, 5).join(", ")}, ...` : items.join(", ");
+}
+// Turn failures.
+export function failureNotice(title, error, group) {
+    const status = error.status === undefined ? "" : `, status ${error.status}`;
+    return [
+        `This session, "${title}", which you started with courier_spawn, failed: ${error.message} (${error.type}${status}).`,
+        "Its turn ended without finishing, so it will not report back on its own.",
+        "Message it with courier_send to have it try again, start a replacement, or carry on without it.",
+        ...(group
+            ? [
+                `It is a member of group "${group}", which no longer waits for it: its other members' reports reach you once they have ` +
+                    "reported and your turn has ended, and if it reports after all before then, its report joins them.",
+            ]
+            : []),
+    ].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.
+ */
+export function silentNotice(title, lastText, progressed = false, group) {
+    const reply = lastText?.trim();
+    return [
+        `This session, "${title}", which you started with courier_spawn, ended its turn without reporting back with courier_send, and does nothing more on its own.`,
+        ...(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."]),
+        "",
+        "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.",
+        "Until it reports, it counts toward your limits on the sessions you run at once.",
+        ...(group
+            ? [
+                `It is a member of group "${group}", whose other reports are held until it reports: have it report, as above, so the group ` +
+                    "reaches you, or, if you no longer need its report, drop it with courier_cleanup, which releases the group without it.",
+            ]
+            : []),
+    ].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;
+        return n ? [`${n} ${status}`] : [];
+    }).join(", ");
+}
+const LEFT_HOW = {
+    failed: "its turn failed",
+    interrupted: "its turn was interrupted",
+    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) => [
+        "",
+        `[${index + 1}/${reports.length}] ${report.sessionID} "${report.title}": ${report.status}`,
+        reportBody(report.message, report.artifacts),
+    ]);
+    const named = left.map((member) => `${member.sessionID} "${member.title}" (${LEFT_HOW[member.by]})`).join(", ");
+    const without = left.length ? ["", `Without a report: ${named}.`] : [];
+    const missing = left.length ? `, ${count(left.length, "member")} without a report, named at the end` : "";
+    return [
+        `Group "${group}" is complete: ${count(reports.length, "report")} of ${count(total, "member")} (${statusCounts(reports)})${missing}. Each report follows, with its status.`,
+        ...listed,
+        ...without,
+        "",
+        "Check and integrate each one yourself. The sessions that reported are idle; message one with courier_send if it has more to do.",
+    ].join("\n");
+}

package/dist/tree/tools.d.ts

@@ -0,0 +1,54 @@
+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>;
+    readonly agent: Schema.optional<Schema.String>;
+    readonly isolate: Schema.optional<Schema.Boolean>;
+    readonly group: Schema.optional<Schema.String>;
+}>;
+export declare const SendInput: Schema.Struct<{
+    readonly sessionID: Schema.String;
+    readonly message: Schema.String;
+    readonly status: Schema.optional<Schema.Literals<readonly ["done", "partial", "blocked", "failed"]>>;
+    readonly artifacts: Schema.optional<Schema.Struct<{
+        readonly branch: Schema.optional<Schema.String>;
+        readonly commits: Schema.optional<Schema.$Array<Schema.String>>;
+        readonly files: Schema.optional<Schema.$Array<Schema.String>>;
+        readonly checks: Schema.optional<Schema.$Array<Schema.Struct<{
+            readonly command: Schema.String;
+            readonly result: Schema.String;
+        }>>>;
+    }>>;
+    readonly queue: Schema.optional<Schema.Boolean>;
+}>;
+export declare const StatusInput: Schema.Struct<{
+    readonly sessionID: Schema.String;
+}>;
+export declare const ChildrenInput: Schema.Struct<{
+    readonly sessionID: Schema.optional<Schema.String>;
+}>;
+export declare const TreeInput: Schema.Struct<{
+    readonly sessionID: Schema.optional<Schema.String>;
+}>;
+export declare const StopInput: Schema.Struct<{
+    readonly sessionID: Schema.String;
+    readonly cleanup: Schema.optional<Schema.Boolean>;
+}>;
+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

@@ -0,0 +1,167 @@
+import { Schema } from "effect";
+import { STATUSES } from "../kernel/protocol.js";
+import { rethrow } from "../kernel/tool.js";
+import { cleanup } from "./cleanup.js";
+import { send } from "./send.js";
+import { spawn } from "./spawn.js";
+import { listChildren, status } from "./status.js";
+import { stop } from "./stop.js";
+import { tree } from "./subtree.js";
+import { childrenText, cleanupText, sendText, spawnText, statusText, 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." })),
+    agent: Schema.optional(Schema.String.annotate({ description: "Agent to run the session with; defaults to the default agent." })),
+    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 " +
+            "commits on a branch named courier/<its session ID> and names it in its report; merge that branch yourself.",
+    })),
+    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, " +
+            "digits, dots, dashes and underscores, up to 60; the name is free again once the group has been delivered.",
+    })),
+});
+export const SendInput = Schema.Struct({
+    sessionID: Schema.String.annotate({ description: "The session to deliver to." }),
+    message: Schema.String.annotate({ description: "The message text." }),
+    status: Schema.optional(Schema.Literals(STATUSES).annotate({
+        description: "For a report to the session that started you: done, partial (some of the task is left), blocked (you need a " +
+            "decision from it; say what) or failed. A message without a status is progress, not your report.",
+    })),
+    artifacts: Schema.optional(Schema.Struct({
+        branch: Schema.optional(Schema.String.annotate({ description: "The branch your work is on." })),
+        commits: Schema.optional(Schema.Array(Schema.String).annotate({ description: "The commits you made, as short hashes or subjects." })),
+        files: Schema.optional(Schema.Array(Schema.String).annotate({ description: "The files you changed." })),
+        checks: Schema.optional(Schema.Array(Schema.Struct({
+            command: Schema.String.annotate({ description: "A command you ran, such as a test suite or a linter." }),
+            result: Schema.String.annotate({ description: "What it gave, in a few words." }),
+        })).annotate({ description: "The checks you ran and their results." })),
+    }).annotate({ description: "With a report: what you produced, listed in the message after your text in a fixed layout." })),
+    queue: Schema.optional(Schema.Boolean.annotate({ description: "Wait until the target's current turn ends instead of steering it now." })),
+});
+export const StatusInput = Schema.Struct({
+    sessionID: Schema.String.annotate({ description: "The session to look at." }),
+});
+export const ChildrenInput = Schema.Struct({
+    sessionID: Schema.optional(Schema.String.annotate({ description: "The session whose children to list; defaults to this one." })),
+});
+export const TreeInput = Schema.Struct({
+    sessionID: Schema.optional(Schema.String.annotate({ description: "The session whose subtree to list; defaults to this one." })),
+});
+export const StopInput = Schema.Struct({
+    sessionID: Schema.String.annotate({ description: "The session to stop, with every session under it. It must have been started, directly or through others, from this one." }),
+    cleanup: Schema.optional(Schema.Boolean.annotate({
+        description: "Also remove the worktrees of the stopped sessions that ran in one of their own, as courier_cleanup does: " +
+            "one with uncommitted changes or commits on no branch is kept and listed.",
+    })),
+});
+export const CleanupInput = Schema.Struct({
+    sessionID: Schema.String.annotate({ description: "The session you started to drop, with its worktree if it is isolated." }),
+    force: Schema.optional(Schema.Boolean.annotate({
+        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",
+        options: { codemode: false },
+        description: "Start a new OpenCode session on a task and return immediately. It runs on your model. 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 " +
+            "be woken once, with all their reports, instead of once per report. DO NOT poll it or call courier_status 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.",
+        input: SpawnInput,
+        execute: async (input, context) => {
+            const child = await spawn(ports.courier, context.sessionID, input).catch(rethrow("courier_spawn"));
+            return { content: spawnText(child), metadata: child };
+        },
+    });
+    tools.add({
+        name: "courier_send",
+        options: { codemode: false },
+        description: "Deliver a message to another OpenCode session. If that session is idle, OpenCode starts a new turn for it. " +
+            "Use it to report back to the session that started you, with a status (done, partial, blocked or failed) and " +
+            "the artifacts you produced, or to steer a session you started. The status is carried as an attribute of the " +
+            "message; without one, a message to the session that started you is progress, not your report. If you were " +
+            "started in a group, a report with status done, partial or failed is held and delivered with the group's other " +
+            "reports; the result says so, and nothing more is needed from you.",
+        input: SendInput,
+        execute: async (input, context) => {
+            const delivered = await send(ports.courier, context.sessionID, input).catch(rethrow("courier_send"));
+            return { content: sendText(input.sessionID, delivered), metadata: delivered };
+        },
+    });
+    tools.add({
+        name: "courier_status",
+        options: { codemode: false },
+        description: "Look once at a session's state and its last reply, e.g. on a scheduled check-in. Not for waiting: " +
+            "sessions you started report back on their own.",
+        input: StatusInput,
+        execute: async (input) => {
+            const result = await status(ports.courier, input).catch(rethrow("courier_status"));
+            return { content: statusText(result), metadata: result };
+        },
+    });
+    tools.add({
+        name: "courier_children",
+        options: { codemode: false },
+        description: "List the sessions this one started with courier_spawn, with each one's state and last reply, and for one " +
+            "started in a group, its group and whether its report is held, still out, or released, e.g. after a " +
+            "compaction or restart. Like courier_status, for a one-off look, not for waiting.",
+        input: ChildrenInput,
+        execute: async (input, context) => {
+            const listed = await listChildren(ports.courier, input.sessionID || context.sessionID).catch(rethrow("courier_children"));
+            return { content: childrenText(listed), metadata: { children: listed } };
+        },
+    });
+    tools.add({
+        name: "courier_tree",
+        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; long trees are cut at maxTotal sessions.",
+        input: TreeInput,
+        execute: async (input, context) => {
+            const result = await tree(ports.courier, input.sessionID || context.sessionID).catch(rethrow("courier_tree"));
+            return { content: treeText(result), metadata: result };
+        },
+    });
+    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 " +
+            "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.",
+        input: StopInput,
+        execute: async (input, context) => {
+            const result = await stop(ports.stop, context.sessionID, input).catch(rethrow("courier_stop"));
+            return { content: stopText(result), metadata: result };
+        },
+    });
+    tools.add({
+        name: "courier_cleanup",
+        options: { codemode: false },
+        description: "Remove the git worktree of a session you started with isolate: true, once you have what you need from it, " +
+            "and drop it from courier_children. A worktree with uncommitted changes or commits on no branch is kept and " +
+            "the result lists them; commit or branch what you want, or pass force: true to discard it. A session without " +
+            "isolate has no worktree and is only dropped from courier_children. Either way, one in a join group that has not " +
+            "reported is dropped from it, so the group's other reports reach you without it; use this for a member you no " +
+            "longer need a report from. It never deletes the session itself, nor the sessions it started.",
+        input: CleanupInput,
+        execute: async (input, context) => {
+            const result = await cleanup(ports.cleanup, context.sessionID, input).catch(rethrow("courier_cleanup"));
+            return { content: cleanupText(result), metadata: result };
+        },
+    });
+}

package/dist/tree/tui.d.ts

@@ -0,0 +1,53 @@
+import type { Plugin } from "@opencode/plugin/tui";
+import { type Row, type Stopped, type Summary, type Wait } from "./rpc.js";
+type Context = Plugin.Context;
+/** 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 status entry's text, such as "courier 2 running · 1 waiting on you · group pair 1/2"; empty when there is nothing to show. */
+export declare function summaryLine(summary: Summary): 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;
+};
+/** A bar of parts reported, `width` cells wide: "[████░░░░░░] 2/5 reported". */
+export declare function bar({ reported, started }: {
+    reported: number;
+    started: number;
+}, width?: number): string;
+/** What a paused session waits on, such as "asks permission: shell echo hi". */
+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): string;
+/** A leaf's activity: how long it has run, its last tool call and how long ago, and its cost. */
+export declare function activityLine(row: Row, now: number): string;
+/** The lines a row shows under its title: an orchestrator's bar, a paused session's requests, or else a live leaf's activity. */
+export declare function detailLines(row: Row, rows: ReadonlyArray<Row>, now: number): string[];
+/**
+ * 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; nothing on the home screen. Clicked while some wait on the person, it calls `onWaiting` with the open session.
+ */
+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 usage the `/courier` command shows for an input it does not know. */
+export declare const USAGE = "/courier tree opens the session tree; /courier stop [session] stops a session and those under it";
+/**
+ * Adds the tree panel to the `session.panel` slot, opened by `/courier tree` or the command palette, and `/courier
+ * stop <session>`, which stops a session under the open one after the person confirms.
+ */
+export declare function addTreePanel(ctx: Context): () => 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 {};

package/dist/tui.d.ts

@@ -0,0 +1,3 @@
+import { Plugin } from "@opencode/plugin/tui";
+declare const _default: Plugin.Definition;
+export default _default;