opencode-courier 0.2.3 → 0.3.0

package/README.md

@@ -73,17 +73,19 @@ it adds:
 - **Webhooks:** GitHub reviews, comments and CI runs, or any signed POST, wake the
   [subscribed](#webhooks) session.
 - **Worktree isolation:** `isolate: true` gives a child its own git worktree, so children can edit
-  files in parallel.
+  files in parallel. An isolated child that splits hands its committed work down: its isolated
+  children start from its HEAD, and each isolated child commits on `courier/<its session ID>` and
+  reports that branch for its parent to merge ([nested isolation](docs/reference.md#nested-isolation)).
 - **Relaying to you:** a child's permission requests and questions reach you through the parent,
   and your answers go back; a form only you can answer is pointed out to you.
 
 ## How it works
 
 A parent session calls `courier_spawn`, gets a session id back immediately and ends its turn. The
-child works on its own and, when it is done or stuck, calls `courier_send` with the parent's id.
-That message lands in the parent's inbox and OpenCode starts a new turn for the parent if it is
-idle. A child whose turn fails instead, so that it cannot report, is reported by the plugin, and a
-child that waits for a permission or asks a question has it passed to the parent, who asks you and
+child works on its own and, when it is done or stuck, calls `courier_send` with the parent's id, a
+status and what it produced. That message lands in the parent's inbox and OpenCode starts a new
+turn for the parent if it is idle. A child whose turn fails instead, so that it cannot report, or ends without reporting, is
+reported by the plugin, and a child that waits for a permission or asks a question has it passed to the parent, who asks you and
 passes your answer back. A child that waits on a form only you can answer, such as OpenCode asking
 which web search provider to use, has its parent told so.
 
@@ -116,6 +118,43 @@ Watch the child's question open in the parent's session as OpenCode's own questi
 Both recordings are real runs with a free model on [OpenCode Zen](https://opencode.ai/zen) (Muse
 Spark 1.3).
 
+## Recursive orchestration
+
+A session splits a goal across child sessions, each child decides in turn whether to split its
+part again, and the results are checked and integrated at every level on the way back up. The
+plugin ships the playbook as an OpenCode skill, `courier-orchestrate`, listed in every session with
+the plugin loaded: how to decide whether to split, and to say which in one line of the reply
+(`split: no, because …; considered: <the parts you weighed>` or `split: 3 parts: …`), plan the
+parts, start them in one join group, end the turn, read each report by its status, verify
+first-hand through the project's scripts, integrate and report upward, and what to do when a part
+fails, ends quietly, blocks or hits a limit. It names the parts an implementation task with one
+tightly coupled core usually still has: its e2e scenario, its documentation, sometimes a second
+test file, and a review of the core by a session with fresh context (`isolate: false`, it edits
+nothing). The session does the core itself first and commits it, then starts one session per
+remaining part, if 2 or more remain; a review session's findings are a report to act on, and
+running the checks stays the session's own. Its description asks a model to load it at the start
+of any implementation task that may have independent parts, and a session nobody spawned is pointed to it by its system prompt as well
+([Session trees](#session-trees)); `/skills` in the TUI attaches it to your prompt. Its text:
+[the reference](docs/reference.md#the-courier-orchestrate-skill).
+
+The smoke test's recursive scenario (`COURIER_SCENARIO=recursive`, [docs/real-model.md](docs/real-model.md#recursive-orchestration))
+asks a free model:
+
+> Have this job done through helper sessions started with courier_spawn, one session per part, and
+> do no part yourself. It has two parts. Part "numbers" is itself two independent halves, which the
+> session that gets it hands to two sessions of its own: one runs `` `sleep 20; echo $((17 * 23))` ``
+> and writes the number it printed to numbers/a.txt, the other runs `` `sleep 20; echo $((2 ** 10))` ``
+> and writes the number it printed to numbers/b.txt. Part "count" runs `` `sleep 20; echo $((99 - 57))` ``
+> and writes the number it printed to count/total.txt. When the parts have reported back, read the
+> three files yourself and reply with one line: RESULTS \<a\> \<b\> \<total\>
+
+The root starts two sessions and ends its turn; the "numbers" session starts two of its own, ends
+its turn, checks both files when their reports wake it and reports once to the root; the "count"
+session does its part itself. The root is woken by the two reports, reads the three files and
+replies `RESULTS 391 1024 42`. The checker verifies the shape of the tree, that no session polled or
+went past `maxDepth`, that every report carries a status and each sub-orchestrator reported once,
+after its children, and the files and the final line.
+
 ## Install
 
 ### Supported OpenCode version
@@ -149,7 +188,8 @@ opencode plugin add opencode-courier
 
 This installs the package from npm and adds `"opencode-courier"` to `plugins` in the global
 configuration (`~/.config/opencode/opencode.json`). To receive webhooks, replace that entry with the
-object form shown under [Webhooks](#webhooks), which carries a `webhook` option.
+object form shown under [Webhooks](#webhooks), which carries a `webhook` option; the [session tree
+limits](#session-trees) are options of the same entry.
 
 Install it by name, without a version: OpenCode only checks plugins for updates when their entry is
 not an exact version, so `opencode-courier@0.2.1` is never offered a newer release. How to move an
@@ -184,23 +224,32 @@ Then list it in `opencode.json` (V2 uses `plugins`, plural). A local plugin path
    (run one web search in your own session and answer OpenCode's prompt, or use its "Third-party
    search" setting): otherwise the first child to search shows that prompt in its own session,
    which only you can answer there.
-3. Use `isolate: true` whenever children edit files in parallel. The child's worktree is made from
-   the last commit, so an uncommitted `opencode.json` is not there and the child falls back to your
+3. Your own session's prompts are relayed nowhere, and each one stalls the whole tree until you
+   answer it. Before an unattended run, allow the orchestrating session's toolchain up front: the
+   repository's `bun run` and `npm run` scripts, `git`, and whatever its checks need. Prefer one rule
+   on `bun run *` or `npm run *` over a rule per binary; the skill tells a session that orchestrates
+   to run checks through the project's scripts rather than `./node_modules/.bin/<tool>`, so one rule
+   covers them.
+4. Use `isolate: true` whenever children edit files in parallel. The child's worktree is made from
+   the last commit (from an isolated session, its HEAD), so an uncommitted `opencode.json` is not there and the child falls back to your
    global config: keep providers and models in the global config, or commit the file. When you are
    done with an isolated child, `courier_cleanup` it so its worktree does not linger.
-4. A child that crashes before calling `courier_send` never wakes the parent. When you spawn a
-   long-running child, also `courier_later` a check-in for yourself, and `courier_cancel` it when
-   the child reports.
+5. A child whose turn fails, or ends without `courier_send`, is reported to its parent by the
+   plugin. What the plugin cannot see, such as a server that stops while a child runs, a
+   `courier_later` check-in still covers: for a long-running child, schedule one for yourself and
+   `courier_cancel` it when the child reports.
 
 ## Tools
 
 | Tool | Does |
 |---|---|
-| `courier_spawn` | Creates a session (optionally in its own git worktree with `isolate: true`) on the parent's model, sends it the task plus a brief naming the parent and how to report back, and returns at once. |
-| `courier_send` | Delivers a message to a session, signed with the sender's id, waking it if idle. |
+| `courier_spawn` | Creates a session (optionally in its own git worktree with `isolate: true`, which from an isolated session starts at its HEAD, [nested isolation](docs/reference.md#nested-isolation)) on the parent's model, sends it the task plus a brief naming the parent, how to report back and when to split the task further, and returns at once. With a `group` name, the reports of every session started under that name are held and delivered together, in one message ([reference](docs/reference.md#join-groups)). Refused past the [session tree limits](#session-trees). |
+| `courier_send` | Delivers a message to a session, signed with the sender's id, waking it if idle. From a child to its parent, a `status` (`done`, `partial`, `blocked` or `failed`) makes it the child's report, carried as an attribute of the message (`<courier from="…" status="done">`), and `artifacts` (`branch`, `commits`, `files`, `checks`) are listed in its body in a fixed layout; a message without a status is progress, not the report ([reference](docs/reference.md#a-childs-report)). From a member of a join group, a report with `done`, `partial` or `failed` is held with the group instead, and the result says so. |
 | `courier_status` | One look at a session: outcome, idle time, last reply and the permission requests and questions it waits on. For check-ins, not for waiting. |
-| `courier_children` | Lists the sessions this one (or a given `sessionID`) started with `courier_spawn`, each with what `courier_status` reports plus its directory, whether it is isolated and when it was started. |
-| `courier_cleanup` | Removes the git worktree of a child started with `isolate: true` and drops the child from `courier_children`. Keeps a worktree with uncommitted changes or commits on no branch, tag or remote and lists them, unless `force: true` is passed ([reference](docs/reference.md#worktree-cleanup)). |
+| `courier_children` | Lists the sessions this one (or a given `sessionID`) started with `courier_spawn`, each with what `courier_status` reports plus its directory, whether it is isolated, when it was started and, for one started in a group, the group and whether its report is `held`, `out` or `released`. |
+| `courier_tree` | Lists the whole tree under this session (or a given `sessionID`): every session started from it with `courier_spawn`, directly or through others, depth first, each with what `courier_children` shows plus its depth, its parent, and its report state (whether it owes a report, sent progress, ended without one, and the status of its last report). Cut at `maxTotal` sessions ([reference](docs/reference.md#seeing-and-stopping-a-subtree)). |
+| `courier_stop` | Interrupts a session you started, directly or through others, and every session under it, deepest first, and cancels the `courier_later` messages scheduled for them. With `cleanup: true` it also removes their worktrees, by `courier_cleanup`'s rules (kept ones are listed). You are not told of what you stopped; a session between you and the target is, once, as `ended="stopped"` ([reference](docs/reference.md#seeing-and-stopping-a-subtree)). |
+| `courier_cleanup` | Removes the git worktree of a child started with `isolate: true` and drops the child from `courier_children`. Keeps a worktree with uncommitted changes or commits on no branch, tag or remote and lists them, unless `force: true` is passed ([reference](docs/reference.md#worktree-cleanup)). A child without a worktree is only dropped from `courier_children`; either way, a join group member that has not reported is dropped from its group, which is released without it ([reference](docs/reference.md#join-groups)). |
 | `courier_answer` | Passes your answer to a permission request or a question that a session started from this one waits on: `reply` (`once`, `always` or `reject`, with an optional `message`) for a permission request, `answers` for a question. |
 | `courier_later` | Schedules a message for a session (this one by default) in `delayMinutes` or `at` an ISO time, and returns an id. When due it is delivered like `courier_send`, queued behind any running turn and waking the session if idle. |
 | `courier_cancel` | Drops a message scheduled with `courier_later`, e.g. because the child it was waiting for reported first. |
@@ -214,9 +263,31 @@ The short version; the long one, with every edge, is [docs/reference.md](docs/re
 - **A child runs on its parent's model**, not on OpenCode's default, so a parent you moved to
   another model starts children that can reach theirs too. An `agent` with a model of its own keeps
   it. [More](docs/reference.md#the-childs-model).
+- **A child can split its task** with `courier_spawn` of its own, within the [limits](#session-trees):
+  its brief says when to split and when to do the work itself, and a session that splits checks
+  its children's work and sends one combined report. [More](docs/reference.md#session-trees-and-their-limits).
+- **A child reports once, with a status**: `done`, `partial`, `blocked` (it needs a decision from
+  its parent, and says what) or `failed`, as an attribute of the message, with its artifacts listed
+  in the body. A message without a status is progress, so a child that sends "halfway" and then
+  stops is still reported as ending without a report. [More](docs/reference.md#a-childs-report).
+- **A join group wakes you once.** Start a batch of sessions with the same `group` name, and
+  their `done`, `partial` and `failed` reports are held until the last one is in and your turn has ended, then delivered
+  in one message, marked `group="<name>"`, listing every report with its status and artifacts in
+  the order the sessions were started. A `blocked` report, progress, a failed turn, a silent end, a
+  permission request and a question reach you at once, as ever; a member whose turn fails or is
+  interrupted leaves the group, which is released without it. A member that will not report (it
+  ended its turn silently, or you gave up on it) holds the others back: drop it with
+  `courier_cleanup`, and the group is released without it, the message naming it; a report it
+  sends after all comes on its own. Held reports survive a restart, and the name is free again
+  once the group has been delivered. [More](docs/reference.md#join-groups).
 - **A child that fails** cannot report, so the plugin does: every failed turn of a spawned session
   sends its parent a message marked `failed="<error type>"`, with the error, waking it if idle.
   [More](docs/reference.md#a-child-that-fails).
+- **A child that ends its turn without reporting** to its parent has the parent told, marked
+  `ended="without-report"`, with its last reply, waking it if idle; it counts toward the limits
+  until it reports. One that waits, on a request, a session it started, a scheduled message or a
+  webhook it just subscribed to, is not reported, nor is one that answers what you typed in its session.
+  [More](docs/reference.md#a-child-that-ends-without-a-report).
 - **A child that asks for permission** has the request passed to the session at the top, with what
   it asks for and the choices OpenCode offers (`once`, `always`, `reject`). That session asks you
   and answers with `courier_answer`; the child carries on.
@@ -230,17 +301,49 @@ The short version; the long one, with every edge, is [docs/reference.md](docs/re
 - **A child that shows a form** the plugin cannot pass on, such as OpenCode's web search asking
   for a provider, has the top session told, marked `asks="form"`, with the form's choices: only you
   can answer it, in the child's session. [More](docs/reference.md#a-child-that-shows-a-form).
-- **The plugin remembers.** Each parent's children (`courier_children`), pending `courier_later`
-  messages and open questions survive a compaction or a restart; entries are dropped after 14 days.
+- **You can see and stop a whole subtree.** `courier_tree` lists every session under yours with its
+  depth and report state; `courier_stop` interrupts one of them and everything under it, deepest
+  first, and cancels their scheduled messages. A stop is neither a failure nor a silent end, and
+  only a session above the target may order it. [More](docs/reference.md#seeing-and-stopping-a-subtree).
+- **The plugin remembers.** Each parent's children (`courier_children`) and whether each owes a
+  report, held group reports, pending `courier_later` messages and open questions survive a compaction or a restart; entries are dropped after 14 days.
   [Roster](docs/reference.md#roster), [Scheduled messages](docs/reference.md#scheduled-messages).
 - **One OpenCode server per data directory, preferably.** A second server on the same one, such as
   `opencode serve` next to `opencode service`, shares the plugin's storage: one of the two delivers
-  `courier_later` messages, but a child's permission request can only be answered from the server
+  `courier_later` messages and released groups, but a child's permission request can only be answered from the server
   that runs the child. [More](docs/reference.md#two-servers-on-one-data-directory).
 - **Worktrees are yours to remove.** An isolated child's worktree is kept until `courier_cleanup`,
   which refuses to drop uncommitted changes or unbranched commits unless told to.
   [More](docs/reference.md#worktree-cleanup).
 
+## Session trees
+
+A spawned session may start sessions of its own, so the sessions form a tree, and three options
+bound it. Set them in the plugin's `options`, in the global config (`~/.config/opencode/opencode.json`):
+
+```jsonc
+{
+  "plugins": [{ "package": "opencode-courier", "options": { "maxDepth": 2, "maxChildren": 3 } }]
+}
+```
+
+| Option | Default | |
+|---|---|---|
+| `maxDepth` | `3` | How deep the tree goes: your session is depth 0, the sessions it starts depth 1. A session at `maxDepth` cannot start sessions. |
+| `maxChildren` | `5` | How many sessions one session started may have live at once. |
+| `maxTotal` | `20` | How many spawned sessions may be live at once in one tree. |
+
+`courier_spawn` refuses a spawn past a limit, naming it and saying what to do instead: do the work
+itself, or wait for a child to report. A session counts while it is live: its turn runs, it owes
+its parent a report (its task or a message reached it after it last reported, failed or was interrupted), or a
+session below it is live. One that has reported, with nothing live below it, does not. Each
+spawned session's model is also told its role on every request: `sub-orchestrator`, which may split
+its task, or `leaf`, at `maxDepth`, which does not see `courier_spawn` at all. Your own session is
+told, in one line, to load the `courier-orchestrate` skill before a task that touches several files
+or areas, decide whether to split it, and say which in one line of its reply (`split: no, because …;
+considered: <the parts you weighed>` or `split: 3 parts: …`); once it has started a session, that
+line becomes a `root orchestrator` part with the limits. The details: [the reference](docs/reference.md#session-trees-and-their-limits).
+
 ## Webhooks
 
 The receiver is off unless the plugin has a `webhook` option. Put it in the **global** config
@@ -320,8 +423,9 @@ gets a scenario there.
 The smoke test (`e2e/real-model.sh`) runs the same server with a real model (by default a free one
 on [OpenCode Zen](https://opencode.ai/zen), no key needed) and checks that the parent spawns instead
 of doing the work, ends its turn instead of polling, and is woken by each report;
-`COURIER_SCENARIO=permission` and `COURIER_SCENARIO=question` exercise the two relays. Which models
-pass and what was tuned for them: [docs/real-model.md](docs/real-model.md).
+`COURIER_SCENARIO=permission` and `COURIER_SCENARIO=question` exercise the two relays, and
+`COURIER_SCENARIO=recursive` the [recursive orchestration](#recursive-orchestration) above. Which
+models pass and what was tuned for them: [docs/real-model.md](docs/real-model.md).
 
 CI runs both suites on every push to `main` and every pull request, with the OpenCode CLI at the
 pinned version, and the live suite once more on the newest OpenCode release, where a failure warns

package/dist/bounded.d.ts

@@ -1,8 +1,6 @@
 /**
- * Bounded collections of remembered ids: plain `Set`s and `Map`s that drop their oldest entry past
- * a bound. Functions over the built-in types rather than a class, since the process-wide ones are
- * shared with copies of the plugin loaded before an update, which call `.has` and `.add` on them.
- * Imports nothing of the plugin's.
+ * Bounded `Set`s and `Map`s of remembered ids that drop their oldest entry past a bound. Functions
+ * on the built-ins, not a class, as older plugin copies call `.has` and `.add` on the shared ones.
  */
 /** Adds to a bounded set, dropping the oldest entry past `max`; false when the value was there already. */
 export declare function addBounded<T>(set: Set<T>, value: T, max: number): boolean;

package/dist/bounded.js

@@ -1,8 +1,6 @@
 /**
- * Bounded collections of remembered ids: plain `Set`s and `Map`s that drop their oldest entry past
- * a bound. Functions over the built-in types rather than a class, since the process-wide ones are
- * shared with copies of the plugin loaded before an update, which call `.has` and `.add` on them.
- * Imports nothing of the plugin's.
+ * Bounded `Set`s and `Map`s of remembered ids that drop their oldest entry past a bound. Functions
+ * on the built-ins, not a class, as older plugin copies call `.has` and `.add` on the shared ones.
  */
 /** Adds to a bounded set, dropping the oldest entry past `max`; false when the value was there already. */
 export function addBounded(set, value, max) {

package/dist/cleanup.d.ts

@@ -19,6 +19,10 @@ export interface CleanupPorts {
     readonly projectID: string;
     /** The worktree's state, or undefined when its directory no longer exists; `base` is the commit it was made from. */
     readonly inspect: (directory: string, base?: string) => Promise<WorktreeState | undefined>;
+    /** When a member still out is dropped from its group. */
+    readonly now: () => number;
+    /** Has the scheduler deliver what is due now: a group the forgotten child may have been the last member out of. */
+    readonly nudge: () => void;
 }
 export interface CleanupInput {
     readonly sessionID: string;
@@ -27,9 +31,8 @@ export interface CleanupInput {
 /** At most this many changes and commits are returned; the reason still counts them all. */
 export declare const MAX_LISTED = 50;
 /**
- * Removes the worktree of an isolated child the parent started, and forgets the child. A worktree
- * with uncommitted changes or commits that exist nowhere else is kept unless `force` is set, and the
- * result says what is in it.
+ * Forgets a child the parent started, removing its worktree if it is isolated. A worktree with uncommitted changes
+ * or commits found nowhere else is kept unless `force` is set; the result says so.
  */
 export declare function cleanup(ports: CleanupPorts, parentID: string, input: CleanupInput): Promise<CleanupResult>;
 /** Names the git to run, by absolute path, overriding the places `GIT_LOCATIONS` lists. */
@@ -46,6 +49,8 @@ export declare const GIT_LOCATIONS: Readonly<Record<"posix" | "win32", readonly
 export declare function findGit(env?: Readonly<Record<string, string | undefined>>, platform?: NodeJS.Platform, exists?: (path: string) => boolean): string;
 /** The commit a worktree is on, or undefined when git cannot tell. */
 export declare function headOf(directory: string): Promise<string | undefined>;
+/** Whether a worktree has uncommitted changes, untracked files included; undefined when git cannot tell. */
+export declare function dirtyOf(directory: string): Promise<boolean | undefined>;
 /**
  * Reads a worktree's state with git; undefined when the directory is gone. Commits reachable from
  * `base`, the commit the worktree was made from, are not its own work and are not listed.

package/dist/cleanup.js

@@ -1,32 +1,30 @@
 import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
 import { isAbsolute } from "node:path";
+import { markLeft, membershipOf } from "./group.js";
 import { keepReason } from "./notices.js";
 import { remove, rosterKey } from "./roster.js";
 /** At most this many changes and commits are returned; the reason still counts them all. */
 export const MAX_LISTED = 50;
 /**
- * Removes the worktree of an isolated child the parent started, and forgets the child. A worktree
- * with uncommitted changes or commits that exist nowhere else is kept unless `force` is set, and the
- * result says what is in it.
+ * Forgets a child the parent started, removing its worktree if it is isolated. A worktree with uncommitted changes
+ * or commits found nowhere else is kept unless `force` is set; the result says so.
  */
 export async function cleanup(ports, parentID, input) {
     const entry = (await ports.storage.get(rosterKey(parentID, input.sessionID)));
     if (!entry)
         throw new Error(`${input.sessionID} is not on the courier_children list of ${parentID}.`);
-    if (!entry.isolated)
-        throw new Error(`${input.sessionID} ran in ${entry.directory}, not in a worktree of its own; there is nothing to remove.`);
     const { directory } = entry;
-    const forget = () => remove(ports.storage, parentID, input.sessionID);
+    const forget = () => forgetChild(ports, entry);
+    if (!entry.isolated)
+        return { sessionID: input.sessionID, directory, outcome: "forgotten", ...(await forget()) };
     // With force the state only decides whether there is anything left to remove, so a worktree git
     // can no longer read is still removed.
     const state = await ports
         .inspect(directory, entry.base)
         .catch((error) => (input.force ? { changes: [], commits: [] } : Promise.reject(error)));
-    if (!state) {
-        await forget();
-        return { sessionID: input.sessionID, directory, outcome: "gone" };
-    }
+    if (!state)
+        return { sessionID: input.sessionID, directory, outcome: "gone", ...(await forget()) };
     const reason = keepReason(state);
     if (reason && !input.force)
         return {
@@ -42,8 +40,18 @@ export async function cleanup(ports, parentID, input) {
         directory,
         force: input.force === true,
     });
-    await forget();
-    return { sessionID: input.sessionID, directory, outcome: "removed" };
+    return { sessionID: input.sessionID, directory, outcome: "removed", ...(await forget()) };
+}
+/**
+ * Drops a member still out from its group as `dropped`, so the group is released without it, then the roster entry
+ * and report state. A held report stays with its group. Returns the group it was dropped from.
+ */
+async function forgetChild(ports, entry) {
+    const member = entry.group ? await membershipOf(ports.storage, entry.parentID, entry.group, entry.sessionID) : undefined;
+    if (member?.out && (await markLeft(ports.storage, member, "dropped", ports.now())))
+        ports.nudge();
+    await remove(ports.storage, entry.parentID, entry.sessionID);
+    return member?.out ? { group: member.group } : {};
 }
 /** Names the git to run, by absolute path, overriding the places `GIT_LOCATIONS` lists. */
 export const GIT_ENV = "OPENCODE_COURIER_GIT";
@@ -85,6 +93,10 @@ function git(directory, args) {
 export function headOf(directory) {
     return git(directory, ["rev-parse", "HEAD"]).then((out) => out.trim() || undefined, () => undefined);
 }
+/** Whether a worktree has uncommitted changes, untracked files included; undefined when git cannot tell. */
+export function dirtyOf(directory) {
+    return git(directory, ["status", "--porcelain"]).then((out) => out.trim().length > 0, () => undefined);
+}
 /**
  * Reads a worktree's state with git; undefined when the directory is gone. Commits reachable from
  * `base`, the commit the worktree was made from, are not its own work and are not listed.

package/dist/courier.d.ts

@@ -1,21 +1,31 @@
 import type { Plugin } from "@opencode/plugin";
-import { type Prompt } from "./notices.js";
-import { type RosterStorage } from "./roster.js";
+import { type Limits, type SpawnGate } from "./limits.js";
+import { type Artifacts, type Prompt, type Sent, type Status } from "./notices.js";
+import { type RosterEntry, type RosterStorage } from "./roster.js";
 type Context = Plugin.Context;
 /** The slice of the plugin context the courier tools use; tests pass a fake. */
 export interface CourierPorts {
-    readonly session: Pick<Context["session"], "create" | "prompt" | "synthetic" | "get" | "context">;
+    readonly session: Pick<Context["session"], "create" | "prompt" | "synthetic" | "get" | "context" | "interrupt">;
     readonly agent: Pick<Context["agent"], "get">;
     readonly worktree: Pick<Context["worktree"], "create" | "remove">;
     /** The project of the plugin's location; an isolated child's worktree is made in it, and removed from it. */
     readonly projectID: string;
     /** The commit a directory's checkout is on, or undefined; recorded as an isolated child's base. */
     readonly head: (directory: string) => Promise<string | undefined>;
+    /** Whether a directory's checkout has uncommitted changes, or undefined when git cannot tell. */
+    readonly dirty: (directory: string) => Promise<boolean | undefined>;
     readonly storage: RosterStorage;
     readonly directory: string;
     readonly now: () => number;
     /** The permission requests and questions a session waits on, wherever they are pending. */
     readonly pending: (sessionID: string) => Promise<ReadonlyArray<Pending>>;
+    readonly limits: Limits;
+    readonly gate: SpawnGate;
+    /** The depths the `context` hook remembers; a parent's is dropped when it starts a child. */
+    readonly roles: Map<string, number | null>;
+    /** Has the scheduler deliver what is due now rather than at its next tick: a group a report has just completed. */
+    readonly nudge: () => void;
+    readonly log: (message: string) => void;
 }
 /** A request a session waits on until someone answers it: a permission request, or a question it asked. */
 export type Pending = {
@@ -36,10 +46,13 @@ export interface SpawnInput {
     readonly title?: string;
     readonly agent?: string;
     readonly isolate?: boolean;
+    readonly group?: string;
 }
 export interface SendInput {
     readonly sessionID: string;
     readonly message: string;
+    readonly status?: Status;
+    readonly artifacts?: Artifacts;
     readonly queue?: boolean;
 }
 export interface StatusInput {
@@ -48,48 +61,140 @@ export interface StatusInput {
 export interface ChildrenInput {
     readonly sessionID?: string;
 }
-/** Creates a child session, hands it the task and returns at once; the child reports back with courier_send. */
+/**
+ * Creates a child session, hands it the task and returns at once; the child reports back with
+ * courier_send. Refused past a limit, whether or not the `context` hook hid the tool.
+ */
 export declare function spawn(ports: CourierPorts, parentID: string, input: SpawnInput): Promise<{
+    uncommitted?: boolean | undefined;
+    fromParent?: boolean | undefined;
+    groupError?: string | undefined;
     rosterError?: string | undefined;
+    group?: string | undefined;
     sessionID: string;
     directory: string;
 }>;
-/** Drops a message into another session's inbox; OpenCode wakes that session if it is idle. */
-export declare function send(ports: CourierPorts, from: string, input: SendInput): Promise<{
-    messageID: string;
-}>;
+/**
+ * Drops a message into another session's inbox; OpenCode wakes that session if it is idle. From a spawned session
+ * to the one that started it, it is its report or its progress (`noteReport`); a group member's final report is held (`hold`).
+ */
+export declare function send(ports: CourierPorts, from: string, input: SendInput): Promise<Sent>;
 /** A one-off look at a session, for check-ins; not meant to be called in a loop. */
 export declare function status(ports: CourierPorts, input: StatusInput): Promise<Partial<{
     sessionID: string;
     title: string | undefined;
     parentID: string | undefined;
-    outcome: "failed" | "succeeded" | "interrupted" | undefined;
+    outcome: "failed" | "interrupted" | "succeeded" | undefined;
     updated: number;
     idle: number | undefined;
     lastText: string | undefined;
     pending: readonly Pending[] | undefined;
 }>>;
-/** The sessions a parent started, each with what courier_status reports, or the error it gave. */
+/** The text of a session's last reply, from its context's messages, or undefined when it has none. */
+export declare function lastReply(messages: Awaited<ReturnType<Context["session"]["context"]>>): string | undefined;
+/**
+ * The sessions a parent started, each with what courier_status reports, or the error it gave; a child in a
+ * group with the group's name and its standing there: `held`, `out`, how it left, `released` or `unknown`.
+ */
 export declare function listChildren(ports: CourierPorts, parentID: string): Promise<({
+    group: {
+        name: string;
+        report: string;
+    };
+    directory: string;
+    isolated: boolean;
+    created: number;
+    sessionID?: string | undefined;
+    title?: string | undefined;
+    parentID?: string | undefined;
+    outcome?: "failed" | "interrupted" | "succeeded" | undefined;
+    updated?: number | undefined;
+    idle?: number | undefined;
+    lastText?: string | undefined;
+    pending?: readonly Pending[] | undefined;
+} | {
+    group?: undefined;
     directory: string;
     isolated: boolean;
     created: number;
     sessionID?: string | undefined;
     title?: string | undefined;
     parentID?: string | undefined;
-    outcome?: "failed" | "succeeded" | "interrupted" | undefined;
+    outcome?: "failed" | "interrupted" | "succeeded" | undefined;
     updated?: number | undefined;
     idle?: number | undefined;
     lastText?: string | undefined;
     pending?: readonly Pending[] | undefined;
 } | {
     error: string;
+    group: {
+        name: string;
+        report: string;
+    };
+    directory: string;
+    isolated: boolean;
+    created: number;
+    sessionID: string;
+    title: string;
+} | {
+    error: string;
+    group?: undefined;
     directory: string;
     isolated: boolean;
     created: number;
     sessionID: string;
     title: string;
 })[]>;
+/** One roster entry as courier_children shows it: what courier_status reports with its directory and group standing, or the error it gave. */
+export declare function described(ports: CourierPorts, entry: RosterEntry): Promise<{
+    group: {
+        name: string;
+        report: string;
+    };
+    directory: string;
+    isolated: boolean;
+    created: number;
+    sessionID?: string | undefined;
+    title?: string | undefined;
+    parentID?: string | undefined;
+    outcome?: "failed" | "interrupted" | "succeeded" | undefined;
+    updated?: number | undefined;
+    idle?: number | undefined;
+    lastText?: string | undefined;
+    pending?: readonly Pending[] | undefined;
+} | {
+    group?: undefined;
+    directory: string;
+    isolated: boolean;
+    created: number;
+    sessionID?: string | undefined;
+    title?: string | undefined;
+    parentID?: string | undefined;
+    outcome?: "failed" | "interrupted" | "succeeded" | undefined;
+    updated?: number | undefined;
+    idle?: number | undefined;
+    lastText?: string | undefined;
+    pending?: readonly Pending[] | undefined;
+} | {
+    error: string;
+    group: {
+        name: string;
+        report: string;
+    };
+    directory: string;
+    isolated: boolean;
+    created: number;
+    sessionID: string;
+    title: string;
+} | {
+    error: string;
+    group?: undefined;
+    directory: string;
+    isolated: boolean;
+    created: number;
+    sessionID: string;
+    title: string;
+}>;
 /** A readable message for a failed courier call; OpenCode's own errors can carry an empty message. */
 export declare function describeFailure(tool: string, error: unknown): Error;
 export {};