opencode-courier 0.7.3 → 0.9.0

package/dist/memory/text.js

@@ -0,0 +1,116 @@
+/** The memory's model-facing texts: what courier_recall and courier_note say. */
+import { clipText, clipWords } from "../kernel/protocol.js";
+import { LESSON_MAX, oneLine, PART_STATUSES, splitProse } from "./domain.js";
+/** The tool's name, which the skill and the role part name too. */
+export const RECALL_TOOL = "courier_recall";
+/** The lesson tool's name, which the skill's last step names. */
+export const NOTE_TOOL = "courier_note";
+const count = (n, noun) => `${n} ${noun}${n === 1 ? "" : "s"}`;
+const DAY_MS = 86_400_000;
+/** A duration in milliseconds as a model reads it: seconds under half a minute, else whole minutes, else hours and minutes. */
+export function duration(ms) {
+    const minutes = Math.round(ms / 60_000);
+    if (minutes < 1)
+        return `${Math.max(0, Math.round(ms / 1000))} s`;
+    if (minutes < 60)
+        return `${minutes} min`;
+    return `${Math.floor(minutes / 60)} h ${minutes % 60} min`;
+}
+/** How long ago a record last moved: a duration under a day, else whole days, which a record kept for months is read in. */
+export function age(ms) {
+    const days = Math.floor(ms / DAY_MS);
+    return days < 1 ? duration(ms) : count(days, "day");
+}
+/** How a listing counts the parts of a record: by status, in the order of `PART_STATUSES`, plus how many were isolated and how many spawns were refused. */
+function partsLine(parts) {
+    if (!parts.length)
+        return "no parts";
+    const statuses = PART_STATUSES.flatMap((status) => {
+        const n = parts.filter((part) => part.status === status).length;
+        return n ? [`${n} ${status}`] : [];
+    }).join(", ");
+    const isolated = parts.filter((part) => part.isolated).length;
+    const refused = parts.reduce((n, part) => n + (part.refused ?? 0), 0);
+    const deepest = Math.max(...parts.map((part) => part.depth));
+    return [
+        `${count(parts.length, "part")}: ${statuses}`,
+        ...(deepest > 1 ? [`${deepest} levels deep`] : []),
+        ...(isolated ? [`${isolated} isolated`] : []),
+        ...(refused ? [`${count(refused, "spawn")} refused`] : []),
+    ].join(", ");
+}
+const day = (at) => new Date(at).toISOString().slice(0, 10);
+/** A lesson as the listing and the note's result show it: dated, and from which depth when a session below the top wrote it. */
+export function lessonLine(lesson) {
+    const from = lesson.depth === undefined ? "" : `, from depth ${lesson.depth}`;
+    return `lesson (${day(lesson.at)}${from}): "${clipText(oneLine(lesson.text), LESSON_MAX)}"`;
+}
+/**
+ * One record as the listing shows it: its top, when it started, its title, its split line and its latest revision as prose,
+ * its parts, how long it ran, how long ago it last moved, what it cost, and whether the person pinned it.
+ */
+export function recordLine(record, top, now) {
+    const cost = record.parts.reduce((sum, part) => sum + (part.cost ?? 0), 0);
+    const costed = record.parts.some((part) => part.cost !== undefined);
+    const revised = record.revisions?.at(-1);
+    return [
+        `- ${record.sessionID}${record.sessionID === top ? " (this tree)" : ""} ${day(record.startedAt)}: "${clipText(oneLine(record.title), 60)}"`,
+        clipWords(splitProse(record.split), 160),
+        ...(revised ? [`then, after ${count(revised.parts, "part")}: ${clipWords(splitProse(revised.text), 160)}`] : []),
+        partsLine(record.parts),
+        `ran ${duration(record.movedAt - record.startedAt)}`,
+        `last moved ${age(now - record.movedAt)} ago`,
+        ...(costed ? [`$${cost.toFixed(2)}`] : []),
+        record.finished ? "finished" : "not finished",
+        ...(record.pinned ? ["pinned"] : []),
+        ...(record.recalled ? [`recalled${record.recalled.at === undefined ? " by a part" : ""}`] : []),
+        ...(record.lesson ? [lessonLine(record.lesson)] : []),
+    ].join(" · ");
+}
+/** What the listing says of pinned records, when it holds one. */
+const PINNED = "A record marked \"pinned\" is one the person chose to keep and listed first: weigh it before the rest.";
+/** What courier_recall says when the memory option is off. */
+export const RECALL_OFF = "Memory is off: the plugin's memory option is false, so no record of a session tree is kept or listed in this project. Decide from the task alone.";
+/**
+ * The listing: every record of the project, the pinned first and then newest first, the caller's own tree marked, each
+ * aged against `now`.
+ */
+export function recallListText(records, top, now) {
+    const others = records.filter((record) => record.sessionID !== top);
+    const pinned = records.some((record) => record.pinned);
+    const intro = others.length
+        ? `${count(others.length, "earlier tree")} recorded in this project, ${pinned ? "pinned first, then newest first" : "newest first"}; weigh how they were split and how their parts went before you decide. ` +
+            "A record holds what the plugin saw, not the work, and a lesson what its orchestrator concluded, next to the facts that bear it out. " +
+            "The facts are as they stood when the tree last moved: \"not finished\" with an old \"last moved\" is a stale record, not a tree running now. " +
+            "courier_recall with a sessionID gives one in full, with each part's status, duration, cost and context use." +
+            (pinned ? ` ${PINNED}` : "")
+        : "No earlier tree is recorded in this project: a tree's record is written by a courier_recall call and as each turn in it ends, and kept 90 days. Decide from the task alone.";
+    return [intro, ...records.map((record) => recordLine(record, top, now))].join("\n");
+}
+/** One record in full, as JSON: durations in milliseconds, times in epoch milliseconds, context use as a share of the model's window. */
+export function recallRecordText(record) {
+    return `Record of the tree under ${record.sessionID}, in project ${record.projectID} (durations in milliseconds, context use as a share of the model's window):\n${JSON.stringify(record, null, 2)}`;
+}
+export const recallMissingText = (sessionID) => `No record of a tree whose top session is ${sessionID} in this project. courier_recall without sessionID lists the records there are.`;
+/** What a lesson is for, which the tool's description and the note's result both say. */
+const NOT_A_RULE = "A lesson that holds every time belongs in AGENTS.md or the skill, which only the person puts there: tell them instead of noting it.";
+/** What courier_note says once the lesson is written: where, and what it replaced. */
+export function noteText(top, lesson, replaced) {
+    return [
+        `Noted on the record of the tree under ${top} as its ${lessonLine(lesson)}.`,
+        ...(replaced ? [`It replaces the ${lessonLine(replaced)}.`] : []),
+        `${RECALL_TOOL} lists it after the tree's facts; a second ${NOTE_TOOL} replaces it. ${NOT_A_RULE}`,
+    ].join(" ");
+}
+/** What courier_note says when the memory option is off. */
+export const NOTE_OFF = "Not noted: the plugin's memory option is false, so no record of a session tree is kept in this project to write a lesson on.";
+export const noteLeafRefusal = (depth, maxDepth) => `Not noted: this session is a leaf, at depth ${depth} of a session tree that goes at most ${maxDepth} deep (maxDepth). A lesson is ` +
+    "written by the session that verified the tree, the top or one that started sessions; put what you learned in your report instead.";
+/** What a lesson holds, which the empty and the long refusal both ask for. */
+const ONE_LINE = "what the next orchestrator in this project should know about running a tree like this one, with the job it comes from and the reason";
+export const NOTE_EMPTY = `Not noted: text is empty. Write one line, ${ONE_LINE}, or nothing.`;
+/** The refusal of a lesson longer than `LESSON_MAX` as one line: nothing is written, and the earlier lesson stays. */
+export const noteLongRefusal = (length) => `Not noted: the lesson is ${length} characters, at most ${LESSON_MAX}; write it shorter. Nothing was written, and the earlier lesson, ` +
+    `if there was one, stays. Keep one line, ${ONE_LINE}, and leave out what the record's facts already say.`;
+export const noteUnrecordedRefusal = (top) => `Not noted: the tree under ${top} has no record in this project to write a lesson on. A record is written by a ${RECALL_TOOL} call ` +
+    "and as each turn in the tree ends, so call it once first, or note once a session you started has reported.";

