@astrosheep/pi-context 0.24.0 → 0.25.0

package/dist/test/helpers/extension.js

@@ -0,0 +1,393 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import piContext, { createPiContext } from "../../src/index.js";
+import { loadNotesSnapshot } from "../../src/notes/notes-snapshot.js";
+import { renderBootBlock } from "../../src/context/prompts.js";
+import { agentSlug, modelSlug } from "../../src/notes/paths.js";
+import { rootWindowId } from "../../src/context/context-window.js";
+import { TOOL_OUTPUT_MAX_BYTES } from "../../src/tool-output.js";
+let defaultCwd = "/private/tmp/pi-context-test-cwd";
+let registerTempPath;
+/**
+ * Install the process-level settings and notes roots needed by one test file.
+ * The caller owns the lifecycle hooks; this helper never registers tests or hooks.
+ */
+export function installExtensionTestEnvironment(prefix = "pi-context-test") {
+    const previousAgentDir = process.env.PI_CODING_AGENT_DIR;
+    const previousNotesHome = process.env.PI_NOTES_HOME;
+    const defaultAgentDir = mkdtempSync(join(tmpdir(), `${prefix}-agent-`));
+    const cwd = mkdtempSync(join(tmpdir(), `${prefix}-cwd-`));
+    defaultCwd = cwd;
+    const notesRoots = new Set();
+    const tempPaths = new Set();
+    registerTempPath = (path) => { tempPaths.add(path); };
+    const newNotesRoot = () => {
+        const root = mkdtempSync(join(tmpdir(), `${prefix}-notes-`));
+        notesRoots.add(root);
+        process.env.PI_NOTES_HOME = root;
+        return root;
+    };
+    const beforeEach = () => {
+        process.env.PI_CODING_AGENT_DIR = defaultAgentDir;
+        newNotesRoot();
+    };
+    const afterEach = () => {
+        process.env.PI_CODING_AGENT_DIR = defaultAgentDir;
+        for (const root of notesRoots)
+            rmSync(root, { recursive: true, force: true });
+        notesRoots.clear();
+        for (const path of tempPaths)
+            rmSync(path, { recursive: true, force: true });
+        tempPaths.clear();
+        if (previousNotesHome === undefined)
+            delete process.env.PI_NOTES_HOME;
+        else
+            process.env.PI_NOTES_HOME = previousNotesHome;
+    };
+    const dispose = () => {
+        afterEach();
+        for (const root of notesRoots)
+            rmSync(root, { recursive: true, force: true });
+        rmSync(defaultAgentDir, { recursive: true, force: true });
+        rmSync(cwd, { recursive: true, force: true });
+        registerTempPath = undefined;
+        if (previousAgentDir === undefined)
+            delete process.env.PI_CODING_AGENT_DIR;
+        else
+            process.env.PI_CODING_AGENT_DIR = previousAgentDir;
+        if (previousNotesHome === undefined)
+            delete process.env.PI_NOTES_HOME;
+        else
+            process.env.PI_NOTES_HOME = previousNotesHome;
+    };
+    return { cwd, agentDir: defaultAgentDir, beforeEach, afterEach, newNotesRoot, dispose };
+}
+export function writeJson(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value, null, 2));
+}
+/**
+ * Materialize global (agentDir/settings.json) and project (cwd/.pi/settings.json)
+ * settings in temp directories, then read them back through the same public
+ * SettingsManager.create the extension uses. Never touches the real ~/.pi.
+ */
+export function settingsFixture(options = {}) {
+    const cwd = mkdtempSync(join(tmpdir(), "pi-context-cwd-"));
+    const agentDir = mkdtempSync(join(tmpdir(), "pi-context-agent-"));
+    const global = { ...(options.global ?? {}) };
+    if (options.reserveTokens !== undefined)
+        global.compaction = { reserveTokens: options.reserveTokens };
+    writeJson(join(agentDir, "settings.json"), global);
+    if (options.project)
+        writeJson(join(cwd, ".pi", "settings.json"), options.project);
+    process.env.PI_CODING_AGENT_DIR = agentDir;
+    registerTempPath?.(cwd);
+    registerTempPath?.(agentDir);
+    const fixtureManager = SettingsManager.create(cwd, agentDir, { projectTrusted: true });
+    const projectReserve = options.project?.compaction?.reserveTokens;
+    assert.equal(fixtureManager.getCompactionSettings().reserveTokens, projectReserve ?? options.reserveTokens ?? 16_384, "fixture reserve reads back");
+    return { cwd, agentDir };
+}
+/** TypeBox's TSchema does not expose `type`/`required` statically; read them structurally. */
+export function objectSchema(tool) {
+    return tool?.parameters;
+}
+export function manager(persisted = false) {
+    if (!persisted)
+        return SessionManager.inMemory("/private/tmp/pi-context-test");
+    const dir = mkdtempSync(join(tmpdir(), "pi-context-session-"));
+    return SessionManager.create("/private/tmp/pi-context-test", dir);
+}
+export function makeExtension(sessionManager, settingsManager) {
+    const captured = { tools: new Map(), handlers: new Map(), commands: new Map(), sent: [], contextMessages: [], flags: [] };
+    const api = {
+        registerFlag(name) {
+            captured.flags.push(name);
+        },
+        registerTool(tool) {
+            captured.tools.set(tool.name, tool);
+        },
+        registerCommand(name, options) {
+            captured.commands.set(name, options);
+        },
+        on(name, handler) {
+            const handlers = captured.handlers.get(name) ?? [];
+            handlers.push(handler);
+            captured.handlers.set(name, handlers);
+        },
+        appendEntry(customType, data) {
+            sessionManager.appendCustomEntry(customType, data);
+        },
+        sendMessage(message, options) {
+            captured.sent.push({ message, options });
+            sessionManager.appendCustomMessageEntry(message.customType, message.content, message.display, message.details);
+        },
+    };
+    // The harness implements only the ExtensionAPI members this extension uses.
+    (settingsManager ? createPiContext({ settingsManager }) : piContext)(api);
+    return captured;
+}
+export function explicitBoot(ctx, currentWindowId, previousWindowId, resetLine) {
+    return renderBootBlock({
+        agentName: agentSlug(ctx),
+        modelName: modelSlug(ctx),
+        firstWindowId: rootWindowId(ctx.sessionManager.getSessionId()),
+        currentWindowId,
+        previousWindowId,
+        resetLine,
+        notes: loadNotesSnapshot(ctx),
+    });
+}
+export function context(sessionManager, compact, usage, idle = true, cwd = defaultCwd, projectTrusted = true, model) {
+    const notices = [];
+    const compactionRequests = [];
+    const fake = {
+        sessionManager,
+        model: typeof model === "string" ? { id: model } : model,
+        getContextUsage: () => usage,
+        compact: (options) => { compactionRequests.push(options); compact?.(options); },
+        isIdle: () => idle,
+        hasPendingMessages: () => false,
+        cwd,
+        isProjectTrusted: () => projectTrusted,
+        ui: { notify: (message, type) => notices.push({ message, type }) },
+    };
+    // Only the members the extension reads; the rest of the ExtensionContext surface is unused.
+    return Object.assign(fake, { notices, compactionRequests });
+}
+export function noticesOf(ctx) {
+    return ctx.notices;
+}
+export function sentOf(captured, customType) {
+    return captured.sent.filter((sent) => sent.message.customType === 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;
+}
+/** Assert the delivered wire text fits the tool-output budget, header included for raw reads. */
+export function assertWithinBudget(result, message) {
+    const text = result.content[0];
+    const bytes = text && text.type === "text" ? Buffer.byteLength(text.text, "utf8") : 0;
+    assert.ok(bytes <= TOOL_OUTPUT_MAX_BYTES, `${message}: ${bytes} bytes over the ${TOOL_OUTPUT_MAX_BYTES}-byte budget`);
+}
+/** Decode either raw read without including its shared metadata block in the payload. */
+export function resultRead(result) {
+    const text = result.content[0];
+    assert.ok(text && text.type === "text", "read result carries text");
+    const block = /^(--- READ WINDOW ---\n(?:[a-z_]+: [^\n]*\n)+chars: \[(\d+),(\d+)\) of (\d+)\nnext_offset_chars: (null|\d+)\n)\n/.exec(text.text);
+    assert.ok(block, "raw read carries one READ WINDOW block followed by exactly one blank line");
+    const header = block[1];
+    const content = text.text.slice(block[0].length);
+    const offset_chars = Number(block[2]);
+    const end = Number(block[3]);
+    const total_chars = Number(block[4]);
+    const next_offset_chars = block[5] === "null" ? null : Number(block[5]);
+    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");
+    const event = {
+        type: "session_before_compact",
+        reason: "manual",
+        willRetry: false,
+        signal: new AbortController().signal,
+        branchEntries: ctx.sessionManager.getBranch(),
+        preparation: {
+            firstKeptEntryId: "",
+            messagesToSummarize: [],
+            turnPrefixMessages: [],
+            isSplitTurn: false,
+            tokensBefore: 0,
+            fileOps: { read: new Set(), written: new Set(), edited: new Set() },
+            settings: { enabled: true, reserveTokens: 0, keepRecentTokens: 0 },
+        },
+    };
+    return (await handler(event, ctx));
+}
+export function runHandlers(captured, name, event, ctx) {
+    const isIdle = ctx.isIdle;
+    if (name === "agent_settled")
+        ctx.isIdle = () => true;
+    try {
+        for (const handler of captured.handlers.get(name) ?? [])
+            handler(event, ctx);
+    }
+    finally {
+        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`);
+    const notices = [];
+    const cmdCtx = Object.assign({}, ctx, {
+        waitForIdle: async () => { },
+        ui: { notify: (message, type) => notices.push({ message, type }) },
+    });
+    await command.handler(args, cmdCtx);
+    return notices;
+}
+export async function runContextHook(captured, ctx, eventOverride = {}) {
+    const handlers = captured.handlers.get("context") ?? [];
+    assert.ok(handlers.length > 0, "context handler registered");
+    // Pi invokes every registered context handler in order; budget and warning each own one.
+    let result;
+    for (const handler of handlers) {
+        const returned = (await handler({ type: "context", messages: [], ...eventOverride }, ctx));
+        if (returned !== undefined) {
+            captured.contextMessages.push(...returned.messages);
+            result = result ? { messages: [...result.messages, ...returned.messages] } : returned;
+        }
+    }
+    return result;
+}
+export async function runContextWithSystemHook(captured, ctx, messages) {
+    const handlers = captured.handlers.get("context_with_system") ?? [];
+    assert.ok(handlers.length > 0, "context_with_system handler registered");
+    let result;
+    for (const handler of handlers) {
+        const returned = (await handler({ type: "context_with_system", messages }, ctx));
+        if (returned !== undefined) {
+            captured.contextMessages.push(...returned.messages);
+            result = result ? { messages: [...result.messages, ...returned.messages] } : returned;
+        }
+    }
+    return result;
+}
+export async function commitTurnEndBoundary(captured, sessionManager, ctx) {
+    let entries = [];
+    let shouldContinue = false;
+    const event = {
+        type: "turn_end",
+        entries,
+        continue: false,
+        context: { contextEntries: [], contextMessages: [], llmMessages: [], pendingMessages: [], canContinue: true },
+        outcome: "completed",
+        turnIndex: 0,
+        message: { role: "assistant", content: [], stopReason: "stop", timestamp: Date.now() },
+        toolResults: [],
+        messageEntryId: "assistant-entry",
+        toolResultEntryIds: [],
+    };
+    for (const handler of captured.handlers.get("turn_end") ?? []) {
+        event.entries = entries;
+        const result = (await handler(event, ctx));
+        if (result?.entries !== undefined)
+            entries = result.entries;
+        if (result?.continue !== undefined)
+            shouldContinue = result.continue;
+    }
+    for (const entry of entries) {
+        switch (entry.type) {
+            case "custom":
+                sessionManager.appendCustomEntry(entry.customType, entry.data);
+                break;
+            case "custom_message":
+                sessionManager.appendCustomMessageEntry(entry.customType, entry.content, entry.display, entry.details);
+                break;
+            case "compaction":
+                sessionManager.appendCompaction(entry.summary, entry.firstKeptEntryId, 0, entry.details, true, entry.usage);
+                break;
+            case "context_edit":
+                sessionManager.appendContextEdit(entry.targetId, entry.replacement);
+                break;
+        }
+    }
+    return { entries, continue: shouldContinue };
+}
+export function appendText(sessionManager, role, text, toolName = "bash") {
+    const base = {
+        role,
+        content: [{ type: "text", text }],
+        timestamp: Date.now(),
+        ...(role === "assistant" ? { stopReason: "stop" } : {}),
+        ...(role === "toolResult" ? { toolCallId: "call-1", toolName, isError: false } : {}),
+    };
+    return sessionManager.appendMessage(base);
+}