@astrosheep/pi-context 0.19.0 → 0.20.0

package/dist/src/memory/store.js

@@ -0,0 +1,297 @@
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { generateDiffString } from "@earendil-works/pi-coding-agent";
+import { assertGlobPattern, assertVirtualPath, globToRegExp } from "../notes.js";
+import { MAX_NOTE_BYTES, MAX_NOTE_PATH_BYTES } from "../protocol.js";
+import { isOrigin, isScope, parseNote, serializeNote, stripLeadingFrontmatter } from "./frontmatter.js";
+import { physicalPath, scopeDir } from "./paths.js";
+/** Typed store refusal. `line_numbers` and `edit_index` are the edit error's addressing fields. */
+export class NoteError extends Error {
+    code;
+    line_numbers;
+    edit_index;
+    constructor(code, message, extra = {}) {
+        super(message);
+        this.name = "NoteError";
+        this.code = code;
+        this.line_numbers = extra.line_numbers;
+        this.edit_index = extra.edit_index;
+    }
+}
+const SCOPE_ORDER = ["session", "project", "global"];
+function assertScope(value) {
+    if (!isScope(value))
+        throw new NoteError("invalid_scope", `scope must be one of session, project, global (got ${JSON.stringify(value)})`);
+    return value;
+}
+function assertOrigin(value) {
+    if (!isOrigin(value))
+        throw new NoteError("invalid_origin", `origin must be one of user, self, external (got ${JSON.stringify(value)})`);
+    return value;
+}
+function scopeList(scope) {
+    if (scope === undefined || scope === null)
+        return [...SCOPE_ORDER];
+    return [assertScope(scope)];
+}
+/** First existing file by precedence session → project → global, or only `scope` when given. */
+function resolve(ctx, vpath, scope) {
+    for (const candidate of scopeList(scope)) {
+        const path = physicalPath(candidate, vpath, ctx);
+        if (existsSync(path))
+            return { scope: candidate, path, raw: readFileSync(path, "utf8") };
+    }
+    return undefined;
+}
+/** Recursively list `.md` files under `dir` as forward-slash virtual paths relative to `base`. */
+function walkMarkdown(dir, base = dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const paths = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const child = `${dir}/${entry.name}`;
+        if (entry.isDirectory())
+            paths.push(...walkMarkdown(child, base));
+        else if (entry.isFile() && entry.name.endsWith(".md"))
+            paths.push(child.slice(base.length + 1).split("\\").join("/"));
+    }
+    return paths;
+}
+function matcherFor(pattern) {
+    const normalized = assertGlobPattern(pattern);
+    return normalized === undefined ? undefined : globToRegExp(normalized);
+}
+/**
+ * Every mutation lands through a tmp file renamed into place in the same directory, so a crash
+ * never leaves a torn note. No cross-process locking: out of scope by decision.
+ */
+function atomicWrite(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(tmp, content);
+        renameSync(tmp, path);
+    }
+    catch (error) {
+        rmSync(tmp, { force: true });
+        throw error;
+    }
+}
+/** Write-time vpath guard: the byte cap is a tool-boundary rule, never a jail rule. */
+function assertWritablePath(vpath) {
+    const bytes = Buffer.byteLength(vpath, "utf8");
+    if (bytes > MAX_NOTE_PATH_BYTES)
+        throw new NoteError("too_large", `note path exceeds ${MAX_NOTE_PATH_BYTES} UTF-8 bytes (got ${bytes})`);
+}
+/** Serialized-size guard applied after the frontmatter is merged, before any bytes are written. */
+function assertSerializedSize(content) {
+    const bytes = Buffer.byteLength(content, "utf8");
+    if (bytes > MAX_NOTE_BYTES)
+        throw new NoteError("too_large", `note exceeds ${MAX_NOTE_BYTES} UTF-8 bytes (serialized ${bytes})`);
+}
+/** Frontmatter block only (the body separator stripped), for the metadata-only diff. */
+function frontmatterOf(meta) {
+    return serializeNote(meta, "").slice(0, -2);
+}
+/** Line numbers (1-based) of every occurrence of `needle` in `body`. */
+function matchLineNumbers(body, needle) {
+    const lines = [];
+    let cursor = 0;
+    for (;;) {
+        const index = body.indexOf(needle, cursor);
+        if (index === -1)
+            break;
+        lines.push(body.slice(0, index).split("\n").length);
+        cursor = index + Math.max(needle.length, 1);
+    }
+    return lines;
+}
+/** Create or overwrite a note; overwrite keeps created_at and every unknown key. */
+export function writeNote(ctx, vpath, body, opts) {
+    assertVirtualPath(vpath);
+    assertWritablePath(vpath);
+    const scope = assertScope(opts.scope);
+    const origin = assertOrigin(opts.origin);
+    const path = physicalPath(scope, vpath, ctx);
+    const now = Date.now();
+    const cleanBody = stripLeadingFrontmatter(body);
+    const existing = existsSync(path) ? parseNote(readFileSync(path, "utf8"), now).meta : undefined;
+    const meta = existing ?? {
+        scope,
+        origin,
+        status: "active",
+        stale: false,
+        created_at: now,
+        updated_at: now,
+        last_accessed: now,
+        access_count: 0,
+    };
+    meta.scope = scope;
+    meta.origin = origin;
+    meta.status = "active";
+    meta.stale = opts.stale ?? false;
+    meta.updated_at = now;
+    const serialized = serializeNote(meta, cleanBody);
+    assertSerializedSize(serialized);
+    atomicWrite(path, serialized);
+    return { meta };
+}
+/** Dream harness mutation: metadata changes still use the store's atomic writer. */
+export function updateNoteMeta(ctx, vpath, scope, mutate) {
+    assertVirtualPath(vpath);
+    const path = physicalPath(scope, vpath, ctx);
+    if (!existsSync(path))
+        throw new NoteError("not_found", `note not found: ${vpath}`);
+    const parsed = parseNote(readFileSync(path, "utf8"));
+    const meta = { ...parsed.meta, scope };
+    mutate(meta);
+    meta.updated_at = Date.now();
+    const serialized = serializeNote(meta, parsed.body);
+    assertSerializedSize(serialized);
+    atomicWrite(path, serialized);
+    return { meta, body: parsed.body };
+}
+/** Apply body-only edits against one snapshot, then optionally move via the scope/origin/stale setters. */
+export function editNote(ctx, vpath, edits, opts = {}) {
+    assertVirtualPath(vpath);
+    assertWritablePath(vpath);
+    const operations = edits ?? [];
+    if (operations.length === 0 && opts.scope === undefined && opts.origin === undefined && opts.stale === undefined) {
+        throw new NoteError("nothing_to_do", "nothing to do: provide edits or at least one of scope, origin, stale");
+    }
+    const found = resolve(ctx, vpath);
+    if (!found)
+        throw new NoteError("not_found", "note not found");
+    const { meta, body } = parseNote(found.raw);
+    // Snapshot the pre-edit frontmatter so the diff can name exactly what the setters changed.
+    const beforeMeta = { ...meta };
+    // Every edit runs against this one snapshot; nothing is written until all of them succeed,
+    // so a failing edit leaves the file byte-identical (frontmatter included).
+    let next = body;
+    operations.forEach((edit, index) => {
+        const oldText = edit?.oldText;
+        const newText = edit?.newText;
+        if (typeof oldText !== "string" || oldText.length === 0)
+            throw new NoteError("no_match", `edit ${index}: oldText must be a non-empty string`, { edit_index: index });
+        if (typeof newText !== "string")
+            throw new NoteError("no_match", `edit ${index}: newText must be a string`, { edit_index: index });
+        const lines = matchLineNumbers(next, oldText);
+        if (lines.length === 0)
+            throw new NoteError("no_match", `edit ${index}: oldText does not occur in the note body`, { edit_index: index });
+        if (lines.length > 1 && !opts.replaceAll) {
+            throw new NoteError("ambiguous_edit", `edit ${index}: oldText occurs ${lines.length} times (lines ${lines.join(", ")}); pass replace_all to replace every occurrence`, { line_numbers: lines, edit_index: index });
+        }
+        next = opts.replaceAll ? next.split(oldText).join(newText) : next.replace(oldText, newText);
+    });
+    const destScope = opts.scope === undefined ? found.scope : assertScope(opts.scope);
+    if (opts.origin !== undefined)
+        meta.origin = assertOrigin(opts.origin);
+    if (opts.stale !== undefined)
+        meta.stale = opts.stale;
+    meta.scope = destScope;
+    meta.updated_at = Date.now();
+    const dest = physicalPath(destScope, vpath, ctx);
+    const moving = dest !== found.path;
+    if (moving && existsSync(dest)) {
+        throw new NoteError("target_exists", `a note already exists at ${vpath} in scope ${destScope}; the move was refused and both files are unchanged`);
+    }
+    const serialized = serializeNote(meta, next);
+    assertSerializedSize(serialized);
+    // pi-edit-style diff: body only for a content edit, frontmatter only for a metadata-only
+    // update, one combined file diff when both moved.
+    const bodyChanged = body !== next;
+    const metadataChanged = beforeMeta.scope !== meta.scope || beforeMeta.origin !== meta.origin || beforeMeta.stale !== meta.stale;
+    const diff = bodyChanged && metadataChanged
+        ? generateDiffString(found.raw, serialized).diff
+        : bodyChanged
+            ? generateDiffString(body, next).diff
+            : metadataChanged
+                ? generateDiffString(frontmatterOf(beforeMeta), frontmatterOf(meta)).diff
+                : "";
+    atomicWrite(dest, serialized);
+    if (moving)
+        rmSync(found.path);
+    return { meta, applied: operations.length, resolved_scope: found.scope, diff };
+}
+/** Read a note and, as a side effect, bump last_accessed/access_count in the file. */
+export function readNote(ctx, vpath, opts = {}) {
+    assertVirtualPath(vpath);
+    const found = resolve(ctx, vpath, opts.scope);
+    if (!found)
+        return undefined;
+    const now = Date.now();
+    const { meta, body } = parseNote(found.raw, now);
+    meta.scope = found.scope;
+    // Only the two access keys move; updated_at and every other key keep their bytes.
+    meta.last_accessed = now;
+    meta.access_count = (typeof meta.access_count === "number" ? meta.access_count : 0) + 1;
+    atomicWrite(found.path, serializeNote(meta, body));
+    return { meta, body, resolvedScope: found.scope };
+}
+/** The scope that holds `vpath` first by precedence, without reading or mutating the file. */
+export function resolveNoteScope(ctx, vpath, scope) {
+    const found = resolve(ctx, vpath, scope);
+    return found ? { scope: found.scope, path: found.path } : undefined;
+}
+/** Read a note's meta and body without the read side effect (used by the boot index). */
+export function peekNote(ctx, scope, vpath) {
+    const path = physicalPath(scope, vpath, ctx);
+    const { meta, body } = parseNote(readFileSync(path, "utf8"));
+    meta.scope = scope;
+    return { meta, body };
+}
+/** Merged rows across scopes, most recently updated first (path then scope break ties). */
+export function listNotes(ctx, opts = {}) {
+    const matcher = matcherFor(opts.pattern);
+    const rows = [];
+    for (const scope of scopeList(opts.scope)) {
+        const root = scopeDir(scope, ctx);
+        for (const path of walkMarkdown(root)) {
+            if (matcher && !matcher.test(path))
+                continue;
+            const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));
+            meta.scope = scope;
+            rows.push({ path, meta, sizeBytes: Buffer.byteLength(body, "utf8") });
+        }
+    }
+    rows.sort((a, b) => b.meta.updated_at - a.meta.updated_at || a.path.localeCompare(b.path) || a.meta.scope.localeCompare(b.meta.scope));
+    return rows;
+}
+/** Case-sensitive literal substring search over note bodies, with a match address per line. */
+export function searchNotes(ctx, queries, opts = {}) {
+    const matcher = matcherFor(opts.pattern);
+    const rows = [];
+    for (const scope of scopeList(opts.scope)) {
+        const root = scopeDir(scope, ctx);
+        for (const path of walkMarkdown(root)) {
+            if (matcher && !matcher.test(path))
+                continue;
+            const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));
+            meta.scope = scope;
+            let baseChars = 0;
+            const matches = [];
+            for (const [index, line] of body.split("\n").entries()) {
+                if (queries.some((query) => line.includes(query))) {
+                    let earliest = -1;
+                    for (const query of queries) {
+                        const found = line.indexOf(query);
+                        if (found >= 0 && (earliest < 0 || found < earliest))
+                            earliest = found;
+                    }
+                    matches.push({ line: index + 1, text: line, offsetChars: baseChars + (earliest <= 0 ? 0 : Array.from(line.slice(0, earliest)).length) });
+                }
+                baseChars += Array.from(line).length + 1;
+            }
+            if (matches.length > 0)
+                rows.push({ path, scope, meta, matches });
+        }
+    }
+    rows.sort((a, b) => a.path.localeCompare(b.path) || a.scope.localeCompare(b.scope));
+    return rows;
+}

