opencode-courier 0.7.3 → 0.8.0

package/dist/memory/rpc-handlers.js

@@ -0,0 +1,23 @@
+import { newestFirst } from "./domain.js";
+import { forget } from "./forget.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;
+/**
+ * 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 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) };
+}
+/** 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 }) }),
+    });
+}

package/dist/memory/rpc.d.ts

@@ -0,0 +1,227 @@
+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"];
+/** 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;
+    readonly title: Schema.String;
+    /** 1 for a session the top started. */
+    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 duration: Schema.optionalKey<Schema.Number>;
+    readonly cost: Schema.optionalKey<Schema.Number>;
+    readonly context: Schema.optionalKey<Schema.Number>;
+    readonly refused: Schema.optionalKey<Schema.Int>;
+}>;
+/** The one line the tree's orchestrator wrote with courier_note: when, and from which depth when not the top's own. */
+declare const Lesson: Schema.Struct<{
+    readonly text: Schema.String;
+    readonly at: Schema.Number;
+    readonly depth: Schema.optionalKey<Schema.Int>;
+}>;
+/** A tree's record as `courier_recall` reads it, with the top session it is kept under; times in epoch milliseconds. */
+declare const Record: Schema.Struct<{
+    readonly sessionID: Schema.String;
+    readonly startedAt: Schema.Number;
+    readonly movedAt: Schema.Number;
+    readonly title: Schema.String;
+    readonly split: Schema.String;
+    readonly finished: Schema.Boolean;
+    readonly recalled: Schema.optionalKey<Schema.Struct<{
+        readonly at: Schema.optionalKey<Schema.Number>;
+        readonly calls: Schema.Int;
+    }>>;
+    readonly lesson: Schema.optionalKey<Schema.Struct<{
+        readonly text: Schema.String;
+        readonly at: Schema.Number;
+        readonly depth: Schema.optionalKey<Schema.Int>;
+    }>>;
+    readonly parts: Schema.$Array<Schema.Struct<{
+        readonly sessionID: Schema.String;
+        readonly title: Schema.String;
+        /** 1 for a session the top started. */
+        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 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. */
+declare const Records: Schema.Struct<{
+    readonly memory: Schema.Boolean;
+    readonly projectID: Schema.String;
+    readonly records: Schema.$Array<Schema.Struct<{
+        readonly sessionID: Schema.String;
+        readonly startedAt: Schema.Number;
+        readonly movedAt: Schema.Number;
+        readonly title: Schema.String;
+        readonly split: Schema.String;
+        readonly finished: Schema.Boolean;
+        readonly recalled: Schema.optionalKey<Schema.Struct<{
+            readonly at: Schema.optionalKey<Schema.Number>;
+            readonly calls: Schema.Int;
+        }>>;
+        readonly lesson: Schema.optionalKey<Schema.Struct<{
+            readonly text: Schema.String;
+            readonly at: Schema.Number;
+            readonly depth: Schema.optionalKey<Schema.Int>;
+        }>>;
+        readonly parts: Schema.$Array<Schema.Struct<{
+            readonly sessionID: Schema.String;
+            readonly title: Schema.String;
+            /** 1 for a session the top started. */
+            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 duration: Schema.optionalKey<Schema.Number>;
+            readonly cost: Schema.optionalKey<Schema.Number>;
+            readonly context: Schema.optionalKey<Schema.Number>;
+            readonly refused: Schema.optionalKey<Schema.Int>;
+        }>>;
+    }>>;
+}>;
+/** What a forget did: removed the record, dropped only its lesson, or found nothing to forget. */
+declare const Forgotten: Schema.Struct<{
+    readonly outcome: Schema.Literals<readonly ["record", "lesson", "none"]>;
+}>;
+export type MemoryRecord = typeof Record.Type;
+export type MemoryPart = typeof Part.Type;
+export type MemoryLesson = typeof Lesson.Type;
+export type Records = typeof Records.Type;
+export type Forgotten = typeof Forgotten.Type;
+export declare const memoryRpc: {
+    readonly id: "courier-memory";
+    readonly methods: {
+        readonly records: {
+            readonly input: import("effect/StandardSchema").StandardSchemaV1<{}, {}> & Schema.Struct<{}>;
+            readonly output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly memory: boolean;
+                readonly projectID: string;
+                readonly records: readonly {
+                    readonly sessionID: string;
+                    readonly title: string;
+                    readonly parts: readonly {
+                        readonly status: "done" | "partial" | "blocked" | "failed" | "interrupted" | "stopped" | "stalled" | "out";
+                        readonly sessionID: string;
+                        readonly title: string;
+                        readonly depth: number;
+                        readonly isolated: boolean;
+                        readonly group?: string | undefined;
+                        readonly duration?: number | undefined;
+                        readonly cost?: number | undefined;
+                        readonly context?: number | undefined;
+                        readonly refused?: number | undefined;
+                    }[];
+                    readonly startedAt: number;
+                    readonly movedAt: number;
+                    readonly split: string;
+                    readonly finished: boolean;
+                    readonly recalled?: {
+                        readonly calls: number;
+                        readonly at?: number | undefined;
+                    } | undefined;
+                    readonly lesson?: {
+                        readonly text: string;
+                        readonly at: number;
+                        readonly depth?: number | undefined;
+                    } | undefined;
+                }[];
+            }, {
+                readonly memory: boolean;
+                readonly projectID: string;
+                readonly records: readonly {
+                    readonly sessionID: string;
+                    readonly title: string;
+                    readonly parts: readonly {
+                        readonly status: "done" | "partial" | "blocked" | "failed" | "interrupted" | "stopped" | "stalled" | "out";
+                        readonly sessionID: string;
+                        readonly title: string;
+                        readonly depth: number;
+                        readonly isolated: boolean;
+                        readonly group?: string | undefined;
+                        readonly duration?: number | undefined;
+                        readonly cost?: number | undefined;
+                        readonly context?: number | undefined;
+                        readonly refused?: number | undefined;
+                    }[];
+                    readonly startedAt: number;
+                    readonly movedAt: number;
+                    readonly split: string;
+                    readonly finished: boolean;
+                    readonly recalled?: {
+                        readonly calls: number;
+                        readonly at?: number | undefined;
+                    } | undefined;
+                    readonly lesson?: {
+                        readonly text: string;
+                        readonly at: number;
+                        readonly depth?: number | undefined;
+                    } | undefined;
+                }[];
+            }> & Schema.Struct<{
+                readonly memory: Schema.Boolean;
+                readonly projectID: Schema.String;
+                readonly records: Schema.$Array<Schema.Struct<{
+                    readonly sessionID: Schema.String;
+                    readonly startedAt: Schema.Number;
+                    readonly movedAt: Schema.Number;
+                    readonly title: Schema.String;
+                    readonly split: Schema.String;
+                    readonly finished: Schema.Boolean;
+                    readonly recalled: Schema.optionalKey<Schema.Struct<{
+                        readonly at: Schema.optionalKey<Schema.Number>;
+                        readonly calls: Schema.Int;
+                    }>>;
+                    readonly lesson: Schema.optionalKey<Schema.Struct<{
+                        readonly text: Schema.String;
+                        readonly at: Schema.Number;
+                        readonly depth: Schema.optionalKey<Schema.Int>;
+                    }>>;
+                    readonly parts: Schema.$Array<Schema.Struct<{
+                        readonly sessionID: Schema.String;
+                        readonly title: Schema.String;
+                        /** 1 for a session the top started. */
+                        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 duration: Schema.optionalKey<Schema.Number>;
+                        readonly cost: Schema.optionalKey<Schema.Number>;
+                        readonly context: Schema.optionalKey<Schema.Number>;
+                        readonly refused: Schema.optionalKey<Schema.Int>;
+                    }>>;
+                }>>;
+            }>;
+        };
+        /** Forgets the record of the tree under `sessionID` in the project asked, or with `lesson` only its lesson, keeping the facts. */
+        readonly forget: {
+            readonly input: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly sessionID: string;
+                readonly lesson?: boolean | undefined;
+            }, {
+                readonly sessionID: string;
+                readonly lesson?: boolean | undefined;
+            }> & Schema.Struct<{
+                readonly sessionID: Schema.String;
+                readonly lesson: Schema.optionalKey<Schema.Boolean>;
+            }>;
+            readonly output: import("effect/StandardSchema").StandardSchemaV1<{
+                readonly outcome: "lesson" | "record" | "none";
+            }, {
+                readonly outcome: "lesson" | "record" | "none";
+            }> & Schema.Struct<{
+                readonly outcome: Schema.Literals<readonly ["record", "lesson", "none"]>;
+            }>;
+        };
+    };
+    readonly events: {};
+};
+export type MemoryRpc = typeof memoryRpc;
+export {};

