opencode-courier 0.2.3 → 0.4.0

package/dist/tree/group.js

@@ -0,0 +1,203 @@
+import { isNotFound, millis } from "../platform/json.js";
+import { envelope } from "../kernel/protocol.js";
+import { complete, standingOf } from "./domain.js";
+import { groupStore } from "./store.js";
+import { groupNotice } from "./text.js";
+/** Makes a spawned session a member of its parent's group, opening the group if it was not. */
+export async function joinGroup(groups, parentID, group, sessionID, title, at) {
+    await groups.put(parentID, group, sessionID, { title, joinedAt: at });
+}
+/** The members of each group among `members`, by the claim key of the group. */
+function byGroup(members) {
+    const groups = new Map();
+    for (const member of members) {
+        const key = claimKey(member.parentID, member.group);
+        const group = groups.get(key);
+        if (group)
+            group.push(member);
+        else
+            groups.set(key, [member]);
+    }
+    return groups;
+}
+/** Whether a parent has a complete group with a report in it, which the scheduler delivers once the parent's turn has ended. */
+export async function hasCompleteGroup(groups, parentID) {
+    return [...byGroup(await groups.ofParent(parentID)).values()].some((members) => complete(members) && members.some((member) => member.report));
+}
+/** Holds a member's report with its group, in place of an earlier one, or of how it had left. */
+export async function holdReport(groups, membership, report) {
+    const { parentID, group, sessionID, title, joinedAt } = membership;
+    await groups.put(parentID, group, sessionID, { title, joinedAt, report });
+}
+/** How many of these members of a group have reported and how many have not left, and whether the group is complete. */
+const tally = (members) => ({
+    reported: members.filter((member) => member.report).length,
+    members: members.filter((member) => !member.left).length,
+    complete: complete(members),
+});
+/** How many members of a group have reported and how many have not left, and whether the group is complete. */
+export async function groupStanding(groups, parentID, group) {
+    return tally(await groups.ofGroup(parentID, group));
+}
+/** `groupStanding` of each open group of a parent, by name, from one read of its members. */
+export async function groupStandings(groups, parentID) {
+    const byName = new Map();
+    for (const member of await groups.ofParent(parentID))
+        byName.set(member.group, [...(byName.get(member.group) ?? []), member]);
+    return [...byName].map(([name, members]) => ({ name, ...tally(members) }));
+}
+/** A session's membership of a parent's group, if it is a member; `out` says whether the group still waits for its report. */
+export async function membershipOf(groups, parentID, group, sessionID) {
+    const member = await groups.member(parentID, group, sessionID);
+    return member && { ...member, parentID, group, sessionID, out: standingOf(member) === "out" };
+}
+/** A child's membership of the group its roster entry names; none without one. A failed read is the caller's to handle. */
+export async function membershipFor(groups, entry) {
+    return entry.group ? membershipOf(groups, entry.parentID, entry.group, entry.sessionID) : undefined;
+}
+/**
+ * Notes that a member left its group without a report: its turn failed or was interrupted, it was deleted or dropped. Read
+ * again first: one whose report is held meanwhile keeps it, one that left keeps why. True when that completes the group.
+ */
+export async function markLeft(groups, membership, by, at) {
+    const { parentID, group, sessionID } = membership;
+    const current = await groups.member(parentID, group, sessionID);
+    if (!current || standingOf(current) !== "out")
+        return false;
+    await groups.put(parentID, group, sessionID, { title: current.title, joinedAt: current.joinedAt, left: { at, by } });
+    return (await groupStanding(groups, parentID, group)).complete;
+}
+/** `markLeft` for a member not read yet; undefined when it is in no open group. */
+export async function leaveGroup(groups, parentID, group, sessionID, by, at) {
+    const membership = await membershipOf(groups, parentID, group, sessionID);
+    return membership && (await markLeft(groups, membership, by, at));
+}
+/** A child's membership of an open group it is still out in: the group waits for it, and its end takes it out without a report. */
+export async function outIn(ports, entry) {
+    try {
+        const member = await membershipFor(groupStore(ports.storage), entry);
+        return member?.out ? member : undefined;
+    }
+    catch (error) {
+        ports.log(`courier watch: could not read ${entry.sessionID}'s place in group ${entry.group}: ${String(error)}`);
+        return undefined;
+    }
+}
+/** Takes a member out of its group without a report; true when that completes the group, for the caller to nudge the scheduler. */
+export async function leave(ports, member, by, at) {
+    try {
+        return await markLeft(groupStore(ports.storage), member, by, at);
+    }
+    catch (error) {
+        ports.log(`courier watch: could not take ${member.sessionID} out of group ${member.group}: ${String(error)}`);
+        return false;
+    }
+}
+/**
+ * Puts a member whose report is held back among those out: its latest word to the parent was a blocked report. Read
+ * again first: a group released meanwhile is not opened again, and a report held since is kept.
+ */
+export async function unholdForBlocked(groups, membership) {
+    const { parentID, group, sessionID, title, joinedAt } = membership;
+    if (!membership.report)
+        return;
+    const current = await groups.member(parentID, group, sessionID);
+    if (JSON.stringify(current?.report) !== JSON.stringify(membership.report))
+        return;
+    await groups.put(parentID, group, sessionID, { title, joinedAt });
+}
+/** The claim key of a group's release, in the hub's shared set of deliveries under way. */
+const claimKey = (parentID, group) => `group:${parentID}/${group}`;
+/**
+ * Delivers every released group once, from the scheduler's tick: claimed in the shared `claimed`, re-read,
+ * delivered and only then dropped, so a failed delivery is tried again at the next tick, and a crash in between delivers it again.
+ */
+export async function deliverReleased(ports, claimed) {
+    const groups = [...byGroup(await groupStore(ports.storage).all())].filter(([key, members]) => complete(members) && !claimed.has(key));
+    // Claimed all at once, before any delivery, so a tick alongside claims none of these.
+    for (const [key] of groups)
+        claimed.add(key);
+    await Promise.all(groups.map(([key, members]) => releaseClaimed(ports, claimed, key, members[0])));
+}
+async function releaseClaimed(ports, claimed, key, { parentID, group }) {
+    try {
+        await release(ports, parentID, group);
+    }
+    catch (error) {
+        ports.log(`courier group ${group} of ${parentID}: ${String(error)}`);
+    }
+    finally {
+        claimed.delete(key);
+    }
+}
+/**
+ * Whether the parent's turn that started a group's last member has ended, so no more join it; `gone` when OpenCode no
+ * longer knows the parent. A turn ending stamps the session's `time.idle`, which a shutdown does not.
+ */
+async function sealed(ports, parentID, members) {
+    const joined = Math.max(...members.map((member) => member.joinedAt));
+    try {
+        const { time } = await ports.session.get({ sessionID: parentID });
+        // NaN, for a parent that has ended no turn yet, holds it.
+        return millis(time.idle) >= joined;
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return "gone";
+        throw error;
+    }
+}
+async function release(ports, parentID, group) {
+    // Re-read: another server may have delivered and dropped it since the scan.
+    const members = (await groupStore(ports.storage).ofGroup(parentID, group)).sort((a, b) => a.joinedAt - b.joinedAt);
+    if (!members.length || !complete(members))
+        return;
+    const seal = await sealed(ports, parentID, members);
+    if (!seal)
+        return;
+    if (seal === "gone")
+        return drop(ports, parentID, group, members, "the session is gone");
+    const reports = members.flatMap((member) => (member.report ? [{ sessionID: member.sessionID, title: member.title, ...member.report }] : []));
+    const left = members.flatMap((member) => (member.left ? [{ sessionID: member.sessionID, title: member.title, by: member.left.by }] : []));
+    if (reports.length) {
+        try {
+            await ports.session.synthetic({
+                sessionID: parentID,
+                text: envelope(reports.map((report) => report.sessionID).join(","), groupNotice(group, reports, left), {
+                    group,
+                    reports: String(reports.length),
+                }),
+                description: `Reports of group ${group}`,
+                metadata: { source: "courier", from: reports.map((report) => report.sessionID).join(","), group, reports: reports.length },
+                delivery: "steer",
+            });
+        }
+        catch (error) {
+            // A parent OpenCode no longer knows will never take it: dropped, like the children of a deleted session.
+            if (!isNotFound(error)) {
+                ports.log(`courier group ${group} of ${parentID} not delivered, held for another try: ${String(error)}`);
+                return;
+            }
+            return drop(ports, parentID, group, members, `the session is gone (${String(error)})`);
+        }
+    }
+    await drop(ports, parentID, group, members);
+}
+/** Drops a group's members once delivered, or unsent, saying why. */
+async function drop(ports, parentID, group, members, unsent) {
+    if (unsent)
+        ports.log(`courier group ${group} of ${parentID} dropped: ${unsent}`);
+    // A member left behind here is delivered again at the next tick, as after a crash: logged, so it can be seen.
+    const groups = groupStore(ports.storage);
+    const dropped = await Promise.allSettled(members.map((member) => dropDelivered(groups, member)));
+    for (const [index, result] of dropped.entries())
+        if (result.status === "rejected")
+            ports.log(`courier group ${group} of ${parentID}: delivered, but ${members[index].sessionID} could not be dropped: ${String(result.reason)}`);
+}
+/** Drops a delivered member's key, unless it was written again since it was read: that report is still to deliver. */
+async function dropDelivered(groups, delivered) {
+    const { parentID, group, sessionID, ...read } = delivered;
+    if (JSON.stringify(await groups.member(parentID, group, sessionID)) !== JSON.stringify(read))
+        return;
+    await groups.remove(parentID, group, sessionID);
+}

