opencode-courier 0.9.0 → 0.10.1

package/README.md

@@ -21,7 +21,7 @@ The edge cases on the live terminal UI, narrated ([what it shows](#demos)).
 ## Quickstart
 
 ```bash
-npm install -g @opencode/cli@2.0.32   # OpenCode V2, at the version courier is tested on
+npm install -g @opencode/cli@2.1.0   # OpenCode V2, at the version courier is tested on
 opencode plugin add opencode-courier  # by name, so OpenCode offers new releases
 opencode                              # in any folder
 ```
@@ -42,7 +42,7 @@ sometimes stall on a request; if nothing moves for a few minutes, send the promp
 
 Courier is built on OpenCode V2's plugin API (`@opencode/plugin`), not the V1 one
 (`@opencode-ai/plugin`). Each release is pinned to one V2 version and tested against it end to end;
-the current one is tested on **OpenCode 2.0.32**. CI also runs the live suite on the newest OpenCode
+the current one is tested on **OpenCode 2.1.0**. CI also runs the live suite on the newest OpenCode
 release, on `main` and nightly. Older releases: [every release](docs/reference.md#the-opencode-version).
 
 ## Courier or the built-in subagent tool?
@@ -108,20 +108,20 @@ version than the pinned one writes one line to the server log
 <!-- compat-table:start rows=3: generated by script/compat-table.ts from the release tags -->
 | opencode-courier | OpenCode V2 (`opencode` and `@opencode/plugin`) |
 |---|---|
-| 0.7.3, 0.8.0, 0.9.0 | 2.0.32 |
+| 0.10.1 | 2.1.0 |
+| 0.7.3, 0.8.0, 0.9.0, 0.10.0 | 2.0.32 |
 | 0.7.2 | 2.0.31 |
-| 0.7.1 | 2.0.30 |
 <!-- compat-table:end -->
 
 Older releases and their versions: [every release](docs/reference.md#the-opencode-version).
 
 The [terminal part](#in-the-terminal) relies on the host to provide its UI modules and is tested on
-OpenCode 2.0.32 only; the server part works on older V2 hosts from 2.0.4 on.
+OpenCode 2.1.0 only; the server part works on older V2 hosts from 2.0.4 on.
 
 Check yours with `opencode --version`, and install the matching CLI with:
 
 ```bash
-npm install -g @opencode/cli@2.0.32
+npm install -g @opencode/cli@2.1.0
 ```
 
 ### The plugin

package/dist/kernel/protocol.d.ts

@@ -11,6 +11,10 @@ export type Status = (typeof STATUSES)[number];
 export declare const isStatus: (value: unknown) => value is Status;
 /** The one line a session states its split decision in, so a transcript tells a decision from one never made. */
 export declare const SPLIT_LINE = "split: no, because \u2026; considered: <the parts you weighed> or split: <n> parts: \u2026 (one phrase per part)";
+/** The third form, for the root alone: it hands a heavy task whole to one session, to keep its own context. */
+export declare const ONE_PART_LINE = "split: 1 part: <the task>, to keep my context";
+/** `SPLIT_LINE` with the root's third form: the root's pointer offers it, a child's brief and role part never do. */
+export declare const ROOT_SPLIT_LINE = "split: no, because \u2026; considered: <the parts you weighed> or split: <n> parts: \u2026 (one phrase per part) or split: 1 part: <the task>, to keep my context";
 export declare const SKILL_ID = "courier-orchestrate";
 export declare function envelope(from: string, message: string, attributes?: Record<string, string>): string;
 export declare function clipText(text: string, max?: number): string;

package/dist/kernel/protocol.js

@@ -10,6 +10,10 @@ export const STATUSES = ["done", "partial", "blocked", "failed"];
 export const isStatus = (value) => typeof value === "string" && STATUSES.includes(value);
 /** The one line a session states its split decision in, so a transcript tells a decision from one never made. */
 export const SPLIT_LINE = "split: no, because …; considered: <the parts you weighed> or split: <n> parts: … (one phrase per part)";
+/** The third form, for the root alone: it hands a heavy task whole to one session, to keep its own context. */
+export const ONE_PART_LINE = "split: 1 part: <the task>, to keep my context";
+/** `SPLIT_LINE` with the root's third form: the root's pointer offers it, a child's brief and role part never do. */
+export const ROOT_SPLIT_LINE = `${SPLIT_LINE} or ${ONE_PART_LINE}`;
 export const SKILL_ID = "courier-orchestrate";
 export function envelope(from, message, attributes = {}) {
     const extra = Object.entries(attributes)

package/dist/skill.d.ts

@@ -1,7 +1,10 @@
 import type { Plugin } from "@opencode/plugin";
 /** Why a model loads the skill, listed with every session's available skills. */
 export declare const SKILL_DESCRIPTION: string;
-/** The skill's text; it names no limits, which the role part and the brief give for the session's own tree. */
+/**
+ * The skill's text; it names no limits, which the role part and the brief give for the session's own tree.
+ * Steps 3, 4 and 6 repeat the brief's split rule on purpose: the root has no brief, so only the skill gives it.
+ */
 export declare const SKILL_CONTENT: string;
 /** The editor OpenCode hands a skill transform. */
 export type SkillEditor = Parameters<Parameters<Plugin.Context["skill"]["transform"]>[0]>[0];

package/dist/skill.js

@@ -1,34 +1,43 @@
-import { SKILL_ID, SPLIT_LINE } from "./kernel/protocol.js";
+import { ONE_PART_LINE, SKILL_ID, SPLIT_LINE } from "./kernel/protocol.js";
 // The courier-orchestrate skill: the playbook a session loads with its skill tool.
 /** Why a model loads the skill, listed with every session's available skills. */
 export const SKILL_DESCRIPTION = "Load at the start of any implementation task that may have independent parts, or when a session started you, to " +
     "decide whether to split it across OpenCode sessions with courier_spawn and state the decision, and how: plan the " +
     "parts, start them, end your turn, read the reports, verify the work, integrate it and report upward, and what to do " +
     "when a part goes wrong.";
-/** The skill's text; it names no limits, which the role part and the brief give for the session's own tree. */
+/**
+ * The skill's text; it names no limits, which the role part and the brief give for the session's own tree.
+ * Steps 3, 4 and 6 repeat the brief's split rule on purpose: the root has no brief, so only the skill gives it.
+ */
 export const SKILL_CONTENT = [
     "How to split a task across OpenCode sessions with opencode-courier, and bring the results back up. Your brief, or the " +
         "opencode-courier role line in your system prompt, names your depth in the session tree and its limits.",
     "",
     "1. Decide: split or do. First call courier_recall once: it lists how earlier trees in this project were split and how " +
         "each part went, so weigh that; one call, before you decide, never in a loop. Split when the task has 2 or more " +
-        "independent, substantial parts touching separate files or areas; do it yourself when it is small, sequential or tightly coupled. Never start exactly one session for the whole " +
-        "task: it only adds a hop. What you read and write yourself stays in your context for every later turn, so keep the " +
-        "deciding, checking and integrating, and hand off the long reading and writing. An implementation task with one tightly " +
-        "coupled core usually still has independent parts: finding out what the change needs (a session with isolate: false " +
-        "reads the code, or a library's or a host's source, tries things and reports what it found), its e2e scenario, its " +
-        "documentation, sometimes a second test file, and a review of the core by a session with fresh context, which reads the " +
-        "committed diff against the task and the repository's rules and reports its findings (isolate: false, it edits nothing). " +
-        "Weigh each of them. When the other parts depend on names and texts the core fixes, split in stages: the core first, " +
-        "yourself when it is small or by one session when it is big, merged and committed before the rest start; then, if 2 or " +
-        "more parts remain, one session per remaining part, in one group. A part that is itself big and divisible is split again " +
-        "by the session that gets it; at the deepest level a session does its part itself. " +
-        `Say which in one line of your reply, before you start: ${SPLIT_LINE}, so that a reasoned decision to do it ` +
-        "yourself can be told from one never made.",
+        "independent, substantial parts touching separate files or areas; do it yourself when it is small, sequential or " +
+        "tightly coupled. What you read and write yourself stays in your context for every later turn, so keep the deciding, " +
+        "checking and integrating, and hand off the long reading and writing. Only the root, the session nobody started, may " +
+        "start exactly one session for the whole task, and only when the task is heavy (long reading, many edits, long runs) " +
+        "and its own context is worth keeping: it still verifies and integrates that session's report itself (steps 5 to 7), " +
+        "and does a small task itself. Every other session never starts exactly one session for the whole task: it only adds " +
+        "a hop, and a chain of single hops uses up the tree's depth. A part that is itself big and divisible is split again by " +
+        "the session that gets it; at the deepest level a session does its part itself. " +
+        `Say which in one line of your reply, before you start, so that a reasoned decision to do it yourself can be told ` +
+        `from one never made: ${SPLIT_LINE}; the root has a third form, ${ONE_PART_LINE}.`,
+    "   When the core is coupled: an implementation task with one tightly coupled core usually still has independent parts: " +
+        "finding out what the change needs (a session with isolate: false reads the code, or a library's or a host's source, " +
+        "tries things and reports what it found), its e2e scenario, its documentation, sometimes a second test file, and a " +
+        "review of the core by a session with fresh context, which reads the committed diff against the task and the " +
+        "repository's rules and reports its findings (isolate: false, it edits nothing). Weigh each of them. When the other " +
+        "parts depend on names and texts the core fixes, split in stages: the core first, yourself when it is small or by one " +
+        "session when it is big, merged and committed before the rest start; then, if 2 or more parts remain, one session per " +
+        "remaining part, in one group. A staged core is one part of the task, not the whole task, so the rule against starting exactly one " +
+        "session for the whole task does not apply to it when 2 or more parts follow it.",
     "2. Plan the parts so that no two edit the same files. Write each task so the session can do it without you: what to " +
         "produce and where, how to check it, what to report. Say if it may split its part further, and to run its checks " +
         "through the project's scripts (step 6): each permission request of a session below you wakes you and waits on the person.",
-    "3. Start them: one courier_spawn per part, all with the same group name, so you are woken once with every report; " +
+    "3. Start them: one courier_spawn per part that runs at once, all with the same group name, so you are woken once with every report; " +
         "isolate: true for each part that edits files in parallel with another (commit your own work first if you are isolated " +
         "yourself). For long work, courier_later a check-in for yourself, and courier_cancel it when the reports arrive.",
     "4. End your turn: reply without calling more tools. Do not poll with courier_status, courier_children, courier_tree or " +

package/dist/tree/panel.d.ts

@@ -6,7 +6,7 @@ export declare function lastTool(messages: Messages): {
     name: string;
     at: number;
 } | undefined;
-/** How full a session's context is, as OpenCode's session view reads it (packages/tui/src/util/session.ts, v2.0.32): the last usage since the last compaction over its model's window. */
+/** How full a session's context is, as OpenCode's session view reads it (packages/tui/src/util/session.ts, v2.1.0): the last usage since the last compaction over its model's window. */
 export declare function contextOf(messages: Messages, windows: ReadonlyArray<ModelWindow>): number | undefined;
 /** A request as the panel says what a paused session waits on: a permission request, or its first question. */
 export declare const waitOf: (pending: Pending) => Wait;

package/dist/tree/panel.js

@@ -15,7 +15,7 @@ export function lastTool(messages) {
     }
     return undefined;
 }
-/** How full a session's context is, as OpenCode's session view reads it (packages/tui/src/util/session.ts, v2.0.32): the last usage since the last compaction over its model's window. */
+/** How full a session's context is, as OpenCode's session view reads it (packages/tui/src/util/session.ts, v2.1.0): the last usage since the last compaction over its model's window. */
 export function contextOf(messages, windows) {
     const compacted = messages.findLastIndex((message) => message.type === "compaction" && message.status === "completed");
     const last = messages.findLast((message, index) => index > compacted && message.type === "assistant" && message.tokens !== undefined);

package/dist/tree/text.js

@@ -1,6 +1,6 @@
 /** 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";
+import { clipText, defuse, END_TURN, ROOT_SPLIT_LINE, 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)}`;
@@ -47,10 +47,12 @@ function splitRule(parentID, depth, limits) {
         `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 for the whole task.",
+        "- Do it yourself when it is small, sequential or tightly coupled. Never start exactly one session for the whole task; a core you stage before the rest is one part of it, not the whole, when 2 or more parts follow it.",
         `- 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.`,
+        "- If you split, you orchestrate: start the parts that run at once in one group, with the same group name for each, " +
+            "then end your turn while they work. Do not poll with courier_status, courier_children, courier_tree or sleep: the group's " +
+            "reports wake you. 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. */
@@ -65,14 +67,15 @@ export function rolePart(depth, limits) {
     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, call courier_recall once for how earlier trees in this project were split and how they went, ` +
-            `and decide whether to split it across sessions (doing it yourself is fine), and say ` +
-            `which in one line of your reply: ${SPLIT_LINE}`);
+            `and decide whether to split it across sessions (doing it yourself is fine; so is handing a heavy task, with long ` +
+            `reading, many edits or long runs, whole to one session to keep your context, but never a small one), and say ` +
+            `which in one line of your reply: ${ROOT_SPLIT_LINE}`);
     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} sub-orchestrator, at depth ${depth} of at most ${maxDepth}. Before you split, load the ${SKILL_ID} ` +
+            `skill. Split your task with courier_spawn or do it yourself, as your brief says; sessions can be started ${count(maxDepth - depth, "level")} below you. ${budget}`);
     return (`${ROLE_PREFIX} leaf, at depth ${depth}, the deepest the session tree goes. You cannot start sessions: do your ` +
         "task yourself and report with courier_send to the session that started you.");
 }

package/dist/tui.js

@@ -61,6 +61,9 @@ var memoryRpc = Rpc.define({
 
 // src/kernel/protocol.ts
 var STATUSES = ["done", "partial", "blocked", "failed"];
+var SPLIT_LINE = "split: no, because \u2026; considered: <the parts you weighed> or split: <n> parts: \u2026 (one phrase per part)";
+var ONE_PART_LINE = "split: 1 part: <the task>, to keep my context";
+var ROOT_SPLIT_LINE = `${SPLIT_LINE} or ${ONE_PART_LINE}`;
 
 // src/memory/domain.ts
 var RETENTION_MS = 90 * 24 * 60 * 60000;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-courier",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Multi-session orchestration for OpenCode V2: spawn child sessions, be woken by them. No polling.",
   "license": "MIT",
   "author": "Ivo Pogace <71701666+ivopogace@users.noreply.github.com>",
@@ -56,14 +56,14 @@
     "test:e2e": "e2e/run.sh"
   },
   "peerDependencies": {
-    "@opencode/plugin": "2.0.32",
+    "@opencode/plugin": "2.1.0",
     "effect": "4.0.1"
   },
   "devDependencies": {
-    "@opencode/plugin": "2.0.32",
-    "@opencode/theme": "2.0.32",
-    "@opentui/core": "0.5.17",
-    "@opentui/solid": "0.5.17",
+    "@opencode/plugin": "2.1.0",
+    "@opencode/theme": "2.1.0",
+    "@opentui/core": "0.6.6",
+    "@opentui/solid": "0.6.6",
     "@types/bun": "1.3.14",
     "@types/node": "26.6.4",
     "effect": "4.0.1",