opencode-courier 0.3.0 → 0.4.1

package/dist/person/rpc-handlers.js

@@ -0,0 +1,62 @@
+import { lineage, subtree } from "../tree/index.js";
+import { pendingOf } from "./permission.js";
+import { answerForPerson, pendingQuestions } from "./question/index.js";
+import { personRpc } from "./rpc.js";
+/**
+ * The permission requests and questions waiting in the courier tree a session is in, from the roster: read from the
+ * top of its lineage down, so each session of the tree sees the same inbox.
+ */
+export async function asks(ports, sessionID) {
+    const { storage } = ports.questions;
+    const top = (await lineage(storage, sessionID)).at(-1)?.parentID ?? sessionID;
+    const { nodes, truncated } = await subtree(storage, top, ports.maxTotal);
+    const waiting = await Promise.all(nodes.map(({ entry }) => Promise.all([
+        pendingOf(ports.permissions(), entry.sessionID).catch(() => []),
+        pendingQuestions(storage, entry.sessionID).catch(() => []),
+    ])));
+    return {
+        top,
+        sessions: nodes.map(({ entry, depth }) => ({
+            sessionID: entry.sessionID,
+            title: entry.title,
+            parentID: entry.parentID,
+            depth,
+            ...(entry.group ? { group: entry.group } : {}),
+        })),
+        permissions: nodes.flatMap(({ entry }, index) => waiting[index][0].flatMap((pending) => pending.type === "permission"
+            ? [
+                {
+                    sessionID: entry.sessionID,
+                    requestID: pending.requestID,
+                    action: pending.action,
+                    resources: pending.resources,
+                    ...(pending.save ? { save: pending.save } : {}),
+                },
+            ]
+            : [])),
+        questions: nodes.flatMap(({ entry }, index) => waiting[index][1].map(({ requestID, questions, stopped }) => ({
+            sessionID: entry.sessionID,
+            requestID,
+            questions,
+            ...(stopped ? { stopped } : {}),
+        }))),
+        ...(truncated ? { truncated: ports.maxTotal } : {}),
+    };
+}
+/** Passes the person's answers to a question on, as courier_answer does; a refusal, such as answers that do not fit, comes back as `problem`. */
+export async function answer(ports, input) {
+    try {
+        const result = await answerForPerson(ports.questions, input);
+        return result.answered ? { answered: true, by: result.by } : { answered: false };
+    }
+    catch (error) {
+        return { answered: false, problem: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** Serves the person's RPC at the plugin's location; disposed with the plugin. */
+export function registerPersonRpc(rpc, ports) {
+    return rpc.register(personRpc, {
+        asks: ({ sessionID }) => asks(ports, sessionID),
+        answer: (input) => answer(ports, input),
+    });
+}

package/dist/person/rpc.d.ts

@@ -0,0 +1,227 @@
+import { Schema } from "effect";
+/** A session of the tree, as the inbox names where an ask comes from. */
+declare const Session: Schema.Struct<{
+    readonly sessionID: Schema.String;
+    readonly title: Schema.String;
+    readonly parentID: Schema.String;
+    /** A child of the tree's top session is at depth 1. */
+    readonly depth: Schema.Int;
+    readonly group: Schema.optionalKey<Schema.String>;
+}>;
+/** A permission request a session of the tree waits on. */
+declare const Permission: Schema.Struct<{
+    readonly sessionID: Schema.String;
+    readonly requestID: Schema.String;
+    readonly action: Schema.String;
+    readonly resources: Schema.$Array<Schema.String>;
+    /** What "always" would allow from now on; absent when it is not offered. */
+    readonly save: Schema.optionalKey<Schema.$Array<Schema.String>>;
+}>;
+/** A question a session of the tree waits on; `stopped` when its call was cut off and the answer goes as a message. */
+declare const Question: Schema.Struct<{
+    readonly sessionID: Schema.String;
+    readonly requestID: Schema.String;
+    readonly questions: Schema.$Array<Schema.Struct<{
+        readonly question: Schema.String;
+        readonly header: Schema.String;
+        readonly options: Schema.$Array<Schema.Struct<{
+            readonly label: Schema.String;
+            readonly description: Schema.String;
+        }>>;
+        readonly multiple: Schema.optionalKey<Schema.Boolean>;
+    }>>;
+    readonly stopped: Schema.optionalKey<Schema.Boolean>;
+}>;
+/** What the sessions of a courier tree wait on the person for, but forms, which the TUI lists itself. */
+declare const Asks: Schema.Struct<{
+    /** The session at the top of the tree, which the sessions below were started from. */
+    readonly top: Schema.String;
+    /** The sessions below the top, in the order a tree is drawn. */
+    readonly sessions: Schema.$Array<Schema.Struct<{
+        readonly sessionID: Schema.String;
+        readonly title: Schema.String;
+        readonly parentID: Schema.String;
+        /** A child of the tree's top session is at depth 1. */
+        readonly depth: Schema.Int;
+        readonly group: Schema.optionalKey<Schema.String>;
+    }>>;
+    readonly permissions: Schema.$Array<Schema.Struct<{
+        readonly sessionID: Schema.String;
+        readonly requestID: Schema.String;
+        readonly action: Schema.String;
+        readonly resources: Schema.$Array<Schema.String>;
+        /** What "always" would allow from now on; absent when it is not offered. */
+        readonly save: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    }>>;
+    readonly questions: Schema.$Array<Schema.Struct<{
+        readonly sessionID: Schema.String;
+        readonly requestID: Schema.String;
+        readonly questions: Schema.$Array<Schema.Struct<{
+            readonly question: Schema.String;
+            readonly header: Schema.String;
+            readonly options: Schema.$Array<Schema.Struct<{
+                readonly label: Schema.String;
+                readonly description: Schema.String;
+            }>>;
+            readonly multiple: Schema.optionalKey<Schema.Boolean>;
+        }>>;
+        readonly stopped: Schema.optionalKey<Schema.Boolean>;
+    }>>;
+    /** Set when the tree had more sessions than `maxTotal`, which were not read. */
+    readonly truncated: Schema.optionalKey<Schema.Int>;
+}>;
+export type Asks = typeof Asks.Type;
+export type AskedQuestion = typeof Question.Type;
+export type AskedPermission = typeof Permission.Type;
+export type TreeSession = typeof Session.Type;
+/** What answering a question did; `problem` says why nothing was passed on, when it was refused. */
+declare const Answered: Schema.Struct<{
+    readonly answered: Schema.Boolean;
+    readonly by: Schema.optionalKey<Schema.Literals<readonly ["result", "message"]>>;
+    readonly problem: Schema.optionalKey<Schema.String>;
+}>;
+export type Answered = typeof Answered.Type;
+export declare const personRpc: {
+    readonly id: "courier-person";
+    readonly methods: {
+        readonly asks: {
+            readonly input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly sessionID: string;
+            }, {
+                readonly sessionID: string;
+            }> & Schema.Struct<{
+                readonly sessionID: Schema.String;
+            }>;
+            readonly output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly questions: readonly {
+                    readonly sessionID: string;
+                    readonly requestID: string;
+                    readonly questions: readonly {
+                        readonly options: readonly {
+                            readonly label: string;
+                            readonly description: string;
+                        }[];
+                        readonly question: string;
+                        readonly header: string;
+                        readonly multiple?: boolean | undefined;
+                    }[];
+                    readonly stopped?: boolean | undefined;
+                }[];
+                readonly sessions: readonly {
+                    readonly sessionID: string;
+                    readonly title: string;
+                    readonly parentID: string;
+                    readonly depth: number;
+                    readonly group?: string | undefined;
+                }[];
+                readonly permissions: readonly {
+                    readonly sessionID: string;
+                    readonly resources: readonly string[];
+                    readonly requestID: string;
+                    readonly action: string;
+                    readonly save?: readonly string[] | undefined;
+                }[];
+                readonly top: string;
+                readonly truncated?: number | undefined;
+            }, {
+                readonly questions: readonly {
+                    readonly sessionID: string;
+                    readonly requestID: string;
+                    readonly questions: readonly {
+                        readonly options: readonly {
+                            readonly label: string;
+                            readonly description: string;
+                        }[];
+                        readonly question: string;
+                        readonly header: string;
+                        readonly multiple?: boolean | undefined;
+                    }[];
+                    readonly stopped?: boolean | undefined;
+                }[];
+                readonly sessions: readonly {
+                    readonly sessionID: string;
+                    readonly title: string;
+                    readonly parentID: string;
+                    readonly depth: number;
+                    readonly group?: string | undefined;
+                }[];
+                readonly permissions: readonly {
+                    readonly sessionID: string;
+                    readonly resources: readonly string[];
+                    readonly requestID: string;
+                    readonly action: string;
+                    readonly save?: readonly string[] | undefined;
+                }[];
+                readonly top: string;
+                readonly truncated?: number | undefined;
+            }> & Schema.Struct<{
+                /** The session at the top of the tree, which the sessions below were started from. */
+                readonly top: Schema.String;
+                /** The sessions below the top, in the order a tree is drawn. */
+                readonly sessions: Schema.$Array<Schema.Struct<{
+                    readonly sessionID: Schema.String;
+                    readonly title: Schema.String;
+                    readonly parentID: Schema.String;
+                    /** A child of the tree's top session is at depth 1. */
+                    readonly depth: Schema.Int;
+                    readonly group: Schema.optionalKey<Schema.String>;
+                }>>;
+                readonly permissions: Schema.$Array<Schema.Struct<{
+                    readonly sessionID: Schema.String;
+                    readonly requestID: Schema.String;
+                    readonly action: Schema.String;
+                    readonly resources: Schema.$Array<Schema.String>;
+                    /** What "always" would allow from now on; absent when it is not offered. */
+                    readonly save: Schema.optionalKey<Schema.$Array<Schema.String>>;
+                }>>;
+                readonly questions: Schema.$Array<Schema.Struct<{
+                    readonly sessionID: Schema.String;
+                    readonly requestID: Schema.String;
+                    readonly questions: Schema.$Array<Schema.Struct<{
+                        readonly question: Schema.String;
+                        readonly header: Schema.String;
+                        readonly options: Schema.$Array<Schema.Struct<{
+                            readonly label: Schema.String;
+                            readonly description: Schema.String;
+                        }>>;
+                        readonly multiple: Schema.optionalKey<Schema.Boolean>;
+                    }>>;
+                    readonly stopped: Schema.optionalKey<Schema.Boolean>;
+                }>>;
+                /** Set when the tree had more sessions than `maxTotal`, which were not read. */
+                readonly truncated: Schema.optionalKey<Schema.Int>;
+            }>;
+        };
+        readonly answer: {
+            readonly input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly sessionID: string;
+                readonly requestID: string;
+                readonly answers: readonly (readonly string[])[];
+            }, {
+                readonly sessionID: string;
+                readonly requestID: string;
+                readonly answers: readonly (readonly string[])[];
+            }> & Schema.Struct<{
+                readonly sessionID: Schema.String;
+                readonly requestID: Schema.String;
+                readonly answers: Schema.$Array<Schema.$Array<Schema.String>>;
+            }>;
+            readonly output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly answered: boolean;
+                readonly by?: "result" | "message" | undefined;
+                readonly problem?: string | undefined;
+            }, {
+                readonly answered: boolean;
+                readonly by?: "result" | "message" | undefined;
+                readonly problem?: string | undefined;
+            }> & Schema.Struct<{
+                readonly answered: Schema.Boolean;
+                readonly by: Schema.optionalKey<Schema.Literals<readonly ["result", "message"]>>;
+                readonly problem: Schema.optionalKey<Schema.String>;
+            }>;
+        };
+    };
+    readonly events: {};
+};
+export type PersonRpc = typeof personRpc;
+export {};