package/dist/memory/tools.d.ts

@@ -0,0 +1,16 @@
+import { Schema } from "effect";
+import { type ToolEditor } from "../kernel/tool.js";
+import type { MemoryPorts, MemoryState } from "./ports.js";
+export declare const RecallInput: Schema.Struct<{
+    readonly sessionID: Schema.optional<Schema.String>;
+}>;
+export declare const NoteInput: Schema.Struct<{
+    readonly text: Schema.String;
+}>;
+/** What the memory's tools run on: one instance's ports and the process's shared state. */
+export interface MemoryToolPorts {
+    readonly memory: MemoryPorts;
+    readonly state: Pick<MemoryState, "tops">;
+}
+/** Adds `courier_recall` and `courier_note`, direct tools rather than code-mode ones. */
+export declare function addMemoryTools(tools: ToolEditor, ports: MemoryToolPorts): void;

package/dist/memory/tools.js

@@ -0,0 +1,78 @@
+import { Schema } from "effect";
+import { describeFailure } from "../kernel/protocol.js";
+import { rethrow } from "../kernel/tool.js";
+import { LESSON_MAX } from "./domain.js";
+import { note } from "./note.js";
+import { recall } from "./recall.js";
+import { NOTE_EMPTY, NOTE_OFF, NOTE_TOOL, noteLeafRefusal, noteLongRefusal, noteText, noteUnrecordedRefusal, RECALL_OFF, RECALL_TOOL, recallListText, recallMissingText, recallRecordText } from "./text.js";
+export const RecallInput = Schema.Struct({
+    sessionID: Schema.optional(Schema.String.annotate({ description: "The top session of a listed record, for that record in full; without it, one line per record of this project." })),
+});
+export const NoteInput = Schema.Struct({
+    text: Schema.String.annotate({
+        description: `The lesson, one line of at most ${LESSON_MAX} characters (longer is refused, not clipped): what the next orchestrator in this ` +
+            "project should know about running a tree like this one, how it was split, verified or briefed, or what the person decided, " +
+            "with the job it comes from and the reason.",
+    }),
+});
+/** Adds `courier_recall` and `courier_note`, direct tools rather than code-mode ones. */
+export function addMemoryTools(tools, ports) {
+    tools.add({
+        name: RECALL_TOOL,
+        options: { codemode: false },
+        description: "Look once at what earlier session trees in this project did, before you decide whether and how to split a task: " +
+            "one line per tree, those the person pinned first and then newest first, with how its top split the task, how each part went (its status, how long it ran, " +
+            "what it cost, how full its context got) and whether a spawn was refused; with sessionID, one tree's record in full. " +
+            "Records hold no report bodies or files. Call it once at the start, not in a loop, and not to check on sessions you " +
+            "started: their reports wake you.",
+        input: RecallInput,
+        execute: async (input, context) => {
+            const result = await recall(ports.memory, ports.state, context.sessionID, input).catch(rethrow(RECALL_TOOL));
+            switch (result.kind) {
+                case "off":
+                    return { content: RECALL_OFF, metadata: { memory: false } };
+                case "list":
+                    return { content: recallListText(result.records, result.top, ports.memory.now()), metadata: { projectID: result.projectID, top: result.top, records: result.records } };
+                case "record":
+                    return { content: recallRecordText(result.record), metadata: { projectID: result.projectID, record: result.record } };
+                case "missing":
+                    return { content: recallMissingText(result.sessionID), metadata: { projectID: result.projectID, sessionID: result.sessionID, found: false } };
+            }
+        },
+    });
+    tools.add({
+        name: NOTE_TOOL,
+        options: { codemode: false },
+        description: "Write the one lesson of your session tree for the next orchestrator in this project, once you have verified and " +
+            "integrated the work: what it should know about running a tree like this one that the record's facts do not say. How " +
+            "it was split (which parts collided, what was too small to hand off), how it was verified (what a part got wrong and " +
+            "what caught it), how the parts were briefed, or what the person decided. Name the job it comes from and the reason, " +
+            "so that a lesson for one kind of job can be told from one that holds everywhere. One line, at most " +
+            `${LESSON_MAX} characters; a longer one is refused, not clipped, so write it again shorter. Kept on your own tree's ` +
+            "record and listed by courier_recall after its facts, dated; a second call replaces the first. From the top session " +
+            "or one that started sessions, never a leaf. No code, no secrets, and not a rule that holds every time: that belongs " +
+            "in AGENTS.md or the skill, for the person to put there, so tell them instead.",
+        input: NoteInput,
+        execute: async (input, context) => {
+            const result = await note(ports.memory, context.sessionID, input).catch(rethrow(NOTE_TOOL));
+            // A refusal is the tool's failure, as courier_spawn's are, so the step ends on it and the model reads why.
+            const refuse = (text) => describeFailure(NOTE_TOOL, new Error(text));
+            switch (result.kind) {
+                case "noted": {
+                    const { projectID, top, lesson, replaced } = result;
+                    return { content: noteText(top, lesson, replaced), metadata: { projectID, top, lesson, ...(replaced ? { replaced } : {}) } };
+                }
+                case "off":
+                    throw refuse(NOTE_OFF);
+                case "leaf":
+                    throw refuse(noteLeafRefusal(result.depth, result.maxDepth));
+                case "empty":
+                    throw refuse(NOTE_EMPTY);
+                case "long":
+                    throw refuse(noteLongRefusal(result.length));
+                case "unrecorded":
+                    throw refuse(noteUnrecordedRefusal(result.top));
+            }
+        },
+    });
+}

