@astrosheep/pi-context 0.25.1 → 0.26.0

package/src/index.ts

@@ -1,13 +1,13 @@
 import { VERSION, type ExtensionAPI, type ExtensionFactory, type SettingsManager } from "@earendil-works/pi-coding-agent";
 import { registerHistoryTools } from "./history/history-tools.js";
-import { registerNotesTools } from "./notes/tools.js";
+import { registerNotesTools } from "./pi/notes/tools.js";
 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 { 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, WARNING_CONTENT } from "./protocol.js";
 import { assertVirtualPath } from "./notes/address.js";
 export { historyFromSession } from "./history/history.js";
-export { notesFromSession } from "./notes/session-replay.js";
+export { notesFromSession } from "./pi/notes/session-replay.js";
 
 function registerPiContext(pi: ExtensionAPI, settingsManager?: SettingsManager): void {
 	const [major, minor] = VERSION.split(".").map(Number);
@@ -32,4 +32,4 @@ export default function piContext(pi: ExtensionAPI): void {
 	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 };
+export const internal = { MAX_NOTE_BYTES, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, CONTINUATION_TYPE, WARNING_PROMPT, WARNING_CONTENT, 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/src/notes/address.ts

@@ -1,5 +1,5 @@
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { agentSlug, modelSlug, SLUG_PATTERN, type Scope } from "./paths.js";
+import type { NotesContext } from "./context.js";
+import { SLUG_PATTERN, type Scope } from "./paths.js";
 
 export type NoteAddress = { scope: Scope; path: string; who?: string };
 
@@ -39,7 +39,7 @@ export function globToRegExp(pattern: string): RegExp {
 	return new RegExp(`${source}$`);
 }
 
-/** Glob patterns are not virtual paths (`*` is legal), so they get their own guard: no NUL, no backslashes. */
+/** Glob patterns are not virtual paths (`*` is legal), so they get their own guard. */
 export function assertGlobPattern(value: unknown): string | undefined {
 	if (value === undefined || value === null || value === "") return undefined;
 	if (typeof value !== "string") throw new Error("glob pattern must be a string");
@@ -48,12 +48,8 @@ export function assertGlobPattern(value: unknown): string | undefined {
 }
 
 /**
- * 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.
+ * Decode one public note address into its physical home and virtual path. @self and @model
+ * are relative; explicit agents/models addresses always name a canonical slug.
  */
 export function assertAddress(value: unknown): NoteAddress {
 	if (typeof value !== "string") throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
@@ -87,13 +83,11 @@ export function assertAddress(value: unknown): NoteAddress {
 	return { scope, path, who };
 }
 
-/** 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: ExtensionContext, scope: Scope, path: string, who?: string): string {
+/** Render a virtual path in its one unambiguous public address form. */
+export function addressFor(context: NotesContext, scope: Scope, path: string, who?: string): string {
 	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}`;
+	if (scope === "agent") return `@agents/${who ?? context.agent}/${path}`;
+	return `@models/${who ?? context.model}/${path}`;
 }

package/src/notes/constants.ts

@@ -0,0 +1,3 @@
+export const MAX_NOTE_BYTES = 1_000_000;
+/** Write-time cap on a virtual note path. Reads and legacy replay stay uncapped. */
+export const MAX_NOTE_PATH_BYTES = 512;

package/src/notes/context.ts

@@ -0,0 +1,40 @@
+import { resolve } from "node:path";
+import { SLUG_PATTERN } from "./paths.js";
+
+/** Explicit, host-neutral identity for one notes store. */
+export type NotesContext = Readonly<{
+	home: string;
+	sessionId: string;
+	projectKey: string;
+	agent: string;
+	model: string;
+}>;
+
+function requireString(field: string, value: unknown): string {
+	if (typeof value !== "string" || value.length === 0) throw new TypeError(`notes context ${field} must be a non-empty string`);
+	return value;
+}
+
+function assertDirectoryComponent(field: string, value: string): void {
+	if (value === "." || value === ".." || /[\\/\0:]/.test(value)) {
+		throw new TypeError(`notes context ${field} must be a safe single directory component`);
+	}
+}
+
+/** Validate and snapshot caller identity; no global or environment defaults are consulted. */
+export function snapshotNotesContext(value: NotesContext): NotesContext {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError("notes context must be a plain object");
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) throw new TypeError("notes context must be a plain object");
+	const homeValue = requireString("home", value.home);
+	const sessionId = requireString("sessionId", value.sessionId);
+	const projectKey = requireString("projectKey", value.projectKey);
+	const agent = requireString("agent", value.agent);
+	const model = requireString("model", value.model);
+	assertDirectoryComponent("sessionId", sessionId);
+	assertDirectoryComponent("projectKey", projectKey);
+	if (!SLUG_PATTERN.test(agent)) throw new TypeError("notes context agent must be a canonical lowercase slug");
+	if (!SLUG_PATTERN.test(model)) throw new TypeError("notes context model must be a canonical lowercase slug");
+	const home = resolve(homeValue);
+	return Object.freeze({ home, sessionId, projectKey, agent, model });
+}

package/src/notes/frontmatter.ts

@@ -13,23 +13,26 @@ export type NoteMeta = {
 	origin: Origin;
 	status: NoteStatus;
 	stale: boolean;
-	created_at: number;
-	updated_at: number;
-	last_accessed: number;
-	access_count: number;
-	source_window?: string;
+	createdAt: number;
+	updatedAt: number;
+	lastAccessed: number;
+	accessCount: number;
+	sourceWindow?: string;
 	supersedes?: string;
-	recurrence_count?: number;
-	recurrence_windows?: string[];
+	recurrenceCount?: number;
+	recurrenceWindows?: string[];
+	/** Project ownership on newly-created session notes; legacy/invalid values are preserved as-is. */
+	project?: unknown;
 	[key: string]: unknown;
 };
 
 const SCOPES: readonly Scope[] = ["session", "project", "human", "agent", "model"];
 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;
+const TIMESTAMP_KEYS = ["createdAt", "updatedAt", "lastAccessed"] as const;
+const LEGACY_KNOWN_KEYS = ["created_at", "updated_at", "last_accessed", "access_count", "source_window", "recurrence_count", "recurrence_windows"] as const;
 /** 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"] as const;
+const KNOWN_KEYS = ["origin", "status", "stale", "createdAt", "updatedAt", "lastAccessed", "accessCount", "sourceWindow", "supersedes", "recurrenceCount", "recurrenceWindows"] as const;
 
 const pad2 = (value: number) => String(value).padStart(2, "0");
 
@@ -96,7 +99,7 @@ function parseFrontmatter(raw: string): { fields: Record<string, unknown>; body:
 		}
 	}
 	if (close === -1) return { fields: {}, body: raw };
-	const fields: Record<string, unknown> = {};
+	const fields = Object.create(null) as Record<string, unknown>;
 	for (let index = 1; index < close; index++) {
 		const line = lines[index]!;
 		const match = /^([A-Za-z_][A-Za-z0-9_-]*):(.*)$/.exec(line);
@@ -122,10 +125,13 @@ function parseFrontmatter(raw: string): { fields: Record<string, unknown>; body:
 
 /**
  * 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.
+ * accessCount 0, timestamps now); unknown keys are carried through untouched. Known
+ * snake_case metadata is refused because it requires the explicit manual migration.
  */
 export function parseNote(raw: string, now = Date.now()): { meta: NoteMeta; body: string } {
 	const { fields, body } = parseFrontmatter(raw);
+	const legacyKeys = LEGACY_KNOWN_KEYS.filter((key) => Object.hasOwn(fields, key));
+	if (legacyKeys.length > 0) throw new Error(`legacy note metadata ${legacyKeys.join(", ")} requires manual migration to camelCase before this note can be used`);
 	const meta = { ...fields } as Record<string, unknown>;
 	// 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.
@@ -134,7 +140,7 @@ export function parseNote(raw: string, now = Date.now()): { meta: NoteMeta; body
 	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;
+	meta.accessCount = typeof meta.accessCount === "number" && Number.isFinite(meta.accessCount) ? meta.accessCount : 0;
 	return { meta: meta as NoteMeta, body };
 }
 

package/src/notes/index.ts

@@ -0,0 +1,22 @@
+export { createNotesStore, NoteError } from "./store.js";
+export { projectKey, slugify } from "./paths.js";
+export type { NotesContext } from "./context.js";
+export type {
+	EditOperation,
+	EditOptions,
+	NoteChange,
+	NoteEditResult,
+	NoteErrorCode,
+	NoteMatch,
+	NoteMeta,
+	NoteReadResult,
+	NoteRow,
+	NoteSearchRow,
+	NoteStatus,
+	NoteWriteResult,
+	NotesQuery,
+	NotesStore,
+	Origin,
+	Scope,
+	WriteOptions,
+} from "./store.js";

package/src/notes/paths.ts

@@ -1,34 +1,18 @@
 import { createHash } from "node:crypto";
-import { existsSync, readdirSync, renameSync } from "node:fs";
-import { homedir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import type { NotesContext } from "./context.js";
 
 export type Scope = "session" | "project" | "human" | "agent" | "model";
 
-/** Physical home of the on-disk note store: $PI_NOTES_HOME or ~/.agents/notes. */
-export function notesRoot(): string {
-	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()): string {
-	return join(home, "pi", "session");
-}
+/** 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]+)*$/;
 
-/**
- * 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: string): string | undefined {
-	let dir = resolve(cwd);
-	for (;;) {
-		if (existsSync(join(dir, ".git"))) return dir;
-		const parent = dirname(dir);
-		if (parent === dir) return undefined;
-		dir = parent;
-	}
+/** Slugify a caller-declared identity; identity is never inferred from note content. */
+export function slugify(value: string): string {
+	const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+	return slug.length > 0 ? slug : "root";
 }
 
 /** `<basename(absGitRoot)-sha1(absGitRoot)[:8]>`, or the same formula over cwd with no git root. */
@@ -39,67 +23,67 @@ export function projectKey(cwd: string): string {
 	return `${basename(root)}-${digest}`;
 }
 
-/** Session identity comes from the pi session manager; ids are filesystem-safe by construction. */
-function sessionId(ctx: ExtensionContext): string {
-	return ctx.sessionManager.getSessionId();
-}
-
-/** 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-].
+ * Repository root behind one `.git` entry. A `.git` directory is the main checkout
+ * itself. A `.git` file is a worktree or submodule pointer: a linked worktree names
+ * `<main>/.git/worktrees/<name>` and resolves to `<main>`, so every worktree of one
+ * repository shares one project identity. Submodules, bare repositories, and separate
+ * git dirs keep the current directory.
  */
-export function slugify(value: string): string {
-	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: ExtensionContext): string {
-	return slugify(process.env.PI_NOTES_AGENT ?? "root");
+function repositoryRoot(dir: string): string {
+	let stats;
+	try {
+		stats = statSync(join(dir, ".git"));
+	} catch {
+		return dir;
+	}
+	if (stats.isDirectory()) return dir;
+	let pointer: string;
+	try {
+		pointer = readFileSync(join(dir, ".git"), "utf8");
+	} catch {
+		return dir;
+	}
+	const match = /^gitdir:\s*(.+)$/m.exec(pointer);
+	if (!match) return dir;
+	const parts = resolve(dir, match[1]!.trim()).split(sep);
+	const worktrees = parts.lastIndexOf("worktrees");
+	if (worktrees <= 0 || worktrees !== parts.length - 2) return dir;
+	const common = parts.slice(0, worktrees).join(sep);
+	return basename(common) === ".git" ? dirname(common) : dir;
 }
 
-/** The current model's home name, live-resolved from ctx.model; "default" when unknown. */
-export function modelSlug(ctx: ExtensionContext): string {
-	const id = ctx.model?.id;
-	if (!id) return "default";
-	return slugify(id.split("/").pop() ?? id);
+/** Absolute repository root for cwd, walking upward until a directory holds a `.git` entry. */
+function gitRoot(cwd: string): string | undefined {
+	let dir = resolve(cwd);
+	for (;;) {
+		if (existsSync(join(dir, ".git"))) return repositoryRoot(dir);
+		const parent = dirname(dir);
+		if (parent === dir) return undefined;
+		dir = parent;
+	}
 }
 
-/**
- * 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: Scope, ctx: ExtensionContext, who?: string): string {
-	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));
+/** Absolute directory holding the per-session note homes. */
+export function sessionHomesRoot(home: string): string {
+	return join(home, "pi", "session");
 }
 
-/**
- * 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()): string | undefined {
-	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;
+/** Absolute directory holding one scope's notes. The context's home is already resolved. */
+export function scopeDir(scope: Scope, context: NotesContext, who?: string): string {
+	if (!["session", "project", "human", "agent", "model"].includes(scope)) throw new TypeError("invalid notes scope");
+	if (who !== undefined && (scope !== "agent" && scope !== "model" || !SLUG_PATTERN.test(who))) throw new TypeError("who must be a canonical agent/model slug");
+	if (scope === "human") return join(context.home, "human");
+	if (scope === "project") return join(context.home, "project", context.projectKey);
+	if (scope === "agent") return join(context.home, "agents", who ?? context.agent);
+	if (scope === "model") return join(context.home, "models", who ?? context.model);
+	return join(sessionHomesRoot(context.home), context.sessionId);
 }
 
-/** Every existing home directory of the agents/ or models/ namespace, as slugs. */
-export function namespaceSlugs(namespace: "agents" | "models", home = notesRoot()): string[] {
+/** Every existing home directory of the agents/ or models/ namespace, as names. */
+export async function namespaceSlugs(namespace: "agents" | "models", home: string): Promise<string[]> {
 	try {
-		return readdirSync(join(home, namespace), { withFileTypes: true })
+		return (await readdir(join(home, namespace), { withFileTypes: true }))
 			.filter((entry) => entry.isDirectory())
 			.map((entry) => entry.name)
 			.sort();
@@ -117,6 +101,8 @@ export function noteFileName(vpath: string): string {
 }
 
 /** Absolute file path for a virtual path in a scope. Callers validate the vpath first. */
-export function physicalPath(scope: Scope, vpath: string, ctx: ExtensionContext, who?: string): string {
-	return join(scopeDir(scope, ctx, who), ...noteFileName(vpath).split("/"));
+export function physicalPath(scope: Scope, vpath: string, context: NotesContext, who?: string): string {
+	if (typeof vpath !== "string" || vpath.length === 0 || vpath.includes("\0") || vpath.includes("\\") || vpath.startsWith("/")) throw new TypeError("path must be a safe virtual relative path");
+	if (vpath.split("/").some((part) => part.length === 0 || part === "." || part === "..")) throw new TypeError("path contains an unsupported component");
+	return join(scopeDir(scope, context, who), ...noteFileName(vpath).split("/"));
 }