opencode-courier 0.7.3 → 0.8.0

package/dist/memory/domain.js

@@ -0,0 +1,84 @@
+/**
+ * The memory's pure rules, on plain data: the option, a record's shape, each part's status, the split line, 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 records a project keeps, the newest by `movedAt`. */
+export const MAX_RECORDS = 30;
+/** 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, `stalled` on a message it will not take, or `out`: it owes a report, running or not.
+ */
+export const PART_STATUSES = [...STATUSES, "interrupted", "stopped", "stalled", "out"];
+export const isPartStatus = (value) => typeof value === "string" && PART_STATUSES.includes(value);
+/** 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();
+}
+/** 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";
+}
+/**
+ * The parts of a refreshed record: those recorded before, in their order, each as read now when the roster still has it,
+ * 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 };
+}
+/** The records a project keeps at `now`: the newest `MAX_RECORDS` by `movedAt`, none older than `RETENTION_MS`; the rest are dropped. */
+export function keep(records, now) {
+    const newest = records.toSorted((a, b) => b.movedAt - a.movedAt);
+    const kept = newest.filter((record, index) => index < MAX_RECORDS && now - record.movedAt <= RETENTION_MS);
+    return { kept, dropped: newest.filter((record) => !kept.includes(record)) };
+}
+/** Records newest first, by when each last moved. */
+export const newestFirst = (records) => records.toSorted((a, b) => 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,10 @@
+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 type { Lesson, MemoryPorts, MemoryState, PartRecord, PartStatus, Recalled, RefreshPorts, StoredRecord, TreeRecord } from "./ports.js";
+export { recall, type Recall, type RecallInput } 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, type MemoryToolPorts } from "./tools.js";

package/dist/memory/index.js

@@ -0,0 +1,11 @@
+// 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 { 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/ports.d.ts

@@ -0,0 +1,44 @@
+/** 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 { ModelWindow } from "../tree/index.js";
+import type { StoredRecord, TreeRecord } from "./domain.js";
+export type { Lesson, PartRecord, PartStatus, Recalled, 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 now: () => number;
+    readonly log: (message: string) => void;
+}
+/** What courier_recall and courier_note run on: one instance's ports. */
+export interface MemoryPorts extends RefreshPorts {
+    /** 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. */
+export interface MemoryStore {
+    get(projectID: string, sessionID: string): Promise<TreeRecord | undefined>;
+    put(projectID: string, sessionID: string, record: TreeRecord): Promise<void>;
+    remove(projectID: string, sessionID: string): Promise<void>;
+    /** A project's records, in key order. */
+    ofProject(projectID: string): Promise<StoredRecord[]>;
+    /** Every project's records. */
+    all(): Promise<StoredRecord[]>;
+}

package/dist/memory/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/memory/recall.d.ts

@@ -0,0 +1,27 @@
+import { type StoredRecord } from "./domain.js";
+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";
+} | {
+    readonly kind: "list";
+    readonly projectID: string;
+    readonly top: string;
+    readonly records: ReadonlyArray<StoredRecord>;
+} | {
+    readonly kind: "record";
+    readonly projectID: string;
+    readonly record: StoredRecord;
+} | {
+    readonly kind: "missing";
+    readonly projectID: string;
+    readonly sessionID: string;
+};
+/**
+ * courier_recall: notes the call on the caller's tree, then lists the project's records newest first, or gives the one
+ * under `sessionID` in full. 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

@@ -0,0 +1,48 @@
+import { addBounded, SEEN_MAX } from "../platform/bounded.js";
+import { finite, millis } from "../platform/json.js";
+import { lineage } from "../tree/index.js";
+import { newestFirst, NOT_STATED, noteRecall } 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();
+    const previous = await store.get(ports.projectID, top);
+    const recalled = noteRecall(previous?.recalled, byTop, now);
+    if (previous)
+        return store.put(ports.projectID, top, { ...previous, recalled });
+    const info = await ports.session.get({ sessionID: top }).catch(() => undefined);
+    await store.put(ports.projectID, top, {
+        startedAt: finite(millis(info?.time.created)) ?? now,
+        movedAt: now,
+        title: info?.title ?? "",
+        split: NOT_STATED,
+        finished: false,
+        recalled,
+        parts: [],
+    });
+}
+/**
+ * courier_recall: notes the call on the caller's tree, then lists the project's records newest first, or gives the one
+ * under `sessionID` in full. With the memory option off, nothing is written or read.
+ */
+export async function recall(ports, state, callerID, input) {
+    if (!ports.memory)
+        return { kind: "off" };
+    const top = await topOfCaller(ports, callerID);
+    await note(ports, top, top === callerID);
+    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);
+        return record ? { kind: "record", projectID, record: { ...record, projectID, sessionID: wanted } } : { kind: "missing", projectID, sessionID: wanted };
+    }
+    return { kind: "list", projectID, top, records: newestFirst(await store.ofProject(projectID)) };
+}

