opencode-courier 0.12.0 → 0.13.0

package/dist/tree/send.js

@@ -1,5 +1,6 @@
 import { envelope, isStatus, STATUSES } from "../kernel/protocol.js";
 import { groupStanding, holdReport, membershipFor, unholdForBlocked } from "./group.js";
+import { syncStanding } from "./standing.js";
 import { childStore, groupStore } from "./store.js";
 import { reportBody } from "./text.js";
 import { noteSent } from "./wake.js";
@@ -8,37 +9,63 @@ import { noteSent } from "./wake.js";
  * to the one that started it, it is its report or its progress (`noteReport`); a group member's final report is held (`hold`).
  */
 export async function send(ports, from, input) {
-    // Some models send null for an optional field they leave out.
-    const status = input.status ?? undefined;
-    if (status !== undefined && !isStatus(status))
-        throw new Error(`status must be one of ${STATUSES.join(", ")}, not ${JSON.stringify(status)}.`);
+    const { status, dropped } = await statusFor(ports, from, input);
     // Noted first: the delivery may wake the parent, whose turn may end before a later note.
     const noted = await noteReport(ports, from, input.sessionID, status).catch(() => undefined);
     try {
         const held = noted?.member && status && status !== "blocked" ? await hold(ports, noted.member, { at: noted.at, status, message: input.message, ...(input.artifacts ? { artifacts: input.artifacts } : {}) }) : undefined;
+        // The parent's standing before the delivery, which may wake it: its first step then shows the report or progress noted.
+        if (noted)
+            await syncStanding(ports, input.sessionID);
         if (held)
             return { status, report: true, held };
-        const text = envelope(from, reportBody(input.message, input.artifacts), status ? { status } : {});
-        const description = `Message from ${from}`;
-        const delivered = await ports.session.synthetic({
-            sessionID: input.sessionID,
-            text,
-            description,
-            metadata: { source: "courier", from, ...(status ? { status } : {}) },
-            delivery: input.queue ? "queue" : "steer",
-        });
-        // Watched now, not when OpenCode's enqueued event is handled: a spawn in the same step must count the child it wakes.
-        await noteSent(ports, { sessionID: input.sessionID, inboxID: delivered.id, text, description }).catch(() => undefined);
-        // A blocked report, once delivered, is the member's latest word: an earlier report held for it would be stale.
-        if (noted?.member && status === "blocked")
-            await unholdForBlocked(groupStore(ports.storage), noted.member).catch(() => undefined);
-        return { messageID: delivered.id, ...(status ? { status } : {}), ...(noted ? { report: noted.report } : {}) };
+        const delivered = await deliver(ports, from, input, status, noted);
+        return { ...delivered, ...(noted ? { report: noted.report } : {}), ...(dropped ? { dropped } : {}) };
     }
     catch (error) {
         await noted?.undo().catch(() => undefined);
+        // The standing as before the note, once the note is taken back.
+        if (noted)
+            await syncStanding(ports, input.sessionID);
         throw error;
     }
 }
