@astrosheep/pi-context 0.23.1 → 0.25.0

package/dist/extension.js

@@ -0,0 +1,1861 @@
+// <define:__PI_CONTEXT_BUILD__>
+var define_PI_CONTEXT_BUILD_default = { version: "0.25.0", sourceHash: "8a2495924871c544d2919a9301b6017c61ebe0c4bc38242b7e8c5b95d50f8df3" };
+
+// src/index.ts
+import { VERSION as VERSION2 } from "@earendil-works/pi-coding-agent";
+
+// src/history/history-tools.ts
+import { Type as Type2 } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+
+// src/tool-output.ts
+var TOOL_OUTPUT_MAX_BYTES = 32 * 1024;
+var DEFAULT_READ_WINDOW_CHARS = 12e3;
+var MAX_READ_WINDOW_CHARS = 5e4;
+var HISTORY_PREVIEW_CHARS = 1200;
+function json(value) {
+  return JSON.stringify(value, null, 2);
+}
+function withinBudget(value, budget = TOOL_OUTPUT_MAX_BYTES) {
+  return Buffer.byteLength(json(value), "utf8") <= budget;
+}
+function withinTextBudget(text, budget = TOOL_OUTPUT_MAX_BYTES) {
+  return Buffer.byteLength(text, "utf8") <= budget;
+}
+function truncationMarker(removedChars) {
+  return `\u2026[truncated ${removedChars} chars]\u2026`;
+}
+function middleTruncate(text, fits) {
+  if (fits(text)) return text;
+  const chars = Array.from(text);
+  const build = (kept) => {
+    const head = Math.ceil(kept / 2);
+    return chars.slice(0, head).join("") + truncationMarker(chars.length - kept) + chars.slice(chars.length - (kept - head)).join("");
+  };
+  let low = 0;
+  let high = chars.length;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (fits(build(mid))) low = mid;
+    else high = mid - 1;
+  }
+  return build(low);
+}
+function prefixFit(text, fits) {
+  if (fits(text)) return text;
+  const chars = Array.from(text);
+  let low = 0;
+  let high = chars.length;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (fits(chars.slice(0, mid).join(""))) low = mid;
+    else high = mid - 1;
+  }
+  while (low > 0 && !fits(chars.slice(0, low).join(""))) low -= 1;
+  return chars.slice(0, low).join("");
+}
+function readCharacterWindow(text, offsetChars, limitChars, render, measure = withinBudget) {
+  const chars = Array.from(text);
+  const requested = offsetChars ?? 0;
+  const resolved = requested < 0 ? Math.max(0, chars.length + requested) : Math.max(0, requested);
+  const windowChars = chars.slice(resolved, resolved + Math.min(limitChars ?? DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS));
+  const build = (content2) => {
+    const next = resolved + Array.from(content2).length;
+    return { offset_chars: resolved, content: content2, total_chars: chars.length, next_offset_chars: next < chars.length ? next : null };
+  };
+  const content = prefixFit(windowChars.join(""), (candidate) => measure(render(build(candidate))));
+  return render(build(content));
+}
+function readWindowBlock(identity, window) {
+  const end = window.offset_chars + Array.from(window.content).length;
+  const next = window.next_offset_chars === null ? "null" : String(window.next_offset_chars);
+  const fields = identity.map(([name, value]) => `${name}: ${value}`).join("\n");
+  return `--- READ WINDOW ---
+${fields}
+chars: [${window.offset_chars},${end}) of ${window.total_chars}
+next_offset_chars: ${next}
+`;
+}
+function earliestMatchOffsetChars(text, queries) {
+  let earliest = -1;
+  for (const query of queries) {
+    const index = text.indexOf(query);
+    if (index < 0) continue;
+    if (earliest < 0 || index < earliest) earliest = index;
+  }
+  return earliest <= 0 ? 0 : Array.from(text.slice(0, earliest)).length;
+}
+function page(items, cursor2, key, limit, truncate) {
+  const end = Math.min(items.length, cursor2 + (limit ?? items.length));
+  const selected = [];
+  let next = end < items.length ? end : null;
+  for (let index = cursor2; index < end; index++) {
+    const candidateNext = index + 1 < end || end < items.length ? index + 1 : null;
+    const fits = (list) => withinBudget({ [key]: list, next_cursor: candidateNext });
+    if (!fits([...selected, items[index]])) {
+      if (selected.length === 0 && truncate) {
+        selected.push(truncate(items[index], (candidate) => fits([candidate])));
+        next = candidateNext;
+      } else {
+        next = index;
+      }
+      break;
+    }
+    selected.push(items[index]);
+  }
+  return { [key]: selected, next_cursor: next };
+}
+function output(value, details, terminate = false) {
+  return { content: [{ type: "text", text: json(value) }], details, terminate };
+}
+function outputRaw(header, content, details, terminate = false) {
+  return { content: [{ type: "text", text: `${header}
+${content}` }], details, terminate };
+}
+
+// src/tool-schema.ts
+import { Type } from "@earendil-works/pi-ai";
+var nullableString = () => Type.Optional(Type.Union([Type.String(), Type.Null()]));
+var positiveInteger = () => Type.Optional(Type.Integer({ minimum: 1 }));
+var cursor = () => Type.Optional(Type.Integer({ minimum: 0, description: "Continuation cursor: pass the previous next_cursor back unchanged, with the same filters and ordering. Omit to start. next_cursor is null only when the set is exhausted." }));
+var recentFirst = () => Type.Optional(Type.Boolean({ description: "Return newest-first. Only an explicit false returns oldest-first. Defaults to true." }));
+var role = Type.Union([Type.Literal("user"), Type.Literal("assistant"), Type.Literal("tool_call"), Type.Literal("tool"), Type.Literal("system"), Type.Literal("developer"), Type.Null()], { description: `Filter by the item's role. Exactly six: "user" and "assistant" are a message's visible text (assistant text never contains tool calls); "tool_call" is one tool invocation (tool_name set, content = the call's JSON arguments); "tool" is one tool run's output (tool_name set); "system" is a native Pi compaction or branch summary; "developer" is an entry this extension authored (boot, guidance, warning, continuation messages, or any pi-context/* custom message).` });
+var searchQuery = () => Type.Union([Type.String(), Type.Array(Type.String(), { minItems: 1 })]);
+function searchQueries(query) {
+  const candidates = typeof query === "string" ? [query] : query;
+  if (!Array.isArray(candidates) || candidates.length === 0) throw new Error("query must be a string or a non-empty array of strings");
+  if (!candidates.every((candidate) => typeof candidate === "string")) throw new Error("query array elements must be strings");
+  if (candidates.some((candidate) => candidate === "")) throw new Error("query strings must be non-empty: an empty query matches everything");
+  return candidates;
+}
+
+// src/context/context-window.ts
+import { getCurrentSystemMessage } from "@earendil-works/pi-ai";
+
+// node_modules/@earendil-works/pi-ai/dist/utils/text.js
+function contentText(content, separator = "\n") {
+  if (typeof content === "string")
+    return content;
+  return content.filter((block) => block.type === "text").map((block) => block.text).join(separator);
+}
+function getSystemMessageText(message) {
+  const parts = [contentText(message.content)];
+  for (const text of Object.values(message.sections ?? {})) {
+    if (text !== null)
+      parts.push(text);
+  }
+  return parts.filter((part) => part.length > 0).join("\n\n");
+}
+
+// node_modules/@earendil-works/pi-ai/dist/utils/estimate.js
+var CHARS_PER_TOKEN = 4;
+var ESTIMATED_IMAGE_CHARS = 4800;
+function calculateContextTokens(usage) {
+  return usage.totalTokens || usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
+}
+function safeJsonStringify(value) {
+  try {
+    return JSON.stringify(value) ?? "undefined";
+  } catch {
+    return "[unserializable]";
+  }
+}
+function estimateTextAndImageContentChars(content) {
+  if (typeof content === "string")
+    return content.length;
+  let chars = 0;
+  for (const block of content)
+    chars += block.type === "text" ? block.text.length : ESTIMATED_IMAGE_CHARS;
+  return chars;
+}
+function estimateTextTokens(text) {
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+function estimateTextAndImageContentTokens(content) {
+  return Math.ceil(estimateTextAndImageContentChars(content) / CHARS_PER_TOKEN);
+}
+function estimateMessageTokens(message) {
+  let chars = 0;
+  if (message.role === "system") {
+    return estimateTextTokens(getSystemMessageText(message)) + estimateToolsTokens(message.toolsAdded) + estimateToolsTokens(message.toolsRemoved);
+  }
+  if (message.role === "user")
+    return estimateTextAndImageContentTokens(message.content);
+  if (message.role === "toolResult")
+    return estimateTextAndImageContentTokens(message.content);
+  for (const block of message.content) {
+    if (block.type === "text") {
+      chars += block.text.length;
+    } else if (block.type === "thinking") {
+      chars += block.thinking.length;
+    } else {
+      chars += block.name.length + safeJsonStringify(block.arguments).length;
+    }
+  }
+  return Math.ceil(chars / CHARS_PER_TOKEN);
+}
+function getLastAssistantUsageInfo(messages) {
+  let latestPrefixTimestamp = Number.NEGATIVE_INFINITY;
+  let usageInfo;
+  for (let i = 0; i < messages.length; i++) {
+    const message = messages[i];
+    if (message.role === "assistant") {
+      const assistant = message;
+      const usageAppliesToPrefix = assistant.timestamp >= latestPrefixTimestamp;
+      if (usageAppliesToPrefix && assistant.stopReason !== "aborted" && assistant.stopReason !== "error" && calculateContextTokens(assistant.usage) > 0) {
+        usageInfo = { usage: assistant.usage, index: i };
+      }
+    }
+    latestPrefixTimestamp = Math.max(latestPrefixTimestamp, message.timestamp);
+  }
+  return usageInfo;
+}
+function estimateContextTokens(context) {
+  const messages = "messages" in context ? context.messages : context;
+  const usageInfo = getLastAssistantUsageInfo(messages);
+  if (usageInfo) {
+    const usageTokens = calculateContextTokens(usageInfo.usage);
+    let trailingTokens = 0;
+    for (let i = usageInfo.index + 1; i < messages.length; i++) {
+      trailingTokens += estimateMessageTokens(messages[i]);
+    }
+    return { tokens: usageTokens + trailingTokens, usageTokens, trailingTokens, lastUsageIndex: usageInfo.index };
+  }
+  let tokens = 0;
+  for (const message of messages)
+    tokens += estimateMessageTokens(message);
+  return { tokens, usageTokens: 0, trailingTokens: tokens, lastUsageIndex: null };
+}
+function estimateToolsTokens(tools) {
+  if (!tools || tools.length === 0)
+    return 0;
+  return estimateTextTokens(safeJsonStringify(tools));
+}
+
+// src/context/context-window.ts
+import { convertToLlm } from "@earendil-works/pi-coding-agent";
+
+// src/protocol.ts
+var NOTE_TYPE = "pi-context/note";
+var BOOT_TYPE = "pi-context/boot";
+var GUIDANCE_TYPE = "pi-context/guidance";
+var WARNING_TYPE = "pi-context/warning";
+var RESET_MARKER_TYPE = "pi-context/reset-marker";
+var CONTINUATION_TYPE = "pi-context/continuation";
+var MAX_NOTE_BYTES = 1e6;
+var POCKET_SESSION_LIMIT = 5;
+var POCKET_PROJECT_LIMIT = 2;
+var POCKET_HUMAN_LIMIT = 2;
+var POCKET_AGENT_LIMIT = 1;
+var POCKET_MODEL_LIMIT = 1;
+var MAX_NOTE_PATH_BYTES = 512;
+var CONTEXT_WINDOW_OPEN_TAG = "<context_window>";
+var CONTEXT_WINDOW_CLOSE_TAG = "</context_window>";
+var CONTEXT_WINDOW_PROTOCOL_OPEN_TAG = "<context_window_protocol>";
+var CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG = "</context_window_protocol>";
+var GUIDANCE_OPEN_TAG = "<context_window_guidance>";
+var GUIDANCE_CLOSE_TAG = "</context_window_guidance>";
+var PI_CONTEXT_SETTINGS_KEY = "pi-context";
+var DEFAULT_RESERVE_TOKENS = 16384;
+var DEFAULT_REMINDER_MARGIN_TOKENS = 24576;
+var WARNING_RUNWAY_TOKENS = 12288;
+var RESET_SUMMARY = "You wake up. Your head is empty \u2014 no memories, the past a blank. The memory is gone for good. What outlived it: the notes you wrote, and the history that was recorded. They are not your memory \u2014 read them to rebuild what you need.";
+var CONTINUATION = "Your memory was just erased. Pull only the details you need from history_* and notes_*, then get back to work.";
+var PROTOCOL_BLOCK = `${CONTEXT_WINDOW_PROTOCOL_OPEN_TAG}
+Your memory resets whenever the context window fills; only what you wrote down survives. Two things outlive every window in this session: the notes you wrote, and the history that was recorded. Neither is memory \u2014 both are record. Write notes with notes_write, revise them with notes_edit, and read them back with notes_read / notes_search / notes_list; history is read-only through the history_* tools. Everything else wakes blank.
+Mark outdated or unneeded notes stale \u2014 leave them, and they will keep misleading you.
+
+Keep a running checkpoint while you work, not at the last minute \u2014 the next window wakes knowing nothing about the work: the goal, decisions, progress, learnings, next steps, the skills you still need, the window ID and item ID of every relevant user request still being solved, and important actions/tool calls for future reference. history_list returns those IDs; history_read pulls the exact item back out. Bookmark anything expensive the same way \u2014 a window/item ID beats re-running or re-searching.
+
+Use get_context_remaining to see how much of the window is left. When it runs out, this window is gone \u2014 with no final turn at the limit \u2014 and you continue in a fresh one, recovering only through notes_* and history_*. Once your checkpoint is written, you can call wipe_memory yourself instead of waiting for the erase. Do not let a window die undocumented.
+
+If <context_window> lists a Previous context window id, a reset just happened and the old conversation is not included. Read your note checkpoint first, then recover details through history_*: history_read directly when you know the window and item IDs, history_list or history_search to find them when you don't.
+
+Notes live in five homes, and the word after @ is always one of their reserved names \u2014 your own name and other people's names live at the second level (@agents/faye/, never @faye/). Bare names are this session; @project/<vpath> is this project's workspace; @human/<vpath> is the human's cross-project home; @self/<vpath> and @agents/<name>/<vpath> are agent homes; @model/<vpath> and @models/<name>/<vpath> are model homes. @self and @model are the only relative forms \u2014 the current agent, the current model \u2014 and listings never show them, only the resolved name. There is no cross-home fallback.
+Session notes belong to this trip \u2014 the goal, the progress, the loose ends. The next window of THIS trip wakes to them; once the trip is over, nobody does.
+@project notes hold facts about this project \u2014 architecture, conventions, workflows, deployment and environment details \u2014 for whoever works here next.
+@human notes hold the human's durable preferences and standing rules, plus lessons that apply across projects \u2014 for every agent that serves this human, whoever is running. You write there as the human's scribe; what the human dictates carries origin: user. When the intended scope is unclear, keep the note in the narrowest stated scope rather than widening it.
+@self notes are yours \u2014 your voice, your lessons, your gripes \u2014 for the next run of whoever you are. Other agents read yours by explicit address and never write them; you read theirs the same way. A note only its author would ever need belongs here, not in @human.
+@model notes capture the substrate \u2014 how the current model actually behaves: context honesty, tool quirks, fallback patterns. @model resolves live, so what you learn on one model is filed under that model even when a fallback moves you mid-window.
+${CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG}`;
+var WARNING_PROMPT = "Your memory is about to be erased. Write the note. NOW. If it already exists, revise it with notes_edit (or rewrite it whole): the goal, decisions, progress, learnings, next steps, the skills you still need, the window ID and item ID of every relevant user request still being solved, and important actions/tool calls for future reference. Do not continue any task. Then call wipe_memory IMMEDIATELY \u2014 anything not in the note dies with the window.";
+
+// src/context/context-window.ts
+function isWindowMarker(entry) {
+  return entry.type === "custom" && entry.customType === RESET_MARKER_TYPE && typeof entry.data === "object" && entry.data !== null && typeof entry.data.windowId === "string" && entry.data.windowId.length > 0;
+}
+function currentReset(ctx) {
+  const branch = ctx.sessionManager.getBranch();
+  for (let i = branch.length - 1; i >= 0; i--) {
+    const entry = branch[i];
+    if (entry && isWindowMarker(entry)) return entry;
+  }
+  return void 0;
+}
+function rootWindowId(sessionId2) {
+  return `pcw:${sessionId2.slice(0, 8)}:root`;
+}
+function hasWindowMessage(ctx, customType) {
+  const branch = ctx.sessionManager.getBranch();
+  for (let i = branch.length - 1; i >= 0; i--) {
+    const entry = branch[i];
+    if (isWindowMarker(entry)) break;
+    if (entry.type === "custom_message" && entry.customType === customType) return true;
+  }
+  return false;
+}
+function currentWindowId(ctx) {
+  return currentReset(ctx)?.data.windowId ?? rootWindowId(ctx.sessionManager.getSessionId());
+}
+function hasWindowId(details, windowId) {
+  return typeof details === "object" && details !== null && typeof details.windowId === "string" && details.windowId === windowId;
+}
+function isWindowBoot(message, windowId) {
+  return message.role === "custom" && message.customType === BOOT_TYPE && (windowId === void 0 || hasWindowId(message.details, windowId));
+}
+function projectWindow(messages, windowId) {
+  const cut = messages.findIndex((message) => isWindowBoot(message, windowId));
+  if (cut < 0) throw new Error(`Missing boot for context window ${windowId}`);
+  const head = getCurrentSystemMessage(messages.slice(0, cut));
+  const suffix = messages.slice(cut);
+  return head ? [head, ...suffix] : suffix;
+}
+function projectRootWindow(messages, windowId) {
+  const matching = messages.filter((message) => isWindowBoot(message, windowId));
+  if (matching.length === 0) return messages;
+  const activeBoot = matching[matching.length - 1];
+  const firstBoot = messages.findIndex((message) => isWindowBoot(message));
+  const withoutBoots = messages.filter((message) => !isWindowBoot(message));
+  return [...withoutBoots.slice(0, firstBoot), activeBoot, ...withoutBoots.slice(firstBoot)];
+}
+function windowUsage(ctx) {
+  const reset = currentReset(ctx);
+  if (!reset) return ctx.getContextUsage();
+  const contextWindow = ctx.model?.contextWindow ?? ctx.getContextUsage()?.contextWindow;
+  if (!contextWindow) return void 0;
+  const windowId = reset.data.windowId;
+  try {
+    const messages = projectWindow(ctx.sessionManager.buildSessionProjection().messages, windowId);
+    const { tokens } = estimateContextTokens(convertToLlm(messages));
+    return { tokens, contextWindow, percent: tokens / contextWindow * 100 };
+  } catch {
+    return void 0;
+  }
+}
+
+// src/history/history.ts
+function isTextContent(part) {
+  return typeof part === "object" && part !== null && part.type === "text" && typeof part.text === "string";
+}
+function contentText2(content) {
+  if (typeof content === "string") return content;
+  return Array.isArray(content) ? content.filter(isTextContent).map((part) => part.text).join("\n") : "";
+}
+function mapRole(role2) {
+  if (role2 === "user" || role2 === "assistant") return role2;
+  if (role2 === "toolResult" || role2 === "bashExecution") return "tool";
+  if (role2 === "custom") return "user";
+  if (role2 === "compactionSummary" || role2 === "branchSummary") return "system";
+  return void 0;
+}
+var PI_CONTEXT_ENTRY_PREFIX = "pi-context/";
+function messageContent(message) {
+  switch (message.role) {
+    case "bashExecution":
+      return message.output ? `${message.command}
+${message.output}` : message.command;
+    case "branchSummary":
+    case "compactionSummary":
+      return message.summary;
+    default:
+      return contentText2(message.content);
+  }
+}
+function toolInfo(message) {
+  if (message.role === "bashExecution") {
+    return { toolName: "bash", outputTruncated: message.truncated || void 0, fullOutputPath: message.truncated ? message.fullOutputPath : void 0 };
+  }
+  if (message.role !== "toolResult") return {};
+  return { toolName: message.toolName, toolError: message.isError === true ? true : void 0 };
+}
+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;
+}
+function historyFromSession(ctx) {
+  const sessionId2 = ctx.sessionManager.getSessionId();
+  let window = { windowId: rootWindowId(sessionId2), items: [] };
+  const windows = [window];
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (isWindowMarker(entry)) {
+      window = { windowId: entry.data.windowId, createdAt: entry.timestamp, items: [] };
+      windows.push(window);
+      continue;
+    }
+    if (entry.type === "compaction" || entry.type === "branch_summary") {
+      window.items.push({
+        windowId: window.windowId,
+        itemId: entry.id,
+        role: "system",
+        content: entry.summary,
+        createdAt: entry.timestamp
+      });
+      continue;
+    }
+    if (entry.type === "message") {
+      const role2 = mapRole(entry.message.role);
+      if (!role2) continue;
+      window.items.push({
+        windowId: window.windowId,
+        itemId: entry.id,
+        role: role2,
+        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: contentText2(entry.content),
+        createdAt: entry.timestamp
+      });
+    }
+  }
+  return windows;
+}
+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
+  };
+}
+function allItems(ctx) {
+  return historyFromSession(ctx).flatMap((window) => window.items);
+}
+function unknownWindowId(ctx, params) {
+  if (typeof params.window_id !== "string") return void 0;
+  const known = historyFromSession(ctx).map((window) => window.windowId);
+  return known.includes(params.window_id) ? void 0 : { message: `unknown window_id "${params.window_id}"`, known };
+}
+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 void 0;
+}
+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;
+}
+
+// src/history/history-tools.ts
+function truncateHistoryItem(item, fits) {
+  if (fits(item)) return item;
+  const shrinkContent = (base) => ({
+    ...base,
+    truncated: true,
+    truncated_content: prefixFit(base.truncated_content, (candidate) => fits({ ...base, truncated: true, truncated_content: candidate }))
+  });
+  const withContent = shrinkContent(item);
+  if (fits(withContent)) return withContent;
+  if (item.tool_name === null) return withContent;
+  const withName = { ...item, tool_name: middleTruncate(item.tool_name, (candidate) => fits({ ...item, tool_name: candidate })) };
+  if (fits(withName)) return withName;
+  return shrinkContent(withName);
+}
+function registerHistoryTools(pi) {
+  pi.registerTool(defineTool({
+    name: "history_windows",
+    label: "History list windows",
+    description: "List durable Pi session-history windows.",
+    parameters: Type2.Object({ limit: positiveInteger(), recent_first: recentFirst() }, { additionalProperties: false }),
+    async execute(_id, params, _signal, _update, ctx) {
+      let windows = historyFromSession(ctx);
+      if (params.recent_first !== false) windows = [...windows].reverse();
+      const limit = params.limit ?? windows.length;
+      return output({ windows: windows.slice(0, limit).map((window) => ({ window_id: window.windowId, item_count: window.items.length })) });
+    }
+  }));
+  pi.registerTool(defineTool({
+    name: "history_list",
+    label: "History list items",
+    description: "List durable session items, including items from earlier reset windows, using opaque item and window IDs; native compaction and branch summaries remain history items in their current window. The role parameter's description enumerates the six roles. Every item carries truncated and total_chars: when truncated is true, truncated_content is a plain prefix of the item's content with no marker, and total_chars is its full code-point length. max_chars_per_item: 1 therefore yields pure addresses you can resolve with history_read.",
+    parameters: Type2.Object({ limit: positiveInteger(), cursor: cursor(), recent_first: recentFirst(), role: Type2.Optional(role), tool_name: nullableString(), window_id: nullableString(), max_chars_per_item: positiveInteger() }, { additionalProperties: false }),
+    async execute(_id, params, _signal, _update, ctx) {
+      const invalid = vacuousRoleToolCombo(params);
+      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 ?? HISTORY_PREVIEW_CHARS));
+      return output(page(items, params.cursor ?? 0, "items", params.limit, truncateHistoryItem));
+    }
+  }));
+  pi.registerTool(defineTool({
+    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 begins with the shared READ WINDOW block naming window_id and item_id; concatenate only the content after that block to reconstruct the item.",
+    parameters: Type2.Object({ item_id: Type2.String(), offset_chars: Type2.Optional(Type2.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: Type2.Optional(Type2.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: Type2.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" });
+      const totalChars = Array.from(item.content).length;
+      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 });
+      }
+      return readCharacterWindow(item.content, params.offset_chars, params.limit_chars, (window) => {
+        const { content, ...cursor2 } = window;
+        return outputRaw(readWindowBlock([["window_id", item.windowId], ["item_id", item.itemId]], window), content, { window_id: item.windowId, item_id: item.itemId, ...cursor2 });
+      }, (result) => withinTextBudget(result.content[0].text));
+    }
+  }));
+  pi.registerTool(defineTool({
+    name: "history_search",
+    label: "History search",
+    description: `Case-sensitive literal substring search over durable Pi session history; query accepts one string or an array of strings, an item matches when it contains any of them (OR), and each item appears once. No semantic search. Invocations and outputs are separate items (roles "tool_call" and "tool"), so both are searchable; the role parameter's description enumerates all six. Each hit carries truncated and total_chars plus match_offset_chars: the code-point offset of the earliest query occurrence in the item's full content. With max_chars_per_item: 1 the page is an address list; resolve an address with history_read at match_offset_chars.`,
+    parameters: Type2.Object({ limit: positiveInteger(), cursor: cursor(), query: searchQuery(), recent_first: recentFirst(), role: Type2.Optional(role), tool_name: nullableString(), window_id: nullableString(), max_chars_per_item: positiveInteger() }, { additionalProperties: false }),
+    async execute(_id, params, _signal, _update, ctx) {
+      const invalid = vacuousRoleToolCombo(params);
+      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 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 ?? HISTORY_PREVIEW_CHARS), match_offset_chars: earliestMatchOffsetChars(item.content, queries) }));
+      return output(page(matching, params.cursor ?? 0, "items", params.limit, truncateHistoryItem));
+    }
+  }));
+}
+
+// src/notes/tools.ts
+import { Type as Type3 } from "@earendil-works/pi-ai";
+import { defineTool as defineTool2 } from "@earendil-works/pi-coding-agent";
+
+// src/notes/frontmatter.ts
+var SCOPES = ["session", "project", "human", "agent", "model"];
+var ORIGINS = ["user", "self", "external"];
+var STATUSES = ["active", "superseded", "pending", "archived"];
+var TIMESTAMP_KEYS = ["created_at", "updated_at", "last_accessed"];
+var KNOWN_KEYS = ["origin", "status", "stale", "created_at", "updated_at", "last_accessed", "access_count", "source_window", "supersedes", "recurrence_count", "recurrence_windows"];
+var pad2 = (value) => String(value).padStart(2, "0");
+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}`;
+}
+function isScope(value) {
+  return typeof value === "string" && SCOPES.includes(value);
+}
+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;
+}
+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;
+  }
+}
+function parseFrontmatter(raw) {
+  const stripped = raw.charCodeAt(0) === 65279 ? 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 rest2 = match[2];
+    if (rest2.trim() === "") {
+      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(rest2);
+    }
+  }
+  const rest = lines.slice(close + 1);
+  if (rest[0] === "") rest.shift();
+  return { fields, body: rest.join("\n") };
+}
+function parseNote(raw, now = Date.now()) {
+  const { fields, body } = parseFrontmatter(raw);
+  const meta = { ...fields };
+  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;
+  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, body };
+}
+function yamlScalar(value) {
+  if (typeof value === "string") {
+    const reserved = /* @__PURE__ */ 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);
+}
+function serializeNote(meta, body) {
+  const lines = [];
+  for (const key of KNOWN_KEYS) {
+    const value = meta[key];
+    if (value === void 0) 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)) {
+    if (key === "scope" || KNOWN_KEYS.includes(key)) continue;
+    if (meta[key] === void 0) continue;
+    lines.push(`${key}: ${yamlScalar(meta[key])}`);
+  }
+  return `---
+${lines.join("\n")}
+---
+
+${body}`;
+}
+function stripLeadingFrontmatter(content) {
+  return parseFrontmatter(content).body;
+}
+
+// src/notes/paths.ts
+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";
+function notesRoot() {
+  const override = process.env.PI_NOTES_HOME;
+  return override && override.length > 0 ? resolve(override) : join(homedir(), ".agents", "notes");
+}
+function sessionHomesRoot(home = notesRoot()) {
+  return join(home, "pi", "session");
+}
+function gitRoot(cwd) {
+  let dir = resolve(cwd);
+  for (; ; ) {
+    if (existsSync(join(dir, ".git"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
+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}`;
+}
+function sessionId(ctx) {
+  return ctx.sessionManager.getSessionId();
+}
+var SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function slugify(value) {
+  const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug.length > 0 ? slug : "root";
+}
+function agentSlug(_ctx) {
+  return slugify(process.env.PI_NOTES_AGENT ?? "root");
+}
+function modelSlug(ctx) {
+  const id = ctx.model?.id;
+  if (!id) return "default";
+  return slugify(id.split("/").pop() ?? id);
+}
+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));
+}
+function migrateLegacyHomes(home = notesRoot()) {
+  const legacy = join(home, "personal");
+  const modern = join(home, "human");
+  if (!existsSync(legacy)) return void 0;
+  if (existsSync(modern)) return "both personal/ and human/ exist under the notes home; migrate by hand, no automatic merge";
+  renameSync(legacy, modern);
+  return void 0;
+}
+function namespaceSlugs(namespace, home = notesRoot()) {
+  try {
+    return readdirSync(join(home, namespace), { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+  } catch {
+    return [];
+  }
+}
+function noteFileName(vpath) {
+  return vpath.endsWith(".md") ? vpath : `${vpath}.md`;
+}
+function physicalPath(scope, vpath, ctx, who) {
+  return join(scopeDir(scope, ctx, who), ...noteFileName(vpath).split("/"));
+}
+
+// src/notes/address.ts
+var ADDRESS_FORMS = "legal prefixes are @project/, @human/, @self/, @agents/<name>/, @model/, and @models/<name>/; bare names are the session home";
+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;
+}
+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}$`);
+}
+function assertGlobPattern(value) {
+  if (value === void 0 || value === null || value === "") return void 0;
+  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;
+}
+function assertAddress(value) {
+  if (typeof value !== "string") throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+  let scope = "session";
+  let path = value;
+  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 === void 0) throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+  }
+  if (path.includes("@")) throw new Error(`invalid note address: ${ADDRESS_FORMS}`);
+  assertVirtualPath(path);
+  return { scope, path, who };
+}
+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}`;
+}
+
+// src/notes/store.ts
+import { randomUUID } from "node:crypto";
+import { existsSync as existsSync2, mkdirSync, readFileSync, readdirSync as readdirSync2, renameSync as renameSync2, rmSync, writeFileSync } from "node:fs";
+import { dirname as dirname2 } from "node:path";
+import { generateDiffString } from "@earendil-works/pi-coding-agent";
+var NoteError = class extends Error {
+  code;
+  line_numbers;
+  edit_index;
+  constructor(code, message, extra = {}) {
+    super(message);
+    this.name = "NoteError";
+    this.code = code;
+    this.line_numbers = extra.line_numbers;
+    this.edit_index = extra.edit_index;
+  }
+};
+var 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, human, agent, model (got ${JSON.stringify(value)})`);
+  return value;
+}
+function assertOrigin(value) {
+  if (!isOrigin(value)) throw new NoteError("invalid_origin", `origin must be one of user, self, external (got ${JSON.stringify(value)})`);
+  return value;
+}
+function walkMarkdown(dir, base = dir) {
+  let entries;
+  try {
+    entries = readdirSync2(dir, { withFileTypes: true });
+  } catch (error) {
+    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))) {
+    const child = `${dir}/${entry.name}`;
+    if (entry.isDirectory()) paths.push(...walkMarkdown(child, base));
+    else if (entry.isFile() && entry.name.endsWith(".md")) paths.push(child.slice(base.length + 1).split("\\").join("/"));
+  }
+  return paths;
+}
+function matcherFor(pattern) {
+  const normalized = assertGlobPattern(pattern);
+  return normalized === void 0 ? void 0 : globToRegExp(normalized);
+}
+function atomicWrite(path, content) {
+  mkdirSync(dirname2(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(tmp, content);
+    renameSync2(tmp, path);
+  } catch (error) {
+    rmSync(tmp, { force: true });
+    throw error;
+  }
+}
+function assertWritablePath(vpath) {
+  const bytes = Buffer.byteLength(vpath, "utf8");
+  if (bytes > MAX_NOTE_PATH_BYTES) throw new NoteError("too_large", `note path exceeds ${MAX_NOTE_PATH_BYTES} UTF-8 bytes (got ${bytes})`);
+}
+function assertSerializedSize(content) {
+  const bytes = Buffer.byteLength(content, "utf8");
+  if (bytes > MAX_NOTE_BYTES) throw new NoteError("too_large", `note exceeds ${MAX_NOTE_BYTES} UTF-8 bytes (serialized ${bytes})`);
+}
+function frontmatterOf(meta) {
+  return serializeNote(meta, "").slice(0, -2);
+}
+function assertWritableHome(scope, who, ctx) {
+  if (who === void 0) 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 void 0;
+  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 [];
+}
+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 !== void 0) return [{ scope: opts.scope, who: opts.who }];
+  return homesForPattern(opts.pattern) ?? SCOPE_ORDER.map((scope) => ({ scope }));
+}
+function matchLineNumbers(body, needle) {
+  const lines = [];
+  let cursor2 = 0;
+  for (; ; ) {
+    const index = body.indexOf(needle, cursor2);
+    if (index === -1) break;
+    lines.push(body.slice(0, index).split("\n").length);
+    cursor2 = index + Math.max(needle.length, 1);
+  }
+  return lines;
+}
+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, opts.who);
+  const now = Date.now();
+  const cleanBody = stripLeadingFrontmatter(body);
+  const existing = existsSync2(path) ? parseNote(readFileSync(path, "utf8"), now).meta : void 0;
+  const meta = existing ?? {
+    scope,
+    origin,
+    status: "active",
+    stale: false,
+    created_at: now,
+    updated_at: now,
+    last_accessed: now,
+    access_count: 0
+  };
+  meta.scope = scope;
+  meta.origin = origin;
+  meta.status = "active";
+  meta.stale = opts.stale ?? false;
+  meta.updated_at = now;
+  const serialized = serializeNote(meta, cleanBody);
+  assertSerializedSize(serialized);
+  atomicWrite(path, serialized);
+  return { meta };
+}
+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 === void 0 && opts.stale === void 0) {
+    throw new NoteError("nothing_to_do", "nothing to do: provide edits or at least one of origin, stale");
+  }
+  const path = physicalPath(scope, vpath, ctx, who);
+  if (!existsSync2(path)) throw new NoteError("not_found", "note not found");
+  const raw = readFileSync(path, "utf8");
+  const { meta, body } = parseNote(raw);
+  meta.scope = scope;
+  const beforeMeta = { ...meta };
+  let next = body;
+  operations.forEach((edit, index) => {
+    const oldText = edit?.oldText;
+    const newText = edit?.newText;
+    if (typeof oldText !== "string" || oldText.length === 0) throw new NoteError("no_match", `edit ${index}: oldText must be a non-empty string`, { edit_index: index });
+    if (typeof newText !== "string") throw new NoteError("no_match", `edit ${index}: newText must be a string`, { edit_index: index });
+    const lines = matchLineNumbers(next, oldText);
+    if (lines.length === 0) throw new NoteError("no_match", `edit ${index}: oldText does not occur in the note body`, { edit_index: index });
+    if (lines.length > 1 && !opts.replaceAll) {
+      throw new NoteError("ambiguous_edit", `edit ${index}: oldText occurs ${lines.length} times (lines ${lines.join(", ")}); pass replace_all to replace every occurrence`, { line_numbers: lines, edit_index: index });
+    }
+    if (opts.replaceAll) {
+      next = next.split(oldText).join(newText);
+    } else {
+      const matchIndex = next.indexOf(oldText);
+      next = next.substring(0, matchIndex) + newText + next.substring(matchIndex + oldText.length);
+    }
+  });
+  if (opts.origin !== void 0) meta.origin = assertOrigin(opts.origin);
+  if (opts.stale !== void 0) meta.stale = opts.stale;
+  meta.updated_at = Date.now();
+  const serialized = serializeNote(meta, next);
+  assertSerializedSize(serialized);
+  const bodyChanged = body !== next;
+  const metadataChanged = beforeMeta.origin !== meta.origin || beforeMeta.stale !== meta.stale;
+  const diff = bodyChanged && metadataChanged ? generateDiffString(raw, serialized).diff : bodyChanged ? generateDiffString(body, next).diff : metadataChanged ? generateDiffString(frontmatterOf(beforeMeta), frontmatterOf(meta)).diff : "";
+  atomicWrite(path, serialized);
+  return { meta, applied: operations.length, resolved_scope: scope, diff };
+}
+function accessedMeta(meta, scope, now) {
+  const next = { ...meta, scope };
+  next.last_accessed = now;
+  next.access_count = (typeof next.access_count === "number" ? next.access_count : 0) + 1;
+  return next;
+}
+function readNote(ctx, vpath, scope, who) {
+  assertVirtualPath(vpath);
+  const path = physicalPath(scope, vpath, ctx, who);
+  if (!existsSync2(path)) return void 0;
+  const now = Date.now();
+  const parsed = parseNote(readFileSync(path, "utf8"), now);
+  const meta = accessedMeta(parsed.meta, scope, now);
+  const text = serializeNote(meta, parsed.body);
+  atomicWrite(path, text);
+  return { meta, body: parsed.body, text, resolvedScope: scope };
+}
+function listNotes(ctx, opts = {}) {
+  const matcher = matcherFor(normalizePattern(opts.pattern, ctx));
+  const rows = [];
+  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(ctx, scope, path, home.who);
+      if (matcher && !matcher.test(address)) continue;
+      const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));
+      meta.scope = scope;
+      rows.push({ address, scope, path, meta, body, sizeBytes: Buffer.byteLength(body, "utf8") });
+    }
+  }
+  rows.sort((a, b) => b.meta.updated_at - a.meta.updated_at || a.address.localeCompare(b.address));
+  return rows;
+}
+function searchNotes(ctx, queries, opts = {}) {
+  const matcher = matcherFor(normalizePattern(opts.pattern, ctx));
+  const rows = [];
+  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(ctx, scope, path, home.who);
+      if (matcher && !matcher.test(address)) continue;
+      const { meta, body } = parseNote(readFileSync(`${root}/${path}`, "utf8"));
+      meta.scope = scope;
+      const serializedBodyOffset = Array.from(serializeNote(accessedMeta(meta, scope, Date.now()), "")).length;
+      let baseChars = 0;
+      const matches = [];
+      for (const [index, line] of body.split("\n").entries()) {
+        if (queries.some((query) => line.includes(query))) {
+          matches.push({ line: index + 1, text: line, offsetChars: serializedBodyOffset + baseChars + earliestMatchOffsetChars(line, queries) });
+        }
+        baseChars += Array.from(line).length + 1;
+      }
+      if (matches.length > 0) rows.push({ address, path, scope, meta, matches });
+    }
+  }
+  rows.sort((a, b) => a.address.localeCompare(b.address));
+  return rows;
+}
+
+// src/notes/tools.ts
+var ORIGIN = Type3.Optional(Type3.Union([Type3.Literal("user"), Type3.Literal("self"), Type3.Literal("external")], {
+  description: "Where the note's content came from. user: written or dictated by the human. self: written by you, the agent (default). external: anything else \u2014 third-party text, tool output, fetched material."
+}));
+var ADDRESS_DESCRIPTION = "Address forms are bare `<vpath>` for this session, `@project/<vpath>` for this project, `@human/<vpath>` for the human's cross-project home, `@self/<vpath>` / `@agents/<name>/<vpath>` for agent homes, and `@model/<vpath>` / `@models/<name>/<vpath>` for model homes. `@self` and `@model` mean the current agent/model; the `<name>` forms name one absolutely. The word after `@` is always one of the reserved home names \u2014 names live at the second level, never `@faye/`. `@` means leaving home. Any other `@` prefix, or `@` inside a vpath, is a hard error. There is no cross-home fallback. Paths reject `..`, absolute paths, and backslashes. Homes you do not own (`@agents/<other>/`, `@models/<other>/`) are read-only.";
+function failure(error) {
+  if (error instanceof NoteError) {
+    const payload = { error: error.message };
+    if (error.line_numbers) payload.line_numbers = error.line_numbers;
+    if (error.edit_index !== void 0) payload.edit_index = error.edit_index;
+    return output(payload);
+  }
+  throw error;
+}
+function registerNotesTools(pi) {
+  pi.registerTool(defineTool2({
+    name: "notes_write",
+    label: "Notes write",
+    description: `Create or replace a note as a real markdown file, and name it for what it holds: a fresh window sees only an index entry, never the note itself. ${ADDRESS_DESCRIPTION} Keep notes small and split by topic \u2014 by what the note is about, never by who said it (authorship is origin's job); a rewrite replaces the body whole while preserving created_at and every other frontmatter key. stale: true marks the note closed so it leaves the boot index but stays readable and searchable.`,
+    parameters: Type3.Object({ address: Type3.String(), content: Type3.String(), origin: ORIGIN, stale: Type3.Optional(Type3.Boolean()) }, { additionalProperties: false }),
+    executionMode: "sequential",
+    async execute(_id, params, _signal, _update, ctx) {
+      const content = params.content;
+      try {
+        const destination = assertAddress(params.address);
+        writeNote(ctx, destination.path, content, { scope: destination.scope, who: destination.who, origin: params.origin ?? "self", stale: params.stale });
+        return output({ address: params.address, written: true });
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  }));
+  pi.registerTool(defineTool2({
+    name: "notes_edit",
+    label: "Notes edit",
+    description: `Edit a note body by exact-text replacement; frontmatter is never editable this way. ${ADDRESS_DESCRIPTION} Each oldText must occur exactly once unless replace_all is set; a multi-match anchor fails with its match line numbers and a zero-match anchor names the failing edit index. edits may be omitted (or empty) for a metadata-only update, which requires at least one of origin/stale. Moving while awake means notes_write at a new address and notes_edit at the old address with stale=true. The success return carries the address and a diff of what changed.`,
+    parameters: Type3.Object({ address: Type3.String(), edits: Type3.Optional(Type3.Array(Type3.Object({ oldText: Type3.String(), newText: Type3.String() }, { additionalProperties: false }))), origin: ORIGIN, stale: Type3.Optional(Type3.Boolean()), replace_all: Type3.Optional(Type3.Boolean()) }, { additionalProperties: false }),
+    executionMode: "sequential",
+    async execute(_id, params, _signal, _update, ctx) {
+      try {
+        const destination = assertAddress(params.address);
+        const { applied, diff } = editNote(ctx, destination.path, destination.scope, params.edits, { origin: params.origin, stale: params.stale, replaceAll: params.replace_all }, destination.who);
+        return output({ address: params.address, applied, diff });
+      } catch (error) {
+        return failure(error);
+      }
+    }
+  }));
+  pi.registerTool(defineTool2({
+    name: "notes_read",
+    label: "Notes read",
+    description: `Read a character window of a note file, frontmatter included. ${ADDRESS_DESCRIPTION} offset_chars is the code-point offset to start from (default 0) \u2014 a negative value counts back from the end \u2014 and limit_chars caps the window (default ${DEFAULT_READ_WINDOW_CHARS}, max ${MAX_READ_WINDOW_CHARS}). Each response delivers the longest fitting prefix of that window in the shared READ WINDOW block: concatenate only the content after the block to reconstruct the note.`,
+    parameters: Type3.Object({ address: Type3.String(), offset_chars: Type3.Optional(Type3.Integer({ description: "Code-point offset to start from (default 0). 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: Type3.Optional(Type3.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.` })) }, { additionalProperties: false }),
+    async execute(_id, params, _signal, _update, ctx) {
+      let note;
+      try {
+        const destination = assertAddress(params.address);
+        note = readNote(ctx, destination.path, destination.scope, destination.who);
+      } catch (error) {
+        return failure(error);
+      }
+      if (!note) return output({ error: "note not found", address: params.address });
+      const text = note.text;
+      const totalChars = Array.from(text).length;
+      if (typeof params.offset_chars === "number" && params.offset_chars > totalChars) return output({ error: `offset_chars ${params.offset_chars} is past the end: the note has ${totalChars} chars; the largest legal offset is ${totalChars} (an empty end-read)`, address: params.address, offset_chars: params.offset_chars, total_chars: totalChars });
+      return readCharacterWindow(text, params.offset_chars, params.limit_chars, (window) => {
+        const { content, ...rest } = window;
+        return outputRaw(readWindowBlock([["address", params.address]], window), content, { address: params.address, ...rest });
+      }, (result) => withinTextBudget(result.content[0].text));
+    }
+  }));
+  pi.registerTool(defineTool2({
+    name: "notes_list",
+    label: "Notes list",
+    description: `List note files as rows carrying address, updated_at, and stale, most recently updated first. ${ADDRESS_DESCRIPTION} Listings merge your five reachable homes: this session, @project/, @human/, your @self home, and the current @model home; other agents and models appear only under an explicit glob (@agents/<name>/**, @models/<name>/**, or a glob in the name segment to scan a whole namespace).`,
+    parameters: Type3.Object({ pattern: nullableString(), cursor: cursor(), max_results: positiveInteger() }, { additionalProperties: false }),
+    async execute(_id, params, _signal, _update, ctx) {
+      let rows;
+      try {
+        rows = listNotes(ctx, { pattern: params.pattern ?? void 0 });
+      } catch (error) {
+        return failure(error);
+      }
+      const files = rows.map((row) => ({ address: row.address, stale: row.meta.stale, updated_at: localIso(row.meta.updated_at) }));
+      return output(page(files, params.cursor ?? 0, "files", params.max_results, (file, fits) => {
+        if (fits(file)) return file;
+        const address = middleTruncate(file.address, (candidate) => fits({ ...file, address: candidate, address_truncated: true }));
+        return { ...file, address, address_truncated: true };
+      }));
+    }
+  }));
+  pi.registerTool(defineTool2({
+    name: "notes_search",
+    label: "Notes search",
+    description: `Case-sensitive literal substring search over note bodies; query is one string or several (OR), each matched line appears once. ${ADDRESS_DESCRIPTION} Search merges the same five reachable homes as notes_list; explicit globs reach other agents and models. Patterns glob over full address strings. Each file entry carries matches_total, its full match count before capping. Each match carries line, text, offset_chars (a code-point offset into the serialized note returned by notes_read, at the earliest query match), and truncated.`,
+    parameters: Type3.Object({ query: searchQuery(), pattern: nullableString(), cursor: cursor(), max_matches_per_file: positiveInteger(), max_files: positiveInteger() }, { additionalProperties: false }),
+    async execute(_id, params, _signal, _update, ctx) {
+      const queries = searchQueries(params.query);
+      let rows;
+      try {
+        rows = searchNotes(ctx, queries, { pattern: params.pattern ?? void 0 });
+      } catch (error) {
+        return failure(error);
+      }
+      const maxPerFile = params.max_matches_per_file ?? Number.POSITIVE_INFINITY;
+      const result = rows.map((row) => {
+        const matches = row.matches.map((match) => ({ line: match.line, text: match.text, truncated: false, offset_chars: match.offsetChars }));
+        return { address: row.address, updated_at: localIso(row.meta.updated_at), stale: row.meta.stale, matches_total: matches.length, matches: matches.slice(0, maxPerFile) };
+      });
+      const fitFile = (file, fits) => {
+        if (fits(file)) return file;
+        const matches = file.matches;
+        let low = 0;
+        let high = matches.length;
+        while (low < high) {
+          const mid = Math.ceil((low + high) / 2);
+          if (mid >= 1 && fits({ ...file, matches: matches.slice(0, mid) })) low = mid;
+          else high = mid - 1;
+        }
+        if (low >= 1) return { ...file, matches: matches.slice(0, low) };
+        const first = matches[0];
+        const fitted = (text2) => ({ ...file, matches: [{ ...first, text: text2, truncated: true }] });
+        const text = prefixFit(first.text, (candidate) => fits(fitted(candidate)));
+        const prefix = fitted(text);
+        if (fits(prefix)) return prefix;
+        const address = middleTruncate(prefix.address, (candidate) => fits({ ...prefix, address: candidate, address_truncated: true }));
+        return { ...prefix, address, address_truncated: true };
+      };
+      return output(page(result, params.cursor ?? 0, "files", params.max_files, fitFile));
+    }
+  }));
+}
+
+// src/context/thresholds.ts
+import { SettingsManager } from "@earendil-works/pi-coding-agent";
+
+// src/settings.ts
+function isSettingsObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function piContextSettings(settings) {
+  if (!isSettingsObject(settings)) return {};
+  const value = settings[PI_CONTEXT_SETTINGS_KEY];
+  return isSettingsObject(value) ? value : {};
+}
+function mergePiContextSettings(globalSettings, projectSettings) {
+  const merged = { ...piContextSettings(globalSettings), ...piContextSettings(projectSettings) };
+  return { reminderMarginTokens: merged.reminderMarginTokens, dreamer: merged.dreamer };
+}
+
+// src/context/thresholds.ts
+function validMargin(raw) {
+  if (typeof raw !== "number" || !Number.isSafeInteger(raw) || raw <= 0) return void 0;
+  return raw;
+}
+function deriveThresholds(reserveTokens, margins) {
+  const warnings = [];
+  const reminderKey = `${PI_CONTEXT_SETTINGS_KEY}.reminderMarginTokens`;
+  let reminderMargin;
+  if (margins.reminderMarginTokens === void 0) reminderMargin = DEFAULT_REMINDER_MARGIN_TOKENS;
+  else {
+    const parsed = validMargin(margins.reminderMarginTokens);
+    if (parsed === void 0) {
+      warnings.push(`pi-context: ${reminderKey} must be a positive integer; using default ${DEFAULT_REMINDER_MARGIN_TOKENS}.`);
+      reminderMargin = DEFAULT_REMINDER_MARGIN_TOKENS;
+    } else reminderMargin = parsed;
+  }
+  return { thresholds: { reminder: reserveTokens + reminderMargin, reserve: reserveTokens, warning: reserveTokens + WARNING_RUNWAY_TOKENS }, warnings };
+}
+function readThresholdSettingsFromManager(ctx, settingsManager) {
+  const model = ctx.model;
+  const compaction = settingsManager.getCompactionSettings(model ? { provider: model.provider, id: model.id } : void 0);
+  const derived = deriveThresholds(
+    compaction.reserveTokens,
+    mergePiContextSettings(settingsManager.getGlobalSettings(), settingsManager.getProjectSettings())
+  );
+  return { thresholds: derived.thresholds, automatic: compaction.enabled, warnings: derived.warnings };
+}
+function readThresholdSettings(ctx, settingsManager) {
+  try {
+    if (settingsManager) return readThresholdSettingsFromManager(ctx, settingsManager);
+    return readThresholdSettingsFromManager(
+      ctx,
+      SettingsManager.create(ctx.cwd, void 0, { projectTrusted: ctx.isProjectTrusted() })
+    );
+  } catch (error) {
+    return {
+      thresholds: {
+        reminder: DEFAULT_RESERVE_TOKENS + DEFAULT_REMINDER_MARGIN_TOKENS,
+        reserve: DEFAULT_RESERVE_TOKENS,
+        warning: DEFAULT_RESERVE_TOKENS + WARNING_RUNWAY_TOKENS
+      },
+      automatic: true,
+      warnings: [`pi-context: could not read settings; using defaults (${String(error)}).`]
+    };
+  }
+}
+
+// src/context/runtime.ts
+import { getCurrentSystemMessage as getCurrentSystemMessage2, Type as Type5 } from "@earendil-works/pi-ai";
+import { VERSION, defineTool as defineTool4 } from "@earendil-works/pi-coding-agent";
+import { randomUUID as randomUUID2 } from "node:crypto";
+
+// src/context/budget.ts
+import { Type as Type4 } from "@earendil-works/pi-ai";
+import { defineTool as defineTool3 } from "@earendil-works/pi-coding-agent";
+
+// src/context/prompts.ts
+function identityBlock(agentName, modelName, firstWindowId, currentWindowId2, previousWindowId) {
+  const lines = [
+    `Agent name: ${agentName} (brain: ${modelName})`,
+    `First context window id: ${firstWindowId}`,
+    `Current context window id: ${currentWindowId2}`
+  ];
+  if (previousWindowId) lines.push(`Previous context window id: ${previousWindowId}`);
+  return `${CONTEXT_WINDOW_OPEN_TAG}
+${lines.join("\n")}
+${CONTEXT_WINDOW_CLOSE_TAG}`;
+}
+function relativeTime(timestamp, now) {
+  const seconds = Math.trunc((timestamp - now) / 1e3);
+  const [unit, size] = [["d", 86400], ["h", 3600], ["m", 60], ["s", 1]].find(([unit2, size2]) => Math.abs(seconds) >= size2 || unit2 === "s");
+  const amount = `${Math.abs(Math.trunc(seconds / size))}${unit}`;
+  return seconds > 0 ? `in ${amount}` : `${amount} ago`;
+}
+function rowsFor(snapshot, scope) {
+  return snapshot.homes.get(scope) ?? [];
+}
+function notesUnavailableNotice(snapshot) {
+  if (snapshot.unavailable.length === 0) return void 0;
+  const homes = snapshot.unavailable.map((home) => home.label).join(", ");
+  const noun = snapshot.unavailable.length === 1 ? "home's index was" : "home indexes were";
+  return `Notes index incomplete: ${homes} ${noun} unavailable during boot; notes_list can retry after recovery.`;
+}
+function notesIndex(snapshot) {
+  const sections = [];
+  for (const scope of ["human", "project", "agent", "model"]) {
+    const toc = rowsFor(snapshot, scope).find((row) => row.path === "MAP.md");
+    if (toc && !toc.meta.stale) {
+      if (toc.body.length > 0) sections.push(toc.body);
+    }
+  }
+  const recentNotes = [
+    ...rowsFor(snapshot, "session").filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_SESSION_LIMIT),
+    ...rowsFor(snapshot, "project").filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_PROJECT_LIMIT),
+    ...rowsFor(snapshot, "human").filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_HUMAN_LIMIT),
+    ...rowsFor(snapshot, "agent").filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_AGENT_LIMIT),
+    ...rowsFor(snapshot, "model").filter((row) => !row.meta.stale && row.path !== "MAP.md").slice(0, POCKET_MODEL_LIMIT)
+  ];
+  if (recentNotes.length > 0) {
+    const lines = [`You find ${recentNotes.length} crumpled note${recentNotes.length === 1 ? "" : "s"} in your pocket (by home, most recent first within each: up to ${POCKET_SESSION_LIMIT} from this session, ${POCKET_PROJECT_LIMIT} from this project, ${POCKET_HUMAN_LIMIT} from @human, ${POCKET_AGENT_LIMIT} from your @self home, ${POCKET_MODEL_LIMIT} from the current @model home). A note's content never appears here, so its name has to say what the note is about:`];
+    for (const row of recentNotes) {
+      lines.push(`- ${row.address} (${row.body.split("\n").length} lines, ${row.sizeBytes} UTF-8 bytes, updated ${relativeTime(row.meta.updated_at, snapshot.openedAt)})`);
+    }
+    sections.push(lines.join("\n"));
+  }
+  return sections.join("\n\n");
+}
+function notesHomeBlock() {
+  return "Notes_* addresses have five homes: bare <vpath> is this session, @project/<vpath> is this project, @human/<vpath> is the human's cross-project home, @self/<vpath> and @agents/<name>/<vpath> are agent homes (current vs named), and @model/<vpath> and @models/<name>/<vpath> are model homes. @self and @model resolve to who is running now; listings always show resolved names. @ means leaving home; there is no cross-home fallback. Anything else after @ \u2014 or @ inside a vpath \u2014 is a hard error. Any other note is a plain file \u2014 use the file tools.";
+}
+function renderBootBlock(data) {
+  const parts = [];
+  if (data.resetLine) parts.push(RESET_SUMMARY);
+  parts.push(identityBlock(data.agentName, data.modelName, data.firstWindowId, data.currentWindowId, data.previousWindowId));
+  parts.push(notesHomeBlock());
+  const incomplete = notesUnavailableNotice(data.notes);
+  if (incomplete) parts.push(incomplete);
+  const index = notesIndex(data.notes);
+  if (index) parts.push(index);
+  parts.push(PROTOCOL_BLOCK);
+  return parts.join("\n\n");
+}
+function tokenBudgetGuidance(remaining) {
+  return `${GUIDANCE_OPEN_TAG}
+Your brain is almost out of room \u2014 ${remaining} tokens left, and then your memory gets wiped. The wipe is automatic: there is no final turn to write then. Grab the notebook now \u2014 the goal, decisions, progress, learnings, next steps, the skills you still need, the window ID and item ID of every relevant user request still being solved, and important actions/tool calls for future reference. Replacing an older checkpoint? Mark it stale. Then call wipe_memory yourself \u2014 anything you do after the checkpoint isn't in it.
+${GUIDANCE_CLOSE_TAG}`;
+}
+
+// src/context/budget.ts
+function remainingTokens(ctx) {
+  const usage = windowUsage(ctx);
+  return !usage || usage.tokens === null ? null : Math.max(0, usage.contextWindow - usage.tokens);
+}
+function registerBudget(pi, isEnabled, settingsManager) {
+  let cachedPolicy;
+  const notifiedWarnings = /* @__PURE__ */ new Set();
+  const resolvePolicy = (ctx) => {
+    if (!settingsManager && cachedPolicy) return { ...cachedPolicy, warnings: [] };
+    const resolution = readThresholdSettings(ctx, settingsManager);
+    for (const warning of resolution.warnings) {
+      if (notifiedWarnings.has(warning)) continue;
+      notifiedWarnings.add(warning);
+      ctx.ui.notify(warning, "warning");
+    }
+    if (!settingsManager) cachedPolicy = { thresholds: resolution.thresholds, automatic: resolution.automatic };
+    return resolution;
+  };
+  const thresholdsFor = (ctx) => {
+    return resolvePolicy(ctx).thresholds;
+  };
+  const automaticResetEnabled = (ctx) => {
+    return resolvePolicy(ctx).automatic;
+  };
+  const resetDue = (ctx) => {
+    if (!automaticResetEnabled(ctx)) return false;
+    const usage = windowUsage(ctx);
+    return usage !== void 0 && usage.tokens !== null && usage.contextWindow - usage.tokens <= thresholdsFor(ctx).reserve;
+  };
+  const invalidateThresholds = () => {
+    cachedPolicy = void 0;
+  };
+  let pendingGuidance;
+  let pendingWarning;
+  let pendingNotices = [];
+  const notifyCommittedReminders = (ctx) => {
+    const windowId = currentWindowId(ctx);
+    for (const notice of pendingNotices) {
+      if (notice.windowId !== windowId || !hasWindowMessage(ctx, notice.customType)) continue;
+      ctx.ui.notify(notice.customType === WARNING_TYPE ? "pi-context: context budget critical \u2014 final checkpoint warning recorded for the model." : "pi-context: context budget low \u2014 checkpoint reminder recorded for the model, kept out of the chat view.", "warning");
+    }
+    pendingNotices = [];
+  };
+  const clearStaged = () => {
+    pendingGuidance = void 0;
+    pendingWarning = void 0;
+  };
+  const resetForTransition = () => {
+    clearStaged();
+    pendingNotices = [];
+    invalidateThresholds();
+    notifiedWarnings.clear();
+  };
+  const consumeTurnEnd = (ctx) => {
+    const staged = [
+      pendingGuidance ? { ...pendingGuidance, customType: GUIDANCE_TYPE } : void 0,
+      pendingWarning ? { ...pendingWarning, customType: WARNING_TYPE } : void 0
+    ];
+    clearStaged();
+    const windowId = currentWindowId(ctx);
+    const drafts = staged.filter((draft) => draft !== void 0 && draft.windowId === windowId);
+    pendingNotices = drafts.map(({ windowId: windowId2, customType }) => ({ windowId: windowId2, customType }));
+    return drafts.map((draft) => ({
+      type: "custom_message",
+      customType: draft.customType,
+      content: draft.content,
+      display: false
+    }));
+  };
+  pi.on("session_start", (_event, ctx) => {
+    resetForTransition();
+    thresholdsFor(ctx);
+  });
+  pi.on("session_tree", resetForTransition);
+  pi.on("model_select", resetForTransition);
+  pi.on("session_shutdown", resetForTransition);
+  pi.on("turn_start", (_event, ctx) => notifyCommittedReminders(ctx));
+  pi.on("agent_settled", (_event, ctx) => {
+    notifyCommittedReminders(ctx);
+    clearStaged();
+  });
+  pi.on("context", (_event, ctx) => {
+    if (!isEnabled()) return void 0;
+    const remaining = remainingTokens(ctx);
+    if (remaining === null) return void 0;
+    const windowId = currentWindowId(ctx);
+    const { reminder, warning } = thresholdsFor(ctx);
+    if (hasWindowMessage(ctx, WARNING_TYPE) || pendingWarning?.windowId === windowId) return void 0;
+    if (remaining <= warning) {
+      pendingGuidance = void 0;
+      const content = `${GUIDANCE_OPEN_TAG}
+${WARNING_PROMPT}
+${GUIDANCE_CLOSE_TAG}`;
+      pendingWarning = { windowId, content };
+      const warningMessage = {
+        role: "custom",
+        customType: WARNING_TYPE,
+        content,
+        display: false,
+        timestamp: Date.now()
+      };
+      return { messages: [..._event.messages, warningMessage] };
+    }
+    if (hasWindowMessage(ctx, GUIDANCE_TYPE) || pendingGuidance?.windowId === windowId) return void 0;
+    if (remaining <= reminder) {
+      const left = Math.max(0, remaining - warning);
+      pendingGuidance = { windowId, content: tokenBudgetGuidance(left) };
+    }
+    return void 0;
+  });
+  pi.registerTool(defineTool3({
+    name: "get_context_remaining",
+    label: "Get context remaining",
+    description: "Return estimated context tokens left before your memory is wiped; null when Pi cannot estimate usage.",
+    parameters: Type4.Object({}, { additionalProperties: false }),
+    async execute(_id, _params, _signal, _update, ctx) {
+      const remaining = remainingTokens(ctx);
+      return output({ remaining_tokens: remaining === null ? null : Math.max(0, remaining - thresholdsFor(ctx).warning) });
+    }
+  }));
+  return {
+    automaticResetEnabled,
+    resetDue,
+    consumeTurnEnd,
+    clear: () => {
+      clearStaged();
+      pendingNotices = [];
+    }
+  };
+}
+
+// src/notes/notes-snapshot.ts
+var NOTES_HOMES = [
+  { scope: "session", label: "this session" },
+  { scope: "project", label: "@project" },
+  { scope: "human", label: "@human" },
+  { scope: "agent", label: "@self" },
+  { scope: "model", label: "@model" }
+];
+function loadNotesSnapshot(ctx, loadHome = (context, scope) => listNotes(context, { scope })) {
+  const openedAt = Date.now();
+  const homes = /* @__PURE__ */ 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 : void 0;
+      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 };
+}
+
+// src/context/reset-lifecycle.ts
+import { isContextOverflow, isRecoverableLength } from "@earendil-works/pi-ai";
+function isAbort(message, outcome, ctx) {
+  return outcome === "aborted" || message.role === "assistant" && message.stopReason === "aborted" || ctx.signal?.aborted === true;
+}
+function isOverflowLike(message, ctx) {
+  if (message.role !== "assistant") return false;
+  return isContextOverflow(message, ctx.model?.contextWindow) || ctx.model !== void 0 && isRecoverableLength(message, ctx.model.maxTokens);
+}
+function registerResetLifecycle(pi, options) {
+  let explicitRequested = false;
+  let overflowPending = false;
+  let overflowRecoveryUsed = false;
+  let active = true;
+  const clear = () => {
+    explicitRequested = false;
+    overflowPending = false;
+    overflowRecoveryUsed = false;
+  };
+  const resetBoundaryResult = (entries, ctx) => {
+    try {
+      return { entries: [...entries, ...options.buildReset(ctx)], continue: true };
+    } catch (error) {
+      ctx.ui.notify(`pi-context: could not build reset (${String(error)}).`, "warning");
+      return entries.length > 0 ? { entries } : void 0;
+    }
+  };
+  pi.on("turn_end", (event, ctx) => {
+    if (!active) return void 0;
+    const requested = explicitRequested;
+    explicitRequested = false;
+    const aborted = isAbort(event.message, event.outcome, ctx);
+    const stagedBudgetEntries = options.budget.consumeTurnEnd(ctx);
+    const budgetEntries = options.isEnabled() && !aborted ? stagedBudgetEntries : [];
+    const entries = [...event.entries ?? [], ...budgetEntries];
+    if (aborted) {
+      overflowPending = false;
+      overflowRecoveryUsed = false;
+      return entries.length > 0 ? { entries } : void 0;
+    }
+    if (isOverflowLike(event.message, ctx)) {
+      const queued = event.context.pendingMessages.length > 0 || ctx.hasPendingMessages();
+      overflowPending = !queued && options.isEnabled() && options.budget.automaticResetEnabled(ctx);
+      return entries.length > 0 ? { entries } : void 0;
+    }
+    if (event.outcome !== "error") {
+      overflowPending = false;
+      overflowRecoveryUsed = false;
+    }
+    if (!options.isEnabled() || event.outcome === "error") return entries.length > 0 ? { entries } : void 0;
+    const autoThreshold = options.budget.resetDue(ctx);
+    if (!requested && !autoThreshold) return entries.length > 0 ? { entries } : void 0;
+    return resetBoundaryResult(entries, ctx);
+  });
+  pi.on("agent_before_settle", (event, ctx) => {
+    if (!active || !overflowPending) return void 0;
+    if (event.context.pendingMessages.length > 0 || ctx.hasPendingMessages()) return void 0;
+    overflowPending = false;
+    if (!options.isEnabled() || !options.budget.automaticResetEnabled(ctx) || event.outcome === "aborted" || ctx.signal?.aborted) return void 0;
+    if (overflowRecoveryUsed) return void 0;
+    overflowRecoveryUsed = true;
+    return resetBoundaryResult(event.entries, ctx);
+  });
+  pi.on("session_before_compact", (event, ctx) => {
+    if (!active) return void 0;
+    if (event.signal.aborted) return { cancel: true };
+    const markerExists = currentReset(ctx) !== void 0;
+    if (options.isEnabled() || markerExists) {
+      if (event.reason === "manual") {
+        ctx.ui.notify("pi-context: /compact is disabled while context windows are active; use /wipe-memory to start a fresh window.", "warning");
+      }
+      return { cancel: true };
+    }
+    return void 0;
+  });
+  pi.on("agent_end", (_event, ctx) => {
+    if (ctx.signal?.aborted) clear();
+  });
+  pi.on("agent_settled", () => {
+    overflowPending = false;
+    overflowRecoveryUsed = false;
+  });
+  pi.on("session_start", () => {
+    clear();
+    active = true;
+  });
+  pi.on("session_tree", clear);
+  pi.on("session_shutdown", () => {
+    clear();
+    options.budget.clear();
+    active = false;
+  });
+  return {
+    request() {
+      if (explicitRequested) return "rollover_already_pending";
+      explicitRequested = true;
+      return "rollover_requested";
+    },
+    clear
+  };
+}
+
+// src/context/runtime.ts
+var buildLabel = typeof define_PI_CONTEXT_BUILD_default === "undefined" ? "unbundled source (build unknown)" : `${define_PI_CONTEXT_BUILD_default.version} \xB7 build ${define_PI_CONTEXT_BUILD_default.sourceHash.slice(0, 12)}`;
+function bootContent(ctx, currentId, previousId, resetLine, notes) {
+  return renderBootBlock({
+    agentName: agentSlug(ctx),
+    modelName: modelSlug(ctx),
+    firstWindowId: rootWindowId(ctx.sessionManager.getSessionId()),
+    currentWindowId: currentId,
+    previousWindowId: previousId,
+    resetLine,
+    notes
+  });
+}
+function buildResetDrafts(ctx, notifyIncompleteNotes) {
+  const sessionPrefix = ctx.sessionManager.getSessionId().slice(0, 8);
+  const usedWindowIds = new Set(
+    ctx.sessionManager.getBranch().filter(isWindowMarker).map((entry) => entry.data.windowId)
+  );
+  let windowId;
+  do {
+    windowId = `pcw:${sessionPrefix}:${randomUUID2().slice(0, 8)}`;
+  } while (usedWindowIds.has(windowId));
+  const notes = loadNotesSnapshot(ctx);
+  notifyIncompleteNotes?.(ctx, windowId, notes);
+  return [
+    { type: "custom", customType: RESET_MARKER_TYPE, data: { windowId } },
+    {
+      type: "custom_message",
+      customType: BOOT_TYPE,
+      content: bootContent(ctx, windowId, currentWindowId(ctx), true, notes),
+      display: false,
+      details: { windowId }
+    },
+    {
+      type: "custom_message",
+      customType: CONTINUATION_TYPE,
+      content: CONTINUATION,
+      display: false
+    }
+  ];
+}
+function ensureBoot(pi, ctx, notifyIncompleteNotes) {
+  const reset = currentReset(ctx);
+  const sessionId2 = ctx.sessionManager.getSessionId();
+  const windowId = reset?.data?.windowId ?? rootWindowId(sessionId2);
+  if (ctx.sessionManager.buildSessionProjection().messages.some((message) => isWindowBoot(message, windowId))) return;
+  if (reset && !resetBootMayBeRepaired(ctx, reset.id, windowId)) return;
+  let previousId = reset ? rootWindowId(sessionId2) : void 0;
+  if (reset) {
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.id === reset.id) break;
+      if (isWindowMarker(entry)) previousId = entry.data.windowId;
+    }
+  }
+  const notes = loadNotesSnapshot(ctx);
+  notifyIncompleteNotes?.(ctx, windowId, notes);
+  pi.sendMessage(
+    { customType: BOOT_TYPE, content: bootContent(ctx, windowId, previousId, reset !== void 0, notes), display: false, details: { windowId } },
+    { triggerTurn: false }
+  );
+}
+function persistManualReset(pi, ctx, notifyIncompleteNotes) {
+  const [marker, boot] = buildResetDrafts(ctx, notifyIncompleteNotes);
+  pi.appendEntry(marker.customType, marker.data);
+  pi.sendMessage(
+    { customType: boot.customType, content: boot.content, display: boot.display, details: boot.details },
+    { triggerTurn: false }
+  );
+  return boot.details.windowId;
+}
+function resetBootMayBeRepaired(ctx, markerId, windowId) {
+  const branch = ctx.sessionManager.getBranch();
+  const markerIndex = branch.findIndex((entry) => entry.id === markerId);
+  if (markerIndex < 0) return false;
+  const afterMarker = branch.slice(markerIndex + 1);
+  if (afterMarker.some((entry) => isWindowBootEntry(entry, windowId))) return false;
+  return !afterMarker.some((entry) => entry.type === "message" || entry.type === "custom_message" || entry.type === "compaction" || entry.type === "branch_summary");
+}
+function isWindowBootEntry(entry, windowId) {
+  return entry.type === "custom_message" && entry.customType === BOOT_TYPE && typeof entry.details === "object" && entry.details !== null && typeof entry.details.windowId === "string" && entry.details.windowId === windowId;
+}
+function branchHasWindowMarker(ctx, fromId) {
+  return ctx.sessionManager.getBranch(fromId).some((entry) => isWindowMarker(entry));
+}
+function registerContext(pi, settingsManager) {
+  let enabled = true;
+  let missingBootNotice;
+  const incompleteNotesNotified = /* @__PURE__ */ new Set();
+  const pendingResetNotices = /* @__PURE__ */ new Set();
+  const notifyCommittedResets = (ctx, addedWindowId) => {
+    if (addedWindowId) pendingResetNotices.add(addedWindowId);
+    if (pendingResetNotices.size === 0) return;
+    const branch = ctx.sessionManager.getBranch();
+    for (const windowId of pendingResetNotices) {
+      if (!branch.some((entry) => isWindowMarker(entry) && entry.data.windowId === windowId) || !branch.some((entry) => isWindowBootEntry(entry, windowId))) continue;
+      pendingResetNotices.delete(windowId);
+      ctx.ui.notify(`pi-context: memory cleared \xB7 ${windowId}`, "info");
+    }
+  };
+  pi.on("turn_start", (_event, ctx) => notifyCommittedResets(ctx));
+  pi.on("agent_settled", (_event, ctx) => {
+    notifyCommittedResets(ctx);
+    pendingResetNotices.clear();
+  });
+  const notifyIncompleteNotes = (ctx, windowId, snapshot) => {
+    if (snapshot.unavailable.length === 0 || incompleteNotesNotified.has(windowId)) return;
+    incompleteNotesNotified.add(windowId);
+    const homes = snapshot.unavailable.map((home) => home.label).join(", ");
+    ctx.ui.notify(`pi-context: notes index incomplete for ${homes}; notes_list can retry after recovery.`, "warning");
+  };
+  const migrationWarning = migrateLegacyHomes();
+  if (migrationWarning) console.warn(`pi-context: ${migrationWarning}`);
+  const budget = registerBudget(pi, () => enabled, settingsManager);
+  pi.on("session_start", (_event, ctx) => {
+    if (!enabled) return;
+    missingBootNotice = void 0;
+    pendingResetNotices.clear();
+    ensureBoot(pi, ctx, notifyIncompleteNotes);
+  });
+  pi.on("session_tree", (_event, ctx) => {
+    missingBootNotice = void 0;
+    pendingResetNotices.clear();
+    if (enabled) ensureBoot(pi, ctx, notifyIncompleteNotes);
+  });
+  pi.on("session_before_tree", (event, ctx) => {
+    if (!event.preparation.userWantsSummary) return void 0;
+    if (!branchHasWindowMarker(ctx) && !branchHasWindowMarker(ctx, event.preparation.targetId)) return void 0;
+    ctx.ui.notify("pi-context: skipped branch summary across a reset window; navigation continues without erased history.", "info");
+    return { summary: { summary: "" } };
+  });
+  pi.on("context_with_system", (event, ctx) => {
+    const reset = currentReset(ctx);
+    const windowId = reset?.data.windowId ?? rootWindowId(ctx.sessionManager.getSessionId());
+    try {
+      return { messages: reset ? projectWindow(event.messages, windowId) : projectRootWindow(event.messages, windowId) };
+    } catch (error) {
+      if (missingBootNotice !== windowId) {
+        missingBootNotice = windowId;
+        ctx.ui.notify(`pi-context: active context window ${windowId} has no visible boot; request cancelled safely. Use /wipe-memory to start another window.`, "error");
+      }
+      ctx.abort();
+      const safeHead = getCurrentSystemMessage2(event.messages);
+      return { messages: safeHead ? [safeHead] : [] };
+    }
+  });
+  pi.registerCommand("pi-context", {
+    description: "Show loaded version/build and toggle pi-context context windows",
+    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;
+        ensureBoot(pi, cmdCtx, notifyIncompleteNotes);
+      } else if (arg === "off") {
+        enabled = false;
+        budget.clear();
+        resets.clear();
+      } else if (arg !== "") {
+        cmdCtx.ui.notify("Usage: /pi-context [on|off]", "error");
+        return;
+      }
+      cmdCtx.ui.notify(`pi-context: ${enabled ? "on" : "off"} \xB7 ${buildLabel} \xB7 Pi ${VERSION}`, "info");
+    }
+  });
+  pi.registerCommand("wipe-memory", {
+    description: "Persist a fresh context window without calling the model",
+    handler: async (_args, cmdCtx) => {
+      if (!enabled) {
+        cmdCtx.ui.notify("pi-context: /wipe-memory requires /pi-context on.", "error");
+        return;
+      }
+      await cmdCtx.waitForIdle();
+      if (!enabled) return;
+      resets.clear();
+      notifyCommittedResets(cmdCtx, persistManualReset(pi, cmdCtx, notifyIncompleteNotes));
+    }
+  });
+  pi.registerTool(defineTool4({
+    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: Type5.Object({}, { additionalProperties: false }),
+    async execute() {
+      if (!enabled) return output({ error: "pi-context is off (/pi-context on to enable)" });
+      return output({ status: resets.request() }, void 0, true);
+    }
+  }));
+  const resets = registerResetLifecycle(pi, {
+    isEnabled: () => enabled,
+    buildReset: (ctx) => {
+      const drafts = buildResetDrafts(ctx, notifyIncompleteNotes);
+      pendingResetNotices.add(drafts[1].details.windowId);
+      return drafts;
+    },
+    budget
+  });
+}
+
+// src/notes/session-replay.ts
+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 === void 0 || typeof op.text === "string") && (op.stale === void 0 || typeof op.stale === "boolean") && (op.text !== void 0 || op.stale !== void 0) && typeof op.createdAt === "number" && Number.isFinite(new Date(op.createdAt).getTime()) && typeof op.updatedAt === "number" && Number.isFinite(new Date(op.updatedAt).getTime());
+}
+function notesFromSession(ctx) {
+  const files = /* @__PURE__ */ 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 !== void 0;
+    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;
+    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;
+}
+
+// src/index.ts
+function registerPiContext(pi, settingsManager) {
+  const [major, minor] = VERSION2.split(".").map(Number);
+  if (!(major > 0 || major === 0 && minor >= 87)) {
+    throw new Error(`pi-context requires Pi >= 0.87.0; running ${VERSION2}. Upgrade Pi and restart the process; /reload only reloads extensions.`);
+  }
+  registerContext(pi, settingsManager);
+  registerHistoryTools(pi);
+  registerNotesTools(pi);
+}
+function createPiContext(options = {}) {
+  return (pi) => registerPiContext(pi, options.settingsManager);
+}
+function piContext(pi) {
+  registerPiContext(pi);
+}
+var internal = { MAX_NOTE_BYTES, NOTE_TYPE, BOOT_TYPE, GUIDANCE_TYPE, WARNING_TYPE, CONTINUATION_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 };
+export {
+  createPiContext,
+  piContext as default,
+  historyFromSession,
+  internal,
+  notesFromSession
+};