@astrosheep/pi-context 0.19.0 → 0.21.0

package/dist/src/history.js

@@ -0,0 +1,215 @@
+import { RESET_V2 } from "./protocol.js";
+import { HISTORY_PREVIEW_CHARS } from "./tool-output.js";
+function isTextContent(part) {
+    return typeof part === "object" && part !== null && part.type === "text" && typeof part.text === "string";
+}
+export function contentText(content) {
+    if (typeof content === "string")
+        return content;
+    return Array.isArray(content) ? content.filter(isTextContent).map((part) => part.text).join("\n") : "";
+}
+function mapRole(role) {
+    if (role === "user" || role === "assistant")
+        return role;
+    if (role === "toolResult" || role === "bashExecution")
+        return "tool";
+    if (role === "custom")
+        return "user";
+    if (role === "compactionSummary" || role === "branchSummary")
+        return "system";
+    return undefined;
+}
+/** This extension's own custom-entry namespace; entries under it are authored by pi-context. */
+const PI_CONTEXT_ENTRY_PREFIX = "pi-context/";
+function messageContent(message) {
+    switch (message.role) {
+        case "bashExecution":
+            // The command is as much the record as its output: without it the typed line is
+            // unsearchable. Mirrors the tool-call projection below.
+            return message.output ? `${message.command}\n${message.output}` : message.command;
+        case "branchSummary":
+        case "compactionSummary":
+            return message.summary;
+        default:
+            return contentText(message.content);
+    }
+}
+function toolInfo(message) {
+    if (message.role === "bashExecution") {
+        // A truncated bash run is only half the record without the on-disk path: surface both.
+        return { toolName: "bash", outputTruncated: message.truncated || undefined, fullOutputPath: message.truncated ? message.fullOutputPath : undefined };
+    }
+    if (message.role !== "toolResult")
+        return {};
+    return { toolName: message.toolName, toolError: message.isError === true ? true : undefined };
+}
+/**
+ * An assistant turn's tool calls, projected as their own items: calls wear their own role so the
+ * authoring turn's visible text (role "assistant") stays pure; what was invoked stays as
+ * searchable as what came back (role "tool"). Ids derive from the turn's entry id and stay
+ * opaque; history_read resolves them like any other item.
+ */
+function toolCallItems(windowId, entry, message) {
+    if (message.role !== "assistant" || !Array.isArray(message.content))
+        return [];
+    const items = [];
+    let callIndex = 0;
+    for (const part of message.content) {
+        if (typeof part !== "object" || part === null || part.type !== "toolCall")
+            continue;
+        const call = part;
+        items.push({
+            windowId,
+            itemId: `${entry.id}#${callIndex++}`,
+            role: "tool_call",
+            content: JSON.stringify(call.arguments),
+            createdAt: entry.timestamp,
+            toolName: call.name,
+        });
+    }
+    return items;
+}
+/** The extension-owned window id baked onto a reset-v2 compaction entry, if present. */
+export function resetV2WindowId(details) {
+    if (typeof details !== "object" || details === null)
+        return undefined;
+    const candidate = details;
+    if (candidate.piContext !== RESET_V2 || typeof candidate.windowId !== "string")
+        return undefined;
+    return candidate.windowId;
+}
+/** A compaction entry's window id: the extension-minted id for reset-v2, else Pi's entry id. */
+export function windowIdOf(sessionId, entry) {
+    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) {
+    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) {
+    const sessionId = ctx.sessionManager.getSessionId();
+    let window = { windowId: rootWindowId(sessionId), items: [] };
+    const windows = [window];
+    for (const entry of ctx.sessionManager.getBranch()) {
+        if (entry.type === "compaction") {
+            window = { windowId: windowIdOf(sessionId, entry), createdAt: entry.timestamp, items: [] };
+            windows.push(window);
+            window.items.push({
+                windowId: window.windowId,
+                itemId: entry.id,
+                // A reset-v2 compaction is authored by this extension; a native Pi compaction is not.
+                role: resetV2WindowId(entry.details) === undefined ? "system" : "developer",
+                content: entry.summary,
+                createdAt: entry.timestamp,
+            });
+            continue;
+        }
+        if (entry.type === "message") {
+            const role = mapRole(entry.message.role);
+            if (!role)
+                continue;
+            window.items.push({
+                windowId: window.windowId,
+                itemId: entry.id,
+                role,
+                content: messageContent(entry.message),
+                createdAt: entry.timestamp,
+                ...toolInfo(entry.message),
+            });
+            window.items.push(...toolCallItems(window.windowId, entry, entry.message));
+            continue;
+        }
+        if (entry.type === "custom_message") {
+            window.items.push({
+                windowId: window.windowId,
+                itemId: entry.id,
+                // Only entries this extension wrote are its own; every foreign custom message stays a user turn.
+                role: entry.customType.startsWith(PI_CONTEXT_ENTRY_PREFIX) ? "developer" : "user",
+                content: contentText(entry.content),
+                createdAt: entry.timestamp,
+            });
+        }
+    }
+    return windows;
+}
+export function visibleItem(item, maxChars = HISTORY_PREVIEW_CHARS) {
+    const characters = Array.from(item.content);
+    const truncated = characters.length > maxChars;
+    return {
+        window_id: item.windowId,
+        item_id: item.itemId,
+        role: item.role,
+        tool_name: item.toolName ?? null,
+        // Surfaced only when set: a truncated bash run names its full-output path, and an
+        // errored tool run says so. Absent keys mean nothing special happened.
+        ...(item.outputTruncated ? { output_truncated: true, full_output_path: item.fullOutputPath ?? null } : {}),
+        ...(item.toolError ? { tool_error: true } : {}),
+        truncated,
+        total_chars: characters.length,
+        // A truncated payload is a plain prefix: no synthetic marker is appended, and
+        // `total_chars` names exactly how many code points were left out.
+        truncated_content: truncated ? characters.slice(0, maxChars).join("") : item.content,
+    };
+}
+export function allItems(ctx) {
+    return historyFromSession(ctx).flatMap((window) => window.items);
+}
+/**
+ * window_id must name a real window; anything else is a named error, not a silent empty page
+ * (a window that exists but has no matching items after the other filters stays a legal empty
+ * page). Returns the teaching message plus the known window ids so the error is self-healing.
+ */
+export function unknownWindowId(ctx, params) {
+    if (typeof params.window_id !== "string")
+        return undefined;
+    const known = historyFromSession(ctx).map((window) => window.windowId);
+    return known.includes(params.window_id) ? undefined : { message: `unknown window_id "${params.window_id}"`, known };
+}
+/**
+ * A role×tool_name combination is vacuous — provably empty from the taxonomy alone, before
+ * any data is read — when tool_name is given alongside a role that never carries one. Only
+ * "tool_call" and "tool" items have a tool name. Returns the teaching error message, or
+ * undefined when the combination can match.
+ */
+export function vacuousRoleToolCombo(params) {
+    if (typeof params.tool_name === "string" && typeof params.role === "string" && params.role !== "tool_call" && params.role !== "tool") {
+        return `tool_name is only set on "tool_call" and "tool" items; role "${params.role}" never carries one`;
+    }
+    return undefined;
+}
+export function filteredItems(ctx, params) {
+    let items = allItems(ctx);
+    if (typeof params.window_id === "string")
+        items = items.filter((item) => item.windowId === params.window_id);
+    if (typeof params.role === "string")
+        items = items.filter((item) => item.role === params.role);
+    if (typeof params.tool_name === "string")
+        items = items.filter((item) => item.toolName === params.tool_name);
+    if (params.recent_first !== false)
+        items.reverse();
+    return items;
+}
+/** Persisted messages in the active window, excluding earlier windows on this branch. */
+export function hasWindowMessage(ctx, customType) {
+    const branch = ctx.sessionManager.getBranch();
+    for (let i = branch.length - 1; i >= 0; i--) {
+        const entry = branch[i];
+        if (entry.type === "compaction")
+            break;
+        if (entry.type === "custom_message" && entry.customType === customType)
+            return true;
+    }
+    return false;
+}
+/** Cheap current-window lookup: scan the branch tail for the latest compaction entry. */
+export function currentWindowId(ctx) {
+    const sessionId = ctx.sessionManager.getSessionId();
+    const branch = ctx.sessionManager.getBranch();
+    for (let i = branch.length - 1; i >= 0; i--) {
+        const entry = branch[i];
+        if (entry?.type === "compaction")
+            return windowIdOf(sessionId, entry);
+    }
+    return rootWindowId(sessionId);
+}