+/** Delivers the message, watches it, and takes a held report back after a blocked one; the message id and status delivered. */
+async function deliver(ports, from, input, status, noted) {
+    const text = envelope(from, reportBody(input.message, input.artifacts), status ? { status } : {});
+    const description = `Message from ${from}`;
+    const delivered = await ports.session.synthetic({
+        sessionID: input.sessionID,
+        text,
+        description,
+        metadata: { source: "courier", from, ...(status ? { status } : {}) },
+        delivery: input.queue ? "queue" : "steer",
+    });
+    // Watched now, not when OpenCode's enqueued event is handled: a spawn in the same step must count the child it wakes.
+    await noteSent(ports, { sessionID: input.sessionID, inboxID: delivered.id, text, description }).catch(() => undefined);
+    // A blocked report, once delivered, is the member's latest word: an earlier report held for it would be stale.
+    if (noted?.member && status === "blocked")
+        await unholdForBlocked(groupStore(ports.storage), noted.member).catch(() => undefined);
+    return { messageID: delivered.id, ...(status ? { status } : {}) };
+}
+/**
+ * The message's status, checked, as OpenCode does not check the schema. A status is a report's: on a message to a
+ * session below the sender it means nothing, so it is `dropped`, and the result says so.
+ */
+async function statusFor(ports, from, input) {
+    // Some models send null for an optional field they leave out.
+    const given = input.status ?? undefined;
+    if (given === undefined)
+        return {};
+    if (!isStatus(given))
+        throw new Error(`status must be one of ${STATUSES.join(", ")}, not ${JSON.stringify(given)}.`);
+    return (await isBelow(ports, from, input.sessionID)) ? { dropped: given } : { status: given };
+}
+/** Whether `from` started `to`, directly or through others, by the reverse index; false when the index does not name `to` or cannot be read. */
+async function isBelow(ports, from, to) {
+    const above = await childStore(ports.storage).indexedAncestors(to).catch(() => []);
+    return above.includes(from);
+}
 /**
  * Notes `from`'s message to `to` when `to` started it: as its report when it carries a status, or when an earlier
  * release briefed `from`, else as progress. Returns which, when, how to take the note back, and `from`'s group membership.

package/dist/tree/spawn.js

@@ -3,8 +3,9 @@ import { isGroupName, modelName } from "./domain.js";
 import { joinGroup, leaveGroup } from "./group.js";
 import { admit } from "./limits.js";
 import { chooseModel } from "./model.js";
+import { putEntries, syncStanding } from "./standing.js";
 import { childStore, groupStore } from "./store.js";
-import { childBrief, childBranch, nativeIsolateRefusal } from "./text.js";
+import { childBrief, childBranch, nativeIsolateRefusal, ROLE_KEY, rolePart } from "./text.js";
 function titleOf(task) {
     const line = task.trim().split("\n")[0] ?? "";
     return line.length > 60 ? `${line.slice(0, 57)}...` : line;
@@ -52,8 +53,14 @@ async function start(ports, parentID, input, admitted, group) {
         ...(model ? { model } : {}),
     };
     const { rosterError, groupError } = await enrol(ports, entry, group);
-    ports.roles.delete(parentID);
-    await handOver(ports, entry, admitted.depth, input.task, !rosterError, !rosterError && !groupError);
+    await nameBoth(ports, parentID, entry.sessionID, admitted.depth);
+    try {
+        await handOver(ports, entry, admitted.depth, input.task, !rosterError, !rosterError && !groupError);
+    }
+    finally {
+        // The parent's standing with the child on it, prompted or failed, announced at its next step.
+        await syncStanding(ports, parentID);
+    }
     return {
         sessionID: entry.sessionID,
         directory: entry.directory,
@@ -170,3 +177,50 @@ async function join(ports, entry, group) {
         return describeFailure("group", error).message;
     }
 }
+/**
+ * The child's role and the other modules' entries before its prompt, so its first request carries them, and a root's own at
+ * its first spawn, remembered for the `context` hook; a parent that is no root is forgotten there, as its depth may have changed.
+ */
+async function nameBoth(ports, parentID, childID, depth) {
+    const extra = await extraEntries(ports);
+    await nameRole(ports, childID, depth);
+    if (depth < ports.limits.maxDepth)
+        await putEntries(ports, childID, extra);
+    const rootNamed = ports.roles.get(parentID)?.entry === true;
+    const named = depth === 1 && (rootNamed || (await nameRole(ports, parentID, 0)));
+    if (named && !rootNamed)
+        await putEntries(ports, parentID, extra);
+    if (named)
+        ports.roles.set(parentID, { depth: 0, entry: true });
+    else
+        ports.roles.delete(parentID);
+}
+/** The entries the other modules give a spawned session, the memory's lessons; none when they cannot be read, logged. */
+async function extraEntries(ports) {
+    if (!ports.entries || !ports.session.instructions)
+        return [];
+    try {
+        return await ports.entries();
+    }
+    catch (error) {
+        ports.log(`courier_spawn: the entries of the other modules could not be read, so the session starts without them: ${String(error)}`);
+        return [];
+    }
+}
+/**
+ * Writes a session's role part to its `role` entry: a child's system prompt carries it from its first request, a root's
+ * transcript as an update. False on a host without entries, or when the put failed, logged: the `context` hook adds the part.
+ */
+async function nameRole(ports, sessionID, depth) {
+    const entries = ports.session.instructions?.entry;
+    if (!entries)
+        return false;
+    try {
+        await entries.put({ sessionID, key: ROLE_KEY, value: rolePart(depth, ports.limits) });
+        return true;
+    }
+    catch (error) {
+        ports.log(`courier_spawn: the role entry of ${sessionID} could not be written, so its role goes in a system part: ${String(error)}`);
+        return false;
+    }
+}