package/dist/memory/rpc.js

@@ -0,0 +1,60 @@
+/**
+ * The memory's RPC, the contract its TUI part, the memory view, and its server half share. Standard Schema values, as
+ * the tree's and the person's; imports only `@opencode/plugin/rpc` and `effect`.
+ */
+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"];
+/** 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,
+    title: Schema.String,
+    /** 1 for a session the top started. */
+    depth: Count,
+    isolated: Schema.Boolean,
+    group: Schema.optionalKey(Schema.String),
+    status: Schema.Literals(PART_STATUSES),
+    duration: Schema.optionalKey(Schema.Number),
+    cost: Schema.optionalKey(Schema.Number),
+    context: Schema.optionalKey(Schema.Number),
+    refused: Schema.optionalKey(Count),
+});
+/** The one line the tree's orchestrator wrote with courier_note: when, and from which depth when not the top's own. */
+const Lesson = Schema.Struct({ text: Schema.String, at: Schema.Number, depth: Schema.optionalKey(Count) });
+/** A tree's record as `courier_recall` reads it, with the top session it is kept under; times in epoch milliseconds. */
+const Record = Schema.Struct({
+    sessionID: Schema.String,
+    startedAt: Schema.Number,
+    movedAt: Schema.Number,
+    title: Schema.String,
+    split: Schema.String,
+    finished: Schema.Boolean,
+    recalled: Schema.optionalKey(Schema.Struct({ at: Schema.optionalKey(Schema.Number), calls: Count })),
+    lesson: Schema.optionalKey(Lesson),
+    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. */
+const Records = Schema.Struct({
+    memory: Schema.Boolean,
+    projectID: Schema.String,
+    records: Schema.Array(Record),
+});
+/** 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"]) });
+export const memoryRpc = Rpc.define({
+    id: "courier-memory",
+    methods: {
+        records: {
+            input: Schema.toStandardSchemaV1(Schema.Struct({})),
+            output: Schema.toStandardSchemaV1(Records),
+        },
+        /** Forgets the record of the tree under `sessionID` in the project asked, or with `lesson` only its lesson, keeping the facts. */
+        forget: {
+            input: Schema.toStandardSchemaV1(Schema.Struct({ sessionID: Schema.String, lesson: Schema.optionalKey(Schema.Boolean) })),
+            output: Schema.toStandardSchemaV1(Forgotten),
+        },
+    },
+    events: {},
+});

