@cortexkit/opencode-magic-context 0.46.1 → 0.48.0

package/src/shared/host-stall-profiler-node.test.ts

@@ -0,0 +1,234 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import * as path from "node:path";
+import {
+    PROFILE_WINDOW_MS,
+    SWITCH_POLL_MS,
+    WATCHDOG_INTERVAL_MS,
+} from "./host-stall-profiler-common";
+import {
+    createNodeHostStallProfiler,
+    type InspectorSession,
+    type V8Profile,
+    v8ProfileTraces,
+} from "./host-stall-profiler-node";
+import { aggregateTraces, sourceOwner } from "./host-stall-profiler-report";
+import { createTestTempDir } from "./test-temp-dir";
+
+const profile: V8Profile = {
+    startTime: 500_000,
+    endTime: 530_000,
+    nodes: [
+        {
+            id: 1,
+            callFrame: { functionName: "(root)", url: "", lineNumber: -1, columnNumber: -1 },
+            children: [2],
+        },
+        {
+            id: 2,
+            callFrame: {
+                functionName: "sqliteCaller",
+                url: "/home/test/.pi/agent/npm/node_modules/stall-package/index.js",
+                lineNumber: 9,
+                columnNumber: 0,
+            },
+            children: [3],
+        },
+        { id: 3, callFrame: { functionName: "get", url: "", lineNumber: -1, columnNumber: -1 } },
+    ],
+    samples: [2, 3, 3],
+    timeDeltas: [10_000, 10_000, 10_000],
+};
+
+test("V8 profile conversion reconstructs native callers and cumulative sample times", () => {
+    const traces = v8ProfileTraces(profile, 1000);
+    expect(traces.map((trace) => trace.timestamp)).toEqual([1.01, 1.02, 1.03]);
+    const aggregate = aggregateTraces(traces);
+    expect(aggregate.owners).toEqual([{ owner: "npm:stall-package", samples: 3, percent: 100 }]);
+    expect(aggregate.top_frames[0].frame).toBe("get [native]");
+    expect(aggregate.top_js_frames[0].frame).toContain("sqliteCaller");
+    expect(aggregate.top_js_frames[0].frame).toContain(":10");
+});
+
+test("Pi and OMP paths distinguish extensions, npm packages and host core", () => {
+    expect(sourceOwner("file:///home/test/.pi/agent/extensions/busy.ts")).toBe("extension:busy.ts");
+    expect(sourceOwner("/home/test/.omp/agent/extensions/busy/index.ts")).toBe("extension:busy");
+    expect(sourceOwner("/home/test/.pi/agent/npm/node_modules/@scope/plugin/index.js")).toBe(
+        "npm:@scope/plugin",
+    );
+    expect(sourceOwner("/tmp/node_modules/@earendil-works/pi-coding-agent/dist/main.js")).toBe(
+        "pi",
+    );
+    expect(sourceOwner("/tmp/node_modules/@oh-my-pi/pi-coding-agent/dist/main.js")).toBe("omp");
+    expect(sourceOwner("/tmp/node_modules/@cortexkit/pi-magic-context/dist/index.js")).toBe(
+        "pkg:@cortexkit/pi-magic-context",
+    );
+    const root = createTestTempDir("mc-profiler-owner-").dir;
+    mkdirSync(path.join(root, ".pi/agent/extensions/local"), { recursive: true });
+    writeFileSync(
+        path.join(root, ".pi/agent/extensions/local/package.json"),
+        '{"name":"test-extension"}',
+    );
+    expect(sourceOwner(path.join(root, ".pi/agent/extensions/local/index.js"))).toBe(
+        "pkg:test-extension",
+    );
+    expect(sourceOwner(path.join(import.meta.dir, "../../../pi-plugin/src/index.ts"))).toBe(
+        "pkg:@cortexkit/pi-magic-context",
+    );
+});
+
+const handles: Array<ReturnType<typeof createNodeHostStallProfiler>> = [];
+afterEach(async () => {
+    for (const handle of handles.splice(0)) {
+        handle.stop();
+        await handle.checkNow();
+    }
+});
+
+function setup(loadGate?: Promise<void>) {
+    const root = createTestTempDir("mc-node-profiler-").dir;
+    let now = 0;
+    let startedAt = 0;
+    let stackId = 2;
+    const calls: string[] = [];
+    const timers = new Map<number, () => void>();
+    const api: InspectorSession = {
+        connect() {
+            calls.push("connect");
+        },
+        disconnect() {
+            calls.push("disconnect");
+        },
+        post(method, _params, callback) {
+            calls.push(method);
+            if (method === "Profiler.start") startedAt = now;
+            const samples = Array.from(
+                { length: Math.floor((now - startedAt) / 10) },
+                () => stackId,
+            );
+            callback(
+                null,
+                method === "Profiler.stop"
+                    ? { profile: { ...profile, samples, timeDeltas: samples.map(() => 10_000) } }
+                    : {},
+            );
+        },
+    };
+    const handle = createNodeHostStallProfiler({
+        profilerDir: () => root,
+        now: () => now,
+        wallNow: () => Date.UTC(2026, 9, 10) + now,
+        setInterval: (fn, ms) => {
+            timers.set(ms, fn);
+            return ms;
+        },
+        clearInterval: (id) => {
+            timers.delete(id as number);
+        },
+        rss: () => 123,
+        memoryUsage: () => ({ heapUsed: 42, rss: 123 }),
+        log: () => {},
+        pid: 10,
+        bunVersion: null,
+        createSession: async () => {
+            calls.push("createSession");
+            await loadGate;
+            return api;
+        },
+    });
+    handles.push(handle);
+    const reports = () => readdirSync(root).filter((entry) => entry.startsWith("stall-"));
+    const advance = async (ms: number) => {
+        now += ms;
+        timers.get(WATCHDOG_INTERVAL_MS)?.();
+        await handle.checkNow();
+    };
+    return {
+        root,
+        handle,
+        calls,
+        timers,
+        reports,
+        advance,
+        enable: () => writeFileSync(path.join(root, "enable"), ""),
+        native: () => {
+            stackId = 3;
+        },
+    };
+}
+
+test("Node switch absent creates no inspector; on/off/on disconnects without restart", async () => {
+    const host = setup();
+    host.handle.start();
+    await host.handle.checkNow();
+    expect(host.calls).toEqual([]);
+    expect([...host.timers.keys()]).toEqual([SWITCH_POLL_MS]);
+    host.enable();
+    await host.handle.checkNow();
+    expect(host.calls).toEqual([
+        "createSession",
+        "connect",
+        "Profiler.enable",
+        "Profiler.setSamplingInterval",
+        "Profiler.start",
+    ]);
+    expect(host.handle.isActive()).toBe(true);
+    rmSync(path.join(host.root, "enable"));
+    await host.handle.checkNow();
+    expect(host.calls.slice(-2)).toEqual(["Profiler.stop", "disconnect"]);
+    expect(host.handle.isActive()).toBe(false);
+    expect([...host.timers.keys()]).toEqual([SWITCH_POLL_MS]);
+    host.enable();
+    await host.handle.checkNow();
+    expect(host.calls.filter((call) => call === "connect")).toHaveLength(2);
+});
+
+test("Node rotation discards ordinary windows and retains only samples inside the detected stall", async () => {
+    const host = setup();
+    host.enable();
+    host.handle.start();
+    await host.handle.checkNow();
+    for (let i = 0; i < PROFILE_WINDOW_MS / WATCHDOG_INTERVAL_MS; i++)
+        await host.advance(WATCHDOG_INTERVAL_MS);
+    expect(host.reports()).toEqual([]);
+    expect(host.calls.filter((call) => call === "Profiler.stop")).toHaveLength(1);
+    for (let i = 0; i < 35; i++) await host.advance(WATCHDOG_INTERVAL_MS);
+    host.native();
+    await host.advance(6250);
+    expect(host.reports()).toHaveLength(1);
+    const report = JSON.parse(readFileSync(path.join(host.root, host.reports()[0]), "utf8"));
+    expect(report.backend).toBe("v8");
+    expect(report.sampling.samples_collected).toBe(1500);
+    expect(report.sampling.samples_in_window).toBeLessThan(640);
+    expect(report.sampling.samples_in_window).toBeGreaterThan(620);
+    expect(report.owners[0].owner).toBe("npm:stall-package");
+    expect(report.top_js_frames[0].frame).toContain("sqliteCaller");
+    expect(report.memory.before.heap_size_bytes).toBe(42);
+    expect(report.memory.after.rss_bytes).toBe(123);
+});
+
+test("Node watchdog applies threshold to lateness rather than the whole tick gap", async () => {
+    const host = setup();
+    host.enable();
+    host.handle.start();
+    await host.handle.checkNow();
+    await host.advance(3249);
+    expect(host.reports()).toEqual([]);
+    await host.advance(3250);
+    expect(host.reports()).toHaveLength(1);
+});
+
+test("Node stop during inspector loading cannot resurrect a watchdog", async () => {
+    const { promise, resolve } = Promise.withResolvers<void>();
+    const host = setup(promise);
+    host.enable();
+    host.handle.start();
+    await Promise.resolve();
+    expect(host.calls).toEqual(["createSession"]);
+    host.handle.stop();
+    resolve();
+    await host.handle.checkNow();
+    expect(host.handle.isActive()).toBe(false);
+    expect(host.timers.size).toBe(0);
+    expect(host.calls).toEqual(["createSession"]);
+});

