opencode-courier 0.3.0 → 0.4.1

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/{tools.js → tree/tools.js}

@@ -1,16 +1,16 @@
 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 "./tree.js";
-import { describeFailure, listChildren, send, spawn, status } from "./courier.js";
-import { cancel, schedule } from "./later.js";
-import { answerText, cancelText, childrenText, cleanupText, laterText, REPLIES, sendText, spawnText, STATUSES, statusText, stopText, subscribeText, treeText, unsubscribeText, } from "./notices.js";
-import { answerQuestion, isQuestion } from "./question/index.js";
-import { answer } from "./relay.js";
-import { subscribe, unsubscribe } from "./webhook.js";
+import { tree } from "./subtree.js";
+import { childrenText, cleanupText, sendText, spawnText, statusText, stopText, treeText } from "./text.js";
 /**
- * The courier tools: their input schemas, descriptions, and what each returns. The descriptions are
- * model-facing like the texts in `notices.ts`, and snapshotted with them in `test/notices.test.ts`.
+ * 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." }),
@@ -67,69 +67,8 @@ export const CleanupInput = Schema.Struct({
         description: "Remove it even with uncommitted changes or commits on no branch; that work is lost.",
     })),
 });
-export const LaterInput = Schema.Struct({
-    message: Schema.String.annotate({ description: "The message to deliver." }),
-    delayMinutes: Schema.optional(
-    // Some models send the number as a string ("3", "3.0") whatever the schema says, and resend it
-    // unchanged after the error, so a string is accepted and schedule reads it as a number.
-    Schema.Union([Schema.Number, Schema.String]).annotate({
-        description: "Deliver this many minutes from now. Give this or at.",
-    })),
-    at: Schema.optional(Schema.String.annotate({ description: "Deliver at this ISO 8601 time. Give this or delayMinutes." })),
-    sessionID: Schema.optional(Schema.String.annotate({ description: "The session to deliver to; defaults to this one." })),
-});
-export const AnswerInput = Schema.Struct({
-    sessionID: Schema.String.annotate({ description: "The session you started that is waiting, as its notice names it." }),
-    requestID: Schema.String.annotate({ description: "The request id from the notice." }),
-    reply: Schema.optional(Schema.Literals(REPLIES).annotate({
-        description: "For a permission request: the choice the person made, once, always (only when the notice offers it) or reject.",
-    })),
-    message: Schema.optional(Schema.String.annotate({ description: "For a permission request, with reject: the person's reason, passed on with the refusal." })),
-    answers: Schema.optional(Schema.Array(Schema.Union([Schema.String, Schema.Array(Schema.String)])).annotate({
-        description: "For a question: one entry per question, in order, each the label the person chose or the text they gave, " +
-            "or a list of labels where the question allows several.",
-    })),
-});
-export const CancelInput = Schema.Struct({
-    id: Schema.String.annotate({ description: "The id courier_later returned." }),
-});
-export const SubscribeInput = Schema.Struct({
-    topic: Schema.String.annotate({
-        description: "owner/repo for every event of a GitHub repository, owner/repo#<number> for one pull request or issue " +
-            "(reviews, comments, completed CI runs), or a plain name for deliveries posted to /hook/<name>.",
-    }),
-    sessionID: Schema.optional(Schema.String.annotate({ description: "The session to subscribe; defaults to this one." })),
-});
-export const UnsubscribeInput = Schema.Struct({
-    topic: Schema.optional(Schema.String.annotate({ description: "The topic to drop; all of this session's when omitted." })),
-    sessionID: Schema.optional(Schema.String.annotate({ description: "The session to unsubscribe; defaults to this one." })),
-});
-const rethrow = (tool) => (error) => {
-    throw describeFailure(tool, error);
-};
-// One tool answers both: a question's id is the plugin's own, a permission request's OpenCode's.
-async function answerRequest(ports, callerID, input) {
-    const { sessionID, requestID } = input;
-    if (isQuestion(requestID)) {
-        if (input.reply !== undefined || input.message !== undefined)
-            throw new Error(`${requestID} is a question: pass the person's answers in answers, not reply or message.`);
-        if (input.answers === undefined)
-            throw new Error(`${requestID} is a question: answers is required, one entry per question.`);
-        return answerQuestion(ports.questions, callerID, { sessionID, requestID, answers: input.answers });
-    }
-    if (input.answers !== undefined)
-        throw new Error(`${requestID} is a permission request: pass the person's choice in reply (once, always or reject), not answers.`);
-    if (input.reply === undefined)
-        throw new Error(`${requestID} is a permission request: reply is required, once, always or reject.`);
-    return answer(ports.answer, ports.waiting, callerID, {
-        sessionID,
-        requestID,
-        reply: input.reply,
-        ...(input.message !== undefined ? { message: input.message } : {}),
-    });
-}
-/** Adds the courier tools, each a direct tool rather than a code-mode one. */
-export function addTools(tools, ports) {
+/** 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 },
@@ -218,80 +157,11 @@ export function addTools(tools, ports) {
             "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.",
+            "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 };
         },
     });
-    tools.add({
-        name: "courier_answer",
-        options: { codemode: false },
-        description: "Pass on the answer to a permission request or a question that a session you started with courier_spawn (or " +
-            "one started from it) waits on, after a notice from it named the request. The answer is the person's, not yours: " +
-            "first ask the person you are working with, offering the choices the notice lists, then call this with what " +
-            "they chose: reply for a permission request, answers for a question. Never choose for them. The session " +
-            "carries on once it has the answer.",
-        input: AnswerInput,
-        execute: async (input, context) => {
-            const result = await answerRequest(ports, context.sessionID, input).catch(rethrow("courier_answer"));
-            return { content: answerText(result), metadata: result };
-        },
-    });
-    tools.add({
-        name: "courier_later",
-        options: { codemode: false },
-        description: "Schedule a message for a session (this one by default), delivered when due and waking it if idle. " +
-            "Use it as a safety net when you start sessions: schedule one check-in, end your turn by replying without " +
-            "calling more tools, and cancel it with courier_cancel if the child reports first. Survives server restarts; " +
-            "may arrive up to ~15 seconds late.",
-        input: LaterInput,
-        execute: async (input, context) => {
-            const entry = await schedule(ports.later, context.sessionID, input).catch(rethrow("courier_later"));
-            const fireAt = new Date(entry.fireAt).toISOString();
-            return {
-                content: laterText(entry, fireAt, entry.sessionID === context.sessionID),
-                metadata: { id: entry.id, fireAt, sessionID: entry.sessionID },
-            };
-        },
-    });
-    tools.add({
-        name: "courier_cancel",
-        options: { codemode: false },
-        description: "Cancel a message scheduled with courier_later, e.g. because the child it was waiting for reported.",
-        input: CancelInput,
-        execute: async (input) => {
-            const cancelled = await cancel(ports.later, input.id).catch(rethrow("courier_cancel"));
-            return { content: cancelText(input.id, cancelled), metadata: { id: input.id, cancelled } };
-        },
-    });
-    tools.add({
-        name: "courier_subscribe",
-        options: { codemode: false },
-        description: "Wake a session (this one by default) when a webhook arrives for a topic: a GitHub repository, one of its " +
-            "pull requests or issues (reviews, comments, completed CI runs), or a named generic hook. Each matching " +
-            "delivery arrives as a message, queued behind any running turn. End your turn and wait; do not poll.",
-        input: SubscribeInput,
-        execute: async (input, context) => {
-            const sessionID = input.sessionID ?? context.sessionID;
-            const subscription = await subscribe(ports.hooks, sessionID, input.topic).catch(rethrow("courier_subscribe"));
-            const receiving = await ports.receiving();
-            return {
-                content: subscribeText(sessionID, subscription.topic, receiving),
-                metadata: { sessionID, topic: subscription.topic, receiver: receiving },
-            };
-        },
-    });
-    tools.add({
-        name: "courier_unsubscribe",
-        options: { codemode: false },
-        description: "Stop webhook deliveries for a topic, or all of a session's topics, e.g. once its pull request is merged.",
-        input: UnsubscribeInput,
-        execute: async (input, context) => {
-            const sessionID = input.sessionID ?? context.sessionID;
-            const dropped = await unsubscribe(ports.hooks, sessionID, input.topic).catch(rethrow("courier_unsubscribe"));
-            return { content: unsubscribeText(sessionID, dropped), metadata: { sessionID, dropped } };
-        },
-    });
 }

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 palette, which follows the person
+ * between sessions while open, and `/courier stop <session>`, which stops a session under the open one once confirmed.
+ */
+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;