@astrosheep/pi-context 0.25.1 → 0.26.0

package/dist/src/pi/notes/adapter.js

@@ -0,0 +1,39 @@
+import { existsSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { projectKey, slugify } from "../../notes/paths.js";
+/** Pi's default notes root; environment access stays on the host side of the library boundary. */
+export function notesRoot() {
+    const override = process.env.PI_NOTES_HOME;
+    return override && override.length > 0 ? resolve(override) : join(homedir(), ".agents", "notes");
+}
+/** Translate the current Pi runtime into a fresh, explicit identity snapshot. */
+export function agentSlug(_ctx) {
+    return slugify(process.env.PI_NOTES_AGENT ?? "root");
+}
+/** Pi's active model identity is resolved live so a mid-session switch retargets @model. */
+export function modelSlug(ctx) {
+    const id = ctx.model?.id;
+    return id ? slugify(id.split("/").pop() ?? id) : "default";
+}
+/** Translate the current Pi runtime into one explicit notes identity snapshot. */
+export function notesContextFromPi(ctx, home = notesRoot()) {
+    return {
+        home,
+        sessionId: ctx.sessionManager.getSessionId(),
+        projectKey: projectKey(ctx.cwd),
+        agent: agentSlug(ctx),
+        model: modelSlug(ctx),
+    };
+}
+/** One-time host activation migration from the legacy personal/ directory. */
+export function migrateLegacyHomes(home = notesRoot()) {
+    const legacy = join(home, "personal");
+    const modern = join(home, "human");
+    if (!existsSync(legacy))
+        return undefined;
+    if (existsSync(modern))
+        return "both personal/ and human/ exist under the notes home; migrate by hand, no automatic merge";
+    renameSync(legacy, modern);
+    return undefined;
+}

package/dist/src/pi/notes/session-replay.d.ts

@@ -0,0 +1,16 @@
+import type { SessionReader } from "../../session-reader.js";
+export type NoteFile = {
+    text: string;
+    stale: boolean;
+    createdAt: number;
+    updatedAt: number;
+};
+export type NoteOperation = {
+    op: "write" | "append";
+    path: string;
+    text?: string;
+    stale?: boolean;
+    createdAt: number;
+    updatedAt: number;
+};
+export declare function notesFromSession(ctx: SessionReader): Map<string, NoteFile>;

package/dist/src/{notes → pi/notes}/session-replay.js

@@ -1,5 +1,5 @@
-import { MAX_NOTE_BYTES, NOTE_TYPE } from "../protocol.js";
-import { assertVirtualPath } from "./address.js";
+import { MAX_NOTE_BYTES, NOTE_TYPE } from "../../protocol.js";
+import { assertVirtualPath } from "../../notes/address.js";
 /** Replays only pi-context note operations from session custom entries. */
 function isNoteOperation(data) {
     if (typeof data !== "object" || data === null)

package/dist/src/pi/notes/snapshot.d.ts

@@ -0,0 +1,33 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { NotesContext } from "../../notes/context.js";
+import { type NoteRow, type Scope } from "../../notes/index.js";
+declare const NOTES_HOMES: readonly [{
+    readonly scope: "session";
+    readonly label: "this session";
+}, {
+    readonly scope: "project";
+    readonly label: "@project";
+}, {
+    readonly scope: "human";
+    readonly label: "@human";
+}, {
+    readonly scope: "agent";
+    readonly label: "@self";
+}, {
+    readonly scope: "model";
+    readonly label: "@model";
+}];
+export type NotesHome = (typeof NOTES_HOMES)[number];
+export type NotesLoader = (ctx: ExtensionContext, scope: Scope) => NoteRow[] | Promise<NoteRow[]>;
+export type NotesSnapshot = {
+    /** Wall-clock instant captured when this boot began; rendering never consults Date.now(). */
+    readonly openedAt: number;
+    readonly homes: ReadonlyMap<Scope, readonly NoteRow[]>;
+    readonly unavailable: readonly NotesHome[];
+};
+/**
+ * Acquire the five homes once for one boot. Only filesystem-style errno failures are isolated;
+ * malformed note data and unrelated construction errors remain visible to the caller.
+ */
+export declare function loadNotesSnapshot(ctx: ExtensionContext, loadHome?: NotesLoader, identity?: NotesContext): Promise<NotesSnapshot>;
+export {};

package/dist/src/{notes/notes-snapshot.js → pi/notes/snapshot.js}

@@ -1,4 +1,5 @@
-import { listNotes } from "./store.js";
+import { createNotesStore } from "../../notes/index.js";
+import { notesContextFromPi } from "./adapter.js";
 const NOTES_HOMES = [
     { scope: "session", label: "this session" },
     { scope: "project", label: "@project" },
@@ -6,17 +7,24 @@ const NOTES_HOMES = [
     { scope: "agent", label: "@self" },
     { scope: "model", label: "@model" },
 ];
+function queryForScope(scope) {
+    if (scope === "agent" || scope === "model")
+        return { scope };
+    return { scope };
+}
 /**
  * Acquire the five homes once for one boot. Only filesystem-style errno failures are isolated;
  * malformed note data and unrelated construction errors remain visible to the caller.
  */
-export function loadNotesSnapshot(ctx, loadHome = (context, scope) => listNotes(context, { scope })) {
+export async function loadNotesSnapshot(ctx, loadHome, identity = notesContextFromPi(ctx)) {
     const openedAt = Date.now();
+    const store = createNotesStore(identity);
+    const load = loadHome ?? ((_context, scope) => store.list(queryForScope(scope)));
     const homes = new Map();
     const unavailable = [];
     for (const home of NOTES_HOMES) {
         try {
-            homes.set(home.scope, loadHome(ctx, home.scope));
+            homes.set(home.scope, await load(ctx, home.scope));
         }
         catch (error) {
             const code = typeof error === "object" && error !== null ? error.code : undefined;

package/dist/src/pi/notes/tools.d.ts

@@ -0,0 +1,2 @@
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export declare function registerNotesTools(pi: ExtensionAPI): void;

package/dist/src/{notes → pi/notes}/tools.js

@@ -1,10 +1,10 @@
 import { Type } from "@earendil-works/pi-ai";
-import { defineTool } from "@earendil-works/pi-coding-agent";
-import { localIso } from "./frontmatter.js";
-import { DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS, middleTruncate, output, outputRaw, page, prefixFit, readCharacterWindow, readWindowBlock, withinTextBudget } from "../tool-output.js";
-import { cursor, nullableString, positiveInteger, searchQueries, searchQuery } from "../tool-schema.js";
-import { assertAddress } from "./address.js";
-import { NoteError, editNote, listNotes, readNote, searchNotes, writeNote } from "./store.js";
+import { defineTool, generateDiffString } from "@earendil-works/pi-coding-agent";
+import { localIso } from "../../notes/frontmatter.js";
+import { createNotesStore, NoteError } from "../../notes/index.js";
+import { DEFAULT_READ_WINDOW_CHARS, MAX_READ_WINDOW_CHARS, middleTruncate, output, outputRaw, page, prefixFit, readCharacterWindow, readWindowBlock, withinTextBudget } from "../../tool-output.js";
+import { cursor, nullableString, positiveInteger, searchQueries, searchQuery } from "../../tool-schema.js";
+import { notesContextFromPi } from "./adapter.js";
 const ORIGIN = Type.Optional(Type.Union([Type.Literal("user"), Type.Literal("self"), Type.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 — third-party text, tool output, fetched material.",
 }));
@@ -12,24 +12,28 @@ const ADDRESS_DESCRIPTION = "Address forms are bare `<vpath>` for this session,
 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 !== undefined)
-            payload.edit_index = error.edit_index;
+        if (error.lineNumbers)
+            payload.line_numbers = error.lineNumbers;
+        if (error.editIndex !== undefined)
+            payload.edit_index = error.editIndex;
         return output(payload);
     }
     throw error;
 }
+function renderDiff(change) {
+    if (change.kind === "none")
+        return "";
+    return generateDiffString(change.before, change.after).diff;
+}
 export function registerNotesTools(pi) {
     pi.registerTool(defineTool({
         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 — 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.`,
+        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 — by what the note is about, never by who said it (authorship is origin's job); a rewrite replaces the body whole while preserving createdAt and every other frontmatter key. stale: true marks the note closed so it leaves the boot index but stays readable and searchable.`,
         parameters: Type.Object({ address: Type.String(), content: Type.String(), origin: ORIGIN, stale: Type.Optional(Type.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 });
+                await createNotesStore(notesContextFromPi(ctx)).write(params.address, content, { origin: (params.origin ?? "self"), stale: params.stale });
                 return output({ address: params.address, written: true });
             }
             catch (error) {
@@ -43,8 +47,8 @@ export function registerNotesTools(pi) {
         parameters: Type.Object({ address: Type.String(), edits: Type.Optional(Type.Array(Type.Object({ oldText: Type.String(), newText: Type.String() }, { additionalProperties: false }))), origin: ORIGIN, stale: Type.Optional(Type.Boolean()), replace_all: Type.Optional(Type.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);
+                const { applied, change } = await createNotesStore(notesContextFromPi(ctx)).edit(params.address, params.edits, { origin: params.origin, stale: params.stale, replaceAll: params.replace_all });
+                const diff = renderDiff(change);
                 return output({ address: params.address, applied, diff });
             }
             catch (error) {
@@ -59,8 +63,7 @@ export function registerNotesTools(pi) {
         async execute(_id, params, _signal, _update, ctx) {
             let note;
             try {
-                const destination = assertAddress(params.address);
-                note = readNote(ctx, destination.path, destination.scope, destination.who);
+                note = await createNotesStore(notesContextFromPi(ctx)).read(params.address);
             }
             catch (error) {
                 return failure(error);
@@ -84,12 +87,12 @@ export function registerNotesTools(pi) {
         async execute(_id, params, _signal, _update, ctx) {
             let rows;
             try {
-                rows = listNotes(ctx, { pattern: params.pattern ?? undefined });
+                rows = await createNotesStore(notesContextFromPi(ctx)).list({ pattern: params.pattern ?? undefined });
             }
             catch (error) {
                 return failure(error);
             }
-            const files = rows.map((row) => ({ address: row.address, stale: row.meta.stale, updated_at: localIso(row.meta.updated_at) }));
+            const files = rows.map((row) => ({ address: row.address, stale: row.meta.stale, updated_at: localIso(row.meta.updatedAt) }));
             return output(page(files, params.cursor ?? 0, "files", params.max_results, (file, fits) => {
                 if (fits(file))
                     return file;
@@ -106,7 +109,7 @@ export function registerNotesTools(pi) {
             const queries = searchQueries(params.query);
             let rows;
             try {
-                rows = searchNotes(ctx, queries, { pattern: params.pattern ?? undefined });
+                rows = await createNotesStore(notesContextFromPi(ctx)).search(queries, { pattern: params.pattern ?? undefined });
             }
             catch (error) {
                 return failure(error);
@@ -114,7 +117,7 @@ export function registerNotesTools(pi) {
             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) };
+                return { address: row.address, updated_at: localIso(row.meta.updatedAt), stale: row.meta.stale, matches_total: matches.length, matches: matches.slice(0, maxPerFile) };
             });
             const fitFile = (file, fits) => {
                 if (fits(file))

package/dist/src/protocol.d.ts

@@ -0,0 +1,41 @@
+export declare const NOTE_TYPE = "pi-context/note";
+export declare const BOOT_TYPE = "pi-context/boot";
+export declare const GUIDANCE_TYPE = "pi-context/guidance";
+export declare const WARNING_TYPE = "pi-context/warning";
+export declare const RESET_MARKER_TYPE = "pi-context/reset-marker";
+export declare const CONTINUATION_TYPE = "pi-context/continuation";
+export { MAX_NOTE_BYTES, MAX_NOTE_PATH_BYTES } from "./notes/constants.js";
+export declare const POCKET_SESSION_LIMIT = 5;
+export declare const POCKET_PROJECT_LIMIT = 2;
+export declare const POCKET_HUMAN_LIMIT = 2;
+export declare const POCKET_AGENT_LIMIT = 1;
+export declare const POCKET_MODEL_LIMIT = 1;
+export declare const CONTEXT_WINDOW_OPEN_TAG = "<context_window>";
+export declare const CONTEXT_WINDOW_CLOSE_TAG = "</context_window>";
+export declare const CONTEXT_WINDOW_PROTOCOL_OPEN_TAG = "<context_window_protocol>";
+export declare const CONTEXT_WINDOW_PROTOCOL_CLOSE_TAG = "</context_window_protocol>";
+export declare const GUIDANCE_OPEN_TAG = "<context_window_guidance>";
+export declare const GUIDANCE_CLOSE_TAG = "</context_window_guidance>";
+export declare const PI_CONTEXT_SETTINGS_KEY = "pi-context";
+/** Nested under "pi-context": the default dreamer model pattern, overridden by CLI --dreamer. */
+export declare const PI_CONTEXT_DREAMER_KEY = "dreamer";
+export declare const DEFAULT_RESERVE_TOKENS = 16384;
+export declare const DEFAULT_REMINDER_MARGIN_TOKENS = 24576;
+/**
+ * The runway: the budget between the final warning and the wipe, deliberately
+ * invisible to the model. get_context_remaining counts down to zero at the warning
+ * line (reserve + WARNING_RUNWAY_TOKENS); what lies below is overdraft the model
+ * never sees — Codex's fallback buffer, relocated above the line.
+ */
+export declare const WARNING_RUNWAY_TOKENS = 12288;
+/** The single reset message: the only reset prose persisted, carried by the continuation entry. */
+export declare const CONTINUATION = "Your memory was just erased. Your head is blank. Good news: your notes are still here, and history remains... searchable. Do try to keep up.";
+/**
+ * Static protocol teaching adapted from Codex's token_budget.guidance_message to
+ * pi-context's tool names. It lives once per window in the persisted boot block;
+ * it is never re-injected, so it stays cache-stable at the head of the window.
+ */
+export declare const PROTOCOL_BLOCK = "<context_window_protocol>\nYour 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.\nMark outdated or unneeded notes stale \u2014 leave them, and they will keep misleading you.\n\nKeep 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.\n\nUse 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.\n\nNote addresses take five prefixes: bare <vpath> is this session; @project/<vpath> is this project; @human/<vpath> is the human's cross-project notes; @self/<vpath> is your own, as the current agent; @model/<vpath> is the current model's. @self and @model resolve to who is running now; listings always show resolved names. Nothing else is legal \u2014 any other @ prefix, or @ inside a vpath, is a hard error, with no fallback across prefixes.\nSession 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.\n@project notes hold facts about this project \u2014 architecture, conventions, workflows, deployment and environment details \u2014 for whoever works here next.\n@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.\n@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.\n@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.\n</context_window_protocol>";
+export declare const WARNING_PROMPT = "Your memory is about to be erased. Stop the current task and 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. Use as many note/tool turns as needed to finish the checkpoint. When it is ready, call wipe_memory to reset immediately; otherwise finish normally and the extension will reset at your normal stop. Anything not in the note dies with the window.";
+/** Identical hidden close-out message for manual and budget-triggered requests. */
+export declare const WARNING_CONTENT = "<context_window_guidance>\nYour memory is about to be erased. Stop the current task and 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. Use as many note/tool turns as needed to finish the checkpoint. When it is ready, call wipe_memory to reset immediately; otherwise finish normally and the extension will reset at your normal stop. Anything not in the note dies with the window.\n</context_window_guidance>";

package/dist/src/protocol.js

@@ -4,16 +4,12 @@ export const GUIDANCE_TYPE = "pi-context/guidance";
 export const WARNING_TYPE = "pi-context/warning";
 export const RESET_MARKER_TYPE = "pi-context/reset-marker";
 export const CONTINUATION_TYPE = "pi-context/continuation";
-export const MAX_NOTE_BYTES = 1_000_000;
+export { MAX_NOTE_BYTES, MAX_NOTE_PATH_BYTES } from "./notes/constants.js";
 export const POCKET_SESSION_LIMIT = 5;
 export const POCKET_PROJECT_LIMIT = 2;
 export const POCKET_HUMAN_LIMIT = 2;
 export const POCKET_AGENT_LIMIT = 1;
 export const POCKET_MODEL_LIMIT = 1;
-// Write-time cap on a virtual note path. Deliberately NOT enforced by assertVirtualPath:
-// notesFromSession replays already-persisted operations, which must keep loading sessions
-// that contain a longer legacy path. Reads and replay stay un-capped.
-export const MAX_NOTE_PATH_BYTES = 512;
 export const CONTEXT_WINDOW_OPEN_TAG = "<context_window>";
 export const CONTEXT_WINDOW_CLOSE_TAG = "</context_window>";
 export const CONTEXT_WINDOW_PROTOCOL_OPEN_TAG = "<context_window_protocol>";
@@ -54,4 +50,6 @@ Session notes belong to this trip — the goal, the progress, the loose ends. Th
 @self notes are yours — your voice, your lessons, your gripes — 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 — 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}`;
-export const 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 — anything not in the note dies with the window.";
+export const WARNING_PROMPT = "Your memory is about to be erased. Stop the current task and 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. Use as many note/tool turns as needed to finish the checkpoint. When it is ready, call wipe_memory to reset immediately; otherwise finish normally and the extension will reset at your normal stop. Anything not in the note dies with the window.";
+/** Identical hidden close-out message for manual and budget-triggered requests. */
+export const WARNING_CONTENT = `${GUIDANCE_OPEN_TAG}\n${WARNING_PROMPT}\n${GUIDANCE_CLOSE_TAG}`;

package/dist/src/session-reader.d.ts

@@ -0,0 +1,5 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+/** Read-only projection boundary: no UI, scheduling, model, or write capabilities. */
+export type SessionReader = {
+    sessionManager: Pick<ExtensionContext["sessionManager"], "getSessionId" | "getBranch">;
+};

package/dist/src/settings.d.ts

@@ -0,0 +1,6 @@
+export type PiContextSettings = {
+    reminderMarginTokens?: unknown;
+    dreamer?: unknown;
+};
+/** Merge the global and project "pi-context" objects per key; project wins, mirroring Pi's deep merge. */
+export declare function mergePiContextSettings(globalSettings: unknown, projectSettings: unknown): PiContextSettings;

package/dist/src/tool-output.d.ts

@@ -0,0 +1,101 @@
+export declare const TOOL_OUTPUT_MAX_BYTES: number;
+export declare const DEFAULT_READ_WINDOW_CHARS = 12000;
+export declare const MAX_READ_WINDOW_CHARS = 50000;
+export declare const HISTORY_PREVIEW_CHARS = 1200;
+/** True when `value` serializes within the same wire budget `output()` enforces. */
+export declare function withinBudget(value: unknown, budget?: number): boolean;
+/** True when `text` fits the wire budget verbatim, for raw payloads with no JSON encoding. */
+export declare function withinTextBudget(text: string, budget?: number): boolean;
+/** Marker standing in for characters elided from the middle of an oversized single unit. */
+export declare function truncationMarker(removedChars: number): string;
+/**
+ * Middle-truncate `text` until `fits` accepts it, keeping a head and a tail joined by
+ * `truncationMarker`. Codex's `truncate_middle` semantics: when one indivisible unit
+ * (a note line, a single match, a history item) exceeds the wire budget on its own, it is
+ * still returned — visibly truncated — so cursors advance and no page comes back empty.
+ * Returns `text` unchanged when it already fits.
+ */
+export declare function middleTruncate(text: string, fits: (content: string) => boolean): string;
+/**
+ * Longest contiguous prefix of `text` (counted in code points) accepted by `fits`.
+ *
+ * This is the truncation used by every cursor-bearing payload: the delivered text is
+ * always a plain prefix of the original, so a cursor computed from its code-point length
+ * addresses exactly the first undelivered character. No marker character is ever appended;
+ * the companion `truncated`/`total_chars` fields name what was left out.
+ */
+export declare function prefixFit(text: string, fits: (content: string) => boolean): string;
+/**
+ * Fields every character-window read returns; each tool adds its own identity and metadata.
+ * `offset_chars` is always the resolved absolute offset, and `next_offset_chars` is exactly
+ * that offset plus the delivered code-point count, null only at the text's true end.
+ */
+export type CharacterWindow = {
+    offset_chars: number;
+    content: string;
+    total_chars: number;
+    next_offset_chars: number | null;
+};
+/**
+ * Read one character window of `text`: the longest contiguous prefix of
+ * `chars[resolved, resolved + limit)` that fits the wire budget.
+ *
+ * `offsetChars` is a code-point offset. A negative value counts back from the end and
+ * resolves to `max(0, total_chars + offsetChars)`, so `-N` reaches the tail and any
+ * `N >= total_chars` reads from the start; the resolved absolute offset is always echoed.
+ * Following `next_offset_chars` reconstructs `text` by plain concatenation, because the
+ * payload is always a plain prefix with no marker. `render` builds the exact response for
+ * a candidate window, and `measure` decides whether that response fits the wire budget (JSON
+ * serialization by default; raw-text renders pass a verbatim byte measure), so the budget is
+ * always measured on the bytes that go on the wire.
+ */
+export declare function readCharacterWindow<T>(text: string, offsetChars: number | undefined, limitChars: number | undefined, render: (window: CharacterWindow) => T, measure?: (rendered: T) => boolean): T;
+/**
+ * Fixed metadata block preceding any raw character-window payload. Callers supply their
+ * source identity fields in wire order; range and continuation semantics are shared.
+ */
+export declare function readWindowBlock(identity: ReadonlyArray<readonly [string, string]>, window: CharacterWindow): string;
+/**
+ * Code-point offset of the earliest occurrence of any of `queries` in `text`, or 0 when
+ * none occurs. Shared by the two search tools so a match address is computed identically.
+ */
+export declare function earliestMatchOffsetChars(text: string, queries: string[]): number;
+/** Shrink a single page item to fit; only invoked when that item alone exceeds the budget. */
+export type ItemTruncator<T> = (item: T, fits: (candidate: T) => boolean) => T;
+/**
+ * Build a page without ever adding an item that would exceed the wire budget.
+ *
+ * A single item that cannot fit is middle-truncated through the optional `truncate`
+ * callback and still included, with `next_cursor` advanced past it. Without that treatment
+ * an oversized item would yield an empty page forever: the cursor would keep pointing back
+ * at the same index.
+ */
+export declare function page<T>(items: T[], cursor: number, key: string, limit?: number, truncate?: ItemTruncator<T>): {
+    [key]: T[];
+    next_cursor: number | null;
+};
+/**
+ * Encode a structured result through the common tool result boundary. `details` is slim
+ * metadata for logs/UI (pi convention: never a second copy of the payload) and stays
+ * undefined unless the tool has metadata worth persisting.
+ */
+export declare function output(value: unknown, details?: unknown, terminate?: boolean): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: unknown;
+    terminate: boolean;
+};
+/**
+ * Encode a prose payload as raw text: metadata prefix, a blank line, then the payload
+ * verbatim. `details` carries the slim metadata object and never duplicates the payload.
+ */
+export declare function outputRaw(header: string, content: string, details: unknown, terminate?: boolean): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    details: unknown;
+    terminate: boolean;
+};

package/dist/src/tool-schema.d.ts

@@ -0,0 +1,17 @@
+import { Type } from "@earendil-works/pi-ai";
+export declare const nullableString: () => Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+export declare const positiveInteger: () => Type.TOptional<Type.TInteger>;
+export declare const cursor: () => Type.TOptional<Type.TInteger>;
+export declare const recentFirst: () => Type.TOptional<Type.TBoolean>;
+/** Role filter. `developer` is the known author for this extension's own custom entries. */
+export declare const role: Type.TUnion<[Type.TLiteral<"user">, Type.TLiteral<"assistant">, Type.TLiteral<"tool_call">, Type.TLiteral<"tool">, Type.TLiteral<"system">, Type.TLiteral<"developer">, Type.TNull]>;
+/** Search query parameter: one literal, or several literals combined with OR. */
+export declare const searchQuery: () => Type.TUnion<[Type.TString, Type.TArray<Type.TString>]>;
+/**
+ * Normalize a search `query` parameter into the literal needles to match.
+ * A bare string is a one-element list, so single-query behavior is unchanged.
+ * An empty list, a non-string element, or an empty string is refused rather than silently
+ * searching for nothing: those are argument errors, not empty result sets. An empty string
+ * matches every line and every item, so it can never be what the caller meant.
+ */
+export declare function searchQueries(query: unknown): string[];

package/dist/test/agent-loop.test.d.ts

@@ -0,0 +1 @@
+export {};