@astrosheep/pi-context 0.19.0 → 0.20.0

package/dist/src/budget.js

@@ -0,0 +1,63 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { GUIDANCE_TYPE, WARNING_TYPE } from "./protocol.js";
+import { thresholdsFor, resetThresholds } from "./thresholds.js";
+import { currentWindowId, hasWindowMessage } from "./history.js";
+import { tokenBudgetGuidance } from "./prompts.js";
+import { output } from "./tool-output.js";
+export { deriveThresholds, mergePiContextSettings } from "./thresholds.js";
+export function registerBudget(pi, isEnabled) {
+    let guidancePersistedInWindow;
+    pi.on("session_start", (_event, ctx) => { guidancePersistedInWindow = undefined; resetThresholds(); thresholdsFor(ctx); });
+    pi.on("session_tree", () => { guidancePersistedInWindow = undefined; resetThresholds(); });
+    pi.on("context", (_event, ctx) => {
+        if (!isEnabled() || hasWindowMessage(ctx, GUIDANCE_TYPE))
+            return undefined;
+        // The early reminder persists once per window the first time remaining crosses
+        // reserve+margin. It never edits the outgoing request.
+        const usage = ctx.getContextUsage();
+        if (!usage || usage.tokens === null)
+            return undefined;
+        const remaining = Math.max(0, usage.contextWindow - usage.tokens);
+        const windowId = currentWindowId(ctx);
+        const { reminder, reserve, warning } = thresholdsFor(ctx);
+        // The final warning owns the deep band: when it has fired (or is due now),
+        // the shallow reminder would only repeat the same instruction closer to
+        // the wipe, at a worse position. See warning.ts.
+        if (remaining <= warning || hasWindowMessage(ctx, WARNING_TYPE))
+            return undefined;
+        if (remaining <= reminder && guidancePersistedInWindow !== windowId && !hasWindowMessage(ctx, GUIDANCE_TYPE)) {
+            guidancePersistedInWindow = windowId;
+            // Persist once per window — no transient copy. A transient bridge would
+            // cover the crossing request, but history would record the reminder after
+            // that request's assistant reply, so across the boundary the model would
+            // meet the same text twice at shifted positions. The reminder is an early
+            // warning, not a per-request instruction: arriving from the next request
+            // on (sendMessage defers safely to end of turn while streaming, queueing
+            // instead of splitting a tool call/result pair) costs nothing, and the
+            // model's view stays identical to recorded history, Codex-style.
+            // The persisted copy stays out of the TUI (display: false); one ephemeral
+            // notify tells the user instead — visible to the human, invisible to the
+            // model, and never recorded, so history and the model's view don't diverge.
+            // The model-facing count ends at the warning line: what lies below is the
+            // runway, invisible by design. The human's notify keeps the honest count.
+            const left = Math.max(0, remaining - warning);
+            pi.sendMessage({ customType: GUIDANCE_TYPE, content: tokenBudgetGuidance(left), display: false }, { triggerTurn: false });
+            ctx.ui.notify(`pi-context: context budget low (${Math.max(0, remaining - reserve)} tokens before reserve) — checkpoint reminder recorded for the model, kept out of the chat view.`, "warning");
+        }
+        return undefined;
+    });
+    pi.registerTool(defineTool({
+        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: Type.Object({}, { additionalProperties: false }),
+        async execute(_id, _params, _signal, _update, ctx) {
+            const usage = ctx.getContextUsage();
+            // The countdown the model sees ends at the warning line (reserve + runway);
+            // the runway below it is overdraft the model never sees. See protocol.ts.
+            const remaining = usage?.tokens === null || usage === undefined ? null : Math.max(0, usage.contextWindow - usage.tokens - thresholdsFor(ctx).warning);
+            return output({ remaining_tokens: remaining });
+        },
+    }));
+}

package/dist/src/dream/apply.js

