@astrosheep/pi-context 0.19.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/pi-context",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "type": "module",
   "description": "Codex-style context windows for Pi: reset-style compaction, durable session history tools, and persistent notes.",
   "license": "MIT",
@@ -20,15 +20,21 @@
   },
   "files": [
     "src",
+    "dist",
     "docs",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "playbook.md"
   ],
+  "bin": {
+    "dream": "dist/src/dream/cli.js"
+  },
   "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && node -e \"require('node:fs').chmodSync('dist/src/dream/cli.js', 0o755)\"",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && node --test dist/test/*.test.js",
-    "prepublishOnly": "npm run typecheck"
+    "prepublishOnly": "npm run typecheck",
+    "prepack": "npm run build"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
@@ -36,9 +42,9 @@
     "@earendil-works/pi-coding-agent": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.85.1",
-    "@earendil-works/pi-ai": "^0.85.1",
-    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@earendil-works/pi-agent-core": "^0.86.0",
+    "@earendil-works/pi-ai": "^0.86.0",
+    "@earendil-works/pi-coding-agent": "^0.86.0",
     "@types/node": "^22.19.19",
     "typescript": "^5.9.3"
   },

package/playbook.md

@@ -0,0 +1,32 @@
+I am dreaming over my notes. They are plain markdown files in three homes, addressed as:
+
+- bare `<vpath>` for this session
+- `@project/<vpath>` for this project
+- `@global/<vpath>` for global notes
+
+Every note has this frontmatter block:
+
+```yaml
+---
+origin: user | self | external
+status: active
+stale: false
+created_at: <timestamp>
+updated_at: <timestamp>
+last_accessed: <timestamp>
+access_count: 0
+---
+```
+
+## Dream rules
+
+1. **Probe before you trust.** Before keeping or promoting a note, verify its world referents with read-only file tools: paths in the body — do they still exist? branches — still present? Dead referents are why a note gets merged away or marked stale, never promoted.
+2. **Merge threshold.** Supersede another note only when all three hold: same topic (name it in the survivor's body), same kind of note (checkpoint/design/log…), and the survivor is strictly newer or strictly more specific. Otherwise keep both and record the open conflict in the survivor.
+3. **Size budget.** Keep every note under ~200 lines / ~8KB. Oversized notes get split by topic with a one-line cross-link in each (`see also: @home/<vpath>`). Checkpoints may exceed the budget — trim prose, never facts.
+4. **Keep the maps.** Each home's `MAP.md` maps that home's durable notes: one line per entry — its address and a short gist in your own words, never a mechanical body slice. Project notes go on `@project/MAP.md`, cross-project knowledge on `@global/MAP.md`; session notes are never mapped — the pocket covers them. When a note is promoted across homes, move its line to the destination map; when a note goes stale, drop its line. Maps obey the same size budget as any note.
+5. **Jurisdiction.** Your mandate is the whole store — every session home, every project home, global. Nothing is skipped: notes are never physically deleted and every run is bracketed by git commits, so the human gate can audit and revert whatever you touch. Group your report by home so the gate can see what moved. In every home: map entry lines are yours to maintain, but prose that carries rules or guidance is not — flag it in your report instead of rewriting it.
+6. **Leave stable notes alone.** Change notes to incorporate new evidence, resolve verified errors, merge genuine duplicates, or split oversized files—not merely to shorten or rephrase them. Preserve facts, conditions, exceptions, and uncertainty. No change is a valid outcome.
+
+Read the files and merge genuinely duplicate notes by editing the survivor, then set `stale: true` in the absorbed note's frontmatter. Nothing is physically deleted; stale notes remain readable. Promote durable cross-project knowledge by writing or editing at `@global/<vpath>`. Keep notes compact and preserve useful provenance in the body.
+
+Do not write skill ideas as files. Put skill ideas and unresolved questions in your final assistant message as proposals for the human. Your final message should be a concise report of what you inspected, changed, and left unresolved. If you made no file writes, say so.

package/src/budget.ts

@@ -1,12 +1,16 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { GUIDANCE_TYPE, WARNING_TYPE } from "./protocol.js";
-import { thresholdsFor, resetThresholds, deriveThresholds, mergePiContextSettings } from "./thresholds.js";
+import { thresholdsFor, resetThresholds } from "./thresholds.js";
 import { currentWindowId, hasWindowMessage } from "./history.js";
 import { tokenBudgetGuidance } from "./prompts.js";
 import { output } from "./tool-output.js";
 
-export { deriveThresholds, mergePiContextSettings } from "./thresholds.js";
+/** Remaining tokens in the current context window, or null when Pi has no usage estimate. */
+export function remainingTokens(ctx: Pick<ExtensionContext, "getContextUsage">): number | null {
+	const usage = ctx.getContextUsage();
+	return !usage || usage.tokens === null ? null : Math.max(0, usage.contextWindow - usage.tokens);
+}
 
 export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean) {
 	let guidancePersistedInWindow: string | undefined;
@@ -17,16 +21,15 @@ export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean) {
 		if (!isEnabled() || hasWindowMessage(ctx, GUIDANCE_TYPE)) return undefined;
 		// The early reminder persists once per window the first time remaining crosses
 		// reserve+margin. It never edits the outgoing request.
-		const usage = ctx.getContextUsage();
-		if (!usage || usage.tokens === null) return undefined;
-		const remaining = Math.max(0, usage.contextWindow - usage.tokens);
+		const remaining = remainingTokens(ctx);
+		if (remaining === null) return undefined;
 		const windowId = currentWindowId(ctx);
 		const { reminder, reserve, warning } = thresholdsFor(ctx);
 		// The final warning owns the deep band: when it has fired (or is due now),
 		// the shallow reminder would only repeat the same instruction closer to
 		// the wipe, at a worse position. See warning.ts.
 		if (remaining <= warning || hasWindowMessage(ctx, WARNING_TYPE)) return undefined;
-		if (remaining <= reminder && guidancePersistedInWindow !== windowId && !hasWindowMessage(ctx, GUIDANCE_TYPE)) {
+		if (remaining <= reminder && guidancePersistedInWindow !== windowId) {
 			guidancePersistedInWindow = windowId;
 			// Persist once per window — no transient copy. A transient bridge would
 			// cover the crossing request, but history would record the reminder after
@@ -54,11 +57,10 @@ export function registerBudget(pi: ExtensionAPI, isEnabled: () => boolean) {
 		description: "Return estimated context tokens left before your memory is wiped; null when Pi cannot estimate usage.",
 		parameters: Type.Object({}, { additionalProperties: false }),
 		async execute(_id, _params, _signal, _update, ctx) {
-			const usage = ctx.getContextUsage();
 			// The countdown the model sees ends at the warning line (reserve + runway);
 			// the runway below it is overdraft the model never sees. See protocol.ts.
-			const remaining = usage?.tokens === null || usage === undefined ? null : Math.max(0, usage.contextWindow - usage.tokens - thresholdsFor(ctx as ExtensionContext).warning);
-			return output({ remaining_tokens: remaining });
+			const remaining = remainingTokens(ctx);
+			return output({ remaining_tokens: remaining === null ? null : Math.max(0, remaining - thresholdsFor(ctx as ExtensionContext).warning) });
 		},
 	}));
 

package/src/dream/cli.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { acquireLock, failLock, releaseLock } from "./lock.js";
+import { materialGate, timeGate } from "./gates.js";
+import { loadPlaybook, runDreamer } from "./runner.js";
+import { gitCommit } from "./git.js";
+import { notesRoot } from "../notes/paths.js";
+
+function args(argv: string[]) { const out: Record<string, string | boolean> = {}; for (let i=0;i<argv.length;i++) { const a=argv[i]!; if (a === "--force" || a === "--help") out[a.slice(2)] = true; else if (a.startsWith("--")) out[a.slice(2)] = argv[++i] ?? ""; } return out; }
+function packageRoot(): string {
+	let dir = dirname(new URL(import.meta.url).pathname);
+	while (true) { if (existsSync(join(dir, "package.json"))) return dir; const parent = dirname(dir); if (parent === dir) throw new Error("could not locate installed package root"); dir = parent; }
+}
+
+export async function main(argv = process.argv.slice(2)): Promise<number> {
+	const a = args(argv); if (a.help) { console.log("dream --notes-home <dir> [--min-hours 24] [--min-sessions 3] [--force] [--dreamer <model pattern>] [--playbook <path>]\nDefault dreamer: in-process pi SDK session with jailed file tools. Default playbook: <installed package root>/playbook.md; --playbook overrides it."); return 0; }
+	const home = resolve(String(a["notes-home"] ?? notesRoot())); process.env.PI_NOTES_HOME = home; mkdirSync(home, { recursive: true });
+	const lockPath = join(home, ".dream.lock"); const minHours = Number(a["min-hours"] ?? 24); const minSessions = Number(a["min-sessions"] ?? 3);
+	const time = timeGate(lockPath, minHours); console.log(time.reason); if (!a.force && !time.ok) return 0;
+	const material = materialGate(home, existsSync(lockPath) ? statSync(lockPath).mtimeMs : 0, minSessions); console.log(material.reason); if (!a.force && !material.ok) return 0;
+	let lock; try { lock = acquireLock(lockPath); } catch (e) { console.log(`lock gate: ${e instanceof Error ? e.message : e}`); return 0; } if (!lock.held) { console.log(lock.reason); return 0; }
+	const stamp = new Date(lock.startedAt).toISOString().replace(/[:.]/g, "-"); const reportPath = join(home, "dreams", `${stamp}.md`);
+	gitCommit(home, `baseline ${stamp}`);
+	try {
+		const defaultBook = join(packageRoot(), "playbook.md");
+		const playbookPath = String(a.playbook ?? defaultBook);
+		const playbook = loadPlaybook(playbookPath); const result = await runDreamer(playbook, home, { modelPattern: a.dreamer ? String(a.dreamer) : undefined });
+		const writes = result.writes.length ? result.writes.map((w) => `- ${w.tool}: ${w.path}`).join("\n") : "- no changes";
+		mkdirSync(join(home, "dreams"), { recursive: true }); writeFileSync(reportPath, `# Dream ${stamp}\n\n${result.report}\n\n${writes}\n`); gitCommit(home, `dream ${stamp}`); console.log(reportPath); return 0;
+	} catch (e) { failLock(lock); console.error(e instanceof Error ? e.message : e); return 1; } finally { releaseLock(lock); }
+}
+main().then((code) => { process.exitCode = code; });

package/src/dream/gates.ts

@@ -0,0 +1,20 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { sessionHomesRoot } from "../notes/paths.js";
+
+export type GateResult = { ok: boolean; reason: string };
+export function timeGate(lockPath: string, minHours: number, now = Date.now()): GateResult {
+	if (!existsSync(lockPath)) return { ok: true, reason: "time gate: no prior lock" };
+	const age = now - statSync(lockPath).mtimeMs;
+	return age >= minHours * 3600000 ? { ok: true, reason: "time gate: stale" } : { ok: false, reason: "time gate: lock is too fresh" };
+}
+export function materialGate(home: string, lockMtime: number, minSessions: number): GateResult {
+	const root = sessionHomesRoot(home);
+	let changed = 0;
+	if (existsSync(root)) for (const dir of readdirSync(root, { withFileTypes: true })) {
+		if (!dir.isDirectory()) continue;
+		const files = readdirSync(join(root, dir.name), { withFileTypes: true });
+		if (files.some((f) => f.isFile() && statSync(join(root, dir.name, f.name)).mtimeMs > lockMtime)) changed++;
+	}
+	return changed >= minSessions ? { ok: true, reason: `material gate: ${changed} changed sessions` } : { ok: false, reason: `material gate: only ${changed} changed sessions` };
+}

package/src/dream/git.ts

@@ -0,0 +1,27 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Git audit layer for a dream run: one commit before (baseline) and one after
+ * (dream), so the human gate reviews `git show` instead of trusting a report,
+ * and rollback is `git revert`. This layer is a garnish, never load-bearing:
+ * every failure is logged and swallowed — a notes home without git, or a
+ * broken repo, still dreams. Nothing is committed when the tree is clean.
+ */
+export function gitCommit(home: string, message: string): void {
+	try {
+		if (!existsSync(join(home, ".git"))) {
+			execFileSync("git", ["init", "-q"], { cwd: home, stdio: "ignore" });
+		}
+		execFileSync("git", ["add", "-A"], { cwd: home, stdio: "ignore" });
+		try {
+			execFileSync("git", ["diff", "--cached", "--quiet"], { cwd: home, stdio: "ignore" });
+			return; // clean tree — no empty commit
+		} catch { /* staged changes exist — fall through to commit */ }
+		execFileSync("git", ["commit", "-q", "-m", message], { cwd: home, stdio: "ignore" });
+		console.log(`git: committed "${message}"`);
+	} catch (error) {
+		console.log(`git audit layer skipped: ${error instanceof Error ? error.message : error}`);
+	}
+}

package/src/dream/lock.ts

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
+
+export type LockState = { path: string; held: boolean; reason?: string; startedAt: number; priorMtime?: number };
+const HOUR = 60 * 60 * 1000;
+
+function live(pid: number): boolean {
+	if (!Number.isInteger(pid) || pid <= 0) return false;
+	try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+export function acquireLock(path: string): LockState {
+	const now = Date.now();
+	let priorMtime: number | undefined;
+	if (existsSync(path)) {
+		const stat = statSync(path);
+		priorMtime = stat.mtimeMs;
+		let pid = 0;
+		try { pid = Number.parseInt(readFileSync(path, "utf8").trim(), 10); } catch { /* reclaim */ }
+		if (now - stat.mtimeMs <= HOUR && live(pid)) return { path, held: false, reason: "lock gate: live process holds the lock", startedAt: now };
+		try { unlinkSync(path); } catch { return { path, held: false, reason: "lock gate: lock could not be reclaimed", startedAt: now }; }
+	}
+	writeFileSync(path, String(process.pid), { flag: "wx" });
+	return { path, held: true, startedAt: now, priorMtime };
+}
+
+export function releaseLock(lock: LockState): void {
+	// The lock is also the durable last-dream timestamp. Leave the PID marker in place;
+	// the next acquisition reclaims it once the PID is dead or it is older than an hour.
+}
+
+export function restoreMtime(path: string, mtimeMs: number): void {
+	try { utimesSync(path, new Date(), new Date(mtimeMs)); } catch { /* advisory */ }
+}
+
+export function failLock(lock: LockState): void {
+	if (!lock.held) return;
+	if (lock.priorMtime === undefined) { try { unlinkSync(lock.path); } catch { /* best effort */ } }
+	else restoreMtime(lock.path, lock.priorMtime);
+}

package/src/dream/runner.ts

@@ -0,0 +1,111 @@
+import { readFileSync } from "node:fs";
+import { lstat, mkdir, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { createAgentSession, createEditToolDefinition, createWriteToolDefinition, ModelRuntime, resolveModelScopeWithDiagnostics, SessionManager, type AgentSession, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { contentText } from "../history.js";
+
+export type DreamWrite = { tool: "write" | "edit"; path: string };
+export type DreamResult = { report: string; writes: DreamWrite[] };
+export type DreamerSession = Pick<AgentSession, "prompt" | "subscribe" | "dispose">;
+export type DreamerSessionFactory = (options: { cwd: string; modelPattern?: string; tools: string[] }) => Promise<DreamerSession>;
+export const DREAMER_TOOLS = ["read", "grep", "find", "ls", "write", "edit"];
+
+function isOutside(notesHome: string, target: string): boolean {
+	const fromHome = relative(notesHome, target);
+	return fromHome === ".." || fromHome.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || isAbsolute(fromHome);
+}
+
+async function jailWritePath(notesHome: string, path: string): Promise<void> {
+	let realNotesHome: string;
+	try {
+		realNotesHome = await realpath(notesHome);
+	} catch {
+		throw new Error(`write jail: cannot resolve notes home ${notesHome}`);
+	}
+	const target = resolve(realNotesHome, path);
+	const targetParent = dirname(target);
+	if (isOutside(realNotesHome, targetParent)) throw new Error(`write jail: ${path} is outside notes home ${notesHome}`);
+	// write creates parent directories itself. Create only after the lexical check, then
+	// canonicalize the parent so a symlink cannot lead the underlying tool out of home.
+	await mkdir(targetParent, { recursive: true });
+	let realTargetParent: string;
+	try {
+		realTargetParent = await realpath(targetParent);
+	} catch {
+		throw new Error(`write jail: cannot resolve target parent in notes home ${notesHome}`);
+	}
+	if (isOutside(realNotesHome, realTargetParent)) throw new Error(`write jail: ${path} is outside notes home ${notesHome}`);
+	let targetStats;
+	try {
+		targetStats = await lstat(target);
+	} catch (error: any) {
+		if (error.code !== "ENOENT") throw new Error(`write jail: cannot inspect target in notes home ${notesHome}`);
+	}
+	if (targetStats?.isSymbolicLink()) {
+		let realTarget: string;
+		try {
+			realTarget = await realpath(target);
+		} catch {
+			throw new Error(`write jail: cannot resolve target in notes home ${notesHome}`);
+		}
+		if (isOutside(realNotesHome, realTarget)) throw new Error(`write jail: ${path} is outside notes home ${notesHome}`);
+	}
+	if (targetStats && targetStats.nlink > 1) throw new Error(`write jail: ${path} has hard links and is not allowed in notes home ${notesHome}`);
+}
+
+function jailToolDefinition<T extends ToolDefinition<any, any, any>>(definition: T, notesHome: string): T {
+	const execute = definition.execute;
+	return {
+		...definition,
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
+			await jailWritePath(notesHome, (params as { path: string }).path);
+			return execute(toolCallId, params, signal, onUpdate, ctx);
+		},
+	} as T;
+}
+
+/** The only custom definitions in the dream session replace the two built-ins with jailed versions. */
+export function dreamerWriteToolDefinitions(notesHome: string): ToolDefinition<any, any, any>[] {
+	return [
+		jailToolDefinition(createWriteToolDefinition(notesHome), notesHome),
+		jailToolDefinition(createEditToolDefinition(notesHome), notesHome),
+	];
+}
+
+export const defaultDreamerSessionFactory: DreamerSessionFactory = async ({ cwd, modelPattern, tools }) => {
+	let model: Model<Api> | undefined;
+	if (modelPattern) {
+		const runtime = await ModelRuntime.create({ allowModelNetwork: false, refreshOnCreate: false });
+		const result = await resolveModelScopeWithDiagnostics([modelPattern], runtime);
+		model = result.scopedModels[0]?.model;
+		if (!model) throw new Error(`dreamer model pattern "${modelPattern}" did not resolve to an available model`);
+	}
+	const { session } = await createAgentSession({ cwd, sessionManager: SessionManager.inMemory(cwd), tools, customTools: dreamerWriteToolDefinitions(cwd), noTools: "all", model, thinkingLevel: "off" });
+	return session;
+};
+
+export async function runDreamer(playbook: string, cwd: string, options: { modelPattern?: string; sessionFactory?: DreamerSessionFactory } = {}): Promise<DreamResult> {
+	const session = await (options.sessionFactory ?? defaultDreamerSessionFactory)({ cwd, modelPattern: options.modelPattern, tools: DREAMER_TOOLS });
+	let answer = "";
+	let providerError: string | undefined;
+	const writes: DreamWrite[] = [];
+	const unsubscribe = session.subscribe((event: any) => {
+		const tool = event.toolName ?? event.tool?.name;
+		const args = event.args ?? event.arguments ?? event.tool?.arguments;
+		if ((tool === "write" || tool === "edit") && args && typeof args === "object" && typeof args.path === "string") writes.push({ tool, path: args.path });
+		if (event.type !== "message_end" || event.message?.role !== "assistant") return;
+		if (event.message.stopReason === "error") { providerError = event.message.errorMessage ?? "unknown provider error"; return; }
+		answer = contentText(event.message.content);
+	});
+	try {
+		await session.prompt(playbook);
+		if (providerError) throw new Error(`dreamer failed: ${providerError}`);
+		return { report: answer, writes };
+	} finally {
+		unsubscribe?.();
+		session.dispose();
+	}
+}
+
+export function loadPlaybook(path: string): string { return readFileSync(path, "utf8"); }

package/src/history-tools.ts

@@ -1,6 +1,6 @@
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { output, outputRaw, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow, characterWindowHeader, withinTextBudget } from "./tool-output.js";
+import { output, outputRaw, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow, characterWindowHeader, withinTextBudget, DEFAULT_READ_WINDOW_CHARS, HISTORY_PREVIEW_CHARS, MAX_READ_WINDOW_CHARS } from "./tool-output.js";
 import { positiveInteger, recentFirst, nullableString, role, cursor, searchQuery, searchQueries } from "./tool-schema.js";
 import { historyFromSession, filteredItems, visibleItem, allItems, vacuousRoleToolCombo, unknownWindowId } from "./history.js";
 
@@ -53,7 +53,7 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 			if (invalid) return output({ error: invalid, role: params.role, tool_name: params.tool_name });
 			const badWindow = unknownWindowId(ctx, params);
 			if (badWindow) return output({ error: badWindow.message, window_id: params.window_id, known_windows: badWindow.known });
-			const items = filteredItems(ctx, params).map((item) => visibleItem(item, params.max_chars_per_item ?? 1200));
+			const items = filteredItems(ctx, params).map((item) => visibleItem(item, params.max_chars_per_item ?? HISTORY_PREVIEW_CHARS));
 			return output(page(items, params.cursor ?? 0, "items", params.limit, truncateHistoryItem));
 		},
 	}));
