opencode-courier 0.2.2 → 0.3.0

package/dist/index.js

@@ -1,79 +1,24 @@
 import { Plugin } from "@opencode/plugin";
 import { Plugin as EffectPlugin } from "@opencode/plugin/effect";
 import { fromPromise } from "@opencode/plugin/promise/adapter";
-import { Effect, Schema } from "effect";
+import { Effect } from "effect";
 import { randomUUID } from "node:crypto";
-import { describeFailure, END_TURN, listChildren, send, spawn, status } from "./courier.js";
-import { cleanup, headOf, inspectWorktree } from "./cleanup.js";
-import { cancel, deliverDue, schedule, TICK_MS } from "./later.js";
-import { answer, pendingOf } from "./relay.js";
-import { answerQuestion, isQuestion, joinRelay, noticeCutOff, pendingQuestions, relayQuestions } from "./question.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 { processWide } from "./storage.js";
-import { watchChildren } from "./watch.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, subscribe, unsubscribe } from "./webhook.js";
-const SpawnInput = Schema.Struct({
-    task: Schema.String.annotate({ description: "What the new session should do. It is told who started it and how to report back." }),
-    title: Schema.optional(Schema.String.annotate({ description: "Session title; defaults to the task's first line." })),
-    agent: Schema.optional(Schema.String.annotate({ description: "Agent to run the session with; defaults to the default agent." })),
-    isolate: Schema.optional(Schema.Boolean.annotate({ description: "Run the session in its own git worktree so parallel sessions don't share files." })),
-});
-const SendInput = Schema.Struct({
-    sessionID: Schema.String.annotate({ description: "The session to deliver to." }),
-    message: Schema.String.annotate({ description: "The message text." }),
-    queue: Schema.optional(Schema.Boolean.annotate({ description: "Wait until the target's current turn ends instead of steering it now." })),
-});
-const StatusInput = Schema.Struct({
-    sessionID: Schema.String.annotate({ description: "The session to look at." }),
-});
-const ChildrenInput = Schema.Struct({
-    sessionID: Schema.optional(Schema.String.annotate({ description: "The session whose children to list; defaults to this one." })),
-});
-const CleanupInput = Schema.Struct({
-    sessionID: Schema.String.annotate({ description: "The isolated child whose worktree to remove." }),
-    force: Schema.optional(Schema.Boolean.annotate({
-        description: "Remove it even with uncommitted changes or commits on no branch; that work is lost.",
-    })),
-});
-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." })),
-});
-const AnswerInput = Schema.Struct({
-    sessionID: Schema.String.annotate({ description: "The session you started that is waiting, as its notice names it." }),
-    requestID: Schema.String.annotate({ description: "The request id from the notice." }),
-    reply: Schema.optional(Schema.Literals(["once", "always", "reject"]).annotate({
-        description: "For a permission request: the choice the person made, once, always (only when the notice offers it) or reject.",
-    })),
-    message: Schema.optional(Schema.String.annotate({ description: "For a permission request, with reject: the person's reason, passed on with the refusal." })),
-    answers: Schema.optional(Schema.Array(Schema.Union([Schema.String, Schema.Array(Schema.String)])).annotate({
-        description: "For a question: one entry per question, in order, each the label the person chose or the text they gave, " +
-            "or a list of labels where the question allows several.",
-    })),
-});
-const CancelInput = Schema.Struct({
-    id: Schema.String.annotate({ description: "The id courier_later returned." }),
-});
-const SubscribeInput = Schema.Struct({
-    topic: Schema.String.annotate({
-        description: "owner/repo for every event of a GitHub repository, owner/repo#<number> for one pull request or issue " +
-            "(reviews, comments, completed CI runs), or a plain name for deliveries posted to /hook/<name>.",
-    }),
-    sessionID: Schema.optional(Schema.String.annotate({ description: "The session to subscribe; defaults to this one." })),
-});
-const UnsubscribeInput = Schema.Struct({
-    topic: Schema.optional(Schema.String.annotate({ description: "The topic to drop; all of this session's when omitted." })),
-    sessionID: Schema.optional(Schema.String.annotate({ description: "The session to unsubscribe; defaults to this one." })),
-});
-const receivers = processWide("opencode-courier.receiver", () => ({}));
+import { listen, readConfig } from "./webhook.js";
+/**
+ * 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;
 function startReceiver(config, log) {
     const instances = new Set();
@@ -118,46 +63,15 @@ function joinReceiver(config, ports) {
             receivers.closing = undefined;
     };
 }
-// One claim set for every instance in the process: OpenCode sets the plugin up once per project
-// location, and those instances share one storage.
-const claimed = processWide("opencode-courier.claimed", () => new Set());
-// Likewise one set of handled events, since every instance may be sent the same event, and the
-// permission requests sessions were told about and have not answered.
-const watched = processWide("opencode-courier.watched", () => ({
-    seen: new Set(),
-    waiting: new Set(),
-    answered: new Set(),
-}));
-// The permission domain of every loaded instance, under a key of its own. OpenCode keeps a request
-// where its session runs, so a request of an isolated child is answered through the instance loaded
-// in its worktree.
-const locations = processWide("opencode-courier.locations", () => new Map());
-const permissions = () => locations.values();
-const rethrow = (tool) => (error) => {
-    throw describeFailure(tool, error);
-};
-function describeCleanup(result) {
-    if (result.outcome === "removed")
-        return `Removed the worktree ${result.directory} of ${result.sessionID}.`;
-    if (result.outcome === "gone")
-        return `The worktree ${result.directory} of ${result.sessionID} was already gone; dropped it from courier_children.`;
-    return `Kept the worktree ${result.directory} of ${result.sessionID}: it has ${result.reason}. Commit or branch what you want to keep, or call courier_cleanup again with force: true to discard it.`;
-}
-function describeAnswer(result) {
-    const kind = isQuestion(result.requestID) ? "question" : "request";
-    if (!result.answered)
-        return (`${result.sessionID} no longer waits on ${kind} ${result.requestID}: it was answered some other way, or the ` +
-            "session stopped waiting. Nothing was passed on; tell the person their answer is not needed.");
-    if ("reply" in result)
-        return `Passed on ${result.reply} for request ${result.requestID} of ${result.sessionID}, which carries on and reports back with courier_send. ${END_TURN}`;
-    const how = "by" in result && result.by === "message" ? " as a message, since its question had been cut off" : "";
-    return `Passed the answers to question ${result.requestID} on to ${result.sessionID}${how}; it carries on and reports back with courier_send. ${END_TURN}`;
-}
+// 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, inbox };
 /**
- * The courier tools, scheduler, webhook receiver and event watcher, as a promise plugin. `relay`
- * receives this instance's ports for the question relay while it is loaded.
+ * 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 = (relay = {}) => Plugin.define({
+export const courier = () => Plugin.define({
     id: "courier",
     setup: async (ctx) => {
         const log = (message) => console.error(message);
@@ -176,10 +90,20 @@ export const courier = (relay = {}) => Plugin.define({
             session: ctx.session,
             directory: ctx.location.directory,
             now: Date.now,
+            timing: { closingGraceMs: 30_000, passingWaitMs: 30_000, relayWaitMs: 30_000, dismissalGraceMs: 2_000 },
             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,
@@ -188,6 +112,7 @@ export const courier = (relay = {}) => 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),
@@ -198,27 +123,6 @@ export const courier = (relay = {}) => Plugin.define({
         };
         const cleanupPorts = { ...ports, inspect: inspectWorktree };
         const answerPorts = { storage: ctx.storage, permissions };
-        // One tool answers both: a question's id is the plugin's own, a permission request's OpenCode's.
-        const answerRequest = async (callerID, input) => {
-            const { sessionID, requestID } = input;
-            if (isQuestion(requestID)) {
-                if (input.reply !== undefined || input.message !== undefined)
-                    throw new Error(`${requestID} is a question: pass the person's answers in answers, not reply or message.`);
-                if (input.answers === undefined)
-                    throw new Error(`${requestID} is a question: answers is required, one entry per question.`);
-                return answerQuestion(questionPorts, callerID, { sessionID, requestID, answers: input.answers });
-            }
-            if (input.answers !== undefined)
-                throw new Error(`${requestID} is a permission request: pass the person's choice in reply (once, always or reject), not answers.`);
-            if (input.reply === undefined)
-                throw new Error(`${requestID} is a permission request: reply is required, once, always or reject.`);
-            return answer(answerPorts, watched.waiting, callerID, {
-                sessionID,
-                requestID,
-                reply: input.reply,
-                ...(input.message !== undefined ? { message: input.message } : {}),
-            });
-        };
         const later = {
             storage: ctx.storage,
             session: ctx.session,
@@ -234,203 +138,68 @@ export const courier = (relay = {}) => Plugin.define({
         catch (error) {
             later.log(`courier webhook: not started: ${error instanceof Error ? error.message : String(error)}`);
         }
-        await ctx.tool.transform((tools) => {
-            tools.add({
-                name: "courier_spawn",
-                options: { codemode: false },
-                description: "Start a new OpenCode session on a task and return immediately. It runs on your model. The session reports " +
-                    "back with courier_send, which wakes this session, and you are told if its turn fails instead, it waits for a " +
-                    "permission or it asks a question. DO NOT poll it or call courier_status in a loop: once you have started the sessions " +
-                    "you need, end your turn by replying without calling more tools; each report starts a new turn in which you " +
-                    "carry on. For long tasks, also courier_later a check-in for yourself in case it never reports, and " +
-                    "courier_cancel it when it does.",
-                input: SpawnInput,
-                execute: async (input, context) => {
-                    const child = await spawn(ports, context.sessionID, input).catch(rethrow("courier_spawn"));
-                    const warning = child.rosterError ? ` It is not on your courier_children list: ${child.rosterError}` : "";
-                    return {
-                        content: `Started session ${child.sessionID} in ${child.directory}. It will report back with courier_send, which ` +
-                            "starts a new turn for you. Once you have started every session you need, end your turn: reply without " +
-                            `calling more tools. That does not drop the task; you carry on with it when the reports arrive.${warning}`,
-                        metadata: child,
-                    };
-                },
-            });
-            tools.add({
-                name: "courier_send",
-                options: { codemode: false },
-                description: "Deliver a message to another OpenCode session. If that session is idle, OpenCode starts a new turn for it. " +
-                    "Use it to report back to the session that started you, or to steer a session you started.",
-                input: SendInput,
-                execute: async (input, context) => {
-                    const delivered = await send(ports, context.sessionID, input).catch(rethrow("courier_send"));
-                    return { content: `Delivered to ${input.sessionID}.`, metadata: delivered };
-                },
-            });
-            tools.add({
-                name: "courier_status",
-                options: { codemode: false },
-                description: "Look once at a session's state and its last reply, e.g. on a scheduled check-in. Not for waiting: " +
-                    "sessions you started report back on their own.",
-                input: StatusInput,
-                execute: async (input) => {
-                    const result = await status(ports, input).catch(rethrow("courier_status"));
-                    return { content: JSON.stringify(result, null, 2), metadata: result };
-                },
-            });
-            tools.add({
-                name: "courier_children",
-                options: { codemode: false },
-                description: "List the sessions this one started with courier_spawn, with each one's state and last reply, e.g. after a " +
-                    "compaction or restart. Like courier_status, for a one-off look, not for waiting.",
-                input: ChildrenInput,
-                execute: async (input, context) => {
-                    const listed = await listChildren(ports, input.sessionID || context.sessionID).catch(rethrow("courier_children"));
-                    return {
-                        content: listed.length ? JSON.stringify(listed, null, 2) : "No sessions started with courier_spawn.",
-                        metadata: { children: listed },
-                    };
-                },
-            });
-            tools.add({
-                name: "courier_cleanup",
-                options: { codemode: false },
-                description: "Remove the git worktree of a session you started with isolate: true, once you have what you need from it, " +
-                    "and drop it from courier_children. A worktree with uncommitted changes or commits on no branch is kept and " +
-                    "the result lists them; commit or branch what you want, or pass force: true to discard it.",
-                input: CleanupInput,
-                execute: async (input, context) => {
-                    const result = await cleanup(cleanupPorts, context.sessionID, input).catch(rethrow("courier_cleanup"));
-                    return { content: describeCleanup(result), metadata: result };
-                },
-            });
-            tools.add({
-                name: "courier_answer",
-                options: { codemode: false },
-                description: "Pass on the answer to a permission request or a question that a session you started with courier_spawn (or " +
-                    "one started from it) waits on, after a notice from it named the request. The answer is the person's, not yours: " +
-                    "first ask the person you are working with, offering the choices the notice lists, then call this with what " +
-                    "they chose: reply for a permission request, answers for a question. Never choose for them. The session " +
-                    "carries on once it has the answer.",
-                input: AnswerInput,
-                execute: async (input, context) => {
-                    const result = await answerRequest(context.sessionID, input).catch(rethrow("courier_answer"));
-                    return { content: describeAnswer(result), metadata: result };
-                },
-            });
-            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();
-                    const next = entry.sessionID === context.sessionID
-                        ? "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 {
-                        content: `Scheduled ${entry.id} for ${fireAt}, to ${entry.sessionID}. ${next}`,
-                        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: cancelled ? `Cancelled ${input.id}.` : `Nothing pending under ${input.id}; it may have been delivered.`,
-                        metadata: { id: input.id, cancelled },
-                    };
-                },
-            });
-            tools.add({
-                name: "courier_subscribe",
-                options: { codemode: false },
-                description: "Wake a session (this one by default) when a webhook arrives for a topic: a GitHub repository, one of its " +
-                    "pull requests or issues (reviews, comments, completed CI runs), or a named generic hook. Each matching " +
-                    "delivery arrives as a message, queued behind any running turn. End your turn and wait; do not poll.",
-                input: SubscribeInput,
-                execute: async (input, context) => {
-                    const sessionID = input.sessionID ?? context.sessionID;
-                    const subscription = await subscribe(hooks, sessionID, input.topic).catch(rethrow("courier_subscribe"));
-                    const receiving = (await receivers.current?.server) !== undefined;
-                    const note = receiving
-                        ? ""
-                        : " Note: no webhook receiver runs in this OpenCode server (see the plugin's webhook option), so nothing will arrive yet.";
-                    return {
-                        content: `Subscribed ${sessionID} to ${subscription.topic}.${note}`,
-                        metadata: { sessionID, topic: subscription.topic, receiver: receiving },
-                    };
-                },
-            });
-            tools.add({
-                name: "courier_unsubscribe",
-                options: { codemode: false },
-                description: "Stop webhook deliveries for a topic, or all of a session's topics, e.g. once its pull request is merged.",
-                input: UnsubscribeInput,
-                execute: async (input, context) => {
-                    const sessionID = input.sessionID ?? context.sessionID;
-                    const dropped = await unsubscribe(hooks, sessionID, input.topic).catch(rethrow("courier_unsubscribe"));
-                    return {
-                        content: dropped.length ? `Unsubscribed ${sessionID} from ${dropped.join(", ")}.` : `${sessionID} had no matching subscription.`,
-                        metadata: { sessionID, dropped },
-                    };
-                },
-            });
-        });
-        void pruneExpired(ctx.storage, Date.now()).catch((error) => log(`courier roster prune: ${String(error)}`));
-        relay.ports = questionPorts;
+        const toolPorts = {
+            courier: ports,
+            cleanup: cleanupPorts,
+            stop: { courier: ports, later, cleanup: cleanupPorts },
+            later,
+            answer: answerPorts,
+            questions: questionPorts,
+            hooks,
+            waiting: watched.waiting,
+            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);
-        void noticeCutOff(questionPorts).catch((error) => questionPorts.log(`courier question: stored questions: ${String(error)}`));
-        let ticking = false;
-        const tick = async () => {
-            if (ticking)
-                return;
-            ticking = true;
-            await deliverDue(later, claimed)
-                .catch((error) => later.log(`courier_later scheduler: ${String(error)}`))
-                .finally(() => (ticking = false));
+        const noticed = noticeCutOff(questionPorts).catch((error) => questionPorts.log(`courier question: stored questions: ${String(error)}`));
+        const watchPorts = {
+            storage: ctx.storage,
+            session: ctx.session,
+            event: ctx.event,
+            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);
+        const member = {
+            directory: ctx.location.directory,
+            location: ctx.location,
+            permission: ctx.permission,
+            later,
+            watch: watchPorts,
+            questions: questionPorts,
+            log,
         };
-        void tick();
-        const timer = setInterval(tick, TICK_MS);
-        const watching = new AbortController();
-        const location = {};
-        locations.set(location, ctx.permission);
-        void watchChildren({ storage: ctx.storage, session: ctx.session, event: ctx.event, permission: ctx.permission, log: later.log }, watched, watching.signal);
+        const leaveHub = join(member);
+        // The leave waits for them, so they do not run on against a location that is closing.
+        track(member, pruned);
+        track(member, noticed);
         const leave = webhook ? joinReceiver(webhook, hooks) : undefined;
         return async () => {
-            clearInterval(timer);
-            watching.abort();
-            locations.delete(location);
-            if (relay.ports === questionPorts)
-                relay.ports = undefined;
+            // Waits, for a moment at most, for the work this instance leaves behind, and on the last
+            // leave for the scheduler's owner key to be released, so another server takes over at once.
+            const leftHub = leaveHub();
             leaveRelay();
             await leave?.();
+            await leftHub;
         };
     },
 });
 /**
- * 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",
     effect: (host) => Effect.gen(function* () {
-        const relay = {};
-        yield* fromPromise(courier(relay)).effect(host);
-        yield* relayQuestions(host, () => relay.ports);
+        yield* fromPromise(courier()).effect(host);
+        // The promise plugin's instance is handed this same location and has just joined with it: its
+        // member, bound now, while it stays loaded.
+        yield* relayQuestions(host, portsAt(host.location));
     }),
 });

package/dist/json.d.ts

@@ -0,0 +1,8 @@
+/** Readers for untyped JSON, such as a webhook payload or a plugin option: the value when it has the type, else nothing. */
+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

@@ -0,0 +1,15 @@
+/** Readers for untyped JSON, such as a webhook payload or a plugin option: the value when it has the type, else nothing. */
+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

@@ -1,7 +1,7 @@
 import type { Plugin } from "@opencode/plugin";
 import { type Storage } from "./storage.js";
 type Context = Plugin.Context;
-/** How often each plugin instance looks for due messages; a delivery can be this late. */
+/** 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;
@@ -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

@@ -1,6 +1,6 @@
-import { envelope } from "./courier.js";
+import { envelope } from "./notices.js";
 import { scanAll } from "./storage.js";
-/** How often each plugin instance looks for due messages; a delivery can be this late. */
+/** How often the hub's scheduler looks for due messages; a delivery can be this late. */
 export const TICK_MS = 15_000;
 const PREFIX = "later/";
 /** The latest time a Date can hold; a message due after it could never be shown or delivered. */
@@ -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>;