opencode-courier 0.2.3 → 0.3.0

package/dist/courier.js

@@ -1,5 +1,8 @@
-import { childBrief, envelope } from "./notices.js";
-import { current, record } from "./roster.js";
+import { groupStanding, holdReport, isGroupName, joinGroup, leaveGroup, memberKey, memberOf, membershipOf, standingOf, unholdForBlocked, unholdReport } from "./group.js";
+import { admit } from "./limits.js";
+import { childBrief, childBranch, envelope, isStatus, reportBody, STATUSES } from "./notices.js";
+import { progressed, progressKey, prompted, settled, settledKey } from "./report.js";
+import { current, indexedEntry, record } from "./roster.js";
 function titleOf(task) {
     const line = task.trim().split("\n")[0] ?? "";
     return line.length > 60 ? `${line.slice(0, 57)}...` : line;
@@ -24,58 +27,227 @@ async function dropWorktree(ports, directory) {
         // The spawn's own failure is the one to report.
     }
 }
-/** Creates a child session, hands it the task and returns at once; the child reports back with courier_send. */
+/**
+ * Creates a child session, hands it the task and returns at once; the child reports back with
+ * courier_send. Refused past a limit, whether or not the `context` hook hid the tool.
+ */
 export async function spawn(ports, parentID, input) {
+    // Some models send null, or an empty string, for an optional field they leave out.
+    const group = typeof input.group === "string" ? input.group.trim() || undefined : (input.group ?? undefined);
+    if (group !== undefined && !isGroupName(group))
+        throw new Error(`group must be a name of 1 to 60 letters, digits, dots, dashes or underscores, not ${JSON.stringify(group)}.`);
+    const admitted = await admit(ports, parentID);
+    try {
+        return await start(ports, parentID, input, admitted, group);
+    }
+    finally {
+        admitted.release();
+    }
+}
+async function start(ports, parentID, input, admitted, group) {
+    const { worktree, handedDown, ...child } = await create(ports, parentID, input);
+    admitted.reservation.sessionID = child.sessionID;
+    const entry = {
+        ...child,
+        parentID,
+        isolated: worktree !== undefined,
+        createdAt: ports.now(),
+        reports: "status",
+        ...(worktree ? { source: ports.directory, project: ports.projectID } : {}),
+        ...(group ? { group } : {}),
+    };
+    const { rosterError, groupError } = await enrol(ports, entry, group);
+    ports.roles.delete(parentID);
+    await handOver(ports, entry, admitted.depth, input.task, !rosterError, !rosterError && !groupError);
+    return {
+        sessionID: entry.sessionID,
+        directory: entry.directory,
+        ...(group && !rosterError && !groupError ? { group } : {}),
+        ...(rosterError ? { rosterError } : {}),
+        ...(groupError ? { groupError } : {}),
+        ...(handedDown ? { fromParent: true } : {}),
+        ...(handedDown?.uncommitted ? { uncommitted: true } : {}),
+    };
+}
+/** Creates the child's session, in a worktree of its own if asked, which goes again if the session cannot be created. */
+async function create(ports, parentID, input) {
     // A failed lookup must not keep the child from starting; it then runs on OpenCode's default.
     const model = await inheritedModel(ports, parentID, input.agent).catch(() => undefined);
-    const directory = input.isolate
-        ? (await ports.worktree.create({ projectID: ports.projectID })).directory
+    const handedDown = input.isolate ? await parentWork(ports, parentID) : undefined;
+    const worktree = input.isolate
+        ? (await ports.worktree.create({ projectID: ports.projectID, ...(handedDown ? { from: handedDown.directory, branch: handedDown.head } : {}) })).directory
         : undefined;
-    const base = directory ? await ports.head(directory) : undefined;
+    const base = worktree ? await ports.head(worktree) : undefined;
     const title = input.title ?? titleOf(input.task);
     const child = await ports.session
         .create({
         title,
         ...(input.agent ? { agent: input.agent } : {}),
         ...(model ? { model } : {}),
-        ...(directory ? { location: { directory } } : {}),
+        ...(worktree ? { location: { directory: worktree } } : {}),
         metadata: { courier: { parentID } },
     })
         .catch(async (error) => {
         // No session will ever use the fresh worktree, and nothing records it, so it goes now.
-        if (directory)
-            await dropWorktree(ports, directory);
+        if (worktree)
+            await dropWorktree(ports, worktree);
         throw error;
     });
-    // Recorded before the prompt, so a child that exists is on the roster even if prompting fails. A
-    // failed write must not keep the child from its task, so it is reported instead of thrown.
-    const rosterError = await record(ports.storage, {
-        sessionID: child.id,
-        parentID,
-        title,
-        directory: directory ?? child.location.directory,
-        isolated: directory !== undefined,
-        createdAt: ports.now(),
-        ...(directory ? { source: ports.directory, project: ports.projectID } : {}),
-        ...(base ? { base } : {}),
-    }).then(() => undefined, (error) => describeFailure("roster", error).message);
-    await ports.session.prompt({ sessionID: child.id, text: childBrief(parentID, input.task) });
-    return {
-        sessionID: child.id,
-        directory: directory ?? child.location.directory,
-        ...(rosterError ? { rosterError } : {}),
-    };
+    return { sessionID: child.id, title, directory: worktree ?? child.location.directory, worktree, handedDown, ...(base ? { base } : {}) };
+}
+/**
+ * The worktree and HEAD an isolated parent hands its isolated child, by the reverse index alone; undefined for any
+ * other parent. An unreadable HEAD fails the spawn rather than start the child without the parent's work.
+ */
+async function parentWork(ports, parentID) {
+    const parent = await indexedEntry(ports.storage, parentID);
+    if (!parent?.isolated)
+        return undefined;
+    const head = await ports.head(parent.directory);
+    if (!head)
+        throw new Error(`the HEAD of your worktree ${parent.directory} could not be read, so an isolated session cannot start from it; nothing was started. Start it without isolate, or fix the worktree.`);
+    const uncommitted = (await ports.dirty(parent.directory).catch(() => undefined)) === true;
+    return { directory: parent.directory, head, uncommitted };
+}
+/**
+ * Records the child on the roster, before the prompt, so a child that exists is on the roster even if prompting
+ * fails, then in its group. A failed write must not keep the child from its task: each is reported, not thrown.
+ */
+async function enrol(ports, entry, group) {
+    const rosterError = await record(ports.storage, entry).then(() => undefined, (error) => describeFailure("roster", error).message);
+    const groupError = group && !rosterError ? await join(ports, entry, group) : undefined;
+    return { rosterError, groupError };
+}
+/**
+ * Hands the child its task. `rostered` says whether its report state is kept, which a child off the roster has none
+ * of, and `grouped` whether it is in its group; a child that never got its task leaves both, as it will never report.
+ */
+async function handOver(ports, entry, depth, task, rostered, grouped) {
+    // A baseline, until OpenCode's event for the prompt's delivery moves it on; written first, so it never overtakes that.
+    if (rostered)
+        await prompted(ports.storage, entry.sessionID, ports.now()).catch(() => undefined);
+    try {
+        await ports.session.prompt({ sessionID: entry.sessionID, text: childBrief(entry.parentID, task, depth, ports.limits, entry.isolated ? childBranch(entry.sessionID) : undefined) });
+    }
+    catch (error) {
+        if (rostered)
+            await settled(ports.storage, entry.sessionID, "failed", ports.now()).catch(() => undefined);
+        if (grouped && entry.group)
+            await leaveGroup(ports.storage, entry.parentID, entry.group, entry.sessionID, "failed", ports.now()).then((complete) => complete && ports.nudge(), (leaveError) => ports.log(`courier_spawn: ${entry.sessionID} could not leave group ${entry.group}: ${String(leaveError)}`));
+        throw error;
+    }
+}
+/**
+ * Joins a child to its group; one that cannot be joined is recorded in no group, so it reports on its own,
+ * and the result says so. Returns the error's message, if any.
+ */
+async function join(ports, entry, group) {
+    try {
+        await joinGroup(ports.storage, entry.parentID, group, entry.sessionID, entry.title, ports.now());
+        return undefined;
+    }
+    catch (error) {
+        const { group: _, ...ungrouped } = entry;
+        // A write that failed may have landed all the same: a member left there would hold its group up for good.
+        await Promise.all([
+            record(ports.storage, ungrouped).catch(() => undefined),
+            ports.storage.remove(memberKey(entry.parentID, group, entry.sessionID)).catch(() => undefined),
+        ]);
+        return describeFailure("group", error).message;
+    }
 }
