opencode-courier 0.2.3 → 0.3.0

package/dist/roster.js

@@ -1,4 +1,6 @@
 import { existsSync } from "node:fs";
+import { dropMember } from "./group.js";
+import { forgetReport } from "./report.js";
 import { scanAll, scanEntries } from "./storage.js";
 /**
  * Entries older than this are dropped when their parent's roster is read, and on plugin setup,
@@ -7,10 +9,8 @@ import { scanAll, scanEntries } from "./storage.js";
 export const RETENTION_MS = 14 * 24 * 60 * 60_000;
 const PREFIX = "roster/";
 /**
- * The reverse index: under `roster-by-child/<sessionID>`, a child's `ReverseEntry`, written with its
- * roster entry. It is only an index: an entry without one, written by an older copy of the plugin,
- * is found by scanning `roster/`, and every entry it leads to is read from `roster/` to check that
- * it is still there.
+ * The reverse index: a child's `ReverseEntry` under `roster-by-child/<sessionID>`, written with its
+ * roster entry; only an index, so `roster/` is scanned for entries lacking one, and confirms a hit.
  */
 const BY_CHILD = "roster-by-child/";
 export function rosterKey(parentID, sessionID) {
@@ -37,17 +37,24 @@ function isReverse(value) {
     return Array.isArray(ancestors) && ancestors.length > 0 && ancestors.every((id) => typeof id === "string");
 }
 /**
- * Removes a child's roster entry and its reverse key. Only the entry's removal can fail it: a
- * reverse key left behind leads nowhere, and the next load drops it.
+ * Removes a child's roster entry, its reverse key, its report state and, given its group, its membership. Only
+ * the entry's removal can fail it: a reverse key left behind leads nowhere, and the next load drops it.
  */
-export async function remove(storage, parentID, sessionID) {
-    await Promise.all([storage.remove(rosterKey(parentID, sessionID)), storage.remove(reverseKey(sessionID)).catch(() => undefined)]);
+export async function remove(storage, parentID, sessionID, group) {
+    const [, , , dropped] = await Promise.all([
+        storage.remove(rosterKey(parentID, sessionID)),
+        storage.remove(reverseKey(sessionID)).catch(() => undefined),
+        forgetReport(storage, sessionID).catch(() => undefined),
+        group ? dropMember(storage, parentID, group, sessionID).catch(() => false) : false,
+    ]);
+    return { droppedFromGroup: dropped };
 }
 /** Removes a child from its parent's roster; false when it was not there. */
 export async function forget(storage, parentID, sessionID) {
-    if ((await storage.get(rosterKey(parentID, sessionID))) === undefined)
+    const entry = (await storage.get(rosterKey(parentID, sessionID)));
+    if (entry === undefined)
         return false;
-    await remove(storage, parentID, sessionID);
+    await remove(storage, parentID, sessionID, entry.group);
     return true;
 }
 /** A parent's children, oldest first. */
@@ -61,21 +68,42 @@ export async function allEntries(storage) {
 }
 /** A session's roster entries: one for the parent that started it, none if courier_spawn did not. */
 export async function entriesOf(storage, sessionID) {
-    const indexed = await storage.get(reverseKey(sessionID));
-    if (!isReverse(indexed))
+    const parentID = await indexedParent(storage, sessionID);
+    if (parentID === undefined)
         return (await scanAll(storage, PREFIX)).filter((entry) => entry.sessionID === sessionID);
-    const entry = await storage.get(rosterKey(indexed.ancestors[0], sessionID));
+    const entry = await storage.get(rosterKey(parentID, sessionID));
     return entry === undefined ? [] : [entry];
 }
+/** The session that started a session, by the reverse index alone, without scanning the roster. */
+export async function indexedParent(storage, sessionID) {
+    const indexed = await storage.get(reverseKey(sessionID));
+    return isReverse(indexed) ? indexed.ancestors[0] : undefined;
+}
+/** A session's roster entry under a parent, if it is there. */
+export async function entryUnder(storage, parentID, sessionID) {
+    return (await storage.get(rosterKey(parentID, sessionID)));
+}
+/** A session's roster entry, by the reverse index alone, without scanning the roster. */
+export async function indexedEntry(storage, sessionID) {
+    const parentID = await indexedParent(storage, sessionID);
+    return parentID === undefined ? undefined : entryUnder(storage, parentID, sessionID);
+}
 /**
- * The roster entries from a session up to the top, its own first: the session's, its parent's, and
- * so on, ending with the entry whose parent courier_spawn did not start. Empty when courier_spawn
- * did not start the session.
+ * The roster entries from a session up to the top, its own first, ending with the entry whose parent
+ * courier_spawn did not start; empty when courier_spawn did not start the session.
  */
 export async function lineage(storage, sessionID) {
     const first = await storage.get(reverseKey(sessionID));
     if (!isReverse(first))
         return lineageIn(await allEntries(storage), sessionID);
+    return walkIndex(storage, sessionID, first);
+}
+/** `lineage` by the reverse index alone: empty, without scanning the roster, when it does not name the session. */
+export async function indexedLineage(storage, sessionID) {
+    const first = await storage.get(reverseKey(sessionID));
+    return isReverse(first) ? walkIndex(storage, sessionID, first) : [];
+}
+async function walkIndex(storage, sessionID, first) {
     let indexed = first;
     const chain = [];
     let below = sessionID;
@@ -101,17 +129,22 @@ export async function lineage(storage, sessionID) {
 }
 /** `lineage` over roster entries already read. */
 export function lineageIn(entries, sessionID) {
-    const bySession = new Map(entries.map((entry) => [entry.sessionID, entry]));
+    return lineageBy(bySession(entries), sessionID);
+}
+/** Roster entries by their session, for `lineageBy`. */
+export function bySession(entries) {
+    return new Map(entries.map((entry) => [entry.sessionID, entry]));
+}
+/** `lineage` over roster entries already read and mapped by `bySession`. */
+export function lineageBy(bySession, sessionID) {
     const chain = [];
     for (let entry = bySession.get(sessionID); entry && !chain.includes(entry); entry = bySession.get(entry.parentID))
         chain.push(entry);
     return chain;
 }
 /**
- * The session at the top of a spawned session's lineage, where its permission requests and
- * questions go, since that is where the person is; only it may answer them. Throws when the
- * session was not started with courier_spawn or `callerID` is another session. `what` names
- * what is being answered.
+ * The top of a spawned session's lineage, where its permission requests and questions go, since the
+ * person is there. Throws unless the session was spawned and `callerID` is that top; `what` names it.
  */
 export async function answeringTop(storage, sessionID, callerID, what) {
     const chain = await lineage(storage, sessionID);
@@ -128,7 +161,7 @@ export async function answeringTop(storage, sessionID, callerID, what) {
  */
 async function dropExpired(storage, entries, now, exists) {
     const expired = new Set(entries.filter((entry) => now - entry.createdAt > RETENTION_MS && !(entry.isolated && exists(entry.directory))));
-    await Promise.all([...expired].map((entry) => remove(storage, entry.parentID, entry.sessionID)));
+    await Promise.all([...expired].map((entry) => remove(storage, entry.parentID, entry.sessionID, entry.group)));
     return entries.filter((entry) => !expired.has(entry));
 }
 /** A parent's children, oldest first, after dropping the expired ones. */
@@ -147,10 +180,8 @@ function indexes(value, entry) {
     return isReverse(value) && value.ancestors[0] === entry.parentID;
 }
 /**
- * Writes the reverse keys missing for the given entries, or naming another parent, all of the roster, such as those an older
- * copy of the plugin recorded, and drops the reverse keys whose entry is gone, such as those of an
- * entry an older copy removed. Keys that lead to their entry are left as they are, so running it
- * again changes nothing.
+ * Writes the reverse keys missing or stale for the given entries, or the whole roster, and drops those
+ * whose entry is gone, as an older copy's writes and removals leave them; a rerun changes nothing.
  */
 export async function backfill(storage, entries) {
     const indexed = new Map((await scanEntries(storage, BY_CHILD)).map(({ key, value }) => [key, value]));

package/dist/skill.d.ts

@@ -0,0 +1,13 @@
+import type { Plugin } from "@opencode/plugin";
+/** The editor OpenCode hands a skill transform. */
+export type SkillEditor = Parameters<Parameters<Plugin.Context["skill"]["transform"]>[0]>[0];
+/** The courier-orchestrate skill as OpenCode lists it: its id, name and description, and the text the model loads. */
+export declare const orchestrateSkill: () => {
+    readonly id: "courier-orchestrate";
+    readonly name: "courier-orchestrate";
+    readonly description: string;
+    readonly path: "/opencode-courier/courier-orchestrate.md";
+    readonly content: string;
+};
+/** Adds the courier-orchestrate skill; every instance adds the same one, under the same id. */
+export declare function addSkill(skills: SkillEditor): void;

package/dist/skill.js

@@ -0,0 +1,9 @@
+import { SKILL_CONTENT, SKILL_DESCRIPTION, SKILL_ID } from "./notices.js";
+/** A skill's path is where OpenCode would look for its files; this one has none, so a path of the plugin's own. */
+const SKILL_PATH = `/opencode-courier/${SKILL_ID}.md`;
+/** The courier-orchestrate skill as OpenCode lists it: its id, name and description, and the text the model loads. */
+export const orchestrateSkill = () => ({ id: SKILL_ID, name: SKILL_ID, description: SKILL_DESCRIPTION, path: SKILL_PATH, content: SKILL_CONTENT });
+/** Adds the courier-orchestrate skill; every instance adds the same one, under the same id. */
+export function addSkill(skills) {
+    skills.add(orchestrateSkill());
+}

package/dist/stop.d.ts

@@ -0,0 +1,41 @@
+import { type CleanupPorts } from "./cleanup.js";
+import { type CourierPorts } from "./courier.js";
+import { type LaterPorts } from "./later.js";
+import { type CleanupResult } from "./notices.js";
+export interface StopPorts {
+    readonly courier: CourierPorts;
+    readonly later: LaterPorts;
+    readonly cleanup: CleanupPorts;
+}
+export interface StopInput {
+    readonly sessionID: string;
+    readonly cleanup?: boolean;
+}
+/** What happened to one session: its turn was interrupted, it was not running, OpenCode no longer knows it, or the interrupt failed. */
+export interface Stopped {
+    readonly sessionID: string;
+    readonly title: string;
+    readonly depth: number;
+    readonly outcome: "interrupted" | "idle" | "gone" | "failed";
+    readonly error?: string;
+}
+export interface StopResult {
+    readonly sessionID: string;
+    /** Every session stopped, deepest first; the target is the last. */
+    readonly stopped: ReadonlyArray<Stopped>;
+    /** The ids of the courier_later messages cancelled. */
+    readonly cancelled: ReadonlyArray<string>;
+    /** With `cleanup`: what became of each isolated session's worktree, deepest first. */
+    readonly cleanup?: ReadonlyArray<CleanupResult | {
+        readonly sessionID: string;
+        readonly outcome: "failed";
+        readonly error: string;
+    }>;
+    /** The session told that the target was stopped, when that is not the caller. */
+    readonly told?: string;
+}
+/**
+ * Stops a session and everything under it, deepest first, and cancels the messages scheduled for them; only a session above the target may.
+ * The caller is not told; the target's parent is, unless that is the caller.
+ */
+export declare function stop(ports: StopPorts, callerID: string, input: StopInput): Promise<StopResult>;

package/dist/stop.js

@@ -0,0 +1,120 @@
+import { cleanup } from "./cleanup.js";
+import { describeFailure } from "./courier.js";
+import { isNotFound } from "./json.js";
+import { cancel, scheduledFor } from "./later.js";
+import { envelope, stoppedNotice } from "./notices.js";
+import { settled, stopped } from "./report.js";
+import { lineage } from "./roster.js";
+import { subtree } from "./tree.js";
+/** Rounds of looking again for sessions started while others were being stopped. */
+const ROUNDS = 3;
+/**
+ * Stops a session and everything under it, deepest first, and cancels the messages scheduled for them; only a session above the target may.
+ * The caller is not told; the target's parent is, unless that is the caller.
+ */
+export async function stop(ports, callerID, input) {
+    const { storage } = ports.courier;
+    const { sessionID } = input;
+    const chain = await lineage(storage, sessionID);
+    if (!chain.length)
+        throw new Error(`${sessionID} was not started with courier_spawn, so courier_stop cannot stop it.`);
+    const target = chain[0];
+    if (!chain.some((entry) => entry.parentID === callerID))
+        throw new Error(`${callerID} is not above ${sessionID}: only a session above it, in the line of sessions that started it with courier_spawn, can stop it.`);
+    const seen = new Set();
+    const nodes = [];
+    const results = [];
+    const cancelled = [];
+    const round = async (pending, left) => {
+        if (!pending.length || left === 0)
+            return;
+        for (const node of pending)
+            seen.add(node.entry.sessionID);
+        nodes.push(...pending);
+        // Before any interrupt, so nothing scheduled wakes a session that was just stopped.
+        await Promise.all(pending.map((node) => silence(ports, node.entry.sessionID, cancelled)));
+        results.push(...(await eachDeepestFirst(pending, (node) => interrupt(ports, node))));
+        const meanwhile = (await subtree(storage, sessionID)).nodes.filter((node) => !seen.has(node.entry.sessionID));
+        return round(meanwhile, left - 1);
+    };
+    await round([{ entry: target, depth: 0 }, ...(await subtree(storage, sessionID)).nodes], ROUNDS);
+    const told = target.parentID !== callerID && results.find((one) => one.sessionID === sessionID)?.outcome === "interrupted"
+        ? await tell(ports, callerID, target)
+        : undefined;
+    return {
+        sessionID,
+        stopped: results,
+        cancelled,
+        ...(input.cleanup ? { cleanup: await removeWorktrees(ports, nodes) } : {}),
+        ...(told ? { told } : {}),
+    };
+}
+/** Runs `act` on the nodes level by level, the deepest level first and the level's nodes at once; the results in that order. */
+function eachDeepestFirst(nodes, act) {
+    const depths = [...new Set(nodes.map((node) => node.depth))].sort((a, b) => b - a);
+    return depths.reduce((before, depth) => before.then(async (done) => [...done, ...(await Promise.all(nodes.filter((node) => node.depth === depth).map(act)))]), Promise.resolve([]));
+}
+/** Notes that a session was stopped, so the failure and silent-end notices stay quiet for it, and cancels its pending messages. */
+async function silence(ports, sessionID, cancelled) {
+    const { storage, now, log } = ports.courier;
+    await stopped(storage, sessionID, now()).catch((error) => log(`courier_stop: could not note that ${sessionID} was stopped: ${String(error)}`));
+    try {
+        const pending = await scheduledFor(storage, sessionID);
+        const dropped = await Promise.all(pending.map(async (later) => ((await cancel(ports.later, later.id)) ? later.id : undefined)));
+        cancelled.push(...dropped.filter((id) => id !== undefined));
+    }
+    catch (error) {
+        log(`courier_stop: could not cancel the messages scheduled for ${sessionID}: ${String(error)}`);
+    }
+}
+async function interrupt(ports, { entry, depth }) {
+    const { sessionID, title } = entry;
+    const { storage, session, now } = ports.courier;
+    try {
+        const { interrupted } = await session.interrupt({ sessionID });
+        // The event for it says so too; noted here as well, so the end is settled when this returns.
+        if (interrupted)
+            await settled(storage, sessionID, "interrupted", now()).catch(() => undefined);
+        return { sessionID, title, depth, outcome: interrupted ? "interrupted" : "idle" };
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return { sessionID, title, depth, outcome: "gone" };
+        return { sessionID, title, depth, outcome: "failed", error: describeFailure("session.interrupt", error).message };
+    }
+}
+/** Tells the target's parent, which is below the caller, that it was stopped; undefined when that could not be done. */
+async function tell(ports, callerID, target) {
+    const { session, log } = ports.courier;
+    try {
+        await session.synthetic({
+            sessionID: target.parentID,
+            text: envelope(target.sessionID, stoppedNotice(target.title, callerID), { ended: "stopped" }),
+            description: `Session ${target.sessionID} was stopped`,
+            metadata: { source: "courier", from: target.sessionID, ended: "stopped" },
+            delivery: "steer",
+        });
+        return target.parentID;
+    }
+    catch (error) {
+        log(`courier_stop: could not tell ${target.parentID} that ${target.sessionID} was stopped: ${String(error)}`);
+        return undefined;
+    }
+}
+/** Removes the isolated sessions' worktrees, deepest first, through courier_cleanup's checks; a failure is reported, not thrown. */
+async function removeWorktrees(ports, nodes) {
+    // One at a time: git locks the repository's worktree list while it removes one.
+    const removeNext = async (queue, done) => {
+        const [next, ...rest] = queue;
+        if (!next)
+            return done;
+        const { entry } = next;
+        const result = await cleanup(ports.cleanup, entry.parentID, { sessionID: entry.sessionID }).catch((error) => ({
+            sessionID: entry.sessionID,
+            outcome: "failed",
+            error: describeFailure("courier_cleanup", error).message,
+        }));
+        return removeNext(rest, [...done, result]);
+    };
+    return removeNext(nodes.filter((node) => node.entry.isolated).sort((a, b) => b.depth - a.depth), []);
+}

package/dist/tools.d.ts

@@ -1,6 +1,7 @@
 import type { Plugin } from "@opencode/plugin";
 import { Schema } from "effect";
 import { type CleanupPorts } from "./cleanup.js";
+import { type StopPorts } from "./stop.js";
 import { type CourierPorts } from "./courier.js";
 import { type LaterPorts } from "./later.js";
 import { type QuestionPorts } from "./question/index.js";
@@ -15,10 +16,21 @@ export declare const SpawnInput: Schema.Struct<{
     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<{
@@ -27,6 +39,13 @@ export declare const StatusInput: Schema.Struct<{
 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>;
@@ -61,6 +80,7 @@ export type ToolEditor = Parameters<Parameters<Plugin.Context["tool"]["transform
 export interface ToolPorts {
     readonly courier: CourierPorts;
     readonly cleanup: CleanupPorts;
+    readonly stop: StopPorts;
     readonly later: LaterPorts;
     readonly answer: AnswerPorts;
     readonly questions: QuestionPorts;

package/dist/tools.js

@@ -1,8 +1,10 @@
 import { Schema } from "effect";
 import { cleanup } from "./cleanup.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, statusText, subscribeText, unsubscribeText, } from "./notices.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";
@@ -14,11 +16,33 @@ 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." })),
+    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({
@@ -27,8 +51,18 @@ export const StatusInput = Schema.Struct({
 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 isolated child whose worktree to remove." }),
+    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.",
     })),
@@ -100,11 +134,12 @@ export function addTools(tools, ports) {
         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 instead, it waits for a " +
-            "permission or it asks a question. 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 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.",
+            "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"));
@@ -115,11 +150,15 @@ export function addTools(tools, ports) {
         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, or to steer a session you started.",
+            "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), metadata: delivered };
+            return { content: sendText(input.sessionID, delivered), metadata: delivered };
         },
     });
     tools.add({
@@ -136,7 +175,8 @@ export function addTools(tools, ports) {
     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, e.g. after a " +
+        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) => {
@@ -144,12 +184,41 @@ export function addTools(tools, ports) {
             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.",
+            "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.",
         input: CleanupInput,
         execute: async (input, context) => {
             const result = await cleanup(ports.cleanup, context.sessionID, input).catch(rethrow("courier_cleanup"));

package/dist/tree.d.ts

@@ -0,0 +1,102 @@
+import { type CourierPorts } from "./courier.js";
+import { type RosterEntry, type RosterStorage } from "./roster.js";
+/** A session below the one a subtree is read from, with how many levels below it is: a child is at depth 1. */
+export interface Below {
+    readonly entry: RosterEntry;
+    readonly depth: number;
+}
+/**
+ * The sessions started from a session, directly or through others, read one prefix scan per parent, at most `max`
+ * (`truncated` if more), in the order a tree is drawn.
+ */
+export declare function subtree(storage: RosterStorage, rootID: string, max?: number): Promise<{
+    nodes: Below[];
+    truncated: boolean;
+}>;
+/**
+ * The subtree under a session, at most `maxTotal` sessions: what courier_children shows of each, plus its depth,
+ * its parent and its report state.
+ */
+export declare function tree(ports: CourierPorts, rootID: string): Promise<{
+    truncated?: number | undefined;
+    sessionID: string;
+    sessions: ({
+        report?: {
+            status?: "done" | "partial" | "blocked" | "failed" | undefined;
+            owes: boolean;
+            progressed: boolean;
+            ended: boolean;
+        } | undefined;
+        parentID: string;
+        depth: number;
+        group: {
+            name: string;
+            report: string;
+        };
+        directory: string;
+        isolated: boolean;
+        created: number;
+        sessionID?: string | undefined;
+        title?: string | undefined;
+        outcome?: "failed" | "interrupted" | "succeeded" | undefined;
+        updated?: number | undefined;
+        idle?: number | undefined;
+        lastText?: string | undefined;
+        pending?: readonly import("./courier.js").Pending[] | undefined;
+    } | {
+        report?: {
+            status?: "done" | "partial" | "blocked" | "failed" | undefined;
+            owes: boolean;
+            progressed: boolean;
+            ended: boolean;
+        } | undefined;
+        parentID: string;
+        depth: number;
+        group?: undefined;
+        directory: string;
+        isolated: boolean;
+        created: number;
+        sessionID?: string | undefined;
+        title?: string | undefined;
+        outcome?: "failed" | "interrupted" | "succeeded" | undefined;
+        updated?: number | undefined;
+        idle?: number | undefined;
+        lastText?: string | undefined;
+        pending?: readonly import("./courier.js").Pending[] | undefined;
+    } | {
+        report?: {
+            status?: "done" | "partial" | "blocked" | "failed" | undefined;
+            owes: boolean;
+            progressed: boolean;
+            ended: boolean;
+        } | undefined;
+        parentID: string;
+        depth: number;
+        error: string;
+        group: {
+            name: string;
+            report: string;
+        };
+        directory: string;
+        isolated: boolean;
+        created: number;
+        sessionID: string;
+        title: string;
+    } | {
+        report?: {
+            status?: "done" | "partial" | "blocked" | "failed" | undefined;
+            owes: boolean;
+            progressed: boolean;
+            ended: boolean;
+        } | undefined;
+        parentID: string;
+        depth: number;
+        error: string;
+        group?: undefined;
+        directory: string;
+        isolated: boolean;
+        created: number;
+        sessionID: string;
+        title: string;
+    })[];
+}>;