opencode-courier 0.3.0 → 0.4.1

package/dist/tree/spawn.js

@@ -0,0 +1,173 @@
+import { describeFailure } from "../kernel/protocol.js";
+import { isGroupName } from "./domain.js";
+import { joinGroup, leaveGroup } from "./group.js";
+import { admit } from "./limits.js";
+import { childStore, groupStore } from "./store.js";
+import { childBrief, childBranch } from "./text.js";
+function titleOf(task) {
+    const line = task.trim().split("\n")[0] ?? "";
+    return line.length > 60 ? `${line.slice(0, 57)}...` : line;
+}
+/**
+ * The model a child runs on: its parent's, so it does not fall back to OpenCode's default, which
+ * the parent may have been moved off for a reason. An agent that names its own model keeps it.
+ */
+async function inheritedModel(ports, parentID, agent) {
+    const parent = await ports.session.get({ sessionID: parentID });
+    if (!parent.model || !agent)
+        return parent.model;
+    const named = await ports.agent.get({ agentID: agent, location: { directory: ports.directory } });
+    return named.data.model ? undefined : parent.model;
+}
+/** Removes a worktree made for a child that was never created; one that cannot be removed stays. */
+async function dropWorktree(ports, directory) {
+    try {
+        await ports.worktree.remove({ projectID: ports.projectID, directory, force: false });
+    }
+    catch {
+        // 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. 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 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 = worktree ? await ports.head(worktree) : undefined;
+    const title = input.title ?? titleOf(input.task);
+    // OpenCode takes a location or a parentID, never both, so an isolated child cannot be a native one.
+    const native = ports.nativeChildren === true && !worktree;
+    const child = await ports.session
+        .create({
+        title,
+        ...(input.agent ? { agent: input.agent } : {}),
+        ...(model ? { model } : {}),
+        ...(worktree ? { location: { directory: worktree } } : {}),
+        // An empty ruleset, not none: a native child would otherwise run on its parent's session rules.
+        ...(native ? { parentID, permissions: [] } : {}),
+        metadata: { courier: { parentID } },
+    })
+        .catch(async (error) => {
+        // No session will ever use the fresh worktree, and nothing records it, so it goes now.
+        if (worktree)
+            await dropWorktree(ports, worktree);
+        throw error;
+    });
+    return {
+        sessionID: child.id,
+        title,
+        directory: worktree ?? child.location.directory,
+        worktree,
+        handedDown,
+        ...(base ? { base } : {}),
+        ...(native ? { native: true } : {}),
+    };
+}
+/**
+ * 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 childStore(ports.storage).indexedEntry(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 childStore(ports.storage).record(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.
+    const children = childStore(ports.storage);
+    if (rostered)
+        await children.prompted(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 children.settled(entry.sessionID, "failed", ports.now()).catch(() => undefined);
+        if (grouped && entry.group)
+            await leaveGroup(groupStore(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) {
+    const groups = groupStore(ports.storage);
+    try {
+        await joinGroup(groups, 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([
+            childStore(ports.storage).record(ungrouped).catch(() => undefined),
+            groups.remove(entry.parentID, group, entry.sessionID).catch(() => undefined),
+        ]);
+        return describeFailure("group", error).message;
+    }
+}

package/dist/tree/status.d.ts

@@ -0,0 +1,128 @@
+import type { Plugin } from "@opencode/plugin";
+import type { CourierPorts, RosterEntry } from "./ports.js";
+type Context = Plugin.Context;
+export interface StatusInput {
+    readonly sessionID: string;
+}
+export interface ChildrenInput {
+    readonly sessionID?: string;
+}
+/** A one-off look at a session, for check-ins; not meant to be called in a loop. */
+export declare function status(ports: CourierPorts, input: StatusInput): Promise<Partial<{
+    sessionID: string;
+    title: string | undefined;
+    parentID: string | undefined;
+    outcome: "failed" | "interrupted" | "succeeded" | undefined;
+    updated: number;
+    idle: number | undefined;
+    lastText: string | undefined;
+    pending: readonly import("./ports.js").Pending[] | undefined;
+}>>;
+/** The text of a session's last reply, from its context's messages, or undefined when it has none. */
+export declare function lastReply(messages: Awaited<ReturnType<Context["session"]["context"]>>): string | 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 declare function listChildren(ports: CourierPorts, parentID: string): Promise<({
+    group: {
+        name: string;
+        report: "failed" | "interrupted" | "deleted" | "dropped" | "held" | "out" | "released" | "unknown";
+    };
+    directory: string;
+    isolated: boolean;
+    created: number;
+    sessionID?: string | undefined;
+    title?: string | undefined;
+    parentID?: string | undefined;
+    outcome?: "failed" | "interrupted" | "succeeded" | undefined;
+    updated?: number | undefined;
+    idle?: number | undefined;
+    lastText?: string | undefined;
+    pending?: readonly import("./ports.js").Pending[] | undefined;
+} | {
+    group?: undefined;
+    directory: string;
+    isolated: boolean;
+    created: number;
+    sessionID?: string | undefined;
+    title?: string | undefined;
+    parentID?: string | undefined;
+    outcome?: "failed" | "interrupted" | "succeeded" | undefined;
+    updated?: number | undefined;
+    idle?: number | undefined;
+    lastText?: string | undefined;
+    pending?: readonly import("./ports.js").Pending[] | undefined;
+} | {
+    error: string;
+    group: {
+        name: string;
+        report: "failed" | "interrupted" | "deleted" | "dropped" | "held" | "out" | "released" | "unknown";
+    };
+    directory: string;
+    isolated: boolean;
+    created: number;
+    sessionID: string;
+    title: string;
+} | {
+    error: string;
+    group?: undefined;
+    directory: string;
+    isolated: boolean;
+    created: number;
+    sessionID: string;
+    title: string;
+})[]>;
+/** One roster entry as courier_children shows it: what courier_status reports with its directory and group standing, or the error it gave. */
+export declare function described(ports: CourierPorts, entry: RosterEntry): Promise<{
+    group: {
+        name: string;
+        report: "failed" | "interrupted" | "deleted" | "dropped" | "held" | "out" | "released" | "unknown";
+    };
+    directory: string;
+    isolated: boolean;
+    created: number;
+    sessionID?: string | undefined;
+    title?: string | undefined;
+    parentID?: string | undefined;
+    outcome?: "failed" | "interrupted" | "succeeded" | undefined;
+    updated?: number | undefined;
+    idle?: number | undefined;
+    lastText?: string | undefined;
+    pending?: readonly import("./ports.js").Pending[] | undefined;
+} | {
+    group?: undefined;
+    directory: string;
+    isolated: boolean;
+    created: number;
+    sessionID?: string | undefined;
+    title?: string | undefined;
+    parentID?: string | undefined;
+    outcome?: "failed" | "interrupted" | "succeeded" | undefined;
+    updated?: number | undefined;
+    idle?: number | undefined;
+    lastText?: string | undefined;
+    pending?: readonly import("./ports.js").Pending[] | undefined;
+} | {
+    error: string;
+    group: {
+        name: string;
+        report: "failed" | "interrupted" | "deleted" | "dropped" | "held" | "out" | "released" | "unknown";
+    };
+    directory: string;
+    isolated: boolean;
+    created: number;
+    sessionID: string;
+    title: string;
+} | {
+    error: string;
+    group?: undefined;
+    directory: string;
+    isolated: boolean;
+    created: number;
+    sessionID: string;
+    title: string;
+}>;
+/** A child's standing in the join group its roster entry names, `unknown` when that cannot be read. */
+export declare function standingIn(ports: Pick<CourierPorts, "storage">, entry: RosterEntry, group: string): Promise<"failed" | "interrupted" | "deleted" | "dropped" | "held" | "out" | "released" | "unknown">;
+export {};

package/dist/tree/status.js

@@ -0,0 +1,62 @@
+import { describeFailure } from "../kernel/protocol.js";
+import { standingOf } from "./domain.js";
+import { current } from "./roster.js";
+import { groupStore } from "./store.js";
+/** A one-off look at a session, for check-ins; not meant to be called in a loop. */
+export async function status(ports, input) {
+    const [info, messages, pending] = await Promise.all([
+        ports.session.get({ sessionID: input.sessionID }),
+        ports.session.context({ sessionID: input.sessionID }),
+        ports.pending(input.sessionID),
+    ]);
+    const lastText = lastReply(messages);
+    return withoutUndefined({
+        sessionID: info.id,
+        title: info.title,
+        parentID: info.parentID,
+        outcome: info.outcome,
+        updated: info.time.updated,
+        idle: info.time.idle,
+        lastText,
+        pending: pending.length ? pending : undefined,
+    });
+}
+/** 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((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 standingIn(ports, entry, entry.group) } } : {};
+    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,
+        };
+    }
+}
+/** A child's standing in the join group its roster entry names, `unknown` when that cannot be read. */
+export function standingIn(ports, entry, group) {
+    return groupStore(ports.storage).member(entry.parentID, group, entry.sessionID).then(standingOf, () => "unknown");
+}
+/** OpenCode leaves a tool call hanging when its metadata holds `undefined`, so results drop those keys. */
+function withoutUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}