package/dist/memory/tui.d.ts

@@ -0,0 +1,82 @@
+import type { Plugin } from "@opencode/plugin/tui";
+import { type Forgotten, type MemoryLesson, type MemoryPart, type MemoryReads, type MemoryRecord, type Pinned } from "./rpc.js";
+type Context = Plugin.Context;
+/** The command that opens the memory view: `/courier memory`, or the palette. */
+export declare const MEMORY_COMMAND = "courier.memory";
+/** The memory view's line of the `/courier` command's usage. */
+export declare const MEMORY_USAGE = "/courier memory lists this project's tree records, to read, pin or forget";
+/** What the view says, in a toast, with the memory option off in the project asked. */
+export declare const MEMORY_OFF = "Memory is off in this project: the plugin's memory option is false, so no record of a session tree is kept or listed here.";
+/** What the view says, in a toast, when the project has no record: when none was written yet, or the last was forgotten. */
+export declare const NO_RECORDS = "No record of a session tree in this project: one is written as each turn in a tree ends, and kept 90 days.";
+/** The most characters of a lesson a list row's line under it shows; the record in full has it whole. */
+export declare const LESSON_LINE_MAX = 160;
+/** The most characters of a title a list row shows, so that "(this session)" after it fits the host's 61. */
+export declare const ROW_TITLE_MAX = 46;
+/** The group of the records moved on the current local day, over the others' local dates, as the host's Sessions dialog has it. */
+export declare const TODAY = "Today";
+/** The group of the records the person pinned, above the days, shown only while there is one. */
+export declare const PINNED = "Pinned";
+/** The widest a row of the lesson in a record in full is; a longer lesson wraps over rows. */
+export declare const LESSON_ROW = 90;
+/** A record's name, as its rows and confirms show it: its title on one line, else its top session. */
+export declare const nameOf: (record: MemoryRecord) => string;
+/** A record's parts counted by status, in the order of `PART_STATUSES`: "3 parts: 2 done, 1 partial"; "no parts" with none. */
+export declare function partsCounted(parts: ReadonlyArray<MemoryPart>): string;
+/** The parts' costs summed, when any is known. */
+export declare function costOf(record: MemoryRecord): number | undefined;
+/** A list row's title: the tree's title, its top session's id without one; the open session's own tree says so. */
+export declare function recordTitle(record: MemoryRecord, open?: string): string;
+/**
+ * A list row's group: `Pinned` for a pinned record, `Today` for a tree last moved on the local day of `now`, else that
+ * local date; the RPC's order, pinned first and then by the last move, keeps the groups in that order.
+ */
+export declare function recordCategory(record: MemoryRecord, now?: number): string;
+/** How often other trees' courier_recall calls listed the record and opened it in full: "shown 7 times, opened once"; "shown 7 times" alone when none opened it. */
+export declare function readsLine(reads: MemoryReads): string;
+/** A lesson as the view shows it: dated on the local day, from which depth when a session below the top wrote it, and its text. */
+export declare function lessonHeading(lesson: MemoryLesson): string;
+/** A list row's description: its parts by status, how long the tree ran, what its parts cost, that it is not finished when it is not, and how often other trees read it. */
+export declare function recordDescription(record: MemoryRecord): string;
+/** The lines under a list row: the lesson, dated and from which depth, clipped; none without a lesson. */
+export declare function recordDetails(record: MemoryRecord): string[];
+/** One part as the record in full describes it: its status, depth, isolation, group, duration, cost, context use and spawns refused. */
+export declare function partLine(part: MemoryPart): string;
+/** `text` in rows of at most `width` characters, broken at spaces where it can be. */
+export declare function wrap(text: string, width: number): string[];
+/** A row of a record in full: a fact of the tree, one of its parts, or a row of its lesson (0 its heading), which `x` forgets alone. */
+export type Line = {
+    readonly kind: "fact";
+    readonly key: string;
+} | {
+    readonly kind: "part";
+    readonly sessionID: string;
+} | {
+    readonly kind: "lesson";
+    readonly row: number;
+};
+/** Where the cursor goes in a record in full after its lesson is forgotten: the lesson's first row, or the row that replaced it. */
+export declare const lessonLine: (record: MemoryRecord) => Line;
+/** The records the list's cursor tries, in order, after one is forgotten, kept or left: it, unless forgotten, then those after it, then those before it, nearest first. */
+export declare function nearby(sessionIDs: ReadonlyArray<string>, sessionID: string, forgotten: boolean): string[];
+/** The rows of a record in full, in three categories: the tree's facts, its parts and its lesson. */
+export declare function detailOptions(record: MemoryRecord): Array<{
+    title: string;
+    value: Line;
+    category: string;
+    description?: string;
+}>;
+/** What the confirm asks before a forget: the record named, with the local day it last moved, and what goes and what stays. */
+export declare function forgetMessage(record: MemoryRecord, lesson: boolean): string;
+/** The toast after a forget, as the server reports it. */
+export declare function forgottenLine(record: MemoryRecord, outcome: Forgotten["outcome"]): string;
+/** The toast after a pin, as the server reports it. */
+export declare function pinnedLine(record: MemoryRecord, outcome: Pinned["outcome"]): string;
+/**
+ * Adds the memory view: the project's records (the open session's location, else the TUI's, else the server's default) under
+ * `Pinned`, `Today` and the days they last moved; `enter` shows one in full, `p` pins or unpins one, `x` forgets one or its lesson after a confirm.
+ */
+export declare function addMemoryView(ctx: Context): {
+    open: () => Promise<void>;
+};
+export {};

