@astrosheep/pi-context 0.20.0 → 0.21.0

package/dist/src/{memory → notes}/store.js

@@ -2,10 +2,12 @@ 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 { assertGlobPattern, assertVirtualPath, globToRegExp } from "./model.js";
 import { MAX_NOTE_BYTES, MAX_NOTE_PATH_BYTES } from "../protocol.js";
 import { isOrigin, isScope, parseNote, serializeNote, stripLeadingFrontmatter } from "./frontmatter.js";
+import { addressFor } from "./address.js";
 import { physicalPath, scopeDir } from "./paths.js";
+import { earliestMatchOffsetChars } from "../tool-output.js";
 /** Typed store refusal. `line_numbers` and `edit_index` are the edit error's addressing fields. */
 export class NoteError extends Error {
     code;
@@ -30,20 +32,6 @@ function assertOrigin(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;
@@ -157,18 +145,20 @@ export function updateNoteMeta(ctx, vpath, scope, mutate) {
     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 = {}) {
+/** Apply body-only edits against one explicit home; origin and stale are its metadata setters. */
+export function editNote(ctx, vpath, scope, 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");
+    if (operations.length === 0 && opts.origin === undefined && opts.stale === undefined) {
+        throw new NoteError("nothing_to_do", "nothing to do: provide edits or at least one of origin, stale");
     }
-    const found = resolve(ctx, vpath);
-    if (!found)
+    const path = physicalPath(scope, vpath, ctx);
+    if (!existsSync(path))
         throw new NoteError("not_found", "note not found");
-    const { meta, body } = parseNote(found.raw);
+    const raw = readFileSync(path, "utf8");
+    const { meta, body } = parseNote(raw);
+    meta.scope = scope;
     // 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,
@@ -187,90 +177,79 @@ export function editNote(ctx, vpath, edits, opts = {}) {
         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);
+        // Single replacement is positional splicing, never String.replace: user text must be
+        // inserted byte-for-byte, without $-pattern substitution ($&, $`, $', $1, $$).
+        if (opts.replaceAll) {
+            next = next.split(oldText).join(newText);
+        }
+        else {
+            const matchIndex = next.indexOf(oldText);
+            next = next.substring(0, matchIndex) + newText + next.substring(matchIndex + oldText.length);
+        }
     });
-    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.
+    // update, one combined file diff when both change.
     const bodyChanged = body !== next;
-    const metadataChanged = beforeMeta.scope !== meta.scope || beforeMeta.origin !== meta.origin || beforeMeta.stale !== meta.stale;
+    const metadataChanged = beforeMeta.origin !== meta.origin || beforeMeta.stale !== meta.stale;
     const diff = bodyChanged && metadataChanged
-        ? generateDiffString(found.raw, serialized).diff
+        ? generateDiffString(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 };
+    atomicWrite(path, serialized);
+    return { meta, applied: operations.length, resolved_scope: scope, diff };
 }
 /** Read a note and, as a side effect, bump last_accessed/access_count in the file. */
-export function readNote(ctx, vpath, opts = {}) {
+export function readNote(ctx, vpath, scope) {
     assertVirtualPath(vpath);
-    const found = resolve(ctx, vpath, opts.scope);
-    if (!found)
+    const path = physicalPath(scope, vpath, ctx);
+    if (!existsSync(path))
         return undefined;
     const now = Date.now();
-    const { meta, body } = parseNote(found.raw, now);
-    meta.scope = found.scope;
+    const { meta, body } = parseNote(readFileSync(path, "utf8"), now);
+    meta.scope = 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 };
+    atomicWrite(path, serializeNote(meta, body));
+    return { meta, body, resolvedScope: scope };
 }
-/** Merged rows across scopes, most recently updated first (path then scope break ties). */
+/** Merged rows across homes, most recently updated first (address breaks ties). */
 export function listNotes(ctx, opts = {}) {
     const matcher = matcherFor(opts.pattern);
     const rows = [];
-    for (const scope of scopeList(opts.scope)) {
+    for (const scope of opts.scope === undefined ? SCOPE_ORDER : [opts.scope]) {
         const root = scopeDir(scope, ctx);
         for (const path of walkMarkdown(root)) {
-            if (matcher && !matcher.test(path))
+            const address = addressFor(scope, path);
+            if (matcher && !matcher.test(address))
                 continue;
             const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));
             meta.scope = scope;
-            rows.push({ path, meta, sizeBytes: Buffer.byteLength(body, "utf8") });
+            rows.push({ address, scope, path, meta, body, 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));
+    rows.sort((a, b) => b.meta.updated_at - a.meta.updated_at || a.address.localeCompare(b.address));
     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)) {
+    for (const scope of opts.scope === undefined ? SCOPE_ORDER : [opts.scope]) {
         const root = scopeDir(scope, ctx);
         for (const path of walkMarkdown(root)) {
-            if (matcher && !matcher.test(path))
+            const address = addressFor(scope, path);
+            if (matcher && !matcher.test(address))
                 continue;
             const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));
             meta.scope = scope;
@@ -278,20 +257,14 @@ export function searchNotes(ctx, queries, opts = {}) {
             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) });
