opencode-courier 0.3.0 → 0.4.0

package/dist/platform/hub.d.ts

@@ -0,0 +1,195 @@
+import { type Registry, type Storage } from "./storage.js";
+/**
+ * The plugin's process-wide state on `globalThis`, shared by every loaded copy; only this module puts
+ * it there. `HUB_VERSION`, the fixed claim keys and version skew: docs/maintainers/architecture.md, § Several copies in one process.
+ */
+export declare const HUB_VERSION = 2;
+/** The key of the hub; a copy that finds another version there keeps its own under `${HUB_KEY}@<version>`. */
+export declare const HUB_KEY = "opencode-courier.hub";
+/** The ports a member's scheduler keeps the owner key through: what every member's `later` ports have. */
+export interface TickPorts {
+    readonly storage: Pick<Storage, "get" | "set" | "remove">;
+    readonly now: () => number;
+}
+/**
+ * The events handled, and the permission requests a session was told about or that were answered
+ * first: claim sets shared by every subscription and copy, so each event is handled once.
+ */
+export interface Watched {
+    readonly seen: Set<string>;
+    readonly waiting: Set<string>;
+    readonly answered: Set<string>;
+}
+/** The forms sessions were told about, kept apart from the permission requests. */
+export interface FormsTold {
+    /** Forms still shown whose notice went out, or is going out: the notice's delivery. */
+    readonly told: Map<string, Promise<unknown>>;
+    /** Forms settled before anyone was told, so a notice whose roster lookup was overtaken is not sent. */
+    readonly settled: Set<string>;
+}
+/**
+ * A loaded plugin instance: its location's directory and permission domain, and the ports a job
+ * run once for the whole process would run it through.
+ */
+export interface Member {
+    readonly directory: string;
+    /**
+     * The location OpenCode set the instance up with, the very object the instance's Effect half is
+     * handed too, which finds its member by it (`portsAt`). A member of a copy before it has none.
+     */
+    readonly location?: object;
+    /** The location's permission domain, kept in `locations`. */
+    readonly permission: unknown;
+    /** The ports the scheduler's tick runs through: the owner key's, and the tick jobs'. */
+    readonly later: TickPorts;
+    /** The ports the hub's subscriptions to OpenCode's events run through. */
+    readonly watch: unknown;
+    /** The question relay's ports. */
+    readonly questions: unknown;
+    readonly log: (message: string) => void;
+}
+/**
+ * A tick under way: the member it runs through, when it started, by the wall clock every member's
+ * `now` reads (the next ticks compare it with another member's), and its end.
+ */
+export interface Tick {
+    readonly member: Member;
+    readonly since: number;
+    /** Settles once the tick has ended, the owner key released if its loop stopped meanwhile; never rejects. */
+    readonly done: Promise<void>;
+}
+/**
+ * The scheduler's loop, one per hub: it runs while the hub has members, and each tick runs the jobs
+ * registered with `open` through the ports of the member that joined first and is still loaded.
+ */
+export interface Scheduler {
+    /** The loop's interval, while it runs. */
+    timer?: unknown;
+    /**
+     * The tick under way, whichever copy started it: for a minute the key is renewed for it and due
+     * ticks skip; past it, one whose member left holds nothing up. Older copies have only `ticking`.
+     */
+    running?: Tick;
+    /**
+     * The member the tick under way runs through, if any, set and cleared with `running`, for a copy
+     * that reads only this: a tick that falls due meanwhile is skipped, unless that member has left.
+     */
+    ticking?: Member;
+    /** One tick, by the copy of the plugin that joined last, so a copy loaded after an update runs its own code. */
+    tick?: () => Promise<void>;
+    /** Whether a nudge came since the tick under way started, whichever copy's, so it ticks once more when done. */
+    nudged?: boolean;
+}
+/** How the hub starts and stops the scheduler's loop, and waits before re-reading the owner key; tests pass their own. */
+export interface Timers {
+    readonly every: (run: () => void, ms: number) => unknown;
+    readonly stop: (timer: unknown) => void;
+    readonly wait: (ms: number) => Promise<void>;
+}
+/** How often the hub's scheduler ticks: what a job delivers, a `courier_later` message, can be this late. */
+export declare const TICK_MS = 15000;
+/**
+ * The storage key, shared by every server on one data directory, naming the server whose scheduler
+ * delivers `courier_later` messages: `{ server, at }`, its id and when it last wrote (epoch ms).
+ */
+export declare const OWNER_KEY = "scheduler/owner";
+/** How long the owner key holds without being renewed; the owner renews it every tick, four times as often. */
+export declare const OWNER_EXPIRY_MS: number;
+/**
+ * How old the owner's own key may be for it to renew the key and deliver at once. An older one,
+ * which it may no longer hold by the time it writes, is taken again like a free one, with the wait.
+ */
+export declare const OWNER_RENEW_MS: number;
+/** The wait between writing the owner key and reading it back, at least `OWNER_WAIT_MS` and up to twice that. */
+export declare const OWNER_WAIT_MS = 500;
+/**
+ * This server's id in the owner key: the same for every copy of the plugin in the process, and
+ * different in every other process, a restart of this one included.
+ */
+export declare const SERVER: string;
+/**
+ * How long an unloading instance waits for the work it leaves behind: what it started itself, a tick
+ * or a notice under way through it, and on the last leave the owner key's release.
+ */
+export declare const LEAVE_MS = 2000;
+/** How many subscriptions to OpenCode's events a hub keeps, each through another member: one, and a standby. */
+export declare const WATCHERS = 2;
+/** One of the hub's subscriptions to OpenCode's events: the member whose ports it runs through, and how it ends. */
+export interface Watcher {
+    readonly member: Member;
+    readonly stop: AbortController;
+    /** Settles once the subscription has ended, after `stop`: after the event it is handling, not the stream's close. */
+    readonly done: Promise<void>;
+}
+export interface Hub {
+    readonly version: typeof HUB_VERSION;
+    /** The instances loaded now, in the order they joined. */
+    readonly members: Set<Member>;
+    readonly scheduler: Scheduler;
+    /**
+     * The hub's subscriptions to OpenCode's events, each through another member: two while two members
+     * are loaded, so one is always connected when the other's member leaves.
+     */
+    readonly watchers: Watcher[];
+    /**
+     * Starts a subscription through a member, by the copy of the plugin that set it last; until one
+     * has, the hub follows no events.
+     */
+    subscribe?: (member: Member) => Watcher;
+    /** The ids of the `courier_later` messages being delivered. */
+    readonly claimed: Set<string>;
+    /** The events handled, and the permission requests a session was told about or that were answered first. */
+    readonly watched: Watched;
+    /** The forms sessions were told about, and those settled first. */
+    readonly forms: FormsTold;
+    /**
+     * The permission domain of every loaded instance, by instance. OpenCode keeps a request where its
+     * session runs, so a request of an isolated child is answered through the instance loaded in its worktree.
+     */
+    readonly locations: Map<object, unknown>;
+    /** The webhook receiver's state: the object every copy shares under the key `receiver`. */
+    readonly receivers: object;
+    /** The question relay's state: the object every copy shares under the key `questions`. */
+    readonly questions: object;
+    /** Whether the hub of another version found under `HUB_KEY` has been logged. */
+    skewLogged: boolean;
+}
+/**
+ * A job each tick runs, in its turn, through the first loaded member, which may be another copy's:
+ * it uses only the ports every hub-v2 member has. `claimed` is the hub's claim set; a throw ends the tick.
+ */
+export type TickJob = (owner: Member, claimed: Set<string>) => Promise<void>;
+/** A hub, as `open` finds or makes it, and how instances join it. */
+export interface Opened {
+    readonly hub: Hub;
+    /**
+     * Adds a loaded instance to the hub and `locations`; returns its leave. The first join starts the
+     * scheduler and watchers, the last leave stops them; a leave waits `LEAVE_MS` for the member's work.
+     */
+    readonly join: (member: Member) => () => Promise<void>;
+    /** Hands the hub work a member started, which its leave waits for; the member's own background work. */
+    readonly track: (member: Member, work: Promise<unknown>) => void;
+    /**
+     * Runs a tick now, or once the tick under way has ended, so what has just fallen due (a released
+     * group) is delivered at once rather than at the next tick; nothing while no instance is loaded.
+     */
+    readonly nudge: () => void;
+}
+/**
+ * The value under `opencode-courier.<name>` every copy in the process shares, made by `create` the first
+ * time; another version, or a copy before the hub, may have made it, so its shape is kept for good.
+ */
+export declare function sharedState<T>(name: string, create: () => T, registry?: Registry): T;
+/**
+ * This copy's hub in `registry`, and how its instances join it. Its ticks run `jobs` in order, kept in
+ * this copy's tick, which the hub runs once this copy has joined last, never in the hub itself.
+ */
+export declare function open(registry: Registry, jobs: readonly TickJob[], timers?: Timers, server?: string): Opened;
+/** This copy's hub, in the process. */
+export declare const hub: Hub;
+/** Opens this copy's hub in the process, with its tick jobs; see `open`. */
+export declare const openInProcess: (jobs: readonly TickJob[]) => Opened;
+/** The member of this copy's hub set up with `location` that joined last, while it is loaded. */
+export declare function memberAt(location: object): Member | undefined;
+/** The permission domains of the loaded instances. */
+export declare const permissions: () => MapIterator<unknown>;

