opencode-courier 0.2.2 → 0.3.0

package/dist/tools.d.ts

@@ -0,0 +1,94 @@
+import type { Plugin } from "@opencode/plugin";
+import { Schema } from "effect";
+import { type CleanupPorts } from "./cleanup.js";
+import { type StopPorts } from "./stop.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>;
+    readonly group: Schema.optional<Schema.String>;
+}>;
+export declare const SendInput: Schema.Struct<{
+    readonly sessionID: Schema.String;
+    readonly message: Schema.String;
+    readonly status: Schema.optional<Schema.Literals<readonly ["done", "partial", "blocked", "failed"]>>;
+    readonly artifacts: Schema.optional<Schema.Struct<{
+        readonly branch: Schema.optional<Schema.String>;
+        readonly commits: Schema.optional<Schema.$Array<Schema.String>>;
+        readonly files: Schema.optional<Schema.$Array<Schema.String>>;
+        readonly checks: Schema.optional<Schema.$Array<Schema.Struct<{
+            readonly command: Schema.String;
+            readonly result: 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 TreeInput: Schema.Struct<{
+    readonly sessionID: Schema.optional<Schema.String>;
+}>;
+export declare const StopInput: Schema.Struct<{
+    readonly sessionID: Schema.String;
+    readonly cleanup: Schema.optional<Schema.Boolean>;
+}>;
+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 stop: StopPorts;
+    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,297 @@
+import { Schema } from "effect";
+import { cleanup } from "./cleanup.js";
+import { stop } from "./stop.js";
+import { tree } from "./tree.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, STATUSES, statusText, stopText, subscribeText, treeText, 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. From a session that is itself " +
+            "isolated, the worktree starts from your current commit, not your uncommitted changes: commit first. The session " +
+            "commits on a branch named courier/<its session ID> and names it in its report; merge that branch yourself.",
+    })),
+    group: Schema.optional(Schema.String.annotate({
+        description: "A join group: start the sessions of one batch with the same name, and their reports are held and delivered " +
+            "to you in one message once every one of them has reported and your turn has ended, instead of one turn per " +
+            "report. A blocked report, a question, a permission request or a failed turn still reaches you at once. Letters, " +
+            "digits, dots, dashes and underscores, up to 60; the name is free again once the group has been delivered.",
+    })),
+});
+export const SendInput = Schema.Struct({
+    sessionID: Schema.String.annotate({ description: "The session to deliver to." }),
+    message: Schema.String.annotate({ description: "The message text." }),
+    status: Schema.optional(Schema.Literals(STATUSES).annotate({
+        description: "For a report to the session that started you: done, partial (some of the task is left), blocked (you need a " +
+            "decision from it; say what) or failed. A message without a status is progress, not your report.",
+    })),
+    artifacts: Schema.optional(Schema.Struct({
+        branch: Schema.optional(Schema.String.annotate({ description: "The branch your work is on." })),
+        commits: Schema.optional(Schema.Array(Schema.String).annotate({ description: "The commits you made, as short hashes or subjects." })),
+        files: Schema.optional(Schema.Array(Schema.String).annotate({ description: "The files you changed." })),
+        checks: Schema.optional(Schema.Array(Schema.Struct({
+            command: Schema.String.annotate({ description: "A command you ran, such as a test suite or a linter." }),
+            result: Schema.String.annotate({ description: "What it gave, in a few words." }),
+        })).annotate({ description: "The checks you ran and their results." })),
+    }).annotate({ description: "With a report: what you produced, listed in the message after your text in a fixed layout." })),
+    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 TreeInput = Schema.Struct({
+    sessionID: Schema.optional(Schema.String.annotate({ description: "The session whose subtree to list; defaults to this one." })),
+});
+export const StopInput = Schema.Struct({
+    sessionID: Schema.String.annotate({ description: "The session to stop, with every session under it. It must have been started, directly or through others, from this one." }),
+    cleanup: Schema.optional(Schema.Boolean.annotate({
+        description: "Also remove the worktrees of the stopped sessions that ran in one of their own, as courier_cleanup does: " +
+            "one with uncommitted changes or commits on no branch is kept and listed.",
+    })),
+});
+export const CleanupInput = Schema.Struct({
+    sessionID: Schema.String.annotate({ description: "The session you started to drop, with its worktree if it is isolated." }),
+    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 or ends without a report " +
+            "instead, it waits for a permission or it asks a question. Give a batch of parallel sessions one group name to " +
+            "be woken once, with all their reports, instead of once per report. 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, or each group's reports, 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, with a status (done, partial, blocked or failed) and " +
+            "the artifacts you produced, or to steer a session you started. The status is carried as an attribute of the " +
+            "message; without one, a message to the session that started you is progress, not your report. If you were " +
+            "started in a group, a report with status done, partial or failed is held and delivered with the group's other " +
+            "reports; the result says so, and nothing more is needed from you.",
+        input: SendInput,
+        execute: async (input, context) => {
+            const delivered = await send(ports.courier, context.sessionID, input).catch(rethrow("courier_send"));
+            return { content: sendText(input.sessionID, delivered), 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, and for one " +
+            "started in a group, its group and whether its report is held, still out, or released, 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_tree",
+        options: { codemode: false },
+        description: "List the whole tree of sessions under this one (or under sessionID): every session started with courier_spawn " +
+            "from it, directly or through others, each with its depth, what courier_children shows, and whether it still " +
+            "owes a report, sent progress, or ended without one. For a one-off look, not for waiting; long trees are cut at maxTotal sessions.",
+        input: TreeInput,
+        execute: async (input, context) => {
+            const result = await tree(ports.courier, input.sessionID || context.sessionID).catch(rethrow("courier_tree"));
+            return { content: treeText(result), metadata: result };
+        },
+    });
+    tools.add({
+        name: "courier_stop",
+        options: { codemode: false },
+        description: "Stop a session you started, directly or through others, and every session under it: each running turn is " +
+            "interrupted, deepest first, and the messages scheduled for them with courier_later are cancelled. Use it when a " +
+            "subtree went wrong or is no longer needed. They do not report back, and you are not told of what you stopped; a " +
+            "session between you and the target is. A stopped session can be woken again with courier_send. With " +
+            "cleanup: true their worktrees are removed too, unless they hold work that is on no branch.",
+        input: StopInput,
+        execute: async (input, context) => {
+            const result = await stop(ports.stop, context.sessionID, input).catch(rethrow("courier_stop"));
+            return { content: stopText(result), metadata: result };
+        },
+    });
+    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. A session without " +
+            "isolate has no worktree and is only dropped from courier_children. Either way, one in a join group that has not " +
+            "reported is dropped from it, so the group's other reports reach you without it; use this for a member you no " +
+            "longer need a report from.",
+        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/tree.d.ts

@@ -0,0 +1,102 @@
+import { type CourierPorts } from "./courier.js";
+import { type RosterEntry, type RosterStorage } from "./roster.js";
+/** A session below the one a subtree is read from, with how many levels below it is: a child is at depth 1. */
+export interface Below {
+    readonly entry: RosterEntry;
+    readonly depth: number;
+}
+/**
+ * The sessions started from a session, directly or through others, read one prefix scan per parent, at most `max`
+ * (`truncated` if more), in the order a tree is drawn.
+ */
+export declare function subtree(storage: RosterStorage, rootID: string, max?: number): Promise<{
+    nodes: Below[];
+    truncated: boolean;
+}>;
+/**
+ * The subtree under a session, at most `maxTotal` sessions: what courier_children shows of each, plus its depth,
+ * its parent and its report state.
+ */
+export declare function tree(ports: CourierPorts, rootID: string): Promise<{
+    truncated?: number | undefined;
+    sessionID: string;
+    sessions: ({
+        report?: {
+            status?: "done" | "partial" | "blocked" | "failed" | undefined;
+            owes: boolean;
+            progressed: boolean;
+            ended: boolean;
+        } | undefined;
+        parentID: string;
+        depth: number;
+        group: {
+            name: string;
+            report: string;
+        };
+        directory: string;
+        isolated: boolean;
+        created: number;
+        sessionID?: string | undefined;
+        title?: string | undefined;
+        outcome?: "failed" | "interrupted" | "succeeded" | undefined;
+        updated?: number | undefined;
+        idle?: number | undefined;
+        lastText?: string | undefined;
+        pending?: readonly import("./courier.js").Pending[] | undefined;
+    } | {
+        report?: {
+            status?: "done" | "partial" | "blocked" | "failed" | undefined;
+            owes: boolean;
+            progressed: boolean;
+            ended: boolean;
+        } | undefined;
+        parentID: string;
+        depth: number;
+        group?: undefined;
+        directory: string;
+        isolated: boolean;
+        created: number;
+        sessionID?: string | undefined;
+        title?: string | undefined;
+        outcome?: "failed" | "interrupted" | "succeeded" | undefined;
+        updated?: number | undefined;
+        idle?: number | undefined;
+        lastText?: string | undefined;
+        pending?: readonly import("./courier.js").Pending[] | undefined;
+    } | {
+        report?: {
+            status?: "done" | "partial" | "blocked" | "failed" | undefined;
+            owes: boolean;
+            progressed: boolean;
+            ended: boolean;
+        } | undefined;
+        parentID: string;
+        depth: number;
+        error: string;
+        group: {
+            name: string;
+            report: string;
+        };
+        directory: string;
+        isolated: boolean;
+        created: number;
+        sessionID: string;
+        title: string;
+    } | {
+        report?: {
+            status?: "done" | "partial" | "blocked" | "failed" | undefined;
+            owes: boolean;
+            progressed: boolean;
+            ended: boolean;
+        } | undefined;
+        parentID: string;
+        depth: number;
+        error: string;
+        group?: undefined;
+        directory: string;
+        isolated: boolean;
+        created: number;
+        sessionID: string;
+        title: string;
+    })[];
+}>;

package/dist/tree.js

@@ -0,0 +1,58 @@
+import { described } from "./courier.js";
+import { lastStatus, reportOf } from "./report.js";
+import { children } from "./roster.js";
+/**
+ * The sessions started from a session, directly or through others, read one prefix scan per parent, at most `max`
+ * (`truncated` if more), in the order a tree is drawn.
+ */
+export async function subtree(storage, rootID, max = Number.POSITIVE_INFINITY) {
+    const byParent = new Map();
+    const seen = new Set([rootID]);
+    let truncated = false;
+    const expand = async (level, depth) => {
+        if (!level.length || truncated)
+            return;
+        const found = await Promise.all(level.map((parentID) => children(storage, parentID)));
+        const next = [];
+        for (const [index, entries] of found.entries()) {
+            const fresh = entries.filter((entry) => !seen.has(entry.sessionID));
+            const kept = fresh.slice(0, Math.max(0, max - (seen.size - 1)));
+            truncated ||= kept.length < fresh.length;
+            for (const entry of kept)
+                seen.add(entry.sessionID);
+            if (kept.length)
+                byParent.set(level[index], kept.map((entry) => ({ entry, depth })));
+            next.push(...kept.map((entry) => entry.sessionID));
+        }
+        return expand(next, depth + 1);
+    };
+    await expand([rootID], 1);
+    return { nodes: drawn(byParent, rootID), truncated };
+}
+/** The nodes in the order a tree is drawn: each followed by what it started. */
+function drawn(byParent, parentID) {
+    return (byParent.get(parentID) ?? []).flatMap((node) => [node, ...drawn(byParent, node.entry.sessionID)]);
+}
+/**
+ * The subtree under a session, at most `maxTotal` sessions: what courier_children shows of each, plus its depth,
+ * its parent and its report state.
+ */
+export async function tree(ports, rootID) {
+    const { nodes, truncated } = await subtree(ports.storage, rootID, ports.limits.maxTotal);
+    const listed = await Promise.all(nodes.map(async ({ entry, depth }) => {
+        const [info, report, last] = await Promise.all([
+            described(ports, entry),
+            reportOf(ports.storage, entry.sessionID).catch(() => undefined),
+            lastStatus(ports.storage, entry.sessionID).catch(() => undefined),
+        ]);
+        return {
+            ...info,
+            parentID: entry.parentID,
+            depth,
+            ...(report
+                ? { report: { owes: report.owes, progressed: report.progressed, ended: report.ended, ...(last ? { status: last } : {}) } }
+                : {}),
+        };
+    }));
+    return { sessionID: rootID, sessions: listed, ...(truncated ? { truncated: ports.limits.maxTotal } : {}) };
+}

package/dist/version.d.ts

@@ -5,18 +5,12 @@ export interface BuiltVersions {
     readonly opencode: string;
 }
 /**
- * Reads the versions from the package's own package.json, which sits next to `dist/` in the
- * published package as it does next to `src/` in the repository: `version`, and the exact
- * `@opencode/plugin` version under devDependencies, the one installed for the build and both test
- * suites; the peer dependency names the same exact version, as the copy of the plugin API that
- * `opencode plugin add` installs next to the plugin. Throws when the file cannot be read or does
- * not hold both.
+ * Reads from the package's own package.json, next to `dist/` as to `src/`: `version` and the exact
+ * `@opencode/plugin` devDependency version, which the peer repeats. Throws if either is missing.
  */
 export declare function builtVersions(): BuiltVersions;
 /**
- * The line for the server log when the running OpenCode is not the one the plugin was built
- * against; undefined when it is. Logged once per plugin load, never in a tool result. An OpenCode
- * whose plugin context does not report a version, as one from before the pinned API or after a
- * change to it may not, is the case the line is for, so it still names the pin then.
+ * The server-log line for an OpenCode other than the plugin was built against, undefined when it is;
+ * logged once per load, never in a tool result. A context without a version is still told the pin.
  */
 export declare function versionNotice(built: BuiltVersions, app: Partial<Pick<App, "version" | "channel">> | undefined): string | undefined;

package/dist/version.js

@@ -1,12 +1,8 @@
 import { readFileSync } from "node:fs";
 const README_TABLE = "https://github.com/ivopogace/opencode-courier#supported-opencode-version";
 /**
- * Reads the versions from the package's own package.json, which sits next to `dist/` in the
- * published package as it does next to `src/` in the repository: `version`, and the exact
- * `@opencode/plugin` version under devDependencies, the one installed for the build and both test
- * suites; the peer dependency names the same exact version, as the copy of the plugin API that
- * `opencode plugin add` installs next to the plugin. Throws when the file cannot be read or does
- * not hold both.
+ * Reads from the package's own package.json, next to `dist/` as to `src/`: `version` and the exact
+ * `@opencode/plugin` devDependency version, which the peer repeats. Throws if either is missing.
  */
 export function builtVersions() {
     const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
@@ -19,10 +15,8 @@ export function builtVersions() {
     return { plugin, opencode };
 }
 /**
- * The line for the server log when the running OpenCode is not the one the plugin was built
- * against; undefined when it is. Logged once per plugin load, never in a tool result. An OpenCode
- * whose plugin context does not report a version, as one from before the pinned API or after a
- * change to it may not, is the case the line is for, so it still names the pin then.
+ * The server-log line for an OpenCode other than the plugin was built against, undefined when it is;
+ * logged once per load, never in a tool result. A context without a version is still told the pin.
  */
 export function versionNotice(built, app) {
     const version = typeof app?.version === "string" ? app.version : undefined;