opencode-courier 0.2.2 → 0.2.3

package/dist/roster.js

@@ -1,23 +1,53 @@
 import { existsSync } from "node:fs";
-import { scanAll } from "./storage.js";
+import { scanAll, scanEntries } from "./storage.js";
 /**
  * Entries older than this are dropped when their parent's roster is read, and on plugin setup,
  * except isolated children whose worktree is still there: those stay until courier_cleanup.
  */
 export const RETENTION_MS = 14 * 24 * 60 * 60_000;
 const PREFIX = "roster/";
+/**
+ * The reverse index: under `roster-by-child/<sessionID>`, a child's `ReverseEntry`, written with its
+ * roster entry. It is only an index: an entry without one, written by an older copy of the plugin,
+ * is found by scanning `roster/`, and every entry it leads to is read from `roster/` to check that
+ * it is still there.
+ */
+const BY_CHILD = "roster-by-child/";
 export function rosterKey(parentID, sessionID) {
     return `${PREFIX}${parentID}/${sessionID}`;
 }
+export function reverseKey(sessionID) {
+    return `${BY_CHILD}${sessionID}`;
+}
+/**
+ * Records a child under its parent, then indexes it. The entry is what counts: a failed index
+ * write leaves it to be found by a scan, and to be indexed when the plugin is next loaded.
+ */
 export async function record(storage, entry) {
     await storage.set(rosterKey(entry.parentID, entry.sessionID), { ...entry });
+    await index(storage, entry).catch(() => undefined);
+}
+async function index(storage, entry) {
+    const above = await storage.get(reverseKey(entry.parentID));
+    const ancestors = isReverse(above) ? above.ancestors : (await lineage(storage, entry.parentID)).map((parent) => parent.parentID);
+    await storage.set(reverseKey(entry.sessionID), { ancestors: [entry.parentID, ...ancestors] });
+}
+function isReverse(value) {
+    const ancestors = value?.ancestors;
+    return Array.isArray(ancestors) && ancestors.length > 0 && ancestors.every((id) => typeof id === "string");
+}
+/**
+ * Removes a child's roster entry and its reverse key. Only the entry's removal can fail it: a
+ * reverse key left behind leads nowhere, and the next load drops it.
+ */
+export async function remove(storage, parentID, sessionID) {
+    await Promise.all([storage.remove(rosterKey(parentID, sessionID)), storage.remove(reverseKey(sessionID)).catch(() => undefined)]);
 }
 /** Removes a child from its parent's roster; false when it was not there. */
 export async function forget(storage, parentID, sessionID) {
-    const key = rosterKey(parentID, sessionID);
-    if ((await storage.get(key)) === undefined)
+    if ((await storage.get(rosterKey(parentID, sessionID))) === undefined)
         return false;
-    await storage.remove(key);
+    await remove(storage, parentID, sessionID);
     return true;
 }
 /** A parent's children, oldest first. */