package/dist/{hub.js → platform/hub.js}

@@ -1,12 +1,10 @@
 import { randomInt } from "node:crypto";
 import { hostname } from "node:os";
-import { deliverReleased } from "./group.js";
 import { num, obj, str } from "./json.js";
-import { deliverDue, TICK_MS } from "./later.js";
 import { processWide } from "./storage.js";
 /**
  * The plugin's process-wide state on `globalThis`, shared by every loaded copy; only this module puts
- * it there. `HUB_VERSION`, the fixed claim keys and version skew: docs/reference.md, § Several copies.
+ * it there. `HUB_VERSION`, the fixed claim keys and version skew: docs/maintainers/architecture.md, § Several copies in one process.
  */
 export const HUB_VERSION = 2;
 /** The key of the hub; a copy that finds another version there keeps its own under `${HUB_KEY}@<version>`. */
@@ -16,6 +14,8 @@ const realTimers = {
     stop: (timer) => clearInterval(timer),
     wait: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
 };
+/** How often the hub's scheduler ticks: what a job delivers, a `courier_later` message, can be this late. */
+export const TICK_MS = 15_000;
 /**
  * The storage key, shared by every server on one data directory, naming the server whose scheduler
  * delivers `courier_later` messages: `{ server, at }`, its id and when it last wrote (epoch ms).
@@ -50,27 +50,19 @@ export const LEAVE_MS = 2_000;
 const holds = (at, now, ms) => Math.abs(now - at) < ms;
 /** How many subscriptions to OpenCode's events a hub keeps, each through another member: one, and a standby. */
 export const WATCHERS = 2;