package/dist/person/rpc.d.ts

@@ -106,8 +106,8 @@ export declare const personRpc: {
                 readonly sessions: readonly {
                     readonly sessionID: string;
                     readonly title: string;
-                    readonly parentID: string;
                     readonly depth: number;
+                    readonly parentID: string;
                     readonly group?: string | undefined;
                 }[];
                 readonly permissions: readonly {
@@ -140,8 +140,8 @@ export declare const personRpc: {
                 readonly sessions: readonly {
                     readonly sessionID: string;
                     readonly title: string;
-                    readonly parentID: string;
                     readonly depth: number;
+                    readonly parentID: string;
                     readonly group?: string | undefined;
                 }[];
                 readonly permissions: readonly {
@@ -227,11 +227,11 @@ export declare const personRpc: {
             }>;
             readonly output: import("effect/StandardSchema").StandardSchemaV1<{
                 readonly answered: boolean;
-                readonly by?: "result" | "message" | undefined;
+                readonly by?: "message" | "result" | undefined;
                 readonly problem?: string | undefined;
             }, {
                 readonly answered: boolean;
-                readonly by?: "result" | "message" | undefined;
+                readonly by?: "message" | "result" | undefined;
                 readonly problem?: string | undefined;
             }> & Schema.Struct<{
                 readonly answered: Schema.Boolean;

package/dist/platform/json.d.ts

@@ -1,6 +1,7 @@
 /** Readers for untyped JSON, such as a webhook payload or a plugin option: the value when it has the type, else nothing. */
 export declare const str: (value: unknown) => string | undefined;
 export declare const num: (value: unknown) => number | undefined;
+export declare const finite: (value: unknown) => number | undefined;
 export declare const obj: (value: unknown) => Record<string, any>;
 /** Epoch milliseconds from a session time, a `DateTime` in OpenCode's API and a number in tests; NaN for none. */
 export declare function millis(value: unknown): number;

package/dist/platform/json.js

@@ -1,6 +1,7 @@
 /** Readers for untyped JSON, such as a webhook payload or a plugin option: the value when it has the type, else nothing. */
 export const str = (value) => (typeof value === "string" ? value : undefined);
 export const num = (value) => (typeof value === "number" && Number.isInteger(value) ? value : undefined);
+export const finite = (value) => (typeof value === "number" && Number.isFinite(value) ? value : undefined);
 export const obj = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
 /** Epoch milliseconds from a session time, a `DateTime` in OpenCode's API and a number in tests; NaN for none. */
 export function millis(value) {

package/dist/rpc.d.ts

@@ -1,2 +1,3 @@
 export { treeRpc, type Row, type Stopped, type Summary, type Tree, type TreeRpc, type Wait } from "./tree/rpc.js";
 export { personRpc, type Answered, type Asks, type PersonRpc } from "./person/rpc.js";
+export { memoryRpc, type Forgotten as MemoryForgotten, type MemoryLesson, type MemoryPart, type MemoryReads, type MemoryRecord, type MemoryRpc, type Pinned as MemoryPinned, type Records } from "./memory/rpc.js";

package/dist/rpc.js

@@ -1,3 +1,4 @@
 // The package's `rpc` entrypoint: the courier's RPC contracts, for a client that calls them.
 export { treeRpc } from "./tree/rpc.js";
 export { personRpc } from "./person/rpc.js";
+export { memoryRpc } from "./memory/rpc.js";

package/dist/skill.js

@@ -10,8 +10,9 @@ export const SKILL_CONTENT = [
     "How to split a task across OpenCode sessions with opencode-courier, and bring the results back up. Your brief, or the " +
         "opencode-courier role line in your system prompt, names your depth in the session tree and its limits.",
     "",
-    "1. Decide: split or do. Split when the task has 2 or more independent, substantial parts touching separate files or " +
-        "areas; do it yourself when it is small, sequential or tightly coupled. Never start exactly one session for the whole " +
+    "1. Decide: split or do. First call courier_recall once: it lists how earlier trees in this project were split and how " +
+        "each part went, so weigh that; one call, before you decide, never in a loop. Split when the task has 2 or more " +
+        "independent, substantial parts touching separate files or areas; do it yourself when it is small, sequential or tightly coupled. Never start exactly one session for the whole " +
         "task: it only adds a hop. What you read and write yourself stays in your context for every later turn, so keep the " +
         "deciding, checking and integrating, and hand off the long reading and writing. An implementation task with one tightly " +
         "coupled core usually still has independent parts: finding out what the change needs (a session with isolate: false " +
@@ -44,7 +45,13 @@ export const SKILL_CONTENT = [
     "7. Integrate: merge each reported branch into your own checkout (git merge courier/<session>), resolve conflicts " +
         "yourself, run the checks once more, then courier_cleanup the isolated sessions you are done with.",
     "8. Report upward if a session started you: one courier_send to it, with one status for the whole (done only when every " +
-        "part is verified and integrated; partial, blocked or failed otherwise) and the artifacts. At the top, reply to the person.",
+        "part is verified and integrated; partial, blocked or failed otherwise) and the artifacts. At the top, before you reply " +
+        "to the person: if there is something the next tree in this project should know about running a tree like this one (how " +
+        "it was split, what a part got wrong and what caught it, what a brief should have said, what the person decided), one " +
+        "courier_note with that one line; none when there is nothing. Name the job it comes from and the reason, so that a " +
+        "lesson for one kind of job is not taken for every job; the tool refuses a line over its limit rather than clipping " +
+        "it, so write it again shorter. A rule that holds every time goes to AGENTS.md or the skill, through the person, not " +
+        "into a note. Then reply to the person.",
     "",
     "When a part goes wrong:",
     "- A failed turn (failed=\"...\") or a silent end (ended=\"without-report\", quoting the session's last reply): message " +

package/dist/tree/context.d.ts

@@ -9,7 +9,7 @@ export interface Shaped {
     }>;
 }
 /**
- * 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.
+ * The `context` hook: names a session's role in its tree in a system part, and hides courier_spawn, and the tools
+ * named `hiddenFromLeaf`, from one at `maxDepth`. A session nobody spawned that has started none is pointed to the skill, if it could spawn.
  */
 export declare function shapeContext(ports: ContextPorts, event: Shaped): Promise<void>;

package/dist/tree/context.js

@@ -4,8 +4,8 @@ import { ROLE_PREFIX, rolePart } from "./text.js";
 /** 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.
+ * The `context` hook: names a session's role in its tree in a system part, and hides courier_spawn, and the tools
+ * named `hiddenFromLeaf`, 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 {
@@ -13,7 +13,8 @@ export async function shapeContext(ports, event) {
         if (depth === null && !event.tools.courier_spawn)
             return;
         if (depth !== null && depth >= ports.limits.maxDepth)
-            delete event.tools.courier_spawn;
+            for (const tool of ["courier_spawn", ...(ports.hiddenFromLeaf ?? [])])
+                delete event.tools[tool];
         if (!event.system.some((part) => part.text.startsWith(ROLE_PREFIX)))
             event.system.push({ type: "text", text: rolePart(depth, ports.limits) });
     }

package/dist/tree/index.d.ts

@@ -1,11 +1,12 @@
 export { dirtyOf, headOf, inspectWorktree } from "./cleanup.js";
 export { shapeContext } from "./context.js";
-export { lineageIn, nativeRootOf, readLimits, readNativeChildren } from "./domain.js";
+export { busy, 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, ShownForm, SpawnGate, Waits, WatchPorts, WatchState, } from "./ports.js";
-export { allEntries, answeringTop, lineage, pruneExpired, RETENTION_MS } from "./roster.js";
-export { subtree } from "./subtree.js";
+export { contextOf } from "./panel.js";
+export type { CleanupPorts, CourierPorts, ModelWindow, Pending, PendingPrompt, RosterEntry, RosterStorage, ShownForm, SpawnGate, Waits, WatchPorts, WatchState, } from "./ports.js";
+export { allEntries, answeringTop, childrenOf, indexedLineage, lineage, pruneExpired, reportState, RETENTION_MS, type ReportState } from "./roster.js";
+export { subtree, type Below } from "./subtree.js";
 export { registerTreeRpc } from "./rpc-handlers.js";
 export { addTreeTools } from "./tools.js";
-export { wakeMissed } from "./wake.js";
+export { stalledAmong, wakeMissed } from "./wake.js";

package/dist/tree/index.js

@@ -1,12 +1,13 @@
 // What the rest of the plugin uses of the session tree: its tools, RPC, event module, context hook and tick jobs
-// for `src/index.ts`, and the lineage and subtree queries and types `person/` reads.
+// for `src/index.ts`, the lineage and subtree queries and types `person/` reads, and what `memory/` reads of each session.
 export { dirtyOf, headOf, inspectWorktree } from "./cleanup.js";
 export { shapeContext } from "./context.js";
-export { lineageIn, nativeRootOf, readLimits, readNativeChildren } from "./domain.js";
+export { busy, lineageIn, nativeRootOf, readLimits, readNativeChildren } from "./domain.js";
 export { together, treeEvents, waitsOn } from "./events.js";
 export { deliverReleased } from "./group.js";
-export { allEntries, answeringTop, lineage, pruneExpired, RETENTION_MS } from "./roster.js";
+export { contextOf } from "./panel.js";
+export { allEntries, answeringTop, childrenOf, indexedLineage, lineage, pruneExpired, reportState, RETENTION_MS } from "./roster.js";
 export { subtree } from "./subtree.js";
 export { registerTreeRpc } from "./rpc-handlers.js";
 export { addTreeTools } from "./tools.js";
-export { wakeMissed } from "./wake.js";
+export { stalledAmong, wakeMissed } from "./wake.js";

package/dist/tree/mascot.js

@@ -95,7 +95,7 @@ export function digby(rise, { top = 6, eyes = "open", slump = false, shift = 0,
         span(head + 2, 8, "k", (column) => !eyeColumns.includes(column), lean(2));
     span(head + 4, 2, "a", undefined, lean(4));
     span(10, SIZE, ".", (column) => column >= 6 && column <= 9);
-    span(10, top, mound, (column) => column >= 6 && column <= 9, shift);
+    span(10, top, mound, (column) => column + shift >= 6 && column + shift <= 9, shift);
     span(11, 10, mound, undefined, shift);
     span(12, 12, mound, undefined, shift);
     for (const row of [13, 14, 15])

package/dist/tree/ports.d.ts

@@ -286,8 +286,8 @@ export interface ExecutionError {
 }
 export interface WatchPorts {
     readonly storage: RosterStorage;
-    /** `context` reads the last reply of a session that ended its turn without reporting. */
-    readonly session: Pick<Context["session"], "synthetic" | "context">;
+    /** `context` reads the last reply of a session that ended its turn without reporting; `get` is what every member joins with too. */
+    readonly session: Pick<Context["session"], "synthetic" | "context" | "get">;
     readonly event: Pick<Context["event"], "subscribe">;
     /** The permission domains of every loaded location, which the `Waits` suppliers ask; an isolated child's are in its worktree's. */
     readonly permissions: () => Iterable<Pick<Context["permission"], "list">>;
@@ -316,5 +316,7 @@ export interface ContextPorts {
     readonly limits: Limits;
     /** Each session's depth once looked up: null for one nobody spawned that has started none, until it starts one. */
     readonly roles: Map<string, number | null>;
+    /** Tools of other modules hidden from a leaf alongside courier_spawn; `src/index.ts` names courier_recall and courier_note. */
+    readonly hiddenFromLeaf?: ReadonlyArray<string>;
     readonly log: (message: string) => void;
 }

package/dist/tree/roster.d.ts

@@ -1,3 +1,4 @@
+import { type Status } from "../kernel/protocol.js";
 import type { RosterEntry, RosterStorage } from "./ports.js";
 /**
  * Entries older than this are dropped when their parent's roster is read, and on plugin setup,
@@ -11,6 +12,22 @@ export declare function allEntries(storage: RosterStorage): Promise<RosterEntry[
  * courier_spawn did not start; empty when courier_spawn did not start the session.
  */
 export declare function lineage(storage: RosterStorage, sessionID: string): Promise<RosterEntry[]>;
+/** `lineage` by the reverse index alone: empty, without scanning the roster, when it does not name the session. */
+export declare function indexedLineage(storage: RosterStorage, sessionID: string): Promise<RosterEntry[]>;
+/** The sessions a session started, oldest first, expired entries included. */
+export declare function childrenOf(storage: RosterStorage, parentID: string): Promise<RosterEntry[]>;
+/**
+ * What another module reads of a spawned session's report: `known` once a prompt was noted, whether it `owes` one, how
+ * its wait `ended` when not by a report, the `status` of its last report, and whether courier_stop `stopped` it since its last prompt.
+ */
+export interface ReportState {
+    readonly known: boolean;
+    readonly owes: boolean;
+    readonly ended?: "failed" | "interrupted";
+    readonly status?: Status;
+    readonly stopped: boolean;
+}
+export declare function reportState(storage: RosterStorage, sessionID: string): Promise<ReportState>;
 /**
  * The top of a spawned session's lineage, where its permission requests and questions go, since the
  * person is there. Throws unless the session was spawned and `callerID` is that top; `what` names it.

package/dist/tree/roster.js

@@ -1,5 +1,7 @@
 import { existsSync } from "node:fs";
+import { isStatus } from "../kernel/protocol.js";
 import { forgetChild, forgetReports } from "./forget.js";
+import { stoppedSincePrompt } from "./report.js";
 import { childStore } from "./store.js";
 /**
  * Entries older than this are dropped when their parent's roster is read, and on plugin setup,
@@ -17,6 +19,28 @@ export async function allEntries(storage) {
 export async function lineage(storage, sessionID) {
     return childStore(storage).lineage(sessionID);
 }
+/** `lineage` by the reverse index alone: empty, without scanning the roster, when it does not name the session. */
+export async function indexedLineage(storage, sessionID) {
+    return childStore(storage).indexedLineage(sessionID);
+}
+/** The sessions a session started, oldest first, expired entries included. */
+export async function childrenOf(storage, parentID) {
+    return childStore(storage).children(parentID);
+}
+export async function reportState(storage, sessionID) {
+    const children = childStore(storage);
+    const [{ prompt, settled }, stopped] = await Promise.all([children.notes(sessionID, ["prompt", "settled"]), stoppedSincePrompt(children, sessionID)]);
+    const known = prompt.at !== undefined;
+    const done = known && settled.at !== undefined && settled.at >= prompt.at;
+    const by = settled.by;
+    return {
+        known,
+        owes: known && !done,
+        ...(done && (by === "failed" || by === "interrupted") ? { ended: by } : {}),
+        ...(isStatus(settled.status) ? { status: settled.status } : {}),
+        stopped,
+    };
+}
 /**
  * The top of a spawned session's lineage, where its permission requests and questions go, since the
  * person is there. Throws unless the session was spawned and `callerID` is that top; `what` names it.