opencode-courier 0.8.0 → 0.9.0

package/dist/memory/record.js

@@ -1,11 +1,13 @@
 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 { isSettled, isStated, mergeParts, NOT_STATED, partStatus, replacingMention, revise, splitLinesOf, splitOf, unreadPart } 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");
+/** A session's replies, in order, each with when it was created, for its split lines; only the `finished` ones when asked. */
+const repliesOf = (messages, finished) => messages.flatMap((message) => message.type === "assistant" && (!finished || message.time?.completed !== undefined)
+    ? [{ text: message.content.flatMap((part) => (part.type === "text" ? [part.text] : [])).join("\n"), at: finite(millis(message.time?.created)) }]
+    : []);
+/** The lines in the replies that begin with `split:`, each with its reply's time. */
+const statedIn = (replies) => replies.flatMap(({ text, at }) => splitLinesOf(text).map((line) => (at === undefined ? { text: line } : { text: line, at })));
 /** 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. */
@@ -19,14 +21,16 @@ const keptUse = (last) => ({
     ...(last?.context !== undefined ? { context: last.context } : {}),
     ...(last?.refused ? { refused: last.refused } : {}),
 });
+/** A session's info, or `gone` when OpenCode no longer knows it; neither when it could not be read for another reason. */
+const infoOf = (ports, sessionID) => ports.session.get({ sessionID }).then((info) => ({ info, gone: false }), (error) => ({ gone: isNotFound(error) }));
 /**
  * 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.
+ * `ended` or it is `known` to no record yet), without a duration when its info was not, 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),
+    const [{ info, gone }, use, report] = await Promise.all([
+        infoOf(ports, sessionID),
         ended || !known ? ports.session.context({ sessionID }).then((messages) => useOf(messages, windows), () => undefined) : undefined,
         reportState(ports.storage, sessionID).catch(() => undefined),
     ]);
@@ -41,14 +45,20 @@ async function part(ports, windows, { entry, depth }, stalled, at, known, ended)
         isolated: entry.isolated,
         ...(entry.group ? { group: entry.group } : {}),
         status: partStatus({ stopped: report?.stopped ?? false, stalled, report }),
-        duration: Math.max(0, end - created),
+        ...(info ? { duration: Math.max(0, end - created) } : {}),
         ...(cost !== undefined ? { cost } : {}),
     };
-    return { record, use, running };
+    return { record, use, running, unread: info === undefined, gone };
+}
+/** Of the parts last recorded, those the roster has forgotten before they settled whose session OpenCode no longer knows. */
+async function goneSince(ports, parts, onRoster) {
+    const unsettled = parts.filter((one) => !onRoster.has(one.sessionID) && !isSettled(one.status));
+    const looked = await Promise.all(unsettled.map(async ({ sessionID }) => ({ sessionID, ...(await infoOf(ports, sessionID)) })));
+    return new Set(looked.flatMap((one) => (one.gone ? [one.sessionID] : [])));
 }
 /**
  * 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.
+ * keeps its last recorded state, unless found gone before it settled. Nothing for a top unknown to OpenCode or with memory off.
  */
 export async function refresh(ports, state, top, at, ended) {
     let info;
@@ -64,25 +74,47 @@ export async function refresh(ports, state, top, at, ended) {
         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, () => "") : "";
+    // The split lines are in the top's own replies, so only its own turn end can revise one stated already; another's reads
+    // them while none is stated, and only the replies finished, never a line the top is still writing.
+    const own = ended === top;
+    const replies = own || !isStated(previous?.split ?? NOT_STATED)
+        ? ports.session.context({ sessionID: top }).then((messages) => repliesOf(messages, !own), () => [])
+        : [];
     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);
