opencode-courier 0.2.3 → 0.4.0

package/dist/tree/store.js

@@ -0,0 +1,264 @@
+import { num, obj, str } from "../platform/json.js";
+import { isStatus } from "../kernel/protocol.js";
+import { scanAll, scanEntries } from "../platform/storage.js";
+import { lineageIn } from "./domain.js";
+// The tree's storage: the only file that knows its keys and layouts. Older copies and a second server on the same data
+// directory read and write the same keys, so a key or a stored value never changes shape.
+const PREFIX = "roster/";
+/**
+ * The reverse index: a child's `ReverseEntry` under `roster-by-child/<sessionID>`, written with its
+ * roster entry; only an index, so `roster/` is scanned for entries lacking one, and confirms a hit.
+ */
+const BY_CHILD = "roster-by-child/";
+export function rosterKey(parentID, sessionID) {
+    return `${PREFIX}${parentID}/${sessionID}`;
+}
+export function reverseKey(sessionID) {
+    return `${BY_CHILD}${sessionID}`;
+}
+/**
+ * Whether a spawned session has reported since its last prompt, under `report/<sessionID>/`: `prompt`, `settled` (with
+ * the report's status), `progress` (a message to its parent without a status) and `told`; docs/maintainers/architecture.md has each.
+ */
+const REPORT_PREFIX = "report/";
+export const promptKey = (sessionID) => `${REPORT_PREFIX}${sessionID}/prompt`;
+export const settledKey = (sessionID) => `${REPORT_PREFIX}${sessionID}/settled`;
+export const progressKey = (sessionID) => `${REPORT_PREFIX}${sessionID}/progress`;
+export const toldKey = (sessionID) => `${REPORT_PREFIX}${sessionID}/told`;
+export const stoppedKey = (sessionID) => `${REPORT_PREFIX}${sessionID}/stopped`;
+const REPORT_KEYS = {
+    prompt: promptKey,
+    settled: settledKey,
+    progress: progressKey,
+    told: toldKey,
+    stopped: stoppedKey,
+};
+/**
+ * Join groups: each member of a parent's group under `group/<parentID>/<name>/<sessionID>`, with its
+ * held report or how it left; released and dropped once none is out. docs/maintainers/architecture.md, § Storage.
+ */
+const GROUP_PREFIX = "group/";
+export const memberKey = (parentID, group, sessionID) => `${GROUP_PREFIX}${parentID}/${group}/${sessionID}`;
+/** The key prefix of a parent's groups, and of one group's members. */
+export const groupsPrefix = (parentID) => `${GROUP_PREFIX}${parentID}/`;
+export const groupPrefix = (parentID, group) => `${groupsPrefix(parentID)}${group}/`;
+function isReverse(value) {
+    const ancestors = value?.ancestors;
+    return Array.isArray(ancestors) && ancestors.length > 0 && ancestors.every((id) => typeof id === "string");
+}
+/** Whether a reverse key's value leads to this entry. */
+function indexes(value, entry) {
+    return isReverse(value) && value.ancestors[0] === entry.parentID;
+}
+const timeOf = (value) => {
+    const at = obj(value).at;
+    return typeof at === "number" && Number.isFinite(at) ? at : undefined;
+};
+const noteOf = (value) => ({ at: timeOf(value), by: obj(value).by, status: obj(value).status });
+/** The `ChildStore` over the plugin's storage. */
+export function childStore(storage) {
+    const entry = async (parentID, sessionID) => (await storage.get(rosterKey(parentID, sessionID)));
+    const all = () => scanAll(storage, PREFIX);
+    const indexedParent = async (sessionID) => {
+        const indexed = await storage.get(reverseKey(sessionID));
+        return isReverse(indexed) ? indexed.ancestors[0] : undefined;
+    };
+    const walkIndex = async (sessionID, first) => {
+        let indexed = first;
+        const chain = [];
+        let below = sessionID;
+        // One read per level, all at once, and one more for the top's own reverse key, in case it was
+        // recorded after the key that names it; the chain ends where an entry is gone, as a scan's would.
+        for (;;) {
+            const { ancestors } = indexed;
+            const top = ancestors.at(-1);
+            const [entries, above] = await Promise.all([
+                Promise.all(ancestors.map((parentID, level) => storage.get(rosterKey(parentID, level ? ancestors[level - 1] : below)))),
+                storage.get(reverseKey(top)),
+            ]);
+            for (const found of entries) {
+                if (!found || chain.some((known) => known.sessionID === found.sessionID))
+                    return chain;
+                chain.push(found);
+            }
+            if (!isReverse(above))
+                return chain;
+            below = top;
+            indexed = above;
+        }
+    };
+    const lineage = async (sessionID) => {
+        const first = await storage.get(reverseKey(sessionID));
+        if (!isReverse(first))
+            return lineageIn(await all(), sessionID);
+        return walkIndex(sessionID, first);
+    };
+    const index = async (child) => {
+        const above = await storage.get(reverseKey(child.parentID));
+        const ancestors = isReverse(above) ? above.ancestors : (await lineage(child.parentID)).map((parent) => parent.parentID);
+        await storage.set(reverseKey(child.sessionID), { ancestors: [child.parentID, ...ancestors] });
+    };
+    /**
+     * Drops a reverse key whose entry was not in the roster read, unless that entry is there now:
+     * another instance may have recorded the child since, and it writes the entry before the key.
+     */
+    const dropDangling = async (sessionID, value) => {
+        if (isReverse(value) && (await storage.get(rosterKey(value.ancestors[0], sessionID))) !== undefined)
+            return;
+        await storage.remove(reverseKey(sessionID));
+    };
+    const forgetReport = async (sessionID) => {
+        await Promise.all(Object.values(REPORT_KEYS).map((key) => storage.remove(key(sessionID))));
+    };
+    return {
+        // The entry is what counts: written first, so a failed index write leaves it to be found by a scan.
+        async record(child) {
+            await storage.set(rosterKey(child.parentID, child.sessionID), { ...child });
+            await index(child).catch(() => undefined);
+        },
+        async remove(parentID, sessionID) {
+            await Promise.all([
+                storage.remove(rosterKey(parentID, sessionID)),
+                storage.remove(reverseKey(sessionID)).catch(() => undefined),
+                forgetReport(sessionID).catch(() => undefined),
+            ]);
+        },
+        entry,
+        async children(parentID) {
+            const entries = await scanAll(storage, `${PREFIX}${parentID}/`);
+            return entries.sort((a, b) => a.createdAt - b.createdAt);
+        },
+        all,
+        async entriesOf(sessionID) {
+            const parentID = await indexedParent(sessionID);
+            if (parentID === undefined)
+                return (await all()).filter((found) => found.sessionID === sessionID);
+            const found = await storage.get(rosterKey(parentID, sessionID));
+            return found === undefined ? [] : [found];
+        },
+        indexedParent,
+        async indexedEntry(sessionID) {
+            const parentID = await indexedParent(sessionID);
+            return parentID === undefined ? undefined : entry(parentID, sessionID);
+        },
+        lineage,
+        async indexedLineage(sessionID) {
+            const first = await storage.get(reverseKey(sessionID));
+            return isReverse(first) ? walkIndex(sessionID, first) : [];
+        },
+        async backfill(entries) {
+            const indexed = new Map((await scanEntries(storage, BY_CHILD)).map(({ key, value }) => [key, value]));
+            const sessions = new Set(entries.map((child) => child.sessionID));
+            await Promise.all([
+                ...entries
+                    .filter((child) => !indexes(indexed.get(child.sessionID), child))
+                    .map((child) => storage.set(reverseKey(child.sessionID), { ancestors: lineageIn(entries, child.sessionID).map((above) => above.parentID) })),
+                ...[...indexed]
+                    .filter(([sessionID]) => !sessions.has(sessionID))
+                    .map(([sessionID, value]) => dropDangling(sessionID, value)),
+            ]);
+        },
+        async notes(sessionID, fields) {
+            const values = await Promise.all(fields.map((field) => storage.get(REPORT_KEYS[field](sessionID))));
+            return Object.fromEntries(fields.map((field, i) => [field, noteOf(values[i])]));
+        },
+        // Both of the hub's subscriptions note each event, one of them maybe behind: an earlier note never replaces a later one.
+        async prompted(sessionID, at) {
+            if ((timeOf(await storage.get(promptKey(sessionID))) ?? -Infinity) < at)
+                await storage.set(promptKey(sessionID), { at });
+        },
+        async settled(sessionID, by, at, status) {
+            if ((timeOf(await storage.get(settledKey(sessionID))) ?? -Infinity) <= at)
+                await storage.set(settledKey(sessionID), { at, by, ...(status ? { status } : {}) });
+        },
+        async progressed(sessionID, at) {
+            if ((timeOf(await storage.get(progressKey(sessionID))) ?? -Infinity) <= at)
+                await storage.set(progressKey(sessionID), { at });
+        },
+        async told(sessionID, at) {
+            if ((timeOf(await storage.get(toldKey(sessionID))) ?? -Infinity) <= at)
+                await storage.set(toldKey(sessionID), { at });
+        },
+        async untold(sessionID, at) {
+            const stored = await storage.get(toldKey(sessionID)).then(timeOf, () => at);
+            if (stored === at)
+                await storage.remove(toldKey(sessionID));
+        },
+        async stopped(sessionID, at) {
+            await storage.set(stoppedKey(sessionID), { at });
+        },
+        async peek(sessionID, field) {
+            const value = await storage.get(REPORT_KEYS[field](sessionID));
+            return value;
+        },
+        async restore(sessionID, field, value) {
+            const key = REPORT_KEYS[field](sessionID);
+            await (value === undefined ? storage.remove(key) : storage.set(key, value));
+        },
+        forgetReport,
+        async reported() {
+            const keys = new Map();
+            for (const { key } of await scanEntries(storage, REPORT_PREFIX)) {
+                const slash = key.indexOf("/");
+                const sessionID = key.slice(0, slash);
+                if (slash > 0)
+                    keys.set(sessionID, [...(keys.get(sessionID) ?? []), `${REPORT_PREFIX}${key}`]);
+            }
+            return keys;
+        },
+        async dropReported(keys) {
+            await Promise.all(keys.map((key) => storage.remove(key).catch(() => undefined)));
+        },
+    };
+}
+function readMember(value) {
+    const given = obj(value);
+    const title = str(given.title);
+    const joinedAt = num(given.joinedAt);
+    if (title === undefined || joinedAt === undefined)
+        return undefined;
+    const report = readReport(given.report);
+    const left = obj(given.left);
+    const by = str(left.by);
+    return {
+        title,
+        joinedAt,
+        ...(report ? { report } : {}),
+        ...(by === "failed" || by === "interrupted" || by === "deleted" || by === "dropped" ? { left: { at: num(left.at) ?? 0, by } } : {}),
+    };
+}
+function readReport(value) {
+    const given = obj(value);
+    const status = given.status;
+    const message = str(given.message);
+    const at = num(given.at);
+    if (!isStatus(status) || message === undefined || at === undefined)
+        return undefined;
+    return { at, status, message, ...(given.artifacts !== undefined ? { artifacts: given.artifacts } : {}) };
+}
+/** A member as the storage takes it, which asks for an index signature the interface lacks. */
+const stored = (member) => ({ ...member });
+/** The `GroupStore` over the plugin's storage. */
+export function groupStore(storage) {
+    /** The members under `prefix`, a key prefix within `GROUP_PREFIX`; a value that is not a member is left out. */
+    const membersUnder = async (prefix) => {
+        const entries = await scanEntries(storage, prefix);
+        return entries.flatMap(({ key, value }) => {
+            const parts = `${prefix.slice(GROUP_PREFIX.length)}${key}`.split("/");
+            const member = parts.length === 3 ? readMember(value) : undefined;
+            return member ? [{ ...member, parentID: parts[0], group: parts[1], sessionID: parts[2] }] : [];
+        });
+    };
+    return {
+        member: async (parentID, group, sessionID) => readMember(await storage.get(memberKey(parentID, group, sessionID))),
+        all: () => membersUnder(GROUP_PREFIX),
+        ofParent: (parentID) => membersUnder(groupsPrefix(parentID)),
+        ofGroup: (parentID, group) => membersUnder(groupPrefix(parentID, group)),
+        async put(parentID, group, sessionID, member) {
+            await storage.set(memberKey(parentID, group, sessionID), stored(member));
+        },
+        async remove(parentID, group, sessionID) {
+            await storage.remove(memberKey(parentID, group, sessionID));
+        },
+    };
+}