package/dist/src/index.js

@@ -0,0 +1,98 @@
+import { registerHistoryTools } from "./history-tools.js";
+import { registerNotesTools } from "./notes/tools.js";
+import { registerBudget } from "./budget.js";
+import { output } from "./tool-output.js";
+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, 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/model.js";
+import { registerResetLifecycle } from "./reset-lifecycle.js";
+import { registerWarning } from "./warning.js";
+import { randomUUID } from "node:crypto";
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+export default function piContext(pi) {
+    let enabled = true;
+    registerBudget(pi, () => enabled);
+    registerWarning(pi, () => enabled);
+    pi.on("session_start", (_event, ctx) => {
+        if (!enabled)
+            return;
+        // 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 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 });
+    });
+    pi.registerCommand("pi-context", {
+        description: "Toggle pi-context: context_window boot block, low-budget guidance, and reset-style compaction",
+        getArgumentCompletions: (prefix) => ["on", "off"].filter((a) => a.startsWith(prefix)).map((a) => ({ value: a, label: a })),
+        handler: async (args, cmdCtx) => {
+            const arg = args.trim().toLowerCase();
+            if (arg === "on")
+                enabled = true;
+            else if (arg === "off") {
+                enabled = false;
+                resets.clear();
+            }
+            else if (arg !== "") {
+                cmdCtx.ui.notify("Usage: /pi-context [on|off]", "error");
+                return;
+            }
+            cmdCtx.ui.notify(`pi-context: ${enabled ? "on" : "off"}`, "info");
+        },
+    });
+    registerHistoryTools(pi);
+    registerNotesTools(pi);
+    pi.registerTool(defineTool({
+        name: "new_context",
+        label: "New context",
+        description: "Clear your mind and start a new context window. Your session, notes, and history survive.",
+        parameters: Type.Object({}, { additionalProperties: false }),
+        async execute() {
+            if (!enabled)
+                return output({ error: "pi-context is off (/pi-context on to enable)" });
+            return output({ status: resets.request() }, undefined, true);
+        },
+    }));
+    const resets = registerResetLifecycle(pi, {
+        isEnabled: () => enabled,
+        continuation: { customType: CONTINUATION_TYPE, content: CONTINUATION, display: false },
+        isCurrentReset: (entryId, ctx) => {
+            const entry = ctx.sessionManager.getEntry(entryId);
+            return entry?.type === "compaction" && resetV2WindowId(entry.details) === currentWindowId(ctx);
+        },
+        onReset: (entryId) => pi.appendEntry(STATE_TYPE, { version: 1, lastResetEntryId: entryId }),
+        buildReset: (event, ctx, explicit) => {
+            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 = { 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();
+            if (!markerId)
+                return { cancel: true };
+            return {
+                compaction: {
+                    summary: bootBlock(ctx, windowId, previousId, true),
+                    firstKeptEntryId: markerId,
+                    tokensBefore: event.preparation.tokensBefore,
+                    details: { piContext: RESET_V2, windowId },
+                },
+            };
+        },
+    });
+}
+export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, WARNING_PROMPT, WARNING_RUNWAY_TOKENS, RESET_MARKER_TYPE, RESET_SUMMARY, CONTINUATION, 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, deriveThresholds, mergePiContextSettings, assertVirtualPath };