-/** Drops a message into another session's inbox; OpenCode wakes that session if it is idle. */
+/**
+ * Drops a message into another session's inbox; OpenCode wakes that session if it is idle. From a spawned session
+ * to the one that started it, it is its report or its progress (`noteReport`); a group member's final report is held (`hold`).
+ */
 export async function send(ports, from, input) {
-    const delivered = await ports.session.synthetic({
-        sessionID: input.sessionID,
-        text: envelope(from, input.message),
-        description: `Message from ${from}`,
-        metadata: { source: "courier", from },
-        delivery: input.queue ? "queue" : "steer",
-    });
-    return { messageID: delivered.id };
+    // Some models send null for an optional field they leave out.
+    const status = input.status ?? undefined;
+    if (status !== undefined && !isStatus(status))
+        throw new Error(`status must be one of ${STATUSES.join(", ")}, not ${JSON.stringify(status)}.`);
+    // Noted first: the delivery may wake the parent, whose turn may end before a later note.
+    const noted = await noteReport(ports, from, input.sessionID, status).catch(() => undefined);
+    try {
+        const held = noted?.member && status && status !== "blocked" ? await hold(ports, noted.member, { at: noted.at, status, message: input.message, ...(input.artifacts ? { artifacts: input.artifacts } : {}) }) : undefined;
+        if (held)
+            return { status, report: true, held };
+        const delivered = await ports.session.synthetic({
+            sessionID: input.sessionID,
+            text: envelope(from, reportBody(input.message, input.artifacts), status ? { status } : {}),
+            description: `Message from ${from}`,
+            metadata: { source: "courier", from, ...(status ? { status } : {}) },
+            delivery: input.queue ? "queue" : "steer",
+        });
+        // A blocked report, once delivered, is the member's latest word: an earlier report held for it would be stale.
+        if (noted?.member && status === "blocked")
+            await unholdForBlocked(ports.storage, noted.member).catch(() => undefined);
+        return { messageID: delivered.id, ...(status ? { status } : {}), ...(noted ? { report: noted.report } : {}) };
+    }
+    catch (error) {
+        await noted?.undo().catch(() => undefined);
+        throw error;
+    }
+}
+/**
+ * Notes `from`'s message to `to` when `to` started it: as its report when it carries a status, or when an earlier
+ * release briefed `from`, else as progress. Returns which, when, how to take the note back, and `from`'s group membership.
+ */
+async function noteReport(ports, from, to, status) {
+    const entry = await indexedEntry(ports.storage, from);
+    if (entry?.parentID !== to)
+        return undefined;
+    const report = status !== undefined || entry.reports !== "status";
+    const key = report ? settledKey(from) : progressKey(from);
+    const before = await ports.storage.get(key);
+    const at = ports.now();
+    await (report ? settled(ports.storage, from, "report", at, status) : progressed(ports.storage, from, at));
+    // Only its own note: another courier_send of the session's may have noted its report since.
+    const undo = async () => {
+        const now = (await ports.storage.get(key));
+        if (now?.at !== at || (report && now.by !== "report"))
+            return;
+        await (before === undefined ? ports.storage.remove(key) : ports.storage.set(key, before));
+    };
+    return { report, at, undo, member: status !== undefined ? await memberIn(ports, entry) : undefined };
+}
+/**
+ * A child's membership of an open group of its parent's, by its roster entry; none once courier_cleanup dropped it. One that
+ * cannot be read is dropped from the group, best effort, as the report then goes on its own and the group must not wait for it.
+ */
+async function memberIn(ports, entry) {
+    if (!entry.group)
+        return undefined;
+    try {
+        const member = await membershipOf(ports.storage, entry.parentID, entry.group, entry.sessionID);
+        return member?.left?.by === "dropped" ? undefined : member;
+    }
+    catch (error) {
+        ports.log(`courier_send: ${entry.sessionID}'s place in group ${entry.group} could not be read, so its report goes on its own: ${String(error)}`);
+        await ports.storage.remove(memberKey(entry.parentID, entry.group, entry.sessionID)).then(() => ports.nudge(), () => undefined);
+        return undefined;
+    }
+}
+/**
+ * Holds a member's report with its group, and nudges the scheduler if that completes the group. Undefined
+ * when it could not be held: the member is dropped from the group, which releases without it, and reports on its own.
+ */
+async function hold(ports, member, report) {
+    try {
+        await holdReport(ports.storage, member, report);
+    }
+    catch (error) {
+        // Neither held nor dropped, the group would wait for ever: the call fails, and the sender sends it again.
+        await unholdReport(ports.storage, member).catch((dropError) => {
+            throw new Error(`the report could not be held with group ${member.group} (${String(error)}), nor the member dropped from it (${String(dropError)}); send it again.`);
+        });
+        ports.nudge();
+        return undefined;
+    }
+    // Held whatever the count gives; a count that cannot be read gets the nudge, as a tick that finds nothing due is cheap.
+    const standing = await groupStanding(ports.storage, member.parentID, member.group).catch(() => undefined);
+    if (standing?.complete !== false)
+        ports.nudge();
+    return { group: member.group, ...(standing ? { reported: standing.reported, members: standing.members } : {}) };
 }
 /** A one-off look at a session, for check-ins; not meant to be called in a loop. */
 export async function status(ports, input) {
@@ -84,10 +256,7 @@ export async function status(ports, input) {
         ports.session.context({ sessionID: input.sessionID }),
         ports.pending(input.sessionID),
     ]);