package/dist/{stop.d.ts → tree/stop.d.ts}

@@ -1,12 +1,4 @@
-import { type CleanupPorts } from "./cleanup.js";
-import { type CourierPorts } from "./courier.js";
-import { type LaterPorts } from "./later.js";
-import { type CleanupResult } from "./notices.js";
-export interface StopPorts {
-    readonly courier: CourierPorts;
-    readonly later: LaterPorts;
-    readonly cleanup: CleanupPorts;
-}
+import type { CleanupResult, StopPorts } from "./ports.js";
 export interface StopInput {
     readonly sessionID: string;
     readonly cleanup?: boolean;

package/dist/{stop.js → tree/stop.js}

@@ -1,11 +1,9 @@
+import { isNotFound } from "../platform/json.js";
+import { describeFailure, envelope } from "../kernel/protocol.js";
 import { cleanup } from "./cleanup.js";
-import { describeFailure } from "./courier.js";
-import { isNotFound } from "./json.js";
-import { cancel, scheduledFor } from "./later.js";
-import { envelope, stoppedNotice } from "./notices.js";
-import { settled, stopped } from "./report.js";
-import { lineage } from "./roster.js";
-import { subtree } from "./tree.js";
+import { childStore } from "./store.js";
+import { subtree } from "./subtree.js";
+import { stoppedNotice } from "./text.js";
 /** Rounds of looking again for sessions started while others were being stopped. */
 const ROUNDS = 3;
 /**
@@ -15,7 +13,7 @@ const ROUNDS = 3;
 export async function stop(ports, callerID, input) {
     const { storage } = ports.courier;
     const { sessionID } = input;
-    const chain = await lineage(storage, sessionID);
+    const chain = await childStore(storage).lineage(sessionID);
     if (!chain.length)
         throw new Error(`${sessionID} was not started with courier_spawn, so courier_stop cannot stop it.`);
     const target = chain[0];
@@ -57,11 +55,9 @@ function eachDeepestFirst(nodes, act) {
 /** Notes that a session was stopped, so the failure and silent-end notices stay quiet for it, and cancels its pending messages. */
 async function silence(ports, sessionID, cancelled) {
     const { storage, now, log } = ports.courier;
-    await stopped(storage, sessionID, now()).catch((error) => log(`courier_stop: could not note that ${sessionID} was stopped: ${String(error)}`));
+    await childStore(storage).stopped(sessionID, now()).catch((error) => log(`courier_stop: could not note that ${sessionID} was stopped: ${String(error)}`));
     try {
-        const pending = await scheduledFor(storage, sessionID);
-        const dropped = await Promise.all(pending.map(async (later) => ((await cancel(ports.later, later.id)) ? later.id : undefined)));
-        cancelled.push(...dropped.filter((id) => id !== undefined));
+        cancelled.push(...(await ports.cancelScheduled(sessionID)));
     }
     catch (error) {
         log(`courier_stop: could not cancel the messages scheduled for ${sessionID}: ${String(error)}`);
@@ -74,7 +70,7 @@ async function interrupt(ports, { entry, depth }) {
         const { interrupted } = await session.interrupt({ sessionID });
         // The event for it says so too; noted here as well, so the end is settled when this returns.
         if (interrupted)
-            await settled(storage, sessionID, "interrupted", now()).catch(() => undefined);
+            await childStore(storage).settled(sessionID, "interrupted", now()).catch(() => undefined);
         return { sessionID, title, depth, outcome: interrupted ? "interrupted" : "idle" };
     }
     catch (error) {

package/dist/tree/store.d.ts

@@ -0,0 +1,24 @@
+import { type Storage } from "../platform/storage.js";
+import type { ChildStore, GroupStore } from "./ports.js";
+/**
+ * What the reverse index holds for a child: the sessions above it, its parent first and the top
+ * session, which courier_spawn did not start, last; each is the parent of the one before it.
+ */
+export interface ReverseEntry {
+    readonly ancestors: ReadonlyArray<string>;
+}
+export declare function rosterKey(parentID: string, sessionID: string): string;
+export declare function reverseKey(sessionID: string): string;
+export declare const promptKey: (sessionID: string) => string;
+export declare const settledKey: (sessionID: string) => string;
+export declare const progressKey: (sessionID: string) => string;
+export declare const toldKey: (sessionID: string) => string;
+export declare const stoppedKey: (sessionID: string) => 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;
+/** The `ChildStore` over the plugin's storage. */
+export declare function childStore(storage: Storage): ChildStore;
+/** The `GroupStore` over the plugin's storage. */
+export declare function groupStore(storage: Storage): GroupStore;