opencode-courier 0.0.0-stage → 0.1.0

package/dist/courier.js

@@ -0,0 +1,122 @@
+import { current, record } from "./roster.js";
+export function childBrief(parentID, task) {
+    return [
+        `You were started by session ${parentID} through opencode-courier.`,
+        "",
+        `When you finish, or need a decision you cannot make yourself, call courier_send with sessionID "${parentID}" and a short report.`,
+        "That message wakes the parent. It is the only way the parent hears from you, so do not end without sending it.",
+        "",
+        "Task:",
+        task,
+    ].join("\n");
+}
+export function envelope(from, message, attributes = {}) {
+    const extra = Object.entries(attributes)
+        .map(([name, value]) => ` ${name}="${value}"`)
+        .join("");
+    return `<courier from="${from}"${extra}>\n${message}\n</courier>`;
+}
+function titleOf(task) {
+    const line = task.trim().split("\n")[0] ?? "";
+    return line.length > 60 ? `${line.slice(0, 57)}...` : line;
+}
+/** Creates a child session, hands it the task and returns at once; the child reports back with courier_send. */
+export async function spawn(ports, parentID, input) {
+    const directory = input.isolate
+        ? (await ports.worktree.create({ location: { directory: ports.directory } })).directory
+        : undefined;
+    const base = directory ? await ports.head(directory) : undefined;
+    const title = input.title ?? titleOf(input.task);
+    const child = await ports.session
+        .create({
+        title,
+        ...(input.agent ? { agent: input.agent } : {}),
+        ...(directory ? { location: { directory } } : {}),
+        metadata: { courier: { parentID } },
+    })
+        .catch(async (error) => {
+        // No session will ever use the fresh worktree, and nothing records it, so it goes now.
+        if (directory)
+            await ports.worktree
+                .remove({ location: { directory: ports.directory }, directory, force: false })
+                .catch(() => undefined);
+        throw error;
+    });
+    // Recorded before the prompt, so a child that exists is on the roster even if prompting fails. A
+    // failed write must not keep the child from its task, so it is reported instead of thrown.
+    const rosterError = await record(ports.storage, {
+        sessionID: child.id,
+        parentID,
+        title,
+        directory: directory ?? child.location.directory,
+        isolated: directory !== undefined,
+        createdAt: ports.now(),
+        ...(directory ? { source: ports.directory } : {}),
+        ...(base ? { base } : {}),
+    }).then(() => undefined, (error) => describeFailure("roster", error).message);
+    await ports.session.prompt({ sessionID: child.id, text: childBrief(parentID, input.task) });
+    return {
+        sessionID: child.id,
+        directory: directory ?? child.location.directory,
+        ...(rosterError ? { rosterError } : {}),
+    };
+}
+/** Drops a message into another session's inbox; OpenCode wakes that session if it is idle. */
+export async function send(ports, from, input) {
+    const delivered = await ports.session.synthetic({
+        sessionID: input.sessionID,
+        text: envelope(from, input.message),
+        description: `Message from ${from}`,
+        metadata: { source: "courier", from },
+        delivery: input.queue ? "queue" : "steer",
+    });
+    return { messageID: delivered.id };
+}
+/** A one-off look at a session, for check-ins; not meant to be called in a loop. */
+export async function status(ports, input) {
+    const info = await ports.session.get({ sessionID: input.sessionID });
+    const messages = await ports.session.context({ sessionID: input.sessionID });
+    const last = messages.findLast((message) => message.type === "assistant");
+    const lastText = last?.type === "assistant"
+        ? last.content.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("")
+        : undefined;
+    return withoutUndefined({
+        sessionID: info.id,
+        title: info.title,
+        parentID: info.parentID,
+        outcome: info.outcome,
+        updated: info.time.updated,
+        idle: info.time.idle,
+        lastText,
+    });
+}
+/** The sessions a parent started, each with what courier_status reports, or the error it gave. */
+export async function listChildren(ports, parentID) {
+    const entries = await current(ports.storage, parentID, ports.now());
+    return Promise.all(entries.map(async (entry) => {
+        const roster = { directory: entry.directory, isolated: entry.isolated, created: entry.createdAt };
+        try {
+            return { ...(await status(ports, { sessionID: entry.sessionID })), ...roster };
+        }
+        catch (error) {
+            return {
+                sessionID: entry.sessionID,
+                title: entry.title,
+                ...roster,
+                error: describeFailure("courier_status", error).message,
+            };
+        }
+    }));
+}
+/** OpenCode leaves a tool call hanging when its metadata holds `undefined`, so results drop those keys. */
+function withoutUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}
+/** 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;
+    const message = (typeof tagged?.message === "string" && tagged.message) ||
+        [tagged?._tag, tagged?.sessionID].filter((item) => typeof item === "string").join(" ") ||
+        String(error);
+    return new Error(`${tool} failed: ${message}`);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { Plugin } from "@opencode-ai/plugin";
+declare const _default: Plugin.Plugin;
+export default _default;

package/dist/index.js

@@ -0,0 +1,284 @@
+import { Plugin } from "@opencode-ai/plugin";
+import { Schema } from "effect";
+import { randomUUID } from "node:crypto";
+import { describeFailure, listChildren, send, spawn, status } from "./courier.js";
+import { cleanup, headOf, inspectWorktree } from "./cleanup.js";
+import { cancel, deliverDue, schedule, TICK_MS } from "./later.js";
+import { pruneExpired } from "./roster.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(Schema.Number.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 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 = (globalThis[Symbol.for("opencode-courier.receiver")] ??= {});
+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();
+    const receiver = {
+        config,
+        instances,
+        server: (receivers.closing ?? Promise.resolve())
+            .then(() => listen(config, () => instances.values().next().value))
+            .then((server) => {
+            log(`courier webhook: listening on http://${config.host}:${server.address().port}`);
+            return server;
+        }, (error) => {
+            log(`courier webhook: cannot listen on ${config.host}:${config.port}: ${String(error)}`);
+            if (receivers.current === receiver)
+                receivers.current = undefined;
+            return undefined;
+        }),
+    };
+    return (receivers.current = receiver);
+}
+function joinReceiver(config, ports) {
+    const receiver = receivers.current ?? startReceiver(config, ports.log);
+    if (!sameSettings(receiver.config, config))
+        ports.log(`courier webhook: already running on ${receiver.config.host}:${receiver.config.port} with other settings ` +
+            "(port, host, secret or maxBytes); this location's are ignored. Set the webhook option once, in the global config.");
+    receiver.instances.add(ports);
+    return async () => {
+        receiver.instances.delete(ports);
+        if (receiver.instances.size > 0 || receivers.current !== receiver)
+            return;
+        receivers.current = undefined;
+        const closing = receiver.server.then((server) => new Promise((resolve) => {
+            if (!server)
+                return resolve();
+            server.closeAllConnections();
+            server.close(() => resolve());
+        }));
+        receivers.closing = closing;
+        await closing;
+        if (receivers.closing === closing)
+            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 = (globalThis[Symbol.for("opencode-courier.claimed")] ??=
+    new Set());
+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.`;
+}
+export default Plugin.define({
+    id: "courier",
+    setup: async (ctx) => {
+        const ports = {
+            session: ctx.session,
+            worktree: ctx.worktree,
+            storage: ctx.storage,
+            directory: ctx.location.directory,
+            now: Date.now,
+            head: headOf,
+        };
+        const cleanupPorts = { ...ports, inspect: inspectWorktree };
+        const later = {
+            storage: ctx.storage,
+            session: ctx.session,
+            now: Date.now,
+            newID: () => `later_${randomUUID()}`,
+            log: (message) => console.error(message),
+        };
+        const hooks = { storage: ctx.storage, session: ctx.session, now: Date.now, log: later.log };
+        let webhook;
+        try {
+            webhook = readConfig(ctx.options);
+        }
+        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. The session reports back with courier_send, " +
+                    "which wakes this session. DO NOT poll it or call courier_status in a loop; end your turn and wait. 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.${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_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 a check-in, end your turn, and cancel it with " +
+                    "courier_cancel if the child reports first. Survives server restarts; may arrive up to ~15 seconds late.",
+                input: LaterInput,
+                execute: async (input, context) => {
+                    const entry = await schedule(later, context.sessionID, input).catch(rethrow("courier_later"));
+                    const fireAt = new Date(entry.fireAt).toISOString();
+                    return {
+                        content: `Scheduled ${entry.id} for ${fireAt}, to ${entry.sessionID}. Cancel it with courier_cancel.`,
+                        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) => console.error(`courier roster prune: ${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));
+        };
+        void tick();
+        const timer = setInterval(tick, TICK_MS);
+        const leave = webhook ? joinReceiver(webhook, hooks) : undefined;
+        return async () => {
+            clearInterval(timer);
+            await leave?.();
+        };
+    },
+});

package/dist/later.d.ts

@@ -0,0 +1,39 @@
+import type { Plugin } from "@opencode-ai/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. */
+export declare const TICK_MS = 15000;
+export interface LaterEntry {
+    readonly id: string;
+    readonly sessionID: string;
+    readonly from: string;
+    readonly message: string;
+    readonly fireAt: number;
+    readonly createdAt: number;
+}
+export interface LaterPorts {
+    readonly storage: Storage;
+    readonly session: Pick<Context["session"], "synthetic">;
+    readonly now: () => number;
+    readonly newID: () => string;
+    readonly log: (message: string) => void;
+}
+export interface LaterInput {
+    readonly message: string;
+    readonly delayMinutes?: number;
+    readonly at?: string;
+    readonly sessionID?: string;
+}
+/** Stores a message for later delivery; the scheduler in `deliverDue` sends it once it is due. */
+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>;
+/**
+ * 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.
+ */
+export declare function deliverDue(ports: LaterPorts, claimed: Set<string>): Promise<void>;
+export {};