+    const [read, lost] = await Promise.all([
+        Promise.all(nodes.map((node) => part(ports, windows, node, stalled.has(node.entry.sessionID), at, known.has(node.entry.sessionID), node.entry.sessionID === ended))),
+        goneSince(ports, previous?.parts ?? [], new Set(nodes.map((node) => node.entry.sessionID))),
+    ]);
+    const said = 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 current = read.map(({ record, use, unread, gone }) => {
+        const before = last.get(record.sessionID);
+        return { ...(unread ? unreadPart(record, before, gone) : record), ...(use ?? keptUse(before)) };
+    });
+    const forgotten = (latest?.parts ?? []).filter((one) => lost.has(one.sessionID)).map((one) => unreadPart(one, one, true));
+    const parts = mergeParts(latest?.parts ?? [], [...current, ...forgotten]);
     const recalled = latest?.recalled ?? previous?.recalled;
     const lesson = latest?.lesson ?? previous?.lesson;
+    // The first stated line stays even when compaction has dropped its reply; a later one is a revision.
+    const first = latest?.split ?? NOT_STATED;
+    const found = splitOf(first, said.map((reply) => reply.text).join("\n"));
+    const stated = statedIn(said);
+    const replaced = found !== first;
+    const { split, revisions: recorded } = replaced ? replacingMention(found, latest?.revisions) : { split: first, revisions: latest?.revisions };
+    // The line that replaced a mention is the first stated, so beside revisions already recorded it is not one of them too.
+    const since = replaced && recorded ? stated.slice(1) : stated;
+    const revisions = split === NOT_STATED ? undefined : revise({ split, revisions: recorded }, since, at, parts.length);
     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"),
+        split,
+        ...(revisions ? { revisions } : {}),
+        finished: !busy(info.time) && !read.some(({ running }) => running) && parts.every((one) => isSettled(one.status)),
         ...(recalled ? { recalled } : {}),
         ...(lesson ? { lesson } : {}),
         parts,

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

@@ -1,13 +1,15 @@
 import type { Plugin } from "@opencode/plugin";
 import type { MemoryPorts } from "./ports.js";
 import { type Records } from "./rpc.js";