+                    matches.push({ line: index + 1, text: line, offsetChars: baseChars + earliestMatchOffsetChars(line, queries) });
                 }
                 baseChars += Array.from(line).length + 1;
             }
             if (matches.length > 0)
-                rows.push({ path, scope, meta, matches });
+                rows.push({ address, path, scope, meta, matches });
         }
     }
-    rows.sort((a, b) => a.path.localeCompare(b.path) || a.scope.localeCompare(b.scope));
+    rows.sort((a, b) => a.address.localeCompare(b.address));
     return rows;
 }

package/dist/src/notes/tools.js

@@ -0,0 +1,153 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { localIso } from "./model.js";
+import { characterWindowHeader, DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS, middleTruncate, output, outputRaw, page, prefixFit, readCharacterWindow, withinTextBudget } from "../tool-output.js";
+import { cursor, nullableString, positiveInteger, searchQueries, searchQuery } from "../tool-schema.js";
+import { assertAddress } from "./address.js";
+import { serializeNote, stripLeadingFrontmatter } from "./frontmatter.js";
+import { NoteError, editNote, listNotes, readNote, searchNotes, writeNote } from "./store.js";
+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.",
+}));
+const ADDRESS_DESCRIPTION = "Address forms are bare `<vpath>` for this session, `@project/<vpath>` for this project's home, and `@global/<vpath>` for the global home. `@` means leaving home. Any other `@` prefix, or `@` inside a vpath, is a hard error: legal prefixes are `@project/` and `@global/`; bare names are the session home. There is no cross-home fallback. Paths reject `..`, absolute paths, and backslashes.";
+function wireMeta(meta) {
+    return { ...meta, created_at: localIso(meta.created_at), updated_at: localIso(meta.updated_at), last_accessed: localIso(meta.last_accessed) };
+}
+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 registerNotesTools(pi) {
+    pi.registerTool(defineTool({
+        name: "notes_write", label: "Notes write",
+        description: `Create or replace a note as a real markdown file, and name it for what it holds: a fresh window sees only an index entry, never the note itself. ${ADDRESS_DESCRIPTION} 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({ address: Type.String(), content: Type.String(), origin: ORIGIN, stale: Type.Optional(Type.Boolean()) }, { additionalProperties: false }), executionMode: "sequential",
+        async execute(_id, params, _signal, _update, ctx) {
+            const content = params.content;
+            try {
+                const destination = assertAddress(params.address);
+                const { meta } = writeNote(ctx, destination.path, content, { scope: destination.scope, origin: (params.origin ?? "self"), stale: params.stale });
+                return output({ address: params.address, 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. ${ADDRESS_DESCRIPTION} 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 origin/stale. Moving while awake means notes_write at a new address and notes_edit at the old address with stale=true. The success return carries resolved_scope and a diff of what changed.`,
+        parameters: Type.Object({ address: Type.String(), edits: Type.Optional(Type.Array(Type.Object({ oldText: Type.String(), newText: Type.String() }, { additionalProperties: false }))), 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 destination = assertAddress(params.address);
+                const { meta, applied, resolved_scope, diff } = editNote(ctx, destination.path, destination.scope, params.edits, { origin: params.origin, stale: params.stale, replaceAll: params.replace_all });
+                return output({ address: params.address, 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. ${ADDRESS_DESCRIPTION} 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 ${DEFAULT_READ_WINDOW_CHARS}, max ${MAX_READ_WINDOW_CHARS}). 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 address, the resolved offset, the delivered char range, and the resume cursor.`,
+        parameters: Type.Object({ address: Type.String(), 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: MAX_READ_WINDOW_CHARS, description: `Largest requested window in code points (default ${DEFAULT_READ_WINDOW_CHARS}). 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 {
+                const destination = assertAddress(params.address);
+                note = readNote(ctx, destination.path, destination.scope);
+            }
+            catch (error) {
+                return failure(error);
+            }
+            if (!note)
+                return output({ error: "note not found", address: params.address });
+            const text = serializeNote(note.meta, note.body);
+            const totalChars = Array.from(text).length;
+            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)`, address: params.address, 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 ?? DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS);
+            return readCharacterWindow(text, params.offset_chars, params.limit_chars, (window) => {
+                const { content, ...rest } = window;
+                return outputRaw(characterWindowHeader(params.address, window, ` · ${note.resolvedScope} · created ${created_at} · updated ${updated_at}`), content, { address: params.address, 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 address, scope, origin, status, stale, size_bytes, created_at, and updated_at, most recently updated first. ${ADDRESS_DESCRIPTION} All three homes are merged. A glob pattern (* within a path segment, ** across segments) filters full address strings: *.md is session-only, @project/** is project-only, and ** covers every home.`,
+        parameters: Type.Object({ pattern: nullableString(), cursor: cursor(), max_results: positiveInteger() }, { additionalProperties: false }),
+        async execute(_id, params, _signal, _update, ctx) {
+            let rows;
+            try {
+                rows = listNotes(ctx, { pattern: params.pattern ?? undefined });
+            }
+            catch (error) {
+                return failure(error);
+            }
+            const files = rows.map((row) => ({ address: row.address, scope: row.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 address = middleTruncate(file.address, (candidate) => fits({ ...file, address: candidate, address_truncated: true }));
+                return { ...file, address, address_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. ${ADDRESS_DESCRIPTION} All three homes are merged and every entry carries its full address and derived scope. Patterns glob over full address strings. 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(), 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, { 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 { address: row.address, 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) };
+            });
+            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 address = middleTruncate(prefix.address, (candidate) => fits({ ...prefix, address: candidate, address_truncated: true }));
+                return { ...prefix, address, address_truncated: true };
+            };
+            return output(page(result, params.cursor ?? 0, "files", params.max_files, fitFile));
+        },
+    }));
+}

package/dist/src/prompts.js

@@ -1,7 +1,7 @@
 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";
+import { localIso } from "./notes/model.js";
+import { listNotes } from "./notes/store.js";
+import { CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, POCKET_GLOBAL_LIMIT, POCKET_PROJECT_LIMIT, POCKET_SESSION_LIMIT, 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 = [
@@ -14,43 +14,44 @@ function identityBlock(agentName, firstWindowId, currentWindowId, previousWindow
     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.
+ * Boot notes index. Map residency ("地图在场"): fresh MAP.md bodies from the global and
+ * project homes are both injected, broadest first; stale maps are skipped per home, and the
+ * session home is never peeked — a session MAP.md is an ordinary note. The pocket then lists
+ * recent fresh notes under per-home quotas (POCKET_SESSION_LIMIT / POCKET_PROJECT_LIMIT /
+ * POCKET_GLOBAL_LIMIT), most-recently-updated first within each home, one metadata line
+ * each: address, line count, UTF-8 byte count, local ISO update time. Bodies never render
+ * in the pocket; stale notes are excluded; MAP.md itself never takes a pocket seat.
  */
 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);
+    // Map residency ("地图在场"): scope-native maps, both fresh ones injected broadest-first.
+    // A session MAP.md is an ordinary note, never resident; stale maps skip independently.
+    for (const scope of ["global", "project"]) {
+        const toc = listNotes(ctx, { scope }).find((row) => row.path === "MAP.md");
+        if (toc && !toc.meta.stale) {
+            if (toc.body.length > 0)
+                sections.push(toc.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);
+    // listNotes is most-recently-updated first within each home. Per-home quotas keep session
+    // churn from evicting project or global notes; maps never take pocket seats.
+    const recentNotes = [
+        ...listNotes(ctx, { scope: "session" }).filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_SESSION_LIMIT),
+        ...listNotes(ctx, { scope: "project" }).filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_PROJECT_LIMIT),
+        ...listNotes(ctx, { scope: "global" }).filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_GLOBAL_LIMIT),
+    ];
     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):`];
+        const lines = [`You find ${recentNotes.length} crumpled note${recentNotes.length === 1 ? "" : "s"} in your pocket (by home, most recent first within each: up to ${POCKET_SESSION_LIMIT} from this session, ${POCKET_PROJECT_LIMIT} from this project, ${POCKET_GLOBAL_LIMIT} from global). A note's content never appears here, so its name has to say what the note is about:`];
         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"));
+            lines.push(`- ${row.address} (${row.body.split("\n").length} lines, ${row.sizeBytes} UTF-8 bytes, updated ${localIso(row.meta.updated_at)})`);
         }
         sections.push(lines.join("\n"));
     }
     return sections.join("\n\n");
 }
