opencode-courier 0.13.8 → 0.15.0

package/dist/memory/domain.js

@@ -1,61 +1,36 @@
-/**
- * The memory's pure rules, on plain data: the option, a record's shape, each part's status, the split line and its revisions,
- * its reads and pin, the retention and how a refresh keeps the parts the roster has forgotten. Imports nothing of the plugin's but `kernel/` and `platform/json.ts`.
- */
 import { STATUSES } from "../kernel/protocol.js";
 import { obj } from "../platform/json.js";
-/** How many unpinned records a project keeps: those with a lesson first, then the newest by `movedAt`. */
 export const MAX_RECORDS = 30;
-/** Unpinned records that last moved longer ago than this are dropped when the plugin loads. */
 export const RETENTION_MS = 90 * 24 * 60 * 60_000;
-/** A record's `split` while its top has stated no split line. */
 export const NOT_STATED = "not stated";
-/** The most characters a lesson holds: courier_note refuses what is longer, and a record written by hand is clipped when read. */
 export const LESSON_MAX = 300;
-/**
- * How a part stands: its last report's status, how its wait ended without one (`failed`, `interrupted`), `stopped` by
- * courier_stop, `gone` before it settled, `stalled` on a message it will not take, or `out`: it owes a report.
- */
 export const PART_STATUSES = [...STATUSES, "interrupted", "stopped", "gone", "stalled", "out"];
 export const isPartStatus = (value) => typeof value === "string" && PART_STATUSES.includes(value);
-/** Whether a part has settled, as every part of a finished tree has: it neither owes a report nor is stalled. */
 export const isSettled = (status) => status !== "out" && status !== "stalled";
-/** How many revisions of the split line a record keeps, the newest. */
 export const MAX_REVISIONS = 3;
-/** The `memory` option: whether records are kept and listed; on unless `false`. */
 export function readMemory(options) {
     const value = obj(options).memory;
     if (value === undefined || typeof value === "boolean")
         return { memory: value !== false, problems: [] };
     return { memory: true, problems: [`memory must be true or false, not ${JSON.stringify(value)}; using true`] };
 }