package/dist/src/memory/tools.js

@@ -0,0 +1,175 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { localIso } from "../notes.js";
+import { characterWindowHeader, middleTruncate, output, outputRaw, page, prefixFit, readCharacterWindow, withinTextBudget } from "../tool-output.js";
+import { cursor, nullableString, positiveInteger, searchQueries, searchQuery } from "../tool-schema.js";
+import { serializeNote, stripLeadingFrontmatter } from "./frontmatter.js";
+import { NoteError, editNote, listNotes, readNote, searchNotes, writeNote } from "./store.js";
+const SCOPE = Type.Optional(Type.Union([Type.Literal("session"), Type.Literal("project"), Type.Literal("global")], {
+    description: "The note's reach — which root it lives under. session: only this session needs it (checkpoints, scratch state, worker rosters); dies with the session. project: tied to the current working directory — design decisions and repo facts that future sessions here still need. global: follows you everywhere — user laws, preferences, cross-project maps. On write, picks the destination root (default: session). Omit on read/list/search to cover all three; a read resolves session → project → global and returns the first existing file.",
+}));
+const ORIGIN = Type.Optional(Type.Union([Type.Literal("user"), Type.Literal("self"), Type.Literal("external")], {
+    description: "Where the note's content came from. user: written or dictated by the human. self: written by you, the agent (default). external: anything else — third-party text, tool output, fetched material.",
+}));
+/** Render epoch-ms metadata as the same local ISO timestamps the frontmatter carries. */
+function wireMeta(meta) {
+    return { ...meta, created_at: localIso(meta.created_at), updated_at: localIso(meta.updated_at), last_accessed: localIso(meta.last_accessed) };
+}
+/** Turn a typed store refusal into the pinned error arm; unknown errors stay thrown. */
+function failure(error) {
+    if (error instanceof NoteError) {
+        const payload = { error: error.message };
+        if (error.line_numbers)
+            payload.line_numbers = error.line_numbers;
+        if (error.edit_index !== undefined)
+            payload.edit_index = error.edit_index;
+        return output(payload);
+    }
+    throw error;
+}
+export function registerMemoryTools(pi) {
+    pi.registerTool(defineTool({
+        name: "notes_write",
+        label: "Notes write",
+        description: "Create or replace a note as a real markdown file under the session, project, or global note root. Keep notes small and split by topic — by what the note is about, never by who said it (authorship is origin's job); a rewrite replaces the body whole while preserving created_at and every other frontmatter key. stale: true marks the note closed so it leaves the boot index but stays readable and searchable.",
+        parameters: Type.Object({ path: Type.String(), content: Type.String(), scope: SCOPE, origin: ORIGIN, stale: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
+        // A batch containing write or edit runs one call at a time, so note read-modify-write cannot race.
+        executionMode: "sequential",
+        async execute(_id, params, _signal, _update, ctx) {
+            const content = params.content;
+            try {
+                const { meta } = writeNote(ctx, params.path, content, { scope: (params.scope ?? "session"), origin: (params.origin ?? "self"), stale: params.stale });
+                return output({ path: params.path, scope: meta.scope, size_bytes: Buffer.byteLength(stripLeadingFrontmatter(content), "utf8"), meta: wireMeta(meta) });
+            }
+            catch (error) {
+                return failure(error);
+            }
+        },
+    }));
+    pi.registerTool(defineTool({
+        name: "notes_edit",
+        label: "Notes edit",
+        description: "Edit a note body by exact-text replacement; frontmatter is never editable this way. Each oldText must occur exactly once unless replace_all is set; a multi-match anchor fails with its match line numbers and a zero-match anchor names the failing edit index. edits may be omitted (or empty) for a metadata-only update, which requires at least one of scope/origin/stale. scope/origin/stale are setters: scope moves the file, refusing when the target already exists. The success return carries resolved_scope and a diff of what changed.",
+        parameters: Type.Object({ path: Type.String(), edits: Type.Optional(Type.Array(Type.Object({ oldText: Type.String(), newText: Type.String() }, { additionalProperties: false }))), scope: SCOPE, origin: ORIGIN, stale: Type.Optional(Type.Boolean()), replace_all: Type.Optional(Type.Boolean()) }, { additionalProperties: false }),
+        executionMode: "sequential",
+        async execute(_id, params, _signal, _update, ctx) {
+            try {
+                const { meta, applied, resolved_scope, diff } = editNote(ctx, params.path, params.edits, { scope: params.scope, origin: params.origin, stale: params.stale, replaceAll: params.replace_all });
+                return output({ path: params.path, applied, resolved_scope, diff, meta: wireMeta(meta) });
+            }
+            catch (error) {
+                return failure(error);
+            }
+        },
+    }));
+    pi.registerTool(defineTool({
+        name: "notes_read",
+        label: "Notes read",
+        description: "Read a character window of a note file, frontmatter included: offset_chars is the code-point offset to start from (default 0) — a negative value counts back from the end — and limit_chars caps the window (default 12000, max 50000). Each response delivers the longest fitting prefix of that window: concatenate pages in order to reconstruct the note. The response is the raw frontmatter + body behind a one-line [bracketed] header naming the file, the resolved offset, the delivered char range, and the resume cursor.",
+        parameters: Type.Object({ path: Type.String(), scope: SCOPE, offset_chars: Type.Optional(Type.Integer({ description: "Code-point offset to start from (default 0). A negative value counts back from the end; the response echoes the resolved absolute offset. Pass the previous next_offset_chars back unchanged to continue." })), limit_chars: Type.Optional(Type.Integer({ minimum: 1, maximum: 50000, description: "Largest requested window in code points (default 12000). A window too large for the wire budget is cut short; next_offset_chars names where the next read resumes." })) }, { additionalProperties: false }),
+        async execute(_id, params, _signal, _update, ctx) {
+            let note;
+            try {
+                note = readNote(ctx, params.path, { scope: params.scope });
+            }
+            catch (error) {
+                return failure(error);
+            }
+            if (!note)
+                return output({ error: "note not found", path: params.path });
+            const text = serializeNote(note.meta, note.body);
+            const totalChars = Array.from(text).length;
+            // A positive offset past the end is an addressing error, not an empty page.
+            if (typeof params.offset_chars === "number" && params.offset_chars > totalChars) {
+                return output({ error: `offset_chars ${params.offset_chars} is past the end: the note has ${totalChars} chars; the largest legal offset is ${totalChars} (an empty end-read)`, path: params.path, offset_chars: params.offset_chars, total_chars: totalChars });
+            }
+            const created_at = localIso(note.meta.created_at);
+            const updated_at = localIso(note.meta.updated_at);
+            const limit_chars = Math.min(params.limit_chars ?? 12000, 50000);
+            return readCharacterWindow(text, params.offset_chars, params.limit_chars, (window) => {
+                const { content, ...rest } = window;
+                return outputRaw(characterWindowHeader(params.path, window, ` · ${note.resolvedScope} · created ${created_at} · updated ${updated_at}`), content, { path: params.path, scope: note.resolvedScope, ...rest, limit_chars, created_at, updated_at });
+            }, (result) => withinTextBudget(result.content[0].text));
+        },
+    }));
+    pi.registerTool(defineTool({
+        name: "notes_list",
+        label: "Notes list",
+        description: "List note files as rows carrying path, scope, origin, status, stale, size_bytes, created_at, and updated_at, most recently updated first. Without scope, all three scopes are merged; a glob pattern (* within a path segment, ** across segments) filters the virtual paths.",
+        parameters: Type.Object({ scope: SCOPE, pattern: nullableString(), cursor: cursor(), max_results: positiveInteger() }, { additionalProperties: false }),
+        async execute(_id, params, _signal, _update, ctx) {
+            let rows;
+            try {
+                rows = listNotes(ctx, { scope: params.scope, pattern: params.pattern ?? undefined });
+            }
+            catch (error) {
+                return failure(error);
+            }
+            const files = rows.map((row) => ({
+                path: row.path,
+                scope: row.meta.scope,
+                origin: row.meta.origin,
+                status: row.meta.status,
+                stale: row.meta.stale,
+                size_bytes: row.sizeBytes,
+                created_at: localIso(row.meta.created_at),
+                updated_at: localIso(row.meta.updated_at),
+            }));
+            return output(page(files, params.cursor ?? 0, "files", params.max_results, (file, fits) => {
+                if (fits(file))
+                    return file;
+                const path = middleTruncate(file.path, (candidate) => fits({ ...file, path: candidate, path_truncated: true }));
+                return { ...file, path, path_truncated: true };
+            }));
+        },
+    }));
+    pi.registerTool(defineTool({
+        name: "notes_search",
+        label: "Notes search",
+        description: "Case-sensitive literal substring search over note bodies; query is one string or several (OR), each matched line appears once. Without scope, all three scopes are merged and every entry carries its scope. Each file entry carries matches_total, its full match count before capping. Each match carries line, text, offset_chars (the body-absolute code-point offset of the earliest match).",
+        parameters: Type.Object({ query: searchQuery(), scope: SCOPE, pattern: nullableString(), cursor: cursor(), max_matches_per_file: positiveInteger(), max_files: positiveInteger() }, { additionalProperties: false }),
+        async execute(_id, params, _signal, _update, ctx) {
+            const queries = searchQueries(params.query);
+            let rows;
+            try {
+                rows = searchNotes(ctx, queries, { scope: params.scope, pattern: params.pattern ?? undefined });
+            }
+            catch (error) {
+                return failure(error);
+            }
+            const maxPerFile = params.max_matches_per_file ?? Number.POSITIVE_INFINITY;
+            const result = rows.map((row) => {
+                const matches = row.matches.map((match) => ({ line: match.line, text: match.text, truncated: false, total_chars: Array.from(match.text).length, offset_chars: match.offsetChars }));
+                return { path: row.path, scope: row.scope, created_at: localIso(row.meta.created_at), updated_at: localIso(row.meta.updated_at), matches_total: matches.length, matches: matches.slice(0, maxPerFile) };
+            });
+            // Trailing matches are dropped to fit the budget, named by matches_total; a single
+            // over-budget line is delivered as a flagged prefix; only a pathological path is
+            // middle-truncated, and then only with a visible path_truncated flag.
+            const fitFile = (file, fits) => {
+                if (fits(file))
+                    return file;
+                const matches = file.matches;
+                let low = 0;
+                let high = matches.length;
+                while (low < high) {
+                    const mid = Math.ceil((low + high) / 2);
+                    if (mid >= 1 && fits({ ...file, matches: matches.slice(0, mid) }))
+                        low = mid;
+                    else
+                        high = mid - 1;
+                }
+                if (low >= 1)
+                    return { ...file, matches: matches.slice(0, low) };
+                const first = matches[0];
+                const fitted = (text) => ({ ...file, matches: [{ ...first, text, truncated: true }] });
+                const text = prefixFit(first.text, (candidate) => fits(fitted(candidate)));
+                const prefix = fitted(text);
+                if (fits(prefix))
+                    return prefix;
+                const path = middleTruncate(prefix.path, (candidate) => fits({ ...prefix, path: candidate, path_truncated: true }));
+                return { ...prefix, path, path_truncated: true };
+            };
+            return output(page(result, params.cursor ?? 0, "files", params.max_files, fitFile));
+        },
+    }));
+}

package/dist/src/notes.js

@@ -0,0 +1,101 @@
+import { MAX_NOTE_BYTES, NOTE_TYPE } from "./protocol.js";
+export function assertVirtualPath(value) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error("path must be a non-empty virtual relative path");
+    if (value.includes("\0") || value.includes("\\") || value.startsWith("/"))
+        throw new Error("path must be a safe virtual relative path");
+    const parts = value.split("/");
+    if (parts.some((part) => part.length === 0 || part === "." || part === ".."))
+        throw new Error("path contains an unsupported component");
+    return value;
+}
+/**
+ * Minimal glob over virtual note paths: `*` matches any run within a segment (never
+ * `/`), `**` matches any run across segments (a leading double-star followed by a
+ * slash also matches zero segments, so it covers the root too), `?` matches exactly
+ * one non-`/` character. Everything else is literal and the match is anchored to the
+ * whole path.
+ */
+export function globToRegExp(pattern) {
+    let source = "^";
+    for (let index = 0; index < pattern.length; index++) {
+        const char = pattern[index];
+        if (char === "*") {
+            if (pattern[index + 1] === "*") {
+                const followedBySlash = pattern[index + 2] === "/";
+                source += followedBySlash ? "(?:[^]*\\/)?" : "[^]*";
+                index += followedBySlash ? 2 : 1;
+            }
+            else {
+                source += "[^/]*";
+            }
+        }
+        else {
+            source += char.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
+        }
+    }
+    return new RegExp(`${source}$`);
+}
+/** Glob patterns are not virtual paths (`*` is legal), so they get their own guard: no NUL, no backslashes. */
+export function assertGlobPattern(value) {
+    if (value === undefined || value === null || value === "")
+        return undefined;
+    if (typeof value !== "string")
+        throw new Error("glob pattern must be a string");
+    if (value.includes("\0") || value.includes("\\"))
+        throw new Error("glob pattern must not contain NUL or backslashes");
+    return value;
+}
+/** Replays only pi-context note operations from session custom entries. */
+function isNoteOperation(data) {
+    if (typeof data !== "object" || data === null)
+        return false;
+    const op = data;
+    return ((op.op === "write" || op.op === "append") &&
+        typeof op.path === "string" &&
+        (op.text === undefined || typeof op.text === "string") &&
+        (op.stale === undefined || typeof op.stale === "boolean") &&
+        (op.text !== undefined || op.stale !== undefined) &&
+        typeof op.createdAt === "number" && Number.isFinite(new Date(op.createdAt).getTime()) &&
+        typeof op.updatedAt === "number" && Number.isFinite(new Date(op.updatedAt).getTime()));
+}
+export function notesFromSession(ctx) {
+    const files = new Map();
+    for (const entry of ctx.sessionManager.getBranch()) {
+        if (entry.type !== "custom" || entry.customType !== NOTE_TYPE || !isNoteOperation(entry.data))
+            continue;
+        const op = entry.data;
+        try {
+            assertVirtualPath(op.path);
+        }
+        catch {
+            continue;
+        }
+        const previous = files.get(op.path);
+        const hasText = op.text !== undefined;
+        // A mark-only operation needs an existing note to change; without one it is a no-op.
+        if (!hasText && !previous)
+            continue;
+        const text = hasText ? (op.op === "append" ? `${previous?.text ?? ""}${op.text}` : op.text) : previous.text;
+        if (Buffer.byteLength(text, "utf8") > MAX_NOTE_BYTES)
+            continue;
+        // Carrying text revives unless the call also marks stale; a mark-only op keeps its flag.
+        const stale = hasText ? op.stale ?? false : op.stale ?? previous.stale;
+        files.set(op.path, { text, stale, createdAt: previous?.createdAt ?? op.createdAt, updatedAt: op.updatedAt });
+    }
+    return files;
+}
+const pad2 = (value) => String(value).padStart(2, "0");
+/**
+ * Format epoch milliseconds as an ISO 8601 string in the host's local time zone with an
+ * explicit numeric offset (e.g. 2026-09-15T17:31:45.392+08:00). A UTC host renders
+ * "+00:00"; the "Z" designator is never used, and Date.parse round-trips the value.
+ */
+export function localIso(epochMs) {
+    const date = new Date(epochMs);
+    const offsetMinutes = -date.getTimezoneOffset();
+    const absOffset = Math.abs(offsetMinutes);
+    const offset = `${offsetMinutes < 0 ? "-" : "+"}${pad2(Math.floor(absOffset / 60))}:${pad2(absOffset % 60)}`;
+    const wallClock = `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}T${pad2(date.getHours())}:${pad2(date.getMinutes())}:${pad2(date.getSeconds())}.${String(date.getMilliseconds()).padStart(3, "0")}`;
+    return `${wallClock}${offset}`;
+}

package/dist/src/prompts.js

@@ -0,0 +1,79 @@
+import { historyFromSession } from "./history.js";
+import { localIso } from "./notes.js";
+import { listNotes, peekNote, resolveNoteScope } from "./memory/store.js";
+import { CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, NOTE_PREVIEW_CHARS, NOTE_PREVIEW_HEAD_CHARS, NOTE_PREVIEW_TAIL_CHARS, RESET_SUMMARY, PROTOCOL_BLOCK, GUIDANCE_OPEN_TAG, GUIDANCE_CLOSE_TAG } from "./protocol.js";
+/** Codex-style <context_window> identity block: agent name and first/current/previous window ids only. */
+function identityBlock(agentName, firstWindowId, currentWindowId, previousWindowId) {
+    const lines = [
+        `Agent name: ${agentName}`,
+        `First context window id: ${firstWindowId}`,
+        `Current context window id: ${currentWindowId}`,
+    ];
+    if (previousWindowId)
+        lines.push(`Previous context window id: ${previousWindowId}`);
+    return `${CONTEXT_WINDOW_OPEN_TAG}\n${lines.join("\n")}\n${CONTEXT_WINDOW_CLOSE_TAG}`;
+}
+/**
+ * Recent-notes index: up to three most-recent fresh (non-stale) notes. Each note shows its
+ * path, line count, UTF-8 byte count and local ISO update time, followed by an indented inline
+ * preview: the whole text when it fits in NOTE_PREVIEW_CHARS, otherwise its first
+ * NOTE_PREVIEW_HEAD_CHARS and last NOTE_PREVIEW_TAIL_CHARS Unicode characters joined by an
+ * explicit ellipsis. The two slices never overlap, so the preview never duplicates head content
+ * as tail content. Stale notes are excluded entirely; empty when no fresh notes remain.
+ */
+function notesIndex(ctx) {
+    const sections = [];
+    // TOC residency ("地图在场"): the map, when present, is injected whole ahead of the list.
+    const toc = resolveNoteScope(ctx, "TOC.md");
+    if (toc) {
+        const body = peekNote(ctx, toc.scope, "TOC.md").body;
+        if (body.length > 0)
+            sections.push(body);
+    }
+    // listNotes is already most-recently-updated first; stale notes never reach the index.
+    const recentNotes = listNotes(ctx, {})
+        .filter((row) => !row.meta.stale)
+        .slice(0, 5);
+    if (recentNotes.length > 0) {
+        const lines = [`You find ${recentNotes.length} crumpled note${recentNotes.length === 1 ? "" : "s"} in your pocket (up to 5, most recent first):`];
+        for (const row of recentNotes) {
+            const body = peekNote(ctx, row.meta.scope, row.path).body;
+            lines.push(`- ${row.path} (${body.split("\n").length} lines, ${row.sizeBytes} UTF-8 bytes, updated ${localIso(row.meta.updated_at)})`);
+            const chars = Array.from(body);
+            // Short notes stay whole; long notes keep both ends. head + tail <= NOTE_PREVIEW_CHARS < chars.length,
+            // so the slices are disjoint and no character is shown twice.
+            const preview = chars.length <= NOTE_PREVIEW_CHARS
+                ? body
+                : `${chars.slice(0, NOTE_PREVIEW_HEAD_CHARS).join("")}…${chars.slice(chars.length - NOTE_PREVIEW_TAIL_CHARS).join("")}`;
+            lines.push(preview.split("\n").map((line) => `  ${line}`).join("\n"));
+        }
+        sections.push(lines.join("\n"));
+    }
+    return sections.join("\n\n");
+}
+/**
+ * Assemble the static, once-per-window boot block: the reset line for resets, the
+ * <context_window> identity block, the recent-notes index at window-open time, and
+ * the <context_window_protocol> teaching block. Nothing here is re-injected, so the
+ * head of the window stays cache-stable.
+ */
+export function bootBlock(ctx, currentId, previousId, resetLine) {
+    const firstId = historyFromSession(ctx)[0]?.windowId ?? currentId;
+    const parts = [];
+    if (resetLine)
+        parts.push(RESET_SUMMARY);
+    parts.push(identityBlock(ctx.sessionManager.getSessionName() ?? "root", firstId, currentId, previousId));
+    const index = notesIndex(ctx);
+    if (index)
+        parts.push(index);
+    parts.push(PROTOCOL_BLOCK);
+    return parts.join("\n\n");
+}
+/**
+ * Codex-equivalent low-budget reminder. The measured remaining count is frozen into
+ * the text at the crossing that fires it, so each persisted copy is a snapshot true
+ * at write time; get_context_remaining remains the live source for the current figure.
+ */
+export function tokenBudgetGuidance(remaining) {
+    return `${GUIDANCE_OPEN_TAG}\nYour brain is almost out of room — ${remaining} tokens left, and then your memory gets wiped. The wipe is automatic: there is no final turn to write then. Grab the notebook now — the goal, decisions, progress, learnings, next steps, the skills you still need, the window ID and item ID of every relevant user request still being solved, and important actions/tool calls for future reference. Replacing an older checkpoint? Mark it stale. Then end the window yourself — anything you do after the checkpoint isn't in it.\n${GUIDANCE_CLOSE_TAG}`;
+}