package/dist/person/rpc.js

@@ -0,0 +1,70 @@
+/**
+ * The person's RPC, the contract its TUI part, the asks inbox, and its server half share. Standard Schema values,
+ * as the tree's; imports only `@opencode/plugin/rpc` and `effect`.
+ */
+import { Rpc } from "@opencode/plugin/rpc";
+import { Schema } from "effect";
+const Count = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
+/** A session of the tree, as the inbox names where an ask comes from. */
+const Session = Schema.Struct({
+    sessionID: Schema.String,
+    title: Schema.String,
+    parentID: Schema.String,
+    /** A child of the tree's top session is at depth 1. */
+    depth: Count,
+    group: Schema.optionalKey(Schema.String),
+});
+/** A permission request a session of the tree waits on. */
+const Permission = Schema.Struct({
+    sessionID: Schema.String,
+    requestID: Schema.String,
+    action: Schema.String,
+    resources: Schema.Array(Schema.String),
+    /** What "always" would allow from now on; absent when it is not offered. */
+    save: Schema.optionalKey(Schema.Array(Schema.String)),
+});
+/** One question of OpenCode's question tool. */
+const Prompt = Schema.Struct({
+    question: Schema.String,
+    header: Schema.String,
+    options: Schema.Array(Schema.Struct({ label: Schema.String, description: Schema.String })),
+    multiple: Schema.optionalKey(Schema.Boolean),
+});
+/** A question a session of the tree waits on; `stopped` when its call was cut off and the answer goes as a message. */
+const Question = Schema.Struct({
+    sessionID: Schema.String,
+    requestID: Schema.String,
+    questions: Schema.Array(Prompt),
+    stopped: Schema.optionalKey(Schema.Boolean),
+});
+/** What the sessions of a courier tree wait on the person for, but forms, which the TUI lists itself. */
+const Asks = Schema.Struct({
+    /** The session at the top of the tree, which the sessions below were started from. */
+    top: Schema.String,
+    /** The sessions below the top, in the order a tree is drawn. */
+    sessions: Schema.Array(Session),
+    permissions: Schema.Array(Permission),
+    questions: Schema.Array(Question),
+    /** Set when the tree had more sessions than `maxTotal`, which were not read. */
+    truncated: Schema.optionalKey(Count),
+});
+/** What answering a question did; `problem` says why nothing was passed on, when it was refused. */
+const Answered = Schema.Struct({
+    answered: Schema.Boolean,
+    by: Schema.optionalKey(Schema.Literals(["result", "message"])),
+    problem: Schema.optionalKey(Schema.String),
+});
+export const personRpc = Rpc.define({
+    id: "courier-person",
+    methods: {
+        asks: {
+            input: Schema.toStandardSchemaV1(Schema.Struct({ sessionID: Schema.String })),
+            output: Schema.toStandardSchemaV1(Asks),
+        },
+        answer: {
+            input: Schema.toStandardSchemaV1(Schema.Struct({ sessionID: Schema.String, requestID: Schema.String, answers: Schema.Array(Schema.Array(Schema.String)) })),
+            output: Schema.toStandardSchemaV1(Answered),
+        },
+    },
+    events: {},
+});

package/dist/person/text.d.ts

@@ -0,0 +1,68 @@
+import type { Asked, Elsewhere, Form, Outcome, PermissionAnswered, PermissionRequest, Prompt, QuestionAnswered, Reply, Withdrawal } from "./ports.js";
+/**
+ * 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;
+export declare function answerText(result: AnswerResult): 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, native?: boolean): 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";
+/** 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, where OpenCode shows it.
+ */
+export declare function formNotice(title: string, form: Form, startedBy?: string, shownIn?: string, top?: 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;
+/** 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 native child's question, which OpenCode shows the person in the
+ * top session's own view: they answer it there, so the top session does not ask them again.
+ */
+export declare function nativeQuestionNotice(asked: Asked): 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 {};