package/dist/tree/index.d.ts

@@ -0,0 +1,10 @@
+export { dirtyOf, headOf, inspectWorktree } from "./cleanup.js";
+export { shapeContext } from "./context.js";
+export { lineageIn, nativeRootOf, readLimits, readNativeChildren } from "./domain.js";
+export { together, treeEvents, waitsOn } from "./events.js";
+export { deliverReleased } from "./group.js";
+export type { CleanupPorts, CourierPorts, Pending, PendingPrompt, RosterEntry, RosterStorage, SpawnGate, Waits, WatchPorts, WatchState, } from "./ports.js";
+export { allEntries, answeringTop, lineage, pruneExpired, RETENTION_MS } from "./roster.js";
+export { subtree } from "./subtree.js";
+export { registerTreeRpc } from "./rpc-handlers.js";
+export { addTreeTools } from "./tools.js";

package/dist/tree/index.js

@@ -0,0 +1,11 @@
+// What the rest of the plugin uses of the session tree: its tools, RPC, event module, context hook and tick job
+// for `src/index.ts`, and the lineage and subtree queries and types `person/` reads.
+export { dirtyOf, headOf, inspectWorktree } from "./cleanup.js";
+export { shapeContext } from "./context.js";
+export { lineageIn, nativeRootOf, readLimits, readNativeChildren } from "./domain.js";
+export { together, treeEvents, waitsOn } from "./events.js";
+export { deliverReleased } from "./group.js";
+export { allEntries, answeringTop, lineage, pruneExpired, RETENTION_MS } from "./roster.js";
+export { subtree } from "./subtree.js";
+export { registerTreeRpc } from "./rpc-handlers.js";
+export { addTreeTools } from "./tools.js";