package/dist/tree/standing.d.ts

@@ -0,0 +1,17 @@
+import type { Entry, ReportNote, RosterStorage, StandingPorts } from "./ports.js";
+import { type ChildState, type StandingRow } from "./text.js";
+/** A child's state from its report notes, as `reportOf` and the silent-turn rule read them. */
+export declare function stateOf(notes: {
+    readonly [K in "prompt" | "settled" | "progress" | "told" | "stopped"]: ReportNote;
+}): ChildState;
+/** The rows of a parent's standing entry: its unexpired children, oldest first, each with its state and group standing. */
+export declare function standingRows(storage: RosterStorage, parentID: string, now: number): Promise<StandingRow[]>;
+/** What `syncStanding` did to the parent's entry. */
+export type Synced = "put" | "unchanged" | "removed" | "absent" | "skipped";
+/**
+ * Writes a parent's `standing` entry once something of it changed: put when its text differs from the entry's, removed when
+ * the parent has no children left; skipped without the keyed entries. A failure is logged, never thrown.
+ */
+export declare function syncStanding(ports: StandingPorts, parentID: string): Promise<Synced>;
+/** Writes `given` entries to a session, each put logged on failure and never thrown: the session gets its task all the same. */
+export declare function putEntries(ports: StandingPorts, sessionID: string, given: ReadonlyArray<Entry>): Promise<void>;

package/dist/tree/standing.js

