memorydetective 1.12.0 → 1.14.0

package/dist/tools/recordTimeProfile.js

@@ -1,8 +1,10 @@
 import { z } from "zod";
 import { existsSync, mkdirSync } from "node:fs";
+import { spawn } from "node:child_process";
 import { resolve as resolvePath, dirname, isAbsolute as isAbsolutePath, join as joinPath, } from "node:path";
 import { runCommand } from "../runtime/exec.js";
 import { getSecurityFlags, maxRecordingExceededMessage, } from "../runtime/securityFlags.js";
+import { getPlatformAdvisory } from "../runtime/platformCheck.js";
 /**
  * Base shape, exposed so the MCP layer can read `.shape` (ZodEffects from
  * `.superRefine()` doesn't expose shape).
@@ -91,6 +93,115 @@ const XCTRACE_TIMEOUT_GRACE_SEC = 30;
  * when xctrace is wedged.
  */
 const XCTRACE_GRACEFUL_KILL_MS = 10_000;
+const PREFLIGHT_TIME_LIMIT_SEC = 2;
+const PREFLIGHT_WRAPPER_TIMEOUT_MS = (PREFLIGHT_TIME_LIMIT_SEC + 6) * 1000;
+const PREFLIGHT_GRACEFUL_KILL_MS = 2000;
+/**
+ * Returns true when a pre-flight probe should run before the user's
+ * actual recording. v1.14 item H.
+ *
+ * - `MEMORYDETECTIVE_PREFLIGHT_XCTRACE=1` forces preflight on.
+ * - `MEMORYDETECTIVE_PREFLIGHT_XCTRACE=0` forces it off.
+ * - Default: auto-enabled when host is macOS 26.x AND target is a
+ *   simulator AND attach mode (`--attach`, not `--launch`). The set of
+ *   configurations where the regression is known to fire.
+ *
+ * The `osPlatform` and `osRelease` params are threaded through to
+ * `getPlatformAdvisory` so tests can simulate non-macOS-26 hosts even
+ * when running on a real macOS 26.x machine.
+ */
+export function shouldPreflightXctrace(input, env = process.env, osPlatform, osRelease) {
+    const explicit = env.MEMORYDETECTIVE_PREFLIGHT_XCTRACE;
+    if (explicit === "1")
+        return true;
+    if (explicit === "0")
+        return false;
+    // Auto: only when the known-broken combination applies.
+    const onMacOS26 = getPlatformAdvisory(env, osPlatform, osRelease) != null;
+    const isSimTarget = !!input.simulatorId && !input.deviceId;
+    const isAttachMode = !input.launchBundleId;
+    return onMacOS26 && isSimTarget && isAttachMode;
+}
+/**
+ * Runs the 2-second probe. Reuses runCommand's timeout wrapper with the
+ * same SIGINT-first / SIGKILL-fallback shape that the full recording
+ * uses, so the probe's salvage behavior matches the real path.
+ *
+ * The output bundle is placed at `<output>.preflight` to keep it
+ * recognizable in cleanup tools and not collide with the user's actual
+ * output path.
+ */
+export async function preflightXctraceRecord(input, resolvedOutput) {
+    const probeOutput = `${resolvedOutput}.preflight`;
+    const probeInput = {
+        ...input,
+        durationSec: PREFLIGHT_TIME_LIMIT_SEC,
+        output: probeOutput,
+    };
+    const args = buildXctraceArgs(probeInput);
+    const probeOutDir = dirname(probeOutput);
+    if (!existsSync(probeOutDir)) {
+        mkdirSync(probeOutDir, { recursive: true });
+    }
+    const start = Date.now();
+    const result = await runCommand("xcrun", args, {
+        timeoutMs: PREFLIGHT_WRAPPER_TIMEOUT_MS,
+        timeoutSignal: "SIGINT",
+        gracefulKillAfterMs: PREFLIGHT_GRACEFUL_KILL_MS,
+    });
+    const durationMs = Date.now() - start;
+    if (result.timedOut) {
+        return {
+            healthy: false,
+            reason: `Pre-flight probe wedged: 2s recording exceeded ${PREFLIGHT_WRAPPER_TIMEOUT_MS / 1000}s wrapper window without exiting. The same wedge will hit the full recording.`,
+            durationMs,
+        };
+    }
+    if (result.code !== 0) {
+        return {
+            healthy: false,
+            reason: `Pre-flight probe exited non-zero (code ${result.code}): ${(result.stderr || result.stdout || "").slice(0, 200)}`,
+            durationMs,
+        };
+    }
+    return { healthy: true, durationMs };
+}
+/**
+ * v1.14 item J. When a `recordTimeProfile` call times out, optionally
+ * launch the partial `.trace` in Instruments.app so the user has a GUI
+ * escape hatch. Returns `true` when `open -a Instruments <tracePath>`
+ * was spawned, `false` otherwise.
+ *
+ * Gated on `MEMORYDETECTIVE_AUTO_OPEN_INSTRUMENTS=1` to avoid spamming
+ * the user's GUI on unattended runs and CI. Also requires the trace
+ * bundle to exist on disk (xctrace's SIGINT path may have failed to
+ * write anything).
+ *
+ * The `open` invocation is fire-and-forget: `detached: true` + `unref()`
+ * so the recording tool returns immediately. Failures to launch
+ * Instruments.app are swallowed; the user is no worse off than without
+ * the flag enabled.
+ *
+ * Exported so the env-gating logic can be tested without spawning
+ * Instruments in test runs.
+ */
+export function maybeOpenInInstruments(tracePath) {
+    if (process.env.MEMORYDETECTIVE_AUTO_OPEN_INSTRUMENTS !== "1")
+        return false;
+    if (!existsSync(tracePath))
+        return false;
+    try {
+        const child = spawn("open", ["-a", "Instruments", tracePath], {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Pure: build the xctrace argv for the given input. Exposed for testing. */
 export function buildXctraceArgs(input) {
     const args = ["xctrace", "record", "--template", input.template];
@@ -132,6 +243,28 @@ export async function recordTimeProfile(input) {
         // parent.
         mkdirSync(outDir, { recursive: true });
     }
+    // v1.14 item H. Pre-flight the xctrace `--time-limit` ignore regression
+    // before spending the user's durationSec on a wedge. Gated to macOS 26.x
+    // simulator targets in attach mode by default; opt-in / opt-out via
+    // MEMORYDETECTIVE_PREFLIGHT_XCTRACE.
+    if (shouldPreflightXctrace({ ...input, output })) {
+        const probe = await preflightXctraceRecord({ ...input, output }, output);
+        if (!probe.healthy) {
+            return {
+                ok: false,
+                command: `xcrun ${buildXctraceArgs({ ...input, output }).join(" ")}`,
+                output,
+                durationSec: input.durationSec,
+                template: input.template,
+                recordingTimedOut: true,
+                workaroundNotice: {
+                    issue: "xctrace-time-limit-ignored",
+                    message: `Pre-flight probe detected the xctrace wedge in ${probe.durationMs}ms. Skipping the full ${input.durationSec}s recording so you do not pay the wrapper timeout. ${probe.reason ?? ""}`,
+                    fallbacks: XCTRACE_TIMEOUT_FALLBACKS,
+                },
+            };
+        }
+    }
     const args = buildXctraceArgs({ ...input, output });
     // External timeout wrapper. xctrace itself receives `--time-limit Ns`, so
     // the normal exit path is xctrace finishing on its own at N seconds. The
@@ -147,6 +280,7 @@ export async function recordTimeProfile(input) {
         gracefulKillAfterMs: XCTRACE_GRACEFUL_KILL_MS,
     });
     if (result.timedOut) {
+        const openedInInstrumentsApp = maybeOpenInInstruments(output);
         return {
             ok: false,
             command: `xcrun ${args.join(" ")}`,
@@ -160,6 +294,7 @@ export async function recordTimeProfile(input) {
                 message: XCTRACE_TIMEOUT_MESSAGE,
                 fallbacks: XCTRACE_TIMEOUT_FALLBACKS,
             },
+            openedInInstrumentsApp,
         };
     }
     if (result.code !== 0) {

package/dist/tools/recordTimeProfile.js.map

@@ -1 +1 @@
-{"version":3,"file":"recordTimeProfile.js","sourceRoot":"","sources":["../../src/tools/recordTimeProfile.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"recordTimeProfile.js","sourceRoot":"","sources":["../../src/tools/recordTimeProfile.ts"],"names":[],"mappings":"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"}

package/dist/tools/replayScenario.d.ts

@@ -33,9 +33,9 @@ declare const actionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     durationMs: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     type: "swipe";
+    durationMs: number;
     from: [number, number];
     to: [number, number];
-    durationMs: number;
 }, {
     type: "swipe";
     from: [number, number];
@@ -85,9 +85,9 @@ export declare const replayScenarioShape: {
         durationMs: z.ZodDefault<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         type: "swipe";
+        durationMs: number;
         from: [number, number];
         to: [number, number];
-        durationMs: number;
     }, {
         type: "swipe";
         from: [number, number];
@@ -140,9 +140,9 @@ export declare const replayScenarioSchema: z.ZodObject<{
         durationMs: z.ZodDefault<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         type: "swipe";
+        durationMs: number;
         from: [number, number];
         to: [number, number];
-        durationMs: number;
     }, {
         type: "swipe";
         from: [number, number];
@@ -180,9 +180,9 @@ export declare const replayScenarioSchema: z.ZodObject<{
         coords?: [number, number] | undefined;
     } | {
         type: "swipe";
+        durationMs: number;
         from: [number, number];
         to: [number, number];
-        durationMs: number;
     } | {
         type: "wait";
         seconds: number;

package/dist/tools/summarizeTrace.d.ts

@@ -0,0 +1,147 @@
+/**
+ * `summarizeTrace`: the trace-to-summary-card-in-one-call feature.
+ *
+ * Today an agent handed a `.trace` chains inspectTrace + up to 5
+ * analyzers + reasons over tens of KB of JSON. That's 6 round-trips
+ * and ~$0.10-0.20 in tokens, most of which get thrown away after the
+ * agent identifies the one user-visible finding.
+ *
+ * summarizeTrace does it all in one call:
+ *
+ *  1. Inspects the TOC via inspectTrace (reuses the v1.11 path).
+ *  2. For each populated known schema, runs the matching analyzer in
+ *     parallel with smart defaults tuned for "what would a user care
+ *     about?" (Apple's 100ms hitch threshold, top-10 hangs, top-15
+ *     time-profile symbols, etc).
+ *  3. Cross-correlates findings (v1.13 Phase 2): hangs overlapping
+ *     with hitches, allocation spikes preceding hangs, etc.
+ *  4. Produces a structured result PLUS a pre-rendered compact
+ *     markdown card (< 10 KB target) suitable for direct presentation
+ *     to the user without further reasoning.
+ *
+ * Strategic positioning: this is memorydetective's "synthesis over
+ * raw-query" play vs trace-MCPs that go deep on single-schema access.
+ * See `~/Desktop/internal/v1.9-notelet-retro-market.md` §4.5 for the
+ * full framing.
+ */
+import { z } from "zod";
+import { type InspectTraceResult } from "./inspectTrace.js";
+import { type AnalyzeHangsResult } from "./analyzeHangs.js";
+import { type AnalyzeAnimationHitchesResult } from "./analyzeAnimationHitches.js";
+import { type AnalyzeTimeProfileResult } from "./analyzeTimeProfile.js";
+import { type AnalyzeAllocationsResult } from "./analyzeAllocations.js";
+import { type AnalyzeAppLaunchResult } from "./analyzeAppLaunch.js";
+export declare const summarizeTraceSchema: z.ZodObject<{
+    tracePath: z.ZodString;
+    focus: z.ZodDefault<z.ZodEnum<["hangs", "hitches", "allocations", "launch", "all"]>>;
+    verbose: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    tracePath: string;
+    focus: "allocations" | "all" | "hangs" | "hitches" | "launch";
+    verbose: boolean;
+}, {
+    tracePath: string;
+    focus?: "allocations" | "all" | "hangs" | "hitches" | "launch" | undefined;
+    verbose?: boolean | undefined;
+}>;
+export type SummarizeTraceInput = z.infer<typeof summarizeTraceSchema>;
+/**
+ * Per-analyzer entry on the structured result. `status` distinguishes
+ * "ran successfully", "schema absent in trace", and "ran but failed".
+ * Callers branching on the summary can decide whether to retry / refine.
+ */
+export interface SummarizeAreaSummary<TResult> {
+    status: "ok" | "schema-absent" | "failed";
+    /** Why the status is what it is (one sentence). Surfaces SIGSEGV / missing-schema / parser-error reasons. */
+    diagnosis: string;
+    /** Full analyzer result when status === "ok". Useful when a caller wants to drill in without re-running the analyzer. */
+    result?: TResult;
+}
+/**
+ * v1.13 Phase 2: cross-area correlation. Each entry is a finding
+ * tying TWO areas together via timestamp overlap. The narrative
+ * field is the human-scannable string that goes into the markdown
+ * card; the structured fields (`kind`, `confidence`, evidence ids)
+ * are what callers can branch on programmatically.
+ */
+export interface Correlation {
+    /** Which two areas this correlation ties together. Currently only `hangs+hitches` is supported; `hangs+allocations` and `hitches+allocations` are deferred to v1.14+ because the analyzer doesn't currently expose per-timestamp allocation rows. */
+    kind: "hangs+hitches";
+    /** `high` when the overlap is substantial (both events > 100ms and the windows overlap significantly); `medium` when one event is short; `low` when timestamps are only adjacent. */
+    confidence: "high" | "medium" | "low";
+    /** Pre-formatted human-scannable narrative. Goes into the markdown card. */
+    narrative: string;
+    /** Start time in seconds (for the hang event). Used to rank correlations by user-relevance (earliest first). */
+    atSec: number;
+}
+export interface SummarizeTraceResult {
+    ok: boolean;
+    tracePath: string;
+    /** TOC + suggestedNextCalls from inspectTrace. Always present. */
+    inspection: InspectTraceResult;
+    /** Per-area summaries. Each section is independent; absence of one doesn't fail the call. */
+    areas: {
+        hangs: SummarizeAreaSummary<AnalyzeHangsResult>;
+        hitches: SummarizeAreaSummary<AnalyzeAnimationHitchesResult>;
+        timeProfile: SummarizeAreaSummary<AnalyzeTimeProfileResult>;
+        allocations: SummarizeAreaSummary<AnalyzeAllocationsResult>;
+        appLaunch: SummarizeAreaSummary<AnalyzeAppLaunchResult>;
+    };
+    /** Cross-area correlations (v1.13 Phase 2). Empty when areas don't have enough data to correlate. */
+    correlations: Correlation[];
+    /** Headline string: 1-2 sentences naming the biggest user-impact finding across all areas. */
+    headline: string;
+    /** Pre-rendered markdown summary card. Target < 10 KB at default `verbose: false`. */
+    markdown: string;
+}
+/**
+ * Pure: detect hangs whose window overlaps with animation hitches.
+ * When a user sees a hang AND a hitch in the same time window,
+ * they almost certainly perceived the impact (the main-thread block
+ * delayed render commits, dropping frames).
+ *
+ * The overlap check is symmetric: a hitch can fall within a hang's
+ * window OR a hang can fall within a hitch's window. Both directions
+ * are treated equally.
+ *
+ * Confidence:
+ *
+ * - `high`: both events >= 250ms AND the overlap span >= 100ms.
+ * - `medium`: at least one event >= 250ms.
+ * - `low`: neither event >= 250ms but the windows touch.
+ *
+ * Results are sorted by `atSec` ascending so the markdown card lists
+ * correlations in trace order.
+ */
+export declare function correlateHangsAndHitches(hangs: Array<{
+    startNs: number;
+    durationNs: number;
+    durationMs: number;
+}>, hitches: Array<{
+    startNs: number;
+    durationNs: number;
+    durationMs: number;
+    hitchType?: string;
+}>): Correlation[];
+/**
+ * Pure: build all cross-area correlations from per-area summaries.
+ * Currently only `hangs+hitches` produces entries; allocation-based
+ * correlations need per-timestamp allocation data the existing
+ * analyzeAllocations doesn't expose (v1.14+ candidate).
+ */
+export declare function buildCorrelations(areas: SummarizeTraceResult["areas"]): Correlation[];
+/**
+ * Pure: produce the one-or-two-sentence headline that goes at the top
+ * of the markdown card. Picks the most user-visible finding across
+ * all areas. Order of priority: longest hang above 250ms > worst
+ * launch phase > worst hitch > largest allocation spike.
+ */
+export declare function buildHeadline(areas: SummarizeTraceResult["areas"]): string;
+/**
+ * Pure: assemble the compact markdown summary card. Designed to be
+ * <10 KB at default settings. The structured `areas` field carries
+ * the full data for callers who need it; this is the human view.
+ */
+export declare function buildMarkdownCard(result: Omit<SummarizeTraceResult, "markdown">, verbose: boolean): string;
+export declare function summarizeTrace(input: SummarizeTraceInput): Promise<SummarizeTraceResult>;
+export declare const SUMMARIZE_AREA_KEYS: readonly ["hangs", "hitches", "timeProfile", "allocations", "appLaunch"];