package/dist/memory/store.d.ts

@@ -0,0 +1,10 @@
+import { type Storage } from "../platform/storage.js";
+import { type TreeRecord } from "./domain.js";
+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. */
+export declare function readRecord(value: unknown): TreeRecord | undefined;
+/** The `MemoryStore` over the plugin's storage. */
+export declare function memoryStore(storage: Storage): MemoryStore;

package/dist/memory/store.js

@@ -0,0 +1,90 @@
+import { finite, num, obj, str } from "../platform/json.js";
+import { scanEntries } from "../platform/storage.js";
+import { isPartStatus, lessonText, NOT_STATED } from "./domain.js";
+// The memory's storage: the only file that knows its key and layout. A record is read leniently, as one written by
+// hand with `e2e/kv.ts set` is: what is missing takes a default, a part without a session id is left out.
+const PREFIX = "memory/";
+export const recordKey = (projectID, sessionID) => `${PREFIX}${projectID}/${sessionID}`;
+/** The key prefix of a project's records. */
+export const projectPrefix = (projectID) => `${PREFIX}${projectID}/`;
+function readPart(value) {
+    const given = obj(value);
+    const sessionID = str(given.sessionID);
+    if (sessionID === undefined)
+        return undefined;
+    const optional = (field) => {
+        const number = finite(given[field]);
+        return number === undefined ? {} : { [field]: number };
+    };
+    const group = str(given.group);
+    return {
+        sessionID,
+        title: str(given.title) ?? "",
+        depth: num(given.depth) ?? 1,
+        isolated: given.isolated === true,
+        ...(group ? { group } : {}),
+        status: isPartStatus(given.status) ? given.status : "out",
+        ...optional("duration"),
+        ...optional("cost"),
+        ...optional("context"),
+        ...optional("refused"),
+    };
+}
+function readRecalled(value) {
+    const given = obj(value);
+    const calls = num(given.calls);
+    if (calls === undefined)
+        return undefined;
+    const at = num(given.at);
+    return at === undefined ? { calls } : { at, calls };
+}
+/** A lesson as `{ text, at, depth }`, or as a bare string written by hand, dated `movedAt`; none for an empty text. */
+function readLesson(value, movedAt) {
+    const given = typeof value === "string" ? { text: value } : obj(value);
+    const { text } = lessonText(str(given.text) ?? "");
+    if (!text)
+        return undefined;
+    const depth = num(given.depth);
+    return { text, at: num(given.at) ?? movedAt, ...(depth !== undefined && Number.isInteger(depth) && depth > 0 ? { depth } : {}) };
+}
+/** A record as stored, or undefined for a value that is not one. */
+export function readRecord(value) {
+    const given = obj(value);
+    if (!Array.isArray(given.parts))
+        return undefined;
+    const recalled = readRecalled(given.recalled);
+    const movedAt = num(given.movedAt) ?? num(given.startedAt) ?? 0;
+    const lesson = readLesson(given.lesson, movedAt);
+    return {
+        startedAt: num(given.startedAt) ?? 0,
+        movedAt,
+        title: str(given.title) ?? "",
+        split: str(given.split) ?? NOT_STATED,
+        finished: given.finished === true,
+        ...(recalled ? { recalled } : {}),
+        ...(lesson ? { lesson } : {}),
+        parts: given.parts.map(readPart).filter((part) => part !== undefined),
+    };
+}
+/** The `MemoryStore` over the plugin's storage. */
+export function memoryStore(storage) {
+    const under = async (prefix) => {
+        const entries = await scanEntries(storage, prefix);
+        return entries.flatMap(({ key, value }) => {
+            const parts = `${prefix.slice(PREFIX.length)}${key}`.split("/");
+            const record = parts.length === 2 ? readRecord(value) : undefined;
+            return record ? [{ ...record, projectID: parts[0], sessionID: parts[1] }] : [];
+        });
+    };
+    return {
+        get: async (projectID, sessionID) => readRecord(await storage.get(recordKey(projectID, sessionID))),
+        async put(projectID, sessionID, record) {
+            await storage.set(recordKey(projectID, sessionID), { ...record, parts: record.parts.map((part) => ({ ...part })) });
+        },
+        async remove(projectID, sessionID) {
+            await storage.remove(recordKey(projectID, sessionID));
+        },
+        ofProject: (projectID) => under(projectPrefix(projectID)),
+        all: () => under(PREFIX),
+    };
+}

