@astrosheep/pi-context 0.20.0 → 0.22.0

package/dist/src/prompts.js

@@ -1,7 +1,6 @@
 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 { listNotes } from "./notes/store.js";
+import { CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, POCKET_PERSONAL_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 = [
@@ -13,44 +12,53 @@ function identityBlock(agentName, firstWindowId, currentWindowId, previousWindow
         lines.push(`Previous context window id: ${previousWindowId}`);
     return `${CONTEXT_WINDOW_OPEN_TAG}\n${lines.join("\n")}\n${CONTEXT_WINDOW_CLOSE_TAG}`;
 }
+function relativeTime(timestamp, now) {
+    const seconds = Math.trunc((timestamp - now) / 1000);
+    const [unit, size] = [["d", 86400], ["h", 3600], ["m", 60], ["s", 1]]
+        .find(([unit, size]) => Math.abs(seconds) >= size || unit === "s");
+    const amount = `${Math.abs(Math.trunc(seconds / size))}${unit}`;
+    return seconds > 0 ? `in ${amount}` : `${amount} ago`;
+}
 /**
- * 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 personal 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_PERSONAL_LIMIT), most-recently-updated first within each home, one metadata line
+ * each: address, line count, UTF-8 byte count, relative update time at window open. 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 ["personal", "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 personal 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: "personal" }).filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_PERSONAL_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_PERSONAL_LIMIT} from personal). A note's content never appears here, so its name has to say what the note is about:`];
+        const now = Date.now();
         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 ${relativeTime(row.meta.updated_at, now)})`);
         }
         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 @personal/<vpath> is the human's cross-project home. @ 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 +71,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_PERSONAL_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.
@@ -18,6 +21,8 @@ export const CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG = "</context_window_protocol>";
 export const GUIDANCE_OPEN_TAG = "<context_window_guidance>";
 export const GUIDANCE_CLOSE_TAG = "</context_window_guidance>";
 export const PI_CONTEXT_SETTINGS_KEY = "pi-context";
+/** Nested under "pi-context": the default dreamer model pattern, overridden by CLI --dreamer. */
+export const PI_CONTEXT_DREAMER_KEY = "dreamer";
 export const DEFAULT_RESERVE_TOKENS = 16_384;
 export const DEFAULT_REMINDER_MARGIN_TOKENS = 24_576;
 /**
@@ -28,9 +33,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 +49,9 @@ 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 project (@project/<vpath>), the human across projects (@personal/<vpath>). @ means leaving home — and homes don't visit each other: there is no cross-home fallback.
+Session notes belong to this trip — the goal, the progress, the loose ends. The next window of THIS trip wakes to them; once the trip is over, nobody does.
+@project notes hold facts about this project — architecture, conventions, workflows, deployment and environment details — for whoever works here next.
+@personal notes hold the human's durable preferences and standing rules, plus lessons that apply across projects. Duration does not make a note personal; its stated scope must already be broader than the project or conversation at hand. When the intended scope is unclear, keep the note in the narrowest stated scope rather than widening it.
 ${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

@@ -1,5 +1,5 @@
 import { SettingsManager } from "@earendil-works/pi-coding-agent";
-import { PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, WARNING_RUNWAY_TOKENS } from "./protocol.js";
+import { PI_CONTEXT_SETTINGS_KEY, PI_CONTEXT_DREAMER_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, WARNING_RUNWAY_TOKENS } from "./protocol.js";
 function isSettingsObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -13,7 +13,7 @@ function piContextSettings(settings) {
 /** Merge the global and project "pi-context" objects per key; project wins, mirroring Pi's deep merge. */
 export function mergePiContextSettings(globalSettings, projectSettings) {
     const merged = { ...piContextSettings(globalSettings), ...piContextSettings(projectSettings) };
-    return { reminderMarginTokens: merged.reminderMarginTokens };
+    return { reminderMarginTokens: merged.reminderMarginTokens, dreamer: merged.dreamer };
 }
 /** A margin is usable only as a positive integer; anything else is ignored. */
 function validMargin(raw) {
@@ -44,6 +44,33 @@ export function deriveThresholds(reserveTokens, margins) {
     }
     return { thresholds: { reminder: reserveTokens + reminderMargin, reserve: reserveTokens, warning: reserveTokens + WARNING_RUNWAY_TOKENS }, warnings };
 }
+/**
+ * `pi-context.dreamer` is a non-empty model pattern. Anything else present is ignored
+ * with one warning; absent means no configured pattern, so the automatic model applies.
+ */
+export function deriveDreamer(settings) {
+    const raw = settings.dreamer;
+    if (raw === undefined)
+        return { warnings: [] };
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+        return { warnings: [`pi-context: ${PI_CONTEXT_SETTINGS_KEY}.${PI_CONTEXT_DREAMER_KEY} must be a non-empty string; ignoring it.`] };
+    }
+    return { pattern: raw.trim(), warnings: [] };
+}
+/**
+ * Resolve the configurable dreamer model from Pi settings for a CLI invocation: global
+ * `~/.pi/agent/settings.json` merged with the project's `.pi/settings.json`, project
+ * values winning per key. A settings read failure degrades to no pattern with one warning.
+ */
+export function readDreamerSettings(cwd = process.cwd()) {
+    try {
+        const settingsManager = SettingsManager.create(cwd, undefined, { projectTrusted: true });
+        return deriveDreamer(mergePiContextSettings(settingsManager.getGlobalSettings(), settingsManager.getProjectSettings()));
+    }
+    catch (error) {
+        return { warnings: [`pi-context: could not read settings; using the automatic dreamer model (${String(error)}).`] };
+    }
+}
 let cached;
 /**
  * Session-level threshold resolution: Pi's compaction reserve plus the settings.json
@@ -56,7 +83,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) {