package/src/shared/host-stall-profiler-node.ts

@@ -0,0 +1,274 @@
+import { existsSync, readFileSync } from "node:fs";
+import * as path from "node:path";
+import {
+    DEFAULT_SAMPLE_INTERVAL_MS,
+    DEFAULT_STALL_THRESHOLD_MS,
+    emitStallReport,
+    HOST_PROFILER_ENABLE_FILENAME,
+    type HostStallProfilerHandle,
+    type HostStallProfilerOptions,
+    type MemorySnapshot,
+    PROFILE_WINDOW_MS,
+    type ProfilerRuntimeDeps,
+    parseEnableFile,
+    SWITCH_POLL_MS,
+    WATCHDOG_INTERVAL_MS,
+} from "./host-stall-profiler-common";
+import type { JscSampleFrame, JscSampleTrace } from "./host-stall-profiler-report";
+
+export interface V8Profile {
+    startTime: number;
+    endTime: number;
+    nodes: Array<{
+        id: number;
+        callFrame: { functionName: string; url: string; lineNumber: number; columnNumber: number };
+        children?: number[];
+    }>;
+    samples?: number[];
+    timeDeltas?: number[];
+}
+
+/** V8's timeDeltas are microseconds since the preceding sample, starting at startTime. */
+export function v8ProfileTraces(profile: V8Profile, windowStartMs: number): JscSampleTrace[] {
+    const nodes = new Map(profile.nodes.map((node) => [node.id, node]));
+    const parents = new Map<number, number>();
+    for (const node of profile.nodes)
+        for (const child of node.children ?? []) parents.set(child, node.id);
+    const stacks = new Map<number, JscSampleFrame[]>();
+    const stackFor = (id: number): JscSampleFrame[] => {
+        const cached = stacks.get(id);
+        if (cached) return cached;
+        const frames: JscSampleFrame[] = [];
+        const seen = new Set<number>();
+        let next: number | undefined = id;
+        while (next !== undefined && !seen.has(next)) {
+            seen.add(next);
+            const node = nodes.get(next);
+            if (!node) break;
+            const frame = node.callFrame;
+            // Synthetic root/idle nodes are not JS stacks. Native leaves stay
+            // in the stack so attribution can walk outward to the JS caller.
+            if (frame.functionName !== "(root)" && frame.functionName !== "(idle)") {
+                frames.push({
+                    name: frame.functionName,
+                    sourceURL: frame.url || undefined,
+                    line: frame.lineNumber >= 0 ? frame.lineNumber + 1 : undefined,
+                    column: frame.columnNumber >= 0 ? frame.columnNumber + 1 : undefined,
+                });
+            }
+            next = parents.get(next);
+        }
+        stacks.set(id, frames);
+        return frames;
+    };
+    let elapsedMicros = 0;
+    return (profile.samples ?? []).flatMap((id, index) => {
+        const delta = profile.timeDeltas?.[index];
+        if (typeof delta !== "number" || !Number.isFinite(delta)) return [];
+        elapsedMicros += delta;
+        return [{ timestamp: (windowStartMs + elapsedMicros / 1000) / 1000, frames: stackFor(id) }];
+    });
+}
+
+export interface InspectorSession {
+    connect(): void;
+    disconnect(): void;
+    post(
+        method: string,
+        params: Record<string, unknown>,
+        callback: (error: Error | null, result?: { profile?: V8Profile }) => void,
+    ): void;
+}
+export interface NodeProfilerDeps extends ProfilerRuntimeDeps {
+    createSession(): Promise<InspectorSession>;
+    memoryUsage(): { heapUsed: number; rss: number };
+}
+
+export function createNodeHostStallProfiler(deps: NodeProfilerDeps): HostStallProfilerHandle {
+    let session: InspectorSession | null = null;
+    let pollTimer: unknown = null;
+    let watchdog: unknown = null;
+    let stopped = false;
+    let unavailable = false;
+    let options: HostStallProfilerOptions = {
+        thresholdMs: DEFAULT_STALL_THRESHOLD_MS,
+        sampleIntervalMs: DEFAULT_SAMPLE_INTERVAL_MS,
+    };
+    let lastTickAt = 0;
+    let windowStartMs = 0;
+    let memoryBefore: MemorySnapshot | null = null;
+    let work: Promise<void> = Promise.resolve();
+    const logged = new Set<string>();
+    const safeLog = (message: string) => {
+        try {
+            deps.log(message);
+        } catch {
+            /* A failed diagnostic log must not stop profiling or the host. */
+        }
+    };
+    const fail = (key: string, error: unknown) => {
+        if (logged.has(key)) return;
+        logged.add(key);
+        safeLog(
+            `[magic-context] host stall profiler: ${key}: ${error instanceof Error ? error.message : String(error)}`,
+        );
+    };
+    const post = (api: InspectorSession, method: string, params: Record<string, unknown> = {}) =>
+        new Promise<{ profile?: V8Profile }>((resolve, reject) => {
+            api.post(method, params, (error, result) =>
+                error ? reject(error) : resolve(result ?? {}),
+            );
+        });
+    const snapshot = (): MemorySnapshot => {
+        const memory = deps.memoryUsage();
+        return {
+            at: new Date(deps.wallNow()).toISOString(),
+            heap_size_bytes: memory.heapUsed,
+            rss_bytes: memory.rss,
+            jsc_memory: null,
+            percent_available_memory_in_use: null,
+        };
+    };
+    const disable = async (reason: string) => {
+        if (watchdog !== null) deps.clearInterval(watchdog);
+        watchdog = null;
+        const api = session;
+        session = null;
+        memoryBefore = null;
+        if (!api) return;
+        try {
+            await post(api, "Profiler.stop");
+        } catch (error) {
+            fail("stop failed", error);
+        } finally {
+            try {
+                api.disconnect();
+            } catch (error) {
+                fail("disconnect failed", error);
+            }
+        }
+        safeLog(`[magic-context] host stall profiler disabled: ${reason}`);
+    };
+    const startWindow = async (api: InspectorSession) => {
+        windowStartMs = deps.now();
+        await post(api, "Profiler.start");
+    };
+    const tick = async () => {
+        const api = session;
+        if (!api || watchdog === null) return;
+        const now = deps.now();
+        const startMs = lastTickAt;
+        lastTickAt = now;
+        const stall = now - startMs - WATCHDOG_INTERVAL_MS >= options.thresholdMs;
+        if (!stall && now - windowStartMs < PROFILE_WINDOW_MS) return;
+        try {
+            const { profile } = await post(api, "Profiler.stop");
+            const profileStartMs = windowStartMs;
+            // Restart sampling before converting/writing the captured profile.
+            // This watchdog both detects stalls and replaces expired profiles;
+            // checking for a stall first prevents a late replacement from
+            // discarding the window that contains the block.
+            if (session !== api || stopped) return;
+            await startWindow(api);
+            const after = snapshot();
+            if (stall && profile) {
+                const traces = v8ProfileTraces(profile, profileStartMs);
+                const slackMs = 2 * options.sampleIntervalMs + 20;
+                const windowed = traces.filter((trace) => {
+                    const at = (trace.timestamp ?? 0) * 1000;
+                    return at >= startMs - slackMs && at <= now + slackMs;
+                });
+                try {
+                    emitStallReport(deps, {
+                        startMs,
+                        endMs: now,
+                        traces,
+                        windowed,
+                        windowFilter: "timestamp",
+                        options,
+                        before: memoryBefore,
+                        after,
+                        backend: "v8",
+                    });
+                } catch (error) {
+                    fail("could not write a stall report", error);
+                }
+            }
+            memoryBefore = after;
+        } catch (error) {
+            fail("watchdog tick failed", error);
+            await disable("sampling failed");
+        }
+    };
+    // Queue file checks and watchdog work so their awaited stop/start pairs run one at a time.
+    const enqueue = (fn: () => Promise<void>) => {
+        work = work.then(fn).catch((error) => fail("profiler operation failed", error));
+        return work;
+    };
+    const runCheck = async () => {
+        if (stopped || unavailable) return;
+        const enablePath = path.join(deps.profilerDir(), HOST_PROFILER_ENABLE_FILENAME);
+        if (!existsSync(enablePath)) {
+            await disable("enable file removed");
+            return;
+        }
+        const parsed = parseEnableFile(readFileSync(enablePath, "utf8"));
+        if (parsed.error) fail("enable options", parsed.error);
+        if (session && parsed.options.sampleIntervalMs === options.sampleIntervalMs) {
+            options = parsed.options;
+            return;
+        }
+        if (session) await disable("sample interval changed");
+        options = parsed.options;
+        try {
+            const api = await deps.createSession();
+            if (stopped || !existsSync(enablePath)) return;
+            session = api;
+            api.connect();
+            await post(api, "Profiler.enable");
+            await post(api, "Profiler.setSamplingInterval", {
+                interval: Math.round(options.sampleIntervalMs * 1000),
+            });
+            await startWindow(api);
+            if (stopped || !existsSync(enablePath)) {
+                await disable("enable file removed");
+                return;
+            }
+            lastTickAt = deps.now();
+            memoryBefore = snapshot();
+            watchdog = deps.setInterval(() => {
+                void enqueue(tick);
+            }, WATCHDOG_INTERVAL_MS);
+            safeLog(
+                `[magic-context] host stall profiler enabled: threshold ${options.thresholdMs}ms, sample interval ${options.sampleIntervalMs}ms, backend v8, rotation ${PROFILE_WINDOW_MS}ms, reports in ${deps.profilerDir()}`,
+            );
+        } catch (error) {
+            fail("could not start inspector profiler", error);
+            await disable("inspector unavailable");
+            unavailable = true;
+            if (pollTimer !== null) deps.clearInterval(pollTimer);
+            pollTimer = null;
+        }
+    };
+    return {
+        start() {
+            if (pollTimer !== null || unavailable) return;
+            stopped = false;
+            pollTimer = deps.setInterval(() => {
+                void enqueue(runCheck);
+            }, SWITCH_POLL_MS);
+            void enqueue(runCheck);
+        },
+        checkNow: () => enqueue(runCheck),
+        stop() {
+            stopped = true;
+            if (pollTimer !== null) deps.clearInterval(pollTimer);
+            pollTimer = null;
+            if (watchdog !== null) deps.clearInterval(watchdog);
+            watchdog = null;
+            void enqueue(() => disable("stopped"));
+        },
+        isActive: () => watchdog !== null,
+        isUnavailable: () => unavailable,
+    };
+}