package/dist/src/notes/address.js

@@ -0,0 +1,31 @@
+import { assertVirtualPath } from "./model.js";
+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) {
+    if (typeof value !== "string")
+        throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+    let 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, path) {
+    return scope === "session" ? path : `@${scope}/${path}`;
+}

package/dist/src/notes/frontmatter.js

@@ -0,0 +1,136 @@
+import { localIso } from "./model.js";
+const SCOPES = ["session", "project", "global"];
+const ORIGINS = ["user", "self", "external"];
+const STATUSES = ["active", "superseded", "pending", "archived"];
+const TIMESTAMP_KEYS = ["created_at", "updated_at", "last_accessed"];
+/** Emission order, exactly the Design's key list. */
+const KNOWN_KEYS = ["origin", "status", "stale", "created_at", "updated_at", "last_accessed", "access_count", "source_window", "supersedes", "recurrence_count", "recurrence_windows"];
+export function isScope(value) {
+    return typeof value === "string" && SCOPES.includes(value);
+}
+export function isOrigin(value) {
+    return typeof value === "string" && ORIGINS.includes(value);
+}
+function isStatus(value) {
+    return typeof value === "string" && STATUSES.includes(value);
+}
+function toEpoch(value, fallback) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string") {
+        const parsed = Date.parse(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return fallback;
+}
+/** A frontmatter scalar encoded as JSON, falling back to a plain string for hand-written YAML. */
+function parseScalar(text) {
+    const trimmed = text.trim();
+    if (trimmed === "")
+        return "";
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'")))
+            return trimmed.slice(1, -1);
+        return trimmed;
+    }
+}
+/**
+ * Split raw file text into its frontmatter fields and body. When the file does not open with
+ * a closed `---` block, the whole text is body and the field map is empty.
+ */
+function parseFrontmatter(raw) {
+    const stripped = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+    const lines = stripped.split("\n").map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line));
+    if (lines[0]?.trim() !== "---")
+        return { fields: {}, body: raw };
+    let close = -1;
+    for (let index = 1; index < lines.length; index++) {
+        if (lines[index]?.trim() === "---") {
+            close = index;
+            break;
+        }
+    }
+    if (close === -1)
+        return { fields: {}, body: raw };
+    const fields = {};
+    for (let index = 1; index < close; index++) {
+        const line = lines[index];
+        const match = /^([A-Za-z_][A-Za-z0-9_-]*):(.*)$/.exec(line);
+        if (!match)
+            continue;
+        const key = match[1];
+        const rest = match[2];
+        if (rest.trim() === "") {
+            // A bare key opens a block sequence of `- item` lines, the only multi-line shape we parse.
+            const items = [];
+            while (index + 1 < close && /^\s*-\s+/.test(lines[index + 1])) {
+                index++;
+                items.push(parseScalar(lines[index].replace(/^\s*-\s+/, "")));
+            }
+            fields[key] = items;
+        }
+        else {
+            fields[key] = parseScalar(rest);
+        }
+    }
+    const rest = lines.slice(close + 1);
+    if (rest[0] === "")
+        rest.shift();
+    return { fields, body: rest.join("\n") };
+}
+/**
+ * Parse a note file. Missing known keys take the Design defaults (status active, stale false,
+ * access_count 0, timestamps now); unknown keys are carried through untouched.
+ */
+export function parseNote(raw, now = Date.now()) {
+    const { fields, body } = parseFrontmatter(raw);
+    const meta = { ...fields };
+    meta.scope = isScope(meta.scope) ? meta.scope : "global";
+    meta.origin = isOrigin(meta.origin) ? meta.origin : "self";
+    meta.status = isStatus(meta.status) ? meta.status : "active";
+    meta.stale = meta.stale === true;
+    for (const key of TIMESTAMP_KEYS)
+        meta[key] = toEpoch(meta[key], now);
+    meta.access_count = typeof meta.access_count === "number" && Number.isFinite(meta.access_count) ? meta.access_count : 0;
+    return { meta: meta, body };
+}
+/** Emit a YAML scalar: bare for safe strings and JSON literals, JSON-quoted otherwise. */
+function yamlScalar(value) {
+    if (typeof value === "string") {
+        const reserved = new Set(["true", "false", "null", "yes", "no", "on", "off", "~"]);
+        if (/^[A-Za-z0-9_.+\-:/]+$/.test(value) && !reserved.has(value.toLowerCase()))
+            return value;
+    }
+    return JSON.stringify(value);
+}
+/** Serialize frontmatter + blank line + body. Known keys emit in Design order, extras after. */
+export function serializeNote(meta, body) {
+    const lines = [];
+    for (const key of KNOWN_KEYS) {
+        const value = meta[key];
+        if (value === undefined)
+            continue;
+        if (TIMESTAMP_KEYS.includes(key))
+            lines.push(`${key}: ${yamlScalar(localIso(value))}`);
+        else
+            lines.push(`${key}: ${yamlScalar(value)}`);
+    }
+    for (const key of Object.keys(meta)) {
+        // 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.includes(key))
+            continue;
+        if (meta[key] === undefined)
+            continue;
+        lines.push(`${key}: ${yamlScalar(meta[key])}`);
+    }
+    return `---\n${lines.join("\n")}\n---\n\n${body}`;
+}
+/** Strip a leading frontmatter block from user content, so a note body is pure content. */
+export function stripLeadingFrontmatter(content) {
+    return parseFrontmatter(content).body;
+}