@@ -0,0 +1,90 @@
+import { existsSync } from "node:fs";
+import { isStatus } from "../kernel/protocol.js";
+import { isNotFound } from "../platform/json.js";
+import { isExpired, standingOf } from "./domain.js";
+import { childStore, groupStore } from "./store.js";
+import { STANDING_KEY, standingEntry } from "./text.js";
+/** Whether `at` is known and no earlier than the prompt at `prompt`. */
+const since = (at, prompt) => at !== undefined && at >= prompt;
+/** A child's state from its report notes, as `reportOf` and the silent-turn rule read them. */
+export function stateOf(notes) {
+    const prompt = notes.prompt.at;
+    if (notes.stopped.at !== undefined && (prompt === undefined || notes.stopped.at >= prompt))
+        return { kind: "stopped" };
+    if (prompt === undefined)
+        return { kind: "started" };
+    const progressed = since(notes.progress.at, prompt) ? { progressed: true } : {};
+    if (!since(notes.settled.at, prompt))
+        return since(notes.told.at, prompt) ? { kind: "ended", ...progressed } : { kind: "working", ...progressed };
+    const { by, status } = notes.settled;
+    if (by === "failed" || by === "interrupted")
+        return { kind: by };
+    return { kind: "reported", status: isStatus(status) ? status : "done", ...progressed };
+}
+/** The rows of a parent's standing entry: its unexpired children, oldest first, each with its state and group standing. */
+export async function standingRows(storage, parentID, now) {
+    const children = childStore(storage);
+    // The groups read best effort, as courier_children reads them: a member's standing is `unknown` when they cannot be.
+    const [entries, members] = await Promise.all([children.children(parentID), groupStore(storage).ofParent(parentID).catch(() => undefined)]);
+    const current = entries.filter((entry) => !isExpired(entry, now, existsSync));
+    return Promise.all(current.map(async (entry) => {
+        const notes = await children.notes(entry.sessionID, ["prompt", "settled", "progress", "told", "stopped"]);
+        const member = members?.find((one) => one.group === entry.group && one.sessionID === entry.sessionID);
+        const standing = members ? standingOf(member) : "unknown";
+        return {
+            sessionID: entry.sessionID,
+            title: entry.title,
+            state: stateOf(notes),
+            ...(entry.group ? { group: { name: entry.group, standing } } : {}),
+        };
+    }));
+}
+/** The syncs under way in this process, by parent, each run after the one before it: a sync that read earlier never writes last. */
+const inTurn = new Map();
+/**
+ * Writes a parent's `standing` entry once something of it changed: put when its text differs from the entry's, removed when
+ * the parent has no children left; skipped without the keyed entries. A failure is logged, never thrown.
+ */
+export function syncStanding(ports, parentID) {
+    const entries = ports.session?.instructions?.entry;
+    if (!entries)
+        return Promise.resolve("skipped");
+    const before = inTurn.get(parentID) ?? Promise.resolve();
+    const run = before.then(() => sync(ports, parentID, entries));
+    const done = run.finally(() => {
+        if (inTurn.get(parentID) === done)
+            inTurn.delete(parentID);
+    });
+    inTurn.set(parentID, done);
+    return run;
+}
+async function sync(ports, parentID, entries) {
+    try {
+        const rows = await standingRows(ports.storage, parentID, ports.now());
+        const stored = (await entries.list({ sessionID: parentID })).find((entry) => entry.key === STANDING_KEY);
+        if (!rows.length) {
+            if (!stored)
+                return "absent";
+            await entries.remove({ sessionID: parentID, key: STANDING_KEY });
+            return "removed";
+        }
+        const value = standingEntry(rows);
+        if (stored?.value === value)
+            return "unchanged";
+        await entries.put({ sessionID: parentID, key: STANDING_KEY, value });
+        return "put";
+    }
+    catch (error) {
+        // A parent OpenCode no longer knows has no entry to keep: a child deleted after it is a normal path.
+        if (!isNotFound(error))
+            ports.log?.(`courier: the standing entry of ${parentID} could not be written, so it may be behind courier_children: ${String(error)}`);
+        return "skipped";
+    }
+}
+/** Writes `given` entries to a session, each put logged on failure and never thrown: the session gets its task all the same. */
+export async function putEntries(ports, sessionID, given) {
+    const entries = ports.session?.instructions?.entry;
+    if (!entries)
+        return;
+    await Promise.all(given.map(({ key, value }) => entries.put({ sessionID, key, value }).catch((error) => ports.log?.(`courier_spawn: the ${key} entry of ${sessionID} could not be written: ${String(error)}`))));
+}

package/dist/tree/status.d.ts

