memorydetective 1.2.0 → 1.3.0

package/dist/tools/getInvestigationPlaybook.js

@@ -0,0 +1,220 @@
+import { z } from "zod";
+/**
+ * Meta-tool: returns the canonical investigation sequence for a known
+ * problem class. Lets a fresh LLM agent jump straight to the right pipeline
+ * without rediscovering the order from tool descriptions.
+ *
+ * Each playbook is a versioned, declarative sequence of tool calls with a
+ * stable `step` number, a `purpose` line, and `argsTemplate` showing which
+ * args matter most. The agent fills in concrete values from the user's
+ * context (file paths, class names, etc.).
+ */
+export const PlaybookKindEnum = z.enum([
+    "memgraph-leak",
+    "perf-hangs",
+    "ui-jank",
+    "app-launch-slow",
+    "verify-fix",
+]);
+export const getInvestigationPlaybookSchema = z.object({
+    kind: PlaybookKindEnum.describe("Which investigation flow to return. `memgraph-leak` is the most common — diagnose a SwiftUI/Combine retain cycle from a `.memgraph` and locate it in source."),
+});
+const PLAYBOOKS = {
+    "memgraph-leak": {
+        kind: "memgraph-leak",
+        summary: "Diagnose a SwiftUI / Combine retain cycle from a `.memgraph` snapshot, locate the offending code, and propose a fix.",
+        steps: [
+            {
+                step: 1,
+                tool: "analyzeMemgraph",
+                purpose: "Run leaks(1) and get totals + top-level ROOT CYCLE summaries with class chains in compact form.",
+                argsTemplate: { path: "<absolute path to the .memgraph>" },
+                resultGuidance: "Note the count of ROOT CYCLEs and the dominant class chain. The response includes `suggestedNextCalls` — follow them.",
+            },
+            {
+                step: 2,
+                tool: "classifyCycle",
+                purpose: "Match each ROOT CYCLE against the built-in catalog of known antipatterns. Returns a fix hint and pre-populated `suggestedNextCalls` for source-code lookup.",
+                argsTemplate: { path: "<same path as step 1>" },
+                resultGuidance: "If `primaryMatch` is `null`, the cycle is novel — use `findRetainers` to walk the chain manually instead.",
+            },
+            {
+                step: 3,
+                tool: "reachableFromCycle",
+                purpose: "Confirm which app-level class is the actual culprit (cycle root) versus collateral retained instances.",
+                argsTemplate: {
+                    path: "<same path>",
+                    rootClassName: "<class from step 2's primaryMatch>",
+                },
+                resultGuidance: "If a single app-level class dominates `counts`, that's the leak. If many compete, the cycle may be deeper than a single owner.",
+            },
+            {
+                step: 4,
+                tool: "swiftSearchPattern",
+                purpose: "Locate the code construct the classifier flagged (e.g. `.tag(`, `.sink {`, `Task {`).",
+                argsTemplate: {
+                    filePath: "<a candidate Swift file in the project>",
+                    pattern: "<from step 2's suggestedNextCalls>",
+                },
+            },
+            {
+                step: 5,
+                tool: "swiftGetSymbolDefinition",
+                purpose: "Jump to the declaration of the cycle's app-level class.",
+                argsTemplate: {
+                    symbolName: "<class from step 3>",
+                    candidatePaths: ["<Sources/, app target dirs>"],
+                },
+            },
+            {
+                step: 6,
+                tool: "swiftFindSymbolReferences",
+                purpose: "List every callsite — useful to compare capture-list patterns across them and detect inconsistencies.",
+                argsTemplate: {
+                    symbolName: "<class from step 3>",
+                    filePath: "<from step 5 result>",
+                },
+            },
+        ],
+        seeAlso: ["verify-fix"],
+    },
+    "perf-hangs": {
+        kind: "perf-hangs",
+        summary: "Diagnose user-visible main-thread hangs from a `.trace` recorded with the Time Profiler or Hangs template.",
+        steps: [
+            {
+                step: 1,
+                tool: "listTraceDevices",
+                purpose: "Find the simulator or device UDID to attach to.",
+                argsTemplate: {},
+            },
+            {
+                step: 2,
+                tool: "recordTimeProfile",
+                purpose: "Capture a fresh `.trace` while reproducing the slow path.",
+                argsTemplate: {
+                    template: "Time Profiler",
+                    deviceId: "<from step 1>",
+                    attachAppName: "<your app name>",
+                    durationSec: 90,
+                    output: "<absolute path ending in .trace>",
+                },
+            },
+            {
+                step: 3,
+                tool: "analyzeHangs",
+                purpose: "Parse the `potential-hangs` schema; report Hang vs Microhang counts plus the top N longest.",
+                argsTemplate: {
+                    tracePath: "<from step 2>",
+                    minDurationMs: 250,
+                },
+            },
+            {
+                step: 4,
+                tool: "swiftSearchPattern",
+                purpose: "If hangs are dominated by a specific call site (visible in `top` entries), grep for likely main-thread offenders: `Task { ... }` blocks without `[weak self]`, synchronous I/O on the main queue, etc.",
+                argsTemplate: {
+                    filePath: "<candidate file>",
+                    pattern: "DispatchQueue\\.main\\.sync|Task\\s*\\{",
+                },
+            },
+        ],
+        seeAlso: ["ui-jank", "app-launch-slow"],
+    },
+    "ui-jank": {
+        kind: "ui-jank",
+        summary: "Diagnose dropped frames / animation hitches from a `.trace` recorded with the Animation Hitches template.",
+        steps: [
+            {
+                step: 1,
+                tool: "recordTimeProfile",
+                purpose: "Capture a `.trace` with the Animation Hitches template active.",
+                argsTemplate: {
+                    template: "Animation Hitches",
+                    deviceId: "<UDID>",
+                    attachAppName: "<app>",
+                    durationSec: 60,
+                    output: "<.trace path>",
+                },
+            },
+            {
+                step: 2,
+                tool: "analyzeAnimationHitches",
+                purpose: "Parse the `animation-hitches` schema; report by-type counts and the count of user-perceptible hitches (>100ms).",
+                argsTemplate: { tracePath: "<from step 1>", minDurationMs: 100 },
+            },
+            {
+                step: 3,
+                tool: "swiftFindSymbolReferences",
+                purpose: "Once a suspected `View` is identified, find callsites to scope which screens render with this view.",
+                argsTemplate: { symbolName: "<View name>", filePath: "<source>" },
+            },
+        ],
+    },
+    "app-launch-slow": {
+        kind: "app-launch-slow",
+        summary: "Diagnose cold/warm launch slowness from a `.trace` recorded with the App Launch template.",
+        steps: [
+            {
+                step: 1,
+                tool: "recordTimeProfile",
+                purpose: "Capture a launch trace.",
+                argsTemplate: {
+                    template: "App Launch",
+                    deviceId: "<UDID>",
+                    launchBundleId: "<com.example.app>",
+                    durationSec: 30,
+                    output: "<.trace path>",
+                },
+            },
+            {
+                step: 2,
+                tool: "analyzeAppLaunch",
+                purpose: "Get cold/warm classification + per-phase breakdown (process-creation, dyld, ObjC init, AppDelegate, first-frame).",
+                argsTemplate: { tracePath: "<from step 1>" },
+            },
+            {
+                step: 3,
+                tool: "swiftSearchPattern",
+                purpose: "If `appdelegate-init` dominates, grep for synchronous work in `application(_:didFinishLaunchingWithOptions:)`.",
+                argsTemplate: {
+                    filePath: "<AppDelegate.swift>",
+                    pattern: "didFinishLaunchingWithOptions",
+                },
+            },
+        ],
+    },
+    "verify-fix": {
+        kind: "verify-fix",
+        summary: "Confirm a fix actually closed a known cycle by diffing a before/after pair of `.memgraph` snapshots.",
+        steps: [
+            {
+                step: 1,
+                tool: "diffMemgraphs",
+                purpose: "Compare totals + class-count deltas + cycle signatures across before/after snapshots.",
+                argsTemplate: {
+                    before: "<path to before.memgraph>",
+                    after: "<path to after.memgraph>",
+                },
+                resultGuidance: "Look for the originally-classified cycle in `cycles.goneFromBefore`. If still in `cycles.persisted`, the fix didn't address the right capture.",
+            },
+            {
+                step: 2,
+                tool: "classifyCycle",
+                purpose: "Re-classify the after snapshot to confirm no new patterns appeared.",
+                argsTemplate: { path: "<path to after.memgraph>" },
+            },
+        ],
+        seeAlso: ["memgraph-leak"],
+    },
+};
+export async function getInvestigationPlaybook(input) {
+    const playbook = PLAYBOOKS[input.kind];
+    if (!playbook) {
+        throw new Error(`Unknown playbook kind: ${input.kind}. Known: ${Object.keys(PLAYBOOKS).join(", ")}`);
+    }
+    return { ok: true, playbook };
+}
+/** Exposed for tests. */
+export const PLAYBOOK_KINDS = Object.keys(PLAYBOOKS);
+//# sourceMappingURL=getInvestigationPlaybook.js.map

