opencode-courier 0.4.1 → 0.6.0

package/dist/person/rpc-handlers.js

@@ -1,15 +1,16 @@
 import { lineage, subtree } from "../tree/index.js";
-import { pendingOf } from "./permission.js";
+import { ownRequests, 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.
+ * The permission requests and questions waiting in the courier tree a session is in, the top's own requests first, read from the
+ * roster 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 { nodes } = await subtree(storage, top, { now: ports.questions.now() });
+    const own = nodes.length ? await ownRequests(ports.permissions(), top).catch(() => []) : [];
     const waiting = await Promise.all(nodes.map(({ entry }) => Promise.all([
         pendingOf(ports.permissions(), entry.sessionID).catch(() => []),
         pendingQuestions(storage, entry.sessionID).catch(() => []),
@@ -23,24 +24,33 @@ export async function asks(ports, sessionID) {
             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 } : {}),
-                },
-            ]
-            : [])),
+        permissions: [
+            ...own.map(({ request, passesOn }) => ({
+                sessionID: top,
+                requestID: request.id,
+                action: request.action,
+                resources: [...request.resources],
+                ...(request.save?.length ? { save: [...request.save] } : {}),
+                ...(passesOn ? { passesOn } : {}),
+            })),
+            ...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`. */

package/dist/person/rpc.d.ts

@@ -8,7 +8,7 @@ declare const Session: Schema.Struct<{
     readonly depth: Schema.Int;
     readonly group: Schema.optionalKey<Schema.String>;
 }>;
-/** A permission request a session of the tree waits on. */
+/** A permission request a session of the tree, the top among them, waits on. */
 declare const Permission: Schema.Struct<{
     readonly sessionID: Schema.String;
     readonly requestID: Schema.String;
@@ -16,6 +16,11 @@ declare const Permission: Schema.Struct<{
     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>>;
+    /** The request below that allowing this one passes on: the top's courier_answer prompt. */
+    readonly passesOn: Schema.optionalKey<Schema.Struct<{
+        readonly sessionID: Schema.String;
+        readonly requestID: 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<{
@@ -45,6 +50,7 @@ declare const Asks: Schema.Struct<{
         readonly depth: Schema.Int;
         readonly group: Schema.optionalKey<Schema.String>;
     }>>;
+    /** The top session's own requests first, then those of the sessions below. */
     readonly permissions: Schema.$Array<Schema.Struct<{
         readonly sessionID: Schema.String;
         readonly requestID: Schema.String;
@@ -52,6 +58,11 @@ declare const Asks: Schema.Struct<{
         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>>;
+        /** The request below that allowing this one passes on: the top's courier_answer prompt. */
+        readonly passesOn: Schema.optionalKey<Schema.Struct<{
+            readonly sessionID: Schema.String;
+            readonly requestID: Schema.String;
+        }>>;
     }>>;
     readonly questions: Schema.$Array<Schema.Struct<{
         readonly sessionID: Schema.String;
@@ -67,8 +78,6 @@ declare const Asks: Schema.Struct<{
         }>>;
         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;
@@ -93,20 +102,7 @@ export declare const personRpc: {
                 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 top: string;
                 readonly sessions: readonly {
                     readonly sessionID: string;
                     readonly title: string;
@@ -120,10 +116,11 @@ export declare const personRpc: {
                     readonly requestID: string;
                     readonly action: string;
                     readonly save?: readonly string[] | undefined;
+                    readonly passesOn?: {
+                        readonly sessionID: string;
+                        readonly requestID: string;
+                    } | undefined;
                 }[];
-                readonly top: string;
-                readonly truncated?: number | undefined;
-            }, {
                 readonly questions: readonly {
                     readonly sessionID: string;
                     readonly requestID: string;
@@ -138,6 +135,8 @@ export declare const personRpc: {
                     }[];
                     readonly stopped?: boolean | undefined;
                 }[];
+            }, {
+                readonly top: string;
                 readonly sessions: readonly {
                     readonly sessionID: string;
                     readonly title: string;
@@ -151,9 +150,25 @@ export declare const personRpc: {
                     readonly requestID: string;
                     readonly action: string;
                     readonly save?: readonly string[] | undefined;
+                    readonly passesOn?: {
+                        readonly sessionID: string;
+                        readonly requestID: string;
+                    } | 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 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;
@@ -166,6 +181,7 @@ export declare const personRpc: {
                     readonly depth: Schema.Int;
                     readonly group: Schema.optionalKey<Schema.String>;
                 }>>;
+                /** The top session's own requests first, then those of the sessions below. */
                 readonly permissions: Schema.$Array<Schema.Struct<{
                     readonly sessionID: Schema.String;
                     readonly requestID: Schema.String;
@@ -173,6 +189,11 @@ export declare const personRpc: {
                     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>>;
+                    /** The request below that allowing this one passes on: the top's courier_answer prompt. */
+                    readonly passesOn: Schema.optionalKey<Schema.Struct<{
+                        readonly sessionID: Schema.String;
+                        readonly requestID: Schema.String;
+                    }>>;
                 }>>;
                 readonly questions: Schema.$Array<Schema.Struct<{
                     readonly sessionID: Schema.String;
@@ -188,8 +209,6 @@ export declare const personRpc: {
                     }>>;
                     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: {

package/dist/person/rpc.js

@@ -14,7 +14,7 @@ const Session = Schema.Struct({
     depth: Count,
     group: Schema.optionalKey(Schema.String),
 });
-/** A permission request a session of the tree waits on. */
+/** A permission request a session of the tree, the top among them, waits on. */
 const Permission = Schema.Struct({
     sessionID: Schema.String,
     requestID: Schema.String,
@@ -22,6 +22,8 @@ const Permission = Schema.Struct({
     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)),
+    /** The request below that allowing this one passes on: the top's courier_answer prompt. */
+    passesOn: Schema.optionalKey(Schema.Struct({ sessionID: Schema.String, requestID: Schema.String })),
 });
 /** One question of OpenCode's question tool. */
 const Prompt = Schema.Struct({
@@ -43,10 +45,9 @@ const Asks = Schema.Struct({
     top: Schema.String,
     /** The sessions below the top, in the order a tree is drawn. */
     sessions: Schema.Array(Session),
+    /** The top session's own requests first, then those of the sessions below. */
     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({

package/dist/person/text.d.ts

@@ -10,6 +10,11 @@ export declare function answerText(result: AnswerResult): string;
  * 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.";
+/**
+ * The failure of a courier_answer whose proposed once OpenCode refused in the caller's session: a rule
+ * denies the action there, or the person rejected the prompt with a reason, which the child was given.
+ */
+export declare function refusedText(sessionID: string, requestID: string, reason: string): string;
 /** 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. */

package/dist/person/text.js

@@ -12,8 +12,10 @@ export function answerText(result) {
     if (!result.answered)
         return (`${result.sessionID} no longer waits on question ${result.requestID}: it was answered some other way, or the ` +
             "session stopped waiting. Nothing was passed on; tell the person their answer is not needed.");
+    if ("reply" in result && result.reply === "reject")
+        return `Passed on reject for request ${result.requestID} of ${result.sessionID}; its call fails and it carries on, and reports back with courier_send. ${END_TURN}`;
     if ("reply" in result)
-        return `Passed on ${result.reply} for request ${result.requestID} of ${result.sessionID}, which carries on and reports back with courier_send. ${END_TURN}`;
+        return `Allowed in your session, by the person in OpenCode's prompt or by your rules, and passed on ${result.reply} for request ${result.requestID} of ${result.sessionID}, which carries on and reports back with courier_send. ${END_TURN}`;
     const how = result.by === "message" ? " as a message, since its question had been cut off" : "";
     return `Passed the answers to question ${result.requestID} on to ${result.sessionID}${how}; it carries on and reports back with courier_send. ${END_TURN}`;
 }