package/dist/memory/sweep.d.ts

@@ -0,0 +1,4 @@
+import type { Storage } from "../platform/storage.js";
+import { type StoredRecord } from "./domain.js";
+/** On loading: drops, per project, the records past `MAX_RECORDS` or `RETENTION_MS` at `now`. Returns those dropped. */
+export declare function sweepRecords(storage: Storage, now: number): Promise<StoredRecord[]>;

package/dist/memory/sweep.js

@@ -0,0 +1,12 @@
+import { keep } from "./domain.js";
+import { memoryStore } from "./store.js";
+/** On loading: drops, per project, the records past `MAX_RECORDS` or `RETENTION_MS` at `now`. Returns those dropped. */
+export async function sweepRecords(storage, now) {
+    const store = memoryStore(storage);
+    const byProject = new Map();
+    for (const record of await store.all())
+        byProject.set(record.projectID, [...(byProject.get(record.projectID) ?? []), record]);
+    const dropped = [...byProject.values()].flatMap((records) => keep(records, now).dropped);
+    await Promise.all(dropped.map((record) => store.remove(record.projectID, record.sessionID)));
+    return dropped;
+}

package/dist/memory/text.d.ts

@@ -0,0 +1,27 @@
+import { type Lesson, type StoredRecord } from "./domain.js";
+/** The tool's name, which the skill and the role part name too. */
+export declare const RECALL_TOOL = "courier_recall";
+/** The lesson tool's name, which the skill's last step names. */
+export declare const NOTE_TOOL = "courier_note";
+/** A duration in milliseconds as a model reads it: seconds under half a minute, else whole minutes, else hours and minutes. */
+export declare function duration(ms: number): string;
+/** A lesson as the listing and the note's result show it: dated, and from which depth when a session below the top wrote it. */
+export declare function lessonLine(lesson: Lesson): string;
+/** One record as the listing shows it: its top, when it started, its title, its split line, its parts, how long it ran and what it cost. */
+export declare function recordLine(record: StoredRecord, top: string): string;
+/** What courier_recall says when the memory option is off. */
+export declare const RECALL_OFF = "Memory is off: the plugin's memory option is false, so no record of a session tree is kept or listed in this project. Decide from the task alone.";
+/** The listing: every record of the project, newest first, the caller's own tree marked. */
+export declare function recallListText(records: ReadonlyArray<StoredRecord>, top: string): string;
+/** One record in full, as JSON: durations in milliseconds, times in epoch milliseconds, context use as a share of the model's window. */
+export declare function recallRecordText(record: StoredRecord): string;
+export declare const recallMissingText: (sessionID: string) => string;
+/** What courier_note says once the lesson is written: where, and what it replaced. */
+export declare function noteText(top: string, lesson: Lesson, replaced: Lesson | undefined): string;
+/** What courier_note says when the memory option is off. */
+export declare const NOTE_OFF = "Not noted: the plugin's memory option is false, so no record of a session tree is kept in this project to write a lesson on.";
+export declare const noteLeafRefusal: (depth: number, maxDepth: number) => string;
+export declare const NOTE_EMPTY = "Not noted: text is empty. Write one line, what the next orchestrator in this project should know about running a tree like this one, with the job it comes from and the reason, or nothing.";
+/** The refusal of a lesson longer than `LESSON_MAX` as one line: nothing is written, and the earlier lesson stays. */
+export declare const noteLongRefusal: (length: number) => string;
+export declare const noteUnrecordedRefusal: (top: string) => string;

package/dist/memory/text.js

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

package/dist/memory/tools.d.ts

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