package/dist/memory/record.d.ts

@@ -0,0 +1,7 @@
+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. Nothing for a top unknown to OpenCode or in a location with memory off; returns the record.
+ */
+export declare function refresh(ports: RefreshPorts, state: Pick<MemoryState, "windows" | "off">, top: string, at: number, ended?: string): Promise<TreeRecord | undefined>;

package/dist/memory/record.js

@@ -0,0 +1,92 @@
+import { finite, isNotFound, millis } from "../platform/json.js";
+import { busy, contextOf, reportState, stalledAmong, subtree } from "../tree/index.js";
+import { mergeParts, NOT_STATED, partStatus, splitLineOf } from "./domain.js";
+import { memoryStore } from "./store.js";
+/** The text of a session's replies, in order, for its split line. */
+const repliesOf = (messages) => messages
+    .flatMap((message) => (message.type === "assistant" ? message.content.flatMap((part) => (part.type === "text" ? [part.text] : [])) : []))
+    .join("\n");
+/** How many courier_spawn calls of a session failed, refused by a limit mostly. */
+const refusedIn = (messages) => messages.reduce((n, message) => (message.type === "assistant" ? n + message.content.filter((part) => part.type === "tool" && part.name === "courier_spawn" && part.state.status === "error").length : n), 0);
+/** A part's context use and refused spawns, as its messages show them. */
+function useOf(messages, windows) {
+    const context = contextOf(messages, windows);
+    const refused = refusedIn(messages);
+    return { ...(context !== undefined ? { context: Math.round(context * 100) / 100 } : {}), ...(refused ? { refused } : {}) };
+}
+/** A part's use as last recorded. */
+const keptUse = (last) => ({
+    ...(last?.context !== undefined ? { context: last.context } : {}),
+    ...(last?.refused ? { refused: last.refused } : {}),
+});
+/**
+ * One session of the tree as its record keeps it, without its use when its messages were not read (only when its turn
+ * `ended` or it is `known` to no record yet), and whether it runs now.
+ */
+async function part(ports, windows, { entry, depth }, stalled, at, known, ended) {
+    const { sessionID } = entry;
+    const [info, use, report] = await Promise.all([
+        ports.session.get({ sessionID }).catch(() => undefined),
+        ended || !known ? ports.session.context({ sessionID }).then((messages) => useOf(messages, windows), () => undefined) : undefined,
+        reportState(ports.storage, sessionID).catch(() => undefined),
+    ]);
+    const running = info !== undefined && busy(info.time);
+    const created = finite(millis(info?.time.created)) ?? entry.createdAt;
+    const end = info && !running && info.time.idle !== undefined ? millis(info.time.idle) : at;
+    const cost = finite(info?.cost);
+    const record = {
+        sessionID,
+        title: info?.title ?? entry.title,
+        depth,
+        isolated: entry.isolated,
+        ...(entry.group ? { group: entry.group } : {}),
+        status: partStatus({ stopped: report?.stopped ?? false, stalled, report }),
+        duration: Math.max(0, end - created),
+        ...(cost !== undefined ? { cost } : {}),
+    };
+    return { record, use, running };
+}
+/**
+ * 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. Nothing for a top unknown to OpenCode or in a location with memory off; returns the record.
+ */
+export async function refresh(ports, state, top, at, ended) {
+    let info;
+    try {
+        info = await ports.session.get({ sessionID: top });
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        throw error;
+    }
+    if (state.off.has(info.location.directory))
+        return undefined;
+    const store = memoryStore(ports.storage);
+    const [previous, { nodes }] = await Promise.all([store.get(info.projectID, top), subtree(ports.storage, top)]);
+    // The split line is in the top's own replies, so only its own turn end can change one stated already.
+    const replies = ended === top || (previous?.split ?? NOT_STATED) === NOT_STATED ? ports.session.context({ sessionID: top }).then(repliesOf, () => "") : "";
+    const stalled = await stalledAmong(ports, nodes.map((node) => node.entry.sessionID));
+    const windows = [...state.windows.values()];
+    const known = new Set(previous?.parts.map((one) => one.sessionID));
+    const read = await Promise.all(nodes.map((node) => part(ports, windows, node, stalled.has(node.entry.sessionID), at, known.has(node.entry.sessionID), node.entry.sessionID === ended)));
+    const split = splitLineOf(await replies);
+    // Read again just before the write: a courier_recall or courier_note call, or another turn end's refresh, wrote meanwhile.
+    const latest = (await store.get(info.projectID, top).catch(() => previous)) ?? previous;
+    const last = new Map(latest?.parts.map((one) => [one.sessionID, one]));
+    const parts = mergeParts(latest?.parts ?? [], read.map(({ record, use }) => ({ ...record, ...(use ?? keptUse(last.get(record.sessionID))) })));
+    const recalled = latest?.recalled ?? previous?.recalled;
+    const lesson = latest?.lesson ?? previous?.lesson;
+    const record = {
+        startedAt: finite(millis(info.time.created)) ?? previous?.startedAt ?? at,
+        movedAt: at,
+        title: info.title ?? previous?.title ?? "",
+        split: split ?? latest?.split ?? NOT_STATED,
+        finished: !busy(info.time) && !read.some(({ running }) => running) && parts.every((one) => one.status !== "out" && one.status !== "stalled"),
+        ...(recalled ? { recalled } : {}),
+        ...(lesson ? { lesson } : {}),
+        parts,
+    };
+    await store.put(info.projectID, top, record);
+    return record;
+}