package/dist/src/notes/model.js

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

package/dist/src/notes/paths.js

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+/** Physical home of the on-disk note store: $PI_NOTES_HOME or ~/.agents/notes. */
+export function notesRoot() {
+    const override = process.env.PI_NOTES_HOME;
+    return override && override.length > 0 ? resolve(override) : join(homedir(), ".agents", "notes");
+}
+/** Absolute directory holding the per-session note homes. */
+export function sessionHomesRoot(home = notesRoot()) {
+    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.
+ */
+function gitRoot(cwd) {
+    let dir = resolve(cwd);
+    for (;;) {
+        if (existsSync(join(dir, ".git")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/** `<basename(absGitRoot)-sha1(absGitRoot)[:8]>`, or the same formula over cwd with no git root. */
+export function projectKey(cwd) {
+    const absolute = resolve(cwd);
+    const root = gitRoot(absolute) ?? absolute;
+    const digest = createHash("sha1").update(root).digest("hex").slice(0, 8);
+    return `${basename(root)}-${digest}`;
+}
+/** Session identity comes from the pi session manager; ids are filesystem-safe by construction. */
+function sessionId(ctx) {
+    return ctx.sessionManager.getSessionId();
+}
+/** Absolute directory holding every note of one scope. */
+export function scopeDir(scope, ctx) {
+    if (scope === "global")
+        return join(notesRoot(), "global");
+    if (scope === "project")
+        return join(notesRoot(), "project", projectKey(ctx.cwd));
+    return join(sessionHomesRoot(), sessionId(ctx));
+}
+/**
+ * Notes are markdown files: a virtual path without an `.md` suffix gains one, an explicit
+ * `.md` is kept as-is, so `a/b` and `a/b.md` name the same physical file.
+ */
+export function noteFileName(vpath) {
+    return vpath.endsWith(".md") ? vpath : `${vpath}.md`;
+}
+/** Absolute file path for a virtual path in a scope. Callers validate the vpath first. */
+export function physicalPath(scope, vpath, ctx) {
+    return join(scopeDir(scope, ctx), ...noteFileName(vpath).split("/"));
+}