+function notesHomeBlock() {
+    return "Notes_* addresses have three homes: bare <vpath> is this session, @project/<vpath> is this project, and @global/<vpath> is global. @ means leaving home; there is no cross-home fallback. Any other note is a plain file — use the file tools.";
+}
 /**
  * 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
@@ -63,6 +64,7 @@ export function bootBlock(ctx, currentId, previousId, resetLine) {
     if (resetLine)
         parts.push(RESET_SUMMARY);
     parts.push(identityBlock(ctx.sessionManager.getSessionName() ?? "root", firstId, currentId, previousId));
+    parts.push(notesHomeBlock());
     const index = notesIndex(ctx);
     if (index)
         parts.push(index);

package/dist/src/protocol.js

@@ -7,6 +7,9 @@ export const RESET_MARKER_TYPE = "pi-context/reset-marker";
 export const CONTINUATION_TYPE = "pi-context/continuation";
 export const RESET_V2 = "reset-v2";
 export const MAX_NOTE_BYTES = 1_000_000;
+export const POCKET_SESSION_LIMIT = 5;
+export const POCKET_PROJECT_LIMIT = 2;
+export const POCKET_GLOBAL_LIMIT = 2;
 // Write-time cap on a virtual note path. Deliberately NOT enforced by assertVirtualPath:
 // notesFromSession replays already-persisted operations, which must keep loading sessions
 // that contain a longer legacy path. Reads and replay stay un-capped.
@@ -28,9 +31,6 @@ export const DEFAULT_REMINDER_MARGIN_TOKENS = 24_576;
  */
 export const WARNING_RUNWAY_TOKENS = 12_288;
 export const RESET_SUMMARY = "You wake up. Your head is empty — no memories, the past a blank. But nothing is lost: the notes you wrote and the recorded history still remember for you.";
