opencode-courier 0.3.0 → 0.4.0

package/dist/tree/ports.d.ts

@@ -0,0 +1,276 @@
+/**
+ * The tree's ports, what it needs of the plugin context and of other modules, and the data types they and
+ * its texts take; those its pure rules take are declared in `domain.ts` and re-exported here.
+ */
+import type { Plugin } from "@opencode/plugin";
+import type { Status } from "../kernel/protocol.js";
+import type { Storage } from "../platform/storage.js";
+import type { Limits, Member, RosterEntry } from "./domain.js";
+export type { Artifacts, HeldReport, LeftMember, Limits, Member, RosterEntry, Standing } from "./domain.js";
+type Context = Plugin.Context;
+export type RosterStorage = Storage;
+/** How a session's wait for a report ended: it reported to its parent, or its turn failed or was interrupted. */
+export type Settled = "report" | "failed" | "interrupted";
+/** The notes kept of a spawned session's report state; docs/maintainers/architecture.md has each. */
+export type ReportField = "prompt" | "settled" | "progress" | "told" | "stopped";
+/** A report note as read: when it was made, and for `settled` how the wait ended and the report's status, as stored. */
+export interface ReportNote {
+    readonly at: number | undefined;
+    readonly by: unknown;
+    readonly status: unknown;
+}
+/** A stored value, as `Storage` gives and takes it. */
+export type Stored = Parameters<Storage["set"]>[1];
+/** The report keys found, by the session they are about. */
+export type ReportKeys = ReadonlyMap<string, ReadonlyArray<string>>;
+/**
+ * A spawned session as kept: its roster entry under its parent, the reverse index that finds it, and its report
+ * state, which go together. The reverse index is only an index: a session it does not name is looked for in the roster.
+ */
+export interface ChildStore {
+    /** Records a child under its parent, then indexes it; a failed index write is left to a scan and the next load. */
+    record(entry: RosterEntry): Promise<void>;
+    /** Removes a child's entry and, at once and best effort, its reverse key and report state; only the entry's removal can fail it. */
+    remove(parentID: string, sessionID: string): Promise<void>;
+    /** A session's roster entry under a parent, if it is there. */
+    entry(parentID: string, sessionID: string): Promise<RosterEntry | undefined>;
+    /** A parent's children, oldest first. */
+    children(parentID: string): Promise<RosterEntry[]>;
+    /** Every parent's children. */
+    all(): Promise<RosterEntry[]>;
+    /** A session's roster entries: one for the parent that started it, none if courier_spawn did not. */
+    entriesOf(sessionID: string): Promise<RosterEntry[]>;
+    /** The session that started a session, by the reverse index alone, without scanning the roster. */
+    indexedParent(sessionID: string): Promise<string | undefined>;
+    /** A session's roster entry, by the reverse index alone, without scanning the roster. */
+    indexedEntry(sessionID: string): Promise<RosterEntry | undefined>;
+    /**
+     * The roster entries from a session up to the top, its own first, ending with the entry whose parent
+     * courier_spawn did not start; empty when courier_spawn did not start the session.
+     */
+    lineage(sessionID: string): Promise<RosterEntry[]>;
+    /** `lineage` by the reverse index alone: empty, without scanning the roster, when it does not name the session. */
+    indexedLineage(sessionID: string): Promise<RosterEntry[]>;
+    /** Writes the reverse keys missing or stale for the given entries, the whole roster, and drops those whose entry is gone. */
+    backfill(entries: ReadonlyArray<RosterEntry>): Promise<void>;
+    /** The given notes of a session's report state, read at once. */
+    notes<F extends ReportField>(sessionID: string, fields: ReadonlyArray<F>): Promise<{
+        readonly [K in F]: ReportNote;
+    }>;
+    /** Notes that a prompt or message reached a spawned session at `at`, unless a later one is noted. */
+    prompted(sessionID: string, at: number): Promise<void>;
+    /** Notes how a spawned session's wait for a report ended at `at`, with its report's status, unless a later end is noted. */
+    settled(sessionID: string, by: Settled, at: number, status?: Status): Promise<void>;
+    /** Notes that a spawned session messaged its parent without a status at `at`, unless a later one is noted. */
+    progressed(sessionID: string, at: number): Promise<void>;
+    /** Notes that a spawned session's parent was told at `at` that a turn ended without a report, unless a later telling is noted. */
+    told(sessionID: string, at: number): Promise<void>;
+    /** Takes back the note `told` made at `at`; a later one stays, and one that cannot be read goes. */
+    untold(sessionID: string, at: number): Promise<void>;
+    /** Notes that courier_stop stopped a spawned session at `at`. */
+    stopped(sessionID: string, at: number): Promise<void>;
+    /** A `settled` or `progress` note as stored, for `restore` to put back. */
+    peek(sessionID: string, field: "settled" | "progress"): Promise<Stored | undefined>;
+    /** Puts back a note `peek` read; one that was not there is removed. */
+    restore(sessionID: string, field: "settled" | "progress", value: Stored | undefined): Promise<void>;
+    /** Drops a session's report state. */
+    forgetReport(sessionID: string): Promise<void>;
+    /** Every report key, by the session it is about. */
+    reported(): Promise<ReportKeys>;
+    /** Removes report keys `reported` found, each best effort. */
+    dropReported(keys: ReadonlyArray<string>): Promise<void>;
+}
+/** A member of a join group with where it is kept. */
+export interface Membership extends Member {
+    readonly parentID: string;
+    readonly group: string;
+    readonly sessionID: string;
+}
+/** The members of parents' join groups, each with its held report or how it left; a value that is not a member reads as none. */
+export interface GroupStore {
+    /** A session's member in a parent's group, if it is one. */
+    member(parentID: string, group: string, sessionID: string): Promise<Member | undefined>;
+    /** The members of every group. */
+    all(): Promise<Membership[]>;
+    /** The members of a parent's groups. */
+    ofParent(parentID: string): Promise<Membership[]>;
+    /** The members of one group. */
+    ofGroup(parentID: string, group: string): Promise<Membership[]>;
+    /** Writes a member in place of what was kept for it. */
+    put(parentID: string, group: string, sessionID: string, member: Member): Promise<void>;
+    /** Removes a member whatever it holds. */
+    remove(parentID: string, group: string, sessionID: string): Promise<void>;
+}
+/** A report held with its group: which group, and how many of its members have reported so far, when that could be read. */
+export interface Held {
+    readonly group: string;
+    readonly reported?: number;
+    readonly members?: number;
+}
+/**
+ * What courier_send did; `report` says whether the message was noted as the sender's report to the session
+ * that started it, and `held` that it was held with the sender's group rather than delivered, with no `messageID`.
+ */
+export interface Sent {
+    readonly messageID?: string;
+    readonly status?: Status;
+    readonly report?: boolean;
+    readonly held?: Held;
+}
+/** The slice of the plugin context the courier tools use; tests pass a fake. */
+export interface CourierPorts {
+    readonly session: Pick<Context["session"], "create" | "prompt" | "synthetic" | "get" | "context" | "interrupt">;
+    readonly agent: Pick<Context["agent"], "get">;
+    readonly worktree: Pick<Context["worktree"], "create" | "remove">;
+    /** The project of the plugin's location; an isolated child's worktree is made in it, and removed from it. */
+    readonly projectID: string;
+    /** The commit a directory's checkout is on, or undefined; recorded as an isolated child's base. */
+    readonly head: (directory: string) => Promise<string | undefined>;
+    /** Whether a directory's checkout has uncommitted changes, or undefined when git cannot tell. */
+    readonly dirty: (directory: string) => Promise<boolean | undefined>;
+    readonly storage: RosterStorage;
+    readonly directory: string;
+    readonly now: () => number;
+    /** The permission requests and questions a session waits on, wherever they are pending. */
+    readonly pending: (sessionID: string) => Promise<ReadonlyArray<Pending>>;
+    readonly limits: Limits;
+    /** The `nativeChildren` option: a child started without isolate is created with OpenCode's own `parentID`. */
+    readonly nativeChildren?: boolean;
+    readonly gate: SpawnGate;
+    /** The depths the `context` hook remembers; a parent's is dropped when it starts a child. */
+    readonly roles: Map<string, number | null>;
+    /** Has the scheduler deliver what is due now rather than at its next tick: a group a report has just completed. */
+    readonly nudge: () => void;
+    readonly log: (message: string) => void;
+}
+/** One question a session waits on, as `Pending` shows it; `person/`'s `Prompt` has these fields. */
+export interface PendingPrompt {
+    readonly question: string;
+    readonly header: string;
+    readonly options: ReadonlyArray<{
+        readonly label: string;
+        readonly description: string;
+    }>;
+    readonly multiple?: boolean;
+}
+/** A request a session waits on until someone answers it: a permission request, or a question it asked. */
+export type Pending = {
+    readonly type: "permission";
+    readonly requestID: string;
+    readonly action: string;
+    readonly resources: ReadonlyArray<string>;
+    readonly save?: ReadonlyArray<string>;
+} | {
+    readonly type: "question";
+    readonly requestID: string;
+    readonly questions: ReadonlyArray<PendingPrompt>;
+    /** Its question call was cut off; the answer reaches it as a message. */
+    readonly stopped?: true;
+};
+/** A spawn past its limit check: its parent, the top of its tree, and its child once created. */
+export interface Reservation {
+    readonly parentID: string;
+    readonly top: string;
+    sessionID?: string;
+}
+/**
+ * The spawns under way in the process, under a fixed process-wide key outside the hub, so spawns in
+ * other locations and copies count them; `turn` runs the limit checks one at a time.
+ */
+export interface SpawnGate {
+    readonly reserved: Set<Reservation>;
+    turn: Promise<unknown>;
+}
+export interface LimitPorts {
+    readonly storage: RosterStorage;
+    readonly session: Pick<Context["session"], "get">;
+    readonly limits: Limits;
+    readonly gate: SpawnGate;
+}
+/** What courier_cleanup did: removed the worktree, found it gone, kept it and why, or forgot a child with none; `group`, one it dropped the child from. */
+export type CleanupResult = {
+    readonly sessionID: string;
+    readonly directory: string;
+    readonly outcome: "removed" | "gone" | "forgotten";
+    readonly group?: string;
+} | {
+    readonly sessionID: string;
+    readonly directory: string;
+    readonly outcome: "kept";
+    readonly reason: string;
+    readonly changes: readonly string[];
+    readonly commits: readonly string[];
+};
+/** What would be lost by removing a worktree. */
+export interface WorktreeState {
+    /** Paths with uncommitted changes, untracked files included, as `git status --porcelain` lists them. */
+    readonly changes: readonly string[];
+    /**
+     * Commits reachable from the worktree's HEAD but from no branch, tag or remote-tracking ref, nor
+     * from the commit the worktree was made from, newest first.
+     */
+    readonly commits: readonly string[];
+}
+export interface CleanupPorts {
+    readonly storage: RosterStorage;
+    readonly worktree: Pick<Context["worktree"], "remove">;
+    /** The project of the plugin's location, for roster entries recorded before they carried their project. */
+    readonly projectID: string;
+    /** The worktree's state, or undefined when its directory no longer exists; `base` is the commit it was made from. */
+    readonly inspect: (directory: string, base?: string) => Promise<WorktreeState | undefined>;
+    /** When a member still out is dropped from its group. */
+    readonly now: () => number;
+    /** Has the scheduler deliver what is due now: a group the forgotten child may have been the last member out of. */
+    readonly nudge: () => void;
+}
+export interface StopPorts {
+    readonly courier: CourierPorts;
+    /** Cancels the messages scheduled for a session; the ids of those cancelled. */
+    readonly cancelScheduled: (sessionID: string) => Promise<ReadonlyArray<string>>;
+    readonly cleanup: CleanupPorts;
+}
+export interface GroupPorts {
+    readonly storage: Storage;
+    readonly session: Pick<Context["session"], "synthetic" | "get">;
+    readonly log: (message: string) => void;
+}
+/** The error of OpenCode's `session.execution.failed` event. */
+export interface ExecutionError {
+    readonly type: string;
+    readonly message: string;
+    readonly status?: number;
+}
+export interface WatchPorts {
+    readonly storage: RosterStorage;
+    /** `context` reads the last reply of a session that ended its turn without reporting. */
+    readonly session: Pick<Context["session"], "synthetic" | "context">;
+    readonly event: Pick<Context["event"], "subscribe">;
+    /** The permission domains of every loaded location, which the `Waits` suppliers ask; an isolated child's are in its worktree's. */
+    readonly permissions: () => Iterable<Pick<Context["permission"], "list">>;
+    /** The clock, in epoch milliseconds, for an event that carries no `created`. */
+    readonly now: () => number;
+    readonly log: (message: string) => void;
+    /** Has the scheduler deliver what is due now rather than at its next tick: a group completed, or its parent's turn ended. */
+    readonly nudge: () => void;
+}
+/**
+ * What every plugin instance in the process shares. Several subscriptions and copies see the same
+ * events, so each is claimed synchronously and handled once.
+ */
+export interface WatchState {
+    readonly seen: Set<string>;
+    /** The type of each item enqueued for a spawned session, by inbox id, for its delivery to look up. */
+    readonly inbox: Map<string, string>;
+}
+/**
+ * Whether a session waits, since `since`, on what the tree does not keep: asked by the silent-turn
+ * rule after the tree's own checks, through the watcher's ports; `src/index.ts` composes it.
+ */
+export type Waits = (ports: Pick<WatchPorts, "storage" | "permissions">, sessionID: string, since: number) => Promise<boolean>;
+export interface ContextPorts {
+    readonly storage: RosterStorage;
+    readonly limits: Limits;
+    /** Each session's depth once looked up: null for one nobody spawned that has started none, until it starts one. */
+    readonly roles: Map<string, number | null>;
+    readonly log: (message: string) => void;
+}