@@ -0,0 +1,87 @@
+import { mkdirSync, renameSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { editNote, peekNote, resolveNoteScope, updateNoteMeta, writeNote } from "../memory/store.js";
+import { physicalPath } from "../memory/paths.js";
+function target(ctx, value, required = true) {
+    const m = /^(session|project|global):(.*)$/.exec(value);
+    if (m) {
+        const scope = m[1];
+        const path = m[2];
+        const physical = physicalPath(scope, path, ctx);
+        if (!existsSync(physical)) {
+            if (required)
+                throw new Error(`unknown path: ${value}`);
+            return undefined;
+        }
+        return { scope, path };
+    }
+    const found = resolveNoteScope(ctx, value);
+    if (!found && required)
+        throw new Error(`unknown path: ${value}`);
+    return found ? { scope: found.scope, path: value } : undefined;
+}
+function body(ctx, t) { return peekNote(ctx, t.scope, t.path); }
+export function applyManifest(ctx, home, stamp, manifest) {
+    const actions = [];
+    // Resolve every referenced note and promotion destination before the first mutation.
+    for (const m of manifest.merge ?? []) {
+        target(ctx, m.into);
+        for (const p of m.from)
+            target(ctx, p);
+    }
+    for (const p of manifest.promote ?? []) {
+        const from = target(ctx, p.path);
+        if (p.to !== "global") {
+            if (!["session", "project"].includes(p.to))
+                throw new Error(`invalid promotion scope: ${p.to}`);
+            if (existsSync(physicalPath(p.to, p.path, ctx)))
+                throw new Error(`promotion collision: ${p.path}`);
+        }
+        void from;
+    }
+    for (const p of manifest.trash ?? [])
+        target(ctx, p.path);
+    for (const merge of manifest.merge ?? []) {
+        const into = target(ctx, merge.into);
+        const sources = merge.from.map((p) => target(ctx, p));
+        const base = body(ctx, into);
+        const chunks = [base.body, ...sources.map((s) => body(ctx, s).body)].filter(Boolean);
+        const dedup = [...new Set(chunks)].join("\n\n");
+        writeNote(ctx, into.path, dedup, { scope: into.scope, origin: base.meta.origin });
+        updateNoteMeta(ctx, into.path, into.scope, (meta) => { meta.recurrence_count = (meta.recurrence_count ?? 0) + sources.length; meta.recurrence_windows = [...new Set([...(meta.recurrence_windows ?? []), ...sources.map((s) => body(ctx, s).meta.source_window).filter((x) => typeof x === "string")])]; });
+        for (const source of sources)
+            updateNoteMeta(ctx, source.path, source.scope, (meta) => { meta.status = "superseded"; meta.supersedes = merge.into; });
+        actions.push(`merged ${merge.from.join(", ")} into ${merge.into}`);
+    }
+    for (const p of manifest.promote ?? []) {
+        const from = target(ctx, p.path);
+        const m = body(ctx, from);
+        const scope = p.to;
+        if (!["session", "project", "global"].includes(scope))
+            throw new Error(`invalid promotion scope: ${p.to}`);
+        if (scope === "global") {
+            actions.push(`proposal: promote ${p.path} to global (${p.reason})`);
+            continue;
+        }
+        const dest = physicalPath(scope, p.path, ctx);
+        if (existsSync(dest))
+            throw new Error(`promotion collision: ${p.path}`);
+        editNote(ctx, from.path, undefined, { scope });
+        actions.push(`promoted ${p.path} to ${scope}`);
+    }
+    const trashRoot = join(home, "trash", stamp);
+    mkdirSync(trashRoot, { recursive: true });
+    for (const item of manifest.trash ?? []) {
+        const t = target(ctx, item.path);
+        const source = physicalPath(t.scope, t.path, ctx);
+        const dest = join(trashRoot, t.scope, t.path.endsWith(".md") ? t.path : `${t.path}.md`);
+        mkdirSync(dirname(dest), { recursive: true });
+        renameSync(source, dest);
+        actions.push(`trashed ${item.path}: ${item.reason}`);
+    }
+    for (const p of manifest.pending ?? [])
+        actions.push(`pending ${p.path}: ${p.reason}`);
+    for (const p of manifest.skillCandidates ?? [])
+        actions.push(`skill proposal ${p.title}: ${p.rationale}`);
+    return actions;
+}

package/dist/src/dream/cli.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { acquireLock, failLock, releaseLock } from "./lock.js";
+import { materialGate, timeGate } from "./gates.js";
+import { loadPlaybook, runDreamer } from "./runner.js";
+import { applyManifest } from "./apply.js";
+function args(argv) { const out = {}; for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--force" || a === "--help")
+        out[a.slice(2)] = true;
+    else if (a.startsWith("--"))
+        out[a.slice(2)] = argv[++i] ?? "";
+} return out; }
+function packageRoot() {
+    let dir = dirname(new URL(import.meta.url).pathname);
+    while (true) {
+        if (existsSync(join(dir, "package.json")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            throw new Error("could not locate installed package root");
+        dir = parent;
+    }
+}
+export async function main(argv = process.argv.slice(2)) {
+    const a = args(argv);
+    if (a.help) {
+        console.log("dream --notes-home <dir> [--min-hours 24] [--min-sessions 3] [--force] [--dreamer <cmd>] [--dreamer-model <pattern>] [--playbook <path>]\nDefault dreamer: in-process pi SDK session with read-only tools; use a cheap model in production. Default playbook: <installed package root>/playbook.md; --playbook overrides it.");
+        return 0;
+    }
+    const home = resolve(String(a["notes-home"] ?? process.env.PI_NOTES_HOME ?? join(homedir(), ".agents", "notes")));
+    process.env.PI_NOTES_HOME = home;
+    mkdirSync(home, { recursive: true });
+    const lockPath = join(home, ".dream.lock");
+    const minHours = Number(a["min-hours"] ?? 24);
+    const minSessions = Number(a["min-sessions"] ?? 3);
+    const time = timeGate(lockPath, minHours);
+    console.log(time.reason);
+    if (!a.force && !time.ok)
+        return 0;
+    const material = materialGate(home, existsSync(lockPath) ? statSync(lockPath).mtimeMs : 0, minSessions);
+    console.log(material.reason);
+    if (!a.force && !material.ok)
+        return 0;
+    let lock;
+    try {
+        lock = acquireLock(lockPath);
+    }
+    catch (e) {
+        console.log(`lock gate: ${e instanceof Error ? e.message : e}`);
+        return 0;
+    }
+    if (!lock.held) {
+        console.log(lock.reason);
+        return 0;
+    }
+    const stamp = new Date(lock.startedAt).toISOString().replace(/[:.]/g, "-");
+    const reportPath = join(home, "dreams", `${stamp}.md`);
+    try {
+        const defaultBook = join(packageRoot(), "playbook.md");
+        const playbookPath = String(a.playbook ?? defaultBook);
+        const playbook = loadPlaybook(playbookPath);
+        const manifest = await runDreamer(playbook, home, { command: a.dreamer ? String(a.dreamer) : undefined, modelPattern: a["dreamer-model"] ? String(a["dreamer-model"]) : undefined });
+        const ctx = { cwd: home, sessionManager: { getSessionId: () => "dream" } };
+        const actions = applyManifest(ctx, home, stamp, manifest);
+        mkdirSync(join(home, "dreams"), { recursive: true });
+        writeFileSync(reportPath, `# Dream ${stamp}\n\n${manifest.report}\n\n${actions.map((x) => `- ${x}`).join("\n")}\n`);
+        console.log(reportPath);
+        return 0;
+    }
+    catch (e) {
+        failLock(lock);
+        console.error(e instanceof Error ? e.message : e);
+        return 1;
+    }
+    finally {
+        releaseLock(lock);
+    }
+}
+main().then((code) => { process.exitCode = code; });

package/dist/src/dream/gates.js

@@ -0,0 +1,21 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+export function timeGate(lockPath, minHours, now = Date.now()) {
+    if (!existsSync(lockPath))
+        return { ok: true, reason: "time gate: no prior lock" };
+    const age = now - statSync(lockPath).mtimeMs;
+    return age >= minHours * 3600000 ? { ok: true, reason: "time gate: stale" } : { ok: false, reason: "time gate: lock is too fresh" };
+}
+export function materialGate(home, lockMtime, minSessions) {
+    const root = join(home, "pi", "session");
+    let changed = 0;
+    if (existsSync(root))
+        for (const dir of readdirSync(root, { withFileTypes: true })) {
+            if (!dir.isDirectory())
+                continue;
+            const files = readdirSync(join(root, dir.name), { withFileTypes: true });
+            if (files.some((f) => f.isFile() && statSync(join(root, dir.name, f.name)).mtimeMs > lockMtime))
+                changed++;
+        }
+    return changed >= minSessions ? { ok: true, reason: `material gate: ${changed} changed sessions` } : { ok: false, reason: `material gate: only ${changed} changed sessions` };
+}

package/dist/src/dream/lock.js

@@ -0,0 +1,58 @@
+import { existsSync, readFileSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
+const HOUR = 60 * 60 * 1000;
+function live(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function acquireLock(path) {
+    const now = Date.now();
+    let priorMtime;
+    if (existsSync(path)) {
+        const stat = statSync(path);
+        priorMtime = stat.mtimeMs;
+        let pid = 0;
+        try {
+            pid = Number.parseInt(readFileSync(path, "utf8").trim(), 10);
+        }
+        catch { /* reclaim */ }
+        if (now - stat.mtimeMs <= HOUR && live(pid))
+            return { path, held: false, reason: "lock gate: live process holds the lock", startedAt: now };
+        try {
+            unlinkSync(path);
+        }
+        catch {
+            return { path, held: false, reason: "lock gate: lock could not be reclaimed", startedAt: now };
+        }
+    }
+    writeFileSync(path, String(process.pid), { flag: "wx" });
+    return { path, held: true, startedAt: now, priorMtime };
+}
+export function releaseLock(lock) {
+    // The lock is also the durable last-dream timestamp. Leave the PID marker in place;
+    // the next acquisition reclaims it once the PID is dead or it is older than an hour.
+}
+export function restoreMtime(path, mtimeMs) {
+    try {
+        utimesSync(path, new Date(), new Date(mtimeMs));
+    }
+    catch { /* advisory */ }
+}
+export function failLock(lock) {
+    if (!lock.held)
+        return;
+    if (lock.priorMtime === undefined) {
+        try {
+            unlinkSync(lock.path);
+        }
+        catch { /* best effort */ }
+    }
+    else
+        restoreMtime(lock.path, lock.priorMtime);
+}

package/dist/src/dream/manifest.js

@@ -0,0 +1,16 @@
+export function parseManifest(output) {
+    const starts = [...output.matchAll(/[\{[]/g)].map((m) => m.index ?? 0).reverse();
+    for (const start of starts) {
+        try {
+            const value = JSON.parse(output.slice(start));
+            if (!value || typeof value !== "object" || typeof value.report !== "string")
+                continue;
+            for (const key of ["merge", "promote", "trash", "pending", "skillCandidates"])
+                if (value[key] !== undefined && !Array.isArray(value[key]))
+                    throw new Error("invalid array");
+            return value;
+        }
+        catch { /* try an earlier JSON start */ }
+    }
+    throw new Error("dreamer did not return a valid JSON manifest");
+}

package/dist/src/dream/runner.js

@@ -0,0 +1,56 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createAgentSession, ModelRuntime, resolveModelScopeWithDiagnostics, SessionManager } from "@earendil-works/pi-coding-agent";
+import { parseManifest } from "./manifest.js";
+export const READ_ONLY_TOOLS = ["read", "grep", "find", "ls", "notes_read", "notes_list", "notes_search"];
+export const defaultDreamerSessionFactory = async ({ cwd, modelPattern, tools }) => {
+    let model;
+    if (modelPattern) {
+        const runtime = await ModelRuntime.create({ allowModelNetwork: false, refreshOnCreate: false });
+        const result = await resolveModelScopeWithDiagnostics([modelPattern], runtime);
+        model = result.scopedModels[0]?.model;
+        if (!model)
+            throw new Error(`dreamer model pattern "${modelPattern}" did not resolve to an available model`);
+    }
+    const { session } = await createAgentSession({ cwd, sessionManager: SessionManager.inMemory(cwd), tools, noTools: "all", model });
+    return session;
+};
+export function runExternalDreamer(command, playbook, cwd) {
+    const result = spawnSync(command, { shell: true, cwd, input: playbook, encoding: "utf8" });
+    if (result.error || result.status !== 0)
+        throw new Error(`dreamer failed: ${result.error?.message ?? result.stderr ?? `exit ${result.status}`}`);
+    return parseManifest(result.stdout);
+}
+export async function runDreamer(playbook, cwd, options = {}) {
+    if (options.command)
+        return runExternalDreamer(options.command, playbook, cwd);
+    const session = await (options.sessionFactory ?? defaultDreamerSessionFactory)({ cwd, modelPattern: options.modelPattern, tools: READ_ONLY_TOOLS });
+    let answer = "";
+    let providerError;
+    const unsubscribe = session.subscribe((event) => {
+        if (event.type !== "message_end" || event.message?.role !== "assistant")
+            return;
+        if (event.message.stopReason === "error") {
+            providerError = event.message.errorMessage ?? "unknown provider error";
+            return;
+        }
+        const content = event.message.content;
+        answer = typeof content === "string" ? content : Array.isArray(content) ? content.filter((part) => part.type === "text").map((part) => part.text).join("") : "";
+    });
+    try {
+        await session.prompt(`${playbook}\n\nReturn exactly one JSON manifest matching this schema: { merge?, promote?, trash?, pending?, skillCandidates?, report }.`);
+        try {
+            return parseManifest(answer);
+        }
+        catch (error) {
+            if (providerError)
+                throw new Error(`dreamer failed: ${providerError}`);
+            throw error;
+        }
+    }
+    finally {
+        unsubscribe?.();
+        session.dispose();
+    }
+}
+export function loadPlaybook(path) { return readFileSync(path, "utf8"); }

package/dist/src/history-tools.js

@@ -0,0 +1,105 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { output, outputRaw, page, middleTruncate, prefixFit, earliestMatchOffsetChars, readCharacterWindow, characterWindowHeader, withinTextBudget } from "./tool-output.js";
+import { positiveInteger, recentFirst, nullableString, role, cursor, searchQuery, searchQueries } from "./tool-schema.js";
+import { historyFromSession, filteredItems, visibleItem, allItems, vacuousRoleToolCombo, unknownWindowId } from "./history.js";
+/**
+ * Shrink one page item to fit the wire budget. `truncated`/`total_chars` stay honest: the
+ * payload is only ever cut to a plain prefix of itself, never filled with a marker, and the
+ * flag flips on whenever a shrink actually removed characters. `tool_name` is metadata, not a
+ * payload, and keeps its visible middle-truncation marker. `item_id`, `window_id`, and `role`
+ * are identity or tiny metadata and are never touched.
+ */
+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;
+    // Content could not help even as an empty prefix: tool_name is oversized, so keep the
+    // original payload and truncate the metadata as the last resort.
+    const withName = { ...item, tool_name: middleTruncate(item.tool_name, (candidate) => fits({ ...item, tool_name: candidate })) };
+    if (fits(withName))
+        return withName;
+    // Both fields are oversized: dissolve the payload against the truncated metadata.
+    return shrinkContent(withName);
+}
+export function registerHistoryTools(pi) {
+    pi.registerTool(defineTool({
+        name: "history_windows",
+        label: "History list windows",
+        description: "List durable Pi session-history windows.",
+        parameters: Type.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 before compaction, using opaque item and window IDs; 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: Type.Object({ limit: positiveInteger(), cursor: cursor(), recent_first: recentFirst(), role: Type.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 ?? 1200));
+            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 is the raw item text behind a one-line [bracketed] header naming the item, the resolved offset, the delivered char range, and the resume cursor (continue at offset_chars=N, or end).",
+        parameters: Type.Object({ item_id: Type.String(), offset_chars: Type.Optional(Type.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: Type.Optional(Type.Integer({ minimum: 1, maximum: 50000, description: "Largest requested window in code points (default 12000). A window too large for the wire budget is cut short; next_offset_chars names where the next read resumes." })), window_id: Type.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;
+            // A positive offset past the end is an addressing error, not an empty page: say so,
+            // and name the largest legal offset (offset == total stays the legal empty end-read).
+            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 });
+            }
+            const limit_chars = Math.min(params.limit_chars ?? 12000, 50000);
+            return readCharacterWindow(item.content, params.offset_chars, params.limit_chars, (window) => {
+                const { content, ...cursor } = window;
+                return outputRaw(characterWindowHeader(`${item.windowId} · item ${item.itemId}`, window), content, { window_id: item.windowId, item_id: item.itemId, ...cursor, limit_chars });
+            }, (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: Type.Object({ limit: positiveInteger(), cursor: cursor(), query: searchQuery(), recent_first: recentFirst(), role: Type.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 ?? 1200), match_offset_chars: earliestMatchOffsetChars(item.content, queries) }));
+            return output(page(matching, params.cursor ?? 0, "items", params.limit, truncateHistoryItem));
+        },
+    }));
+}