opencode-courier 0.12.0 → 0.13.0

package/README.md

@@ -18,7 +18,7 @@ A narrated tour of the terminal UI: the tree panel, the asks inbox, failing chil
 ## Quickstart
 
 ```bash
-npm install -g @opencode/cli@2.1.4   # OpenCode V2, the version courier is tested on
+npm install -g @opencode/cli@2.2.0   # OpenCode V2, the version courier is tested on
 opencode plugin add opencode-courier
 opencode
 ```
@@ -54,17 +54,18 @@ The message lands in the parent's inbox and starts a new turn if the parent is i
 
 Children started with the same `group` report together, in one message. A child that fails (a
 rate or quota limit with when it lifts), or ends its turn without reporting, is reported to its
-parent. A message that does not wake its session is sent once more, then shown as `stalled`. Children, held reports and scheduled messages
-survive a restart. The `courier-orchestrate` skill, listed in every session, tells a model when to
+parent. A message that does not wake its session is sent once more, then shown as `stalled`. On
+OpenCode 2.2.0 a parent's system prompt carries one line per child with its state, kept current,
+so it need not look. Children, held reports and scheduled messages survive a restart. The `courier-orchestrate` skill, listed in every session, tells a model when to
 split a task and how to check and merge the parts. Every detail: [the reference](docs/reference.md).
 
 ## Install
 
 Requires OpenCode V2: the `opencode` command from `@opencode/cli`. Each release is tested against
-one OpenCode version; this one is tested on **OpenCode 2.1.4** (check with `opencode --version`).
+one OpenCode version; this one is tested on **OpenCode 2.2.0** (check with `opencode --version`).
 
 ```bash
-npm install -g @opencode/cli@2.1.4
+npm install -g @opencode/cli@2.2.0
 opencode plugin add opencode-courier
 ```
 
@@ -77,13 +78,13 @@ name, without a version: OpenCode offers updates only for an entry without an ex
 <!-- compat-table:start rows=3: generated by script/compat-table.ts from the release tags -->
 | opencode-courier | OpenCode V2 (`opencode` and `@opencode/plugin`) |
 |---|---|
+| 0.13.0 | 2.2.0 |
 | 0.11.1, 0.12.0 | 2.1.4 |
 | 0.11.0 | 2.1.3 |
