opencode-courier 0.1.6

package/dist/question.d.ts

@@ -0,0 +1,138 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import type { Plugin as EffectPlugin } from "@opencode-ai/plugin/effect";
+import { Effect } from "effect";
+import { type RosterStorage } from "./roster.js";
+type Context = Plugin.Context;
+/** OpenCode's own question tool, which the relay wraps. */
+export declare const QUESTION_TOOL = "question";
+/** At most this many questions are kept in storage; the oldest go first. */
+export declare const MAX_STORED = 100;
+/** 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;
+};
+/**
+ * Timings, changed by the tests: how long a question cut off by a closing location waits before an
+ * instance still loaded tells its top session, how long an answer waits for another one to it that
+ * is still being passed on, and how long what follows a call's end waits for the notice of the
+ * question to go out.
+ */
+export declare const timing: {
+    closingGraceMs: number;
+    passingWaitMs: number;
+    relayWaitMs: number;
+};
+export interface QuestionPorts {
+    readonly storage: RosterStorage;
+    readonly session: Pick<Context["session"], "synthetic">;
+    readonly now: () => number;
+    readonly newID: () => string;
+    readonly log: (message: string) => void;
+}
+/** Whether a request id is a question's rather than a permission request's. */
+export declare const isQuestion: (requestID: string) => boolean;
+/** 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;
+};
+/** 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?: keyof typeof CUT_OFF): string;
+/** What the top session is told about a question settled without it. */
+export declare function settledNotice(asked: Asked, how: Elsewhere): string;
+export interface QuestionAnswerInput {
+    readonly sessionID: string;
+    readonly requestID: string;
+    /** One entry per question: a label or the text the person gave, or a list of them. */
+    readonly answers: ReadonlyArray<string | ReadonlyArray<string>>;
+}
+/**
+ * Answers a question of a session started, directly or through others, from the caller, which must
+ * be the session at the top, as for permission requests. `answered` is false when it no longer waits.
+ */
+export declare function answerQuestion(ports: QuestionPorts, callerID: string, input: QuestionAnswerInput): Promise<{
+    sessionID: string;
+    requestID: string;
+    answered: boolean;
+    by?: undefined;
+    answers?: undefined;
+} | {
+    sessionID: string;
+    requestID: string;
+    answered: boolean;
+    by: "message" | "result";
+    answers: Answers;
+}>;
+/** The questions a session waits on, for courier_status; `stopped` when its call was cut off. */
+export declare function pendingQuestions(storage: RosterStorage, sessionID: string): Promise<{
+    type: "question";
+    requestID: string;
+    questions: Prompt[];
+    stopped?: true;
+}[]>;
+/**
+ * On loading: drops stored questions that are too old, whose session is no longer on a roster, or
+ * beyond the newest `MAX_STORED`, and tells the top session about the rest, which a restart cut off.
+ */
+export declare function noticeCutOff(ports: QuestionPorts): Promise<void>;
+/** A plugin instance whose ports the relay may use, until the returned function is called. */
+export declare function joinRelay(ports: QuestionPorts): () => undefined;
+/** Called for OpenCode's `form.created`: a question call's form is shown, so its question can be relayed. */
+export declare function formShown(event: {
+    readonly data: {
+        readonly form: {
+            readonly sessionID: string;
+            readonly metadata?: unknown;
+        };
+    };
+}): void;
+/**
+ * Called when an event stream may have missed forms being shown: every call still waiting for its
+ * form is taken as shown. One still waiting for its permission check is relayed early, which is the
+ * lesser harm.
+ */
+export declare function formsMayHaveBeenMissed(): void;
+/**
+ * Called when an instance starts following OpenCode's events. Every instance is sent every event,
+ * so a form shown is missed only while none follows them; then the calls waiting are released, and
+ * true is returned, for the caller to release them again on its first event, once it is connected.
+ */
+export declare function eventsFollowed(): boolean;
+/** Called when an instance's event stream ended or broke. */
+export declare function eventsLeft(): void;
+/** Wraps OpenCode's question tool for the relay. A tool by that id that is missing is left alone. */
+export declare function relayQuestions(host: Pick<EffectPlugin.Context, "tool">, ports: () => QuestionPorts | undefined): Effect.Effect<import("@opencode-ai/plugin/effect/registration").Registration, never, import("effect/Scope").Scope>;
+/** For tests: forgets every question this process knows. */
+export declare function forgetQuestions(): void;
+export {};