opencode-courier 0.2.2 → 0.3.0

package/dist/cleanup.js

@@ -1,46 +1,30 @@
 import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
-import { rosterKey } from "./roster.js";
-/** Why a worktree in this state must be kept, or undefined when removing it loses nothing. */
-export function keepReason(state) {
-    const reasons = [
-        state.changes.length ? `${count(state.changes.length, "uncommitted change")} (${preview(state.changes)})` : "",
-        state.commits.length
-            ? `${count(state.commits.length, "commit")} on no branch, tag or remote (${preview(state.commits)})`
-            : "",
-    ].filter(Boolean);
-    return reasons.length ? reasons.join(" and ") : undefined;
-}
-function count(n, noun) {
-    return `${n} ${noun}${n === 1 ? "" : "s"}`;
-}
+import { isAbsolute } from "node:path";
+import { markLeft, membershipOf } from "./group.js";
+import { keepReason } from "./notices.js";
+import { remove, rosterKey } from "./roster.js";
 /** At most this many changes and commits are returned; the reason still counts them all. */
 export const MAX_LISTED = 50;
-function preview(items) {
-    return items.length > 5 ? `${items.slice(0, 5).join(", ")}, ...` : items.join(", ");
-}
 /**
- * Removes the worktree of an isolated child the parent started, and forgets the child. A worktree
- * with uncommitted changes or commits that exist nowhere else is kept unless `force` is set, and the
- * result says what is in it.
+ * Forgets a child the parent started, removing its worktree if it is isolated. A worktree with uncommitted changes
+ * or commits found nowhere else is kept unless `force` is set; the result says so.
  */
 export async function cleanup(ports, parentID, input) {
     const entry = (await ports.storage.get(rosterKey(parentID, input.sessionID)));
     if (!entry)
         throw new Error(`${input.sessionID} is not on the courier_children list of ${parentID}.`);
-    if (!entry.isolated)
-        throw new Error(`${input.sessionID} ran in ${entry.directory}, not in a worktree of its own; there is nothing to remove.`);
     const { directory } = entry;
-    const forget = () => ports.storage.remove(rosterKey(parentID, input.sessionID));
+    const forget = () => forgetChild(ports, entry);
+    if (!entry.isolated)
+        return { sessionID: input.sessionID, directory, outcome: "forgotten", ...(await forget()) };
     // With force the state only decides whether there is anything left to remove, so a worktree git
     // can no longer read is still removed.
     const state = await ports
         .inspect(directory, entry.base)
         .catch((error) => (input.force ? { changes: [], commits: [] } : Promise.reject(error)));
-    if (!state) {
-        await forget();
-        return { sessionID: input.sessionID, directory, outcome: "gone" };
-    }
+    if (!state)
+        return { sessionID: input.sessionID, directory, outcome: "gone", ...(await forget()) };
     const reason = keepReason(state);
     if (reason && !input.force)
         return {
@@ -56,16 +40,63 @@ export async function cleanup(ports, parentID, input) {
         directory,
         force: input.force === true,
     });
-    await forget();
-    return { sessionID: input.sessionID, directory, outcome: "removed" };
+    return { sessionID: input.sessionID, directory, outcome: "removed", ...(await forget()) };
+}
+/**
+ * Drops a member still out from its group as `dropped`, so the group is released without it, then the roster entry
+ * and report state. A held report stays with its group. Returns the group it was dropped from.
+ */
+async function forgetChild(ports, entry) {
+    const member = entry.group ? await membershipOf(ports.storage, entry.parentID, entry.group, entry.sessionID) : undefined;
+    if (member?.out && (await markLeft(ports.storage, member, "dropped", ports.now())))
+        ports.nudge();
+    await remove(ports.storage, entry.parentID, entry.sessionID);
+    return member?.out ? { group: member.group } : {};
+}
+/** Names the git to run, by absolute path, overriding the places `GIT_LOCATIONS` lists. */
+export const GIT_ENV = "OPENCODE_COURIER_GIT";
+/**
+ * Where git is looked for, in order: its usual install locations, never `PATH`, so a writable
+ * directory early in `PATH` cannot put another program in its place.
+ */
+export const GIT_LOCATIONS = {
+    posix: [
+        "/usr/bin/git",
+        "/usr/local/bin/git",
+        "/opt/homebrew/bin/git",
+        // NixOS, and nix-darwin.
+        "/run/current-system/sw/bin/git",
+    ],
+    win32: [String.raw `C:\Program Files\Git\cmd\git.exe`, String.raw `C:\Program Files (x86)\Git\cmd\git.exe`],
+};
+/**
+ * The git to run: `OPENCODE_COURIER_GIT` when it is an absolute path, otherwise the first of
+ * `GIT_LOCATIONS` that exists. Throws when there is none.
+ */
+export function findGit(env = process.env, platform = process.platform, exists = existsSync) {
+    const named = env[GIT_ENV]?.trim();
+    if (named) {
+        if (!isAbsolute(named))
+            throw new Error(`${GIT_ENV} must be an absolute path, not ${named}.`);
+        return named;
+    }
+    const locations = GIT_LOCATIONS[platform === "win32" ? "win32" : "posix"];
+    const found = locations.find((path) => exists(path));
+    if (!found)
+        throw new Error(`git is in none of ${locations.join(", ")}; set ${GIT_ENV} to its absolute path.`);
+    return found;
 }
 function git(directory, args) {
-    return new Promise((resolve, reject) => execFile("git", ["-C", directory, ...args], { maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => error ? reject(new Error(`git ${args[0]} in ${directory}: ${stderr.trim() || error.message}`)) : resolve(stdout)));
+    return new Promise((resolve, reject) => execFile(findGit(), ["-C", directory, ...args], { maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => error ? reject(new Error(`git ${args[0]} in ${directory}: ${stderr.trim() || error.message}`)) : resolve(stdout)));
 }
 /** The commit a worktree is on, or undefined when git cannot tell. */
 export function headOf(directory) {
     return git(directory, ["rev-parse", "HEAD"]).then((out) => out.trim() || undefined, () => undefined);
 }
+/** Whether a worktree has uncommitted changes, untracked files included; undefined when git cannot tell. */
+export function dirtyOf(directory) {
+    return git(directory, ["status", "--porcelain"]).then((out) => out.trim().length > 0, () => undefined);
+}
 /**
  * Reads a worktree's state with git; undefined when the directory is gone. Commits reachable from
  * `base`, the commit the worktree was made from, are not its own work and are not listed.

package/dist/courier.d.ts

@@ -1,21 +1,31 @@
 import type { Plugin } from "@opencode/plugin";
-import type { Prompt } from "./question.js";
-import { type RosterStorage } from "./roster.js";
+import { type Limits, type SpawnGate } from "./limits.js";
+import { type Artifacts, type Prompt, type Sent, type Status } from "./notices.js";
+import { type RosterEntry, type RosterStorage } from "./roster.js";
 type Context = Plugin.Context;
 /** The slice of the plugin context the courier tools use; tests pass a fake. */
 export interface CourierPorts {
-    readonly session: Pick<Context["session"], "create" | "prompt" | "synthetic" | "get" | "context">;
+    readonly session: Pick<Context["session"], "create" | "prompt" | "synthetic" | "get" | "context" | "interrupt">;
     readonly agent: Pick<Context["agent"], "get">;
     readonly worktree: Pick<Context["worktree"], "create" | "remove">;
     /** The project of the plugin's location; an isolated child's worktree is made in it, and removed from it. */
     readonly projectID: string;
     /** The commit a directory's checkout is on, or undefined; recorded as an isolated child's base. */
     readonly head: (directory: string) => Promise<string | undefined>;
+    /** Whether a directory's checkout has uncommitted changes, or undefined when git cannot tell. */
+    readonly dirty: (directory: string) => Promise<boolean | undefined>;
     readonly storage: RosterStorage;
     readonly directory: string;
     readonly now: () => number;
     /** The permission requests and questions a session waits on, wherever they are pending. */
     readonly pending: (sessionID: string) => Promise<ReadonlyArray<Pending>>;
+    readonly limits: Limits;
+    readonly gate: SpawnGate;
+    /** The depths the `context` hook remembers; a parent's is dropped when it starts a child. */
+    readonly roles: Map<string, number | null>;
+    /** Has the scheduler deliver what is due now rather than at its next tick: a group a report has just completed. */
+    readonly nudge: () => void;
+    readonly log: (message: string) => void;
 }
 /** A request a session waits on until someone answers it: a permission request, or a question it asked. */
 export type Pending = {
@@ -36,10 +46,13 @@ export interface SpawnInput {
     readonly title?: string;
     readonly agent?: string;
     readonly isolate?: boolean;
+    readonly group?: string;
 }
 export interface SendInput {
     readonly sessionID: string;
     readonly message: string;
+    readonly status?: Status;
+    readonly artifacts?: Artifacts;
     readonly queue?: boolean;
 }
 export interface StatusInput {
@@ -48,52 +61,140 @@ export interface StatusInput {
 export interface ChildrenInput {
     readonly sessionID?: string;
 }
-/** Closes a tool result after which the caller most likely has nothing left to do. */
-export declare const END_TURN = "If nothing else is left to do now, end your turn by replying without calling more tools.";
-export declare function childBrief(parentID: string, task: string): string;
-export declare function envelope(from: string, message: string, attributes?: Record<string, string>): string;
-/** 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 declare function spawn(ports: CourierPorts, parentID: string, input: SpawnInput): Promise<{
+    uncommitted?: boolean | undefined;
+    fromParent?: boolean | undefined;
+    groupError?: string | undefined;
     rosterError?: string | undefined;
+    group?: string | undefined;
     sessionID: string;
     directory: string;
 }>;
-/** Drops a message into another session's inbox; OpenCode wakes that session if it is idle. */
-export declare function send(ports: CourierPorts, from: string, input: SendInput): Promise<{
-    messageID: string;
-}>;
+/**
+ * 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 declare function send(ports: CourierPorts, from: string, input: SendInput): Promise<Sent>;
 /** 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" | "succeeded" | "interrupted" | undefined;
+    outcome: "failed" | "interrupted" | "succeeded" | undefined;
     updated: number;
     idle: number | undefined;
     lastText: string | undefined;
     pending: readonly 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 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: string;
+    };
+    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 Pending[] | undefined;
+} | {
+    group?: undefined;
     directory: string;
     isolated: boolean;
     created: number;
     sessionID?: string | undefined;
     title?: string | undefined;
     parentID?: string | undefined;
-    outcome?: "failed" | "succeeded" | "interrupted" | undefined;
+    outcome?: "failed" | "interrupted" | "succeeded" | undefined;
     updated?: number | undefined;
     idle?: number | undefined;
     lastText?: string | undefined;
     pending?: readonly Pending[] | undefined;
 } | {
     error: string;
+    group: {
+        name: string;
+        report: string;
+    };
+    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: string;
+    };
+    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 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 Pending[] | undefined;
+} | {
+    error: string;
+    group: {
+        name: string;
+        report: string;
+    };
+    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 readable message for a failed courier call; OpenCode's own errors can carry an empty message. */
 export declare function describeFailure(tool: string, error: unknown): Error;
 export {};