@astrosheep/pi-context 0.26.0 → 0.26.2

package/dist/src/tool-output.js

@@ -1,3 +1,4 @@
+export { earliestMatchOffsetChars } from "./text-match.js";
 export const TOOL_OUTPUT_MAX_BYTES = 32 * 1024;
 export const DEFAULT_READ_WINDOW_CHARS = 12000;
 export const MAX_READ_WINDOW_CHARS = 50000;
@@ -111,21 +112,6 @@ export function readWindowBlock(identity, window) {
     const fields = identity.map(([name, value]) => `${name}: ${value}`).join("\n");
     return `--- READ WINDOW ---\n${fields}\nchars: [${window.offset_chars},${end}) of ${window.total_chars}\nnext_offset_chars: ${next}\n`;
 }
-/**
- * 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 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;
-}
 /**
  * Build a page without ever adding an item that would exceed the wire budget.
  *

package/dist/test/agent-loop.test.js

@@ -127,7 +127,7 @@ async function openFixture(options) {
                     assert.ok(sessionManager.getBranch().some((entry) => entry.type === "custom" && entry.customType === RESET_MARKER_TYPE && entry.data?.windowId === windowId), "notification follows the reset marker commit");
                     assert.ok(sessionManager.getBranch().some((entry) => entry.type === "custom_message" && entry.customType === BOOT_TYPE && entry.details?.windowId === windowId), "notification follows the reset boot commit");
                 }
-                if (type === "warning" && sessionManager.getBranch().some((entry) => entry.type === "custom_message" && (entry.customType === GUIDANCE_TYPE || entry.customType === WARNING_TYPE)))
+                if (type === "warning" && /^pi-context: Context (?:almost full|running low)/.test(message))
                     budgetNotices++;
                 notices.push(message);
             },
@@ -213,30 +213,98 @@ function assertFreshRequest(fixture, requestIndex, oldSentinel) {
     assert.ok(body.includes(CONTEXT_WINDOW_OPEN_TAG), "the new provider request includes the fresh context-window boot");
     assert.equal(body.split(CONTINUATION).length - 1, 1, "the fresh window carries exactly one reset message");
 }
-test("real AgentSession: aborted low-budget requests notify only after a retry commits the reminder", async () => {
+test("real AgentSession: aborted early guidance retries silently with automatic reset disabled", async () => {
     let fixture;
     fixture = await openFixture({
         compactionEnabled: false,
         script: (request) => assistant(fixture, [{ type: "text", text: `response ${request}` }], request === 2 ? "aborted" : "stop", { usage: usage(50_000) }),
     });
     try {
-        const reminders = () => fixture.sessionManager.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === GUIDANCE_TYPE);
+        const guidance = () => fixture.sessionManager.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === GUIDANCE_TYPE);
         const notices = () => fixture.budgetNotices();
         await fixture.session.prompt("Establish usage below the reminder line.");
         await fixture.session.waitForIdle();
-        assert.equal(reminders().length, 0);
+        assert.equal(guidance().length, 0);
         await fixture.session.prompt("Abort this low-budget request.");
         await fixture.session.waitForIdle();
-        assert.equal(reminders().length, 0, "an aborted turn does not commit its reminder");
-        assert.equal(notices(), 0, "an uncommitted reminder never notifies");
+        assert.equal(guidance().length, 0, "an aborted turn does not commit early guidance");
+        assert.equal(notices(), 0, "early guidance never notifies");
         await fixture.session.prompt("Retry successfully.");
         await fixture.session.waitForIdle();
-        assert.equal(reminders().length, 1);
-        assert.equal(notices(), 1, "the committed retry notifies once");
+        assert.equal(guidance().length, 1, "the successful retry commits the model guidance");
+        assert.equal(notices(), 0, "committed early guidance stays UI-silent");
         await fixture.session.prompt("Continue in the same window.");
         await fixture.session.waitForIdle();
-        assert.equal(reminders().length, 1);
-        assert.equal(notices(), 1, "later turns cannot repeat the notice");
+        assert.equal(guidance().length, 1);
+        assert.equal(notices(), 0, "later turns cannot toast the early reminder");
+    }
+    finally {
+        fixture.close();
+    }
+});
+test("real AgentSession: an aborted final warning stays silent until a successful retry commits it", async () => {
+    let fixture;
+    fixture = await openFixture({
+        compactionEnabled: true,
+        script: (request, context) => {
+            if (request === 1)
+                return assistant(fixture, [{ type: "toolCall", id: "abort-budget-probe-1", name: "get_context_remaining", arguments: {} }], "toolUse", { usage: usage(50_000) });
+            if (request === 2)
+                return assistant(fixture, [{ type: "toolCall", id: "abort-budget-probe-2", name: "get_context_remaining", arguments: {} }], "toolUse", { usage: usage(60_000) });
+            assert.ok(text(context).includes(WARNING_PROMPT), "the final warning reaches the model on both attempts");
+            return assistant(fixture, [{ type: "text", text: `response ${request}` }], request === 3 ? "aborted" : "stop", { usage: usage(60_000) });
+        },
+    });
+    try {
+        const warnings = () => fixture.sessionManager.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === WARNING_TYPE);
+        const notices = () => fixture.budgetNotices();
+        await fixture.session.prompt("Establish usage and reach the final runway.");
+        await fixture.session.waitForIdle();
+        assert.equal(fixture.requests.length, 3, "budget probes reach one final-warning attempt");
+        assert.equal(warnings().length, 0, "the aborted attempt leaves no durable warning");
+        assert.equal(notices(), 0, "an uncommitted warning never notifies");
+        await fixture.session.prompt("Retry successfully.");
+        await fixture.session.waitForIdle();
+        assert.equal(warnings().length, 1, "the successful retry commits one hidden warning");
+        assert.equal(resetMarkers(fixture).length, 1, "normal close-out resets after the committed warning");
+        assert.equal(notices(), 1, "the committed warning notifies once, including after reset");
+        assert.equal(fixture.notices.some((notice) => notice.includes("Context running low")), false, "early guidance remains UI-silent");
+    }
+    finally {
+        fixture.close();
+    }
+});
+test("real AgentSession: final warning survives its reset boundary and notifies once", { timeout: 20000 }, async () => {
+    let fixture;
+    fixture = await openFixture({
+        compactionEnabled: true,
+        script: (request, context) => {
+            if (request === 1)
+                return assistant(fixture, [{ type: "toolCall", id: "final-budget-probe-1", name: "get_context_remaining", arguments: {} }], "toolUse", { usage: usage(50_000) });
+            if (request === 2)
+                return assistant(fixture, [{ type: "toolCall", id: "final-budget-probe-2", name: "get_context_remaining", arguments: {} }], "toolUse", { usage: usage(60_000) });
+            if (request === 3) {
+                assert.ok(text(context).includes(WARNING_PROMPT), "the final warning reaches the model");
+                return assistant(fixture, [{ type: "toolCall", id: "final-budget-wipe", name: "wipe_memory", arguments: {} }], "toolUse", { usage: usage(60_000) });
+            }
+            return assistant(fixture, [{ type: "text", text: "fresh window ready" }]);
+        },
+    });
+    try {
+        assert.equal(fixture.notices.length, 0, "boot is silent");
+        await fixture.session.prompt("FINAL_WARNING_RESET_SENTINEL");
+        await fixture.session.waitForIdle();
+        assert.equal(fixture.requests.length, 4, "two budget probes, close-out tool, and fresh-window request run");
+        assertFreshRequest(fixture, 3, "FINAL_WARNING_RESET_SENTINEL");
+        assert.equal(fixture.sessionManager.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === WARNING_TYPE).length, 1);
+        assert.equal(resetMarkers(fixture).length, 1, "the reset commits in the same boundary as the final warning");
+        assert.equal(fixture.budgetNotices(), 1, "the old-window committed warning reaches the UI after reset");
+        assert.equal(fixture.notices.filter((notice) => notice.startsWith("pi-context: memory cleared · ")).length, 1, "reset notification remains intact");
+        assert.equal(fixture.notices.some((notice) => notice.includes("Context running low")), false, "early guidance stays silent");
+        await fixture.session.prompt("Continue after reset.");
+        await fixture.session.waitForIdle();
+        assert.equal(fixture.budgetNotices(), 1, "later turns cannot repeat the consumed final warning");
+        assert.equal(fixture.notices.filter((notice) => notice.startsWith("pi-context: memory cleared · ")).length, 1, "the prior reset notification is also deduplicated");
     }
     finally {
         fixture.close();

package/dist/test/boot.integration.test.js

@@ -4,11 +4,9 @@ import test from "node:test";
 import { historyFromSession, internal } from "../src/index.js";
 import { listNotes } from "./helpers/notes.js";
 import { CONTINUATION_TYPE, WARNING_TYPE } from "../src/protocol.js";
-import { appendText, call, commitTurnEndBoundary, context, installExtensionTestEnvironment, makeExtension, manager, noticesOf, resultJson, resultRead, runContextHook, runContextWithSystemHook, runHandlers, runManualCompact, runCommand, sentOf, } from "./helpers/extension.js";
-const testEnvironment = installExtensionTestEnvironment("pi-context-integration");
-test.beforeEach(() => testEnvironment.beforeEach());
-test.afterEach(() => testEnvironment.afterEach());
-test.after(() => testEnvironment.dispose());
+import { appendText, call, commitTurnEndBoundary, context, makeExtension, manager, noticesOf, resultJson, resultRead, runContextHook, runContextWithSystemHook, runHandlers, runManualCompact, runCommand, sentOf, } from "./helpers/extension.js";
+import { installExtensionTestHooks } from "./helpers/extension-test-environment.js";
+const testEnvironment = installExtensionTestHooks("pi-context-integration");
 test("custom reset marker removes old provider context while history remains searchable", async () => {
     const sessionManager = manager();
     const captured = makeExtension(sessionManager);
@@ -50,7 +48,7 @@ test("the root boot and reset boot carry durable window identity", async () => {
     const ctx = context(sessionManager);
     appendText(sessionManager, "user", "task before reset");
     appendText(sessionManager, "assistant", "working");
-    await call(captured, "notes_write", { path: "decisions.md", content: "use terra" }, ctx);
+    await call(captured, "notes_write", { address: "decisions.md", content: "use terra" }, ctx);
     // Root window: session_start persists the boot block without triggering a turn.
     await runHandlers(captured, "session_start", { reason: "startup" }, ctx);
     assert.equal(captured.sent.length, 1);
@@ -71,7 +69,7 @@ test("the root boot and reset boot carry durable window identity", async () => {
     assert.ok(rootText.includes("decisions.md"));
     const decisionsMeta = (await listNotes(ctx, { scope: "session" })).find((row) => row.path === "decisions.md")?.meta;
     assert.ok(decisionsMeta);
-    assert.match(rootText, /updated \d+s ago\)/, "boot note metadata carries a relative update time");
+    assert.match(rootText, /·  \d+s ago/, "boot note metadata carries a relative update time");
     assert.ok(rootText.includes(internal.CONTEXT_WINDOW_PROTOCOL_OPEN_TAG));
     // Reset: the marker and boot are committed together at the turn boundary.
     await call(captured, "wipe_memory", {}, ctx);

package/dist/test/budget-settings.integration.test.js

@@ -1,11 +1,9 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import { internal } from "../src/index.js";
-import { appendText, call, commitTurnEndBoundary, context, installExtensionTestEnvironment, makeExtension, manager, noticesOf, resultJson, runContextHook, runHandlers, sentOf, settingsFixture, } from "./helpers/extension.js";
-const testEnvironment = installExtensionTestEnvironment("pi-context-integration");
-test.beforeEach(() => testEnvironment.beforeEach());
-test.afterEach(() => testEnvironment.afterEach());
-test.after(() => testEnvironment.dispose());
+import { appendText, call, commitTurnEndBoundary, context, makeExtension, manager, noticesOf, resultJson, runContextHook, runHandlers, sentOf, settingsFixture, } from "./helpers/extension.js";
+import { installExtensionTestHooks } from "./helpers/extension-test-environment.js";
+const testEnvironment = installExtensionTestHooks("pi-context-integration");
 test("low-budget guidance and warning persist at turn_end, once per active window", async () => {
     const sessionManager = manager();
     const captured = makeExtension(sessionManager);
@@ -24,6 +22,23 @@ test("low-budget guidance and warning persist at turn_end, once per active windo
     assert.equal(warningBoundary.entries.filter((entry) => entry.type === "custom_message" && entry.customType === internal.WARNING_TYPE).length, 1);
     assert.equal(sessionManager.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === internal.WARNING_TYPE).length, 1);
 });
+test("early guidance stays silent and the committed final warning notifies once", async () => {
+    const sm = manager();
+    const captured = makeExtension(sm);
+    const early = context(sm, undefined, { tokens: 165_000, percent: 82.5, contextWindow: 200_000 });
+    assert.equal(await runContextHook(captured, early), undefined, "early guidance is persisted at turn_end, not injected immediately");
+    await commitTurnEndBoundary(captured, sm, early);
+    await runHandlers(captured, "agent_settled", {}, early);
+    assert.equal(noticesOf(early).filter((notice) => notice.message.includes("Context running low") || notice.message.includes("Context almost full")).length, 0, "early model guidance has no UI toast");
+    assert.equal(sm.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === internal.GUIDANCE_TYPE).length, 1, "early guidance remains durable for the model");
+    const final = context(sm, undefined, { tokens: 181_000, percent: 90.5, contextWindow: 200_000 });
+    const warning = await runContextHook(captured, final);
+    assert.equal(warning?.messages[0]?.customType, internal.WARNING_TYPE);
+    await commitTurnEndBoundary(captured, sm, final);
+    await runHandlers(captured, "turn_start", {}, final);
+    await runHandlers(captured, "agent_settled", {}, final);
+    assert.equal(noticesOf(final).filter((notice) => notice.message === "pi-context: Context almost full; close out the current memory window.").length, 1, "only the committed final warning notifies, exactly once");
+});
 test("the visible countdown ends at the warning line, clamps at zero, and preserves unknown usage", async () => {
     const fixture = settingsFixture({
         reserveTokens: 16_384,

package/dist/test/doctor.test.js

@@ -6,13 +6,12 @@ import test from "node:test";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 const note = "---\norigin: self\nstatus: active\nstale: false\ncreatedAt: 2026-01-01T00:00:00Z\nupdatedAt: 2026-01-01T00:00:00Z\nlastAccessed: 2026-01-01T00:00:00Z\naccessCount: 0\n---\n\n";
-test("doctor identifies legacy metadata as requiring manual migration", (t) => {
-    const root = mkdtempSync(join(tmpdir(), "dream-doctor-legacy-"));
+test("doctor ignores unknown frontmatter keys while validating canonical metadata", (t) => {
+    const root = mkdtempSync(join(tmpdir(), "dream-doctor-extra-"));
     t.after(() => rmSync(root, { recursive: true, force: true }));
     mkdirSync(join(root, "human"));
-    writeFileSync(join(root, "human/legacy.md"), note.replace("createdAt", "created_at"));
-    const issues = doctor(root);
-    assert.ok(issues.some((issue) => issue.includes("legacy metadata key created_at; manually migrate to createdAt")));
+    writeFileSync(join(root, "human/extra.md"), note.replace("accessCount: 0", "accessCount: 0\ncreated_at: 2025-01-01\nupdated_at: 2025-01-01\nlast_accessed: 2025-01-01\naccess_count: 7\nsource_window: old\nrecurrence_count: 2\nrecurrence_windows: old"));
+    assert.deepEqual(doctor(root), [], "unknown fields have no special diagnostics");
 });
 test("doctor validates without repairing files or running the dreamer", async () => {
     const root = mkdtempSync(join(tmpdir(), "dream-doctor-test-"));

package/dist/test/helpers/extension-test-environment.d.ts

@@ -0,0 +1 @@
+export declare function installExtensionTestHooks(prefix: string): import("./extension.js").ExtensionTestEnvironment;

package/dist/test/helpers/extension-test-environment.js

@@ -0,0 +1,9 @@
+import test from "node:test";
+import { installExtensionTestEnvironment } from "./extension.js";
+export function installExtensionTestHooks(prefix) {
+    const environment = installExtensionTestEnvironment(prefix);
+    test.beforeEach(() => environment.beforeEach());
+    test.afterEach(() => environment.afterEach());
+    test.after(() => environment.dispose());
+    return environment;
+}

package/dist/test/helpers/extension.d.ts

@@ -88,19 +88,8 @@ export type ReadWindow = {
 };
 /** Decode either raw read without including its shared metadata block in the payload. */
 export declare function resultRead(result: AgentToolResult<unknown>): ReadWindow;