@@ -31,7 +61,11 @@ export async function allEntries(storage) {
 }
 /** A session's roster entries: one for the parent that started it, none if courier_spawn did not. */
 export async function entriesOf(storage, sessionID) {
-    return (await scanAll(storage, PREFIX)).filter((entry) => entry.sessionID === sessionID);
+    const indexed = await storage.get(reverseKey(sessionID));
+    if (!isReverse(indexed))
+        return (await scanAll(storage, PREFIX)).filter((entry) => entry.sessionID === sessionID);
+    const entry = await storage.get(rosterKey(indexed.ancestors[0], sessionID));
+    return entry === undefined ? [] : [entry];
 }
 /**
  * The roster entries from a session up to the top, its own first: the session's, its parent's, and
@@ -39,7 +73,31 @@ export async function entriesOf(storage, sessionID) {
  * did not start the session.
  */
 export async function lineage(storage, sessionID) {
-    return lineageIn(await allEntries(storage), sessionID);
+    const first = await storage.get(reverseKey(sessionID));
+    if (!isReverse(first))
+        return lineageIn(await allEntries(storage), sessionID);
+    let indexed = first;
+    const chain = [];
+    let below = sessionID;
+    // One read per level, all at once, and one more for the top's own reverse key, in case it was
+    // recorded after the key that names it; the chain ends where an entry is gone, as a scan's would.
+    for (;;) {
+        const { ancestors } = indexed;
+        const top = ancestors.at(-1);
+        const [entries, above] = await Promise.all([
+            Promise.all(ancestors.map((parentID, level) => storage.get(rosterKey(parentID, level ? ancestors[level - 1] : below)))),
+            storage.get(reverseKey(top)),
+        ]);
+        for (const entry of entries) {
+            if (!entry || chain.some((known) => known.sessionID === entry.sessionID))
+                return chain;
+            chain.push(entry);
+        }
+        if (!isReverse(above))
+            return chain;
+        below = top;
+        indexed = above;
+    }
 }
 /** `lineage` over roster entries already read. */
 export function lineageIn(entries, sessionID) {
@@ -70,14 +128,48 @@ export async function answeringTop(storage, sessionID, callerID, what) {
  */
 async function dropExpired(storage, entries, now, exists) {
     const expired = new Set(entries.filter((entry) => now - entry.createdAt > RETENTION_MS && !(entry.isolated && exists(entry.directory))));
-    await Promise.all([...expired].map((entry) => storage.remove(rosterKey(entry.parentID, entry.sessionID))));
+    await Promise.all([...expired].map((entry) => remove(storage, entry.parentID, entry.sessionID)));
     return entries.filter((entry) => !expired.has(entry));
 }
 /** A parent's children, oldest first, after dropping the expired ones. */
 export async function current(storage, parentID, now, exists = existsSync) {
     return dropExpired(storage, await children(storage, parentID), now, exists);
 }
-/** Drops expired entries of every parent, so parents that never list their children don't keep them forever. */
+/**
+ * On loading: drops expired entries of every parent, so parents that never list their children
+ * don't keep them forever, then brings the reverse index in line with what is left (`backfill`).
+ */
 export async function pruneExpired(storage, now, exists = existsSync) {
-    await dropExpired(storage, await scanAll(storage, PREFIX), now, exists);
+    await backfill(storage, await dropExpired(storage, await scanAll(storage, PREFIX), now, exists));
+}
+/** Whether a reverse key's value leads to this entry. */
+function indexes(value, entry) {
+    return isReverse(value) && value.ancestors[0] === entry.parentID;
+}
+/**
+ * Writes the reverse keys missing for the given entries, or naming another parent, all of the roster, such as those an older
+ * copy of the plugin recorded, and drops the reverse keys whose entry is gone, such as those of an
+ * entry an older copy removed. Keys that lead to their entry are left as they are, so running it
+ * again changes nothing.
+ */
+export async function backfill(storage, entries) {
+    const indexed = new Map((await scanEntries(storage, BY_CHILD)).map(({ key, value }) => [key, value]));
+    const sessions = new Set(entries.map((entry) => entry.sessionID));
+    await Promise.all([
+        ...entries
+            .filter((entry) => !indexes(indexed.get(entry.sessionID), entry))
+            .map((entry) => storage.set(reverseKey(entry.sessionID), { ancestors: lineageIn(entries, entry.sessionID).map((above) => above.parentID) })),
+        ...[...indexed]
+            .filter(([sessionID]) => !sessions.has(sessionID))
+            .map(([sessionID, value]) => dropDangling(storage, sessionID, value)),
+    ]);
+}
+/**
+ * Drops a reverse key whose entry was not in the roster read, unless that entry is there now:
+ * another instance may have recorded the child since, and it writes the entry before the key.
+ */
+async function dropDangling(storage, sessionID, value) {
+    if (isReverse(value) && (await storage.get(rosterKey(value.ancestors[0], sessionID))) !== undefined)
+        return;
+    await storage.remove(reverseKey(sessionID));
 }

package/dist/storage.d.ts

@@ -3,9 +3,16 @@ type Context = Plugin.Context;
 export type Storage = Pick<Context["storage"], "get" | "set" | "remove" | "scan">;
 /** Every value stored under `prefix`, following the scan's pages. */
 export declare function scanAll<T>(storage: Pick<Storage, "scan">, prefix: string): Promise<T[]>;
+/** Every key under `prefix`, without the prefix, with its value, following the scan's pages. */
+export declare function scanEntries<T>(storage: Pick<Storage, "scan">, prefix: string): Promise<{
+    key: string;
+    value: T;
+}[]>;
+/** Where process-wide values are kept: `globalThis`, or a stand-in for it in tests. */
+export type Registry = Record<symbol, unknown>;
 /**
  * The one value the whole process keeps under `Symbol.for(key)`, made by `create` the first time,
  * so every instance of the plugin, and every copy of it loaded later, gets the same one.
  */
-export declare function processWide<T>(key: string, create: () => T): T;
+export declare function processWide<T>(key: string, create: () => T, registry?: Registry): T;
 export {};

package/dist/storage.js

@@ -1,21 +1,24 @@
 /** Every value stored under `prefix`, following the scan's pages. */
 export async function scanAll(storage, prefix) {
-    const values = [];
+    return (await scanEntries(storage, prefix)).map((entry) => entry.value);
+}
+/** Every key under `prefix`, without the prefix, with its value, following the scan's pages. */
+export async function scanEntries(storage, prefix) {
+    const entries = [];
     let after;
     do {
         const page = await storage.scan({ prefix, ...(after ? { after } : {}) });
         for (const entry of page.entries)
-            values.push(entry.value);
+            entries.push({ key: entry.key.slice(prefix.length), value: entry.value });
         after = page.next;
     } while (after);
-    return values;
+    return entries;
 }
 /**
  * The one value the whole process keeps under `Symbol.for(key)`, made by `create` the first time,
  * so every instance of the plugin, and every copy of it loaded later, gets the same one.
  */
-export function processWide(key, create) {
-    const registry = globalThis;
+export function processWide(key, create, registry = globalThis) {
     const symbol = Symbol.for(key);
     registry[symbol] ??= create();
     return registry[symbol];

package/dist/tools.d.ts

@@ -0,0 +1,74 @@
+import type { Plugin } from "@opencode/plugin";
+import { Schema } from "effect";
+import { type CleanupPorts } from "./cleanup.js";
+import { type CourierPorts } from "./courier.js";
+import { type LaterPorts } from "./later.js";
+import { type QuestionPorts } from "./question/index.js";
+import { type AnswerPorts, type Waiting } from "./relay.js";
+import { type WebhookPorts } from "./webhook.js";
+/**
+ * The courier tools: their input schemas, descriptions, and what each returns. The descriptions are
+ * model-facing like the texts in `notices.ts`, and snapshotted with them in `test/notices.test.ts`.
+ */
+export declare const SpawnInput: Schema.Struct<{
+    readonly task: Schema.String;
+    readonly title: Schema.optional<Schema.String>;
+    readonly agent: Schema.optional<Schema.String>;
+    readonly isolate: Schema.optional<Schema.Boolean>;
+}>;
+export declare const SendInput: Schema.Struct<{
+    readonly sessionID: Schema.String;
+    readonly message: Schema.String;
+    readonly queue: Schema.optional<Schema.Boolean>;
+}>;
+export declare const StatusInput: Schema.Struct<{
+    readonly sessionID: Schema.String;
+}>;
+export declare const ChildrenInput: Schema.Struct<{
+    readonly sessionID: Schema.optional<Schema.String>;
+}>;
+export declare const CleanupInput: Schema.Struct<{
+    readonly sessionID: Schema.String;
+    readonly force: Schema.optional<Schema.Boolean>;
+}>;
+export declare const LaterInput: Schema.Struct<{
+    readonly message: Schema.String;
+    readonly delayMinutes: Schema.optional<Schema.Union<readonly [Schema.Number, Schema.String]>>;
+    readonly at: Schema.optional<Schema.String>;
+    readonly sessionID: Schema.optional<Schema.String>;
+}>;
+export declare const AnswerInput: Schema.Struct<{
+    readonly sessionID: Schema.String;
+    readonly requestID: Schema.String;
+    readonly reply: Schema.optional<Schema.Literals<readonly ["once", "always", "reject"]>>;
+    readonly message: Schema.optional<Schema.String>;
+    readonly answers: Schema.optional<Schema.$Array<Schema.Union<readonly [Schema.String, Schema.$Array<Schema.String>]>>>;
+}>;
+export declare const CancelInput: Schema.Struct<{
+    readonly id: Schema.String;
+}>;
+export declare const SubscribeInput: Schema.Struct<{
+    readonly topic: Schema.String;
+    readonly sessionID: Schema.optional<Schema.String>;
+}>;
+export declare const UnsubscribeInput: Schema.Struct<{
+    readonly topic: Schema.optional<Schema.String>;
+    readonly sessionID: Schema.optional<Schema.String>;
+}>;
+/** The editor OpenCode hands a tool transform. */
+export type ToolEditor = Parameters<Parameters<Plugin.Context["tool"]["transform"]>[0]>[0];
+/** What the tools run on: one plugin instance's ports. */
+export interface ToolPorts {
+    readonly courier: CourierPorts;
+    readonly cleanup: CleanupPorts;
+    readonly later: LaterPorts;
+    readonly answer: AnswerPorts;
+    readonly questions: QuestionPorts;
+    readonly hooks: WebhookPorts;
+    /** The permission requests sessions were told about and have not answered. */
+    readonly waiting: Waiting;
+    /** Whether a webhook receiver runs in this server. */
+    readonly receiving: () => Promise<boolean>;
+}
+/** Adds the courier tools, each a direct tool rather than a code-mode one. */
+export declare function addTools(tools: ToolEditor, ports: ToolPorts): void;

package/dist/tools.js

@@ -0,0 +1,228 @@
+import { Schema } from "effect";
+import { cleanup } from "./cleanup.js";
+import { describeFailure, listChildren, send, spawn, status } from "./courier.js";
+import { cancel, schedule } from "./later.js";
+import { answerText, cancelText, childrenText, cleanupText, laterText, REPLIES, sendText, spawnText, statusText, subscribeText, unsubscribeText, } from "./notices.js";
+import { answerQuestion, isQuestion } from "./question/index.js";
+import { answer } from "./relay.js";
+import { subscribe, unsubscribe } from "./webhook.js";
+/**
+ * The courier tools: their input schemas, descriptions, and what each returns. The descriptions are
+ * model-facing like the texts in `notices.ts`, and snapshotted with them in `test/notices.test.ts`.
+ */
+export 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." })),
+});
+export 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." })),
+});
+export const StatusInput = Schema.Struct({
+    sessionID: Schema.String.annotate({ description: "The session to look at." }),
+});
+export const ChildrenInput = Schema.Struct({
+    sessionID: Schema.optional(Schema.String.annotate({ description: "The session whose children to list; defaults to this one." })),
+});
+export 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.",
+    })),
+});
+export const LaterInput = Schema.Struct({
+    message: Schema.String.annotate({ description: "The message to deliver." }),
+    delayMinutes: Schema.optional(
+    // Some models send the number as a string ("3", "3.0") whatever the schema says, and resend it
+    // unchanged after the error, so a string is accepted and schedule reads it as a number.
+    Schema.Union([Schema.Number, Schema.String]).annotate({
+        description: "Deliver this many minutes from now. Give this or at.",
+    })),
+    at: Schema.optional(Schema.String.annotate({ description: "Deliver at this ISO 8601 time. Give this or delayMinutes." })),
+    sessionID: Schema.optional(Schema.String.annotate({ description: "The session to deliver to; defaults to this one." })),
+});
+export const 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(REPLIES).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.",
+    })),
+});
+export const CancelInput = Schema.Struct({
+    id: Schema.String.annotate({ description: "The id courier_later returned." }),
+});
+export 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." })),
+});
+export 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 rethrow = (tool) => (error) => {
+    throw describeFailure(tool, error);
+};
+// One tool answers both: a question's id is the plugin's own, a permission request's OpenCode's.
+async function answerRequest(ports, 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(ports.questions, 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(ports.answer, ports.waiting, callerID, {
+        sessionID,
+        requestID,
+        reply: input.reply,
+        ...(input.message !== undefined ? { message: input.message } : {}),
+    });
+}
+/** Adds the courier tools, each a direct tool rather than a code-mode one. */
+export function addTools(tools, ports) {
+    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.courier, context.sessionID, input).catch(rethrow("courier_spawn"));
+            return { content: spawnText(child), 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.courier, context.sessionID, input).catch(rethrow("courier_send"));
+            return { content: sendText(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.courier, input).catch(rethrow("courier_status"));
+            return { content: statusText(result), 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.courier, input.sessionID || context.sessionID).catch(rethrow("courier_children"));
+            return { content: childrenText(listed), 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(ports.cleanup, context.sessionID, input).catch(rethrow("courier_cleanup"));
+            return { content: cleanupText(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(ports, context.sessionID, input).catch(rethrow("courier_answer"));
+            return { content: answerText(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(ports.later, context.sessionID, input).catch(rethrow("courier_later"));
+            const fireAt = new Date(entry.fireAt).toISOString();
+            return {
+                content: laterText(entry, fireAt, entry.sessionID === context.sessionID),
+                metadata: { id: entry.id, fireAt, sessionID: entry.sessionID },
+            };
+        },
+    });
+    tools.add({
+        name: "courier_cancel",
+        options: { codemode: false },
+        description: "Cancel a message scheduled with courier_later, e.g. because the child it was waiting for reported.",
+        input: CancelInput,
+        execute: async (input) => {
+            const cancelled = await cancel(ports.later, input.id).catch(rethrow("courier_cancel"));
+            return { content: cancelText(input.id, cancelled), 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(ports.hooks, sessionID, input.topic).catch(rethrow("courier_subscribe"));
+            const receiving = await ports.receiving();
+            return {
+                content: subscribeText(sessionID, subscription.topic, receiving),
+                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(ports.hooks, sessionID, input.topic).catch(rethrow("courier_unsubscribe"));
+            return { content: unsubscribeText(sessionID, dropped), metadata: { sessionID, dropped } };
+        },
+    });
+}

package/dist/watch.d.ts

@@ -1,44 +1,17 @@
-import type { Plugin } from "@opencode/plugin";
-import { type PermissionAsked, type PermissionReplied, type Waiting } from "./relay.js";
-import { type RosterStorage } from "./roster.js";
-type Context = Plugin.Context;
+import type { Hub, WatchPorts, WatchState } from "./hub.js";
+import { type ExecutionError } from "./notices.js";
+import { type FormCreated, type FormSettled, type PermissionAsked, type PermissionReplied } from "./relay.js";
+export type { FormsTold, WatchPorts, WatchState } from "./hub.js";
 /** How long to wait before subscribing again after the event stream ended or broke. */
 export declare const RESUBSCRIBE_MS = 5000;
-export interface WatchPorts {
-    readonly storage: RosterStorage;
-    readonly session: Pick<Context["session"], "synthetic">;
-    readonly event: Pick<Context["event"], "subscribe">;
-    /** This location's pending permission requests, relayed when the watcher (re)subscribes. */
-    readonly permission: Pick<Context["permission"], "list">;
-    readonly log: (message: string) => void;
-}
-/**
- * What every plugin instance in the process shares: OpenCode sets the plugin up once per project
- * location, all in one process, and each instance may see the same event, so an event id is
- * claimed synchronously and handled once. `waiting` holds the permission requests a session was
- * told about and has not answered; `answered`, requests answered before anyone was told, so a
- * notice whose roster lookup was overtaken by the answer is not sent.
- */
-export interface WatchState {
-    readonly seen: Set<string>;
-    readonly waiting: Waiting;
-    readonly answered: Set<string>;
-}
 /** The part of OpenCode's `session.execution.failed` event the notice is made from. */
 export interface ExecutionFailed {
     readonly id: string;
     readonly data: {
         readonly sessionID: string;
-        readonly error: {
-            readonly type: string;
-            readonly message: string;
-            readonly status?: number;
-        };
+        readonly error: ExecutionError;
     };
 }
-export declare function failureNotice(title: string, error: ExecutionFailed["data"]["error"]): string;
-/** Adds to a bounded set, dropping the oldest entry; false when the value was there already. */
-export declare function claim(set: Set<string>, value: string): boolean;
 /**
  * Tells the parent of a child whose turn failed, since a child that cannot reach its model cannot
  * call courier_send. Returns the parents told.
@@ -56,15 +29,33 @@ export declare function reportAsked(ports: WatchPorts, state: WatchState, event:
  */
 export declare function reportReplied(ports: WatchPorts, state: WatchState, event: PermissionReplied): Promise<string[]>;
 /**
- * Relays the requests that spawned sessions in this location already wait on, which the event
- * stream does not repeat: those asked while it was down, before the watcher (re)subscribed.
+ * Tells the session at the top about a form OpenCode shows in a spawned session, such as web
+ * search asking for its provider, which only the person can answer there. Question forms are
+ * left to the question relay, which passes every question of a spawned session on.
+ */
+export declare function reportForm(ports: WatchPorts, state: WatchState, event: FormCreated): Promise<string[]>;
+/** Tells the session told about a form that it was answered or withdrawn, so it does not send the person to a form that is gone. */
+export declare function reportFormSettled(ports: WatchPorts, state: WatchState, event: FormSettled): Promise<string[]>;
+/**
+ * Relays the requests that spawned sessions already wait on, in every loaded location, which the
+ * event stream does not repeat: those asked while it was down, before the watcher (re)subscribed.
  */
 export declare function relayPending(ports: WatchPorts, state: WatchState): Promise<void>;
 /**
  * Follows OpenCode's events until `signal` aborts, telling parents when a spawned child's turn
- * fails, when it waits for a permission and when that request is answered without them, and
+ * fails, when it waits for a permission or on a form and when that is answered without them, and
  * noting for the question relay the question forms shown, which it waits for, and the locations
- * shutting down, whose withdrawn forms must not pass for dismissals.
+ * shutting down, whose withdrawn forms must not pass for dismissals. Once `signal` aborts it ends
+ * as soon as the event it is handling, and the relay of the requests already pending, are done,
+ * without waiting for the stream to close: an unloading instance's leave waits for that.
  */
 export declare function watchChildren(ports: WatchPorts, state: WatchState, signal: AbortSignal, retryMs?: number): Promise<void>;
-export {};
+/**
+ * Makes the hub start its subscriptions to OpenCode's events with this copy's watcher, the copy loaded
+ * last's, as after an update; `join` starts them. Every instance in the process is sent every event,
+ * so one subscription would serve them all; the second is a standby, already connected when the
+ * first one's member leaves, so no event goes unseen then. Both handle every event, and the claim
+ * sets tell each once. Like any (re)subscription, a new one relays the requests already pending,
+ * which the claim sets tell once too.
+ */
+export declare function watchFromHub(hub: Pick<Hub, "subscribe">, state: WatchState, retryMs?: number): void;