+/** What the memory's RPC runs on: one instance's ports. */
+export type MemoryRpcPorts = Pick<MemoryPorts, "storage" | "projectID" | "memory" | "now">;
 /**
- * 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.
+ * The records of the ports' project, pinned first and then 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>;
+export declare function records(ports: Pick<MemoryRpcPorts, "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<{
+export declare function registerMemoryRpc(rpc: Pick<Plugin.Context["rpc"], "register">, ports: MemoryRpcPorts): Promise<import("@opencode/plugin/promise/rpc").RpcRegistration<{
     readonly id: "courier-memory";
     readonly methods: {
         readonly records: {
@@ -19,12 +21,12 @@ export declare function registerMemoryRpc(rpc: Pick<Plugin.Context["rpc"], "regi
                     readonly sessionID: string;
                     readonly split: string;
                     readonly title: string;
-                    readonly movedAt: number;
                     readonly startedAt: number;
+                    readonly movedAt: number;
                     readonly finished: boolean;
                     readonly parts: readonly {
                         readonly sessionID: string;
-                        readonly status: "done" | "partial" | "blocked" | "failed" | "interrupted" | "out" | "stopped" | "stalled";
+                        readonly status: "done" | "partial" | "blocked" | "failed" | "interrupted" | "out" | "stopped" | "gone" | "stalled";
                         readonly title: string;
                         readonly isolated: boolean;
                         readonly depth: number;
@@ -43,6 +45,14 @@ export declare function registerMemoryRpc(rpc: Pick<Plugin.Context["rpc"], "regi
                         readonly text: string;
                         readonly depth?: number | undefined;
                     } | undefined;
+                    readonly reads?: {
+                        readonly shown: number;
+                        readonly read: number;
+                        readonly at: number;
+                    } | undefined;
+                    readonly pinned?: {
+                        readonly at: number;
+                    } | undefined;
                 }[];
             }, {
                 readonly memory: boolean;
@@ -51,12 +61,12 @@ export declare function registerMemoryRpc(rpc: Pick<Plugin.Context["rpc"], "regi
                     readonly sessionID: string;
                     readonly split: string;
                     readonly title: string;
-                    readonly movedAt: number;
                     readonly startedAt: number;
+                    readonly movedAt: number;
                     readonly finished: boolean;
                     readonly parts: readonly {
                         readonly sessionID: string;
-                        readonly status: "done" | "partial" | "blocked" | "failed" | "interrupted" | "out" | "stopped" | "stalled";
+                        readonly status: "done" | "partial" | "blocked" | "failed" | "interrupted" | "out" | "stopped" | "gone" | "stalled";
                         readonly title: string;
                         readonly isolated: boolean;
                         readonly depth: number;
@@ -75,6 +85,14 @@ export declare function registerMemoryRpc(rpc: Pick<Plugin.Context["rpc"], "regi
                         readonly text: string;
                         readonly depth?: number | undefined;
                     } | undefined;
+                    readonly reads?: {
+                        readonly shown: number;
+                        readonly read: number;
+                        readonly at: number;
+                    } | undefined;
+                    readonly pinned?: {
+                        readonly at: number;
+                    } | undefined;
                 }[];
             }> & import("effect/Schema").Struct<{
                 readonly memory: import("effect/Schema").Boolean;
@@ -95,13 +113,21 @@ export declare function registerMemoryRpc(rpc: Pick<Plugin.Context["rpc"], "regi
                         readonly at: import("effect/Schema").Number;
                         readonly depth: import("effect/Schema").optionalKey<import("effect/Schema").Int>;
                     }>>;
+                    readonly reads: import("effect/Schema").optionalKey<import("effect/Schema").Struct<{
+                        readonly shown: import("effect/Schema").Int;
+                        readonly read: import("effect/Schema").Int;
+                        readonly at: import("effect/Schema").Number;
+                    }>>;
+                    readonly pinned: import("effect/Schema").optionalKey<import("effect/Schema").Struct<{
+                        readonly at: import("effect/Schema").Number;
+                    }>>;
                     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 status: import("effect/Schema").Literals<readonly ["done", "partial", "blocked", "failed", "interrupted", "stopped", "gone", "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>;
@@ -129,6 +155,25 @@ export declare function registerMemoryRpc(rpc: Pick<Plugin.Context["rpc"], "regi
                 readonly outcome: import("effect/Schema").Literals<readonly ["record", "lesson", "none"]>;
             }>;
         };
+        readonly pin: {
+            readonly input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly sessionID: string;
+                readonly pinned: boolean;
+            }, {
+                readonly sessionID: string;
+                readonly pinned: boolean;
+            }> & import("effect/Schema").Struct<{
+                readonly sessionID: import("effect/Schema").String;
+                readonly pinned: import("effect/Schema").Boolean;
+            }>;
+            readonly output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly outcome: "pinned" | "unpinned" | "none";
+            }, {
+                readonly outcome: "pinned" | "unpinned" | "none";
+            }> & import("effect/Schema").Struct<{
+                readonly outcome: import("effect/Schema").Literals<readonly ["pinned", "unpinned", "none"]>;
+            }>;
+        };
     };
     readonly events: {};
 }>>;

package/dist/memory/rpc-handlers.js

@@ -1,23 +1,25 @@
-import { newestFirst } from "./domain.js";
+import { pinnedFirst } from "./domain.js";
 import { forget } from "./forget.js";
+import { pin } from "./pin.js";
 import { memoryRpc } from "./rpc.js";
 import { memoryStore } from "./store.js";
-/** A stored record as the RPC gives it: without its project, which the listing names once. */
-const toRecord = ({ projectID: _project, ...record }) => record;
+/** A stored record as the RPC gives it: without its project, which the listing names once, nor the split line's revisions, which its schema lacks. */
+const toRecord = ({ projectID: _project, revisions: _revisions, ...record }) => record;
 /**
- * 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.
+ * The records of the ports' project, pinned first and then 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 async function records(ports) {
     const { projectID } = ports;
     if (!ports.memory)
         return { memory: false, projectID, records: [] };
-    return { memory: true, projectID, records: newestFirst(await memoryStore(ports.storage).ofProject(projectID)).map(toRecord) };
+    return { memory: true, projectID, records: pinnedFirst(await memoryStore(ports.storage).ofProject(projectID)).map(toRecord) };
 }
 /** Serves the memory's RPC at the plugin's location, after the tree's and the person's; disposed with the plugin. */
 export function registerMemoryRpc(rpc, ports) {
     return rpc.register(memoryRpc, {
         records: () => records(ports),
         forget: async ({ sessionID, lesson }) => ({ outcome: await forget(ports, sessionID, { lesson: lesson === true }) }),
+        pin: async ({ sessionID, pinned }) => ({ outcome: await pin(ports, sessionID, pinned) }),
     });
 }