package/dist/tree/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/tree/report.d.ts

@@ -0,0 +1,23 @@
+import { type Status } from "../kernel/protocol.js";
+import type { ChildStore } from "./ports.js";
+type Notes = Pick<ChildStore, "notes">;
+/** Whether courier_stop stopped a session after its last prompt, or with none noted, at all. */
+export declare function stoppedSincePrompt(children: Notes, sessionID: string): Promise<boolean>;
+/** The status of a spawned session's last report to its parent, if it has reported with one. */
+export declare function lastStatus(children: Notes, sessionID: string): Promise<Status | undefined>;
+/**
+ * What is known of a spawned session's report: when a prompt last reached it, and whether since then it owes one, has
+ * messaged its parent without a status, or failed or was interrupted. Undefined for one spawned before this was kept.
+ */
+export declare function reportOf(children: Notes, sessionID: string): Promise<{
+    prompt: number;
+    owes: boolean;
+    progressed: boolean;
+    ended: boolean;
+} | undefined>;
+/**
+ * Whether its parent still waits on a spawned session's report: it owes one, and the parent has not
+ * been told since its last prompt that it ended a turn without one.
+ */
+export declare function awaited(children: Notes, sessionID: string): Promise<boolean>;
+export {};

package/dist/tree/report.js

@@ -0,0 +1,33 @@
+import { isStatus } from "../kernel/protocol.js";
+/** Whether `at` is known and no earlier than the prompt at `prompt`. */
+const since = (at, prompt) => at !== undefined && at >= prompt;
+/** Whether courier_stop stopped a session after its last prompt, or with none noted, at all. */
+export async function stoppedSincePrompt(children, sessionID) {
+    const { stopped, prompt } = await children.notes(sessionID, ["stopped", "prompt"]);
+    return stopped.at !== undefined && (prompt.at === undefined || stopped.at >= prompt.at);
+}
+/** The status of a spawned session's last report to its parent, if it has reported with one. */
+export async function lastStatus(children, sessionID) {
+    const { status } = (await children.notes(sessionID, ["settled"])).settled;
+    return isStatus(status) ? status : undefined;
+}
+/**
+ * What is known of a spawned session's report: when a prompt last reached it, and whether since then it owes one, has
+ * messaged its parent without a status, or failed or was interrupted. Undefined for one spawned before this was kept.
+ */
+export async function reportOf(children, sessionID) {
+    const { prompt, settled, progress } = await children.notes(sessionID, ["prompt", "settled", "progress"]);
+    const promptAt = prompt.at;
+    if (promptAt === undefined)
+        return undefined;
+    const done = since(settled.at, promptAt);
+    return { prompt: promptAt, owes: !done, progressed: since(progress.at, promptAt), ended: done && settled.by !== "report" };
+}
+/**
+ * Whether its parent still waits on a spawned session's report: it owes one, and the parent has not
+ * been told since its last prompt that it ended a turn without one.
+ */
+export async function awaited(children, sessionID) {
+    const { prompt, settled, told } = await children.notes(sessionID, ["prompt", "settled", "told"]);
+    return prompt.at !== undefined && !since(settled.at, prompt.at) && !since(told.at, prompt.at);
+}

