opencode-courier 0.7.3 → 0.9.0

package/dist/memory/domain.d.ts

@@ -0,0 +1,188 @@
+/**
+ * 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 { type Status } from "../kernel/protocol.js";
+/** How many unpinned records a project keeps: those with a lesson first, then the newest by `movedAt`. */
+export declare const MAX_RECORDS = 30;
+/** Unpinned records that last moved longer ago than this are dropped when the plugin loads. */
+export declare const RETENTION_MS: number;
+/** A record's `split` while its top has stated no split line. */
+export declare 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 declare 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 declare const PART_STATUSES: readonly ["done", "partial", "blocked", "failed", "interrupted", "stopped", "gone", "stalled", "out"];
+export type PartStatus = (typeof PART_STATUSES)[number];
+export declare const isPartStatus: (value: unknown) => value is PartStatus;
+/** Whether a part has settled, as every part of a finished tree has: it neither owes a report nor is stalled. */
+export declare const isSettled: (status: PartStatus) => status is "done" | "partial" | "blocked" | "failed" | "interrupted" | "stopped" | "gone";
+/** One session started in a tree, as its record keeps it; `duration` is in milliseconds, `context` a share of its model's window. */
+export interface PartRecord {
+    readonly sessionID: string;
+    readonly title: string;
+    /** 1 for a session the top started. */
+    readonly depth: number;
+    readonly isolated: boolean;
+    readonly group?: string;
+    readonly status: PartStatus;
+    /** From its start to the end of its last turn, or to the refresh while it runs. */
+    readonly duration?: number;
+    readonly cost?: number;
+    /** How full its context was at the end, 0 to 1, when its model's window is known. */
+    readonly context?: number;
+    /** How many courier_spawn calls of its own failed, refused by a limit mostly. */
+    readonly refused?: number;
+}
+/** Whether and when the top called courier_recall (`at`, its first call), and how many calls the tree made in all. */
+export interface Recalled {
+    readonly at?: number;
+    readonly calls: number;
+}
+/**
+ * The one line the tree's orchestrator wrote for the next one with courier_note: when, and from which depth when it was
+ * not the top's own session (1 for a session the top started).
+ */
+export interface Lesson {
+    readonly text: string;
+    readonly at: number;
+    readonly depth?: number;
+}
+/**
+ * How often other trees' courier_recall calls listed the record (`shown`) or gave it in full (`read`), and when one last
+ * did (`at`). Kept per reader tree and summed when read; a listing to the tree's own sessions counts nothing.
+ */
+export interface Reads {
+    readonly shown: number;
+    readonly read: number;
+    readonly at: number;
+}
+/** What a courier_recall call did with a record: listed it, or gave it in full. */
+export type ReadKind = "shown" | "read";
+/** The person's pin, set in the memory view: when. A pinned record is listed first and never swept. */
+export interface Pinned {
+    readonly at: number;
+}
+/** How many revisions of the split line a record keeps, the newest. */
+export declare const MAX_REVISIONS = 3;
+/** A later split line the top stated, worded otherwise than the one before it: when, and how many parts the tree had then. */
+export interface Revision {
+    readonly text: string;
+    readonly at: number;
+    readonly parts: number;
+}
+/** What is remembered of one tree: its top session and each session started in it, never a report's body or artifacts. */
+export interface TreeRecord {
+    /** When the top session was created, epoch milliseconds. */
+    readonly startedAt: number;
+    /** When a turn in the tree last ended, or the record was first written. */
+    readonly movedAt: number;
+    readonly title: string;
+    /**
+     * The top's first split line, as `e2e/real-model-recursive.mjs` reads it, or `not stated`; a stated line takes precedence over a
+     * mention, which it replaces once, and is never replaced.
+     */
+    readonly split: string;
+    /** Absent until the top states a split line worded otherwise than `split`; newest last, at most `MAX_REVISIONS`. */
+    readonly revisions?: ReadonlyArray<Revision>;
+    /** Whether, at the last refresh, no session in the tree ran and every part had settled: none was out or stalled. */
+    readonly finished: boolean;
+    readonly recalled?: Recalled;
+    /** Absent until a session of the tree that is not a leaf wrote one; a second note replaces the first. */
+    readonly lesson?: Lesson;
+    /** Absent until another tree's courier_recall listed or read the record; kept beside the record, never written with it. */
+    readonly reads?: Reads;
+    /** Absent until the person pinned the record in the memory view; kept beside the record, never written with it. */
+    readonly pinned?: Pinned;
+    readonly parts: ReadonlyArray<PartRecord>;
+}
+/** A record with where it is kept: its project and its top session. */
+export interface StoredRecord extends TreeRecord {
+    readonly projectID: string;
+    readonly sessionID: string;
+}
+/** The `memory` option: whether records are kept and listed; on unless `false`. */
+export declare function readMemory(options: unknown): {
+    memory: boolean;
+    problems: string[];
+};
+/** 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 declare function splitLineOf(text: string): string | undefined;
+/** Whether a split line is stated, beginning with `split:` after any markdown, not a passing mention nor `not stated`. */
+export declare const isStated: (line: string) => boolean;
+/** 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 declare function splitOf(recorded: string, text: string): string;
+/** Every line of a text that begins with `split:` after any markdown, trimmed: a passing mention of a split is none. */
+export declare const splitLinesOf: (text: string) => string[];
+/** A split line the top's replies state, with when its reply was created when the message says. */
+export interface Stated {
+    readonly text: string;
+    readonly at?: number;
+}
+/**
+ * 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 declare function revise(previous: Pick<TreeRecord, "split" | "revisions">, stated: ReadonlyArray<Stated>, at: number, parts: number): Revision[] | 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 declare function replacingMention(found: string, revisions: ReadonlyArray<Revision> | undefined): Pick<TreeRecord, "split" | "revisions">;
+/** 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 declare function splitProse(split: string): string;
+/** What a part's status is read from: whether courier_stop stopped it, whether it is stalled, and its report state. */
+export interface Standing {
+    readonly stopped: boolean;
+    readonly stalled: boolean;
+    readonly report?: {
+        readonly known: boolean;
+        readonly owes: boolean;
+        readonly ended?: "failed" | "interrupted";
+        readonly status?: Status;
+    };
+}
+/** A part's status by `Standing`; one whose report state is not known is still out. */
+export declare function partStatus({ stopped, stalled, report }: Standing): PartStatus;
+/**
+ * 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 declare function unreadPart(read: PartRecord, last: PartRecord | undefined, gone: boolean): PartRecord;
+/**
+ * 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 declare function mergeParts(previous: ReadonlyArray<PartRecord>, current: ReadonlyArray<PartRecord>): PartRecord[];
+/** `recalled` after one more call at `at`, the top's first call noted when `byTop`. */
+export declare function noteRecall(recalled: Recalled | undefined, byTop: boolean, at: number): Recalled;
+/** A text as the one line a lesson is: whitespace and line breaks collapsed to spaces, trimmed. */
+export declare const oneLine: (text: string) => string;
+/**
+ * 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 declare function lessonText(text: string): {
+    text: string;
+    clipped?: undefined;
+} | {
+    text: string;
+    clipped: number;
+};
+/** One reader tree's `reads` after courier_recall listed the record or gave it in full at `at`. */
+export declare function noteRead(reads: Reads | undefined, kind: ReadKind, at: number): Reads;
+/** The reads of every reader tree as one: the counts summed, `at` the latest; none without a reader. */
+export declare function sumReads(reads: ReadonlyArray<Reads>): Reads | undefined;
+/**
+ * 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 declare function keep<T extends Pick<StoredRecord, "movedAt" | "lesson" | "pinned">>(records: ReadonlyArray<T>, now: number): {
+    kept: T[];
+    dropped: T[];
+};
+/** Records as courier_recall and the memory view list them: the pinned first, then by when each last moved, newest first. */
+export declare const pinnedFirst: <T extends Pick<StoredRecord, "movedAt" | "pinned">>(records: ReadonlyArray<T>) => T[];