package/dist/later.js

@@ -0,0 +1,76 @@
+import { envelope } from "./courier.js";
+import { scanAll } from "./storage.js";
+/** How often each plugin instance looks for due messages; a delivery can be this late. */
+export const TICK_MS = 15_000;
+const PREFIX = "later/";
+function fireTime(now, input) {
+    if ((input.delayMinutes === undefined) === (input.at === undefined))
+        throw new Error("Give exactly one of delayMinutes or at.");
+    if (input.delayMinutes !== undefined) {
+        if (!Number.isFinite(input.delayMinutes) || input.delayMinutes < 0)
+            throw new Error("delayMinutes must be a number of minutes, zero or more.");
+        return now + Math.round(input.delayMinutes * 60_000);
+    }
+    const at = Date.parse(input.at);
+    if (Number.isNaN(at))
+        throw new Error(`at is not a date: ${input.at}`);
+    if (at < now)
+        throw new Error(`at is in the past: ${input.at}`);
+    return at;
+}
+/** Stores a message for later delivery; the scheduler in `deliverDue` sends it once it is due. */
+export async function schedule(ports, from, input) {
+    const now = ports.now();
+    const entry = {
+        id: ports.newID(),
+        sessionID: input.sessionID ?? from,
+        from,
+        message: input.message,
+        fireAt: fireTime(now, input),
+        createdAt: now,
+    };
+    await ports.storage.set(PREFIX + entry.id, { ...entry });
+    return entry;
+}
+/** Drops a pending message; false when there was none, e.g. it was already delivered. */
+export async function cancel(ports, id) {
+    if ((await ports.storage.get(PREFIX + id)) === undefined)
+        return false;
+    await ports.storage.remove(PREFIX + id);
+    return true;
+}
+function pending(ports) {
+    return scanAll(ports.storage, PREFIX);
+}
+/**
+ * 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.
+ */
+export async function deliverDue(ports, claimed) {
+    const now = ports.now();
+    for (const due of (await pending(ports)).filter((entry) => entry.fireAt <= now)) {
+        if (claimed.has(due.id))
+            continue;
+        claimed.add(due.id);
+        try {
+            if ((await ports.storage.get(PREFIX + due.id)) === undefined)
+                continue;
+            await ports.session
+                .synthetic({
+                sessionID: due.sessionID,
+                text: envelope(due.from, due.message, { scheduled: new Date(due.createdAt).toISOString() }),
+                description: `Scheduled message from ${due.from}`,
+                metadata: { source: "courier", from: due.from, scheduled: due.id },
+                delivery: "queue",
+            })
+                .catch((error) => ports.log(`courier_later ${due.id} to ${due.sessionID} not delivered: ${String(error)}`));
+            await ports.storage.remove(PREFIX + due.id);
+        }
+        finally {
+            claimed.delete(due.id);
+        }
+    }
+}