package/dist/memory/rpc.d.ts

@@ -1,6 +1,6 @@
 import { Schema } from "effect";
 /** A part's statuses, as `memory/domain.ts`'s `PART_STATUSES` has them; a unit test keeps the two equal. */
-export declare const PART_STATUSES: readonly ["done", "partial", "blocked", "failed", "interrupted", "stopped", "stalled", "out"];
+export declare const PART_STATUSES: readonly ["done", "partial", "blocked", "failed", "interrupted", "stopped", "gone", "stalled", "out"];
 /** One session started in a tree, as its record keeps it: durations in milliseconds, context use a share of the model's window. */
 declare const Part: Schema.Struct<{
     readonly sessionID: Schema.String;
@@ -9,7 +9,7 @@ declare const Part: Schema.Struct<{
     readonly depth: Schema.Int;
     readonly isolated: Schema.Boolean;
     readonly group: Schema.optionalKey<Schema.String>;
-    readonly status: Schema.Literals<readonly ["done", "partial", "blocked", "failed", "interrupted", "stopped", "stalled", "out"]>;
+    readonly status: Schema.Literals<readonly ["done", "partial", "blocked", "failed", "interrupted", "stopped", "gone", "stalled", "out"]>;
     readonly duration: Schema.optionalKey<Schema.Number>;
     readonly cost: Schema.optionalKey<Schema.Number>;
     readonly context: Schema.optionalKey<Schema.Number>;
@@ -38,6 +38,16 @@ declare const Record: Schema.Struct<{
         readonly at: Schema.Number;
         readonly depth: Schema.optionalKey<Schema.Int>;
     }>>;
+    /** How often other trees' courier_recall calls listed the record and gave it in full, and when one last did. */
+    readonly reads: Schema.optionalKey<Schema.Struct<{
+        readonly shown: Schema.Int;
+        readonly read: Schema.Int;
+        readonly at: Schema.Number;
+    }>>;
+    /** The person's pin, when; a pinned record is listed first and never swept. */
+    readonly pinned: Schema.optionalKey<Schema.Struct<{
+        readonly at: Schema.Number;
+    }>>;
     readonly parts: Schema.$Array<Schema.Struct<{
         readonly sessionID: Schema.String;
         readonly title: Schema.String;
@@ -45,14 +55,14 @@ declare const Record: Schema.Struct<{
         readonly depth: Schema.Int;
         readonly isolated: Schema.Boolean;
         readonly group: Schema.optionalKey<Schema.String>;
-        readonly status: Schema.Literals<readonly ["done", "partial", "blocked", "failed", "interrupted", "stopped", "stalled", "out"]>;
+        readonly status: Schema.Literals<readonly ["done", "partial", "blocked", "failed", "interrupted", "stopped", "gone", "stalled", "out"]>;
         readonly duration: Schema.optionalKey<Schema.Number>;
         readonly cost: Schema.optionalKey<Schema.Number>;
         readonly context: Schema.optionalKey<Schema.Number>;
         readonly refused: Schema.optionalKey<Schema.Int>;
     }>>;
 }>;
-/** The records of the project of the location asked, newest first; none, and `memory` false, when the option is off there. */
+/** The records of the project of the location asked, pinned first and then newest first; none, and `memory` false, when the option is off there. */
 declare const Records: Schema.Struct<{
     readonly memory: Schema.Boolean;
     readonly projectID: Schema.String;
@@ -72,6 +82,16 @@ declare const Records: Schema.Struct<{
             readonly at: Schema.Number;
             readonly depth: Schema.optionalKey<Schema.Int>;
         }>>;
+        /** How often other trees' courier_recall calls listed the record and gave it in full, and when one last did. */
+        readonly reads: Schema.optionalKey<Schema.Struct<{
+            readonly shown: Schema.Int;
+            readonly read: Schema.Int;
+            readonly at: Schema.Number;
+        }>>;
+        /** The person's pin, when; a pinned record is listed first and never swept. */
+        readonly pinned: Schema.optionalKey<Schema.Struct<{
+            readonly at: Schema.Number;
+        }>>;
         readonly parts: Schema.$Array<Schema.Struct<{
             readonly sessionID: Schema.String;
             readonly title: Schema.String;
@@ -79,7 +99,7 @@ declare const Records: Schema.Struct<{
             readonly depth: Schema.Int;
             readonly isolated: Schema.Boolean;
             readonly group: Schema.optionalKey<Schema.String>;
-            readonly status: Schema.Literals<readonly ["done", "partial", "blocked", "failed", "interrupted", "stopped", "stalled", "out"]>;
+            readonly status: Schema.Literals<readonly ["done", "partial", "blocked", "failed", "interrupted", "stopped", "gone", "stalled", "out"]>;
             readonly duration: Schema.optionalKey<Schema.Number>;
             readonly cost: Schema.optionalKey<Schema.Number>;
             readonly context: Schema.optionalKey<Schema.Number>;
@@ -91,11 +111,17 @@ declare const Records: Schema.Struct<{
 declare const Forgotten: Schema.Struct<{
     readonly outcome: Schema.Literals<readonly ["record", "lesson", "none"]>;
 }>;
+/** What a pin did: pinned the record, unpinned it, or found no record to pin. */
+declare const Pinned: Schema.Struct<{
+    readonly outcome: Schema.Literals<readonly ["pinned", "unpinned", "none"]>;
+}>;
 export type MemoryRecord = typeof Record.Type;
 export type MemoryPart = typeof Part.Type;
 export type MemoryLesson = typeof Lesson.Type;
+export type MemoryReads = NonNullable<MemoryRecord["reads"]>;
 export type Records = typeof Records.Type;
 export type Forgotten = typeof Forgotten.Type;
+export type Pinned = typeof Pinned.Type;
 export declare const memoryRpc: {
     readonly id: "courier-memory";
     readonly methods: {
@@ -108,7 +134,7 @@ export declare const memoryRpc: {
                     readonly sessionID: string;
                     readonly title: string;
                     readonly parts: readonly {
-                        readonly status: "done" | "partial" | "blocked" | "failed" | "interrupted" | "stopped" | "stalled" | "out";
+                        readonly status: "done" | "partial" | "blocked" | "failed" | "interrupted" | "stopped" | "gone" | "stalled" | "out";
                         readonly sessionID: string;
                         readonly title: string;
                         readonly depth: number;
@@ -132,6 +158,14 @@ export declare const memoryRpc: {
                         readonly at: number;
                         readonly depth?: number | undefined;
                     } | undefined;
+                    readonly reads?: {
+                        readonly shown: number;
+                        readonly read: number;
+                        readonly at: number;
+                    } | undefined;
+                    readonly pinned?: {
+                        readonly at: number;
+                    } | undefined;
                 }[];
             }, {
                 readonly memory: boolean;
@@ -140,7 +174,7 @@ export declare const memoryRpc: {
                     readonly sessionID: string;
                     readonly title: string;
                     readonly parts: readonly {
-                        readonly status: "done" | "partial" | "blocked" | "failed" | "interrupted" | "stopped" | "stalled" | "out";
+                        readonly status: "done" | "partial" | "blocked" | "failed" | "interrupted" | "stopped" | "gone" | "stalled" | "out";
                         readonly sessionID: string;
                         readonly title: string;
                         readonly depth: number;
@@ -164,6 +198,14 @@ export declare const memoryRpc: {
                         readonly at: number;
                         readonly depth?: number | undefined;
                     } | undefined;
+                    readonly reads?: {
+                        readonly shown: number;
+                        readonly read: number;
+                        readonly at: number;
+                    } | undefined;
+                    readonly pinned?: {
+                        readonly at: number;
+                    } | undefined;
                 }[];
             }> & Schema.Struct<{
                 readonly memory: Schema.Boolean;
@@ -184,6 +226,16 @@ export declare const memoryRpc: {
                         readonly at: Schema.Number;
                         readonly depth: Schema.optionalKey<Schema.Int>;
                     }>>;
+                    /** How often other trees' courier_recall calls listed the record and gave it in full, and when one last did. */
+                    readonly reads: Schema.optionalKey<Schema.Struct<{
+                        readonly shown: Schema.Int;
+                        readonly read: Schema.Int;
+                        readonly at: Schema.Number;
+                    }>>;
+                    /** The person's pin, when; a pinned record is listed first and never swept. */
+                    readonly pinned: Schema.optionalKey<Schema.Struct<{
+                        readonly at: Schema.Number;
+                    }>>;
                     readonly parts: Schema.$Array<Schema.Struct<{
                         readonly sessionID: Schema.String;
                         readonly title: Schema.String;
@@ -191,7 +243,7 @@ export declare const memoryRpc: {
                         readonly depth: Schema.Int;
                         readonly isolated: Schema.Boolean;
                         readonly group: Schema.optionalKey<Schema.String>;
-                        readonly status: Schema.Literals<readonly ["done", "partial", "blocked", "failed", "interrupted", "stopped", "stalled", "out"]>;
+                        readonly status: Schema.Literals<readonly ["done", "partial", "blocked", "failed", "interrupted", "stopped", "gone", "stalled", "out"]>;
                         readonly duration: Schema.optionalKey<Schema.Number>;
                         readonly cost: Schema.optionalKey<Schema.Number>;
                         readonly context: Schema.optionalKey<Schema.Number>;
@@ -220,6 +272,26 @@ export declare const memoryRpc: {
                 readonly outcome: Schema.Literals<readonly ["record", "lesson", "none"]>;
             }>;
         };
+        /** Pins the record of the tree under `sessionID` in the project asked, or with `pinned` false unpins it. */
+        readonly pin: {
+            readonly input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly sessionID: string;
+                readonly pinned: boolean;
+            }, {
+                readonly sessionID: string;
+                readonly pinned: boolean;
+            }> & Schema.Struct<{
+                readonly sessionID: Schema.String;
+                readonly pinned: Schema.Boolean;
+            }>;
+            readonly output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly outcome: "pinned" | "none" | "unpinned";
+            }, {
+                readonly outcome: "pinned" | "none" | "unpinned";
+            }> & Schema.Struct<{
+                readonly outcome: Schema.Literals<readonly ["pinned", "unpinned", "none"]>;
+            }>;
+        };
     };
     readonly events: {};
 };

package/dist/memory/rpc.js

@@ -6,7 +6,7 @@ import { Rpc } from "@opencode/plugin/rpc";
 import { Schema } from "effect";
 const Count = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
 /** A part's statuses, as `memory/domain.ts`'s `PART_STATUSES` has them; a unit test keeps the two equal. */
-export const PART_STATUSES = ["done", "partial", "blocked", "failed", "interrupted", "stopped", "stalled", "out"];
+export const PART_STATUSES = ["done", "partial", "blocked", "failed", "interrupted", "stopped", "gone", "stalled", "out"];
 /** One session started in a tree, as its record keeps it: durations in milliseconds, context use a share of the model's window. */
 const Part = Schema.Struct({
     sessionID: Schema.String,
@@ -33,9 +33,13 @@ const Record = Schema.Struct({
     finished: Schema.Boolean,
     recalled: Schema.optionalKey(Schema.Struct({ at: Schema.optionalKey(Schema.Number), calls: Count })),
     lesson: Schema.optionalKey(Lesson),
+    /** How often other trees' courier_recall calls listed the record and gave it in full, and when one last did. */
+    reads: Schema.optionalKey(Schema.Struct({ shown: Count, read: Count, at: Schema.Number })),
+    /** The person's pin, when; a pinned record is listed first and never swept. */
+    pinned: Schema.optionalKey(Schema.Struct({ at: Schema.Number })),
     parts: Schema.Array(Part),
 });
-/** The records of the project of the location asked, newest first; none, and `memory` false, when the option is off there. */
+/** The records of the project of the location asked, pinned first and then newest first; none, and `memory` false, when the option is off there. */
 const Records = Schema.Struct({
     memory: Schema.Boolean,
     projectID: Schema.String,
@@ -43,6 +47,8 @@ const Records = Schema.Struct({
 });
 /** What a forget did: removed the record, dropped only its lesson, or found nothing to forget. */
 const Forgotten = Schema.Struct({ outcome: Schema.Literals(["record", "lesson", "none"]) });
+/** What a pin did: pinned the record, unpinned it, or found no record to pin. */
+const Pinned = Schema.Struct({ outcome: Schema.Literals(["pinned", "unpinned", "none"]) });
 export const memoryRpc = Rpc.define({
     id: "courier-memory",
     methods: {
@@ -55,6 +61,11 @@ export const memoryRpc = Rpc.define({
             input: Schema.toStandardSchemaV1(Schema.Struct({ sessionID: Schema.String, lesson: Schema.optionalKey(Schema.Boolean) })),
             output: Schema.toStandardSchemaV1(Forgotten),
         },
+        /** Pins the record of the tree under `sessionID` in the project asked, or with `pinned` false unpins it. */
+        pin: {
+            input: Schema.toStandardSchemaV1(Schema.Struct({ sessionID: Schema.String, pinned: Schema.Boolean })),
+            output: Schema.toStandardSchemaV1(Pinned),
+        },
     },
     events: {},
 });

package/dist/memory/store.d.ts

@@ -4,7 +4,11 @@ import type { MemoryStore } from "./ports.js";
 export declare const recordKey: (projectID: string, sessionID: string) => string;
 /** The key prefix of a project's records. */
 export declare const projectPrefix: (projectID: string) => string;
-/** A record as stored, or undefined for a value that is not one. */
+/** The person's pin on a record, `{ at }`; the key's presence pins. */
+export declare const pinKey: (projectID: string, sessionID: string) => string;
+/** The reads of a record by the tree under `by`, `{ shown, read, at }`, written only by that tree's sessions. */
+export declare const readsKey: (projectID: string, sessionID: string, by: string) => string;
+/** A record as stored, or undefined for a value that is not one; its reads and pin lie beside it (`beside`). */
 export declare function readRecord(value: unknown): TreeRecord | undefined;
 /** The `MemoryStore` over the plugin's storage. */
 export declare function memoryStore(storage: Storage): MemoryStore;