opencode-courier 0.1.6

package/dist/cleanup.d.ts

@@ -0,0 +1,59 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import { type RosterStorage } from "./roster.js";
+type Context = Plugin.Context;
+/** What would be lost by removing a worktree. */
+export interface WorktreeState {
+    /** Paths with uncommitted changes, untracked files included, as `git status --porcelain` lists them. */
+    readonly changes: readonly string[];
+    /**
+     * Commits reachable from the worktree's HEAD but from no branch, tag or remote-tracking ref, nor
+     * from the commit the worktree was made from, newest first.
+     */
+    readonly commits: readonly string[];
+}
+export interface CleanupPorts {
+    readonly storage: RosterStorage;
+    readonly worktree: Pick<Context["worktree"], "remove">;
+    /** The plugin's own location, for roster entries recorded before they carried their source. */
+    readonly directory: string;
+    /** The worktree's state, or undefined when its directory no longer exists; `base` is the commit it was made from. */
+    readonly inspect: (directory: string, base?: string) => Promise<WorktreeState | undefined>;
+}
+export interface CleanupInput {
+    readonly sessionID: string;
+    readonly force?: boolean;
+}
+export type CleanupResult = {
+    readonly sessionID: string;
+    readonly directory: string;
+    readonly outcome: "removed";
+} | {
+    readonly sessionID: string;
+    readonly directory: string;
+    readonly outcome: "gone";
+} | {
+    readonly sessionID: string;
+    readonly directory: string;
+    readonly outcome: "kept";
+    readonly reason: string;
+    readonly changes: readonly string[];
+    readonly commits: readonly string[];
+};
+/** Why a worktree in this state must be kept, or undefined when removing it loses nothing. */
+export declare function keepReason(state: WorktreeState): string | undefined;
+/** At most this many changes and commits are returned; the reason still counts them all. */
+export declare const MAX_LISTED = 50;
+/**
+ * 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.
+ */
+export declare function cleanup(ports: CleanupPorts, parentID: string, input: CleanupInput): Promise<CleanupResult>;
+/** The commit a worktree is on, or undefined when git cannot tell. */
+export declare function headOf(directory: string): Promise<string | 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.
+ */
+export declare function inspectWorktree(directory: string, base?: string): Promise<WorktreeState | undefined>;
+export {};

package/dist/cleanup.js

@@ -0,0 +1,98 @@
+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"}`;
+}
+/** 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.
+ */
+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));
+    // 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" };
+    }
+    const reason = keepReason(state);
+    if (reason && !input.force)
+        return {
+            sessionID: input.sessionID,
+            directory,
+            outcome: "kept",
+            reason,
+            changes: state.changes.slice(0, MAX_LISTED),
+            commits: state.commits.slice(0, MAX_LISTED),
+        };
+    await ports.worktree.remove({
+        location: { directory: entry.source ?? ports.directory },
+        directory,
+        force: input.force === true,
+    });
+    await forget();
+    return { sessionID: input.sessionID, directory, outcome: "removed" };
+}
+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)));
+}
+/** 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);
+}
+/**
+ * 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.
+ */
+export async function inspectWorktree(directory, base) {
+    if (!existsSync(directory))
+        return undefined;
+    // An untracked directory is one entry, not every file in it.
+    const status = await git(directory, ["status", "--porcelain=v1", "-z", "--untracked-files=normal"]);
+    const changes = [];
+    const records = status.split("\0").filter(Boolean);
+    for (let i = 0; i < records.length; i++) {
+        const record = records[i];
+        changes.push(record.slice(3));
+        // A rename or copy is followed by its source path in a record of its own.
+        if ("RC".includes(record[0]) || "RC".includes(record[1]))
+            i++;
+    }
+    const log = await git(directory, [
+        "log",
+        "--format=%h %s",
+        "HEAD",
+        "--not",
+        "--branches",
+        "--tags",
+        "--remotes",
+        ...(base ? [base] : []),
+    ]);
+    return { changes, commits: log.split("\n").filter(Boolean) };
+}

package/dist/courier.d.ts