package/dist/tree/limits.d.ts

@@ -0,0 +1,10 @@
+import type { LimitPorts, Reservation } from "./ports.js";
+/**
+ * Checks the limits for a spawn from `parentID`, then holds its place in `gate` until `release`;
+ * throws a refusal naming the limit. Checks run one at a time, so spawns made together count each other.
+ */
+export declare function admit(ports: LimitPorts, parentID: string): Promise<{
+    depth: number;
+    reservation: Reservation;
+    release: () => void;
+}>;

package/dist/tree/limits.js

@@ -0,0 +1,60 @@
+import { isNotFound } from "../platform/json.js";
+import { busy, bySession, lineageBy } from "./domain.js";
+import { reportOf } from "./report.js";
+import { childStore } from "./store.js";
+import { childrenRefusal, depthRefusal, totalRefusal } from "./text.js";
+/**
+ * Whether a spawned session counts against the limits: it runs, unless its turn failed or was
+ * interrupted since its last prompt, or it owes its parent a report. One OpenCode no longer knows does not.
+ */
+async function live(ports, sessionID) {
+    const [time, report] = await Promise.all([
+        ports.session.get({ sessionID }).then((info) => info.time, (error) => (isNotFound(error) ? null : undefined)),
+        reportOf(childStore(ports.storage), sessionID).catch(() => undefined),
+    ]);
+    if (time === null)
+        return false;
+    // One whose first prompt failed never ran, and has no idle time to tell so.
+    const runs = time !== undefined && busy(time) && !report?.ended;
+    return runs || (report?.owes ?? false);
+}
+/**
+ * Checks the limits for a spawn from `parentID`, then holds its place in `gate` until `release`;
+ * throws a refusal naming the limit. Checks run one at a time, so spawns made together count each other.
+ */
+export async function admit(ports, parentID) {
+    const gate = ports.gate;
+    const checked = gate.turn.then(() => check(ports, parentID));
+    gate.turn = checked.catch(() => undefined);
+    const { depth, reservation } = await checked;
+    const release = () => {
+        gate.reserved.delete(reservation);
+    };
+    return { depth, reservation, release };
+}
+async function check(ports, parentID) {
+    const { maxDepth, maxChildren, maxTotal } = ports.limits;
+    const entries = await childStore(ports.storage).all();
+    const parents = bySession(entries);
+    const chain = lineageBy(parents, parentID);
+    if (chain.length >= maxDepth)
+        throw new Error(depthRefusal(chain.length, maxDepth));
+    const top = chain.at(-1)?.parentID ?? parentID;
+    const chains = new Map(entries.map((entry) => [entry.sessionID, lineageBy(parents, entry.sessionID)]));
+    const tree = entries.filter((entry) => chains.get(entry.sessionID).at(-1)?.parentID === top);
+    const runs = await Promise.all(tree.map((entry) => live(ports, entry.sessionID)));
+    // A session waiting on a live descendant is live too: the brief tells it to end its turn meanwhile.
+    const active = new Set(tree.filter((_, i) => runs[i]).flatMap((entry) => [entry.sessionID, ...chains.get(entry.sessionID).map((above) => above.parentID)]));
+    const counted = tree.filter((entry) => active.has(entry.sessionID));
+    // A spawn whose child is on the roster already is counted there, if it is live, not by its reservation.
+    const recorded = new Set(tree.map((entry) => entry.sessionID));
+    const pending = [...ports.gate.reserved].filter((held) => held.top === top && !(held.sessionID && recorded.has(held.sessionID)));
+    const mine = counted.filter((entry) => entry.parentID === parentID).length + pending.filter((held) => held.parentID === parentID).length;
+    if (mine >= maxChildren)
+        throw new Error(childrenRefusal(mine, maxChildren));
+    if (counted.length + pending.length >= maxTotal)
+        throw new Error(totalRefusal(counted.length + pending.length, maxTotal));
+    const reservation = { parentID, top };
+    ports.gate.reserved.add(reservation);
+    return { depth: chain.length + 1, reservation };
+}