package/dist/tree/roster.d.ts

@@ -0,0 +1,27 @@
+import type { RosterEntry, RosterStorage } from "./ports.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;
+/** Every parent's children. */
+export declare function allEntries(storage: RosterStorage): Promise<RosterEntry[]>;
+/**
+ * The roster entries from a session up to the top, its own first, ending with the entry whose parent
+ * courier_spawn did not start; empty when courier_spawn did not start the session.
+ */
+export declare function lineage(storage: RosterStorage, sessionID: string): Promise<RosterEntry[]>;
+/**
+ * The top of a spawned session's lineage, where its permission requests and questions go, since the
+ * person is there. Throws unless the session was spawned and `callerID` is that top; `what` names it.
+ */
+export declare function answeringTop(storage: RosterStorage, sessionID: string, callerID: string, what: string): Promise<string>;
+/** 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[]>;
+/**
+ * On loading: drops expired entries of every parent, then brings the reverse index in line with
+ * what is left (`backfill`) and drops report state with no entry (`dropOrphanedReports`).
+ */
+export declare function pruneExpired(storage: RosterStorage, now: number, exists?: Exists): Promise<void>;

package/dist/tree/roster.js

@@ -0,0 +1,62 @@
+import { existsSync } from "node:fs";
+import { forgetChild, forgetReports } from "./forget.js";
+import { childStore } from "./store.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;
+/** Every parent's children. */
+export async function allEntries(storage) {
+    return childStore(storage).all();
+}
+/**
+ * The roster entries from a session up to the top, its own first, ending with the entry whose parent
+ * courier_spawn did not start; empty when courier_spawn did not start the session.
+ */
+export async function lineage(storage, sessionID) {
+    return childStore(storage).lineage(sessionID);
+}
+/**
+ * The top of a spawned session's lineage, where its permission requests and questions go, since the
+ * person is there. Throws unless the session was spawned and `callerID` is that top; `what` names it.
+ */
+export async function answeringTop(storage, sessionID, callerID, what) {
+    const chain = await lineage(storage, sessionID);
+    if (!chain.length)
+        throw new Error(`${sessionID} was not started with courier_spawn, so courier_answer cannot answer for it.`);
+    const top = chain.at(-1).parentID;
+    if (top !== callerID)
+        throw new Error(`${sessionID}'s ${what} go to ${top}, the session at the top of the sessions started from it with courier_spawn; ${callerID} cannot answer them.`);
+    return top;
+}
+/**
+ * Forgets 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) => forgetChild(storage, entry.parentID, entry.sessionID, entry.group)));
+    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 childStore(storage).children(parentID), now, exists);
+}
+/**
+ * On loading: drops expired entries of every parent, then brings the reverse index in line with
+ * what is left (`backfill`) and drops report state with no entry (`dropOrphanedReports`).
+ */
+export async function pruneExpired(storage, now, exists = existsSync) {
+    const children = childStore(storage);
+    // Report keys are read before the roster: courier_spawn writes a child's entry before its first
+    // report key, so a session seen here that spawns during the sweep has its entry in the read below.
+    const reported = await children.reported().catch(() => new Map());
+    const entries = await dropExpired(storage, await children.all(), now, exists);
+    await Promise.all([children.backfill(entries), dropOrphanedReports(storage, reported, entries)]);
+}
+/** Removes the report keys read of sessions that have no roster entry. */
+async function dropOrphanedReports(storage, reported, entries) {
+    const sessions = new Set(entries.map((entry) => entry.sessionID));
+    await forgetReports(storage, reported, [...reported.keys()].filter((sessionID) => !sessions.has(sessionID)));
+}