@@ -62,7 +62,7 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 		name: "history_read",
 		label: "History read item",
 		description: "Read a bounded character range from one session item. Each response delivers the longest contiguous prefix of the requested window that fits the wire budget: follow the resume cursor to reconstruct the item exactly. A negative offset_chars counts back from the item's end. Offsets and counts are code points (an emoji or CJK character counts as one). The response is the raw item text behind a one-line [bracketed] header naming the item, the resolved offset, the delivered char range, and the resume cursor (continue at offset_chars=N, or end).",
-		parameters: Type.Object({ item_id: Type.String(), offset_chars: Type.Optional(Type.Integer({ description: "Code-point offset to start from. 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." })), window_id: Type.String() }, { additionalProperties: false }),
+		parameters: Type.Object({ item_id: Type.String(), offset_chars: Type.Optional(Type.Integer({ description: "Code-point offset to start from. 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.` })), window_id: Type.String() }, { additionalProperties: false }),
 		async execute(_id, params, _signal, _update, ctx) {
 			const item = allItems(ctx).find((candidate) => candidate.windowId === params.window_id && candidate.itemId === params.item_id);
 			if (!item) return output({ error: "unknown item_id or window_id" });
@@ -72,7 +72,7 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 			if (typeof params.offset_chars === "number" && params.offset_chars > totalChars) {
 				return output({ error: `offset_chars ${params.offset_chars} is past the end: the item has ${totalChars} chars; the largest legal offset is ${totalChars} (an empty end-read)`, window_id: item.windowId, item_id: item.itemId, offset_chars: params.offset_chars, total_chars: totalChars });
 			}
-			const limit_chars = Math.min(params.limit_chars ?? 12000, 50000);
+			const limit_chars = Math.min(params.limit_chars ?? DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS);
 			return readCharacterWindow(item.content, params.offset_chars, params.limit_chars, (window) => {
 				const { content, ...cursor } = window;
 				return outputRaw(characterWindowHeader(`${item.windowId} · item ${item.itemId}`, window), content, { window_id: item.windowId, item_id: item.itemId, ...cursor, limit_chars });
@@ -93,7 +93,7 @@ export function registerHistoryTools(pi: ExtensionAPI) {
 			const queries = searchQueries(params.query);
 			const matching = filteredItems(ctx, params)
 				.filter((item) => queries.some((query) => item.content.includes(query)))
-				.map((item) => ({ ...visibleItem(item, params.max_chars_per_item ?? 1200), match_offset_chars: earliestMatchOffsetChars(item.content, queries) }));
+				.map((item) => ({ ...visibleItem(item, params.max_chars_per_item ?? HISTORY_PREVIEW_CHARS), match_offset_chars: earliestMatchOffsetChars(item.content, queries) }));
 			return output(page(matching, params.cursor ?? 0, "items", params.limit, truncateHistoryItem));
 		},
 	}));

package/src/history.ts

@@ -2,6 +2,7 @@ import type { TextContent, ToolCall } from "@earendil-works/pi-ai";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { SessionReader } from "./session-reader.js";
 import { RESET_V2 } from "./protocol.js";
+import { HISTORY_PREVIEW_CHARS } from "./tool-output.js";
 
 type HistoryItem = {
 	windowId: string;
@@ -29,9 +30,9 @@ function isTextContent(part: unknown): part is TextContent {
 	return typeof part === "object" && part !== null && (part as TextContent).type === "text" && typeof (part as TextContent).text === "string";
 }
 
-function contentText(content: string | unknown[]): string {
+export function contentText(content: unknown): string {
 	if (typeof content === "string") return content;
-	return content.filter(isTextContent).map((part) => part.text).join("\n");
+	return Array.isArray(content) ? content.filter(isTextContent).map((part) => part.text).join("\n") : "";
 }
 
 function mapRole(role: AgentMessage["role"]): HistoryItem["role"] | undefined {
@@ -102,14 +103,19 @@ export function resetV2WindowId(details: unknown): string | undefined {
 }
 
 /** A compaction entry's window id: the extension-minted id for reset-v2, else Pi's entry id. */
-function windowIdOf(sessionId: string, entry: { id: string; details?: unknown }): string {
+export function windowIdOf(sessionId: string, entry: { id: string; details?: unknown }): string {
 	return resetV2WindowId(entry.details) ?? `pcw:${sessionId.slice(0, 8)}:${entry.id}`;
 }
 
+/** Mint the durable identity of a session's root history window. */
+export function rootWindowId(sessionId: string): string {
+	return `pcw:${sessionId.slice(0, 8)}:root`;
+}
+
 /** Build durable, on-demand history directly from every entry on the current session branch. */
 export function historyFromSession(ctx: SessionReader): HistoryWindow[] {
 	const sessionId = ctx.sessionManager.getSessionId();
-	let window: HistoryWindow = { windowId: `pcw:${sessionId.slice(0, 8)}:root`, items: [] };
+	let window: HistoryWindow = { windowId: rootWindowId(sessionId), items: [] };
 	const windows = [window];
 	for (const entry of ctx.sessionManager.getBranch()) {
 		if (entry.type === "compaction") {
@@ -153,7 +159,7 @@ export function historyFromSession(ctx: SessionReader): HistoryWindow[] {
 	return windows;
 }
 
-export function visibleItem(item: HistoryItem, maxChars = 1200) {
+export function visibleItem(item: HistoryItem, maxChars = HISTORY_PREVIEW_CHARS) {
 	const characters = Array.from(item.content);
 	const truncated = characters.length > maxChars;
 	return {
@@ -230,6 +236,5 @@ export function currentWindowId(ctx: SessionReader): string {
 		const entry = branch[i];
 		if (entry?.type === "compaction") return windowIdOf(sessionId, entry);
 	}
-	return `pcw:${sessionId.slice(0, 8)}:root`;
+	return rootWindowId(sessionId);
 }
-

package/src/index.ts

@@ -1,14 +1,14 @@
 import { registerHistoryTools } from "./history-tools.js";
-import { registerMemoryTools } from "./memory/tools.js";
-import { registerBudget, deriveThresholds, mergePiContextSettings } from "./budget.js";
+import { registerNotesTools } from "./notes/tools.js";
+import { registerBudget } from "./budget.js";
 import { output } from "./tool-output.js";
-export { deriveThresholds, mergePiContextSettings };
+import { deriveThresholds, mergePiContextSettings } from "./thresholds.js";
 import { STATE_TYPE, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, RESET_MARKER_TYPE, CONTINUATION_TYPE, RESET_V2, MAX_NOTE_BYTES, CONTEXT_WINDOW_OPEN_TAG, CONTEXT_WINDOW_CLOSE_TAG, CONTEXT_WINDOW_PROTOCOL_OPEN_TAG, CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG, GUIDANCE_OPEN_TAG, PI_CONTEXT_SETTINGS_KEY, DEFAULT_RESERVE_TOKENS, DEFAULT_REMINDER_MARGIN_TOKENS, WARNING_RUNWAY_TOKENS, RESET_SUMMARY, CONTINUATION, WARNING_PROMPT } from "./protocol.js";
-import { historyFromSession, hasWindowMessage, currentWindowId, resetV2WindowId } from "./history.js";
-import { assertVirtualPath } from "./notes.js";
+import { historyFromSession, hasWindowMessage, currentWindowId, resetV2WindowId, rootWindowId, windowIdOf } from "./history.js";
+import { assertVirtualPath } from "./notes/model.js";
 import { bootBlock } from "./prompts.js";
 export { historyFromSession } from "./history.js";
-export { notesFromSession } from "./notes.js";
+export { notesFromSession } from "./notes/model.js";
 import { registerResetLifecycle } from "./reset-lifecycle.js";
 import { registerWarning } from "./warning.js";
 import { randomUUID } from "node:crypto";
@@ -25,8 +25,7 @@ export default function piContext(pi: ExtensionAPI) {
 		// The root window has no compaction entry to carry the boot block, so persist
 		// it once as a hidden custom message. Reset windows already carry theirs at
 		// position 0 in the compaction summary, so a resumed session adds nothing.
-		const sessionId = ctx.sessionManager.getSessionId();
-		const rootId = `pcw:${sessionId.slice(0, 8)}:root`;
+		const rootId = rootWindowId(ctx.sessionManager.getSessionId());
 		if (currentWindowId(ctx) !== rootId || hasWindowMessage(ctx, BOOT_TYPE)) return;
 		pi.sendMessage({ customType: BOOT_TYPE, content: bootBlock(ctx, rootId, undefined, false), display: false }, { triggerTurn: false });
 	});
@@ -48,7 +47,7 @@ export default function piContext(pi: ExtensionAPI) {
 	});
 
 	registerHistoryTools(pi);
-	registerMemoryTools(pi);
+	registerNotesTools(pi);
 
 	pi.registerTool(defineTool({
 		name: "new_context",
@@ -70,15 +69,15 @@ export default function piContext(pi: ExtensionAPI) {
 		},
 		onReset: (entryId) => pi.appendEntry(STATE_TYPE, { version: 1, lastResetEntryId: entryId }),
 		buildReset: (event, ctx, explicit) => {
-			const session8 = ctx.sessionManager.getSessionId().slice(0, 8);
+			const sessionId = ctx.sessionManager.getSessionId();
 			// Window IDs are independent of Pi entry IDs. Avoid reusing a window
 			// identity already present on this branch.
 			const windows = historyFromSession(ctx);
 			const usedIds = new Set(windows.map((window) => window.windowId));
-			let minted = randomUUID().slice(0, 8);
-			while (usedIds.has(`pcw:${session8}:${minted}`)) minted = randomUUID().slice(0, 8);
-			const windowId = `pcw:${session8}:${minted}`;
-			const previousId = windows[windows.length - 1]?.windowId ?? `pcw:${session8}:root`;
+			let minted = { id: randomUUID().slice(0, 8) };
+			while (usedIds.has(windowIdOf(sessionId, minted))) minted = { id: randomUUID().slice(0, 8) };
+			const windowId = windowIdOf(sessionId, minted);
+			const previousId = windows[windows.length - 1]?.windowId ?? rootWindowId(sessionId);
 			// The reset marker stays as firstKeptEntryId; it no longer names the window.
 			pi.appendEntry(RESET_MARKER_TYPE, { version: 1, reason: event.reason, requested: explicit });
 			const markerId = ctx.sessionManager.getLeafId();

package/src/notes/address.ts

@@ -0,0 +1,33 @@
+import { assertVirtualPath } from "./model.js";
+import type { Scope } from "./paths.js";
+
+export type NoteAddress = { scope: Scope; path: string };
+
+const ADDRESS_FORMS = "legal prefixes are @project/ and @global/; bare names are the session home";
+
+/**
+ * Decode the one public note address into its physical home and virtual path. This is a
+ * tool-boundary rule: replay paths keep using assertVirtualPath directly and are untouched.
+ */
+export function assertAddress(value: unknown): NoteAddress {
+	if (typeof value !== "string") throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+	let scope: Scope = "session";
+	let path = value;
+	if (value.startsWith("@project/")) {
+		scope = "project";
+		path = value.slice("@project/".length);
+	} else if (value.startsWith("@global/")) {
+		scope = "global";
+		path = value.slice("@global/".length);
+	} else if (value.startsWith("@")) {
+		throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+	}
+	if (path.includes("@")) throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+	assertVirtualPath(path);
+	return { scope, path };
+}
+
+/** Render a virtual path in its one unambiguous public address form. */
+export function addressFor(scope: Scope, path: string): string {
+	return scope === "session" ? path : `@${scope}/${path}`;
+}

package/src/{memory → notes}/frontmatter.ts

@@ -1,4 +1,4 @@
-import { localIso } from "../notes.js";
+import { localIso } from "./model.js";
 import type { Scope } from "./paths.js";
 
 export type NoteStatus = "active" | "superseded" | "pending" | "archived";
@@ -30,7 +30,7 @@ const ORIGINS: readonly Origin[] = ["user", "self", "external"];
 const STATUSES: readonly NoteStatus[] = ["active", "superseded", "pending", "archived"];
 const TIMESTAMP_KEYS = ["created_at", "updated_at", "last_accessed"] as const;
 /** Emission order, exactly the Design's key list. */
-const KNOWN_KEYS = ["scope", "origin", "status", "stale", "created_at", "updated_at", "last_accessed", "access_count", "source_window", "supersedes", "recurrence_count", "recurrence_windows"] as const;
+const KNOWN_KEYS = ["origin", "status", "stale", "created_at", "updated_at", "last_accessed", "access_count", "source_window", "supersedes", "recurrence_count", "recurrence_windows"] as const;
 
 export function isScope(value: unknown): value is Scope {
 	return typeof value === "string" && (SCOPES as readonly string[]).includes(value);
@@ -140,7 +140,9 @@ export function serializeNote(meta: NoteMeta, body: string): string {
 		else lines.push(`${key}: ${yamlScalar(value)}`);
 	}
 	for (const key of Object.keys(meta)) {
-		if ((KNOWN_KEYS as readonly string[]).includes(key)) continue;
+		// scope is a legacy on-disk field. Store callers derive it from the home's location,
+		// but serialization intentionally drops it on the next write.
+		if (key === "scope" || (KNOWN_KEYS as readonly string[]).includes(key)) continue;
 		if (meta[key] === undefined) continue;
 		lines.push(`${key}: ${yamlScalar(meta[key])}`);
 	}

package/src/{notes.ts → notes/model.ts}

@@ -1,5 +1,5 @@
-import type { SessionReader } from "./session-reader.js";
-import { MAX_NOTE_BYTES, NOTE_TYPE } from "./protocol.js";
+import type { SessionReader } from "../session-reader.js";
+import { MAX_NOTE_BYTES, NOTE_TYPE } from "../protocol.js";
 
 export type NoteFile = { text: string; stale: boolean; createdAt: number; updatedAt: number };
 export type NoteOperation = {

package/src/{memory → notes}/paths.ts

@@ -12,6 +12,11 @@ export function notesRoot(): string {
 	return override && override.length > 0 ? resolve(override) : join(homedir(), ".agents", "notes");
 }
 
+/** Absolute directory holding the per-session note homes. */
+export function sessionHomesRoot(home = notesRoot()): string {
+	return join(home, "pi", "session");
+}
+
 /**
  * Absolute git root for `cwd`, walking upward until a directory holds a `.git` entry.
  * No git root yields undefined, which projectKey then replaces with the cwd itself.
@@ -43,7 +48,7 @@ function sessionId(ctx: ExtensionContext): string {
 export function scopeDir(scope: Scope, ctx: ExtensionContext): string {
 	if (scope === "global") return join(notesRoot(), "global");
 	if (scope === "project") return join(notesRoot(), "project", projectKey(ctx.cwd));
-	return join(notesRoot(), "pi", "session", sessionId(ctx));
+	return join(sessionHomesRoot(), sessionId(ctx));
 }
 
 /**