package/dist/roster.d.ts

@@ -0,0 +1,32 @@
+import { type Storage } 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 declare const RETENTION_MS: number;
+/** A session started with courier_spawn, recorded under the session that started it. */
+export interface RosterEntry {
+    readonly sessionID: string;
+    readonly parentID: string;
+    readonly title: string;
+    readonly directory: string;
+    readonly isolated: boolean;
+    readonly createdAt: number;
+    /** For an isolated child, the directory its worktree was made from; courier_cleanup removes it through there. */
+    readonly source?: string;
+    /** For an isolated child, the commit its worktree was made from; its own work is what came after. */
+    readonly base?: string;
+}
+export type RosterStorage = Storage;
+export declare function rosterKey(parentID: string, sessionID: string): string;
+export declare function record(storage: RosterStorage, entry: RosterEntry): Promise<void>;
+/** Removes a child from its parent's roster; false when it was not there. */
+export declare function forget(storage: RosterStorage, parentID: string, sessionID: string): Promise<boolean>;
+/** A parent's children, oldest first. */
+export declare function children(storage: RosterStorage, parentID: string): Promise<RosterEntry[]>;
+/** Whether a directory still exists; tests pass a fake. */
+export type Exists = (directory: string) => boolean;
+/** A parent's children, oldest first, after dropping the expired ones. */
+export declare function current(storage: RosterStorage, parentID: string, now: number, exists?: Exists): Promise<RosterEntry[]>;
+/** Drops expired entries of every parent, so parents that never list their children don't keep them forever. */
+export declare function pruneExpired(storage: RosterStorage, now: number, exists?: Exists): Promise<void>;