+/**
+ * The value under `opencode-courier.<name>` every copy in the process shares, made by `create` the first
+ * time; another version, or a copy before the hub, may have made it, so its shape is kept for good.
+ */
+export function sharedState(name, create, registry = globalThis) {
+    return processWide(`opencode-courier.${name}`, create, registry);
+}
 /**
  * Finds or makes this copy's hub in `registry`: the one under `HUB_KEY`, or its own under a versioned
  * key when another version holds that; its claim sets are the pre-hub keys', made when missing.
  */
-export function open(registry, timers = realTimers, server = SERVER) {
-    const shared = (name, create) => processWide(`opencode-courier.${name}`, create, registry);
-    const questionState = () => {
-        // Field by field, since a copy before the hub may have made it without the fields added later.
-        const state = shared("questions", () => ({}));
-        state.questions ??= new Map();
-        state.noticed ??= new Set();
-        state.shown ??= new Map();
-        state.passing ??= new Map();
-        state.answered ??= new Set();
-        state.loaded ??= new Set();
-        state.following ??= 0;
-        state.followed ??= false;
-        state.shutdowns ??= new Map();
-        state.closingWaiters ??= new Set();
-        return state;
-    };
+function find(registry) {
+    const shared = (name, create) => sharedState(name, create, registry);
     const create = () => ({
         version: HUB_VERSION,
         members: new Set(),
@@ -81,13 +73,21 @@ export function open(registry, timers = realTimers, server = SERVER) {
         forms: shared("forms", () => ({ told: new Map(), settled: new Set() })),
         locations: shared("locations", () => new Map()),
         receivers: shared("receiver", () => ({})),
-        questions: questionState(),
+        // Filled in by `person/question/`, field by field, since a copy before the hub may have made it without them.
+        questions: shared("questions", () => ({})),
         skewLogged: false,
     });
     const found = registry[Symbol.for(HUB_KEY)];
     // The version of the hub of another copy found under `HUB_KEY`, if one is there.
     const skew = found != null && found.version !== HUB_VERSION ? { version: found.version } : undefined;
-    const hub = processWide(skew ? `${HUB_KEY}@${HUB_VERSION}` : HUB_KEY, create, registry);
+    return { hub: processWide(skew ? `${HUB_KEY}@${HUB_VERSION}` : HUB_KEY, create, registry), skew };
+}
+/**
+ * This copy's hub in `registry`, and how its instances join it. Its ticks run `jobs` in order, kept in
+ * this copy's tick, which the hub runs once this copy has joined last, never in the hub itself.
+ */
+export function open(registry, jobs, timers = realTimers, server = SERVER) {
+    const { hub, skew } = find(registry);
     /**
      * Whether this server holds the owner key, taking or renewing it through `ports`. A free, expired
      * or stalled key is written and read back after a random wait: the last of two writers holds it.
@@ -180,8 +180,8 @@ export function open(registry, timers = realTimers, server = SERVER) {
         };
         try {
             if ((await own(owner.later)) && scheduler.timer !== undefined && hub.members.has(owner)) {
-                await deliverDue(owner.later, hub.claimed);
-                await deliverReleased(owner.later, hub.claimed);
+                for (const job of jobs)
+                    await job(owner, hub.claimed);
             }
         }
         catch (error) {
@@ -280,24 +280,13 @@ export function open(registry, timers = realTimers, server = SERVER) {
         hub,
         join,
         track,
-        gate: shared("spawning", () => ({ reserved: new Set(), turn: Promise.resolve() })),
-        inbox: shared("inbox", () => new Map()),
         nudge,
     };
 }
-const opened = open(globalThis);
 /** This copy's hub, in the process. */
-export const hub = opened.hub;
-/** Joins this copy's hub; see `Opened.join`. */
-export const join = opened.join;
-/** Hands this copy's hub work a member started; see `Opened.track`. */
-export const track = opened.track;
-/** The spawns under way in the process; see `Opened.gate`. */
-export const gate = opened.gate;
-/** The types of the items enqueued for spawned sessions; see `Opened.inbox`. */
-export const inbox = opened.inbox;
-/** Has this copy's scheduler deliver what is due now; see `Opened.nudge`. */
-export const nudge = opened.nudge;
+export const hub = find(globalThis).hub;
+/** Opens this copy's hub in the process, with its tick jobs; see `open`. */
+export const openInProcess = (jobs) => open(globalThis, jobs);
 /** The member of this copy's hub set up with `location` that joined last, while it is loaded. */
 export function memberAt(location) {
     let found;
@@ -306,38 +295,5 @@ export function memberAt(location) {
             found = member;
     return found;
 }
-/**
- * The question ports of the member that just joined at `location`, while it is loaded: resolved once,
- * so a later instance at the same location does not take its place while this one is still loaded.
- */
-export function portsAt(location) {
-    const own = memberAt(location);
-    return () => (own && hub.members.has(own) ? own.questions : undefined);
-}
 /** The permission domains of the loaded instances. */
 export const permissions = () => hub.locations.values();
-/**
- * For tests: forgets every remembered id, the spawns under way and the question relay's state, loaded
- * instances and watcher count included. Members, locations and the receiver are left to unloading.
- */
-export function resetHub() {
-    gate.reserved.clear();
-    inbox.clear();
-    hub.claimed.clear();
-    hub.watched.seen.clear();
-    hub.watched.waiting.clear();
-    hub.watched.answered.clear();
-    hub.forms.told.clear();
-    hub.forms.settled.clear();
-    const questions = hub.questions;
-    questions.questions.clear();
-    questions.noticed.clear();
-    questions.shown.clear();
-    questions.passing.clear();
-    questions.answered.clear();
-    questions.loaded.clear();
-    questions.following = 0;
-    questions.followed = false;
-    questions.shutdowns.clear();
-    questions.closingWaiters.clear();
-}

package/dist/{version.js → platform/version.js}

@@ -5,7 +5,7 @@ const README_TABLE = "https://github.com/ivopogace/opencode-courier#supported-op
  * `@opencode/plugin` devDependency version, which the peer repeats. Throws if either is missing.
  */
 export function builtVersions() {
-    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    const pkg = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
     const plugin = pkg.version;
     const opencode = pkg.devDependencies?.["@opencode/plugin"];
     if (typeof plugin !== "string")

package/dist/rpc.d.ts

@@ -0,0 +1,2 @@
+export { treeRpc, type Row, type Stopped, type Summary, type Tree, type TreeRpc, type Wait } from "./tree/rpc.js";
+export { personRpc, type Answered, type Asks, type PersonRpc } from "./person/rpc.js";

package/dist/rpc.js

@@ -0,0 +1,3 @@
+// The package's `rpc` entrypoint: the courier's RPC contracts, for a client that calls them.
+export { treeRpc } from "./tree/rpc.js";
+export { personRpc } from "./person/rpc.js";

package/dist/scheduling/index.d.ts

@@ -0,0 +1,6 @@
+import type { TickJob } from "../platform/hub.js";
+export { cancel, cancelScheduled, deliverDue, isScheduled, schedule, scheduledFor } from "./later.js";
+export type { LaterEntry, LaterInput, LaterPorts } from "./later.js";
+export { addSchedulingTools } from "./tools.js";
+/** The scheduler's tick job: due messages, through the first loaded member, whose `later` is every hub-v2 member's LaterPorts. */
+export declare const dueJob: TickJob;

package/dist/scheduling/index.js

@@ -0,0 +1,5 @@
+import { deliverDue } from "./later.js";
+export { cancel, cancelScheduled, deliverDue, isScheduled, schedule, scheduledFor } from "./later.js";
+export { addSchedulingTools } from "./tools.js";
+/** The scheduler's tick job: due messages, through the first loaded member, whose `later` is every hub-v2 member's LaterPorts. */
+export const dueJob = (owner, claimed) => deliverDue(owner.later, claimed);

package/dist/{later.d.ts → scheduling/later.d.ts}

@@ -1,8 +1,6 @@
 import type { Plugin } from "@opencode/plugin";
-import { type Storage } from "./storage.js";
+import { type Storage } from "../platform/storage.js";
 type Context = Plugin.Context;
-/** How often the hub's scheduler looks for due messages; a delivery can be this late. */
-export declare const TICK_MS = 15000;
 export interface LaterEntry {
     readonly id: string;
     readonly sessionID: string;
@@ -32,6 +30,12 @@ export declare function schedule(ports: LaterPorts, from: string, input: LaterIn
 export declare function cancel(ports: LaterPorts, id: string): Promise<boolean>;
 /** The messages scheduled for a session that have not been delivered yet. */
 export declare function scheduledFor(storage: Pick<Storage, "scan">, sessionID: string): Promise<LaterEntry[]>;
+/** Cancels every message scheduled for a session; the ids of those cancelled. */
+export declare function cancelScheduled(ports: LaterPorts, sessionID: string): Promise<string[]>;
+/** Whether a session waits on a scheduled message of its own. */
+export declare function isScheduled(ports: {
+    readonly storage: Pick<Storage, "scan">;
+}, sessionID: string): Promise<boolean>;
 /**
  * Delivers every due message once: an id is claimed synchronously in the shared `claimed`, re-read,
  * delivered and only then removed; a crash in between delivers it again after a restart, not never.

package/dist/{later.js → scheduling/later.js}

@@ -1,7 +1,5 @@
-import { envelope } from "./notices.js";
-import { scanAll } from "./storage.js";
-/** How often the hub's scheduler looks for due messages; a delivery can be this late. */
-export const TICK_MS = 15_000;
+import { envelope } from "../kernel/protocol.js";
+import { scanAll } from "../platform/storage.js";
 const PREFIX = "later/";
 /** The latest time a Date can hold; a message due after it could never be shown or delivered. */
 const LATEST = 8.64e15;
@@ -64,6 +62,16 @@ function pending(ports) {
 export async function scheduledFor(storage, sessionID) {
     return (await pending({ storage: storage })).filter((entry) => entry.sessionID === sessionID);
 }
+/** Cancels every message scheduled for a session; the ids of those cancelled. */
+export async function cancelScheduled(ports, sessionID) {
+    const scheduled = await scheduledFor(ports.storage, sessionID);
+    const dropped = await Promise.all(scheduled.map(async (later) => ((await cancel(ports, later.id)) ? later.id : undefined)));
+    return dropped.filter((id) => id !== undefined);
+}
+/** Whether a session waits on a scheduled message of its own. */
+export async function isScheduled(ports, sessionID) {
+    return (await scheduledFor(ports.storage, sessionID)).length > 0;
+}
 /**
  * Delivers every due message once: an id is claimed synchronously in the shared `claimed`, re-read,
  * delivered and only then removed; a crash in between delivers it again after a restart, not never.

package/dist/scheduling/text.d.ts

@@ -0,0 +1,6 @@
+/** `own` when the message goes to the session that scheduled it. */
+export declare function laterText(entry: {
+    readonly id: string;
+    readonly sessionID: string;
+}, fireAt: string, own: boolean): string;
+export declare const cancelText: (id: string, cancelled: boolean) => string;

package/dist/scheduling/text.js

@@ -0,0 +1,10 @@
+/** `own` when the message goes to the session that scheduled it. */
+export function laterText(entry, fireAt, own) {
+    const next = own
+        ? "It arrives when due, after your current turn if one is running, so do not wait for it: once nothing " +
+            "else is left to do now, end your turn by replying without calling more tools. If what it checks on " +
+            "reports first, cancel it then with courier_cancel."
+        : "Cancel it with courier_cancel if it is no longer needed.";
+    return `Scheduled ${entry.id} for ${fireAt}, to ${entry.sessionID}. ${next}`;
+}
+export const cancelText = (id, cancelled) => cancelled ? `Cancelled ${id}.` : `Nothing pending under ${id}; it may have been delivered.`;

package/dist/scheduling/tools.d.ts

@@ -0,0 +1,14 @@
+import { Schema } from "effect";
+import { type ToolEditor } from "../kernel/tool.js";
+import { type LaterPorts } from "./later.js";
+export declare const LaterInput: Schema.Struct<{
+    readonly message: Schema.String;
+    readonly delayMinutes: Schema.optional<Schema.Union<readonly [Schema.Number, Schema.String]>>;
+    readonly at: Schema.optional<Schema.String>;
+    readonly sessionID: Schema.optional<Schema.String>;
+}>;
+export declare const CancelInput: Schema.Struct<{
+    readonly id: Schema.String;
+}>;
+/** Adds `courier_later` and `courier_cancel`. */
+export declare function addSchedulingTools(tools: ToolEditor, later: LaterPorts): void;

package/dist/scheduling/tools.js

@@ -0,0 +1,48 @@
+import { Schema } from "effect";
+import { rethrow } from "../kernel/tool.js";
+import { cancel, schedule } from "./later.js";
+import { cancelText, laterText } from "./text.js";
+export const LaterInput = Schema.Struct({
+    message: Schema.String.annotate({ description: "The message to deliver." }),
+    delayMinutes: Schema.optional(
+    // Some models send the number as a string ("3", "3.0") whatever the schema says, and resend it
+    // unchanged after the error, so a string is accepted and schedule reads it as a number.
+    Schema.Union([Schema.Number, Schema.String]).annotate({
+        description: "Deliver this many minutes from now. Give this or at.",
+    })),
+    at: Schema.optional(Schema.String.annotate({ description: "Deliver at this ISO 8601 time. Give this or delayMinutes." })),
+    sessionID: Schema.optional(Schema.String.annotate({ description: "The session to deliver to; defaults to this one." })),
+});
+export const CancelInput = Schema.Struct({
+    id: Schema.String.annotate({ description: "The id courier_later returned." }),
+});
+/** Adds `courier_later` and `courier_cancel`. */
+export function addSchedulingTools(tools, later) {
+    tools.add({
+        name: "courier_later",
+        options: { codemode: false },
+        description: "Schedule a message for a session (this one by default), delivered when due and waking it if idle. " +
+            "Use it as a safety net when you start sessions: schedule one check-in, end your turn by replying without " +
+            "calling more tools, and cancel it with courier_cancel if the child reports first. Survives server restarts; " +
+            "may arrive up to ~15 seconds late.",
+        input: LaterInput,
+        execute: async (input, context) => {
+            const entry = await schedule(later, context.sessionID, input).catch(rethrow("courier_later"));
+            const fireAt = new Date(entry.fireAt).toISOString();
+            return {
+                content: laterText(entry, fireAt, entry.sessionID === context.sessionID),
+                metadata: { id: entry.id, fireAt, sessionID: entry.sessionID },
+            };
+        },
+    });
+    tools.add({
+        name: "courier_cancel",
+        options: { codemode: false },
+        description: "Cancel a message scheduled with courier_later, e.g. because the child it was waiting for reported.",
+        input: CancelInput,
+        execute: async (input) => {
+            const cancelled = await cancel(later, input.id).catch(rethrow("courier_cancel"));
+            return { content: cancelText(input.id, cancelled), metadata: { id: input.id, cancelled } };
+        },
+    });
+}

package/dist/skill.d.ts

@@ -1,4 +1,8 @@
 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. */
+export declare const SKILL_CONTENT: string;
 /** The editor OpenCode hands a skill transform. */
 export type SkillEditor = Parameters<Parameters<Plugin.Context["skill"]["transform"]>[0]>[0];
 /** The courier-orchestrate skill as OpenCode lists it: its id, name and description, and the text the model loads. */

package/dist/skill.js

@@ -1,4 +1,57 @@
-import { SKILL_CONTENT, SKILL_DESCRIPTION, SKILL_ID } from "./notices.js";
+import { 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. */
+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. 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. " +
+        "An implementation task with one tightly coupled core usually still has independent parts: 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: do the core yourself first and commit it, so that the names and texts the other parts depend on are " +
+        "fixed, then, if 2 or more remain, start 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.",
+    "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.",
+    "3. Start them: one courier_spawn per part, 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 " +
+        "sleep. The group's reports, a blocked report, a question, a permission request, a failed turn or a silent end each start " +
+        "a new turn for you.",
+    "5. Read each report by its status and its artifacts (branch, commits, files, checks). done: verify it. partial: what is " +
+        "left and why; have the session finish it with a courier_send, or do it yourself. blocked: make the decision it asks for " +
+        "and send it with courier_send; if only the person can make it, ask them with your question tool and pass the answer on. " +
+        "failed: read the error; message the session to try again, start a replacement, or carry on without it.",
+    "6. Verify first-hand: open the files, run the checks. Never hand the checking to another session: a review session's " +
+        "findings are a report to act on, and running the checks is still yours. Run checks through " +
+        "the project's scripts (bun run <script>, npm run <script>), not ./node_modules/.bin/<tool>, so that one permission " +
+        "rule covers them: your own permission prompts are relayed nowhere, and each one stalls the whole tree.",
+    "7. Integrate: merge each reported branch into your own checkout (git merge courier/<session>), resolve conflicts " +
+        "yourself, run the checks once more, then courier_cleanup the isolated sessions you are done with.",
+    "8. Report upward if a session started you: one courier_send to it, with one status for the whole (done only when every " +
+        "part is verified and integrated; partial, blocked or failed otherwise) and the artifacts. At the top, reply to the person.",
+    "",
+    "When a part goes wrong:",
+    "- A failed turn (failed=\"...\") or a silent end (ended=\"without-report\", quoting the session's last reply): message " +
+        "the session with courier_send to carry on, to report, or to try again; or start a replacement. Until it reports, it " +
+        "counts toward the limits.",
+    "- A refusal from courier_spawn naming maxDepth, maxChildren or maxTotal: do that part yourself, or end your turn and " +
+        "start it once a report has arrived. Do not retry it in a loop.",
+    "- Lost track, after a compaction or a restart: one courier_tree shows every session under you with its depth, its " +
+        "parent and whether it still owes a report; one look, not a loop.",
+    "- A subtree that went wrong or is no longer needed: courier_stop its top session; everything under it is stopped too, " +
+        "and nothing in it reports back. cleanup: true removes their worktrees.",
+].join("\n");
 /** A skill's path is where OpenCode would look for its files; this one has none, so a path of the plugin's own. */
 const SKILL_PATH = `/opencode-courier/${SKILL_ID}.md`;
 /** The courier-orchestrate skill as OpenCode lists it: its id, name and description, and the text the model loads. */

package/dist/{cleanup.d.ts → tree/cleanup.d.ts}

@@ -1,29 +1,4 @@
-import type { Plugin } from "@opencode/plugin";
-import { type CleanupResult } from "./notices.js";
-import { type RosterStorage } from "./roster.js";
-type Context = Plugin.Context;
-/** What would be lost by removing a worktree. */
-export interface WorktreeState {
-    /** Paths with uncommitted changes, untracked files included, as `git status --porcelain` lists them. */
-    readonly changes: readonly string[];
-    /**
-     * Commits reachable from the worktree's HEAD but from no branch, tag or remote-tracking ref, nor
-     * from the commit the worktree was made from, newest first.
-     */
-    readonly commits: readonly string[];
-}
-export interface CleanupPorts {
-    readonly storage: RosterStorage;
-    readonly worktree: Pick<Context["worktree"], "remove">;
-    /** The project of the plugin's location, for roster entries recorded before they carried their project. */
-    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;
-}
+import type { CleanupPorts, CleanupResult, WorktreeState } from "./ports.js";
 export interface CleanupInput {
     readonly sessionID: string;
     readonly force?: boolean;
@@ -56,4 +31,3 @@ export declare function dirtyOf(directory: string): Promise<boolean | undefined>
  * `base`, the commit the worktree was made from, are not its own work and are not listed.
  */
 export declare function inspectWorktree(directory: string, base?: string): Promise<WorktreeState | undefined>;
-export {};