@astrosheep/pi-context 0.24.0 → 0.25.1

package/dist/src/index.js

@@ -1,98 +1,31 @@
-import { registerHistoryTools } from "./history-tools.js";
+import { VERSION } from "@earendil-works/pi-coding-agent";
+import { registerHistoryTools } from "./history/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");
-        },
-    });
+import { deriveThresholds } from "./context/thresholds.js";
+import { registerContext } from "./context/runtime.js";
+import { mergePiContextSettings } from "./settings.js";
+import { NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, RESET_MARKER_TYPE, CONTINUATION_TYPE, 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, CONTINUATION, WARNING_PROMPT } from "./protocol.js";
+import { assertVirtualPath } from "./notes/address.js";
+export { historyFromSession } from "./history/history.js";
+export { notesFromSession } from "./notes/session-replay.js";
+function registerPiContext(pi, settingsManager) {
+    const [major, minor] = VERSION.split(".").map(Number);
+    if (!(major > 0 || (major === 0 && minor >= 87))) {
+        throw new Error(`pi-context requires Pi >= 0.87.0; running ${VERSION}. Upgrade Pi and restart the process; /reload only reloads extensions.`);
+    }
+    registerContext(pi, settingsManager);
     registerHistoryTools(pi);
     registerNotesTools(pi);
-    pi.registerTool(defineTool({
-        name: "wipe_memory",
-        label: "Wipe memory",
-        description: "Wipe your in-context memory and start a fresh 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 };
+/**
+ * Create an extension factory bound to an SDK settings authority. The host must pass
+ * the same manager to createAgentSession and to this factory's resource loader.
+ */
+export function createPiContext(options = {}) {
+    return (pi) => registerPiContext(pi, options.settingsManager);
+}
+/** The Pi-discovered extension keeps the standard file-backed settings behavior. */
+export default function piContext(pi) {
+    registerPiContext(pi);
+}
+export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, CONTINUATION_TYPE, WARNING_PROMPT, WARNING_RUNWAY_TOKENS, RESET_MARKER_TYPE, 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

@@ -1,31 +1,112 @@
-import { assertVirtualPath } from "./model.js";
-const ADDRESS_FORMS = "legal prefixes are @project/ and @personal/; bare names are the session home";
+import { agentSlug, modelSlug, SLUG_PATTERN } from "./paths.js";
+export const ADDRESS_FORMS = "legal prefixes are @project/, @human/, @self/, and @model/; bare names are this session";
+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;
+}
 /**
  * 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.
+ * The word after `@` is always a reserved home name; agent and model names live at the
+ * second level (@agents/faye/, never @faye/), so user-chosen names can never collide with
+ * the reserved set. `@self` and `@model` are relative — `who` stays undefined and the
+ * store resolves the current agent/model at call time.
  */
 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("@personal/")) {
-        scope = "personal";
-        path = value.slice("@personal/".length);
-    }
-    else if (value.startsWith("@")) {
-        throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+    let who;
+    if (value.startsWith("@")) {
+        const rest = value.slice(1);
+        const headEnd = rest.indexOf("/");
+        const head = headEnd === -1 ? rest : rest.slice(0, headEnd);
+        const tail = headEnd === -1 ? "" : rest.slice(headEnd + 1);
+        path = tail;
+        if (head === "project")
+            scope = "project";
+        else if (head === "human")
+            scope = "human";
+        else if (head === "self")
+            scope = "agent";
+        else if (head === "model")
+            scope = "model";
+        else if (head === "agents" || head === "models") {
+            const nameEnd = tail.indexOf("/");
+            who = nameEnd === -1 ? tail : tail.slice(0, nameEnd);
+            if (!SLUG_PATTERN.test(who))
+                throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+            scope = head === "agents" ? "agent" : "model";
+            path = nameEnd === -1 ? "" : tail.slice(nameEnd + 1);
+        }
+        else {
+            throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+        }
+        if (path === "" && scope !== "agent" && scope !== "model")
+            throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+        if (path === "" && who === undefined)
+            throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
     }
     if (path.includes("@"))
         throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
     assertVirtualPath(path);
-    return { scope, path };
+    return { scope, path, who };
 }
-/** Render a virtual path in its one unambiguous public address form. */
-export function addressFor(scope, path) {
-    return scope === "session" ? path : `@${scope}/${path}`;
+/** Render a virtual path in its one unambiguous public address form. Relative forms
+ * (@self/, @model/) never render: the canonical address always carries the resolved
+ * name, so listings alone tell every home apart. */
+export function addressFor(ctx, scope, path, who) {
+    if (scope === "session")
+        return path;
+    if (scope === "project")
+        return `@project/${path}`;
+    if (scope === "human")
+        return `@human/${path}`;
+    if (scope === "agent")
+        return `@agents/${who ?? agentSlug(ctx)}/${path}`;
+    return `@models/${who ?? modelSlug(ctx)}/${path}`;
 }

package/dist/src/notes/frontmatter.js

@@ -1,10 +1,23 @@
-import { localIso } from "./model.js";
-const SCOPES = ["session", "project", "personal"];
+const SCOPES = ["session", "project", "human", "agent", "model"];
 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"];
+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}`;
+}
 export function isScope(value) {
     return typeof value === "string" && SCOPES.includes(value);
 }
@@ -89,7 +102,9 @@ function parseFrontmatter(raw) {
 export function parseNote(raw, now = Date.now()) {
     const { fields, body } = parseFrontmatter(raw);
     const meta = { ...fields };
-    meta.scope = isScope(meta.scope) ? meta.scope : "personal";
+    // scope is a legacy on-disk field: store callers derive it from the file's home and
+    // overwrite it after parsing, so an absent or outdated value just falls back.
+    meta.scope = isScope(meta.scope) ? meta.scope : "session";
     meta.origin = isOrigin(meta.origin) ? meta.origin : "self";
     meta.status = isStatus(meta.status) ? meta.status : "active";
     meta.stale = meta.stale === true;

package/dist/src/notes/notes-snapshot.js

@@ -0,0 +1,30 @@
+import { listNotes } from "./store.js";
+const NOTES_HOMES = [
+    { scope: "session", label: "this session" },
+    { scope: "project", label: "@project" },
+    { scope: "human", label: "@human" },
+    { scope: "agent", label: "@self" },
+    { scope: "model", label: "@model" },
+];
+/**
+ * Acquire the five homes once for one boot. Only filesystem-style errno failures are isolated;
+ * malformed note data and unrelated construction errors remain visible to the caller.
+ */
+export function loadNotesSnapshot(ctx, loadHome = (context, scope) => listNotes(context, { scope })) {
+    const openedAt = Date.now();
+    const homes = new Map();
+    const unavailable = [];
+    for (const home of NOTES_HOMES) {
+        try {
+            homes.set(home.scope, loadHome(ctx, home.scope));
+        }
+        catch (error) {
+            const code = typeof error === "object" && error !== null ? error.code : undefined;
+            if (typeof code !== "string" || !/^E[A-Z0-9_]+$/.test(code) || code.startsWith("ERR_"))
+                throw error;
+            homes.set(home.scope, []);
+            unavailable.push(home);
+        }
+    }
+    return { openedAt, homes, unavailable };
+}

package/dist/src/notes/paths.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync, renameSync } 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. */
@@ -37,14 +37,71 @@ export function projectKey(cwd) {
 function sessionId(ctx) {
     return ctx.sessionManager.getSessionId();
 }
-/** Absolute directory holding every note of one scope. */
-export function scopeDir(scope, ctx) {
-    if (scope === "personal")
-        return join(notesRoot(), "personal");
+/** The one legal home-name shape: lowercase [a-z0-9-] runs separated by single dashes. */
+export const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * Identity slugs: one declared name per home, never detected from prompt content.
+ * `PI_NOTES_AGENT` declares who is running (default "root"); the model slug derives
+ * from the live model id, provider prefix stripped. Both slugified to [a-z0-9-].
+ */
+export function slugify(value) {
+    const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    return slug.length > 0 ? slug : "root";
+}
+/** The current agent's home name: the launch-declared identity, defaulting to "root". */
+export function agentSlug(_ctx) {
+    return slugify(process.env.PI_NOTES_AGENT ?? "root");
+}
+/** The current model's home name, live-resolved from ctx.model; "default" when unknown. */
+export function modelSlug(ctx) {
+    const id = ctx.model?.id;
+    if (!id)
+        return "default";
+    return slugify(id.split("/").pop() ?? id);
+}
+/**
+ * Absolute directory holding every note of one scope. `who` names an agent or model
+ * home absolutely; omitted, the current one resolves (agent from PI_NOTES_AGENT,
+ * model live from ctx.model).
+ */
+export function scopeDir(scope, ctx, who) {
+    if (scope === "human")
+        return join(notesRoot(), "human");
     if (scope === "project")
         return join(notesRoot(), "project", projectKey(ctx.cwd));
+    if (scope === "agent")
+        return join(notesRoot(), "agents", who ?? agentSlug(ctx));
+    if (scope === "model")
+        return join(notesRoot(), "models", who ?? modelSlug(ctx));
     return join(sessionHomesRoot(), sessionId(ctx));
 }
+/**
+ * One-time migration of the pre-v0.25 `personal/` home to `human/`. Runs at extension
+ * activation; returns a warning string when both directories exist (no auto-merge),
+ * undefined otherwise. Old note bodies are history, not addresses, and stay untouched.
+ */
+export function migrateLegacyHomes(home = notesRoot()) {
+    const legacy = join(home, "personal");
+    const modern = join(home, "human");
+    if (!existsSync(legacy))
+        return undefined;
+    if (existsSync(modern))
+        return "both personal/ and human/ exist under the notes home; migrate by hand, no automatic merge";
+    renameSync(legacy, modern);
+    return undefined;
+}
+/** Every existing home directory of the agents/ or models/ namespace, as slugs. */
+export function namespaceSlugs(namespace, home = notesRoot()) {
+    try {
+        return readdirSync(join(home, namespace), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
 /**
  * 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.
@@ -53,6 +110,6 @@ 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("/"));
+export function physicalPath(scope, vpath, ctx, who) {
+    return join(scopeDir(scope, ctx, who), ...noteFileName(vpath).split("/"));
 }

package/dist/src/notes/session-replay.js

@@ -0,0 +1,41 @@
+import { MAX_NOTE_BYTES, NOTE_TYPE } from "../protocol.js";
+import { assertVirtualPath } from "./address.js";
+/** 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;
+}

package/dist/src/notes/store.js

@@ -2,11 +2,10 @@ 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 "./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 { addressFor, assertGlobPattern, assertVirtualPath, globToRegExp } from "./address.js";
+import { agentSlug, modelSlug, namespaceSlugs, 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 {
@@ -21,10 +20,10 @@ export class NoteError extends Error {
         this.edit_index = extra.edit_index;
     }
 }
-const SCOPE_ORDER = ["session", "project", "personal"];
+const SCOPE_ORDER = ["session", "project", "human", "agent", "model"];
 function assertScope(value) {
     if (!isScope(value))
-        throw new NoteError("invalid_scope", `scope must be one of session, project, personal (got ${JSON.stringify(value)})`);
+        throw new NoteError("invalid_scope", `scope must be one of session, project, human, agent, model (got ${JSON.stringify(value)})`);
     return value;
 }
 function assertOrigin(value) {
@@ -38,8 +37,13 @@ function walkMarkdown(dir, base = dir) {
     try {
         entries = readdirSync(dir, { withFileTypes: true });
     }
-    catch {
-        return [];
+    catch (error) {
+        // A home that has never been created is normal. Every other directory
+        // failure must reach the boot snapshot boundary instead of masquerading as
+        // an empty home.
+        if (typeof error === "object" && error !== null && error.code === "ENOENT")
+            return [];
+        throw error;
     }
     const paths = [];
     for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
@@ -87,6 +91,52 @@ function assertSerializedSize(content) {
 function frontmatterOf(meta) {
     return serializeNote(meta, "").slice(0, -2);
 }
+/** Named agent/model homes are read-only to whoever is not running there. */
+function assertWritableHome(scope, who, ctx) {
+    if (who === undefined)
+        return;
+    const current = scope === "agent" ? agentSlug(ctx) : modelSlug(ctx);
+    if (who === current)
+        return;
+    const home = scope === "agent" ? `@agents/${who}/` : `@models/${who}/`;
+    throw new NoteError("invalid_scope", `${home} is not your home: writable homes are this session, @project/, @human/, @self/, and the current @model/ home`);
+}
+function homesForPattern(pattern) {
+    if (!pattern || !pattern.startsWith("@"))
+        return undefined;
+    const head = /^@([^/]+)\//.exec(pattern)?.[1];
+    if (head === "project")
+        return [{ scope: "project" }];
+    if (head === "human")
+        return [{ scope: "human" }];
+    if (head === "self")
+        return [{ scope: "agent" }];
+    if (head === "model")
+        return [{ scope: "model" }];
+    if (head === "agents" || head === "models") {
+        const scope = head === "agents" ? "agent" : "model";
+        const name = pattern.slice(head.length + 2).split("/")[0] ?? "";
+        if (name.length > 0 && !/[*?]/.test(name))
+            return [{ scope, who: name }];
+        return namespaceSlugs(head).map((who) => ({ scope, who }));
+    }
+    return [];
+}
+/** Relative pattern heads resolve to canonical names, so they match rendered addresses. */
+function normalizePattern(pattern, ctx) {
+    if (!pattern)
+        return pattern;
+    if (pattern.startsWith("@self/"))
+        return `@agents/${agentSlug(ctx)}/${pattern.slice("@self/".length)}`;
+    if (pattern.startsWith("@model/"))
+        return `@models/${modelSlug(ctx)}/${pattern.slice("@model/".length)}`;
+    return pattern;
+}
+function homesFor(ctx, opts) {
+    if (opts.scope !== undefined)
+        return [{ scope: opts.scope, who: opts.who }];
+    return homesForPattern(opts.pattern) ?? SCOPE_ORDER.map((scope) => ({ scope }));
+}
 /** Line numbers (1-based) of every occurrence of `needle` in `body`. */
 function matchLineNumbers(body, needle) {
     const lines = [];
@@ -105,8 +155,9 @@ export function writeNote(ctx, vpath, body, opts) {
     assertVirtualPath(vpath);
     assertWritablePath(vpath);
     const scope = assertScope(opts.scope);
+    assertWritableHome(scope, opts.who, ctx);
     const origin = assertOrigin(opts.origin);
-    const path = physicalPath(scope, vpath, ctx);
+    const path = physicalPath(scope, vpath, ctx, opts.who);
     const now = Date.now();
     const cleanBody = stripLeadingFrontmatter(body);
     const existing = existsSync(path) ? parseNote(readFileSync(path, "utf8"), now).meta : undefined;
@@ -131,9 +182,9 @@ export function writeNote(ctx, vpath, body, opts) {
     return { meta };
 }
 /** Dream harness mutation: metadata changes still use the store's atomic writer. */
-export function updateNoteMeta(ctx, vpath, scope, mutate) {
+export function updateNoteMeta(ctx, vpath, scope, mutate, who) {
     assertVirtualPath(vpath);
-    const path = physicalPath(scope, vpath, ctx);
+    const path = physicalPath(scope, vpath, ctx, who);
     if (!existsSync(path))
         throw new NoteError("not_found", `note not found: ${vpath}`);
     const parsed = parseNote(readFileSync(path, "utf8"));
@@ -146,14 +197,15 @@ export function updateNoteMeta(ctx, vpath, scope, mutate) {
     return { meta, body: parsed.body };
 }
 /** Apply body-only edits against one explicit home; origin and stale are its metadata setters. */
-export function editNote(ctx, vpath, scope, edits, opts = {}) {
+export function editNote(ctx, vpath, scope, edits, opts = {}, who) {
     assertVirtualPath(vpath);
     assertWritablePath(vpath);
+    assertWritableHome(scope, who, ctx);
     const operations = edits ?? [];
     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 path = physicalPath(scope, vpath, ctx);
+    const path = physicalPath(scope, vpath, ctx, who);
     if (!existsSync(path))
         throw new NoteError("not_found", "note not found");
     const raw = readFileSync(path, "utf8");
@@ -216,9 +268,9 @@ function accessedMeta(meta, scope, now) {
     return next;
 }
 /** Read a note and, as a side effect, bump last_accessed/access_count in the file. */
-export function readNote(ctx, vpath, scope) {
+export function readNote(ctx, vpath, scope, who) {
     assertVirtualPath(vpath);
-    const path = physicalPath(scope, vpath, ctx);
+    const path = physicalPath(scope, vpath, ctx, who);
     if (!existsSync(path))
         return undefined;
     const now = Date.now();
@@ -230,12 +282,13 @@ export function readNote(ctx, vpath, scope) {
 }
 /** Merged rows across homes, most recently updated first (address breaks ties). */
 export function listNotes(ctx, opts = {}) {
-    const matcher = matcherFor(opts.pattern);
+    const matcher = matcherFor(normalizePattern(opts.pattern, ctx));
     const rows = [];
-    for (const scope of opts.scope === undefined ? SCOPE_ORDER : [opts.scope]) {
-        const root = scopeDir(scope, ctx);
+    for (const home of homesFor(ctx, opts)) {
+        const scope = home.scope;
+        const root = scopeDir(scope, ctx, home.who);
         for (const path of walkMarkdown(root)) {
-            const address = addressFor(scope, path);
+            const address = addressFor(ctx, scope, path, home.who);
             if (matcher && !matcher.test(address))
                 continue;
             const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));
@@ -248,12 +301,13 @@ export function listNotes(ctx, opts = {}) {
 }
 /** 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 matcher = matcherFor(normalizePattern(opts.pattern, ctx));
     const rows = [];
-    for (const scope of opts.scope === undefined ? SCOPE_ORDER : [opts.scope]) {
-        const root = scopeDir(scope, ctx);
+    for (const home of homesFor(ctx, opts)) {
+        const scope = home.scope;
+        const root = scopeDir(scope, ctx, home.who);
         for (const path of walkMarkdown(root)) {
-            const address = addressFor(scope, path);
+            const address = addressFor(ctx, scope, path, home.who);
             if (matcher && !matcher.test(address))
                 continue;
             const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));