@@ -23,16 +25,16 @@ export function answerText(result) {
  * rejection, and the child would never report back; with a message, the call fails and it carries on.
  */
 export const REJECTED = "Refused by the session that started you. Do without it, or report back why you cannot.";
+/**
+ * The failure of a courier_answer whose proposed once OpenCode refused in the caller's session: a rule
+ * denies the action there, or the person rejected the prompt with a reason, which the child was given.
+ */
+export function refusedText(sessionID, requestID, reason) {
+    return `not allowed in your session (${reason}). The refusal was passed on with that reason to request ${requestID} of ${sessionID}, so its call fails and it carries on; it reports back with courier_send. Tell the person, and do not propose it again unless they ask.`;
+}
 const MAX_RESOURCES = 20;
 const MAX_RESOURCE_LENGTH = 300;
 const clip = (text) => (text.length > MAX_RESOURCE_LENGTH ? `${text.slice(0, MAX_RESOURCE_LENGTH - 3)}...` : text);
-function alwaysChoice(request) {
-    const save = request.save ?? [];
-    if (!save.length)
-        return [];
-    const scope = save.length === 1 && save[0] === "*" ? `every ${request.action} request` : `requests matching ${save.join(", ")}`;
-    return [`- always: allow it, and from now on ${scope} in this project`];
-}
 /** How a notice names where the asking session came from, to the session at the top of its lineage. */
 export const origin = (startedBy) => startedBy ? `which ${startedBy} started with courier_spawn, a session started from yours,` : "which you started with courier_spawn,";
 /** For a notice that a session's turn ended without it finishing. */
@@ -51,21 +53,21 @@ export function permissionNotice(title, request, startedBy, native = false) {
         ...(resources.length ? ["On:", ...resources] : []),
         ...(request.message ? [`Note: ${request.message}`] : []),
         "",
-        ...(native ? NATIVE_PERMISSION : PERMISSION_ASK),
-        "- once: allow this request only",
-        ...alwaysChoice(request),
-        "- reject: refuse it, with a reason if they give one; the session's call fails and it carries on",
-        `When they have chosen, call courier_answer with sessionID "${request.sessionID}", requestID "${request.id}", reply set to their choice and, with reject, message set to their reason.`,
+        ...(native ? nativePermission(request) : permissionAsk(request)),
     ].join("\n");
 }