-/**
- * Assert a value is a local-time ISO 8601 string with an explicit numeric offset (never "Z")
- * and that Date.parse restores the stored epoch milliseconds. No time zone is assumed.
- */
-export declare function assertLocalIso(value: unknown, epochMs: number, message: string): void;
-/** Assert the text contains a well-formed local ISO timestamp and return it, without pinning surrounding wording. */
-export declare function assertIsoTimestamp(text: string, message: string): string;
-/** Assert `actual` is a middle-truncation of `original`: same head, same tail, strictly fewer characters. */
-export declare function assertTruncationOf(original: string, actual: string): void;
 export declare function runManualCompact(captured: Captured, ctx: ExtensionContext): Promise<CompactionHookResult>;
 export declare function runHandlers(captured: Captured, name: string, event: unknown, ctx: ExtensionContext): Promise<void>;
-export declare function runHandlersAsync(captured: Captured, name: string, event: unknown, ctx: ExtensionContext): Promise<unknown[]>;
-export declare function completeRequestedCompaction(ctx: ExtensionContext): void;
 export declare function runCommand(captured: Captured, name: string, args: string, ctx: ExtensionContext): Promise<Notice[]>;
 export type ContextHookResult = {
     messages: unknown[];

package/dist/test/helpers/extension.js

@@ -166,41 +166,12 @@ export function sentOf(captured, customType) {
 export async function call(captured, name, params, ctx) {
     const tool = captured.tools.get(name);
     assert.ok(tool, `registered ${name}`);
-    // Most pre-redesign coverage names session notes by their bare address. Keep these old
-    // fixture call sites readable while routing the direct tool invocation through its new
-    // address-shaped input; contract-specific tests below pass address themselves.
-    const noteCall = name === "notes_write" || name === "notes_edit" || name === "notes_read";
-    if (noteCall && "path" in params && !("address" in params)) {
-        const { path, scope, ...rest } = params;
-        assert.equal(typeof path, "string", "legacy note fixture path is a string");
-        const address = scope === "project" ? `@project/${path}` : scope === "human" ? `@human/${path}` : path;
-        return tool.execute("call-1", { ...rest, address }, new AbortController().signal, () => { }, ctx);
-    }
-    if ((name === "notes_list" || name === "notes_search") && params.scope === "human") {
-        const { scope: _scope, pattern, ...rest } = params;
-        return tool.execute("call-1", { ...rest, pattern: `@human/${typeof pattern === "string" ? pattern : "**"}` }, new AbortController().signal, () => { }, ctx);
-    }
-    if ((name === "notes_list" || name === "notes_search") && params.scope === "session") {
-        const { scope: _scope, pattern, ...rest } = params;
-        return tool.execute("call-1", { ...rest, pattern: typeof pattern === "string" ? pattern : "*.md" }, new AbortController().signal, () => { }, ctx);
-    }
     return tool.execute("call-1", params, new AbortController().signal, () => { }, ctx);
 }
 export function resultJson(result) {
     const text = result.content[0];
     assert.ok(text && text.type === "text", "tool result carries text");
-    const value = JSON.parse(text.text);
-    const suffix = (address) => address.startsWith("@project/") ? address.slice("@project/".length) : address.startsWith("@human/") ? address.slice("@human/".length) : address;
-    const legacyPath = (row) => {
-        if (typeof row.address === "string" && row.path === undefined)
-            Object.defineProperty(row, "path", { value: suffix(row.address), enumerable: false });
-    };
-    legacyPath(value);
-    if (Array.isArray(value.files))
-        for (const file of value.files)
-            if (file && typeof file === "object")
-                legacyPath(file);
-    return value;
+    return JSON.parse(text.text);
 }
 /** Assert the delivered wire text fits the tool-output budget, header included for raw reads. */
 export function assertWithinBudget(result, message) {
@@ -223,32 +194,6 @@ export function resultRead(result) {
     assert.equal(Array.from(content).length, end - offset_chars, "READ WINDOW range matches the delivered payload");
     return { header, content, offset_chars, total_chars, next_offset_chars, details: (result.details ?? {}) };
 }
-/**
- * Assert a value is a local-time ISO 8601 string with an explicit numeric offset (never "Z")
- * and that Date.parse restores the stored epoch milliseconds. No time zone is assumed.
- */
-export function assertLocalIso(value, epochMs, message) {
-    assert.equal(typeof value, "string", message);
-    assert.match(value, /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}[+-]\d{2}:\d{2}$/, message);
-    assert.equal(Date.parse(value), epochMs, `${message}: Date.parse restores the stored epoch ms`);
-}
-/** Assert the text contains a well-formed local ISO timestamp and return it, without pinning surrounding wording. */
-export function assertIsoTimestamp(text, message) {
-    const match = text.match(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}[+-]\d{2}:\d{2}/);
-    assert.ok(match, message);
-    assert.equal(Number.isNaN(Date.parse(match[0])), false, `${message}: timestamp parses`);
-    return match[0];
-}
-/** Assert `actual` is a middle-truncation of `original`: same head, same tail, strictly fewer characters. */
-export function assertTruncationOf(original, actual) {
-    const match = actual.match(/^([\s\S]*)…\[truncated \d+ chars\]…([\s\S]*)$/);
-    assert.ok(match, "truncated value carries the middle-truncation marker");
-    const head = match[1];
-    const tail = match[2];
-    assert.ok(original.startsWith(head), "truncation keeps the original head");
-    assert.ok(original.endsWith(tail), "truncation keeps the original tail");
-    assert.ok(head.length + tail.length < original.length, "truncation actually removes characters");
-}
 export async function runManualCompact(captured, ctx) {
     const handler = captured.handlers.get("session_before_compact")?.[0];
     assert.ok(handler, "session_before_compact handler registered");
@@ -282,25 +227,6 @@ export async function runHandlers(captured, name, event, ctx) {
         ctx.isIdle = isIdle;
     }
 }
-export async function runHandlersAsync(captured, name, event, ctx) {
-    const results = [];
-    for (const handler of captured.handlers.get(name) ?? [])
-        results.push(await handler(event, ctx));
-    return results;
-}
-export function completeRequestedCompaction(ctx) {
-    const requests = ctx.compactionRequests;
-    const options = requests.shift();
-    assert.ok(options?.onComplete, "a reset request has a completion callback");
-    const isIdle = ctx.isIdle;
-    ctx.isIdle = () => true;
-    try {
-        options.onComplete({});
-    }
-    finally {
-        ctx.isIdle = isIdle;
-    }
-}
 export async function runCommand(captured, name, args, ctx) {
     const command = captured.commands.get(name);
     assert.ok(command, `${name} command registered`);

package/dist/test/history.integration.test.js

@@ -2,11 +2,9 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import { historyFromSession } from "../src/index.js";
 import { TOOL_OUTPUT_MAX_BYTES } from "../src/tool-output.js";
-import { appendText, assertWithinBudget, call, context, installExtensionTestEnvironment, makeExtension, manager, objectSchema, resultJson, resultRead, } from "./helpers/extension.js";
-const testEnvironment = installExtensionTestEnvironment("pi-context-integration");
-test.beforeEach(() => testEnvironment.beforeEach());
-test.afterEach(() => testEnvironment.afterEach());
-test.after(() => testEnvironment.dispose());
+import { appendText, assertWithinBudget, call, context, makeExtension, manager, objectSchema, resultJson, resultRead, } from "./helpers/extension.js";
+import { installExtensionTestHooks } from "./helpers/extension-test-environment.js";
+const testEnvironment = installExtensionTestHooks("pi-context-integration");
 test("schemas cover the History/Notes actions plus reset controls", () => {
     const captured = makeExtension(manager());
     for (const name of [
@@ -94,7 +92,7 @@ test("paged tool outputs stay bounded and cursors reconstruct history and notes"
     }
     assert.equal(readParts.join(""), historyText);
     for (let index = 0; index < 100; index++) {
-        await call(captured, "notes_write", { path: `page-${"x".repeat(120)}-${index}.md`, content: Array.from({ length: 1000 }, (_, line) => `needle ${line} ${"z".repeat(30)}`).join("\n") }, ctx);
+        await call(captured, "notes_write", { address: `page-${"x".repeat(120)}-${index}.md`, content: Array.from({ length: 1000 }, (_, line) => `needle ${line} ${"z".repeat(30)}`).join("\n") }, ctx);
     }
     const listPages = [];
     let listOffset = 0;
@@ -102,7 +100,7 @@ test("paged tool outputs stay bounded and cursors reconstruct history and notes"
     while (listNext !== null) {
         const result = resultJson(await call(captured, "notes_list", { max_results: 300, cursor: listOffset }, ctx));
         assert.ok(Buffer.byteLength(JSON.stringify(result), "utf8") <= TOOL_OUTPUT_MAX_BYTES);
-        listPages.push(...result.files.map((file) => file.path));
+        listPages.push(...result.files.map((file) => file.address));
         listNext = result.next_cursor;
         if (listNext !== null)
             listOffset = listNext;
@@ -127,7 +125,7 @@ test("paged tool outputs stay bounded and cursors reconstruct history and notes"
     let noteOffset = 0;
     let noteNext = 0;
     while (noteNext !== null) {
-        const raw = await call(captured, "notes_read", { path: `page-${"x".repeat(120)}-0.md`, offset_chars: noteOffset }, ctx);
+        const raw = await call(captured, "notes_read", { address: `page-${"x".repeat(120)}-0.md`, offset_chars: noteOffset }, ctx);
         assertWithinBudget(raw, `notes_read page at ${noteOffset}`);
         const result = resultRead(raw);
         // The window is a plain prefix of the file, so the pages join by plain concatenation.
@@ -172,7 +170,7 @@ test("a page cap limits the page, not the enumerable set: cursors stay truthful
     assert.equal(searchTail.next_cursor, null);
     // notes_search: max_files caps the page, not the matched files.
     for (let index = 0; index < 7; index++)
-        await call(captured, "notes_write", { path: `needle-${index}.md`, content: "needle" }, ctx);
+        await call(captured, "notes_write", { address: `needle-${index}.md`, content: "needle" }, ctx);
     const notes = async (params) => resultJson(await call(captured, "notes_search", params, ctx));
     const notesFirst = await notes({ query: "needle", max_files: 3 });
     assert.equal(notesFirst.files.length, 3);
@@ -200,18 +198,18 @@ test("multi-query search: OR semantics, dedupe, and bare-string backward compati
     assert.deepEqual(await historyIds({ query: ["alpha"] }), [bothId, alphaId], "history: a one-element array searches that literal");
     assert.deepEqual(await historyIds({ query: "alpha" }), orIds.filter((id) => id !== betaId), "history: a bare string still behaves exactly as before");
     assert.deepEqual(await historyIds({ query: "alpha" }), await historyIds({ query: ["alpha"] }), "history: bare string equals the single-element list");
-    await call(captured, "notes_write", { path: "both.md", content: "alpha beta\nunrelated" }, ctx);
-    await call(captured, "notes_write", { path: "alpha.md", content: "alpha only" }, ctx);
-    await call(captured, "notes_write", { path: "beta.md", content: "beta only" }, ctx);
-    await call(captured, "notes_write", { path: "gamma.md", content: "gamma only" }, ctx);
+    await call(captured, "notes_write", { address: "both.md", content: "alpha beta\nunrelated" }, ctx);
+    await call(captured, "notes_write", { address: "alpha.md", content: "alpha only" }, ctx);
+    await call(captured, "notes_write", { address: "beta.md", content: "beta only" }, ctx);
+    await call(captured, "notes_write", { address: "gamma.md", content: "gamma only" }, ctx);
     const notesSearch = async (params) => resultJson(await call(captured, "notes_search", params, ctx)).files;
     const orFiles = await notesSearch({ query: ["alpha", "beta"] });
-    assert.deepEqual(orFiles.map((file) => file.path), ["alpha.md", "beta.md", "both.md"], "notes: a file matching any query is returned once, path-ordered");
-    assert.equal(orFiles.find((file) => file.path === "both.md")?.matches.length, 1, "notes: one line containing both queries is reported once");
-    assert.deepEqual((await notesSearch({ query: ["alpha"] })).map((file) => file.path), ["alpha.md", "both.md"], "notes: a one-element array searches that literal");
-    assert.deepEqual((await notesSearch({ query: "alpha" })).map((file) => file.path), ["alpha.md", "both.md"], "notes: a bare string still behaves exactly as before");
-    assert.deepEqual((await notesSearch({ query: "alpha" })).map((file) => file.path), (await notesSearch({ query: ["alpha"] })).map((file) => file.path), "notes: bare string equals the single-element list");
-    assert.deepEqual((await notesSearch({ query: ["gamma"] })).map((file) => file.path), ["gamma.md"]);
+    assert.deepEqual(orFiles.map((file) => file.address), ["alpha.md", "beta.md", "both.md"], "notes: a file matching any query is returned once, address-ordered");
+    assert.equal(orFiles.find((file) => file.address === "both.md")?.matches.length, 1, "notes: one line containing both queries is reported once");
+    assert.deepEqual((await notesSearch({ query: ["alpha"] })).map((file) => file.address), ["alpha.md", "both.md"], "notes: a one-element array searches that literal");
+    assert.deepEqual((await notesSearch({ query: "alpha" })).map((file) => file.address), ["alpha.md", "both.md"], "notes: a bare string still behaves exactly as before");
+    assert.deepEqual((await notesSearch({ query: "alpha" })).map((file) => file.address), (await notesSearch({ query: ["alpha"] })).map((file) => file.address), "notes: bare string equals the single-element list");
+    assert.deepEqual((await notesSearch({ query: ["gamma"] })).map((file) => file.address), ["gamma.md"]);
     // An empty array is an argument error, not a silently empty result set.
     await assert.rejects(() => call(captured, "history_search", { query: [] }, ctx), /non-empty array of strings/, "history: empty query array is refused");
     await assert.rejects(() => call(captured, "notes_search", { query: [] }, ctx), /non-empty array of strings/, "notes: empty query array is refused");

package/dist/test/notes-library.test.js

@@ -91,6 +91,23 @@ test("stores snapshot explicit identity and do not leak homes across instances",
     assert.equal((await notes.read("@agents/visitor/hello"))?.body, "visiting");
     await assert.rejects(() => notes.write("@agents/visitor/hello", "overwrite"), (error) => error instanceof NoteError && error.code === "invalid_scope");
 });
+test("list and search share scoped pattern scans and search offsets count Unicode code points", async (t) => {
+    const { notes } = fixture(t);
+    await notes.write("shared.md", "😀 needle in session");
+    await notes.write("@project/shared.md", "needle in project");
+    await notes.write("@human/shared.md", "needle in human");
+    await notes.write("@project/elsewhere.md", "unrelated");
+    const pattern = "**/shared.md";
+    const listed = await notes.list({ pattern });
+    const searched = await notes.search(["needle"], { pattern });
+    const listedAddresses = listed.map((row) => row.address).sort();
+    const searchedAddresses = searched.map((row) => row.address).sort();
+    assert.deepEqual(searchedAddresses, ["@human/shared.md", "@project/shared.md", "shared.md"]);
+    assert.deepEqual(searchedAddresses, listedAddresses, "list and search traverse the same filtered homes and files");
+    const sessionMatch = searched.find((row) => row.address === "shared.md").matches[0];
+    const serialized = (await notes.read("shared.md")).text;
+    assert.ok(Array.from(serialized).slice(sessionMatch.offsetChars).join("").startsWith("needle"), "the absolute offset counts the emoji as one code point");
+});
 test("invalid addressing and failed edits leave stored bytes untouched without poisoning the queue", async (t) => {
     const { home, context, notes } = fixture(t);
     assert.throws(() => createNotesStore({ ...context, sessionId: "../escape" }));