opencode-courier 0.2.3 → 0.3.0

package/dist/hub.js

@@ -1,33 +1,14 @@
 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, in one place. OpenCode sets the plugin up once per location
- * (project or worktree), all in one process, and after an update loads the new copy of the package
- * next to the old one until the old one unloads; so the state every instance shares lives on
- * `globalThis`, outside the module graph, and this is the only module that puts it there.
- *
- * The hub is versioned by `HUB_VERSION`, not by the package's version: copies whose hub has the
- * same shape share one hub, however far apart their releases, and only a change to the hub's shape
- * (the ports a `Member` carries included) or to the meaning of one of its fields bumps it. An
- * optional field that a copy without it gets along without, such as `Member.location` or
- * `Scheduler.running`, is added without a bump while no release has the hub (the latest is 0.2.2).
- *
- * Version skew: a copy that finds a hub of another version under `opencode-courier.hub` logs that
- * once and runs its own hub under `opencode-courier.hub@<version>`. Whatever its version, a hub
- * takes the claim sets and the other shared objects of the copies before the hub from their own
- * keys (`opencode-courier.claimed`, `.watched`, `.forms`, `.questions`, `.receiver`, `.locations`),
- * making each when it is missing, so every copy in the process, with a hub or without, claims an
- * event or a delivery in the same set, and an old and a new copy never both act on it. Those keys'
- * shapes and meanings are therefore fixed: a hub version that needs other ones makes new keys, and
- * keeps claiming in the old ones too while a copy that uses them may still be loaded. `members` is
- * the one thing each version keeps to itself, so a job a hub runs once for its members runs once
- * per hub version, and still claims what it acts on in the shared sets, which keep it from acting
- * twice.
+ * 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.
  */