-    const last = messages.findLast((message) => message.type === "assistant");
-    const lastText = last?.type === "assistant"
-        ? last.content.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("")
-        : undefined;
+    const lastText = lastReply(messages);
     return withoutUndefined({
         sessionID: info.id,
         title: info.title,
@@ -99,23 +268,38 @@ export async function status(ports, input) {
         pending: pending.length ? pending : undefined,
     });
 }
-/** The sessions a parent started, each with what courier_status reports, or the error it gave. */
+/** The text of a session's last reply, from its context's messages, or undefined when it has none. */
+export function lastReply(messages) {
+    const last = messages.findLast((message) => message.type === "assistant");
+    return last?.type === "assistant"
+        ? last.content.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("")
+        : undefined;
+}
+/**
+ * The sessions a parent started, each with what courier_status reports, or the error it gave; a child in a
+ * group with the group's name and its standing there: `held`, `out`, how it left, `released` or `unknown`.
+ */
 export async function listChildren(ports, parentID) {
     const entries = await current(ports.storage, parentID, ports.now());
-    return Promise.all(entries.map(async (entry) => {
-        const roster = { directory: entry.directory, isolated: entry.isolated, created: entry.createdAt };
-        try {
-            return { ...(await status(ports, { sessionID: entry.sessionID })), ...roster };
-        }
-        catch (error) {
-            return {
-                sessionID: entry.sessionID,
-                title: entry.title,
-                ...roster,
-                error: describeFailure("courier_status", error).message,
-            };
-        }
-    }));
+    return Promise.all(entries.map((entry) => described(ports, entry)));
+}
+/** One roster entry as courier_children shows it: what courier_status reports with its directory and group standing, or the error it gave. */
+export async function described(ports, entry) {
+    const group = entry.group
+        ? { group: { name: entry.group, report: await memberOf(ports.storage, entry.parentID, entry.group, entry.sessionID).then(standingOf, () => "unknown") } }
+        : {};
+    const roster = { directory: entry.directory, isolated: entry.isolated, created: entry.createdAt, ...group };
+    try {
+        return { ...(await status(ports, { sessionID: entry.sessionID })), ...roster };
+    }
+    catch (error) {
+        return {
+            sessionID: entry.sessionID,
+            title: entry.title,
+            ...roster,
+            error: describeFailure("courier_status", error).message,
+        };
+    }
 }
 /** OpenCode leaves a tool call hanging when its metadata holds `undefined`, so results drop those keys. */
 function withoutUndefined(value) {

package/dist/group.d.ts

@@ -0,0 +1,86 @@
+import type { Plugin } from "@opencode/plugin";
+import { type HeldReport, type LeftMember } from "./notices.js";
+import { type Storage } from "./storage.js";
+type Context = Plugin.Context;
+export declare const isGroupName: (value: unknown) => value is string;
+export declare const memberKey: (parentID: string, group: string, sessionID: string) => string;
+/** The key prefix of a parent's groups, and of one group's members. */
+export declare const groupsPrefix: (parentID: string) => string;
+export declare const groupPrefix: (parentID: string, group: string) => string;
+/** A member of a group, as stored: its title for the release notice, and its report or how it left. */
+export interface Member {
+    readonly title: string;
+    readonly joinedAt: number;
+    readonly report?: HeldReport;
+    readonly left?: {
+        readonly at: number;
+        readonly by: LeftMember["by"];
+    };
+}
+/** A member with where it is kept. */
+export interface Membership extends Member {
+    readonly parentID: string;
+    readonly group: string;
+    readonly sessionID: string;
+}
+/** What is known of a member's standing: its report is held, still out, or it left, or it is no longer in an open group. */
+export type Standing = "held" | "out" | LeftMember["by"] | "released";
+/** A member's standing from its stored value, or `released` when there is none. */
+export declare function standingOf(member: Member | undefined): Standing;
+/** The member a session is in a parent's group, if the group is open and it is a member. */
+export declare function memberOf(storage: Pick<Storage, "get">, parentID: string, group: string, sessionID: string): Promise<Member | undefined>;
+/** Makes a spawned session a member of its parent's group, opening the group if it was not. */
+export declare function joinGroup(storage: Pick<Storage, "set">, 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(storage: Pick<Storage, "scan">, 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(storage: Pick<Storage, "set">, 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(storage: Pick<Storage, "scan">, parentID: string, group: string): Promise<{
+    reported: number;
+    members: number;
+    complete: boolean;
+}>;
+/** 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(storage: Pick<Storage, "get">, 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>;
+/**
+ * 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(storage: Pick<Storage, "get" | "set" | "scan">, 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(storage: Pick<Storage, "get" | "set" | "scan">, parentID: string, group: string, sessionID: string, by: LeftMember["by"], at: number): Promise<boolean | undefined>;
+/**
+ * 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(storage: Pick<Storage, "get" | "set">, membership: Membership): Promise<void>;
+/** Drops a member from its group as its roster entry goes, unless its report is held: that still goes to the parent. True when dropped. */
+export declare function dropMember(storage: Pick<Storage, "get" | "remove">, parentID: string, group: string, sessionID: string): Promise<boolean>;
+/** Drops a member from its group whatever it holds: its report could not be held after all, so it goes on its own. */
+export declare function unholdReport(storage: Pick<Storage, "remove">, membership: Membership): Promise<void>;
+/** Drops every group of a parent, whose members' reports can no longer be delivered. */
+export declare function dropGroups(storage: Pick<Storage, "scan" | "remove">, parentID: string): Promise<void>;
+export interface GroupPorts {
+    readonly storage: Storage;
+    readonly session: Pick<Context["session"], "synthetic" | "get">;
+    readonly log: (message: string) => 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>;
+export {};