@duckmind/dm-darwin-x64 0.66.5 → 0.66.6

package/extensions/dm-lens/dist/tools/lsp-structured-output.js

@@ -0,0 +1,277 @@
+import { fileURLToPath, pathToFileURL } from "node:url";
+function asRecord(value) {
+  return typeof value === "object" && value !== null ? value : undefined;
+}
+function finiteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function lspStatusFromFailureKind(failureKind) {
+  if (failureKind === "success" || failureKind === "fallback_success") {
+    return "success";
+  }
+  if (failureKind === "empty_result")
+    return "empty";
+  if (failureKind === "unsupported")
+    return "unsupported";
+  if (failureKind === "bad_input" || failureKind === "invalid_operation" || failureKind === "missing_file_path") {
+    return "bad_input";
+  }
+  if (failureKind === "no_server")
+    return "no_server";
+  if (failureKind === "lsp_disabled")
+    return "lsp_disabled";
+  if (failureKind === "filepath_is_directory")
+    return "filepath_is_directory";
+  if (failureKind === "tracked_snapshot")
+    return "tracked_snapshot";
+  return "error";
+}
+function lspToolLocationFromUriRange(uri, range) {
+  if (typeof uri !== "string" || !uri.startsWith("file:"))
+    return;
+  const rangeLike = asRecord(range);
+  const startLine = finiteNumber(rangeLike?.start?.line);
+  const startCharacter = finiteNumber(rangeLike?.start?.character);
+  const endLine = finiteNumber(rangeLike?.end?.line);
+  const endCharacter = finiteNumber(rangeLike?.end?.character);
+  if (startLine === undefined || startCharacter === undefined || endLine === undefined || endCharacter === undefined) {
+    return;
+  }
+  try {
+    return {
+      uri,
+      filePath: fileURLToPath(uri),
+      range: {
+        start: {
+          line: Math.floor(startLine) + 1,
+          character: Math.floor(startCharacter) + 1
+        },
+        end: {
+          line: Math.floor(endLine) + 1,
+          character: Math.floor(endCharacter) + 1
+        }
+      }
+    };
+  } catch {
+    return;
+  }
+}
+function lspToolLocationFromFileRange(filePath, range) {
+  if (!filePath || filePath === "(workspace)")
+    return;
+  const rangeLike = asRecord(range);
+  const startLine = finiteNumber(rangeLike?.start?.line);
+  const startCharacter = finiteNumber(rangeLike?.start?.character);
+  const endLine = finiteNumber(rangeLike?.end?.line);
+  const endCharacter = finiteNumber(rangeLike?.end?.character);
+  if (startLine === undefined || startCharacter === undefined || endLine === undefined || endCharacter === undefined) {
+    return;
+  }
+  return {
+    uri: pathToFileURL(filePath).href,
+    filePath,
+    range: {
+      start: {
+        line: Math.floor(startLine) + 1,
+        character: Math.floor(startCharacter) + 1
+      },
+      end: {
+        line: Math.floor(endLine) + 1,
+        character: Math.floor(endCharacter) + 1
+      }
+    }
+  };
+}
+function pushToolLocation(out, uri, range) {
+  const loc = lspToolLocationFromUriRange(uri, range);
+  if (loc)
+    out.push(loc);
+}
+function collectLocationSummaries(result, filePath) {
+  const out = [];
+  for (const entry of Array.isArray(result) ? result : [result]) {
+    const record = asRecord(entry);
+    if (!record)
+      continue;
+    pushToolLocation(out, record.uri, record.range);
+    pushToolLocation(out, record.targetUri, record.targetSelectionRange ?? record.targetRange);
+    if (!record.uri && !record.targetUri) {
+      const local = lspToolLocationFromFileRange(filePath, record.range);
+      let alreadyIncluded = false;
+      for (const loc of out) {
+        if (loc.uri === local?.uri) {
+          alreadyIncluded = true;
+          break;
+        }
+      }
+      if (local && !alreadyIncluded)
+        out.push(local);
+    }
+  }
+  return out;
+}
+function collectWorkspaceSymbolLocationSummaries(result) {
+  const out = [];
+  for (const entry of Array.isArray(result) ? result : [result]) {
+    const symbol = asRecord(entry);
+    const location = asRecord(symbol?.location);
+    if (!location)
+      continue;
+    pushToolLocation(out, location.uri, location.range);
+    pushToolLocation(out, location.targetUri, location.targetSelectionRange ?? location.targetRange);
+  }
+  return out;
+}
+function collectCallHierarchyLocationSummaries(result, operation) {
+  const out = [];
+  for (const entry of Array.isArray(result) ? result : [result]) {
+    const record = asRecord(entry);
+    const item = asRecord(operation === "incomingCalls" ? record?.from : record?.to);
+    pushToolLocation(out, item?.uri, item?.selectionRange ?? item?.range);
+  }
+  return out;
+}
+function collectLspToolLocationsForOperation(operation, result, filePath) {
+  if ([
+    "definition",
+    "typeDefinition",
+    "declaration",
+    "references",
+    "implementation",
+    "prepareCallHierarchy"
+  ].includes(operation)) {
+    return collectLocationSummaries(result, filePath);
+  }
+  if (operation === "workspaceSymbol") {
+    return collectWorkspaceSymbolLocationSummaries(result);
+  }
+  if (operation === "documentSymbol" || operation === "findSymbol") {
+    return collectLocationSummaries(result, filePath);
+  }
+  if (operation === "incomingCalls" || operation === "outgoingCalls") {
+    return collectCallHierarchyLocationSummaries(result, operation);
+  }
+  return [];
+}
+function parseBalancedJsonPrefix(text) {
+  const trimmed = text.trim();
+  const start = trimmed.search(/[[{]/);
+  if (start < 0)
+    return;
+  const open = trimmed[start];
+  const close = open === "[" ? "]" : "}";
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = start;i < trimmed.length; i += 1) {
+    const ch = trimmed[i];
+    if (inString) {
+      if (escaped)
+        escaped = false;
+      else if (ch === "\\")
+        escaped = true;
+      else if (ch === '"')
+        inString = false;
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      continue;
+    }
+    if (ch === open)
+      depth += 1;
+    if (ch === close)
+      depth -= 1;
+    if (depth === 0) {
+      try {
+        return {
+          value: JSON.parse(trimmed.slice(start, i + 1)),
+          rest: trimmed.slice(i + 1).trim()
+        };
+      } catch {
+        return;
+      }
+    }
+  }
+  return;
+}
+function parseLspNavigationTextPayload(text) {
+  const notes = [];
+  const hints = [];
+  const errors = [];
+  const trimmed = text.trim();
+  if (!trimmed)
+    return { notes, hints, errors };
+  try {
+    return { result: JSON.parse(trimmed), notes, hints, errors };
+  } catch {}
+  const lines = trimmed.split(/\r?\n/);
+  let jsonCandidate = trimmed;
+  if (/^Note:/i.test(lines[0] ?? "") && lines.length > 1) {
+    notes.push((lines.shift() ?? "").replace(/^Note:\s*/i, ""));
+    jsonCandidate = lines.join(`
+`).trim();
+  }
+  const parsed = parseBalancedJsonPrefix(jsonCandidate);
+  if (parsed) {
+    for (const entry of parsed.rest.split(/\r?\n/)) {
+      const line = entry.trim();
+      if (!line)
+        continue;
+      if (/^Hint:/i.test(line))
+        hints.push(line.replace(/^Hint:\s*/i, ""));
+      else if (/^Note:/i.test(line))
+        notes.push(line.replace(/^Note:\s*/i, ""));
+      else
+        notes.push(line);
+    }
+    return { result: parsed.value, notes, hints, errors };
+  }
+  for (const entry of lines) {
+    const line = entry.trim();
+    if (!line)
+      continue;
+    if (/^Hint:/i.test(line))
+      hints.push(line.replace(/^Hint:\s*/i, ""));
+    else if (/^Note:/i.test(line))
+      notes.push(line.replace(/^Note:\s*/i, ""));
+    else if (/^LSP error:/i.test(line))
+      errors.push(line);
+    else
+      notes.push(line);
+  }
+  return { notes, hints, errors };
+}
+function withoutUndefined(value) {
+  for (const key of Object.keys(value)) {
+    if (value[key] === undefined)
+      delete value[key];
+  }
+  return value;
+}
+export function buildLspNavigationEnvelope(options) {
+  const parsed = parseLspNavigationTextPayload(options.text ?? "");
+  const status = lspStatusFromFailureKind(options.failureKind);
+  const result = parsed.result;
+  const notes = [...parsed.notes];
+  const hints = [...parsed.hints];
+  const errors = [...parsed.errors];
+  if (options.isError && errors.length === 0 && (options.text ?? "").trim()) {
+    errors.push((options.text ?? "").trim());
+  }
+  const locations = collectLspToolLocationsForOperation(options.operation, result, options.filePath ?? "");
+  return withoutUndefined({
+    tool: "lsp_navigation",
+    operation: options.operation,
+    ok: !options.isError,
+    status,
+    filePath: options.filePath,
+    resultCount: options.resultCount,
+    result,
+    locations: locations.length > 0 ? locations : undefined,
+    notes: notes.length > 0 ? notes : undefined,
+    hints: hints.length > 0 ? hints : undefined,
+    errors: errors.length > 0 ? errors : undefined,
+    metadata: options.details
+  });
+}

package/extensions/dm-lens/dist/tools/module-report.js

@@ -0,0 +1,332 @@
+import * as path from "node:path";
+import { Type } from "../clients/deps/typebox.js";
+import { logLatency } from "../clients/latency-logger.js";
+import { moduleReport, readEnclosing, readSymbol, renderCompactModuleReport } from "../clients/module-report.js";
+import { baseName, compactRenderResult } from "./render-compact.js";
+function resolveFile(filePath, cwd) {
+  return path.isAbsolute(filePath) ? filePath : path.resolve(cwd || ".", filePath);
+}
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+export function createModuleReportTool(getProjectRoot) {
+  return {
+    name: "module_report",
+    label: "Module Report",
+    description: "Return a navigable source-module outline with symbols, references, and read handles. An outline shows shape, not bodies, and does not satisfy read-before-edit; `read_symbol` and `read_enclosing` return body text and record read coverage. On a cold cache, project_report and symbol_search return available: false with a retry hint and start a non-blocking background build; module_report degrades to outline-only with cache freshness explicit. Example: use module_report on `src/app.ts` before read_symbol.",
+    promptSnippet: "Outline a source module before reading a body",
+    renderResult: compactRenderResult(({ details, args, isError }) => {
+      const base = baseName(args.path) || "module";
+      if (isError || details?.available === false) {
+        return `module_report ${base} — unavailable`;
+      }
+      const parts = [
+        `${details?.symbols ?? 0} symbols`,
+        `${details?.exports ?? 0} exports`
+      ];
+      if (details?.callbacks)
+        parts.push(`${details.callbacks} callbacks`);
+      const view = details?.view && details.view !== "default" ? ` [${details.view}]` : "";
+      return `module_report ${base}  ${parts.join(" · ")}${view}`;
+    }),
+    parameters: Type.Object({
+      path: Type.String({
+        description: "Source file, e.g. `src/app.ts`."
+      }),
+      maxRefsPerSymbol: Type.Optional(Type.Number({
+        description: "Cap on who-uses-this entries per symbol (default 10)."
+      })),
+      focus: Type.Optional(Type.String({
+        description: "Optional task hint used only to rank recommendedReads (does not expand scope or trigger scans)."
+      })),
+      view: Type.Optional(Type.String({
+        enum: ["summary", "default", "compact"],
+        description: "Payload tier. summary returns top-level entries/recommendedReads and section provenance with heavy callback/usedBy/blast-radius payloads omitted. compact (cheapest) returns a line-oriented TEXT rendering of the full report instead of JSON."
+      })),
+      blastRadius: Type.Optional(Type.Boolean({
+        description: "Include the cross-file blast-radius section: transitive dependents aggregated to ranked file reads. Read-only over the cached graph (omitted when cold)."
+      })),
+      blastRadiusDepth: Type.Optional(Type.Number({
+        description: "Max hops for the blast-radius walk (default 3). Only used with blastRadius."
+      })),
+      callGraph: Type.Optional(Type.Boolean({
+        description: "Include bounded derived callers/callees from the cached FunctionCallGraph; cold or stale cache state is explicit."
+      })),
+      maxCallGraphEntries: Type.Optional(Type.Number({
+        description: "Per-direction cap for call-graph relations (default 20)."
+      }))
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const absFile = resolveFile(params.path, ctx.cwd);
+      const cwd = getProjectRoot() || ctx.cwd || ".";
+      let report;
+      try {
+        report = await moduleReport(absFile, cwd, {
+          maxRefsPerSymbol: params.maxRefsPerSymbol,
+          focus: params.focus,
+          view: params.view,
+          blastRadius: params.blastRadius,
+          blastRadiusDepth: params.blastRadiusDepth,
+          callGraph: params.callGraph,
+          maxCallGraphEntries: params.maxCallGraphEntries
+        });
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Module report failed for ${path.basename(absFile)}: ${errorMessage(err)}`
+            }
+          ],
+          isError: true,
+          details: { available: false }
+        };
+      }
+      const text = params.view === "compact" ? renderCompactModuleReport(report) : JSON.stringify(report);
+      return {
+        content: [{ type: "text", text }],
+        isError: !report.available,
+        details: {
+          available: report.available,
+          staleness: report.staleness,
+          symbols: report.summary.symbols,
+          exports: report.summary.exports,
+          callbacks: report.callbacks.length,
+          callbackSupport: report.callbackSupport,
+          view: report.view ?? "default"
+        }
+      };
+    }
+  };
+}
+function recordReadCoverage(recordSymbolRead, result, phase, toolCallId) {
+  if (!result.name || !result.kind || typeof result.startLine !== "number" || typeof result.endLine !== "number") {
+    return false;
+  }
+  try {
+    recordSymbolRead(result.path, {
+      name: result.name,
+      kind: result.kind,
+      startLine: result.startLine,
+      endLine: result.endLine
+    }, toolCallId);
+    return true;
+  } catch (err) {
+    logLatency({
+      type: "phase",
+      phase,
+      filePath: result.path,
+      durationMs: 0,
+      metadata: { error: errorMessage(err) }
+    });
+    return false;
+  }
+}
+export function createReadSymbolTool(getProjectRoot, recordSymbolRead) {
+  return {
+    name: "read_symbol",
+    label: "Read Symbol",
+    description: "Return one symbol's verbatim source. An outline shows shape, not bodies, and does not satisfy read-before-edit; `read_symbol` and `read_enclosing` return body text and record read coverage. Example: use read_symbol after module_report identifies `parseConfig`.",
+    promptSnippet: "Read one symbol's body instead of the whole file",
+    renderResult: compactRenderResult(({ details, args, isError, lineCount }) => {
+      const base = baseName(args.path);
+      if (isError || details?.found === false) {
+        const sym = typeof args.symbol === "string" ? args.symbol : "?";
+        return `read_symbol "${sym}" ${base} — not found`;
+      }
+      const range = details?.startLine && details?.endLine ? `:${details.startLine}-${details.endLine} (${details.endLine - details.startLine + 1} lines)` : ` (${lineCount} lines)`;
+      return `read_symbol ${details?.kind ?? ""} ${details?.name ?? ""}  ${base}${range}`.replace(/\s+/g, " ");
+    }),
+    parameters: Type.Object({
+      path: Type.String({
+        description: "Absolute or workspace-relative path to the source file."
+      }),
+      symbol: Type.String({
+        description: "Exact symbol name or callback handle to read (e.g. a function, class, type, or module_report callbacks[].name). Accepts a dotted `Class.method` name to resolve a member."
+      }),
+      kind: Type.Optional(Type.String({
+        description: "Optional kind filter (e.g. function, interface, class) to disambiguate when multiple same-file symbols share the requested name. Omitting it returns the first match, same as today."
+      }))
+    }),
+    async execute(toolCallId, params, _signal, _onUpdate, ctx) {
+      const absFile = resolveFile(params.path, ctx.cwd);
+      const cwd = getProjectRoot() || ctx.cwd || ".";
+      let result;
+      try {
+        result = await readSymbol(absFile, params.symbol, cwd, {
+          kind: params.kind
+        });
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Read symbol failed for ${path.basename(absFile)}: ${errorMessage(err)}`
+            }
+          ],
+          isError: true,
+          details: { found: false }
+        };
+      }
+      if (!result.found) {
+        const warningSuffix = result.warnings?.length ? ` Warnings: ${result.warnings.join("; ")}` : "";
+        const suggestionSuffix = result.suggestions?.length ? ` Did you mean: ${result.suggestions.join(", ")}?` : " Use module_report to list available symbols.";
+        const text = result.error ? `Could not inspect ${path.basename(absFile)}: ${result.error}${warningSuffix}` : `Symbol "${params.symbol}" not found in ${path.basename(absFile)}.${suggestionSuffix}${warningSuffix}`;
+        return {
+          content: [{ type: "text", text }],
+          isError: true,
+          details: {
+            found: false,
+            ...result.error ? { error: result.error } : {},
+            ...result.warnings ? { warnings: result.warnings } : {},
+            ...result.suggestions ? { suggestions: result.suggestions } : {}
+          }
+        };
+      }
+      const readRecorded = recordReadCoverage(recordSymbolRead, result, "read_symbol_guard_error", toolCallId);
+      const ambiguityNote = result.ambiguous ? ` (${result.ambiguous.count} matches — returned the ${result.kind}; pass \`kind\` to disambiguate: ${result.ambiguous.kinds.join(", ")})` : "";
+      const header = `${result.kind} ${result.name}${ambiguityNote}  ${path.basename(result.path)}:${result.startLine}-${result.endLine}`;
+      const guardWarning = readRecorded ? "" : `
+
+Warning: read coverage recording failed; the returned body may not satisfy the edit guard.`;
+      return {
+        content: [
+          {
+            type: "text",
+            text: `${header}${guardWarning}
+
+${result.source ?? ""}`
+          }
+        ],
+        details: {
+          found: true,
+          name: result.name,
+          kind: result.kind,
+          startLine: result.startLine,
+          endLine: result.endLine,
+          readRecorded,
+          ...result.ambiguous ? { ambiguous: result.ambiguous } : {}
+        }
+      };
+    }
+  };
+}
+export function createReadEnclosingTool(getProjectRoot, recordSymbolRead) {
+  return {
+    name: "read_enclosing",
+    label: "Read Enclosing",
+    description: "Return the smallest symbol or callback enclosing a line. An outline shows shape, not bodies, and does not satisfy read-before-edit; `read_symbol` and `read_enclosing` return body text and record read coverage. Example: use read_enclosing after a diagnostic points to line 42.",
+    promptSnippet: "Read the enclosing symbol or callback body for a line",
+    renderResult: compactRenderResult(({ details, args, isError }) => {
+      const base = baseName(args.path);
+      if (isError || details?.found === false) {
+        const ln = typeof args.line === "number" ? args.line : "?";
+        return `read_enclosing ${base}:${ln} — no enclosing symbol`;
+      }
+      const range = details?.startLine && details?.endLine ? `:${details.startLine}-${details.endLine}` : "";
+      return `read_enclosing ${details?.kind ?? ""} ${details?.name ?? ""}  ${base}${range}`.replace(/\s+/g, " ");
+    }),
+    parameters: Type.Object({
+      path: Type.String({
+        description: "Absolute or workspace-relative path to the source file."
+      }),
+      line: Type.Number({
+        description: "1-based line number inside the desired symbol/callback."
+      }),
+      kinds: Type.Optional(Type.Array(Type.String(), {
+        description: "Optional kind filter, e.g. function, method, callback, class, object_property_callback."
+      })),
+      maxLines: Type.Optional(Type.Number({
+        description: "Optional maximum body size to return. Oversized matches obey onOversize."
+      })),
+      onOversize: Type.Optional(Type.String({
+        enum: ["error", "slice", "outline"],
+        description: "Behavior when the enclosing body exceeds maxLines. error (default) returns metadata only; slice returns a bounded partial read around line; outline returns nested symbols/callbacks with read handles."
+      })),
+      aroundLine: Type.Optional(Type.Number({
+        description: "Maximum lines for onOversize=slice; defaults to maxLines, then 80."
+      }))
+    }),
+    async execute(toolCallId, params, _signal, _onUpdate, ctx) {
+      const absFile = resolveFile(params.path, ctx.cwd);
+      const cwd = getProjectRoot() || ctx.cwd || ".";
+      let result;
+      try {
+        result = await readEnclosing(absFile, params.line, cwd, {
+          kinds: params.kinds,
+          maxLines: params.maxLines,
+          onOversize: params.onOversize,
+          aroundLine: params.aroundLine
+        });
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Read enclosing failed for ${path.basename(absFile)}:${params.line}: ${errorMessage(err)}`
+            }
+          ],
+          isError: true,
+          details: { found: false }
+        };
+      }
+      if (!result.found) {
+        const warningSuffix = result.warnings?.length ? ` Warnings: ${result.warnings.join("; ")}` : "";
+        const outlineSuffix = result.outline?.length ? `
+
+Nested outline:
+${JSON.stringify(result.outline)}` : "";
+        const text = result.error ? `Could not read enclosing range in ${path.basename(absFile)}:${result.line}: ${result.error}${warningSuffix}${outlineSuffix}` : `No enclosing symbol/callback found in ${path.basename(absFile)}:${result.line}.${warningSuffix}`;
+        return {
+          content: [{ type: "text", text }],
+          isError: true,
+          details: {
+            found: false,
+            line: result.line,
+            ...result.name ? { name: result.name } : {},
+            ...result.kind ? { kind: result.kind } : {},
+            ...result.startLine ? { startLine: result.startLine } : {},
+            ...result.endLine ? { endLine: result.endLine } : {},
+            ...result.enclosingStartLine ? { enclosingStartLine: result.enclosingStartLine } : {},
+            ...result.enclosingEndLine ? { enclosingEndLine: result.enclosingEndLine } : {},
+            ...result.selection ? { selection: result.selection } : {},
+            ...result.outline ? { outline: result.outline } : {},
+            ...result.error ? { error: result.error } : {},
+            ...result.warnings ? { warnings: result.warnings } : {}
+          }
+        };
+      }
+      const readRecorded = recordReadCoverage(recordSymbolRead, result, "read_enclosing_guard_error", toolCallId);
+      const range = result.partial ? `${result.startLine}-${result.endLine} (partial of ${result.enclosingStartLine}-${result.enclosingEndLine})` : `${result.startLine}-${result.endLine}`;
+      const header = `${result.kind} ${result.name}  ${path.basename(result.path)}:${range}`;
+      const guardWarning = readRecorded ? "" : `
+
+Warning: read coverage recording failed; the returned body may not satisfy the edit guard.`;
+      return {
+        content: [
+          {
+            type: "text",
+            text: `${header}${guardWarning}
+
+${result.source ?? ""}`
+          }
+        ],
+        details: {
+          found: true,
+          name: result.name,
+          kind: result.kind,
+          line: result.line,
+          startLine: result.startLine,
+          endLine: result.endLine,
+          enclosingStartLine: result.enclosingStartLine,
+          enclosingEndLine: result.enclosingEndLine,
+          parentChain: result.parentChain,
+          partial: result.partial,
+          selection: result.selection,
+          readRecorded,
+          ...result.warnings ? { warnings: result.warnings } : {}
+        }
+      };
+    }
+  };
+}

package/extensions/dm-lens/dist/tools/project-report.js

@@ -0,0 +1,72 @@
+import { Type } from "../clients/deps/typebox.js";
+import { projectReport, renderCompactProjectReport } from "../clients/lens-engine.js";
+import { compactRenderResult, renderToolText } from "./render-compact.js";
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+export function createProjectReportTool(getProjectRoot) {
+  return {
+    name: "project_report",
+    label: "Project Report",
+    description: "Orient in a project from its review graph, with ranked hubs and entry points. On a cold cache, project_report and symbol_search return available: false with a retry hint and start a non-blocking background build; module_report degrades to outline-only with cache freshness explicit. Example: use project_report before module_report when the target file is unknown.",
+    promptSnippet: "Orient in a project before choosing a file",
+    renderResult: compactRenderResult(({ details, isError }) => {
+      if (isError || details?.available === false) {
+        return `project_report — unavailable${details?.hint ? `: ${details.hint}` : ""}`;
+      }
+      const parts = [
+        `${details?.hubs ?? 0} hub(s)`,
+        `${details?.entryPoints ?? 0} entry point(s)`
+      ];
+      const view = details?.view && details.view !== "default" ? ` [${details.view}]` : "";
+      return `project_report  ${parts.join(" · ")}${view}`;
+    }),
+    parameters: Type.Object({
+      limit: Type.Optional(Type.Number({
+        description: "Scales every ranked section's cap (default 10) — a single knob for all sections."
+      })),
+      focus: Type.Optional(Type.String({
+        description: "Optional task hint used only to re-rank sections toward relevant subsystems (does not expand scope or trigger scans)."
+      })),
+      view: Type.Optional(Type.String({
+        enum: ["default", "compact"],
+        description: "Payload tier. compact (cheapest) returns a line-oriented TEXT rendering instead of JSON. Default returns JSON."
+      }))
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const cwd = getProjectRoot() || ctx.cwd || ".";
+      let report;
+      try {
+        report = await projectReport(cwd, {
+          limit: params.limit,
+          focus: params.focus,
+          view: params.view === "compact" ? "compact" : undefined
+        });
+      } catch (err) {
+        return {
+          ...renderToolText(`Project report failed: ${errorMessage(err)}`),
+          isError: true,
+          details: { available: false }
+        };
+      }
+      if (!report.available) {
+        return {
+          ...renderToolText(report.hint ?? "No review graph cached for this workspace yet.", report),
+          isError: true,
+          details: { available: false, hint: report.hint }
+        };
+      }
+      const text = params.view === "compact" ? renderCompactProjectReport(report) : JSON.stringify(report);
+      return {
+        content: [{ type: "text", text }],
+        isError: false,
+        details: {
+          available: true,
+          hubs: report.hubs?.length ?? 0,
+          entryPoints: report.entryPoints?.length ?? 0,
+          view: report.view ?? "default"
+        }
+      };
+    }
+  };
+}