package/dist/roster.js

@@ -0,0 +1,44 @@
+import { existsSync } from "node:fs";
+import { scanAll } 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/";
+export function rosterKey(parentID, sessionID) {
+    return `${PREFIX}${parentID}/${sessionID}`;
+}
+export async function record(storage, entry) {
+    await storage.set(rosterKey(entry.parentID, entry.sessionID), { ...entry });
+}
+/** 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)
+        return false;
+    await storage.remove(key);
+    return true;
+}
+/** A parent's children, oldest first. */
+export async function children(storage, parentID) {
+    const entries = await scanAll(storage, `${PREFIX}${parentID}/`);
+    return entries.sort((a, b) => a.createdAt - b.createdAt);
+}
+/**
+ * Removes the given entries that were recorded more than `RETENTION_MS` before `now`, and returns
+ * the rest. An isolated child is kept while its worktree exists, so it can still be cleaned up.
+ */
+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))));
+    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. */
+export async function pruneExpired(storage, now, exists = existsSync) {
+    await dropExpired(storage, await scanAll(storage, PREFIX), now, exists);
+}

package/dist/storage.d.ts

@@ -0,0 +1,6 @@
+import type { Plugin } from "@opencode-ai/plugin";
+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[]>;
+export {};

package/dist/storage.js

@@ -0,0 +1,12 @@
+/** Every value stored under `prefix`, following the scan's pages. */
+export async function scanAll(storage, prefix) {
+    const values = [];
+    let after;
+    do {
+        const page = await storage.scan({ prefix, ...(after ? { after } : {}) });
+        for (const entry of page.entries)
+            values.push(entry.value);
+        after = page.next;
+    } while (after);
+    return values;
+}