-| 0.10.2, 0.10.3 | 2.1.2 |
 <!-- compat-table:end -->
 
 Every release: [the full table](docs/reference.md#the-opencode-version). The server part loads on
-any V2 host from 2.0.4 on. The terminal part is tested on OpenCode 2.1.4 only.
+any V2 host from 2.0.4 on. The terminal part is tested on OpenCode 2.2.0 only.
 
 ## Options
 
@@ -114,7 +115,7 @@ form. Its one option, `"animations": false`, keeps the tree panel still.
 |---|---|
 | `courier_spawn` | Starts a child session with a task and returns at once. `isolate`, `group`, `agent`, `model`, `variant`, `native`, `title`. |
 | `courier_send` | Messages a session, waking it if idle. With a `status`, it is a child's report. |
-| `courier_status` / `courier_children` / `courier_tree` | One look at a session, at the sessions it started, or at its whole tree. |
+| `courier_children` / `courier_tree` | One look at the sessions a session started, or at its whole tree. |
 | `courier_stop` | Stops a session below you and everything under it. |
 | `courier_cleanup` | Removes an isolated child's worktree and forgets the child. |
 | `courier_answer` | Proposes an answer to a child's permission request, or passes on your answer to its question. |

package/dist/index.js

@@ -8,7 +8,7 @@ import { hub, openInProcess, permissions as domains, sharedState } from "./platf
 import { builtVersions, versionNotice } from "./platform/version.js";
 import { addSchedulingTools, cancelScheduled, dueJob, isScheduled } from "./scheduling/index.js";
 import { addPersonTools, asksPermission, asksQuestion, formsShown, joinRelay, noticeCutOff, pendingOf, pendingQuestions, personEvents, portsAt, registerPersonRpc, relayQuestions, } from "./person/index.js";
-import { addMemoryTools, memoryEvents, NOTE_TOOL, readMemory, RECALL_TOOL, registerMemoryRpc, sweepRecords } from "./memory/index.js";
+import { addMemoryTools, lessonsOf, memoryEvents, NOTE_TOOL, readMemory, RECALL_TOOL, registerMemoryRpc, sweepRecords } from "./memory/index.js";
 import { addSkill } from "./skill.js";
 import { addTreeTools, deliverReleased, wakeMissed, dirtyOf, headOf, inspectWorktree, pruneExpired, readLimits, readNativeChildren, registerTreeRpc, shapeContext, together, treeEvents, waitsOn, } from "./tree/index.js";
 import { addWebhookTools, joinReceiver, readConfig, receiving, subscribedSince, } from "./webhook/index.js";
@@ -77,6 +77,7 @@ export const courier = () => Plugin.define({
         for (const problem of [...problems, ...nativeProblems, ...memoryProblems])
             log(`courier: ${problem}`);
         const roles = new Map();
+        const memoryPorts = { storage: ctx.storage, session: ctx.session, now: Date.now, log, projectID: ctx.location.project.id, memory, maxDepth: limits.maxDepth };
         const ports = {
             limits,
             nativeChildren,
@@ -84,6 +85,8 @@ export const courier = () => Plugin.define({
             roles,
             nudge,
             log,
+            // What a spawned session gets besides its role: the memory's lessons entry, handed to the tree here as `outside` hands it the `Waits` suppliers.
+            entries: () => lessonsOf(memoryPorts),
             session: ctx.session,
             agent: ctx.agent,
             worktree: ctx.worktree,
@@ -130,7 +133,6 @@ export const courier = () => Plugin.define({
             later.log(`courier webhook: not started: ${error instanceof Error ? error.message : String(error)}`);
         }
         const stopPorts = { courier: ports, cancelScheduled: (sessionID) => cancelScheduled(later, sessionID), cleanup: cleanupPorts };
-        const memoryPorts = { storage: ctx.storage, session: ctx.session, now: Date.now, log, projectID: ctx.location.project.id, memory, maxDepth: limits.maxDepth };
         // The tools in a fixed order: the tree's, then the person's, the scheduled messages', the webhooks' and the memory's.
         await ctx.tool.transform((tools) => {
             addTreeTools(tools, { courier: ports, cleanup: cleanupPorts, stop: stopPorts });
@@ -146,7 +148,9 @@ export const courier = () => Plugin.define({
             .then(() => registerPersonRpc(ctx.rpc, { questions: questionPorts, permissions }))
             .then(() => registerMemoryRpc(ctx.rpc, memoryPorts))
             .catch((error) => log(`courier rpc: not registered, the TUI part shows nothing and cannot stop: ${String(error)}`));
-        await ctx.session.hook("context", (event) => shapeContext({ storage: ctx.storage, limits, roles, hiddenFromLeaf: [RECALL_TOOL, NOTE_TOOL], log }, event));
+        // `instructions` is read off the context as is: a host before 2.2.0 has none, and the hook then adds the role part.
+        const instructions = ctx.session.instructions;
+        await ctx.session.hook("context", (event) => shapeContext({ storage: ctx.storage, limits, roles, instructions, hiddenFromLeaf: [RECALL_TOOL, NOTE_TOOL], log }, event));
         const pruned = pruneExpired(ctx.storage, Date.now()).catch((error) => log(`courier roster prune: ${String(error)}`));
         const swept = sweepRecords(ctx.storage, Date.now()).catch((error) => log(`courier memory sweep: ${String(error)}`));
         // The windows the memory reads each part's context use by; a tree whose top runs in a location with memory off is not recorded.

package/dist/kernel/protocol.d.ts

@@ -22,5 +22,7 @@ export declare function clipText(text: string, max?: number): string;
 export declare function clipWords(text: string, max: number): string;
 /** Defuses `<courier` and `</courier>` in outside text, so it cannot close the envelope or forge another. */
 export declare function defuse(text: string): string;
+/** Defuses `<context` and `</context>` in text put in a session instruction entry, so it cannot close the entry's block or open another. */
+export declare function defuseBlock(text: string): string;
 /** A readable message for a failed courier call; OpenCode's own errors can carry an empty message. */
 export declare function describeFailure(tool: string, error: unknown): Error;

package/dist/kernel/protocol.js

@@ -38,6 +38,10 @@ export function clipWords(text, max) {
 export function defuse(text) {
     return text.replace(/<(\/?)(courier)/gi, "&lt;$1$2");
 }
+/** Defuses `<context` and `</context>` in text put in a session instruction entry, so it cannot close the entry's block or open another. */
+export function defuseBlock(text) {
+    return text.replace(/<(\/?)(context)/gi, "&lt;$1$2");
+}
 /** A readable message for a failed courier call; OpenCode's own errors can carry an empty message. */
 export function describeFailure(tool, error) {
     const tagged = error;

package/dist/memory/events.js

@@ -1,7 +1,8 @@
 import { claim } from "../platform/bounded.js";
 import { childrenOf, endsIdle, indexedLineage } from "../tree/index.js";
 import { refresh } from "./record.js";
-const TURN_ENDS = new Set(["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"]);
+const TURN_END_TYPES = ["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"];
+const TURN_ENDS = new Set(TURN_END_TYPES);
 /**
  * The top of the tree a session is in: by the reverse index for a spawned one, else the session itself when it called
  * courier_recall or has started sessions; undefined for a session in no tree.
@@ -41,6 +42,7 @@ export async function noteTurnEnd(ports, state, event) {
  */
 export function memoryEvents(state) {
     return {
+        types: TURN_END_TYPES,
         after: (ports, event) => TURN_ENDS.has(event.type)
             ? noteTurnEnd(ports, state, event).then(() => undefined, (error) => ports.log(`courier memory: could not record the tree of ${event.data?.sessionID}: ${String(error)}`))
             : undefined,

package/dist/memory/index.d.ts

@@ -1,5 +1,6 @@
 export { LESSON_MAX, MAX_RECORDS, NOT_STATED, readMemory, RETENTION_MS } from "./domain.js";
 export { memoryEvents, type MemoryEventPorts } from "./events.js";
+export { lessonsOf } from "./lessons.js";
 export { note, type Noted, type NoteInput } from "./note.js";
 export { pin, type PinOutcome } from "./pin.js";
 export type { Lesson, MemoryPorts, MemoryState, PartRecord, PartStatus, Pinned, Reads, Recalled, RefreshPorts, Revision, StoredRecord, TreeRecord } from "./ports.js";
@@ -7,5 +8,5 @@ export { recall, type Recall, type RecallInput } from "./recall.js";
 export { refresh } from "./record.js";
 export { registerMemoryRpc, type MemoryRpcPorts } from "./rpc-handlers.js";
 export { sweepRecords } from "./sweep.js";
-export { NOTE_TOOL, RECALL_TOOL } from "./text.js";
+export { LESSONS_KEY, NOTE_TOOL, RECALL_TOOL } from "./text.js";
 export { addMemoryTools, type MemoryToolPorts } from "./tools.js";

package/dist/memory/index.js

@@ -2,11 +2,12 @@
 // and the record's types.
 export { LESSON_MAX, MAX_RECORDS, NOT_STATED, readMemory, RETENTION_MS } from "./domain.js";
 export { memoryEvents } from "./events.js";
+export { lessonsOf } from "./lessons.js";
 export { note } from "./note.js";
 export { pin } from "./pin.js";
 export { recall } from "./recall.js";
 export { refresh } from "./record.js";
 export { registerMemoryRpc } from "./rpc-handlers.js";
 export { sweepRecords } from "./sweep.js";
-export { NOTE_TOOL, RECALL_TOOL } from "./text.js";
+export { LESSONS_KEY, NOTE_TOOL, RECALL_TOOL } from "./text.js";
 export { addMemoryTools } from "./tools.js";

package/dist/memory/lessons.d.ts

@@ -0,0 +1,12 @@
+import { type Entry } from "../tree/index.js";
+import type { MemoryPorts } from "./ports.js";
+/**
+ * The `lessons` entry of this project, as `courier_spawn` writes it to a spawned session before its prompt and to a root at
+ * its first spawn: none with the memory option off, or while no record of the project holds a lesson.
+ */
+export declare function lessonsOf(ports: MemoryPorts): Promise<ReadonlyArray<Entry>>;
+/**
+ * Puts the project's lessons entry again, once a lesson was written, on the writer's tree's top, the top's current children
+ * below `maxDepth` and the writer, each only where it differs from the entry stored; a failure is logged. Returns the sessions put.
+ */
+export declare function relesson(ports: MemoryPorts, writerID: string, top: string): Promise<string[]>;

package/dist/memory/lessons.js

@@ -0,0 +1,56 @@
+import { isNotFound } from "../platform/json.js";
+import { childrenOf } from "../tree/index.js";
+import { pinnedFirst } from "./domain.js";
+import { memoryStore } from "./store.js";
+import { LESSONS_KEY, lessonsEntry } from "./text.js";
+/**
+ * The `lessons` entry of this project, as `courier_spawn` writes it to a spawned session before its prompt and to a root at
+ * its first spawn: none with the memory option off, or while no record of the project holds a lesson.
+ */
+export async function lessonsOf(ports) {
+    if (!ports.memory)
+        return [];
+    const value = lessonsEntry(pinnedFirst(await memoryStore(ports.storage).ofProject(ports.projectID)));
+    return value === undefined ? [] : [{ key: LESSONS_KEY, value }];
+}
+/**
+ * Puts the project's lessons entry again, once a lesson was written, on the writer's tree's top, the top's current children
+ * below `maxDepth` and the writer, each only where it differs from the entry stored; a failure is logged. Returns the sessions put.
+ */
+export async function relesson(ports, writerID, top) {
+    const entries = ports.session.instructions?.entry;
+    if (!entries)
+        return [];
+    let sessions = [];
+    let entry;
+    try {
+        ;
+        [entry] = await lessonsOf(ports);
+        if (!entry)
+            return [];
+        const children = ports.maxDepth > 1 ? await childrenOf(ports.storage, top) : [];
+        sessions = [...new Set([top, ...children.map((child) => child.sessionID), writerID])];
+    }
+    catch (error) {
+        ports.log(`courier_note: the lessons entry could not be read again: ${String(error)}`);
+        return [];
+    }
+    const value = entry;
+    const renew = async (sessionID) => {
+        try {
+            const stored = (await entries.list({ sessionID })).find((one) => one.key === value.key);
+            if (stored?.value === value.value)
+                return false;
+            await entries.put({ sessionID, key: value.key, value: value.value });
+            return true;
+        }
+        catch (error) {
+            // A child on the roster that OpenCode no longer knows is a normal path, not one to log.
+            if (!isNotFound(error))
+                ports.log(`courier_note: the lessons entry of ${sessionID} could not be written: ${String(error)}`);
+            return false;
+        }
+    };
+    const put = await Promise.all(sessions.map(renew));
+    return sessions.filter((_, index) => put[index]);
+}

package/dist/memory/note.js

@@ -1,5 +1,6 @@
 import { lineage } from "../tree/index.js";
 import { LESSON_MAX, oneLine } from "./domain.js";
+import { relesson } from "./lessons.js";
 import { memoryStore } from "./store.js";
 /**
  * courier_note: writes `text`, as one line of at most `LESSON_MAX` characters (longer is refused, never clipped), as the lesson
@@ -25,5 +26,7 @@ export async function note(ports, callerID, input) {
         return { kind: "unrecorded", top };
     const lesson = { text, at: ports.now(), ...(depth ? { depth } : {}) };
     await store.put(projectID, top, { ...record, lesson });
+    // The lessons entry of the top, its children and the writer moves with it; the next tree's sessions get it at their spawn.
+    await relesson(ports, callerID, top);
     return { kind: "noted", projectID, top, lesson, ...(record.lesson ? { replaced: record.lesson } : {}) };
 }

package/dist/memory/ports.d.ts

@@ -1,7 +1,7 @@
 /** The memory's ports: what refreshing a record and courier_recall need of the plugin context, and what the process shares. */
 import type { Plugin } from "@opencode/plugin";
 import type { Storage } from "../platform/storage.js";
-import type { ModelWindow } from "../tree/index.js";
+import type { Instructions, ModelWindow } from "../tree/index.js";
 import type { Pinned, ReadKind, Reads, StoredRecord, TreeRecord } from "./domain.js";
 export type { Lesson, PartRecord, PartStatus, Pinned, ReadKind, Reads, Recalled, Revision, StoredRecord, TreeRecord } from "./domain.js";
 type Context = Plugin.Context;
@@ -14,6 +14,8 @@ export interface RefreshPorts {
 }
 /** What courier_recall and courier_note run on: one instance's ports. */
 export interface MemoryPorts extends RefreshPorts {
+    /** With `instructions`, the keyed session entries, which courier_note puts the lessons entry through; missing on a host before 2.2.0. */
+    readonly session: RefreshPorts["session"] & Instructions;
     /** The project of the plugin's location, whose records the tools read and write. */
     readonly projectID: string;
     /** The `memory` option: off, and the tools write and list nothing. */

package/dist/memory/text.d.ts

@@ -33,3 +33,14 @@ export declare const NOTE_EMPTY = "Not noted: text is empty. Write one line, wha
 /** The refusal of a lesson longer than `LESSON_MAX` as one line: nothing is written, and the earlier lesson stays. */
 export declare const noteLongRefusal: (length: number) => string;
 export declare const noteUnrecordedRefusal: (top: string) => string;
+/** The key of the session instruction entry carrying the project's lessons, `<context key="lessons">`. */
+export declare const LESSONS_KEY = "lessons";
+/** How every lessons entry begins. */
+export declare const LESSONS_PREFIX = "opencode-courier lessons:";
+/** How many lessons the entry carries: the records' order, pinned first, then newest first. */
+export declare const LESSONS_MAX = 5;
+/**
+ * The lessons entry: the lessons of the project's records as courier_recall lists them, pinned first and then newest first,
+ * at most `LESSONS_MAX`, each with its tree's title; undefined while no record holds one.
+ */
+export declare function lessonsEntry(records: ReadonlyArray<StoredRecord>): string | undefined;

package/dist/memory/text.js

@@ -1,5 +1,5 @@
 /** The memory's model-facing texts: what courier_recall and courier_note say. */
-import { clipText, clipWords } from "../kernel/protocol.js";
+import { clipText, clipWords, defuseBlock } from "../kernel/protocol.js";
 import { LESSON_MAX, oneLine, PART_STATUSES, splitProse } from "./domain.js";
 /** The tool's name, which the skill and the role part name too. */
 export const RECALL_TOOL = "courier_recall";
@@ -114,3 +114,24 @@ export const noteLongRefusal = (length) => `Not noted: the lesson is ${length} c
     `if there was one, stays. Keep one line, ${ONE_LINE}, and leave out what the record's facts already say.`;
 export const noteUnrecordedRefusal = (top) => `Not noted: the tree under ${top} has no record in this project to write a lesson on. A record is written by a ${RECALL_TOOL} call ` +
     "and as each turn in the tree ends, so call it once first, or note once a session you started has reported.";
+// The lessons entry: what a spawned session's system prompt says of the project's earlier trees.
+/** The key of the session instruction entry carrying the project's lessons, `<context key="lessons">`. */
+export const LESSONS_KEY = "lessons";
+/** How every lessons entry begins. */
+export const LESSONS_PREFIX = "opencode-courier lessons:";
+/** How many lessons the entry carries: the records' order, pinned first, then newest first. */
+export const LESSONS_MAX = 5;
+/**
+ * The lessons entry: the lessons of the project's records as courier_recall lists them, pinned first and then newest first,
+ * at most `LESSONS_MAX`, each with its tree's title; undefined while no record holds one.
+ */
+export function lessonsEntry(records) {
+    const lessons = records.filter((record) => record.lesson).slice(0, LESSONS_MAX);
+    if (!lessons.length)
+        return undefined;
+    return [
+        `${LESSONS_PREFIX} what the orchestrators of earlier session trees in this project concluded, each with its tree's title; ` +
+            `${RECALL_TOOL} has the records with the facts behind them.`,
+        ...lessons.map((record) => `- ${record.sessionID} "${clipText(defuseBlock(oneLine(record.title)), 60)}": ${defuseBlock(lessonLine(record.lesson))}`),
+    ].join("\n");
+}

package/dist/person/events.js

@@ -75,6 +75,8 @@ export async function relayPending(ports, state) {
     };
     await Promise.all([...sessions].map(relay));
 }
+/** What `routePerson` dispatches on. */
+const PERSON_TYPES = ["permission.asked", "permission.replied", "form.created", "form.replied", "form.cancelled", "location.shutdown"];
 /** The events of what a spawned session asks the person: permission requests, forms, and locations closing on them. */
 function routePerson(ports, state, event) {
     if (event.type === "permission.asked")
@@ -103,9 +105,10 @@ function routePerson(ports, state, event) {
  */
 export function personEvents(state) {
     return {
+        types: PERSON_TYPES,
         handle: (ports, event) => routePerson(ports, state, event),
         // Question forms shown while no instance followed the events were not seen: released now,
-        // and again on the first event, by when the stream is surely connected.
+        // and again once the stream is surely connected.
         followed: () => (eventsFollowed() ? formsMayHaveBeenMissed : undefined),
         // Alongside the new subscription; a request both relays see is relayed once.
         subscribed: (ports) => relayPending(ports, state).catch((error) => ports.log(`courier watch: could not relay pending requests: ${String(error)}`)),

package/dist/person/permission.d.ts

@@ -108,6 +108,6 @@ export declare function ownRequests(permissions: Iterable<Permissions>, sessionI
         requestID: string;
     } | undefined;
 }[]>;
-/** The requests a session waits on, in whichever location holds them, for courier_status. */
+/** The requests a session waits on, in whichever location holds them, for courier_children. */
 export declare function pendingOf(permissions: Iterable<Permissions>, sessionID: string): Promise<Pending[]>;
 export {};

package/dist/person/permission.js

@@ -130,7 +130,7 @@ export async function ownRequests(permissions, sessionID) {
             found.set(request.id, request);
     return [...found.values()].map((request) => ({ request, passesOn: passedOn(request.metadata) }));
 }
-/** The requests a session waits on, in whichever location holds them, for courier_status. */
+/** The requests a session waits on, in whichever location holds them, for courier_children. */
 export async function pendingOf(permissions, sessionID) {
     const found = new Map();
     for (const { requests } of await listEverywhere(permissions, sessionID))

package/dist/person/question/answer.d.ts

@@ -50,7 +50,7 @@ export declare function answerForPerson(ports: QuestionPorts, input: QuestionAns
 export declare function asksQuestion(ports: {
     readonly storage: RosterStorage;
 }, sessionID: string): Promise<boolean>;
-/** The questions a session waits on, for courier_status; `stopped` when its call was cut off. */
+/** The questions a session waits on, for courier_children; `stopped` when its call was cut off. */
 export declare function pendingQuestions(storage: RosterStorage, sessionID: string): Promise<{
     type: "question";
     requestID: string;

package/dist/person/question/answer.js

@@ -190,7 +190,7 @@ export async function answerForPerson(ports, input) {
 export async function asksQuestion(ports, sessionID) {
     return (await pendingQuestions(ports.storage, sessionID)).length > 0;
 }
-/** The questions a session waits on, for courier_status; `stopped` when its call was cut off. */
+/** The questions a session waits on, for courier_children; `stopped` when its call was cut off. */
 export async function pendingQuestions(storage, sessionID) {
     const found = new Map();
     const add = (asked, stopped) => found.set(asked.requestID, {

package/dist/person/question/lifecycle.d.ts

@@ -36,7 +36,7 @@ export declare function formShown(event: {
 export declare function formsMayHaveBeenMissed(): void;
 /**
  * Called when an instance starts following OpenCode's events: a shown form is missed only while none
- * follows, so waiting calls are released; true tells the caller to release again on its first event.
+ * follows, so waiting calls are released; true tells the caller to release again once connected.
  */
 export declare function eventsFollowed(): boolean;
 /** Called when an instance's event stream ended or broke. */

package/dist/person/question/lifecycle.js

@@ -75,7 +75,7 @@ export function formsMayHaveBeenMissed() {
 }
 /**
  * Called when an instance starts following OpenCode's events: a shown form is missed only while none
- * follows, so waiting calls are released; true tells the caller to release again on its first event.
+ * follows, so waiting calls are released; true tells the caller to release again once connected.
  */
 export function eventsFollowed() {
     const missed = shared.following === 0 && shared.followed;

package/dist/person/question/relay.js

@@ -31,7 +31,7 @@ async function relay(ports, question) {
         return true;
     }
     catch (error) {
-        // The question stays registered and the call waits on: courier_status lists it, and an answer
+        // The question stays registered and the call waits on: courier_children lists it, and an answer
         // that comes anyway, through a link or courier_answer, still reaches the call.
         ports.log(`courier question: could not tell ${question.top} about ${question.requestID}: ${String(error)}`);
         return false;

package/dist/platform/events.d.ts

@@ -10,13 +10,17 @@ export interface EventPorts {
     readonly event: Pick<Plugin.Context["event"], "subscribe">;
     readonly log: (message: string) => void;
 }
+/** An event type `event.subscribe` can filter on: any of OpenCode's but `server.connected`, which a plugin never receives. */
+export type EventType = NonNullable<NonNullable<Parameters<EventPorts["event"]["subscribe"]>[0]>["types"]>[number];
 /** What a module does with OpenCode's events, by phase; each phase runs the modules in list order. */
 export interface EventModule<P extends EventPorts> {
+    /** The event types it handles; without them, every event, so the subscription is not filtered. */
+    readonly types?: readonly EventType[];
     /** For each event; the first to throw ends the phase. */
     readonly handle?: (ports: P, event: HostEvent) => Promise<unknown> | undefined;
     /** For each event, once the `handle` phase has ended, however it did; the first to throw ends this one too. */
     readonly after?: (ports: P, event: HostEvent) => Promise<void> | undefined;
-    /** As a subscription starts; returns what to run at its first event, if anything. */
+    /** As a subscription starts; returns what to run once the stream is surely connected, if anything. */
     readonly followed?: () => (() => void) | undefined;
     /** Alongside each (re)subscription; the watcher's end waits for it. */
     readonly subscribed?: (ports: P) => Promise<void>;
@@ -25,8 +29,12 @@ export interface EventModule<P extends EventPorts> {
 }
 /** How long to wait before subscribing again after the event stream ended or broke. */
 export declare const RESUBSCRIBE_MS = 5000;
+/** How long after subscribing the stream is taken as connected, should no event come first: a plugin's reports no connection. */
+export declare const CONNECTED_MS = 1000;
+/** The types `modules` declare, sorted; undefined, every type, once one of them declares none. */
+export declare function typesOf(modules: readonly EventModule<never>[]): EventType[] | undefined;
 /** Follows OpenCode's events through `ports`, subscribing again after `retryMs` when a subscription ends, until `signal` aborts. */
-export declare function follow<P extends EventPorts>(ports: P, modules: readonly EventModule<P>[], signal: AbortSignal, retryMs?: number): Promise<void>;
+export declare function follow<P extends EventPorts>(ports: P, modules: readonly EventModule<P>[], signal: AbortSignal, retryMs?: number, connectedMs?: number): Promise<void>;
 /**
  * Makes the hub start its subscriptions to OpenCode's events with this copy's modules, the copy loaded
  * last; `join` starts them. The second is a standby, connected before the first's member leaves.

package/dist/platform/events.js

@@ -1,5 +1,7 @@
 /** How long to wait before subscribing again after the event stream ended or broke. */
 export const RESUBSCRIBE_MS = 5_000;
+/** How long after subscribing the stream is taken as connected, should no event come first: a plugin's reports no connection. */
+export const CONNECTED_MS = 1_000;
 const pause = (ms, signal) => new Promise((resolve) => {
     const timer = setTimeout(done, ms);
     function done() {
@@ -32,6 +34,17 @@ const until = (events, signal) => ({
         }),
     }),
 });
+/** The types `modules` declare, sorted; undefined, every type, once one of them declares none. */
+export function typesOf(modules) {
+    const types = new Set();
+    for (const module of modules) {
+        if (!module.types)
+            return undefined;
+        for (const type of module.types)
+            types.add(type);
+    }
+    return [...types].sort((a, b) => Number(a > b) - Number(a < b));
+}
 /** One event through the `handle` phase, then, however that ended, the `after` phase. */
 async function handle(ports, modules, event) {
     try {
@@ -70,18 +83,31 @@ function subscribed(ports, modules, alongside) {
     }
 }
 /** One subscription, its events through `modules`' phases, until its stream ends or breaks or `signal` aborts. */
-async function subscription(ports, modules, signal, alongside) {
+async function subscription(ports, modules, signal, alongside, connectedMs) {
     let following = false;
     let events;
+    let first = [];
+    let timer;
+    // The stream is surely connected at its first event, filtered or not, or `connectedMs` after subscribing.
+    const connected = () => {
+        clearTimeout(timer);
+        for (const run of first.splice(0))
+            run();
+    };
+    const types = typesOf(modules);
+    const wanted = types && new Set(types);
     try {
-        events = ports.event.subscribe({ signal })[Symbol.asyncIterator]();
-        let first = modules.flatMap((module) => module.followed?.() ?? []);
+        events = ports.event.subscribe({ signal, ...(types && { types }) })[Symbol.asyncIterator]();
+        first = modules.flatMap((module) => module.followed?.() ?? []);
+        if (first.length > 0)
+            timer = setTimeout(connected, connectedMs);
         following = true;
         subscribed(ports, modules, alongside);
         for await (const event of until(events, signal)) {
-            for (const run of first)
-                run();
-            first = [];
+            connected();
+            // A host that ignores `types` sends every event; none outside them reaches a module.
+            if (wanted && !wanted.has(event.type))
+                continue;
             await handleLogged(ports, modules, event);
         }
     }
@@ -90,6 +116,8 @@ async function subscription(ports, modules, signal, alongside) {
             ports.log(`courier watch: event stream broke: ${String(error)}`);
     }
     finally {
+        clearTimeout(timer);
+        first = [];
         if (following)
             for (const module of modules)
                 module.left?.();
@@ -99,10 +127,10 @@ async function subscription(ports, modules, signal, alongside) {
     }
 }
 /** Follows OpenCode's events through `ports`, subscribing again after `retryMs` when a subscription ends, until `signal` aborts. */
-export async function follow(ports, modules, signal, retryMs = RESUBSCRIBE_MS) {
+export async function follow(ports, modules, signal, retryMs = RESUBSCRIBE_MS, connectedMs = CONNECTED_MS) {
     const alongside = new Set();
     while (!signal.aborted) {
-        await subscription(ports, modules, signal, alongside);
+        await subscription(ports, modules, signal, alongside, connectedMs);
         if (!signal.aborted)
             await pause(retryMs, signal);
     }
@@ -113,8 +141,10 @@ export async function follow(ports, modules, signal, retryMs = RESUBSCRIBE_MS) {
  * last; `join` starts them. The second is a standby, connected before the first's member leaves.
  */
 export function watchFromHub(hub, modules, retryMs = RESUBSCRIBE_MS) {
+    const types = typesOf(modules);
     hub.subscribe = (member) => {
         const stop = new AbortController();
+        member.log(`courier watch: following ${types ? types.join(", ") : "every event"} through ${member.directory}`);
         // A member of any copy runs them: every hub-v2 member's `watch` ports are the same shape.
         return { member, stop, done: follow(member.watch, modules, stop.signal, retryMs) };
     };