opencode-courier 0.2.2 → 0.3.0

package/dist/limits.js

@@ -0,0 +1,109 @@
+import { setBounded } from "./bounded.js";
+import { isNotFound, millis, obj } from "./json.js";
+import { childrenRefusal, depthRefusal, ROLE_PREFIX, rolePart, totalRefusal } from "./notices.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);
+/**
+ * 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.
+ */
+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),
+    ]);
+    if (time === null)
+        return false;
+    // One whose first prompt failed never ran, and has no idle time to tell so.
+    const runs = time !== undefined && busy(time) && !report?.ended;
+    return runs || (report?.owes ?? false);
+}
+/**
+ * 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 async function admit(ports, parentID) {
+    const gate = ports.gate;
+    const checked = gate.turn.then(() => check(ports, parentID));
+    gate.turn = checked.catch(() => undefined);
+    const { depth, reservation } = await checked;
+    const release = () => {
+        gate.reserved.delete(reservation);
+    };
+    return { depth, reservation, release };
+}
+async function check(ports, parentID) {
+    const { maxDepth, maxChildren, maxTotal } = ports.limits;
+    const entries = await allEntries(ports.storage);
+    const parents = bySession(entries);
+    const chain = lineageBy(parents, parentID);
+    if (chain.length >= maxDepth)
+        throw new Error(depthRefusal(chain.length, maxDepth));
+    const top = chain.at(-1)?.parentID ?? parentID;
+    const chains = new Map(entries.map((entry) => [entry.sessionID, lineageBy(parents, entry.sessionID)]));
+    const tree = entries.filter((entry) => chains.get(entry.sessionID).at(-1)?.parentID === top);
+    const runs = await Promise.all(tree.map((entry) => live(ports, entry.sessionID)));
+    // A session waiting on a live descendant is live too: the brief tells it to end its turn meanwhile.
+    const active = new Set(tree.filter((_, i) => runs[i]).flatMap((entry) => [entry.sessionID, ...chains.get(entry.sessionID).map((above) => above.parentID)]));
+    const counted = tree.filter((entry) => active.has(entry.sessionID));
+    // A spawn whose child is on the roster already is counted there, if it is live, not by its reservation.
+    const recorded = new Set(tree.map((entry) => entry.sessionID));
+    const pending = [...ports.gate.reserved].filter((held) => held.top === top && !(held.sessionID && recorded.has(held.sessionID)));
+    const mine = counted.filter((entry) => entry.parentID === parentID).length + pending.filter((held) => held.parentID === parentID).length;
+    if (mine >= maxChildren)
+        throw new Error(childrenRefusal(mine, maxChildren));
+    if (counted.length + pending.length >= maxTotal)
+        throw new Error(totalRefusal(counted.length + pending.length, maxTotal));
+    const reservation = { parentID, top };
+    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/notices.d.ts

@@ -0,0 +1,356 @@
+/** 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.";
+/** The limits on the tree of sessions courier_spawn builds, from the plugin's options. */
+export interface Limits {
+    readonly maxDepth: number;
+    readonly maxChildren: number;
+    readonly maxTotal: number;
+}
+/** The statuses a report carries: the task is done, partly done, waits on the parent, or failed. */
+export declare const STATUSES: readonly ["done", "partial", "blocked", "failed"];
+export type Status = (typeof STATUSES)[number];
+export declare const isStatus: (value: unknown) => value is Status;
+/** The one line a session states its split decision in, so a transcript tells a decision from one never made. */
+export declare const SPLIT_LINE = "split: no, because \u2026; considered: <the parts you weighed> or split: <n> parts: \u2026 (one phrase per part)";
+/** The branch an isolated child commits its work on, and names in the `branch` of its report. */
+export declare const childBranch: (sessionID: string) => string;
+/** What a spawned session at `depth` is told; `depth` 1 is a child of a session nobody spawned. `branch` is for an isolated one. */
+export declare function childBrief(parentID: string, task: string, depth: number, limits: Limits, branch?: string): string;
+/** How every part the context hook adds begins, so a second copy of the plugin does not add its own. */
+export declare const ROLE_PREFIX = "opencode-courier role:";
+/**
+ * The system part naming a session's place in its tree: `depth` 0 for a session nobody spawned that
+ * has started one, `null` for one that has started none, which is pointed to the skill. The same on every request.
+ */
+export declare function rolePart(depth: number | null, limits: Limits): string;
+export declare const SKILL_ID = "courier-orchestrate";
+/** Why a model loads the skill, listed with every session's available skills. */
+export declare const SKILL_DESCRIPTION: string;
+/** The skill's text; it names no limits, which the role part and the brief give for the session's own tree. */
+export declare const SKILL_CONTENT: string;
+export declare const depthRefusal: (depth: number, maxDepth: number) => string;
+export declare const childrenRefusal: (running: number, maxChildren: number) => string;
+export declare const totalRefusal: (running: number, maxTotal: number) => string;
+export declare function envelope(from: string, message: string, attributes?: Record<string, string>): string;
+/** What a report lists besides its text; `checks` are the commands the session ran and what each gave. */
+export interface Artifacts {
+    readonly branch?: string;
+    readonly commits?: ReadonlyArray<string>;
+    readonly files?: ReadonlyArray<string>;
+    readonly checks?: ReadonlyArray<{
+        readonly command: string;
+        readonly result: string;
+    }>;
+}
+/**
+ * The body of a report: its text, then the artifacts in a fixed layout, the same for every report,
+ * so a parent finds the branch, the commits, the files and the checks without reading prose.
+ */
+export declare function reportBody(message: string, artifacts: Artifacts | undefined): string;
+export declare function spawnText(child: {
+    readonly sessionID: string;
+    readonly directory: string;
+    readonly group?: string;
+    readonly rosterError?: string;
+    readonly groupError?: string;
+    readonly fromParent?: boolean;
+    readonly uncommitted?: boolean;
+}): string;
+/** A report held with its group: which group, and how many of its members have reported so far, when that could be read. */
+export interface Held {
+    readonly group: string;
+    readonly reported?: number;
+    readonly members?: number;
+}
+/**
+ * What courier_send did; `report` says whether the message was noted as the sender's report to the session
+ * that started it, and `held` that it was held with the sender's group rather than delivered, with no `messageID`.
+ */
+export interface Sent {
+    readonly messageID?: string;
+    readonly status?: Status;
+    readonly report?: boolean;
+    readonly held?: Held;
+}
+/** courier_send's result: for a message to the session that started the sender, whether it was its report. */
+export declare function sendText(sessionID: string, sent?: Pick<Sent, "status" | "report" | "held">): string;
+/** courier_status's result: the session's state, as JSON. */
+export declare const statusText: (status: unknown) => string;
+export declare const childrenText: (listed: ReadonlyArray<unknown>) => string;
+/** What courier_cleanup did: removed the worktree, found it gone, kept it and why, or forgot a child with none; `group`, one it dropped the child from. */
+export type CleanupResult = {
+    readonly sessionID: string;
+    readonly directory: string;
+    readonly outcome: "removed" | "gone" | "forgotten";
+    readonly group?: string;
+} | {
+    readonly sessionID: string;
+    readonly directory: string;
+    readonly outcome: "kept";
+    readonly reason: string;
+    readonly changes: readonly string[];
+    readonly commits: readonly string[];
+};
+export declare function cleanupText(result: CleanupResult): string;
+/** courier_tree's result: the sessions under a session, drawn depth first, as JSON. */
+export declare function treeText(tree: {
+    readonly sessions: ReadonlyArray<unknown>;
+    readonly truncated?: number;
+}): string;
+/** What courier_stop did to each session, and to the messages and worktrees. */
+export declare function stopText(result: {
+    readonly sessionID: string;
+    readonly stopped: ReadonlyArray<{
+        readonly sessionID: string;
+        readonly outcome: string;
+        readonly error?: string;
+    }>;
+    readonly cancelled: ReadonlyArray<string>;
+    readonly cleanup?: ReadonlyArray<CleanupResult | {
+        readonly sessionID: string;
+        readonly outcome: "failed";
+        readonly error: string;
+    }>;
+    readonly told?: string;
+}): string;
+/** What the parent of a stopped session is told when the stop was ordered by a session above both. */
+export declare const stoppedNotice: (title: string, by: string) => string;
+/** Why a worktree in this state must be kept, or undefined when removing it loses nothing. */
+export declare function keepReason(state: {
+    readonly changes: readonly string[];
+    readonly commits: readonly string[];
+}): string | undefined;
+/**
+ * What courier_answer did: a permission request's result carries the reply, a question's whether its
+ * answers went out as the result of its call or, since that call had been cut off, as a message.
+ */
+export type AnswerResult = PermissionAnswered | QuestionAnswered;
+/**
+ * What answering a permission request did; `answered` is false when no location loaded here held the
+ * request: answered already, no longer waited for, or waiting in another server on the same data dir.
+ */
+export interface PermissionAnswered {
+    readonly sessionID: string;
+    readonly requestID: string;
+    readonly reply: Reply;
+    readonly answered: boolean;
+}
+/** What answering a question did; `answered` is false when it no longer waited. */
+export type QuestionAnswered = {
+    readonly sessionID: string;
+    readonly requestID: string;
+    readonly answered: false;
+} | {
+    readonly sessionID: string;
+    readonly requestID: string;
+    readonly answered: true;
+    readonly by: "result" | "message";
+    readonly answers: Answers;
+};
+export declare function answerText(result: AnswerResult): string;
+/** `own` when the message goes to the session that scheduled it. */
+export declare function laterText(entry: {
+    readonly id: string;
+    readonly sessionID: string;
+}, fireAt: string, own: boolean): string;
+export declare const cancelText: (id: string, cancelled: boolean) => string;
+/** `receiving` says whether a webhook receiver runs in this server. */
+export declare function subscribeText(sessionID: string, topic: string, receiving: boolean): string;
+export declare const unsubscribeText: (sessionID: string, dropped: readonly string[]) => string;
+/** The error of OpenCode's `session.execution.failed` event. */
+export interface ExecutionError {
+    readonly type: string;
+    readonly message: string;
+    readonly status?: number;
+}
+export declare function failureNotice(title: string, error: ExecutionError, group?: string): string;
+/**
+ * What the parent is told when a session it started ends its turn without a report to it;
+ * `progressed` when it messaged the parent without a status since its last prompt.
+ */
+export declare function silentNotice(title: string, lastText: string | undefined, progressed?: boolean, group?: string): string;
+/** A report held with its group: its status, text and artifacts, as courier_send was given them, and when. */
+export interface HeldReport {
+    readonly at: number;
+    readonly status: Status;
+    readonly message: string;
+    readonly artifacts?: Artifacts;
+}
+/** A member of a group that left it without a report, and why: its turn failed or was interrupted, it was deleted, or courier_cleanup dropped it. */
+export interface LeftMember {
+    readonly sessionID: string;
+    readonly title: string;
+    readonly by: "failed" | "interrupted" | "deleted" | "dropped";
+}
+/**
+ * What the parent gets when a group it named is released: every report, with its status, text and artifacts in
+ * `reportBody`'s layout, and the members that left without one, in the order they joined.
+ */
+export declare function groupNotice(group: string, reports: ReadonlyArray<HeldReport & {
+    readonly sessionID: string;
+    readonly title: string;
+}>, left?: ReadonlyArray<LeftMember>): string;
+/** The answers to a permission request, as OpenCode's own prompt offers them. */
+export declare const REPLIES: readonly ["once", "always", "reject"];
+export type Reply = (typeof REPLIES)[number];
+/** A permission request, as OpenCode's `permission.asked` event carries it. */
+export interface PermissionRequest {
+    readonly id: string;
+    readonly sessionID: string;
+    readonly action: string;
+    readonly resources: ReadonlyArray<string>;
+    readonly save?: ReadonlyArray<string>;
+    readonly message?: string;
+}
+/**
+ * Sent with a rejection that has no reason of its own. OpenCode ends the child's turn on a bare
+ * rejection, and the child would never report back; with a message, the call fails and it carries on.
+ */
+export declare const REJECTED = "Refused by the session that started you. Do without it, or report back why you cannot.";
+/** How a notice names where the asking session came from, to the session at the top of its lineage. */
+export declare const origin: (startedBy?: string) => string;
+/** For a notice that a session's turn ended without it finishing. */
+export declare const STAYS_QUIET = "and then it does not report back on its own: if it stays quiet, message it with courier_send to have it carry on.";
+/**
+ * What the session at the top is told. `startedBy` names the session that started the asking one
+ * when that is not the top session itself, but one started from it.
+ */
+export declare function permissionNotice(title: string, request: PermissionRequest, startedBy?: string): string;
+/** What the session told about a permission request is told once it is answered without courier_answer. */
+export declare function permissionSettledNotice(title: string, requestID: string, reply: Reply): string;
+/** The `metadata.kind` of the forms OpenCode's web search asks its provider with. */
+export declare const WEBSEARCH_FORM = "websearch.provider";
+/** One field of an OpenCode form, as much of it as a notice shows. */
+export interface FormField {
+    readonly key: string;
+    readonly type: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly options?: ReadonlyArray<{
+        readonly value: string;
+        readonly label: string;
+        readonly description?: string;
+    }>;
+    readonly url?: string;
+    /** Not shown to the person. */
+    readonly hidden?: boolean;
+    /** Conditions on earlier answers; the field is shown only when they hold. */
+    readonly when?: ReadonlyArray<unknown>;
+}
+/** An OpenCode form, as its `form.created` event carries it. */
+export interface Form {
+    readonly id: string;
+    readonly sessionID: string;
+    readonly title: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly fields: ReadonlyArray<FormField>;
+}
+/** A form's `metadata.kind`, when it has one that can go in a notice's envelope. */
+export declare const kindOf: (form: Form) => string | undefined;
+/**
+ * What the session at the top is told about a form OpenCode shows in a session started with
+ * courier_spawn, which the plugin cannot pass on or answer: only the person can, in that session.
+ */
+export declare function formNotice(title: string, form: Form, startedBy?: string): string;
+/** What the session told about a form is told once it is answered or withdrawn. */
+export declare function formSettledNotice(title: string, formID: string, settled: "answered" | "cancelled"): string;
+/** One question of OpenCode's question tool, as the asking model wrote it. */
+export interface Prompt {
+    readonly question: string;
+    readonly header: string;
+    readonly options: ReadonlyArray<{
+        readonly label: string;
+        readonly description: string;
+    }>;
+    readonly multiple?: boolean;
+}
+/** The answers to a question call, as the question tool returns them: one list per question. */
+export type Answers = string[][];
+/** A question a spawned session asked with its question tool, stored until it is answered. */
+export interface Asked {
+    readonly requestID: string;
+    readonly sessionID: string;
+    /** The session told, at the top of the sessions started with courier_spawn; it alone answers. */
+    readonly top: string;
+    readonly title: string;
+    /** The session that started the asking one, when that is not the top session itself. */
+    readonly startedBy?: string;
+    readonly questions: ReadonlyArray<Prompt>;
+    readonly askedAt: number;
+}
+/** How a question was settled without the top session: in the asking session, or not at all. */
+export type Elsewhere = {
+    readonly by: "child";
+    readonly answers: Answers;
+} | {
+    readonly by: "dismissed";
+} | {
+    readonly by: "failed";
+    readonly error: string;
+};
+/** What the top session's answer does to a call that waits: answers it, or dismisses it. */
+export type Outcome = {
+    readonly answers: Answers;
+} | {
+    readonly dismissed: true;
+};
+/**
+ * Why a linked call is withdrawn: its question was settled elsewhere, or the top session's outcome
+ * reached it another way (courier_answer, or a dismissal through an earlier call linked to it).
+ */
+export type Withdrawal = Elsewhere | {
+    readonly by: "top";
+    readonly outcome: Outcome;
+};
+/** What OpenCode's question tool tells the asking model once it has the answers. */
+export declare function answeredText(questions: ReadonlyArray<Prompt>, answers: ReadonlyArray<ReadonlyArray<string>>): string;
+declare const CUT_OFF: {
+    stopped: string;
+    restarted: string;
+};
+/** Why a question's call was cut off: its turn was stopped, or OpenCode restarted or closed its location. */
+export type CutOff = keyof typeof CUT_OFF;
+/** What the top session is told about a question, when it is asked or after its call was cut off. */
+export declare function questionNotice(asked: Asked, cutOff?: CutOff): string;
+/** What the top session is told about a question settled without it. */
+export declare function questionSettledNotice(asked: Asked, how: Elsewhere): string;
+/** The result of a spawned session's question call that the person dismissed through the top session. */
+export declare const DISMISSED = "The person dismissed this question without answering it. Carry on without the answers, or report back with courier_send to the session that started you why you cannot.";
+/** The message a spawned session whose question call was cut off gets, with the top session's outcome. */
+export declare function cutOffAnswer(asked: Asked, outcome: Outcome): string;
+/**
+ * What a top session's question call that no waiting question was linked to adds to its result, when
+ * questions with the same choices wait: `waiting` lists them.
+ */
+export declare function unlinkedNote(waiting: ReadonlyArray<Pick<Asked, "sessionID" | "requestID">>): string;
+/** The result of a linked call withdrawn because its question was settled without it. */
+export declare function withdrawnText(linked: Asked, how: Withdrawal): string;
+/**
+ * What a linked call adds to the person's answers about passing them on: `passed` is "result",
+ * "message", undefined when it no longer waited, or the error as `error: <message>`.
+ */
+export declare function passedNote(linked: Asked, passed: string | undefined): string;
+export declare function clipText(text: string, max?: number): string;
+/** The GitHub CI events, with how a summary names each. */
+export declare const CI_EVENTS: Record<string, string>;
+/** What every GitHub delivery carries, read once for the summary of its event. */
+export interface Delivery {
+    readonly name: string;
+    readonly body: Record<string, any>;
+    readonly repo: string;
+    readonly action: string | undefined;
+    readonly sender: string | undefined;
+    /** ` by <sender>`, or nothing when the delivery names no sender. */
+    readonly by: string;
+    /** The pull request and issue numbers it concerns, which `webhook.ts` reads for its topics. */
+    readonly numbers: readonly number[];
+}
+/** The summary of a GitHub delivery that wakes its subscribers. */
+export declare function githubSummary(delivery: Delivery): string;
+/** The summary of a delivery to `/hook/<name>`: its text, clipped. */
+export declare const hookSummary: (text: string) => string;
+/** Defuses `<courier` and `</courier>` in outside text, so it cannot close the envelope or forge another. */
+export declare function defuse(text: string): string;
+/** The text a subscribed session is woken with for a webhook delivery, before its envelope. */
+export declare const webhookText: (summary: string) => string;
+export {};