opencode-courier 0.3.0 → 0.4.1

package/dist/tree/group.d.ts

@@ -0,0 +1,82 @@
+import { type HeldReport, type LeftMember, type RosterEntry } from "./domain.js";
+import type { GroupPorts, GroupStore, Membership, WatchPorts } from "./ports.js";
+/** Makes a spawned session a member of its parent's group, opening the group if it was not. */
+export declare function joinGroup(groups: GroupStore, parentID: string, group: string, sessionID: string, title: string, at: number): Promise<void>;
+/** Whether a parent has a complete group with a report in it, which the scheduler delivers once the parent's turn has ended. */
+export declare function hasCompleteGroup(groups: GroupStore, parentID: string): Promise<boolean>;
+/** Holds a member's report with its group, in place of an earlier one, or of how it had left. */
+export declare function holdReport(groups: GroupStore, membership: Membership, report: HeldReport): Promise<void>;
+/** How many members of a group have reported and how many have not left, and whether the group is complete. */
+export declare function groupStanding(groups: GroupStore, parentID: string, group: string): Promise<{
+    reported: number;
+    members: number;
+    complete: boolean;
+}>;
+/** `groupStanding` of each open group of a parent, by name, from one read of its members. */
+export declare function groupStandings(groups: Pick<GroupStore, "ofParent">, parentID: string): Promise<{
+    reported: number;
+    members: number;
+    complete: boolean;
+    name: string;
+}[]>;
+/** 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 declare function membershipOf(groups: Pick<GroupStore, "member">, parentID: string, group: string, sessionID: string): Promise<{
+    parentID: string;
+    group: string;
+    sessionID: string;
+    out: boolean;
+    title: string;
+    joinedAt: number;
+    report?: HeldReport;
+    left?: {
+        readonly at: number;
+        readonly by: LeftMember["by"];
+    };
+} | undefined>;
+/** A child's membership of the group its roster entry names; none without one. A failed read is the caller's to handle. */
+export declare function membershipFor(groups: Pick<GroupStore, "member">, entry: RosterEntry): Promise<{
+    parentID: string;
+    group: string;
+    sessionID: string;
+    out: boolean;
+    title: string;
+    joinedAt: number;
+    report?: HeldReport;
+    left?: {
+        readonly at: number;
+        readonly by: LeftMember["by"];
+    };
+} | 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 declare function markLeft(groups: GroupStore, membership: Membership, by: LeftMember["by"], at: number): Promise<boolean>;
+/** `markLeft` for a member not read yet; undefined when it is in no open group. */
+export declare function leaveGroup(groups: GroupStore, parentID: string, group: string, sessionID: string, by: LeftMember["by"], at: number): Promise<boolean | undefined>;
+/** 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 declare function outIn(ports: Pick<WatchPorts, "storage" | "log">, entry: RosterEntry): Promise<{
+    parentID: string;
+    group: string;
+    sessionID: string;
+    out: boolean;
+    title: string;
+    joinedAt: number;
+    report?: HeldReport;
+    left?: {
+        readonly at: number;
+        readonly by: LeftMember["by"];
+    };
+} | 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 declare function leave(ports: Pick<WatchPorts, "storage" | "log">, member: Membership, by: "failed" | "interrupted" | "deleted", at: number): Promise<boolean>;
+/**
+ * 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 declare function unholdForBlocked(groups: GroupStore, membership: Membership): Promise<void>;
+/**
+ * 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 declare function deliverReleased(ports: GroupPorts, claimed: Set<string>): Promise<void>;

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/{limits.js → tree/limits.js}

@@ -1,27 +1,8 @@
-import { setBounded } from "./bounded.js";
-import { isNotFound, millis, obj } from "./json.js";
-import { childrenRefusal, depthRefusal, ROLE_PREFIX, rolePart, totalRefusal } from "./notices.js";
+import { isNotFound } from "../platform/json.js";
+import { busy, bySession, lineageBy } from "./domain.js";
 import { reportOf } from "./report.js";
-import { allEntries, bySession, children, indexedLineage, lineageBy } from "./roster.js";
-export const DEFAULT_LIMITS = { maxDepth: 3, maxChildren: 5, maxTotal: 20 };
-/** The limits in the plugin's options; one that is not a positive integer keeps its default and is named in `problems`. */
-export function readLimits(options) {
-    const given = obj(options);
-    const problems = [];
-    const read = (name) => {
-        const value = given[name];
-        if (value === undefined)
-            return DEFAULT_LIMITS[name];
-        if (typeof value === "number" && Number.isInteger(value) && value > 0)
-            return value;
-        problems.push(`${name} must be a positive integer, not ${JSON.stringify(value)}; using ${DEFAULT_LIMITS[name]}`);
-        return DEFAULT_LIMITS[name];
-    };
-    const limits = { maxDepth: read("maxDepth"), maxChildren: read("maxChildren"), maxTotal: read("maxTotal") };
-    return { limits, problems };
-}
-/** Whether a session with these times runs: it has never finished a turn, or something reached it after the last one ended. */
-export const busy = (time) => time.idle === undefined || millis(time.updated) > millis(time.idle);
+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.
@@ -29,7 +10,7 @@ export const busy = (time) => time.idle === undefined || millis(time.updated) >
 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(ports.storage, sessionID).catch(() => undefined),
+        reportOf(childStore(ports.storage), sessionID).catch(() => undefined),
     ]);
     if (time === null)
         return false;
@@ -53,7 +34,7 @@ export async function admit(ports, parentID) {
 }
 async function check(ports, parentID) {
     const { maxDepth, maxChildren, maxTotal } = ports.limits;
-    const entries = await allEntries(ports.storage);
+    const entries = await childStore(ports.storage).all();
     const parents = bySession(entries);
     const chain = lineageBy(parents, parentID);
     if (chain.length >= maxDepth)
@@ -77,33 +58,3 @@ async function check(ports, parentID) {
     ports.gate.reserved.add(reservation);
     return { depth: chain.length + 1, reservation };
 }
-/** How many sessions' depths an instance remembers. */
-const ROLES_MAX = 1000;
-/**
- * The `context` hook: names a session's role in its tree in a system part, and hides courier_spawn
- * from one at `maxDepth`. A session nobody spawned that has started none is pointed to the skill, if it could spawn.
- */
-export async function shapeContext(ports, event) {
-    try {
-        const depth = await depthOf(ports, event.sessionID);
-        if (depth === null && !event.tools.courier_spawn)
-            return;
-        if (depth !== null && depth >= ports.limits.maxDepth)
-            delete event.tools.courier_spawn;
-        if (!event.system.some((part) => part.text.startsWith(ROLE_PREFIX)))
-            event.system.push({ type: "text", text: rolePart(depth, ports.limits) });
-    }
-    catch (error) {
-        ports.log(`courier: cannot tell the role of session ${event.sessionID}: ${String(error)}`);
-    }
-}
-async function depthOf(ports, sessionID) {
-    const known = ports.roles.get(sessionID);
-    if (known !== undefined)
-        return known;
-    // The reverse index alone: a scan here would run for every session's first request, courier or not.
-    const chain = await indexedLineage(ports.storage, sessionID);
-    const depth = chain.length || ((await children(ports.storage, sessionID)).length ? 0 : null);
-    setBounded(ports.roles, sessionID, depth, ROLES_MAX);
-    return depth;
-}

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 } : {}) };
+}