package/dist/memory/domain.js

@@ -0,0 +1,209 @@
+/**
+ * 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);
+    if (!last)
+        return stated.slice(stated.findIndex((line) => words(line) === splitProse(previous.split)) + 1);
+    const inReply = stated.findLastIndex((line) => words(line) === splitProse(last.text) && line.at === last.at);
+    if (inReply >= 0)
+        return stated.slice(inReply + 1);
+    if (stated.some((line) => line.at !== undefined))
+        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) => {
+        const words = splitProse(line.text);
+        return words === last ? { last, added } : { last: words, added: [...added, { text: line.text, at: line.at ?? at, parts }] };
+    }, { last: recorded, added: [] });
+    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*/]/],
+    ["*", /[\p{L}\p{N}\0"']/u],
+];
+const WRAPS = [
+    ["__", /[^\s_]/],
+    ["_", /[^\s_]/],
+    ["`", /[^\s`]/],
+];
+const unwrapped = (line, marks) => {
+    const inner = (mark) => line.slice(mark.length, -mark.length);
+    const wraps = ([mark, opens]) => {
+        const words = inner(mark);
+        const apart = mark === "*" ? !words.includes("* ") && !words.includes(" *") : !words.includes(mark);
+        return line.length > 2 * mark.length && line.startsWith(mark) && line.endsWith(mark) && opens.test(words[0]) && !/[\s(/]/.test(words.at(-1)) && apart;
+    };
+    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", ""))
+        .replace(BLOCK_MARKS, "")
+        .replace(LABEL, "$2")
+        .replace(CODE_SPAN, (span) => `\0${code.push(span) - 1}\0`);
+    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";
+    if (stalled)
+        return "stalled";
+    if (!report?.known || report.owes)
+        return "out";
+    if (report.ended)
+        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 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

@@ -0,0 +1,26 @@
+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;
+    readonly data: {
+        readonly sessionID: string;
+        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

@@ -0,0 +1,46 @@
+import { claim } from "../platform/bounded.js";
+import { childrenOf, indexedLineage } from "../tree/index.js";
+import { refresh } from "./record.js";
+const TURN_ENDS = new Set(["session.execution.succeeded", "session.execution.failed", "session.execution.interrupted"]);
+/**
+ * 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)
+        return chain.at(-1).parentID;
+    if (state.tops.has(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) {
+    // A shutdown's interruption is resumed on the next start: nothing ended.
+    if (event.data.reason === "shutdown")
+        return undefined;
+    const top = await topOf(ports, state, event.data.sessionID);
+    // 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 (top === undefined || !claim(state.seen, event.id))
+        return undefined;
+    try {
+        await refresh(ports, state, top, event.created ?? ports.now(), event.data.sessionID);
+    }
+    catch (error) {
+        state.seen.delete(event.id);
+        throw error;
+    }
+    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 {
+        after: (ports, event) => TURN_ENDS.has(event.type)
+            ? noteTurnEnd(ports, state, event).then(() => undefined, (error) => ports.log(`courier memory: could not record the tree of ${event.data?.sessionID}: ${String(error)}`))
+            : undefined,
+    };
+}

package/dist/memory/forget.d.ts

@@ -0,0 +1,10 @@
+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

@@ -0,0 +1,20 @@
+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);
+    if (!record)
+        return "none";
+    if (!lesson) {
+        await store.remove(ports.projectID, sessionID);
+        return "record";
+    }
+    if (!record.lesson)
+        return "none";
+    const { lesson: _dropped, ...kept } = record;
+    await store.put(ports.projectID, sessionID, kept);
+    return "lesson";
+}

package/dist/memory/index.d.ts

@@ -0,0 +1,11 @@
+export { LESSON_MAX, MAX_RECORDS, NOT_STATED, readMemory, RETENTION_MS } from "./domain.js";
+export { memoryEvents, type MemoryEventPorts } from "./events.js";
+export { note, type Noted, type NoteInput } from "./note.js";
+export { pin, type PinOutcome } from "./pin.js";
+export type { Lesson, MemoryPorts, MemoryState, PartRecord, PartStatus, Pinned, Reads, Recalled, RefreshPorts, Revision, StoredRecord, TreeRecord } from "./ports.js";
+export { recall, type Recall, type RecallInput } from "./recall.js";
+export { refresh } from "./record.js";
+export { registerMemoryRpc, type MemoryRpcPorts } from "./rpc-handlers.js";
+export { sweepRecords } from "./sweep.js";
+export { NOTE_TOOL, RECALL_TOOL } from "./text.js";
+export { addMemoryTools, type MemoryToolPorts } from "./tools.js";

package/dist/memory/index.js

@@ -0,0 +1,12 @@
+// 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 { note } from "./note.js";
+export { pin } from "./pin.js";
+export { recall } from "./recall.js";
+export { refresh } from "./record.js";
+export { registerMemoryRpc } from "./rpc-handlers.js";
+export { sweepRecords } from "./sweep.js";
+export { NOTE_TOOL, RECALL_TOOL } from "./text.js";
+export { addMemoryTools } from "./tools.js";

package/dist/memory/note.d.ts

@@ -0,0 +1,37 @@
+import { type Lesson } from "./domain.js";
+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 depth: number;
+    readonly maxDepth: number;
+} | {
+    readonly kind: "empty";
+} | {
+    readonly kind: "long";
+    readonly length: number;
+} | {
+    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;
+    readonly top: string;
+    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

@@ -0,0 +1,29 @@
+import { lineage } from "../tree/index.js";
+import { LESSON_MAX, oneLine } from "./domain.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 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 } : {}) };
+    await store.put(projectID, top, { ...record, lesson });
+    return { kind: "noted", projectID, top, lesson, ...(record.lesson ? { replaced: record.lesson } : {}) };
+}

package/dist/memory/pin.d.ts

@@ -0,0 +1,8 @@
+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

@@ -0,0 +1,13 @@
+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);
+    if (!record)
+        return "none";
+    await store.pin(ports.projectID, sessionID, pinned ? (record.pinned ?? { at: ports.now() }) : undefined);
+    return pinned ? "pinned" : "unpinned";
+}