-export const HUB_VERSION = 1;
+export const HUB_VERSION = 2;
 /** The key of the hub; a copy that finds another version there keeps its own under `${HUB_KEY}@<version>`. */
 export const HUB_KEY = "opencode-courier.hub";
 const realTimers = {
@@ -36,10 +17,8 @@ const realTimers = {
     wait: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
 };
 /**
- * The key in the plugin's storage, shared by every OpenCode server on one data directory, naming
- * the server whose scheduler delivers the `courier_later` messages: `{ server, at }`, its id and
- * when it last wrote the key, in epoch milliseconds. Outside `later/`, which the schedulers scan
- * for messages, those of copies before the key included.
+ * 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 const OWNER_KEY = "scheduler/owner";
 /** How long the owner key holds without being renewed; the owner renews it every tick, four times as often. */
@@ -63,9 +42,8 @@ async function readOwner(ports) {
     return server !== undefined && at !== undefined ? { server, at } : undefined;
 }
 /**
- * How long an unloading instance waits, before it lets go, for the work it leaves behind: what it
- * started itself, a tick or an event's notice still under way through it, and on the last leave the
- * owner key's release.
+ * 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 const LEAVE_MS = 2_000;
 /** Whether a key written at `at` still holds at `now`; one from the future, after the clock went back, holds as long. */
@@ -73,9 +51,8 @@ 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;
 /**
- * Finds or makes this copy's hub in `registry`: the one under `HUB_KEY`, or its own under a
- * versioned key when a hub of another version holds that. Either way, its claim sets and shared
- * objects are the ones under the keys of the copies before the hub, made when missing.
+ * 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);
@@ -112,9 +89,8 @@ export function open(registry, timers = realTimers, server = SERVER) {
     const skew = found != null && found.version !== HUB_VERSION ? { version: found.version } : undefined;
     const hub = processWide(skew ? `${HUB_KEY}@${HUB_VERSION}` : HUB_KEY, create, registry);
     /**
-     * Whether this server holds the owner key, taking or renewing it through `ports`. Its own fresh
-     * key is renewed. A free one, an expired one, or its own after a stall, is written and read back
-     * after a random wait: of two servers taking it at once, the one that wrote last holds it.
+     * 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.
      */
     const own = async (ports) => {
         const held = await readOwner(ports);
@@ -142,10 +118,8 @@ export function open(registry, timers = realTimers, server = SERVER) {
         return other !== hub && (name === HUB_KEY || name.startsWith(`${HUB_KEY}@`)) && Number(other?.members?.size) > 0;
     });
     /**
-     * Removes the owner key if this server holds it, so another server takes over at its next tick:
-     * once the loop has stopped and no tick is under way, whichever copy started it (a tick whose loop
-     * stopped releases it as it ends), and while no hub of another version in the process still runs a
-     * loop under the same id.
+     * Removes the owner key if this server holds it, so another takes over at its next tick: once the
+     * loop has stopped, no tick is under way and no other hub version here runs a loop under this id.
      */
     const release = async (ports) => {
         const scheduler = hub.scheduler;
@@ -154,30 +128,33 @@ export function open(registry, timers = realTimers, server = SERVER) {
             await ports.storage.remove(OWNER_KEY);
     };
     /**
-     * Whether the tick under way, kept on the hub by whichever copy started it, still holds up the
-     * next: within a minute of its start it does, and the key is renewed for it, through the first
-     * member still loaded, since a delivery may run longer than the key holds; past the minute it is
-     * taken to hang, and holds up the next only while its member is still loaded. A tick of a copy that
-     * keeps only `ticking` holds it up while its member is loaded, without renewing the key.
+     * Whether the tick under way still holds the next up: within a minute of its start it does; past
+     * that it is taken to hang, holding up only while its member is loaded. `recent` says which.
      */
-    const underWay = () => {
+    const busy = () => {
         const { running, ticking } = hub.scheduler;
         if (!running)
-            return ticking !== undefined && hub.members.has(ticking);
+            return { busy: ticking !== undefined && hub.members.has(ticking), recent: false };
+        const first = hub.members.values().next().value;
+        if (first && holds(running.since, first.later.now(), OWNER_EXPIRY_MS))
+            return { busy: true, recent: true };
+        return { busy: hub.members.has(running.member), recent: false };
+    };
+    /** `busy`, renewing the key for a recent tick under way, as each tick falling due meanwhile does. */
+    const underWay = () => {
+        const state = busy();
         const first = hub.members.values().next().value;
-        if (first && holds(running.since, first.later.now(), OWNER_EXPIRY_MS)) {
+        if (state.recent && first)
             void renew(first.later).catch((error) => first.log(`courier_later scheduler: ${String(error)}`));
-            return true;
-        }
-        return hub.members.has(running.member);
+        return state.busy;
     };
-    // One tick, through the first member still loaded, by the server holding the owner key. The claim
-    // on each delivery stays, as the second line of defence against a copy before the hub, which runs
-    // its own interval until it unloads, and has no owner key.
+    // One tick, through the first loaded member, by the server holding the owner key. The claim on each
+    // delivery stays, as a second line of defence against a pre-hub copy running its own interval.
     const tick = async () => {
         const scheduler = hub.scheduler;
         if (underWay())
             return;
+        scheduler.nudged = false;
         const owner = hub.members.values().next().value;
         if (!owner)
             return;
@@ -202,8 +179,10 @@ export function open(registry, timers = realTimers, server = SERVER) {
             catch { }
         };
         try {
-            if ((await own(owner.later)) && scheduler.timer !== undefined && hub.members.has(owner))
+            if ((await own(owner.later)) && scheduler.timer !== undefined && hub.members.has(owner)) {
                 await deliverDue(owner.later, hub.claimed);
+                await deliverReleased(owner.later, hub.claimed);
+            }
         }
         catch (error) {
             tell(`courier_later scheduler: ${String(error)}`);
@@ -219,6 +198,18 @@ export function open(registry, timers = realTimers, server = SERVER) {
         if (scheduler.timer === undefined)
             await release(owner.later).catch((error) => tell(`courier_later scheduler: owner key not released: ${String(error)}`));
         end();
+        if (scheduler.nudged && scheduler.timer !== undefined)
+            void scheduler.tick?.();
+    };
+    // Through the hub's tick, the copy loaded last's, like the loop's; this copy's only before one joined. A
+    // tick under way runs once more when it ends, so nothing is started here meanwhile.
+    const nudge = () => {
+        const scheduler = hub.scheduler;
+        if (scheduler.timer === undefined)
+            return;
+        scheduler.nudged = true;
+        if (!busy().busy)
+            void (scheduler.tick ?? tick)();
     };
     // Subscriptions through the earliest members without one, the longest loaded, until there are
     // `WATCHERS`; never through `leaving`.
@@ -262,9 +253,8 @@ export function open(registry, timers = realTimers, server = SERVER) {
             const behind = [...(work.get(member) ?? [])];
             if (scheduler.running?.member === member)
                 behind.push(scheduler.running.done);
-            // The other subscription, already connected, follows the events meanwhile; this one is
-            // replaced before it ends, so the question relay's count of watchers never drops to none.
-            // It ends once the event it is handling, whose notice may be going out, has been handled.
+            // The other subscription, already connected, follows the events meanwhile; this one is replaced
+            // before it ends, after its current event, so the relay's watcher count never drops to none.
             const index = hub.watchers.findIndex((watcher) => watcher.member === member);
             if (index >= 0) {
                 const [leaving] = hub.watchers.splice(index, 1);
@@ -286,7 +276,14 @@ export function open(registry, timers = realTimers, server = SERVER) {
             return Promise.race([Promise.allSettled(behind).then(() => { }), timers.wait(LEAVE_MS)]);
         };
     };
-    return { hub, join, track };
+    return {
+        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. */
@@ -295,6 +292,12 @@ export const hub = opened.hub;
 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;
 /** The member of this copy's hub set up with `location` that joined last, while it is loaded. */
 export function memberAt(location) {
     let found;
@@ -304,9 +307,8 @@ export function memberAt(location) {
     return found;
 }
 /**
- * The question ports of the member that has just joined at `location`, the newest there, for as long
- * as it stays loaded: resolved once, so an instance joining later at the same location, while this
- * one is still loaded, does not take its place.
+ * 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);
@@ -315,11 +317,12 @@ export function portsAt(location) {
 /** The permission domains of the loaded instances. */
 export const permissions = () => hub.locations.values();
 /**
- * For tests: forgets every remembered id and the question relay's state, the relay's loaded
- * instances and its count of watchers included. The hub's members, the locations and the webhook
- * receiver are left alone; leaving and unloading take them out.
+ * 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();

package/dist/index.d.ts

@@ -1,17 +1,13 @@
 import { Plugin } from "@opencode/plugin";
 import { Plugin as EffectPlugin } from "@opencode/plugin/effect";
 /**
- * The courier tools and webhook receiver, as a promise plugin, which joins the hub that runs the
- * scheduler and the event watcher. Its member of the hub carries the instance's location, by which
- * the question relay, the Effect half of the same instance, finds its ports.
+ * The courier tools and webhook receiver, as a promise plugin joining the hub that runs the scheduler
+ * and the watcher; its member carries the location by which the question relay finds its ports.
  */
 export declare const courier: () => Plugin.Plugin;
 /**
- * The plugin OpenCode loads. It is an Effect plugin, because the question relay wraps OpenCode's own
- * question tool, whose execute the promise API hands out only as a promise that cannot be
- * interrupted, so a child's question could not be withdrawn once its parent answered. Everything
- * else is the promise plugin above, run through the plugin package's own adapter, as OpenCode runs
- * a promise plugin.
+ * The plugin OpenCode loads: an Effect plugin, since the question relay wraps OpenCode's question tool
+ * and only the Effect API makes its call interruptible; the rest is the promise plugin, adapted.
  */
 declare const _default: EffectPlugin.Plugin<import("effect/Scope").Scope>;
 export default _default;

package/dist/index.js

@@ -3,21 +3,20 @@ import { Plugin as EffectPlugin } from "@opencode/plugin/effect";
 import { fromPromise } from "@opencode/plugin/promise/adapter";
 import { Effect } from "effect";
 import { randomUUID } from "node:crypto";
-import { headOf, inspectWorktree } from "./cleanup.js";
-import { hub, join, permissions, portsAt, track } from "./hub.js";
+import { dirtyOf, headOf, inspectWorktree } from "./cleanup.js";
+import { gate, hub, inbox, join, nudge, permissions, portsAt, track } from "./hub.js";
+import { readLimits, shapeContext } from "./limits.js";
 import { pendingOf } from "./relay.js";
 import { joinRelay, noticeCutOff, pendingQuestions, relayQuestions } from "./question/index.js";
 import { pruneExpired } from "./roster.js";
+import { addSkill } from "./skill.js";
 import { addTools } from "./tools.js";
 import { watchFromHub } from "./watch.js";
 import { builtVersions, versionNotice } from "./version.js";
 import { listen, readConfig } from "./webhook.js";
 /**
- * The webhook receiver, one per process like the claim set: every instance configured with a
- * `webhook` option joins `instances`, the first one starts the server, and the last one to unload
- * stops it. Requests are served with any live instance's ports; sessions and storage are shared.
- * A receiver that could not listen is dropped, so the next instance to load tries again, and a new
- * one waits for the previous one to finish closing, as on a plugin reload.
+ * The webhook receiver, one per process: instances with a `webhook` option join `instances`, the first
+ * starts the server and the last to unload stops it; one that could not listen is dropped for a retry.
  */
 const receivers = hub.receivers;
 const sameSettings = (a, b) => a.port === b.port && a.host === b.host && a.secret === b.secret && a.maxBytes === b.maxBytes;
@@ -64,16 +63,13 @@ function joinReceiver(config, ports) {
             receivers.closing = undefined;
     };
 }
-// One set of handled events for every instance in the process, since the hub's two subscriptions,
-// and a copy of another hub version or one from before the hub, are sent the same events, and of
-// the permission requests sessions were told about. The scheduler's claim set is the hub's
-// own business: the hub runs the scheduler once for its members.
+// One set of handled events and of told permission requests for every instance in the process, since
+// several subscriptions and copies see the same events. The scheduler's claim set is the hub's own.
 const { watched } = hub;
-const watchState = { ...watched, forms: hub.forms };
+const watchState = { ...watched, forms: hub.forms, inbox };
 /**
- * The courier tools and webhook receiver, as a promise plugin, which joins the hub that runs the
- * scheduler and the event watcher. Its member of the hub carries the instance's location, by which
- * the question relay, the Effect half of the same instance, finds its ports.
+ * The courier tools and webhook receiver, as a promise plugin joining the hub that runs the scheduler
+ * and the watcher; its member carries the location by which the question relay finds its ports.
  */
 export const courier = () => Plugin.define({
     id: "courier",
@@ -98,7 +94,16 @@ export const courier = () => Plugin.define({
             newID: () => `question_${randomUUID()}`,
             log,
         };
+        const { limits, problems } = readLimits(ctx.options);
+        for (const problem of problems)
+            log(`courier: ${problem}`);
+        const roles = new Map();
         const ports = {
+            limits,
+            gate,
+            roles,
+            nudge,
+            log,
             session: ctx.session,
             agent: ctx.agent,
             worktree: ctx.worktree,
@@ -107,6 +112,7 @@ export const courier = () => Plugin.define({
             projectID: ctx.location.project.id,
             now: Date.now,
             head: headOf,
+            dirty: dirtyOf,
             pending: async (sessionID) => {
                 const [requests, questions] = await Promise.all([
                     pendingOf(permissions(), sessionID),
@@ -135,6 +141,7 @@ export const courier = () => Plugin.define({
         const toolPorts = {
             courier: ports,
             cleanup: cleanupPorts,
+            stop: { courier: ports, later, cleanup: cleanupPorts },
             later,
             answer: answerPorts,
             questions: questionPorts,
@@ -143,6 +150,8 @@ export const courier = () => Plugin.define({
             receiving: async () => (await receivers.current?.server) !== undefined,
         };
         await ctx.tool.transform((tools) => addTools(tools, toolPorts));
+        await ctx.skill.transform(addSkill);
+        await ctx.session.hook("context", (event) => shapeContext({ storage: ctx.storage, limits, roles, log }, event));
         const pruned = pruneExpired(ctx.storage, Date.now()).catch((error) => log(`courier roster prune: ${String(error)}`));
         const leaveRelay = joinRelay(questionPorts);
         const noticed = noticeCutOff(questionPorts).catch((error) => questionPorts.log(`courier question: stored questions: ${String(error)}`));
@@ -153,6 +162,7 @@ export const courier = () => Plugin.define({
             permissions,
             now: questionPorts.now,
             log: later.log,
+            nudge,
         };
         // The hub's subscriptions to OpenCode's events, one and a standby, start with this copy's watcher.
         watchFromHub(hub, watchState);
@@ -181,11 +191,8 @@ export const courier = () => Plugin.define({
     },
 });
 /**
- * The plugin OpenCode loads. It is an Effect plugin, because the question relay wraps OpenCode's own
- * question tool, whose execute the promise API hands out only as a promise that cannot be
- * interrupted, so a child's question could not be withdrawn once its parent answered. Everything
- * else is the promise plugin above, run through the plugin package's own adapter, as OpenCode runs
- * a promise plugin.
+ * The plugin OpenCode loads: an Effect plugin, since the question relay wraps OpenCode's question tool
+ * and only the Effect API makes its call interruptible; the rest is the promise plugin, adapted.
  */
 export default EffectPlugin.define({
     id: "courier",

package/dist/json.d.ts

@@ -2,3 +2,7 @@
 export declare const str: (value: unknown) => string | undefined;
 export declare const num: (value: unknown) => number | undefined;
 export declare const obj: (value: unknown) => Record<string, any>;
+/** Epoch milliseconds from a session time, a `DateTime` in OpenCode's API and a number in tests; NaN for none. */
+export declare function millis(value: unknown): number;
+/** Whether an error of OpenCode's says that what it names, such as a session, does not exist (`Session.NotFoundError`). */
+export declare const isNotFound: (error: unknown) => boolean;

package/dist/json.js

@@ -2,3 +2,14 @@
 export const str = (value) => (typeof value === "string" ? value : undefined);
 export const num = (value) => (typeof value === "number" && Number.isInteger(value) ? value : undefined);
 export const obj = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+/** Epoch milliseconds from a session time, a `DateTime` in OpenCode's API and a number in tests; NaN for none. */
+export function millis(value) {
+    if (typeof value === "number")
+        return value;
+    if (typeof value === "string")
+        return Date.parse(value);
+    const epoch = obj(value).epochMilliseconds;
+    return typeof epoch === "number" ? epoch : Number.NaN;
+}
+/** Whether an error of OpenCode's says that what it names, such as a session, does not exist (`Session.NotFoundError`). */
+export const isNotFound = (error) => str(obj(error)._tag)?.includes("NotFound") ?? false;

package/dist/later.d.ts

@@ -13,7 +13,8 @@ export interface LaterEntry {
 }
 export interface LaterPorts {
     readonly storage: Storage;
-    readonly session: Pick<Context["session"], "synthetic">;
+    /** `get` for the release of a join group, which waits for its parent's turn to end. */
+    readonly session: Pick<Context["session"], "synthetic" | "get">;
     readonly now: () => number;
     readonly newID: () => string;
     readonly log: (message: string) => void;
@@ -29,12 +30,11 @@ export interface LaterInput {
 export declare function schedule(ports: LaterPorts, from: string, input: LaterInput): Promise<LaterEntry>;
 /** Drops a pending message; false when there was none, e.g. it was already delivered. */
 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[]>;
 /**
- * Delivers every due message once. OpenCode sets the plugin up once per project location, all in
- * one process and over one storage, so the instances share `claimed`: an id is claimed
- * synchronously, re-read after the claim (another instance may have just delivered it), delivered,
- * and only then removed. A crash between delivery and removal delivers it again after a restart,
- * which a check-in survives better than being lost.
+ * 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.
  */
 export declare function deliverDue(ports: LaterPorts, claimed: Set<string>): Promise<void>;
 export {};

package/dist/later.js

@@ -60,12 +60,13 @@ export async function cancel(ports, id) {
 function pending(ports) {
     return scanAll(ports.storage, PREFIX);
 }
+/** The messages scheduled for a session that have not been delivered yet. */
+export async function scheduledFor(storage, sessionID) {
+    return (await pending({ storage: storage })).filter((entry) => entry.sessionID === sessionID);
+}
 /**
- * Delivers every due message once. OpenCode sets the plugin up once per project location, all in
- * one process and over one storage, so the instances share `claimed`: an id is claimed
- * synchronously, re-read after the claim (another instance may have just delivered it), delivered,
- * and only then removed. A crash between delivery and removal delivers it again after a restart,
- * which a check-in survives better than being lost.
+ * 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.
  */
 export async function deliverDue(ports, claimed) {
     const now = ports.now();

package/dist/limits.d.ts

@@ -0,0 +1,65 @@
+import type { Plugin } from "@opencode/plugin";
+import { type Limits } from "./notices.js";
+import { type RosterStorage } from "./roster.js";
+export type { Limits } from "./notices.js";
+type Context = Plugin.Context;
+export declare const DEFAULT_LIMITS: Limits;
+/** The limits in the plugin's options; one that is not a positive integer keeps its default and is named in `problems`. */
+export declare function readLimits(options: unknown): {
+    limits: Limits;
+    problems: string[];
+};
+/** A spawn past its limit check: its parent, the top of its tree, and its child once created. */
+export interface Reservation {
+    readonly parentID: string;
+    readonly top: string;
+    sessionID?: string;
+}
+/**
+ * The spawns under way in the process, kept by the hub under a fixed key, so spawns in other
+ * locations and copies count them; `turn` runs the limit checks one at a time.
+ */
+export interface SpawnGate {
+    readonly reserved: Set<Reservation>;
+    turn: Promise<unknown>;
+}
+export interface LimitPorts {
+    readonly storage: RosterStorage;
+    readonly session: Pick<Context["session"], "get">;
+    readonly limits: Limits;
+    readonly gate: SpawnGate;
+}
+/** A session's times, as `session.get` gives them. */
+type Times = Awaited<ReturnType<Context["session"]["get"]>>["time"];
+/** Whether a session with these times runs: it has never finished a turn, or something reached it after the last one ended. */
+export declare const busy: (time: Pick<Times, "updated" | "idle">) => boolean;
+/**
+ * Checks the limits for a spawn from `parentID`, then holds its place in `gate` until `release`;
+ * throws a refusal naming the limit. Checks run one at a time, so spawns made together count each other.
+ */
+export declare function admit(ports: LimitPorts, parentID: string): Promise<{
+    depth: number;
+    reservation: Reservation;
+    release: () => void;
+}>;
+export interface ContextPorts {
+    readonly storage: RosterStorage;
+    readonly limits: Limits;
+    /** Each session's depth once looked up: null for one nobody spawned that has started none, until it starts one. */
+    readonly roles: Map<string, number | null>;
+    readonly log: (message: string) => void;
+}
+/** The part of a session context this hook changes. */
+export interface Shaped {
+    readonly sessionID: string;
+    tools: Record<string, unknown>;
+    system: Array<{
+        type: "text";
+        text: string;
+    }>;
+}
+/**
+ * The `context` hook: names a session's role in its tree in a system part, and hides courier_spawn
+ * from one at `maxDepth`. A session nobody spawned that has started none is pointed to the skill, if it could spawn.
+ */
+export declare function shapeContext(ports: ContextPorts, event: Shaped): Promise<void>;

package/dist/limits.js

@@ -0,0 +1,109 @@
+import { setBounded } from "./bounded.js";
+import { isNotFound, millis, obj } from "./json.js";
+import { childrenRefusal, depthRefusal, ROLE_PREFIX, rolePart, totalRefusal } from "./notices.js";
+import { reportOf } from "./report.js";
+import { allEntries, bySession, children, indexedLineage, lineageBy } from "./roster.js";
+export const DEFAULT_LIMITS = { maxDepth: 3, maxChildren: 5, maxTotal: 20 };
+/** The limits in the plugin's options; one that is not a positive integer keeps its default and is named in `problems`. */
+export function readLimits(options) {
+    const given = obj(options);
+    const problems = [];
+    const read = (name) => {
+        const value = given[name];
+        if (value === undefined)
+            return DEFAULT_LIMITS[name];
+        if (typeof value === "number" && Number.isInteger(value) && value > 0)
+            return value;
+        problems.push(`${name} must be a positive integer, not ${JSON.stringify(value)}; using ${DEFAULT_LIMITS[name]}`);
+        return DEFAULT_LIMITS[name];
+    };
+    const limits = { maxDepth: read("maxDepth"), maxChildren: read("maxChildren"), maxTotal: read("maxTotal") };
+    return { limits, problems };
+}
+/** Whether a session with these times runs: it has never finished a turn, or something reached it after the last one ended. */
+export const busy = (time) => time.idle === undefined || millis(time.updated) > millis(time.idle);
+/**
+ * Whether a spawned session counts against the limits: it runs, unless its turn failed or was
+ * interrupted since its last prompt, or it owes its parent a report. One OpenCode no longer knows does not.
+ */
+async function live(ports, sessionID) {
+    const [time, report] = await Promise.all([
+        ports.session.get({ sessionID }).then((info) => info.time, (error) => (isNotFound(error) ? null : undefined)),
+        reportOf(ports.storage, sessionID).catch(() => undefined),
+    ]);
+    if (time === null)
+        return false;
+    // One whose first prompt failed never ran, and has no idle time to tell so.
+    const runs = time !== undefined && busy(time) && !report?.ended;
+    return runs || (report?.owes ?? false);
+}
+/**
+ * Checks the limits for a spawn from `parentID`, then holds its place in `gate` until `release`;
+ * throws a refusal naming the limit. Checks run one at a time, so spawns made together count each other.
+ */
+export async function admit(ports, parentID) {
+    const gate = ports.gate;
+    const checked = gate.turn.then(() => check(ports, parentID));
+    gate.turn = checked.catch(() => undefined);
+    const { depth, reservation } = await checked;
+    const release = () => {
+        gate.reserved.delete(reservation);
+    };
+    return { depth, reservation, release };
+}
+async function check(ports, parentID) {
+    const { maxDepth, maxChildren, maxTotal } = ports.limits;
+    const entries = await allEntries(ports.storage);
+    const parents = bySession(entries);
+    const chain = lineageBy(parents, parentID);
+    if (chain.length >= maxDepth)
+        throw new Error(depthRefusal(chain.length, maxDepth));
+    const top = chain.at(-1)?.parentID ?? parentID;
+    const chains = new Map(entries.map((entry) => [entry.sessionID, lineageBy(parents, entry.sessionID)]));
+    const tree = entries.filter((entry) => chains.get(entry.sessionID).at(-1)?.parentID === top);
+    const runs = await Promise.all(tree.map((entry) => live(ports, entry.sessionID)));
+    // A session waiting on a live descendant is live too: the brief tells it to end its turn meanwhile.
+    const active = new Set(tree.filter((_, i) => runs[i]).flatMap((entry) => [entry.sessionID, ...chains.get(entry.sessionID).map((above) => above.parentID)]));
+    const counted = tree.filter((entry) => active.has(entry.sessionID));
+    // A spawn whose child is on the roster already is counted there, if it is live, not by its reservation.
+    const recorded = new Set(tree.map((entry) => entry.sessionID));
+    const pending = [...ports.gate.reserved].filter((held) => held.top === top && !(held.sessionID && recorded.has(held.sessionID)));
+    const mine = counted.filter((entry) => entry.parentID === parentID).length + pending.filter((held) => held.parentID === parentID).length;
+    if (mine >= maxChildren)
+        throw new Error(childrenRefusal(mine, maxChildren));
+    if (counted.length + pending.length >= maxTotal)
+        throw new Error(totalRefusal(counted.length + pending.length, maxTotal));
+    const reservation = { parentID, top };
+    ports.gate.reserved.add(reservation);
+    return { depth: chain.length + 1, reservation };
+}
+/** How many sessions' depths an instance remembers. */
+const ROLES_MAX = 1000;
+/**
+ * The `context` hook: names a session's role in its tree in a system part, and hides courier_spawn
+ * from one at `maxDepth`. A session nobody spawned that has started none is pointed to the skill, if it could spawn.
+ */
+export async function shapeContext(ports, event) {
+    try {
+        const depth = await depthOf(ports, event.sessionID);
+        if (depth === null && !event.tools.courier_spawn)
+            return;
+        if (depth !== null && depth >= ports.limits.maxDepth)
+            delete event.tools.courier_spawn;
+        if (!event.system.some((part) => part.text.startsWith(ROLE_PREFIX)))
+            event.system.push({ type: "text", text: rolePart(depth, ports.limits) });
+    }
+    catch (error) {
+        ports.log(`courier: cannot tell the role of session ${event.sessionID}: ${String(error)}`);
+    }
+}
+async function depthOf(ports, sessionID) {
+    const known = ports.roles.get(sessionID);
+    if (known !== undefined)
+        return known;
+    // The reverse index alone: a scan here would run for every session's first request, courier or not.
+    const chain = await indexedLineage(ports.storage, sessionID);
+    const depth = chain.length || ((await children(ports.storage, sessionID)).length ? 0 : null);
+    setBounded(ports.roles, sessionID, depth, ROLES_MAX);
+    return depth;
+}