package/dist/tree/panel.d.ts

@@ -0,0 +1,13 @@
+import type { CourierPorts, Pending } from "./ports.js";
+import type { Tree, Wait } from "./rpc.js";
+type Messages = Awaited<ReturnType<CourierPorts["session"]["context"]>>;
+/** The last tool call in a session's messages, and when it was made. */
+export declare function lastTool(messages: Messages): {
+    name: string;
+    at: number;
+} | undefined;
+/** A request as the panel says what a paused session waits on: a permission request, or its first question. */
+export declare const waitOf: (pending: Pending) => Wait;
+/** The tree panel's rows: the sessions courier_tree reads under a session, at most `maxTotal`, each as `row` reads it. */
+export declare function panel(ports: CourierPorts, rootID: string): Promise<Tree>;
+export {};

package/dist/tree/panel.js

@@ -0,0 +1,75 @@
+import { busy } from "./domain.js";
+import { lastStatus, reportOf } from "./report.js";
+import { standingIn } from "./status.js";
+import { childStore } from "./store.js";
+import { subtree } from "./subtree.js";
+/** The last tool call in a session's messages, and when it was made. */
+export function lastTool(messages) {
+    for (const message of messages.toReversed()) {
+        if (message.type !== "assistant")
+            continue;
+        const tool = message.content.findLast((part) => part.type === "tool");
+        if (tool?.type === "tool")
+            return { name: tool.name, at: tool.time.ran ?? tool.time.created };
+    }
+    return undefined;
+}
+/** A request as the panel says what a paused session waits on: a permission request, or its first question. */
+export const waitOf = (pending) => pending.type === "permission"
+    ? { type: "permission", action: pending.action, resources: [...pending.resources] }
+    : { type: "question", question: pending.questions[0]?.question ?? "" };
+/** A session's report since its last prompt, as the panel shows it; none for one spawned before this was kept. */
+function reportRow(report, status) {
+    if (!report)
+        return {};
+    if (report.owes)
+        return { report: { state: "owed", progressed: report.progressed } };
+    if (report.ended)
+        return { report: { state: "ended", progressed: report.progressed } };
+    return { report: { state: "reported", progressed: report.progressed, ...(status ? { status } : {}) } };
+}
+/** What a session does: waiting on a request to the person, running, idle, or gone when OpenCode no longer knows it. */
+function stateOf(info, waits, running) {
+    if (!info)
+        return "gone";
+    if (waits)
+        return "waiting";
+    return running ? "running" : "idle";
+}
+/** One session of the panel: what it is doing, its report and group standing, its last tool call and its cost. */
+async function row(ports, entry, depth) {
+    const { sessionID } = entry;
+    const children = childStore(ports.storage);
+    const [info, messages, pending, report, status, standing] = await Promise.all([
+        ports.session.get({ sessionID }).catch(() => undefined),
+        ports.session.context({ sessionID }).catch(() => []),
+        ports.pending(sessionID).catch(() => []),
+        reportOf(children, sessionID).catch(() => undefined),
+        lastStatus(children, sessionID).catch(() => undefined),
+        entry.group ? standingIn(ports, entry, entry.group) : undefined,
+    ]);
+    const running = info !== undefined && busy(info.time);
+    const tool = lastTool(messages);
+    return {
+        sessionID,
+        parentID: entry.parentID,
+        title: info?.title ?? entry.title,
+        depth,
+        state: stateOf(info, pending.length, running),
+        ...(info?.outcome ? { outcome: info.outcome } : {}),
+        ...reportRow(report, status),
+        ...(entry.group && standing ? { group: { name: entry.group, standing } } : {}),
+        isolated: entry.isolated,
+        created: info?.time.created ?? entry.createdAt,
+        ...(info && !running && info.time.idle !== undefined ? { idle: info.time.idle } : {}),
+        ...(info ? { cost: info.cost } : {}),
+        ...(tool ? { tool } : {}),
+        waits: pending.map(waitOf),
+    };
+}
+/** The tree panel's rows: the sessions courier_tree reads under a session, at most `maxTotal`, each as `row` reads it. */
+export async function panel(ports, rootID) {
+    const { nodes, truncated } = await subtree(ports.storage, rootID, ports.limits.maxTotal);
+    const rows = await Promise.all(nodes.map(({ entry, depth }) => row(ports, entry, depth)));
+    return { rows, ...(truncated ? { truncated: ports.limits.maxTotal } : {}) };
+}