@@ -0,0 +1,97 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import type { Prompt } from "./question.js";
+import { 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 agent: Pick<Context["agent"], "get">;
+    readonly worktree: Pick<Context["worktree"], "create" | "remove">;
+    /** The commit a directory's checkout is on, or undefined; recorded as an isolated child's base. */
+    readonly head: (directory: string) => Promise<string | 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>>;
+}
+/** A request a session waits on until someone answers it: a permission request, or a question it asked. */
+export type Pending = {
+    readonly type: "permission";
+    readonly requestID: string;
+    readonly action: string;
+    readonly resources: ReadonlyArray<string>;
+    readonly save?: ReadonlyArray<string>;
+} | {
+    readonly type: "question";
+    readonly requestID: string;
+    readonly questions: ReadonlyArray<Prompt>;
+    /** Its question call was cut off; the answer reaches it as a message. */
+    readonly stopped?: true;
+};
+export interface SpawnInput {
+    readonly task: string;
+    readonly title?: string;
+    readonly agent?: string;
+    readonly isolate?: boolean;
+}
+export interface SendInput {
+    readonly sessionID: string;
+    readonly message: string;
+    readonly queue?: boolean;
+}
+export interface StatusInput {
+    readonly sessionID: string;
+}
+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. */
+export declare function spawn(ports: CourierPorts, parentID: string, input: SpawnInput): Promise<{
+    rosterError?: 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;
+}>;
+/** 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;
+    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. */
+export declare function listChildren(ports: CourierPorts, parentID: string): Promise<({
+    directory: string;
+    isolated: boolean;
+    created: number;
+    sessionID?: string | undefined;
+    title?: string | undefined;
+    parentID?: string | undefined;
+    outcome?: "failed" | "succeeded" | "interrupted" | undefined;
+    updated?: number | undefined;
+    idle?: number | undefined;
+    lastText?: string | undefined;
+    pending?: readonly Pending[] | undefined;
+} | {
+    error: string;
+    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 {};

package/dist/courier.js

@@ -0,0 +1,143 @@
+import { current, record } from "./roster.js";
+/** Closes a tool result after which the caller most likely has nothing left to do. */
+export const END_TURN = "If nothing else is left to do now, end your turn by replying without calling more tools.";
+export function childBrief(parentID, task) {
+    return [
+        `You were started by session ${parentID} through opencode-courier.`,
+        "",
+        `When you finish, or need a decision you cannot make yourself, call courier_send with sessionID "${parentID}" and a short report.`,
+        "That message wakes the parent. It is the only way the parent hears from you, so do not end without sending it.",
+        "If you need the person to decide something, use your question tool; it reaches them through the session that started you.",
+        "",
+        "Task:",
+        task,
+    ].join("\n");
+}
+export function envelope(from, message, attributes = {}) {
+    const extra = Object.entries(attributes)
+        .map(([name, value]) => ` ${name}="${value}"`)
+        .join("");
+    return `<courier from="${from}"${extra}>\n${message}\n</courier>`;
+}
+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;
+}
+/** Creates a child session, hands it the task and returns at once; the child reports back with courier_send. */
+export async function spawn(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({ location: { directory: ports.directory } })).directory
+        : undefined;
+    const base = directory ? await ports.head(directory) : 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 } } : {}),
+        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 ports.worktree
+                .remove({ location: { directory: ports.directory }, directory, force: false })
+                .catch(() => undefined);
+        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 } : {}),
+        ...(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 } : {}),
+    };
+}
+/** Drops a message into another session's inbox; OpenCode wakes that session if it is idle. */
+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 };
+}
+/** 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 last = messages.findLast((message) => message.type === "assistant");
+    const lastText = last?.type === "assistant"
+        ? last.content.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("")
+        : undefined;
+    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 sessions a parent started, each with what courier_status reports, or the error it gave. */
+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,
+            };
+        }
+    }));
+}
+/** 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));
+}
+/** A readable message for a failed courier call; OpenCode's own errors can carry an empty message. */
+export function describeFailure(tool, error) {
+    const tagged = error;
+    const message = (typeof tagged?.message === "string" && tagged.message) ||
+        [tagged?._tag, tagged?.sessionID].filter((item) => typeof item === "string").join(" ") ||
+        String(error);
+    return new Error(`${tool} failed: ${message}`);
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import { Plugin } from "@opencode-ai/plugin";
+import { Plugin as EffectPlugin } from "@opencode-ai/plugin/effect";
+import { type QuestionPorts } from "./question.js";
+/** What a question relay needs from the plugin instance that wraps the question tool. */
+export interface RelaySlot {
+    ports?: QuestionPorts;
+}
+/**
+ * The courier tools, scheduler, webhook receiver and event watcher, as a promise plugin. `relay`
+ * receives this instance's ports for the question relay while it is loaded.
+ */
+export declare const courier: (relay?: RelaySlot) => Plugin.Plugin;
+/**
+ * The plugin OpenCode loads. It is an Effect plugin, because the question relay wraps OpenCode's own
+ * question tool, whose execute the promise API hands out only as a promise that cannot be
+ * interrupted, so a child's question could not be withdrawn once its parent answered. Everything
+ * else is the promise plugin above, run through the plugin package's own adapter, as OpenCode runs
+ * a promise plugin.
+ */
+declare const _default: EffectPlugin.Plugin<import("effect/Scope").Scope>;
+export default _default;