@@ -7,7 +7,7 @@ export interface StatusInput {
 export interface ChildrenInput {
     readonly sessionID?: string;
 }
-/** A one-off look at a session, for check-ins; not meant to be called in a loop. */
+/** One session's state and last reply, as courier_children shows each child. */
 export declare function status(ports: CourierPorts, input: StatusInput): Promise<Partial<{
     sessionID: string;
     title: string | undefined;
@@ -22,7 +22,7 @@ export declare function status(ports: CourierPorts, input: StatusInput): Promise
 /** 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
+ * The sessions a parent started, each with its state and last reply, 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<({
@@ -84,7 +84,7 @@ export declare function listChildren(ports: CourierPorts, parentID: string): Pro
     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. */
+/** One roster entry as courier_children shows it: the session's state with its directory and group standing, or the error it gave. */
 export declare function described(ports: CourierPorts, entry: RosterEntry): Promise<{
     group: {
         name: string;

package/dist/tree/status.js

@@ -2,7 +2,7 @@ import { describeFailure } from "../kernel/protocol.js";
 import { standingOf, startedAs } from "./domain.js";
 import { current } from "./roster.js";
 import { groupStore } from "./store.js";
-/** A one-off look at a session, for check-ins; not meant to be called in a loop. */
+/** One session's state and last reply, as courier_children shows each child. */
 export async function status(ports, input) {
     const [info, messages, pending] = await Promise.all([
         ports.session.get({ sessionID: input.sessionID }),
@@ -30,14 +30,14 @@ export function lastReply(messages) {
         : undefined;
 }
 /**
- * The sessions a parent started, each with what courier_status reports, or the error it gave; a child in a
+ * The sessions a parent started, each with its state and last reply, 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 async function listChildren(ports, parentID) {
     const entries = await current(ports.storage, parentID, ports.now());
     return Promise.all(entries.map((entry) => described(ports, entry)));
 }
-/** One roster entry as courier_children shows it: what courier_status reports with its directory and group standing, or the error it gave. */
+/** One roster entry as courier_children shows it: the session's state with its directory and group standing, or the error it gave. */
 export async function described(ports, entry) {
     const group = entry.group ? { group: { name: entry.group, report: await standingIn(ports, entry, entry.group) } } : {};
     const roster = { directory: entry.directory, ...startedAs(entry), created: entry.createdAt, ...group };
@@ -49,7 +49,7 @@ export async function described(ports, entry) {
             sessionID: entry.sessionID,
             title: entry.title,
             ...roster,
-            error: describeFailure("courier_status", error).message,
+            error: describeFailure("reading the session", error).message,
         };
     }
 }

package/dist/tree/stop.js

@@ -1,6 +1,7 @@
 import { isNotFound } from "../platform/json.js";
 import { describeFailure, envelope } from "../kernel/protocol.js";
 import { cleanup } from "./cleanup.js";
+import { syncStanding } from "./standing.js";
 import { childStore } from "./store.js";
 import { subtree } from "./subtree.js";
 import { stoppedNotice } from "./text.js";
@@ -37,6 +38,8 @@ export async function stop(ports, callerID, input) {
         return round(meanwhile, left - 1);
     };
     await round([{ entry: target, depth: 0 }, ...(await subtree(storage, sessionID)).nodes], ROUNDS);
+    // Each parent among them reads its stopped children at its next step; the caller's own entry, when it is the target's parent, too.
+    await Promise.all([...new Set(nodes.map((node) => node.entry.parentID))].map((parentID) => syncStanding(ports.courier, parentID)));
     const told = target.parentID !== callerID && results.find((one) => one.sessionID === sessionID)?.outcome === "interrupted"
         ? await tell(ports, callerID, target)
         : undefined;

package/dist/tree/store.js

@@ -65,10 +65,11 @@ const noteOf = (value) => ({ at: timeOf(value), by: obj(value).by, status: obj(v
 export function childStore(storage) {
     const entry = async (parentID, sessionID) => (await storage.get(rosterKey(parentID, sessionID)));
     const all = () => scanAll(storage, PREFIX);
-    const indexedParent = async (sessionID) => {
+    const indexedAncestors = async (sessionID) => {
         const indexed = await storage.get(reverseKey(sessionID));
-        return isReverse(indexed) ? indexed.ancestors[0] : undefined;
+        return isReverse(indexed) ? indexed.ancestors : [];
     };
+    const indexedParent = async (sessionID) => (await indexedAncestors(sessionID))[0];
     const walkIndex = async (sessionID, first) => {
         let indexed = first;
         const chain = [];
@@ -143,6 +144,7 @@ export function childStore(storage) {
             return found === undefined ? [] : [found];
         },
         indexedParent,
+        indexedAncestors,
         async indexedEntry(sessionID) {
             const parentID = await indexedParent(sessionID);
             return parentID === undefined ? undefined : entry(parentID, sessionID);

package/dist/tree/text.d.ts

@@ -1,16 +1,49 @@
 import { type ModelRef } from "./domain.js";
-import type { Artifacts, CleanupResult, ExecutionError, HeldReport, LeftMember, Limits, Sent } from "./ports.js";
+import type { Artifacts, CleanupResult, ExecutionError, HeldReport, LeftMember, Limits, Sent, Standing } from "./ports.js";
 /** The branch an isolated child commits its work on, and names in the `branch` of its report. */
 export declare const childBranch: (sessionID: string) => string;
 /** 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 declare function childBrief(parentID: string, task: string, depth: number, limits: Limits, branch?: string): string;
-/** How every part the context hook adds begins, so a second copy of the plugin does not add its own. */
+/** How every role part begins, in the role entry and in the part the context hook adds without one, so no second copy is added. */
 export declare const ROLE_PREFIX = "opencode-courier role:";
+/** The key of the session instruction entry carrying a spawned session's role part, `<context key="role">` in its system prompt. */
+export declare const ROLE_KEY = "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 declare function rolePart(depth: number | null, limits: Limits): string;
+/** The key of the session instruction entry on a parent listing the sessions it started, `<context key="standing">`. */
+export declare const STANDING_KEY = "standing";
+/** How every standing entry begins. */
+export declare const STANDING_PREFIX = "opencode-courier standing:";
+/** How many children the entry lists; older ones past that are counted. */
+export declare const STANDING_MAX = 10;
+/** What a child is doing, as its parent's standing entry says it; `reported` carries the status. */
+export type ChildState = {
+    readonly kind: "started" | "working" | "ended" | "failed" | "interrupted" | "stopped";
+    readonly progressed?: boolean;
+} | {
+    readonly kind: "reported";
+    readonly status: string;
+    readonly progressed?: boolean;
+};
+/** One child as the standing entry lists it. */
+export interface StandingRow {
+    readonly sessionID: string;
+    readonly title: string;
+    readonly state: ChildState;
+    /** Its join group and its standing there, `unknown` when that could not be read. */
+    readonly group?: {
+        readonly name: string;
+        readonly standing: Standing | "unknown";
+    };
+}
+/**
+ * The standing entry: one line per session the parent started, oldest first, with its state and its place in its join group,
+ * in the same words for the same state, so an unchanged standing is not put again.
+ */
+export declare function standingEntry(rows: ReadonlyArray<StandingRow>): string;
 export declare const depthRefusal: (depth: number, maxDepth: number) => string;
 export declare const childrenRefusal: (running: number, maxChildren: number) => string;
 export declare const totalRefusal: (running: number, maxTotal: number) => string;
@@ -38,10 +71,8 @@ export declare function spawnText(child: {
     /** The model it runs on, when that is not the caller's own. */
     readonly model?: string;
 }): string;
-/** courier_send's result: for a message to the session that started the sender, whether it was its report. */
-export declare function sendText(sessionID: string, sent?: Pick<Sent, "status" | "report" | "held">): string;
-/** courier_status's result: the session's state, as JSON. */
-export declare const statusText: (status: unknown) => string;
+/** courier_send's result: for a message to the session that started the sender, whether it was its report; below it, the status dropped. */
+export declare function sendText(sessionID: string, sent?: Pick<Sent, "status" | "report" | "held" | "dropped">): string;
 export declare const childrenText: (listed: ReadonlyArray<unknown>) => string;
 export declare function cleanupText(result: CleanupResult): string;
 /** courier_tree's result: the sessions under a session, drawn depth first, as JSON. */

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, ROOT_SPLIT_LINE, SKILL_ID, SPLIT_LINE, STATUSES } from "../kernel/protocol.js";
+import { clipText, defuse, defuseBlock, END_TURN, ROOT_SPLIT_LINE, SKILL_ID, SPLIT_LINE, STATUSES } from "../kernel/protocol.js";
 import { retryDelay } from "./domain.js";
 // The envelope and the child brief.
 /** How a text names the statuses a report may carry. */
@@ -20,8 +20,10 @@ export function childBrief(parentID, task, depth, limits, branch) {
         "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 find something the other parts of the job need (an assumption of the split that is wrong, a shared file or API " +
-            "that behaves otherwise, something the person told you), send it to the parent at once with courier_send without a " +
-            "status, then carry on: it passes it on to the sessions it affects. Progress alone is not worth a message.",
+            "that behaves otherwise), send it to the parent at once with courier_send without a status, then carry on: it passes " +
+            "it on to the sessions it affects. Progress alone is not worth a message.",
+        "A message the person writes in your session, outside a <courier> envelope, is for the whole job: before you act on it, " +
+            "send it to the parent at once with courier_send without a status, quoting it as the person's, then carry on.",
         "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), ""] : []),
@@ -56,13 +58,15 @@ function splitRule(parentID, depth, limits) {
             "One session alone, with nothing of the task done before it by you or by 2 or more parts, and fewer than 2 parts after it, is the whole task.",
         `- Say which in one line of your reply: ${SPLIT_LINE}.`,
         "- 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 " +
+            "then end your turn while they work. Do not poll with 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. */
+/** How every role part begins, in the role entry and in the part the context hook adds without one, so no second copy is added. */
 export const ROLE_PREFIX = "opencode-courier role:";
+/** The key of the session instruction entry carrying a spawned session's role part, `<context key="role">` in its system prompt. */
+export const ROLE_KEY = "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.
@@ -85,6 +89,67 @@ export function rolePart(depth, limits) {
     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.");
 }
+// The standing entry: what a parent's system prompt says of the sessions it started.
+/** The key of the session instruction entry on a parent listing the sessions it started, `<context key="standing">`. */
+export const STANDING_KEY = "standing";
+/** How every standing entry begins. */
+export const STANDING_PREFIX = "opencode-courier standing:";
+/** How many children the entry lists; older ones past that are counted. */
+export const STANDING_MAX = 10;
+/** The most characters of a child's title the entry shows. */
+const TITLE_MAX = 40;
+function stateWords(state) {
+    const progressed = state.progressed ? ", sent progress" : "";
+    switch (state.kind) {
+        case "started":
+            return "started";
+        case "working":
+            return `working${progressed}`;
+        case "ended":
+            return `ended its turn without a report${progressed}`;
+        case "failed":
+            return "its turn failed";
+        case "interrupted":
+            return "its turn was interrupted";
+        case "stopped":
+            return "stopped";
+        case "reported":
+            return `reported ${state.status}`;
+    }
+}
+function groupWords(name, standing) {
+    const group = `group "${name}"`;
+    switch (standing) {
+        case "held":
+            return `its report is held with ${group}`;
+        case "out":
+            return `${group} waits for it`;
+        case "released":
+            return `${group} was delivered`;
+        case "unknown":
+            return `in ${group}`;
+        default:
+            return `out of ${group} (${LEFT_HOW[standing]})`;
+    }
+}
+/**
+ * The standing entry: one line per session the parent started, oldest first, with its state and its place in its join group,
+ * in the same words for the same state, so an unchanged standing is not put again.
+ */
+export function standingEntry(rows) {
+    const shown = rows.slice(-STANDING_MAX);
+    const older = rows.length - shown.length;
+    return [
+        `${STANDING_PREFIX} the sessions you started with courier_spawn, each with its state, kept current as it changes, so you need ` +
+            "not look with courier_children or courier_tree; a report, a group's reports or a notice still reach you as a message.",
+        ...shown.map((row) => {
+            const title = defuseBlock(row.title.replace(/\s+/g, " ").trim());
+            const group = row.group ? `; ${groupWords(row.group.name, row.group.standing)}` : "";
+            return `- ${row.sessionID} "${clipText(title, TITLE_MAX)}": ${stateWords(row.state)}${group}`;
+        }),
+        ...(older ? [`${count(older, "older session")} not listed; courier_children lists them.`] : []),
+    ].join("\n");
+}
 // 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.";
@@ -166,8 +231,11 @@ export function spawnText(child) {
     return (`Started session ${child.sessionID} in ${child.directory}${on}. ${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. */
+/** courier_send's result: for a message to the session that started the sender, whether it was its report; below it, the status dropped. */
 export function sendText(sessionID, sent = {}) {
+    if (sent.dropped)
+        return (`Delivered to ${sessionID}, without the status ${sent.dropped}: a status belongs on a report to the session that ` +
+            "started you, and means nothing on a message to a session you started.");
     const status = sent.status ? `, status ${sent.status}` : "";
     if (sent.held) {
         const { group, reported, members } = sent.held;
@@ -185,8 +253,6 @@ export function sendText(sessionID, sent = {}) {
         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")

package/dist/tree/tools.d.ts

@@ -30,9 +30,6 @@ export declare const SendInput: Schema.Struct<{
     }>>;
     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>;
 }>;