package/dist/tools/getInvestigationPlaybook.js.map

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

package/dist/tools/reachableFromCycle.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { LeaksReport } from "../types.js";
+import type { LeaksReport, NextCallSuggestion } from "../types.js";
 /**
  * Cycle-scoped reachability + class counting.
  *
@@ -30,9 +30,9 @@ export declare const reachableFromCycleSchema: z.ZodObject<{
 }, {
     path: string;
     className?: string | undefined;
+    cycleIndex?: number | undefined;
     verbosity?: "compact" | "normal" | "full" | undefined;
     topN?: number | undefined;
-    cycleIndex?: number | undefined;
     rootClassName?: string | undefined;
 }>;
 export type ReachableFromCycleInput = z.infer<typeof reachableFromCycleSchema>;
@@ -55,6 +55,8 @@ export interface ReachableFromCycleResult {
     counts: ClassCount[];
     /** Total unique classes in the cycle's reachable set. */
     uniqueClasses: number;
+    /** Pipeline hint — locate the cycle root in source code. */
+    suggestedNextCalls?: NextCallSuggestion[];
 }
 /** Pure: compute the result from a parsed report. Exposed for testing. */
 export declare function reachableFromReport(report: LeaksReport, path: string, input: ReachableFromCycleInput): ReachableFromCycleResult;