package/dist/tree/rpc-handlers.d.ts

@@ -0,0 +1,201 @@
+import type { Plugin } from "@opencode/plugin";
+import type { StopPorts } from "./ports.js";
+/** Serves the tree's RPC at the plugin's location, through the same use cases as the tools; disposed with the plugin. */
+export declare function registerTreeRpc(rpc: Pick<Plugin.Context["rpc"], "register">, ports: StopPorts): Promise<import("@opencode/plugin/promise/rpc").RpcRegistration<{
+    readonly id: "courier";
+    readonly methods: {
+        readonly summary: {
+            readonly input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly sessionID: string;
+            }, {
+                readonly sessionID: string;
+            }> & import("effect/Schema").Struct<{
+                readonly sessionID: import("effect/Schema").String;
+            }>;
+            readonly output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly running: number;
+                readonly idle: number;
+                readonly groups: readonly {
+                    readonly name: string;
+                    readonly reported: number;
+                    readonly members: number;
+                }[];
+                readonly waiting: number;
+                readonly truncated?: number | undefined;
+            }, {
+                readonly running: number;
+                readonly idle: number;
+                readonly groups: readonly {
+                    readonly name: string;
+                    readonly reported: number;
+                    readonly members: number;
+                }[];
+                readonly waiting: number;
+                readonly truncated?: number | undefined;
+            }> & import("effect/Schema").Struct<{
+                readonly running: import("effect/Schema").Int;
+                readonly waiting: import("effect/Schema").Int;
+                readonly idle: import("effect/Schema").Int;
+                readonly groups: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+                    readonly name: import("effect/Schema").String;
+                    readonly reported: import("effect/Schema").Int;
+                    readonly members: import("effect/Schema").Int;
+                }>>;
+                readonly truncated: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
+            }>;
+        };
+        readonly tree: {
+            readonly input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly sessionID: string;
+            }, {
+                readonly sessionID: string;
+            }> & import("effect/Schema").Struct<{
+                readonly sessionID: import("effect/Schema").String;
+            }>;
+            readonly output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly rows: readonly {
+                    readonly sessionID: string;
+                    readonly title: string;
+                    readonly parentID: string;
+                    readonly depth: number;
+                    readonly created: number;
+                    readonly isolated: boolean;
+                    readonly state: "running" | "idle" | "gone" | "waiting";
+                    readonly waits: readonly ({
+                        readonly type: "permission";
+                        readonly action: string;
+                        readonly resources: readonly string[];
+                    } | {
+                        readonly type: "question";
+                        readonly question: string;
+                    })[];
+                    readonly group?: {
+                        readonly name: string;
+                        readonly standing: string;
+                    } | undefined;
+                    readonly idle?: number | undefined;
+                    readonly report?: {
+                        readonly progressed: boolean;
+                        readonly state: "reported" | "ended" | "owed";
+                        readonly status?: string | undefined;
+                    } | undefined;
+                    readonly outcome?: "failed" | "interrupted" | "succeeded" | undefined;
+                    readonly tool?: {
+                        readonly name: string;
+                        readonly at: number;
+                    } | undefined;
+                    readonly cost?: number | undefined;
+                }[];
+                readonly truncated?: number | undefined;
+            }, {
+                readonly rows: readonly {
+                    readonly sessionID: string;
+                    readonly title: string;
+                    readonly parentID: string;
+                    readonly depth: number;
+                    readonly created: number;
+                    readonly isolated: boolean;
+                    readonly state: "running" | "idle" | "gone" | "waiting";
+                    readonly waits: readonly ({
+                        readonly type: "permission";
+                        readonly action: string;
+                        readonly resources: readonly string[];
+                    } | {
+                        readonly type: "question";
+                        readonly question: string;
+                    })[];
+                    readonly group?: {
+                        readonly name: string;
+                        readonly standing: string;
+                    } | undefined;
+                    readonly idle?: number | undefined;
+                    readonly report?: {
+                        readonly progressed: boolean;
+                        readonly state: "reported" | "ended" | "owed";
+                        readonly status?: string | undefined;
+                    } | undefined;
+                    readonly outcome?: "failed" | "interrupted" | "succeeded" | undefined;
+                    readonly tool?: {
+                        readonly name: string;
+                        readonly at: number;
+                    } | undefined;
+                    readonly cost?: number | undefined;
+                }[];
+                readonly truncated?: number | undefined;
+            }> & import("effect/Schema").Struct<{
+                readonly rows: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+                    readonly sessionID: import("effect/Schema").String;
+                    readonly parentID: import("effect/Schema").String;
+                    readonly title: import("effect/Schema").String;
+                    readonly depth: import("effect/Schema").Int;
+                    readonly state: import("effect/Schema").Literals<readonly ["running", "waiting", "idle", "gone"]>;
+                    readonly outcome: import("effect/Schema").optionalKey<import("effect/Schema").Literals<readonly ["succeeded", "failed", "interrupted"]>>;
+                    readonly report: import("effect/Schema").optionalKey<import("effect/Schema").Struct<{
+                        readonly state: import("effect/Schema").Literals<readonly ["owed", "reported", "ended"]>;
+                        readonly status: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                        readonly progressed: import("effect/Schema").Boolean;
+                    }>>;
+                    readonly group: import("effect/Schema").optionalKey<import("effect/Schema").Struct<{
+                        readonly name: import("effect/Schema").String;
+                        readonly standing: import("effect/Schema").String;
+                    }>>;
+                    readonly isolated: import("effect/Schema").Boolean;
+                    readonly created: import("effect/Schema").Number;
+                    readonly idle: import("effect/Schema").optionalKey<import("effect/Schema").Number>;
+                    readonly cost: import("effect/Schema").optionalKey<import("effect/Schema").Number>;
+                    readonly tool: import("effect/Schema").optionalKey<import("effect/Schema").Struct<{
+                        readonly name: import("effect/Schema").String;
+                        readonly at: import("effect/Schema").Number;
+                    }>>;
+                    readonly waits: import("effect/Schema").$Array<import("effect/Schema").Union<readonly [import("effect/Schema").Struct<{
+                        readonly type: import("effect/Schema").Literal<"permission">;
+                        readonly action: import("effect/Schema").String;
+                        readonly resources: import("effect/Schema").$Array<import("effect/Schema").String>;
+                    }>, import("effect/Schema").Struct<{
+                        readonly type: import("effect/Schema").Literal<"question">;
+                        readonly question: import("effect/Schema").String;
+                    }>]>>;
+                }>>;
+                readonly truncated: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
+            }>;
+        };
+        readonly stop: {
+            readonly input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly sessionID: string;
+                readonly by: string;
+            }, {
+                readonly sessionID: string;
+                readonly by: string;
+            }> & import("effect/Schema").Struct<{
+                readonly sessionID: import("effect/Schema").String;
+                readonly by: import("effect/Schema").String;
+            }>;
+            readonly output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly stopped: readonly {
+                    readonly sessionID: string;
+                    readonly title: string;
+                    readonly outcome: string;
+                }[];
+                readonly cancelled: number;
+            }, {
+                readonly stopped: readonly {
+                    readonly sessionID: string;
+                    readonly title: string;
+                    readonly outcome: string;
+                }[];
+                readonly cancelled: number;
+            }> & import("effect/Schema").Struct<{
+                readonly stopped: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+                    readonly sessionID: import("effect/Schema").String;
+                    readonly title: import("effect/Schema").String;
+                    readonly outcome: import("effect/Schema").String;
+                }>>;
+                readonly cancelled: import("effect/Schema").Int;
+            }>;
+            readonly errors: {
+                readonly refused: import("effect/StandardSchema").StandardSchemaV1<{}, {}> & import("effect/Schema").Struct<{}>;
+            };
+        };
+    };
+    readonly events: {};
+}>>;

package/dist/tree/rpc-handlers.js

@@ -0,0 +1,20 @@
+import { panel } from "./panel.js";
+import { treeRpc } from "./rpc.js";
+import { stop } from "./stop.js";
+import { summary } from "./summary.js";
+/** Serves the tree's RPC at the plugin's location, through the same use cases as the tools; disposed with the plugin. */
+export function registerTreeRpc(rpc, ports) {
+    return rpc.register(treeRpc, {
+        summary: ({ sessionID }) => summary(ports.courier, sessionID),
+        tree: ({ sessionID }) => panel(ports.courier, sessionID),
+        stop: async ({ sessionID, by }, { error }) => {
+            try {
+                const { stopped, cancelled } = await stop(ports, by, { sessionID });
+                return { stopped: stopped.map(({ sessionID, title, outcome }) => ({ sessionID, title, outcome })), cancelled: cancelled.length };
+            }
+            catch (cause) {
+                return error("refused", cause instanceof Error ? cause.message : String(cause), {});
+            }
+        },
+    });
+}