-const PERMISSION_ASK = [
-    "Do not decide this yourself. Ask the person you are working with (with your question tool, if you have one), offering exactly these choices:",
+const permissionAsk = (request) => [
+    "You cannot decide this: the person you are working with does, in OpenCode's own permission prompt, which opens in your session when you propose once. Do not ask them in your reply or with your question tool first; propose one of these:",
+    "- once: allow this request only; OpenCode first asks the person in your session, under your permission rules, and it is passed on only once they have allowed it",
+    "- reject: refuse it, with a reason if the person gave one; the session's call fails and it carries on",
+    `Call courier_answer with sessionID "${request.sessionID}", requestID "${request.id}", reply set to the choice and, with reject, message set to the reason.`,
+    "Propose once unless the person has told you to refuse it, or the request plainly goes against what they asked of you; with once, the call returns when they have answered the prompt (or your rules allow the action without one). A refusal there with a reason fails the call with it, which the session is given; one without a reason ends your turn, and the session waits on.",
 ];
-/** For a native child's request, which OpenCode shows the person itself, in the top session's view. */
-const NATIVE_PERMISSION = [
+/** For a native child's request, which OpenCode shows the person itself, in the top session's view: nothing to call. */
+const nativePermission = (request) => [
     "OpenCode already shows this request to the person you are working with, as its own permission prompt in your session (and in the paired app's request dock), where they answer it; you will be told once it is answered.",
-    "Do not ask them yourself, with your question tool or in your reply, and do not decide it: at most tell them in one line that this session waits on their permission, then end your turn.",
-    "Only if they ask you to answer it for them, these are the choices:",
+    "Do not ask them yourself, with your question tool or in your reply, and do not call courier_answer for it, which would only ask them a second time: at most tell them in one line that this session waits on their permission, then end your turn.",
+    `Only if they tell you to answer it for them, call courier_answer with sessionID "${request.sessionID}", requestID "${request.id}" and reply set to once or reject (with reject, message set to the reason); with once, OpenCode asks them again in your session before it is passed on.`,
 ];
 /** What the session told about a permission request is told once it is answered without courier_answer. */
 export function permissionSettledNotice(title, requestID, reply) {

package/dist/person/tools.d.ts

@@ -5,7 +5,7 @@ import { type QuestionPorts } from "./question/index.js";
 export declare const AnswerInput: Schema.Struct<{
     readonly sessionID: Schema.String;
     readonly requestID: Schema.String;
-    readonly reply: Schema.optional<Schema.Literals<readonly ["once", "always", "reject"]>>;
+    readonly reply: Schema.optional<Schema.Literals<readonly ["once", "reject"]>>;
     readonly message: Schema.optional<Schema.String>;
     readonly answers: Schema.optional<Schema.$Array<Schema.Union<readonly [Schema.String, Schema.$Array<Schema.String>]>>>;
 }>;

package/dist/person/tools.js

@@ -1,22 +1,23 @@
 import { Schema } from "effect";
 import { rethrow } from "../kernel/tool.js";
-import { answer, REPLIES } from "./permission.js";
+import { answer, isDeclined, PROPOSALS } from "./permission.js";
 import { answerQuestion, isQuestion } from "./question/index.js";
 import { answerText } from "./text.js";
 export const AnswerInput = Schema.Struct({
     sessionID: Schema.String.annotate({ description: "The session you started that is waiting, as its notice names it." }),
     requestID: Schema.String.annotate({ description: "The request id from the notice." }),
-    reply: Schema.optional(Schema.Literals(REPLIES).annotate({
-        description: "For a permission request: the choice the person made, once, always (only when the notice offers it) or reject.",
+    reply: Schema.optional(Schema.Literals(PROPOSALS).annotate({
+        description: "For a permission request: the answer you propose, once or reject. With once, OpenCode first asks the person in " +
+            "your session, and it is passed on only once they have allowed it; always is not granted through this tool.",
     })),
-    message: Schema.optional(Schema.String.annotate({ description: "For a permission request, with reject: the person's reason, passed on with the refusal." })),
+    message: Schema.optional(Schema.String.annotate({ description: "For a permission request, with reject: the reason, passed on with the refusal." })),
     answers: Schema.optional(Schema.Array(Schema.Union([Schema.String, Schema.Array(Schema.String)])).annotate({
         description: "For a question: one entry per question, in order, each the label the person chose or the text they gave, " +
             "or a list of labels where the question allows several.",
     })),
 });
 // One tool answers both: a question's id is the plugin's own, a permission request's OpenCode's.
-async function answerRequest(ports, callerID, input) {
+async function answerRequest(ports, callerID, input, call) {
     const { sessionID, requestID } = input;
     if (isQuestion(requestID)) {
         if (input.reply !== undefined || input.message !== undefined)
@@ -26,14 +27,15 @@ async function answerRequest(ports, callerID, input) {
         return answerQuestion(ports.questions, callerID, { sessionID, requestID, answers: input.answers });
     }
     if (input.answers !== undefined)
-        throw new Error(`${requestID} is a permission request: pass the person's choice in reply (once, always or reject), not answers.`);
+        throw new Error(`${requestID} is a permission request: pass the answer you propose in reply (once or reject), not answers.`);
     if (input.reply === undefined)
-        throw new Error(`${requestID} is a permission request: reply is required, once, always or reject.`);
+        throw new Error(`${requestID} is a permission request: reply is required, once or reject.`);
     return answer(ports.answer, ports.waiting, callerID, {
         sessionID,
         requestID,
         reply: input.reply,
         ...(input.message !== undefined ? { message: input.message } : {}),
+        ...(call ? { call } : {}),
     });
 }
 /** Adds `courier_answer`. */
@@ -42,13 +44,22 @@ export function addPersonTools(tools, ports) {
         name: "courier_answer",
         options: { codemode: false },
         description: "Pass on the answer to a permission request or a question that a session you started with courier_spawn (or " +
-            "one started from it) waits on, after a notice from it named the request. The answer is the person's, not yours: " +
-            "first ask the person you are working with, offering the choices the notice lists, then call this with what " +
-            "they chose: reply for a permission request, answers for a question. Never choose for them. The session " +
-            "carries on once it has the answer.",
+            "one started from it) waits on, after a notice from it named the request. For a permission request, reply is " +
+            "the answer you propose, once or reject: proposing is not deciding. With once, OpenCode asks the person you are " +
+            "working with in your session, as its own permission prompt for what that session asked, under your permission " +
+            "rules, and the call returns once they have answered; what they allow is passed on, and a refusal with a reason " +
+            "fails this call and is passed on with the reason. Do not ask them in your reply or with your question tool first. " +
+            "For a question, answers is what the person chose: ask them first, with your question tool if you have one, and " +
+            "never answer for them. The session carries on once it has the answer.",
         input: AnswerInput,
         execute: async (input, context) => {
-            const result = await answerRequest(ports, context.sessionID, input).catch(rethrow("courier_answer"));
+            const call = { messageID: context.messageID, callID: context.id };
+            const result = await answerRequest(ports, context.sessionID, input, call).catch((error) => {
+                // A plain rejection of the caller's prompt ends its step, as OpenCode's own tools do: it goes back as it is.
+                if (isDeclined(error))
+                    throw error;
+                return rethrow("courier_answer")(error);
+            });
             return { content: answerText(result), metadata: result };
         },
     });

package/dist/person/tui.d.ts

@@ -1,17 +1,21 @@
 import type { Plugin } from "@opencode/plugin/tui";
-import type { AttentionSoundName } from "@opencode/plugin/tui/context";
 import { type AskedPermission, type AskedQuestion, type Asks, type TreeSession } from "./rpc.js";
 type Context = Plugin.Context;
 type FormInfo = NonNullable<ReturnType<Context["data"]["session"]["form"]["list"]>>[number];
 type FormField = FormInfo["fields"][number];
 type FormAnswer = Parameters<Context["data"]["session"]["form"]["reply"]>[0]["answer"];
-/** Something a session of the tree waits on the person for; `key` is unique across kinds. */
+type FormValue = FormAnswer[string];
+/**
+ * Something a session of the tree waits on the person for; `key` is unique across kinds. `prompted` marks a permission
+ * request the top session's courier_answer prompt asks about.
+ */
 export type Ask = {
     readonly key: string;
     readonly session: TreeSession;
 } & ({
     readonly kind: "permission";
     readonly request: AskedPermission;
+    readonly prompted?: boolean;
 } | {
     readonly kind: "question";
     readonly question: AskedQuestion;
@@ -23,23 +27,30 @@ export type Ask = {
 export declare const INBOX_COMMAND = "courier.asks";
 /** How long after the first of a burst of asks the inbox reads the tree again, to sound the new ones. */
 export declare const SETTLE_MS = 250;
-/** The asks of a tree in the order the inbox lists them: by the tree's order, each session's permissions, questions, then forms. */
+/** The top session, at depth 0, as its own permission requests name it. */
+export declare const topSession: (asks: Asks) => TreeSession;
+/**
+ * The asks of a tree in the order the inbox lists them: the top session's own permission requests, then by the tree's
+ * order, each session's permissions, questions, then forms.
+ */
 export declare function asksOf(asks: Asks, forms: ReadonlyMap<string, ReadonlyArray<FormInfo>>): Ask[];
-/** Where an ask comes from: the titles from the top session down to the asking one, as "root › child › grandchild". */
-export declare function pathOf(asks: Asks, sessionID: string, topTitle: string): string;
+/** Where an ask comes from: the titles from the top session down to the asking one, as "root › child › grandchild", each as the TUI knows it now, else as spawned. */
+export declare function pathOf(asks: Asks, sessionID: string, topTitle: string, currentTitle?: (sessionID: string) => string | undefined): string;
 /** What an ask is, in one line. */
 export declare function askTitle(ask: Ask): string;
-/** The line under an ask: its depth and group, and that a question's call was cut off. */
+/** The line under an ask: its depth (the top's own say so) and group, that a question's call was cut off, or that the top's courier_answer prompt asks for it. */
 export declare function askFooter(ask: Ask): string;
-/** The sound an ask arriving plays: a permission request's, or a question's for questions and forms. */
-export declare const soundOf: (ask: Ask) => AttentionSoundName;
-/** Whether a form field is shown, given the answers so far: hidden ones never, conditional ones when their conditions hold. */
-export declare function shown(field: FormField, answers: FormAnswer): boolean;
+/** Whether a form field applies, given the answers so far (a hidden field's default among them): its `when` conditions hold, as OpenCode reads them (a condition on an unanswered field is false; on a multiselect, `eq` means includes). */
+export declare function active(field: FormField, answers: FormAnswer): boolean;
+/** What is wrong with a field's answer by the limits OpenCode's form service checks on reply, worded as its form view does; undefined when it fits. */
+export declare function misfit(field: FormField, value: FormValue): string | undefined;
+/** The limits of a typed field as a prompt's placeholder: "1-5", "at least 3 characters", "email"; undefined without any. */
+export declare function limitsOf(field: FormField): string | undefined;
 /**
  * Adds the asks inbox: what the open session's courier tree waits on the person for, read through the person's RPC and
- * answered in dialogs, opened by its command; a sound for each new ask. Returns its opener and its cleanup.
+ * answered in dialogs, opened by its command, its open list read again on `follows`; a sound for each new ask.
  */
-export declare function addAsksInbox(ctx: Context): {
+export declare function addAsksInbox(ctx: Context, follows: ReadonlySet<string>): {
     open: (sessionID?: string | undefined) => Promise<void>;
     cleanup: () => void;
 };

package/dist/tree/domain.d.ts

@@ -26,6 +26,29 @@ export declare function readNativeChildren(options: unknown): {
 type Times = Awaited<ReturnType<Context["session"]["get"]>>["time"];
 /** Whether a session with these times runs: it has never finished a turn, or something reached it after the last one ended. */
 export declare const busy: (time: Pick<Times, "updated" | "idle">) => boolean;
+/**
+ * Whether a session a tree is read of is live: it runs (as the limits count it: busy, and its turn has not failed or
+ * been interrupted since its last prompt), waits on a request or form, or owes a report; one OpenCode no longer knows is not.
+ */
+export declare const isLive: (time: Pick<Times, "updated" | "idle"> | undefined, waits: number, report: {
+    readonly owes: boolean;
+    readonly ended: boolean;
+} | undefined) => boolean;
+/** A session of a tree read, as `cut` takes it: where it is in the tree, when it was started, and whether it is live. */
+export interface Cuttable {
+    readonly sessionID: string;
+    readonly parentID: string;
+    readonly createdAt: number;
+    readonly live: boolean;
+}
+/**
+ * Which sessions a listing of at most `max` keeps, of a tree read in the order it is drawn: the live ones first, then
+ * the newest, each with the sessions above it so the tree still draws; `leftOut` counts the rest.
+ */
+export declare function cut<T extends Cuttable>(nodes: ReadonlyArray<T>, max: number): {
+    kept: T[];
+    leftOut: number;
+};
 /** A session started with courier_spawn, recorded under the session that started it. */
 export interface RosterEntry {
     readonly sessionID: string;

package/dist/tree/domain.js

@@ -25,6 +25,32 @@ export function readNativeChildren(options) {
 }
 /** 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 session a tree is read of is live: it runs (as the limits count it: busy, and its turn has not failed or
+ * been interrupted since its last prompt), waits on a request or form, or owes a report; one OpenCode no longer knows is not.
+ */
+export const isLive = (time, waits, report) => time !== undefined && ((busy(time) && !report?.ended) || waits > 0 || (report?.owes ?? false));
+/**
+ * Which sessions a listing of at most `max` keeps, of a tree read in the order it is drawn: the live ones first, then
+ * the newest, each with the sessions above it so the tree still draws; `leftOut` counts the rest.
+ */
+export function cut(nodes, max) {
+    const byID = new Map(nodes.map((node) => [node.sessionID, node]));
+    const ranked = nodes
+        .map((node, order) => ({ node, order }))
+        .sort((a, b) => Number(b.node.live) - Number(a.node.live) || b.node.createdAt - a.node.createdAt || a.order - b.order);
+    const kept = new Set();
+    for (const { node } of ranked) {
+        const chain = [];
+        for (let above = node; above && !kept.has(above.sessionID); above = byID.get(above.parentID))
+            chain.push(above.sessionID);
+        if (kept.size + chain.length > max)
+            continue;
+        for (const sessionID of chain)
+            kept.add(sessionID);
+    }
+    return { kept: nodes.filter((node) => kept.has(node.sessionID)), leftOut: nodes.length - kept.size };
+}
 /** `lineage` over roster entries already read. */
 export function lineageIn(entries, sessionID) {
     return lineageBy(bySession(entries), sessionID);

package/dist/tree/events.d.ts

@@ -51,8 +51,8 @@ export declare function notePrompt(ports: WatchPorts, event: SessionEvent & {
  */
 export declare function noteInterrupted(ports: WatchPorts, event: SessionEvent): Promise<boolean>;
 /**
- * Drops the report state, and the groups, of a session OpenCode deleted, and the report state of the sessions it
- * started, whose reports can no longer be delivered; it leaves its own group. Returns the sessions forgotten.
+ * Forgets what a deleted session leaves (report state, groups) and, unless isolated or a parent on the roster, its
+ * entry. Returns the sessions forgotten.
  */
 export declare function noteDeleted(ports: WatchPorts, event: SessionEvent): Promise<string[]>;
 /** A `Waits` asking `suppliers` one after another, cheapest first: the first that waits answers. */

package/dist/tree/events.js

@@ -1,6 +1,6 @@
 import { envelope } from "../kernel/protocol.js";
 import { claim, SEEN_MAX, setBounded } from "../platform/bounded.js";
-import { forgetDeleted } from "./forget.js";
+import { forgetChild, forgetDeleted } from "./forget.js";
 import { hasCompleteGroup, leave, outIn } from "./group.js";
 import { awaited, reportOf, stoppedSincePrompt } from "./report.js";
 import { childStore, groupStore } from "./store.js";
@@ -88,8 +88,8 @@ export async function noteInterrupted(ports, event) {
     return true;
 }
 /**
- * Drops the report state, and the groups, of a session OpenCode deleted, and the report state of the sessions it
- * started, whose reports can no longer be delivered; it leaves its own group. Returns the sessions forgotten.
+ * Forgets what a deleted session leaves (report state, groups) and, unless isolated or a parent on the roster, its
+ * entry. Returns the sessions forgotten.
  */
 export async function noteDeleted(ports, event) {
     const { sessionID } = event.data;
@@ -99,6 +99,8 @@ export async function noteDeleted(ports, event) {
     const entry = parentID === undefined ? undefined : await children.entry(parentID, sessionID);
     const member = entry && (await outIn(ports, entry));
     await forgetDeleted(ports, sessionID, forgotten, member, event.created);
+    if (parentID !== undefined && entry && !entry.isolated && started.length === 0)
+        await forgetChild(ports.storage, parentID, sessionID);
     return forgotten;
 }
 /** A `Waits` asking `suppliers` one after another, cheapest first: the first that waits answers. */

package/dist/tree/index.d.ts

@@ -3,7 +3,7 @@ export { shapeContext } from "./context.js";
 export { lineageIn, nativeRootOf, readLimits, readNativeChildren } from "./domain.js";
 export { together, treeEvents, waitsOn } from "./events.js";
 export { deliverReleased } from "./group.js";
-export type { CleanupPorts, CourierPorts, Pending, PendingPrompt, RosterEntry, RosterStorage, SpawnGate, Waits, WatchPorts, WatchState, } from "./ports.js";
+export type { CleanupPorts, CourierPorts, Pending, PendingPrompt, RosterEntry, RosterStorage, ShownForm, SpawnGate, Waits, WatchPorts, WatchState, } from "./ports.js";
 export { allEntries, answeringTop, lineage, pruneExpired, RETENTION_MS } from "./roster.js";
 export { subtree } from "./subtree.js";
 export { registerTreeRpc } from "./rpc-handlers.js";

package/dist/tree/panel.d.ts

@@ -1,4 +1,4 @@
-import type { CourierPorts, Pending } from "./ports.js";
+import type { CourierPorts, Pending, ShownForm } from "./ports.js";
 import type { Tree, Wait } from "./rpc.js";
 type Messages = Awaited<ReturnType<CourierPorts["session"]["context"]>>;
 /** The last tool call in a session's messages, and when it was made. */
@@ -8,6 +8,11 @@ export declare function lastTool(messages: Messages): {
 } | undefined;
 /** A request as the panel says what a paused session waits on: a permission request, or its first question. */
 export declare const waitOf: (pending: Pending) => Wait;
-/** The tree panel's rows: the sessions courier_tree reads under a session, at most `maxTotal`, each as `row` reads it. */
+/** A form a session shows, as the panel says what it waits on. */
+export declare const formWait: (form: ShownForm) => Wait;
+/**
+ * The tree panel's rows: the sessions under a session as courier_tree lists them, at most `maxTotal`, the live ones
+ * first, then the newest, each as `row` reads it; `truncated` counts the older ones left out.
+ */
 export declare function panel(ports: CourierPorts, rootID: string): Promise<Tree>;
 export {};