package/dist/tree/subtree.d.ts

@@ -0,0 +1,101 @@
+import type { CourierPorts, RosterEntry, RosterStorage } from "./ports.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: "failed" | "interrupted" | "deleted" | "dropped" | "held" | "out" | "released" | "unknown";
+        };
+        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("./ports.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("./ports.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: "failed" | "interrupted" | "deleted" | "dropped" | "held" | "out" | "released" | "unknown";
+        };
+        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/subtree.js

@@ -0,0 +1,60 @@
+import { lastStatus, reportOf } from "./report.js";
+import { described } from "./status.js";
+import { childStore } from "./store.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 children = childStore(storage);
+    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.children(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 children = childStore(ports.storage);
+    const listed = await Promise.all(nodes.map(async ({ entry, depth }) => {
+        const [info, report, last] = await Promise.all([
+            described(ports, entry),
+            reportOf(children, entry.sessionID).catch(() => undefined),
+            lastStatus(children, 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/tree/summary.d.ts

@@ -0,0 +1,7 @@
+import type { CourierPorts } from "./ports.js";
+import type { Summary } from "./rpc.js";
+/**
+ * The sessions started under a session, at most `maxTotal` as courier_tree reads them, counted by what they
+ * are doing, and its open join groups, those of its own children, with how far each has reported.
+ */
+export declare function summary(ports: CourierPorts, sessionID: string): Promise<Summary>;

package/dist/tree/summary.js

@@ -0,0 +1,35 @@
+import { busy } from "./domain.js";
+import { groupStandings } from "./group.js";
+import { groupStore } from "./store.js";
+import { subtree } from "./subtree.js";
+/** What a session is doing: waiting on a request it made, running, or idle; undefined when OpenCode no longer knows it. */
+async function activity(ports, sessionID) {
+    const [info, pending] = await Promise.all([
+        ports.session.get({ sessionID }).catch(() => undefined),
+        ports.pending(sessionID).catch(() => []),
+    ]);
+    if (!info)
+        return undefined;
+    if (pending.length)
+        return "waiting";
+    return busy(info.time) ? "running" : "idle";
+}
+/**
+ * The sessions started under a session, at most `maxTotal` as courier_tree reads them, counted by what they
+ * are doing, and its open join groups, those of its own children, with how far each has reported.
+ */
+export async function summary(ports, sessionID) {
+    const counted = async () => {
+        const { nodes, truncated } = await subtree(ports.storage, sessionID, ports.limits.maxTotal);
+        return { activities: await Promise.all(nodes.map(({ entry }) => activity(ports, entry.sessionID))), truncated };
+    };
+    const [{ activities, truncated }, standings] = await Promise.all([counted(), groupStandings(groupStore(ports.storage), sessionID)]);
+    const count = (kind) => activities.filter((item) => item === kind).length;
+    return {
+        running: count("running"),
+        waiting: count("waiting"),
+        idle: count("idle"),
+        groups: standings.map(({ name, reported, members }) => ({ name, reported, members })),
+        ...(truncated ? { truncated: ports.limits.maxTotal } : {}),
+    };
+}

package/dist/tree/text.d.ts

@@ -0,0 +1,77 @@
+import type { Artifacts, CleanupResult, ExecutionError, HeldReport, LeftMember, Limits, Sent } from "./ports.js";
+/** The branch an isolated child commits its work on, and names in the `branch` of its report. */
+export declare const childBranch: (sessionID: string) => string;
+/** What a spawned session at `depth` is told; `depth` 1 is a child of a session nobody spawned. `branch` is for an isolated one. */
+export declare function childBrief(parentID: string, task: string, depth: number, limits: Limits, branch?: string): string;
+/** How every part the context hook adds begins, so a second copy of the plugin does not add its own. */
+export declare const ROLE_PREFIX = "opencode-courier role:";
+/**
+ * The system part naming a session's place in its tree: `depth` 0 for a session nobody spawned that
+ * has started one, `null` for one that has started none, which is pointed to the skill. The same on every request.
+ */
+export declare function rolePart(depth: number | null, limits: Limits): string;
+export declare const depthRefusal: (depth: number, maxDepth: number) => string;
+export declare const childrenRefusal: (running: number, maxChildren: number) => string;
+export declare const totalRefusal: (running: number, maxTotal: number) => string;
+/**
+ * The body of a report: its text, then the artifacts in a fixed layout, the same for every report,
+ * so a parent finds the branch, the commits, the files and the checks without reading prose.
+ */
+export declare function reportBody(message: string, artifacts: Artifacts | undefined): string;
+export declare function spawnText(child: {
+    readonly sessionID: string;
+    readonly directory: string;
+    readonly group?: string;
+    readonly rosterError?: string;
+    readonly groupError?: string;
+    readonly fromParent?: boolean;
+    readonly uncommitted?: boolean;
+}): string;
+/** courier_send's result: for a message to the session that started the sender, whether it was its report. */
+export declare function sendText(sessionID: string, sent?: Pick<Sent, "status" | "report" | "held">): string;
+/** courier_status's result: the session's state, as JSON. */
+export declare const statusText: (status: unknown) => string;
+export declare const childrenText: (listed: ReadonlyArray<unknown>) => string;
+export declare function cleanupText(result: CleanupResult): string;
+/** courier_tree's result: the sessions under a session, drawn depth first, as JSON. */
+export declare function treeText(tree: {
+    readonly sessions: ReadonlyArray<unknown>;
+    readonly truncated?: number;
+}): string;
+/** What courier_stop did to each session, and to the messages and worktrees. */
+export declare function stopText(result: {
+    readonly sessionID: string;
+    readonly stopped: ReadonlyArray<{
+        readonly sessionID: string;
+        readonly outcome: string;
+        readonly error?: string;
+    }>;
+    readonly cancelled: ReadonlyArray<string>;
+    readonly cleanup?: ReadonlyArray<CleanupResult | {
+        readonly sessionID: string;
+        readonly outcome: "failed";
+        readonly error: string;
+    }>;
+    readonly told?: string;
+}): string;
+/** What the parent of a stopped session is told when the stop was ordered by a session above both. */
+export declare const stoppedNotice: (title: string, by: string) => string;
+/** Why a worktree in this state must be kept, or undefined when removing it loses nothing. */
+export declare function keepReason(state: {
+    readonly changes: readonly string[];
+    readonly commits: readonly string[];
+}): string | undefined;
+export declare function failureNotice(title: string, error: ExecutionError, group?: string): string;
+/**
+ * What the parent is told when a session it started ends its turn without a report to it;
+ * `progressed` when it messaged the parent without a status since its last prompt.
+ */
+export declare function silentNotice(title: string, lastText: string | undefined, progressed?: boolean, group?: string): string;
+/**
+ * What the parent gets when a group it named is released: every report, with its status, text and artifacts in
+ * `reportBody`'s layout, and the members that left without one, in the order they joined.
+ */
+export declare function groupNotice(group: string, reports: ReadonlyArray<HeldReport & {
+    readonly sessionID: string;
+    readonly title: string;
+}>, left?: ReadonlyArray<LeftMember>): string;