package/dist/tools/reachableFromCycle.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { runLeaksAndParse } from "../runtime/leaks.js";
 import { rootCyclesOnly } from "../parsers/leaksOutput.js";
 import { shortenForVerbosity, } from "../parsers/shortenClassName.js";
+import { pickPrimaryAppClass, suggestionFindReferences, suggestionGetDefinition, } from "../runtime/suggestions.js";
 /**
  * Cycle-scoped reachability + class counting.
  *
@@ -93,17 +94,29 @@ export function reachableFromReport(report, path, input) {
     }
     entries.sort((a, b) => b.count - a.count);
     entries = entries.slice(0, input.topN ?? 20);
+    // Find a class that looks "app-level" (not stdlib / SwiftUI internal) to
+    // suggest as the followup target. The cycle root is the canonical answer
+    // when it itself is app-level; otherwise we walk the counts.
+    const suggestedNextCalls = [];
+    const rootShort = shortenForVerbosity(picked.node.className, verbosity);
+    const candidate = pickPrimaryAppClass([rootShort]) ??
+        pickPrimaryAppClass(entries.map((e) => e.className));
+    if (candidate) {
+        suggestedNextCalls.push(suggestionGetDefinition({ symbolName: candidate }));
+        suggestedNextCalls.push(suggestionFindReferences({ symbolName: candidate }));
+    }
     return {
         ok: true,
         path,
         cycle: {
             index: picked.index,
-            rootClass: shortenForVerbosity(picked.node.className, verbosity),
+            rootClass: rootShort,
             rootAddress: picked.node.address,
             totalReachable: total,
         },
         counts: entries,
         uniqueClasses: byClass.size,
+        ...(suggestedNextCalls.length > 0 ? { suggestedNextCalls } : {}),
     };
 }
 export async function reachableFromCycle(input) {

package/dist/tools/reachableFromCycle.js.map

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

package/dist/tools/swift/findSymbolReferences.d.ts

@@ -6,13 +6,13 @@ export declare const swiftFindSymbolReferencesSchema: z.ZodObject<{
     projectRoot: z.ZodOptional<z.ZodString>;
     includeDeclaration: z.ZodDefault<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
-    symbolName: string;
     filePath: string;
+    symbolName: string;
     includeDeclaration: boolean;
     projectRoot?: string | undefined;
 }, {
-    symbolName: string;
     filePath: string;
+    symbolName: string;
     projectRoot?: string | undefined;
     includeDeclaration?: boolean | undefined;
 }>;

package/dist/tools/swift/getHoverInfo.d.ts

@@ -5,14 +5,14 @@ export declare const swiftGetHoverInfoSchema: z.ZodObject<{
     character: z.ZodNumber;
     projectRoot: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
+    filePath: string;
     line: number;
     character: number;
-    filePath: string;
     projectRoot?: string | undefined;
 }, {
+    filePath: string;
     line: number;
     character: number;
-    filePath: string;
     projectRoot?: string | undefined;
 }>;
 export type SwiftGetHoverInfoInput = z.infer<typeof swiftGetHoverInfoSchema>;

package/dist/tools/swift/getSymbolDefinition.d.ts

@@ -6,30 +6,30 @@ export declare const swiftGetSymbolDefinitionSchema: z.ZodObject<{
         filePath: z.ZodOptional<z.ZodString>;
         module: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        module?: string | undefined;
         filePath?: string | undefined;
-    }, {
         module?: string | undefined;
+    }, {
         filePath?: string | undefined;
+        module?: string | undefined;
     }>>;
     projectRoot: z.ZodOptional<z.ZodString>;
     candidatePaths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     symbolName: string;
+    candidatePaths?: string[] | undefined;
     hint?: {
-        module?: string | undefined;
         filePath?: string | undefined;
+        module?: string | undefined;
     } | undefined;
     projectRoot?: string | undefined;
-    candidatePaths?: string[] | undefined;
 }, {
     symbolName: string;
+    candidatePaths?: string[] | undefined;
     hint?: {
-        module?: string | undefined;
         filePath?: string | undefined;
+        module?: string | undefined;
     } | undefined;
     projectRoot?: string | undefined;
-    candidatePaths?: string[] | undefined;
 }>;
 export type SwiftGetSymbolDefinitionInput = z.infer<typeof swiftGetSymbolDefinitionSchema>;
 export interface SwiftGetSymbolDefinitionResult {

package/dist/tools/swift/searchPattern.d.ts

@@ -11,13 +11,13 @@ export declare const swiftSearchPatternSchema: z.ZodObject<{
     flags: z.ZodOptional<z.ZodString>;
     maxMatches: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    filePath: string;
     pattern: string;
+    filePath: string;
     maxMatches: number;
     flags?: string | undefined;
 }, {
-    filePath: string;
     pattern: string;
+    filePath: string;
     flags?: string | undefined;
     maxMatches?: number | undefined;
 }>;

package/dist/types.d.ts

@@ -52,3 +52,17 @@ export interface LeaksReport {
     /** True if the report contains zero ROOT CYCLE entries (independent of leakCount, since plain leaks may exist). */
     hasNoCycles: boolean;
 }
+/**
+ * HATEOAS-style hint that an LLM agent can chain after the current tool's
+ * result. We pre-populate `args` from the current response so the agent can
+ * call the next tool with one fewer inference step. The agent is free to
+ * adapt or ignore — these are suggestions, not commands.
+ */
+export interface NextCallSuggestion {
+    /** Name of the tool to call next. */
+    tool: string;
+    /** Pre-populated arguments based on the current result. */
+    args: Record<string, unknown>;
+    /** One-sentence rationale: why this next call advances the investigation. */
+    why: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorydetective",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "MCP server for iOS leak hunting and performance investigation. Reads .memgraph + .trace files, captures new ones via xctrace and leaks(1), classifies retain cycles.",
   "type": "module",
   "bin": {