opencode-courier 0.13.6 → 0.13.7

package/README.md

@@ -23,7 +23,7 @@ A narrated tour of the terminal UI: the tree panel, the asks inbox, failing chil
 ## Quickstart
 
 ```bash
-npm install -g @opencode/cli@2.2.4   # OpenCode V2, the version courier is tested on
+npm install -g @opencode/cli@2.2.5   # OpenCode V2, the version courier is tested on
 opencode plugin add opencode-courier
 opencode
 ```
@@ -58,8 +58,9 @@ or stuck, the child calls `courier_send` with a status (`done`, `partial`, `bloc
 The message lands in the parent's inbox and starts a new turn if the parent is idle.
 
 Children started with the same `group` report together, in one message. A child that fails (a
-rate or quota limit with when it lifts), or ends its turn without reporting, is reported to its
-parent. A message that does not wake its session is sent once more, then shown as `stalled`. On
+rate or quota limit with when it lifts) is reported to its parent. One about to end its turn
+without reporting is reminded once, in the same turn, and its parent is told only if it still does
+not report. A message that does not wake its session is sent once more, then shown as `stalled`. On
 OpenCode 2.2.0 a parent's system prompt carries one line per child with its state, kept current,
 so it need not look. Children, held reports and scheduled messages survive a restart. The `courier-orchestrate` skill, listed in every session, tells a model when to
 split a task and how to check and merge the parts. Every detail: [the reference](docs/reference.md).
@@ -67,10 +68,10 @@ split a task and how to check and merge the parts. Every detail: [the reference]
 ## Install
 
 Requires OpenCode V2: the `opencode` command from `@opencode/cli`. Each release is tested against
-one OpenCode version; this one is tested on **OpenCode 2.2.4** (check with `opencode --version`).
+one OpenCode version; this one is tested on **OpenCode 2.2.5** (check with `opencode --version`).
 
 ```bash
-npm install -g @opencode/cli@2.2.4
+npm install -g @opencode/cli@2.2.5
 opencode plugin add opencode-courier
 ```
 
@@ -83,13 +84,13 @@ name, without a version: OpenCode offers updates only for an entry without an ex
 <!-- compat-table:start rows=3: generated by script/compat-table.ts from the release tags -->
 | opencode-courier | OpenCode V2 (`opencode` and `@opencode/plugin`) |
 |---|---|
+| 0.13.7 | 2.2.5 |
 | 0.13.6 | 2.2.4 |
 | 0.13.5 | 2.2.3 |
-| 0.13.2, 0.13.3, 0.13.4 | 2.2.2 |
 <!-- compat-table:end -->
 
 Every release: [the full table](docs/reference.md#the-opencode-version). The server part loads on
-any V2 host from 2.0.4 on. The terminal part is tested on OpenCode 2.2.4 only.
+any V2 host from 2.0.4 on. The terminal part is tested on OpenCode 2.2.5 only.
 
 ## Options
 

package/dist/index.js

@@ -10,7 +10,7 @@ import { addSchedulingTools, cancelScheduled, dueJob, isScheduled } from "./sche
 import { addPersonTools, asksPermission, asksQuestion, formsShown, joinRelay, noticeCutOff, pendingOf, pendingQuestions, personEvents, portsAt, registerPersonRpc, relayQuestions, } from "./person/index.js";
 import { addMemoryTools, lessonsOf, memoryEvents, NOTE_TOOL, readMemory, RECALL_TOOL, registerMemoryRpc, sweepRecords } from "./memory/index.js";
 import { addSkill } from "./skill.js";
-import { addTreeTools, deliverReleased, wakeMissed, dirtyOf, headOf, inspectWorktree, pruneExpired, readLimits, readNativeChildren, registerTreeRpc, shapeContext, together, treeEvents, waitsOn, } from "./tree/index.js";
+import { addTreeTools, deliverReleased, wakeMissed, dirtyOf, headOf, inspectWorktree, onIdle, pruneExpired, readLimits, readNativeChildren, registerTreeRpc, shapeContext, together, treeEvents, waitsOn, } from "./tree/index.js";
 import { addWebhookTools, joinReceiver, readConfig, receiving, subscribedSince, } from "./webhook/index.js";
 /** The spawns under way in the process, outside the hub, so spawns in other locations, copies and hub versions count them. */
 const gate = sharedState("spawning", () => ({ reserved: new Set(), turn: Promise.resolve() }));
@@ -171,6 +171,11 @@ export const courier = () => Plugin.define({
             log: later.log,
             nudge,
         };
+        // A spawned session about to go idle owing a report is reminded once, in the same execution. The hook is
+        // experimental, and a host before 2.2.4 lacks it: the rest loads all the same, and its parents are told as before.
+        await Promise.resolve()
+            .then(() => ctx.session.hook("experimental.idle", (event) => onIdle(watchPorts, watchState.seen, outside, event).then(() => undefined)))
+            .catch((error) => log(`courier idle: not registered, a child that ends without a report is not reminded: ${String(error)}`));
         // The hub's subscriptions to OpenCode's events, one and a standby, start with this copy's modules.
         watchFromHub(hub, eventModules);
         const member = {

package/dist/tree/events.js

@@ -3,7 +3,8 @@ import { claim, SEEN_MAX, setBounded } from "../platform/bounded.js";
 import { endsIdle, retryDelay } from "./domain.js";
 import { forgetChild, forgetDeleted } from "./forget.js";
 import { hasCompleteGroup, leave, outIn } from "./group.js";
-import { awaited, reportOf, stoppedSincePrompt } from "./report.js";
+import { owedUnwaited } from "./nudge.js";
+import { stoppedSincePrompt } from "./report.js";
 import { syncStanding } from "./standing.js";
 import { childStore, groupStore } from "./store.js";
 import { lastReply } from "./status.js";
@@ -71,6 +72,9 @@ export async function notePrompt(ports, event, inbox) {
     const parentID = await children.indexedParent(sessionID);
     if (parentID === undefined)
         return false;
+    // The reminder to report is not a prompt: it asks for the report the last one owes.
+    if (inboxID !== undefined && (await children.nudgeOf(sessionID)).inboxID === inboxID)
+        return false;
     await children.prompted(sessionID, event.created ?? ports.now());
     await syncStanding(ports, parentID);
     return true;
@@ -122,20 +126,6 @@ export const waitsOn = (...suppliers) => async (ports, sessionID, since) => {
 };
 /** A `Waits` asking `suppliers` at once, as cheap as each other: it waits when one does, and fails when one fails. */
 export const together = (...suppliers) => async (ports, sessionID, since) => (await Promise.all(suppliers.map((supplier) => supplier(ports, sessionID, since)))).includes(true);
-/**
- * Whether a session prompted at `prompt` waits: on an untold report of a session it started, a complete group of
- * its about to be delivered, or what `outside` says it waits on. Cheapest first.
- */
-async function waits(ports, outside, sessionID, prompt) {
-    const children = childStore(ports.storage);
-    const started = await children.children(sessionID);
-    if ((await Promise.all(started.map((entry) => awaited(children, entry.sessionID)))).includes(true))
-        return true;
-    // A group with a member still out is waited on through that member, above; one whose every out member was told of is not.
-    if (started.some((entry) => entry.group) && (await hasCompleteGroup(groupStore(ports.storage), sessionID)))
-        return true;
-    return outside(ports, sessionID, prompt);
-}
 /**
  * Tells the parent of a spawned session whose turn ended without reporting to it since its last
  * prompt, unless it waits; finds the session by the reverse index alone. Returns the parents told.
@@ -147,10 +137,8 @@ export async function reportSilent(ports, seen, event, outside) {
     // Claimed after the lookup, so other sessions' turns do not crowd `seen`, and before anything is told.
     if (!entry || !claim(seen, event.id))
         return [];
-    const report = await reportOf(children, sessionID);
-    if (!report?.owes || (await waits(ports, outside, sessionID, report.prompt)))
-        return [];
-    if (await stoppedSincePrompt(children, sessionID).catch(() => false))
+    const report = await owedUnwaited(ports, children, outside, sessionID);
+    if (!report)
         return [];
     // The notice goes out without the reply rather than not at all.
     const lastText = await ports.session.context({ sessionID }).then(lastReply, () => undefined);

package/dist/tree/index.d.ts

@@ -3,6 +3,7 @@ export { shapeContext } from "./context.js";
 export { endsIdle, lineageIn, nativeRootOf, readLimits, readNativeChildren } from "./domain.js";
 export { together, treeEvents, waitsOn } from "./events.js";
 export { deliverReleased } from "./group.js";
+export { onIdle } from "./nudge.js";
 export { contextOf } from "./panel.js";
 export type { CleanupPorts, CourierPorts, Entries, Entry, Instructions, ModelWindow, Pending, PendingPrompt, Role, RosterEntry, RosterStorage, ShownForm, SpawnGate, Waits, WatchPorts, WatchState, } from "./ports.js";
 export { allEntries, answeringTop, childrenOf, indexedLineage, lineage, pruneExpired, reportState, RETENTION_MS, type ReportState } from "./roster.js";

package/dist/tree/index.js

@@ -5,6 +5,7 @@ export { shapeContext } from "./context.js";
 export { endsIdle, lineageIn, nativeRootOf, readLimits, readNativeChildren } from "./domain.js";
 export { together, treeEvents, waitsOn } from "./events.js";
 export { deliverReleased } from "./group.js";
+export { onIdle } from "./nudge.js";
 export { contextOf } from "./panel.js";
 export { allEntries, answeringTop, childrenOf, indexedLineage, lineage, pruneExpired, reportState, RETENTION_MS } from "./roster.js";
 export { runs, turnIn, turnOf } from "./running.js";

package/dist/tree/nudge.d.ts

@@ -0,0 +1,28 @@
+import type { ChildStore, Waits, WatchPorts } from "./ports.js";
+/** OpenCode's `experimental.idle` hook event: a session about to go idle, and the background work still running for it or below it. */
+export interface Idle {
+    readonly sessionID: string;
+    readonly background: ReadonlyArray<{
+        readonly sessionID: string;
+    }>;
+}
+/** The ports the reminder is sent through: the watcher's. */
+export type NudgePorts = Pick<WatchPorts, "storage" | "session" | "permissions" | "now" | "log">;
+/**
+ * The report a spawned session owes since its last prompt, unless it waits or courier_stop stopped it since: what the
+ * silent-turn notice tells the parent of, and the reminder reminds the session of.
+ */
+export declare function owedUnwaited(ports: NudgePorts, children: ChildStore, outside: Waits, sessionID: string): Promise<{
+    resumesAt?: number | undefined;
+    prompt: number;
+    owes: boolean;
+    progressed: boolean;
+    ended: boolean;
+} | undefined>;
+/**
+ * Reminds a spawned session about to go idle owing a report it does not wait on, once per prompt, so it reports in the
+ * same execution; one with background work of its own is woken again by it. Returns whether it was reminded.
+ */
+export declare function nudgeSilent(ports: NudgePorts, seen: Set<string>, outside: Waits, idle: Idle): Promise<boolean>;
+/** `nudgeSilent` as the hook runs it: a hook that fails fails the execution, so a failure is logged, never thrown. */
+export declare function onIdle(ports: NudgePorts, seen: Set<string>, outside: Waits, idle: Idle): Promise<boolean>;

package/dist/tree/nudge.js

@@ -0,0 +1,75 @@
+import { envelope } from "../kernel/protocol.js";
+import { claim } from "../platform/bounded.js";
+import { hasCompleteGroup } from "./group.js";
+import { awaited, reportOf, stoppedSincePrompt } from "./report.js";
+import { childStore, groupStore } from "./store.js";
+import { reportReminder } from "./text.js";
+/**
+ * Whether a session prompted at `prompt` waits: on an untold report of a session it started, a complete group of
+ * its about to be delivered, or what `outside` says it waits on. Cheapest first.
+ */
+async function waits(ports, outside, sessionID, prompt) {
+    const children = childStore(ports.storage);
+    const started = await children.children(sessionID);
+    if ((await Promise.all(started.map((entry) => awaited(children, entry.sessionID)))).includes(true))
+        return true;
+    // A group with a member still out is waited on through that member, above; one whose every out member was told of is not.
+    if (started.some((entry) => entry.group) && (await hasCompleteGroup(groupStore(ports.storage), sessionID)))
+        return true;
+    return outside(ports, sessionID, prompt);
+}
+/**
+ * The report a spawned session owes since its last prompt, unless it waits or courier_stop stopped it since: what the
+ * silent-turn notice tells the parent of, and the reminder reminds the session of.
+ */
+export async function owedUnwaited(ports, children, outside, sessionID) {
+    const report = await reportOf(children, sessionID);
+    if (!report?.owes || (await waits(ports, outside, sessionID, report.prompt)))
+        return undefined;
+    if (await stoppedSincePrompt(children, sessionID).catch(() => false))
+        return undefined;
+    return report;
+}
+/**
+ * Reminds a spawned session about to go idle owing a report it does not wait on, once per prompt, so it reports in the
+ * same execution; one with background work of its own is woken again by it. Returns whether it was reminded.
+ */
+export async function nudgeSilent(ports, seen, outside, idle) {
+    const { sessionID } = idle;
+    if (idle.background.some((work) => work.sessionID === sessionID))
+        return false;
+    const children = childStore(ports.storage);
+    const parentID = await children.indexedParent(sessionID);
+    if (parentID === undefined)
+        return false;
+    const report = await owedUnwaited(ports, children, outside, sessionID);
+    if (!report)
+        return false;
+    const { at: nudgedAt } = await children.nudgeOf(sessionID);
+    if ((nudgedAt !== undefined && nudgedAt >= report.prompt) || !claim(seen, `nudge/${sessionID}/${report.prompt}`))
+        return false;
+    const at = Math.max(ports.now(), report.prompt);
+    // Noted before it is sent, so a second hook never sends another, and with its id after, before the turn takes it.
+    await children.nudged(sessionID, at);
+    const { id } = await ports.session.synthetic({
+        sessionID,
+        text: envelope("courier", reportReminder(parentID), { reminder: "report" }),
+        description: "Reminded to report",
+        metadata: { source: "courier", reminder: "report", resume: false },
+        delivery: "steer",
+        // The hook's own execution takes it: no wake, and the missed-wake watch leaves it be.
+        resume: false,
+    });
+    await children.nudged(sessionID, at, id);
+    return true;
+}
+/** `nudgeSilent` as the hook runs it: a hook that fails fails the execution, so a failure is logged, never thrown. */
+export async function onIdle(ports, seen, outside, idle) {
+    try {
+        return await nudgeSilent(ports, seen, outside, idle);
+    }
+    catch (error) {
+        ports.log(`courier idle: could not remind ${idle.sessionID} to report: ${String(error)}`);
+        return false;
+    }
+}

package/dist/tree/ports.d.ts

@@ -12,7 +12,7 @@ export type RosterStorage = Storage;
 /** How a session's wait for a report ended: it reported to its parent, or its turn failed or was interrupted. */
 export type Settled = "report" | "failed" | "interrupted";
 /** The notes kept of a spawned session's report state; docs/maintainers/architecture.md has each. */
-export type ReportField = "prompt" | "settled" | "progress" | "told" | "stopped";
+export type ReportField = "prompt" | "settled" | "progress" | "told" | "stopped" | "nudged";
 /** A report note as read: when it was made, and for `settled` how the wait ended, the report's status or a failure's `resumesAt`, as stored. */
 export interface ReportNote {
     readonly at: number | undefined;
@@ -75,6 +75,13 @@ export interface ChildStore {
     untold(sessionID: string, at: number): Promise<void>;
     /** Notes that courier_stop stopped a spawned session at `at`. */
     stopped(sessionID: string, at: number): Promise<void>;
+    /** Notes that a spawned session was reminded at `at` to report, with the reminder's inbox id once it is admitted. */
+    nudged(sessionID: string, at: number, inboxID?: string): Promise<void>;
+    /** When a spawned session was last reminded to report, and the reminder's inbox id. */
+    nudgeOf(sessionID: string): Promise<{
+        readonly at: number | undefined;
+        readonly inboxID?: string;
+    }>;
     /** A `settled` or `progress` note as stored, for `restore` to put back. */
     peek(sessionID: string, field: "settled" | "progress"): Promise<Stored | undefined>;
     /** Puts back a note `peek` read; one that was not there is removed. */

package/dist/tree/store.d.ts

@@ -14,6 +14,7 @@ export declare const settledKey: (sessionID: string) => string;
 export declare const progressKey: (sessionID: string) => string;
 export declare const toldKey: (sessionID: string) => string;
 export declare const stoppedKey: (sessionID: string) => string;
+export declare const nudgedKey: (sessionID: string) => string;
 export declare const memberKey: (parentID: string, group: string, sessionID: string) => string;
 /** The key prefix of a parent's groups, and of one group's members. */
 export declare const groupsPrefix: (parentID: string) => string;

package/dist/tree/store.js

@@ -17,8 +17,8 @@ export function reverseKey(sessionID) {
     return `${BY_CHILD}${sessionID}`;
 }
 /**
- * Whether a spawned session has reported since its last prompt, under `report/<sessionID>/`: `prompt`, `settled` (with
- * the report's status, or when a failed turn's wait lifts), `progress` (a message to its parent without a status) and `told`; docs/maintainers/architecture.md has each.
+ * Whether a spawned session has reported since its last prompt, under `report/<sessionID>/`: `prompt`, `settled`, `progress`,
+ * `told`, `stopped` and `nudged` (the reminder to report); docs/maintainers/architecture.md has each.
  */
 const REPORT_PREFIX = "report/";
 export const promptKey = (sessionID) => `${REPORT_PREFIX}${sessionID}/prompt`;
@@ -26,12 +26,14 @@ export const settledKey = (sessionID) => `${REPORT_PREFIX}${sessionID}/settled`;
 export const progressKey = (sessionID) => `${REPORT_PREFIX}${sessionID}/progress`;
 export const toldKey = (sessionID) => `${REPORT_PREFIX}${sessionID}/told`;
 export const stoppedKey = (sessionID) => `${REPORT_PREFIX}${sessionID}/stopped`;
+export const nudgedKey = (sessionID) => `${REPORT_PREFIX}${sessionID}/nudged`;
 const REPORT_KEYS = {
     prompt: promptKey,
     settled: settledKey,
     progress: progressKey,
     told: toldKey,
     stopped: stoppedKey,
+    nudged: nudgedKey,
 };
 /**
  * Join groups: each member of a parent's group under `group/<parentID>/<name>/<sessionID>`, with its
@@ -195,6 +197,14 @@ export function childStore(storage) {
         async stopped(sessionID, at) {
             await storage.set(stoppedKey(sessionID), { at });
         },
+        async nudged(sessionID, at, inboxID) {
+            await storage.set(nudgedKey(sessionID), { at, ...(inboxID === undefined ? {} : { inboxID }) });
+        },
+        async nudgeOf(sessionID) {
+            const value = await storage.get(nudgedKey(sessionID));
+            const inboxID = str(obj(value).inboxID);
+            return { at: timeOf(value), ...(inboxID === undefined ? {} : { inboxID }) };
+        },
         async peek(sessionID, field) {
             const value = await storage.get(REPORT_KEYS[field](sessionID));
             return value;

package/dist/tree/text.d.ts

@@ -108,6 +108,8 @@ export declare function keepReason(state: {
  * retry time (`retryAfterMs`) counts from. Message the child before that and it fails again, so the notice says to wait.
  */
 export declare function failureNotice(title: string, error: ExecutionError, group?: string, at?: number): string;
+/** The one reminder a spawned session gets as it is about to end its turn owing its parent a report; it carries on in the same turn. */
+export declare function reportReminder(parentID: string): string;
 /**
  * What the parent is told when a session it started ends its turn without a report to it;
  * `progressed` when it messaged the parent without a status since its last prompt.

package/dist/tree/text.js

@@ -364,6 +364,15 @@ export function failureNotice(title, error, group, at) {
             : []),
     ].join("\n");
 }
+/** The one reminder a spawned session gets as it is about to end its turn owing its parent a report; it carries on in the same turn. */
+export function reportReminder(parentID) {
+    return [
+        `You are about to end your turn without reporting to session ${parentID}, which started you.`,
+        `If you are finished, send your report now: call courier_send with sessionID "${parentID}", a short account of what you did and ` +
+            `status ${STATUS_LIST}. If work is left, carry on and report when you finish.`,
+        "This reminder comes once: if you end your turn without a report, the session that started you is told.",
+    ].join("\n");
+}
 /** Longest last reply a notice that a session ended its turn without reporting quotes. */
 const MAX_REPLY = 2000;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-courier",
-  "version": "0.13.6",
+  "version": "0.13.7",
   "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,12 +56,12 @@
     "test:e2e": "e2e/run.sh"
   },
   "peerDependencies": {
-    "@opencode/plugin": "2.2.4",
+    "@opencode/plugin": "2.2.5",
     "effect": "4.0.6"
   },
   "devDependencies": {
-    "@opencode/plugin": "2.2.4",
-    "@opencode/theme": "2.2.4",
+    "@opencode/plugin": "2.2.5",
+    "@opencode/theme": "2.2.5",
     "@opentui/core": "0.8.0",
     "@opentui/solid": "0.8.0",
     "@types/bun": "1.4.2",