package/dist/memory/rpc-handlers.d.ts

@@ -0,0 +1,134 @@
+import type { Plugin } from "@opencode/plugin";
+import type { MemoryPorts } from "./ports.js";
+import { type Records } from "./rpc.js";
+/**
+ * The records of the ports' project, newest first, as the memory view lists them; nothing, and `memory` false, with the
+ * option off. Read from the store alone: unlike courier_recall, a look from the terminal is noted on no record.
+ */
+export declare function records(ports: Pick<MemoryPorts, "storage" | "projectID" | "memory">): Promise<Records>;
+/** Serves the memory's RPC at the plugin's location, after the tree's and the person's; disposed with the plugin. */
+export declare function registerMemoryRpc(rpc: Pick<Plugin.Context["rpc"], "register">, ports: Pick<MemoryPorts, "storage" | "projectID" | "memory">): Promise<import("@opencode/plugin/promise/rpc").RpcRegistration<{
+    readonly id: "courier-memory";
+    readonly methods: {
+        readonly records: {
+            readonly input: import("effect/StandardSchema").StandardSchemaV1<{}, {}> & import("effect/Schema").Struct<{}>;
+            readonly output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly memory: boolean;
+                readonly projectID: string;
+                readonly records: readonly {
+                    readonly sessionID: string;
+                    readonly split: string;
+                    readonly title: string;
+                    readonly movedAt: number;
+                    readonly startedAt: number;
+                    readonly finished: boolean;
+                    readonly parts: readonly {
+                        readonly sessionID: string;
+                        readonly status: "done" | "partial" | "blocked" | "failed" | "interrupted" | "out" | "stopped" | "stalled";
+                        readonly title: string;
+                        readonly isolated: boolean;
+                        readonly depth: number;
+                        readonly context?: number | undefined;
+                        readonly group?: string | undefined;
+                        readonly cost?: number | undefined;
+                        readonly refused?: number | undefined;
+                        readonly duration?: number | undefined;
+                    }[];
+                    readonly recalled?: {
+                        readonly calls: number;
+                        readonly at?: number | undefined;
+                    } | undefined;
+                    readonly lesson?: {
+                        readonly at: number;
+                        readonly text: string;
+                        readonly depth?: number | undefined;
+                    } | undefined;
+                }[];
+            }, {
+                readonly memory: boolean;
+                readonly projectID: string;
+                readonly records: readonly {
+                    readonly sessionID: string;
+                    readonly split: string;
+                    readonly title: string;
+                    readonly movedAt: number;
+                    readonly startedAt: number;
+                    readonly finished: boolean;
+                    readonly parts: readonly {
+                        readonly sessionID: string;
+                        readonly status: "done" | "partial" | "blocked" | "failed" | "interrupted" | "out" | "stopped" | "stalled";
+                        readonly title: string;
+                        readonly isolated: boolean;
+                        readonly depth: number;
+                        readonly context?: number | undefined;
+                        readonly group?: string | undefined;
+                        readonly cost?: number | undefined;
+                        readonly refused?: number | undefined;
+                        readonly duration?: number | undefined;
+                    }[];
+                    readonly recalled?: {
+                        readonly calls: number;
+                        readonly at?: number | undefined;
+                    } | undefined;
+                    readonly lesson?: {
+                        readonly at: number;
+                        readonly text: string;
+                        readonly depth?: number | undefined;
+                    } | undefined;
+                }[];
+            }> & import("effect/Schema").Struct<{
+                readonly memory: import("effect/Schema").Boolean;
+                readonly projectID: import("effect/Schema").String;
+                readonly records: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+                    readonly sessionID: import("effect/Schema").String;
+                    readonly startedAt: import("effect/Schema").Number;
+                    readonly movedAt: import("effect/Schema").Number;
+                    readonly title: import("effect/Schema").String;
+                    readonly split: import("effect/Schema").String;
+                    readonly finished: import("effect/Schema").Boolean;
+                    readonly recalled: import("effect/Schema").optionalKey<import("effect/Schema").Struct<{
+                        readonly at: import("effect/Schema").optionalKey<import("effect/Schema").Number>;
+                        readonly calls: import("effect/Schema").Int;
+                    }>>;
+                    readonly lesson: import("effect/Schema").optionalKey<import("effect/Schema").Struct<{
+                        readonly text: import("effect/Schema").String;
+                        readonly at: import("effect/Schema").Number;
+                        readonly depth: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
+                    }>>;
+                    readonly parts: import("effect/Schema").$Array<import("effect/Schema").Struct<{
+                        readonly sessionID: import("effect/Schema").String;
+                        readonly title: import("effect/Schema").String;
+                        readonly depth: import("effect/Schema").Int;
+                        readonly isolated: import("effect/Schema").Boolean;
+                        readonly group: import("effect/Schema").optionalKey<import("effect/Schema").String>;
+                        readonly status: import("effect/Schema").Literals<readonly ["done", "partial", "blocked", "failed", "interrupted", "stopped", "stalled", "out"]>;
+                        readonly duration: import("effect/Schema").optionalKey<import("effect/Schema").Number>;
+                        readonly cost: import("effect/Schema").optionalKey<import("effect/Schema").Number>;
+                        readonly context: import("effect/Schema").optionalKey<import("effect/Schema").Number>;
+                        readonly refused: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
+                    }>>;
+                }>>;
+            }>;
+        };
+        readonly forget: {
+            readonly input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly sessionID: string;
+                readonly lesson?: boolean | undefined;
+            }, {
+                readonly sessionID: string;
+                readonly lesson?: boolean | undefined;
+            }> & import("effect/Schema").Struct<{
+                readonly sessionID: import("effect/Schema").String;
+                readonly lesson: import("effect/Schema").optionalKey<import("effect/Schema").Boolean>;
+            }>;
+            readonly output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly outcome: "record" | "lesson" | "none";
+            }, {
+                readonly outcome: "record" | "lesson" | "none";
+            }> & import("effect/Schema").Struct<{
+                readonly outcome: import("effect/Schema").Literals<readonly ["record", "lesson", "none"]>;
+            }>;
+        };
+    };
+    readonly events: {};
+}>>;