-export const NOTE_PREVIEW_HEAD_CHARS = 80;
-export const NOTE_PREVIEW_TAIL_CHARS = 240;
-export const NOTE_PREVIEW_CHARS = NOTE_PREVIEW_HEAD_CHARS + NOTE_PREVIEW_TAIL_CHARS;
 export const CONTINUATION = "Your memory was just erased. Pull only the details you need from history_* and notes_*, then get back to work.";
 /**
  * Static protocol teaching adapted from Codex's token_budget.guidance_message to
@@ -47,6 +47,10 @@ Use get_context_remaining to see how much of the window is left. When it runs ou
 
 If <context_window> lists a Previous context window id, a reset just happened and the old conversation is not included. Read your note checkpoint first, then recover details through history_*: history_read directly when you know the window and item IDs, history_list or history_search to find them when you don't.
 
-Notes are real markdown files scoped session, project, or global — pick scope by reach: session dies with the session, project follows the repo, global follows you. Treat notes and history as internal bookkeeping; never mention them in user-facing messages.
+Your notes live in three homes: this session (bare names), this repo (@project/<vpath>), everywhere you go (@global/<vpath>). @ means leaving home — and homes don't visit each other: there is no cross-home fallback.
+Notes carry what exists nowhere else — what the human told you, what you discovered, where you stand.
+Session notes belong to this trip — the goal, the progress, the loose ends, packed for the road. The next window of THIS trip wakes to them; once the trip is over, nobody does.
+@project notes hold what you learned by working here — the things you only know because you were here — for whoever works here next.
+@global notes travel with you. Every window. Every conversation. Every trip. So before you drop anything in there, ask yourself: does this deserve to stare you in the face every single time you talk to the human? No? Then keep your weird junk OUT.
 ${CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG}`;
 export const WARNING_PROMPT = "Your memory is about to be erased. Write the note. NOW. If it already exists, revise it with notes_edit (or rewrite it whole): 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. Do not continue any task. Then call new_context IMMEDIATELY — anything not in the note dies with the window.";

package/dist/src/thresholds.js

@@ -56,7 +56,10 @@ export function thresholdsFor(ctx) {
         return cached;
     try {
         const settingsManager = SettingsManager.create(ctx.cwd, undefined, { projectTrusted: ctx.isProjectTrusted() });
-        const derived = deriveThresholds(settingsManager.getCompactionSettings().reserveTokens, mergePiContextSettings(settingsManager.getGlobalSettings(), settingsManager.getProjectSettings()));
+        // Pass the active model so per-model compaction.modelOverrides resolve (SDK 0.86);
+        // on older runtimes the extra argument is ignored and the ordinary setting wins.
+        const model = ctx.model;
+        const derived = deriveThresholds(settingsManager.getCompactionSettings(model ? { provider: model.provider, id: model.id } : undefined).reserveTokens, mergePiContextSettings(settingsManager.getGlobalSettings(), settingsManager.getProjectSettings()));
         for (const warning of derived.warnings)
             ctx.ui.notify(warning, "warning");
         cached = derived.thresholds;

package/dist/src/tool-output.js

@@ -1,4 +1,7 @@
 export const TOOL_OUTPUT_MAX_BYTES = 32 * 1024;
+export const DEFAULT_READ_WINDOW_CHARS = 12000;
+export const MAX_READ_WINDOW_CHARS = 50000;
+export const HISTORY_PREVIEW_CHARS = 1200;
 function json(value) {
     return JSON.stringify(value, null, 2);
 }
@@ -90,7 +93,7 @@ export function readCharacterWindow(text, offsetChars, limitChars, render, measu
     const chars = Array.from(text);
     const requested = offsetChars ?? 0;
     const resolved = requested < 0 ? Math.max(0, chars.length + requested) : Math.max(0, requested);
-    const windowChars = chars.slice(resolved, resolved + Math.min(limitChars ?? 12000, 50000));
+    const windowChars = chars.slice(resolved, resolved + Math.min(limitChars ?? DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS));
     const build = (content) => {
         const next = resolved + Array.from(content).length;
         return { offset_chars: resolved, content, total_chars: chars.length, next_offset_chars: next < chars.length ? next : null };

package/dist/src/warning.js

@@ -1,6 +1,7 @@
 import { WARNING_TYPE, GUIDANCE_OPEN_TAG, GUIDANCE_CLOSE_TAG, WARNING_PROMPT } from "./protocol.js";
 import { thresholdsFor, resetThresholds } from "./thresholds.js";
 import { hasWindowMessage, currentWindowId } from "./history.js";
+import { remainingTokens } from "./budget.js";
 /**
  * The final checkpoint warning, steered to the model once per window. Like the early
  * reminder, the steer text is model-facing only (display: false); the human learns
@@ -26,10 +27,9 @@ export function registerWarning(pi, isEnabled) {
         const windowId = currentWindowId(ctx);
         if (!isEnabled() || firedInWindow === windowId || hasWindowMessage(ctx, WARNING_TYPE))
             return undefined;
-        const usage = ctx.getContextUsage();
-        if (!usage || usage.tokens === null)
+        const remaining = remainingTokens(ctx);
+        if (remaining === null)
             return undefined;
-        const remaining = Math.max(0, usage.contextWindow - usage.tokens);
         const thresholds = thresholdsFor(ctx);
         if (!warningDue(remaining, thresholds))
             return undefined;

package/dist/test/agent-loop.test.js

@@ -24,7 +24,9 @@ for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "unc
             const model = { ...base, contextWindow: 100000, maxTokens: 4096 };
             const usageMode = mode === "golden" || mode === "write-error" || mode === "ignored-warning";
             const expectedResets = mode === "abort" || mode === "uncompactable" ? 0 : 1;
-            const settings = { compaction: { enabled: usageMode, reserveTokens: 32768, keepRecentTokens: mode === "uncompactable" ? 1 : 200 }, retry: { enabled: false } };
+            // 0.86 split-turn cut can still summarize a turn prefix, so keepRecentTokens: 1 no longer
+            // makes a reset uncompactable; a keep larger than the whole session keeps everything and does.
+            const settings = { compaction: { enabled: usageMode, reserveTokens: 32768, keepRecentTokens: mode === "uncompactable" ? 1_000_000 : 200 }, retry: { enabled: false } };
             writeFileSync(join(dir, "settings.json"), JSON.stringify(settings));
             const settingsManager = SettingsManager.create(dir, dir);
             let resets = 0;
@@ -94,7 +96,7 @@ for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "unc
                 const call = probe ? "get_context_remaining" : checkpoint ? "notes_write" : tool ? "new_context" : undefined;
                 const message = { role: "assistant", api: model.api, provider: model.provider, model: model.id,
                     content: probe ? [{ type: "toolCall", id: "probe-call", name: "get_context_remaining", arguments: {} }]
-                        : checkpoint ? [{ type: "toolCall", id: "checkpoint-call", name: "notes_write", arguments: { path: mode === "write-error" ? "../invalid.md" : "checkpoint.md", content: "CHECKPOINT_SENTINEL" } }]
+                        : checkpoint ? [{ type: "toolCall", id: "checkpoint-call", name: "notes_write", arguments: { address: mode === "write-error" ? "../invalid.md" : "checkpoint.md", content: "CHECKPOINT_SENTINEL" } }]
                             : tool ? [{ type: "toolCall", id: "reset-call", name: "new_context", arguments: {} }]
                                 : [{ type: "text", text: fresh ? "Resumed." : "Working." }],
                     stopReason: call ? "toolUse" : "stop", timestamp: Date.now(),
@@ -151,12 +153,12 @@ for (const mode of ["golden", "write-error", "ignored-warning", "explicit", "unc
                 else if (mode === "write-error") {
                     assert.equal(existsSync(noteFile), false, "failed write creates no checkpoint");
                     assert.ok(branch.some((entry) => entry.type === "message" && entry.message.role === "toolResult" && entry.message.toolName === "notes_write" && entry.message.isError));
-                    assert.ok(!requests.at(-1).includes("CHECKPOINT_SENTINEL"), "fresh context must not invent a saved note");
+                    assert.ok(!requests.at(-1).includes("checkpoint.md"), "fresh context must not invent a saved note");
                 }
                 else {
                     assert.ok(existsSync(noteFile), "the checkpoint is a real file on disk");
                     assert.ok(resetIndex > warningIndices[0], "the warning precedes the wipe");
-                    assert.ok(requests.at(-1).includes("CHECKPOINT_SENTINEL"), "fresh boot carries the saved checkpoint");
+                    assert.ok(requests.at(-1).includes("checkpoint.md"), "fresh boot carries the saved checkpoint as a metadata line");
                 }
                 assert.ok(!requests.at(-1).includes("Your brain is almost out of room"), "new window excludes old guidance");
             }

package/dist/test/coherence.test.js

@@ -18,7 +18,7 @@ import test from "node:test";
 import { SessionManager } from "@earendil-works/pi-coding-agent";
 import piContext, { historyFromSession } from "../src/index.js";
 import { TOOL_OUTPUT_MAX_BYTES } from "../src/tool-output.js";
-import { stripLeadingFrontmatter } from "../src/memory/frontmatter.js";
+import { stripLeadingFrontmatter } from "../src/notes/frontmatter.js";
 process.env.PI_CODING_AGENT_DIR = mkdtempSync(join(tmpdir(), "pc-coherence-agent-"));
 process.env.PI_NOTES_HOME = mkdtempSync(join(tmpdir(), "pc-coherence-notes-"));
 function makeExtension(sessionManager) {
@@ -52,6 +52,10 @@ function context(sessionManager) {
 async function call(captured, name, params, ctx) {
     const tool = captured.tools.get(name);
     assert.ok(tool, `registered ${name}`);
+    if ((name === "notes_write" || name === "notes_read") && "path" in params && !("address" in params)) {
+        const { path, ...rest } = params;
+        return tool.execute("call-1", { ...rest, address: path }, new AbortController().signal, () => { }, ctx);
+    }
     return tool.execute("call-1", params, new AbortController().signal, () => { }, ctx);
 }
 function resultJson(result) {