-/** A line beginning with `split:` after any markdown (whitespace, emphasis, heading, quote and list marks). */
 const STARTS_SPLIT = /^[\s*_#>`-]*split:/i;
-/** A line holding `split:` as a word. */
 const HOLDS_SPLIT = /\bsplit:/i;
-/** The split line a text states, as the real-model checker reads it: a line beginning with `split:` after any markdown, else one holding it. */
 export function splitLineOf(text) {
     const lines = text.split("\n");
     return (lines.find((line) => STARTS_SPLIT.test(line)) ?? lines.find((line) => HOLDS_SPLIT.test(line)))?.trim();
 }
-/** Whether a split line is stated, beginning with `split:` after any markdown, not a passing mention nor `not stated`. */
 export const isStated = (line) => STARTS_SPLIT.test(line);
-/** The record's `split` once `text` is read: kept once stated; a mention gives way to the first stated line; `not stated` to either. */
 export function splitOf(recorded, text) {
     if (isStated(recorded))
         return recorded;
     const found = splitLineOf(text);
     return found !== undefined && (recorded === NOT_STATED || isStated(found)) ? found : recorded;
 }
-/** Every line of a text that begins with `split:` after any markdown, trimmed: a passing mention of a split is none. */
 export const splitLinesOf = (text) => text
     .split("\n")
     .filter((line) => STARTS_SPLIT.test(line))
     .map((line) => line.trim());
-/**
- * The lines after the one recorded last: after its reply, else (compacted, or unread by an overlapping refresh) those stated since its
- * time; without a revision, after `split`'s first statement; all when neither is found.
- */
 function statedSince(previous, stated) {
     const last = previous.revisions?.at(-1);
     const words = (line) => splitProse(line.text);
@@ -68,10 +43,6 @@ function statedSince(previous, stated) {
         return stated.filter((line) => line.at !== undefined && line.at > last.at);
     return stated.slice(stated.findLastIndex((line) => words(line) === splitProse(last.text)) + 1);
 }
-/**
- * The revisions once the split lines `stated` are read at a refresh at `at` with `parts` parts: those `statedSince` the line recorded
- * last, each appended when its words differ from the line before, so a re-read appends nothing.
- */
 export function revise(previous, stated, at, parts) {
     const recorded = splitProse(previous.revisions?.at(-1)?.text ?? previous.split);
     const { added } = statedSince(previous, stated).reduce(({ last, added }, line) => {
@@ -81,28 +52,18 @@ export function revise(previous, stated, at, parts) {
     const revisions = [...(previous.revisions ?? []), ...added].slice(-MAX_REVISIONS);
     return revisions.length ? revisions : undefined;
 }
-/**
- * The split and revisions once the stated line `found` replaces a mention: when `found` is among the revisions (recorded beside the
- * mention before #294), the first of them was stated first and is `split`, the rest stay; else `found` is, beside them all.
- */
 export function replacingMention(found, revisions) {
     const [first, ...rest] = revisions ?? [];
     if (!first || !revisions.some((one) => splitProse(one.text) === splitProse(found)))
         return { split: found, ...(first ? { revisions } : {}) };
     return { split: first.text, ...(rest.length ? { revisions: rest } : {}) };
 }
-/** Heading, quote and list marks before a line's words, each with the space markdown puts after it, unlike the `#` of `#282`. */
 const BLOCK_MARKS = /^(?:\s|#+\s|>\s|[-+*]\s|\d+[.)]\s)*/;
-/** A bold or bold italic span within a line, opening at a word's start and closing at its end, unlike the asterisks of `2**3` or a `**` beside a slash. */
 const BOLD = /(?<=^|[\s(["'])(\*\*\*?)([^\s*/][^*]*?)(?<![\s(/])\1(?=$|[\s.,;:!?)\]"'])/gu;
-/** An italic span opens only before a letter, digit, quote or code span, which tells it from the globs of `*.ts and *.md` or `src/*.ts`. */
 const ITALIC = /(?<=^|[\s(["'])\*([\p{L}\p{N}\0"'][^*]*?)(?<![\s(/])\*(?=$|[\s.,;:!?)\]"'])/gu;
-/** A label the line opens with in underscores or a code span (`_split:_`, `` `split:` ``), which its colon tells from `__init__`. */
 const LABEL = /^(__?|`)([^\s_`][^_`]*:)\1(?=\s)/;
-/** A code span, whose asterisks are its words', and the stand-in it is masked by while emphasis is taken off. */
 const CODE_SPAN = /`[^`]*`/g;
 const MASKED = /\0(\d+)\0/g;
-/** Marks taken off a line they wrap whole, with what its words must open with; `*` may recur inside as a glob's, the others not at all. */
 const STARS = [
     ["***", /[^\s*/]/],
     ["**", /[^\s*/]/],
@@ -123,7 +84,6 @@ const unwrapped = (line, marks) => {
     const found = marks.find(wraps);
     return found ? inner(found[0]).trim() : line;
 };
-/** A split line as the listing shows it: one line, without its block marks, the asterisks wrapping it or a span in it, nor an underscore or code span wrapping it. */
 export function splitProse(split) {
     const code = [];
     const masked = oneLine(split.replaceAll("\0", ""))
@@ -133,7 +93,6 @@ export function splitProse(split) {
     const prose = unwrapped(masked, STARS).replace(BOLD, "$2").replace(ITALIC, "$1");
     return unwrapped(prose.replace(MASKED, (_, i) => code[Number(i)]), WRAPS);
 }
-/** A part's status by `Standing`; one whose report state is not known is still out. */
 export function partStatus({ stopped, stalled, report }) {
     if (stopped)
         return "stopped";
@@ -145,65 +104,50 @@ export function partStatus({ stopped, stalled, report }) {
         return report.ended;
     return report.status ?? "done";
 }
-/**
- * A part whose session could not be read, from what was read of it and its last record: its title, duration and cost as
- * last recorded; once OpenCode no longer knows it (`gone`), settled as read, else as last recorded, else `gone`.
- */
+export function subagentStatus({ running, stalled, outcome }) {
+    if (stalled)
+        return "stalled";
+    if (running)
+        return "out";
+    return outcome === "failed" || outcome === "interrupted" ? outcome : "done";
+}
 export function unreadPart(read, last, gone) {
     const settledLast = last && isSettled(last.status) ? last.status : "gone";
     const status = !gone || isSettled(read.status) ? read.status : settledLast;
     const { title, duration, cost } = last ?? read;
     return { ...read, title, status, ...(duration !== undefined ? { duration } : {}), ...(cost !== undefined ? { cost } : {}) };
 }
-/**
- * The parts of a refreshed record: those recorded before, in their order, each as `current` has it (read now, or found
- * gone), else as last recorded, then those first seen now, in the order the tree is drawn.
- */
 export function mergeParts(previous, current) {
     const now = new Map(current.map((part) => [part.sessionID, part]));
     const kept = previous.map((part) => now.get(part.sessionID) ?? part);
     const known = new Set(previous.map((part) => part.sessionID));
     return [...kept, ...current.filter((part) => !known.has(part.sessionID))];
 }
-/** `recalled` after one more call at `at`, the top's first call noted when `byTop`. */
 export function noteRecall(recalled, byTop, at) {
     const calls = (recalled?.calls ?? 0) + 1;
     const first = recalled?.at ?? (byTop ? at : undefined);
     return first === undefined ? { calls } : { at: first, calls };
 }
-/** A text as the one line a lesson is: whitespace and line breaks collapsed to spaces, trimmed. */
 export const oneLine = (text) => text.replace(/\s+/g, " ").trim();
-/**
- * A hand-written lesson's text as one line, clipped at `LESSON_MAX`; `clipped` is the length it had when it was clipped.
- * courier_note does not clip: it refuses a line over `LESSON_MAX` (`note.ts`).
- */
 export function lessonText(text) {
     const line = oneLine(text);
     if (line.length <= LESSON_MAX)
         return { text: line };
     return { text: line.slice(0, LESSON_MAX).trimEnd(), clipped: line.length };
 }
-/** One reader tree's `reads` after courier_recall listed the record or gave it in full at `at`. */
 export function noteRead(reads, kind, at) {
     return { shown: (reads?.shown ?? 0) + (kind === "shown" ? 1 : 0), read: (reads?.read ?? 0) + (kind === "read" ? 1 : 0), at: Math.max(reads?.at ?? 0, at) };
 }
-/** The reads of every reader tree as one: the counts summed, `at` the latest; none without a reader. */
 export function sumReads(reads) {
     if (!reads.length)
         return undefined;
     return reads.reduce((sum, one) => ({ shown: sum.shown + one.shown, read: sum.read + one.read, at: Math.max(sum.at, one.at) }));
 }
-/**
- * The records a project keeps at `now`: every pinned one, whatever its age, and of the rest the first `MAX_RECORDS` by
- * whether each has a lesson, then by `movedAt`, none older than `RETENTION_MS`; the rest are dropped.
- */
 export function keep(records, now) {
     const pinned = records.filter((record) => record.pinned);
-    // Aged out first, so that a stale record takes no slot from a live one behind it in the order.
     const live = records.filter((record) => !record.pinned && now - record.movedAt <= RETENTION_MS);
     const ordered = live.toSorted((a, b) => Number(Boolean(b.lesson)) - Number(Boolean(a.lesson)) || b.movedAt - a.movedAt);
     const kept = [...pinned, ...ordered.slice(0, MAX_RECORDS)];
     return { kept, dropped: records.filter((record) => !kept.includes(record)) };
 }
-/** Records as courier_recall and the memory view list them: the pinned first, then by when each last moved, newest first. */
 export const pinnedFirst = (records) => records.toSorted((a, b) => Number(Boolean(b.pinned)) - Number(Boolean(a.pinned)) || b.movedAt - a.movedAt);

package/dist/memory/events.d.ts

@@ -1,6 +1,5 @@
 import type { EventModule, EventPorts } from "../platform/events.js";
 import type { MemoryState, RefreshPorts } from "./ports.js";
-/** OpenCode's `session.execution.*` events, as the memory reads them. */
 interface Execution {
     readonly id: string;
     readonly created?: number;
@@ -9,18 +8,8 @@ interface Execution {
         readonly reason?: string;
     };
 }
-/** The ports the event module runs on: the watcher's, which every hub-v2 member joins with. */
 export type MemoryEventPorts = RefreshPorts & EventPorts;
-/**
- * The top of the tree a session is in: by the reverse index for a spawned one, else the session itself when it called
- * courier_recall or has started sessions; undefined for a session in no tree.
- */
 export declare function topOf(ports: Pick<RefreshPorts, "storage">, state: Pick<MemoryState, "tops">, sessionID: string): Promise<string | undefined>;
-/** A turn ended in a tree: its record is written again, once however many subscriptions see the event. Returns the top refreshed. */
 export declare function noteTurnEnd(ports: RefreshPorts, state: MemoryState, event: Execution): Promise<string | undefined>;
-/**
- * Keeps each tree's record current: after the tree's and the person's notices of a turn's end have gone out, and the
- * report state it settled is written, the record of the tree it belongs to is rebuilt. A failure is logged, never thrown.
- */
 export declare function memoryEvents(state: MemoryState): EventModule<MemoryEventPorts>;
 export {};

package/dist/memory/events.js

@@ -3,10 +3,6 @@ import { childrenOf, endsIdle, indexedLineage } from "../tree/index.js";
 import { refresh } from "./record.js";
 const TURN_END_TYPES = ["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"];
 const TURN_ENDS = new Set(TURN_END_TYPES);
-/**
- * The top of the tree a session is in: by the reverse index for a spawned one, else the session itself when it called
- * courier_recall or has started sessions; undefined for a session in no tree.
- */
 export async function topOf(ports, state, sessionID) {
     const chain = await indexedLineage(ports.storage, sessionID);
     if (chain.length)
@@ -15,16 +11,13 @@ export async function topOf(ports, state, sessionID) {
         return sessionID;
     return (await childrenOf(ports.storage, sessionID)).length ? sessionID : undefined;
 }
-/** A turn ended in a tree: its record is written again, once however many subscriptions see the event. Returns the top refreshed. */
 export async function noteTurnEnd(ports, state, event) {
     const top = await topOf(ports, state, event.data.sessionID);
     if (top === undefined)
         return undefined;
-    // A shutdown's interruption is resumed on the next start, unless a plain decline ended the turn: its transcript ends on an aborted step.
+    // a plain permission decline also reports "shutdown" (api-notes)
     if (event.data.reason === "shutdown" && !endsIdle(await ports.session.context({ sessionID: event.data.sessionID }).catch(() => [])))
         return undefined;
-    // Claimed after the lookup, so other sessions' turns do not crowd `seen`; released on a failure, as a write is
-    // the same twice, so the hub's other subscription may still make it.
     if (!claim(state.seen, event.id))
         return undefined;
     try {
@@ -36,10 +29,6 @@ export async function noteTurnEnd(ports, state, event) {
     }
     return top;
 }
-/**
- * Keeps each tree's record current: after the tree's and the person's notices of a turn's end have gone out, and the
- * report state it settled is written, the record of the tree it belongs to is rebuilt. A failure is logged, never thrown.
- */
 export function memoryEvents(state) {
     return {
         types: TURN_END_TYPES,

package/dist/memory/forget.d.ts

@@ -1,10 +1,5 @@
 import type { MemoryPorts } from "./ports.js";
-/** What forgetting did: the record is gone, only its lesson is, or there was nothing to forget. */
 export type Forgotten = "record" | "lesson" | "none";
-/**
- * Forgets the record of the tree under `sessionID` in the ports' project, as the memory view's `x` does, or with
- * `lesson` only its lesson, writing the record back without it. Whatever the memory option says: it only removes.
- */
 export declare function forget(ports: Pick<MemoryPorts, "storage" | "projectID">, sessionID: string, { lesson }?: {
     lesson?: boolean | undefined;
 }): Promise<Forgotten>;

package/dist/memory/forget.js

@@ -1,8 +1,4 @@
 import { memoryStore } from "./store.js";
-/**
- * Forgets the record of the tree under `sessionID` in the ports' project, as the memory view's `x` does, or with
- * `lesson` only its lesson, writing the record back without it. Whatever the memory option says: it only removes.
- */
 export async function forget(ports, sessionID, { lesson = false } = {}) {
     const store = memoryStore(ports.storage);
     const record = await store.get(ports.projectID, sessionID);

package/dist/memory/index.js

@@ -1,5 +1,3 @@
-// What the rest of the plugin uses of the memory: its tools, event module, RPC, option and sweep for `src/index.ts`,
-// and the record's types.
 export { LESSON_MAX, MAX_RECORDS, NOT_STATED, readMemory, RETENTION_MS } from "./domain.js";
 export { memoryEvents } from "./events.js";
 export { lessonsOf } from "./lessons.js";

package/dist/memory/lessons.d.ts

@@ -1,12 +1,4 @@
 import { type Entry } from "../tree/index.js";
 import type { MemoryPorts } from "./ports.js";
-/**
- * The `lessons` entry of this project, as `courier_spawn` writes it to a spawned session before its prompt and to a root at
- * its first spawn: none with the memory option off, or while no record of the project holds a lesson.
- */
 export declare function lessonsOf(ports: MemoryPorts): Promise<ReadonlyArray<Entry>>;
-/**
- * Puts the project's lessons entry again, once a lesson was written, on the writer's tree's top, the top's current children
- * below `maxDepth` and the writer, each only where it differs from the entry stored; a failure is logged. Returns the sessions put.
- */
-export declare function relesson(ports: MemoryPorts, writerID: string, top: string): Promise<string[]>;
+export declare function relesson(ports: MemoryPorts, top: string): Promise<string[]>;

package/dist/memory/lessons.js

@@ -3,21 +3,13 @@ import { childrenOf } from "../tree/index.js";
 import { pinnedFirst } from "./domain.js";
 import { memoryStore } from "./store.js";
 import { LESSONS_KEY, lessonsEntry } from "./text.js";
-/**
- * The `lessons` entry of this project, as `courier_spawn` writes it to a spawned session before its prompt and to a root at
- * its first spawn: none with the memory option off, or while no record of the project holds a lesson.
- */
 export async function lessonsOf(ports) {
     if (!ports.memory)
         return [];
     const value = lessonsEntry(pinnedFirst(await memoryStore(ports.storage).ofProject(ports.projectID)));
     return value === undefined ? [] : [{ key: LESSONS_KEY, value }];
 }
-/**
- * Puts the project's lessons entry again, once a lesson was written, on the writer's tree's top, the top's current children
- * below `maxDepth` and the writer, each only where it differs from the entry stored; a failure is logged. Returns the sessions put.
- */
-export async function relesson(ports, writerID, top) {
+export async function relesson(ports, top) {
     const entries = ports.session.instructions?.entry;
     if (!entries)
         return [];
@@ -29,7 +21,7 @@ export async function relesson(ports, writerID, top) {
         if (!entry)
             return [];
         const children = ports.maxDepth > 1 ? await childrenOf(ports.storage, top) : [];
-        sessions = [...new Set([top, ...children.map((child) => child.sessionID), writerID])];
+        sessions = [top, ...children.map((child) => child.sessionID)];
     }
     catch (error) {
         ports.log(`courier_note: the lessons entry could not be read again: ${String(error)}`);
@@ -45,7 +37,6 @@ export async function relesson(ports, writerID, top) {
             return true;
         }
         catch (error) {
-            // A child on the roster that OpenCode no longer knows is a normal path, not one to log.
             if (!isNotFound(error))
                 ports.log(`courier_note: the lessons entry of ${sessionID} could not be written: ${String(error)}`);
             return false;

package/dist/memory/note.d.ts

@@ -3,16 +3,12 @@ import type { MemoryPorts } from "./ports.js";
 export interface NoteInput {
     readonly text: string;
 }
-/**
- * Why courier_note wrote nothing: the option is off, the caller is a leaf, its text is empty or longer than `LESSON_MAX`
- * (`length` is what it had as one line), or its tree has no record to write on.
- */
 export type Refusal = {
     readonly kind: "off";
 } | {
-    readonly kind: "leaf";
+    readonly kind: "below";
     readonly depth: number;
-    readonly maxDepth: number;
+    readonly top: string;
 } | {
     readonly kind: "empty";
 } | {
@@ -22,7 +18,6 @@ export type Refusal = {
     readonly kind: "unrecorded";
     readonly top: string;
 };
-/** What courier_note gives: the lesson written on the caller's tree's record, with the one it replaced, or why it was not. */
 export type Noted = {
     readonly kind: "noted";
     readonly projectID: string;
@@ -30,8 +25,4 @@ export type Noted = {
     readonly lesson: Lesson;
     readonly replaced?: Lesson;
 } | Refusal;
-/**
- * courier_note: writes `text`, as one line of at most `LESSON_MAX` characters (longer is refused, never clipped), as the lesson
- * on the record of the caller's own tree in this project, replacing the one there; the top is the top of the caller's lineage, or itself.
- */
 export declare function note(ports: MemoryPorts, callerID: string, input: NoteInput): Promise<Noted>;

package/dist/memory/note.js

@@ -2,31 +2,25 @@ import { lineage } from "../tree/index.js";
 import { LESSON_MAX, oneLine } from "./domain.js";
 import { relesson } from "./lessons.js";
 import { memoryStore } from "./store.js";
-/**
- * courier_note: writes `text`, as one line of at most `LESSON_MAX` characters (longer is refused, never clipped), as the lesson
- * on the record of the caller's own tree in this project, replacing the one there; the top is the top of the caller's lineage, or itself.
- */
 export async function note(ports, callerID, input) {
     if (!ports.memory)
         return { kind: "off" };
     const chain = await lineage(ports.storage, callerID);
-    const depth = chain.length;
-    if (depth >= ports.maxDepth)
-        return { kind: "leaf", depth, maxDepth: ports.maxDepth };
+    const top = chain.at(-1)?.parentID ?? callerID;
+    if (chain.length)
+        return { kind: "below", depth: chain.length, top };
     const text = oneLine(typeof input.text === "string" ? input.text : "");
     if (!text)
         return { kind: "empty" };
     if (text.length > LESSON_MAX)
         return { kind: "long", length: text.length };
-    const top = chain.at(-1)?.parentID ?? callerID;
     const store = memoryStore(ports.storage);
     const { projectID } = ports;
     const record = await store.get(projectID, top);
     if (!record)
         return { kind: "unrecorded", top };
-    const lesson = { text, at: ports.now(), ...(depth ? { depth } : {}) };
+    const lesson = { text, at: ports.now() };
     await store.put(projectID, top, { ...record, lesson });
-    // The lessons entry of the top, its children and the writer moves with it; the next tree's sessions get it at their spawn.
-    await relesson(ports, callerID, top);
+    await relesson(ports, top);
     return { kind: "noted", projectID, top, lesson, ...(record.lesson ? { replaced: record.lesson } : {}) };
 }

package/dist/memory/pin.d.ts

@@ -1,8 +1,3 @@
 import type { MemoryPorts } from "./ports.js";
-/** What pinning did: the record is pinned, unpinned, or there is no record to pin. */
 export type PinOutcome = "pinned" | "unpinned" | "none";
-/**
- * Pins the record of the tree under `sessionID` in the ports' project, as the memory view's `p` does, or with `pinned`
- * false unpins it; a record pinned already keeps when it was. Whatever the memory option says: a pin is the person's.
- */
 export declare function pin(ports: Pick<MemoryPorts, "storage" | "projectID" | "now">, sessionID: string, pinned: boolean): Promise<PinOutcome>;

package/dist/memory/pin.js

@@ -1,8 +1,4 @@
 import { memoryStore } from "./store.js";
-/**
- * Pins the record of the tree under `sessionID` in the ports' project, as the memory view's `p` does, or with `pinned`
- * false unpins it; a record pinned already keeps when it was. Whatever the memory option says: a pin is the person's.
- */
 export async function pin(ports, sessionID, pinned) {
     const store = memoryStore(ports.storage);
     const record = await store.get(ports.projectID, sessionID);

package/dist/memory/ports.d.ts

@@ -1,55 +1,35 @@
-/** The memory's ports: what refreshing a record and courier_recall need of the plugin context, and what the process shares. */
 import type { Plugin } from "@opencode/plugin";
 import type { Storage } from "../platform/storage.js";
-import type { Instructions, ModelWindow } from "../tree/index.js";
+import type { Instructions, Lister, ModelWindow } from "../tree/index.js";
 import type { Pinned, ReadKind, Reads, StoredRecord, TreeRecord } from "./domain.js";
 export type { Lesson, PartRecord, PartStatus, Pinned, ReadKind, Reads, Recalled, Revision, StoredRecord, TreeRecord } from "./domain.js";
 type Context = Plugin.Context;
-/** What refreshing a record runs on: every hub-v2 member's watch ports have these, so the event module runs through any. */
 export interface RefreshPorts {
     readonly storage: Storage;
-    readonly session: Pick<Context["session"], "get" | "context">;
+    readonly session: Pick<Context["session"], "get" | "context"> & Lister;
     readonly now: () => number;
     readonly log: (message: string) => void;
 }
-/** What courier_recall and courier_note run on: one instance's ports. */
 export interface MemoryPorts extends RefreshPorts {
-    /** With `instructions`, the keyed session entries, which courier_note puts the lessons entry through; missing on a host before 2.2.0. */
     readonly session: RefreshPorts["session"] & Instructions;
-    /** The project of the plugin's location, whose records the tools read and write. */
     readonly projectID: string;
-    /** The `memory` option: off, and the tools write and list nothing. */
     readonly memory: boolean;
-    /** The tree's `maxDepth` limit: a session at it is a leaf, which courier_note refuses. */
     readonly maxDepth: number;
 }
-/** What every plugin instance in the process shares of the memory, under a fixed key outside the hub. */
 export interface MemoryState {
-    /** The context windows of the models known, by `<providerID>/<modelID>`, filled as each instance loads. */
     readonly windows: Map<string, ModelWindow>;
-    /** The directories of the locations whose instance has memory off: no record is written for a tree whose top runs there. */
     readonly off: Set<string>;
-    /** The top sessions that called courier_recall, whose turn ends refresh their record before they have started a session. */
     readonly tops: Set<string>;
-    /** The turn ends recorded, so the hub's two subscriptions refresh once. */
     readonly seen: Set<string>;
 }
-/** The records, by project and top session, each read with its reads and pin, which lie beside it and are written apart. */
 export interface MemoryStore {
     get(projectID: string, sessionID: string): Promise<TreeRecord | undefined>;
-    /** Writes the record's facts; its `reads` and `pinned` are left out, as nothing but `noteRead` and `pin` write them. */
     put(projectID: string, sessionID: string, record: TreeRecord): Promise<void>;
-    /** Removes the record with its reads and pin. */
     remove(projectID: string, sessionID: string): Promise<void>;
-    /** Counts a listing or a full read of the record by the tree under `by` at `at`; gives that tree's reads of it. */
     noteRead(projectID: string, sessionID: string, by: string, kind: ReadKind, at: number): Promise<Reads>;
-    /** Pins the record, or with `undefined` unpins it. */
     pin(projectID: string, sessionID: string, pinned: Pinned | undefined): Promise<void>;
-    /** A project's records, in key order. */
     ofProject(projectID: string): Promise<StoredRecord[]>;
-    /** Every project's records. */
     all(): Promise<StoredRecord[]>;
-    /** The trees with reads or a pin but no record, left by a record removed while it was read or pinned. */
     strays(): Promise<Array<{
         projectID: string;
         sessionID: string;

package/dist/memory/recall.d.ts

@@ -3,7 +3,6 @@ import type { MemoryPorts, MemoryState } from "./ports.js";
 export interface RecallInput {
     readonly sessionID?: string;
 }
-/** What courier_recall gives: the option is off, the project's records with the caller's tree named, one record in full, or none under that session. */
 export type Recall = {
     readonly kind: "off";
 } | {
@@ -20,8 +19,4 @@ export type Recall = {
     readonly projectID: string;
     readonly sessionID: string;
 };
-/**
- * courier_recall: notes the call on the caller's tree, then lists the project's records, pinned first and then newest first,
- * or gives the one under `sessionID` in full, each counted on the other trees' records; with the memory option off, nothing is written or read.
- */
 export declare function recall(ports: MemoryPorts, state: Pick<MemoryState, "tops">, callerID: string, input: RecallInput): Promise<Recall>;

package/dist/memory/recall.js

@@ -3,11 +3,9 @@ import { finite, millis } from "../platform/json.js";
 import { lineage } from "../tree/index.js";
 import { NOT_STATED, noteRead, noteRecall, pinnedFirst } from "./domain.js";
 import { memoryStore } from "./store.js";
-/** The top of the caller's tree: the top of its lineage, or itself. */
 async function topOfCaller(ports, callerID) {
     return (await lineage(ports.storage, callerID)).at(-1)?.parentID ?? callerID;
 }
-/** Notes the call on the caller's tree's record, which is written now if the tree has none yet, so the call is remembered before any session is started. */
 async function note(ports, top, byTop) {
     const store = memoryStore(ports.storage);
     const now = ports.now();
@@ -26,10 +24,6 @@ async function note(ports, top, byTop) {
         parts: [],
     });
 }
-/**
- * Counts, on each record of another tree, that this call listed it or gave it in full, best effort: a count lost is
- * logged, never the call's failure. Gives the reads of the reader's tree on each, in order, or undefined where it failed.
- */
 function count(ports, top, kind, sessionIDs) {
     const store = memoryStore(ports.storage);
     const now = ports.now();
@@ -38,10 +32,6 @@ function count(ports, top, kind, sessionIDs) {
         return undefined;
     })));
 }
-/**
- * courier_recall: notes the call on the caller's tree, then lists the project's records, pinned first and then newest first,
- * or gives the one under `sessionID` in full, each counted on the other trees' records; with the memory option off, nothing is written or read.
- */
 export async function recall(ports, state, callerID, input) {
     if (!ports.memory)
         return { kind: "off" };
@@ -50,13 +40,11 @@ export async function recall(ports, state, callerID, input) {
     addBounded(state.tops, top, SEEN_MAX);
     const store = memoryStore(ports.storage);
     const { projectID } = ports;
-    // Some models send null, or an empty string, for an optional field they leave out.
     const wanted = typeof input.sessionID === "string" ? input.sessionID.trim() : "";
     if (wanted) {
         const record = await store.get(projectID, wanted);
         if (!record)
             return { kind: "missing", projectID, sessionID: wanted };
-        // Another tree's record is given with this read added to the reads just read; the caller's own is not counted.
         const [counted] = wanted === top ? [undefined] : await count(ports, top, "read", [wanted]);
         const reads = counted ? noteRead(record.reads, "read", counted.at) : record.reads;
         return { kind: "record", projectID, record: { ...record, ...(reads ? { reads } : {}), projectID, sessionID: wanted } };

package/dist/memory/record.d.ts

@@ -1,7 +1,3 @@
 import { type TreeRecord } from "./domain.js";
 import type { MemoryState, RefreshPorts } from "./ports.js";
-/**
- * Writes the record of the tree under `top` as it stands at `at`, after the turn of `ended`; a part the roster has forgotten
- * keeps its last recorded state, unless found gone before it settled. Nothing for a top unknown to OpenCode or with memory off.
- */
 export declare function refresh(ports: RefreshPorts, state: Pick<MemoryState, "windows" | "off">, top: string, at: number, ended?: string): Promise<TreeRecord | undefined>;