@flyingrobots/graft 0.7.0 → 0.8.0

package/src/mcp/tools/code-show.ts

@@ -1,289 +0,0 @@
-import { z } from "zod";
-import { readRange } from "../../operations/read-range.js";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
-import { nodePathOps } from "../../adapters/node-paths.js";
-import { indexHead } from "../../warp/index-head.js";
-import { listProjectFiles } from "./git-files.js";
-import {
-  evaluatePrecisionPolicy,
-  getIndexedCommitCeilings,
-  listTrackedFilesAtRef,
-  loadFileContent,
-  normalizeRepoPath,
-  PrecisionSearchRequest,
-  type PrecisionSymbolMatch,
-  readRangeFromContent,
-  requireRepoPath,
-  resolveGitRef,
-  searchLiveSymbols,
-  searchWarpSymbols,
-} from "./precision.js";
-
-interface CodeShowOptions {
-  readonly allowWarp: boolean;
-}
-
-async function lazyIndexReadPaths(
-  ctx: ToolContext,
-  paths: readonly string[],
-  dirty: boolean,
-): Promise<void> {
-  if (dirty || paths.length === 0) return;
-  try {
-    const warp = await ctx.getWarp();
-    await indexHead({
-      cwd: ctx.projectRoot,
-      git: ctx.git,
-      pathOps: nodePathOps,
-      ctx: warp,
-      paths: [...new Set(paths)],
-    });
-  } catch {
-    // Lazy indexing is a cache refresh. It must not break the read response.
-  }
-}
-
-export async function runCodeShow(
-  ctx: ToolContext,
-  args: Record<string, unknown>,
-  options: CodeShowOptions,
-) {
-  const symbolName = args["symbol"] as string;
-  const rawPath = args["path"] as string | undefined;
-  const ref = args["ref"] as string | undefined;
-  const targetPath = rawPath !== undefined ? normalizeRepoPath(ctx.projectRoot, rawPath) : undefined;
-  const repoState = ctx.getRepoState();
-  const layer = ref !== undefined
-    ? "commit_worldline"
-    : repoState.dirty
-      ? "workspace_overlay"
-      : "ref_view";
-
-  let resolvedRef: string | undefined;
-  if (ref !== undefined) {
-    try {
-      resolvedRef = await resolveGitRef(ref, ctx.git, ctx.projectRoot);
-    } catch (err: unknown) {
-      const message = err instanceof Error ? err.message : String(err);
-      return ctx.respond("code_show", {
-        symbol: symbolName,
-        error: message,
-        source: "live",
-        layer,
-      });
-    }
-  }
-
-  let locations: PrecisionSymbolMatch[];
-  let source: "warp" | "live" = "live";
-
-  if (resolvedRef !== undefined) {
-    if (targetPath !== undefined) {
-      try {
-        requireRepoPath(ctx.projectRoot, targetPath);
-      } catch (err: unknown) {
-        const message = err instanceof Error ? err.message : String(err);
-        return ctx.respond("code_show", {
-          symbol: symbolName,
-          error: message,
-          source: "live",
-          layer,
-        });
-      }
-    }
-
-    try {
-      const repoPath = targetPath !== undefined ? requireRepoPath(ctx.projectRoot, targetPath) : undefined;
-      if (options.allowWarp) {
-        const warp = await ctx.getWarp();
-        const ceilings = await getIndexedCommitCeilings(warp);
-        const ceiling = ceilings.get(resolvedRef);
-        if (ceiling !== undefined) {
-          locations = await searchWarpSymbols(warp, new PrecisionSearchRequest({
-            exactName: symbolName,
-            ...(repoPath !== undefined ? { filePath: repoPath } : {}),
-            ceiling,
-          }));
-          source = "warp";
-        } else {
-          const filePaths = repoPath !== undefined
-            ? [repoPath]
-            : await listTrackedFilesAtRef("", ctx.git, ctx.projectRoot, resolvedRef);
-          locations = await searchLiveSymbols(
-            ctx,
-            filePaths,
-            new PrecisionSearchRequest({ exactName: symbolName }),
-            resolvedRef,
-          );
-        }
-      } else {
-        const filePaths = repoPath !== undefined
-          ? [repoPath]
-          : await listTrackedFilesAtRef("", ctx.git, ctx.projectRoot, resolvedRef);
-        locations = await searchLiveSymbols(
-          ctx,
-          filePaths,
-          new PrecisionSearchRequest({ exactName: symbolName }),
-          resolvedRef,
-        );
-      }
-    } catch {
-      const repoPath = targetPath !== undefined ? requireRepoPath(ctx.projectRoot, targetPath) : undefined;
-      const filePaths = repoPath !== undefined
-        ? [repoPath]
-        : await listTrackedFilesAtRef("", ctx.git, ctx.projectRoot, resolvedRef);
-      locations = await searchLiveSymbols(
-        ctx,
-        filePaths,
-        new PrecisionSearchRequest({ exactName: symbolName }),
-        resolvedRef,
-      );
-      source = "live";
-    }
-  } else {
-    const filePaths = targetPath !== undefined
-      ? [targetPath]
-      : await listProjectFiles("", ctx.projectRoot, ctx.git);
-    locations = await searchLiveSymbols(
-      ctx,
-      filePaths,
-      new PrecisionSearchRequest({ exactName: symbolName }),
-    );
-  }
-
-  const visibleLocations: PrecisionSymbolMatch[] = [];
-  const fileCache = new Map<string, string>();
-  let firstRefusal:
-    | {
-      path: string;
-      reason: string;
-      reasonDetail: string;
-      next: readonly string[];
-      actual: { lines: number; bytes: number };
-    }
-    | undefined;
-
-  for (const location of locations) {
-    let content = fileCache.get(location.path);
-    if (content === undefined) {
-      const loaded = await loadFileContent(ctx, location.path, resolvedRef);
-      if (loaded === null) continue;
-      fileCache.set(location.path, loaded);
-      content = loaded;
-    }
-
-    const refusal = evaluatePrecisionPolicy(ctx, location.path, content);
-    if (refusal !== null) {
-      firstRefusal ??= refusal;
-      continue;
-    }
-
-    visibleLocations.push(location);
-  }
-
-  if (visibleLocations.length === 0) {
-    if (firstRefusal !== undefined) {
-      return ctx.respond("code_show", {
-        path: firstRefusal.path,
-        projection: "refused",
-        reason: firstRefusal.reason,
-        reasonDetail: firstRefusal.reasonDetail,
-        next: [...firstRefusal.next],
-        actual: firstRefusal.actual,
-        source,
-        layer,
-      });
-    }
-
-    return ctx.respond("code_show", {
-      symbol: symbolName,
-      error: `Symbol '${symbolName}' not found`,
-      source,
-      layer,
-    });
-  }
-
-  if (visibleLocations.length > 1) {
-    ctx.recordFootprint({
-      paths: [...new Set(visibleLocations.map((m) => m.path))],
-      symbols: visibleLocations.map((m) => m.name),
-    });
-    await lazyIndexReadPaths(ctx, visibleLocations.map((m) => m.path), repoState.dirty);
-    return ctx.respond("code_show", {
-      symbol: symbolName,
-      ambiguous: true,
-      matches: visibleLocations,
-      source,
-      layer,
-    });
-  }
-
-  const loc = visibleLocations[0];
-  if (loc?.startLine === undefined || loc.endLine === undefined) {
-    if (loc?.path !== undefined) {
-      await lazyIndexReadPaths(ctx, [loc.path], repoState.dirty);
-    }
-    return ctx.respond("code_show", {
-      symbol: symbolName,
-      kind: loc?.kind,
-      signature: loc?.signature,
-      path: loc?.path,
-      exported: loc?.exported,
-      error: "Symbol found but line range unavailable — use read_range with file_outline",
-      source,
-      layer,
-    });
-  }
-
-  const content = fileCache.get(loc.path) ?? await loadFileContent(ctx, loc.path, resolvedRef);
-  if (content === null) {
-    return ctx.respond("code_show", {
-      symbol: symbolName,
-      error: `File '${loc.path}' is no longer readable`,
-      source,
-      layer,
-    });
-  }
-
-  const rangeResult = resolvedRef !== undefined
-    ? readRangeFromContent(loc.path, content, loc.startLine, loc.endLine)
-    : await readRange(ctx.resolvePath(loc.path), loc.startLine, loc.endLine, { fs: ctx.fs });
-
-  ctx.recordFootprint({
-    paths: [loc.path],
-    symbols: [loc.name],
-    regions: [{ path: loc.path, startLine: loc.startLine, endLine: loc.endLine }],
-  });
-  await lazyIndexReadPaths(ctx, [loc.path], repoState.dirty);
-
-  return ctx.respond("code_show", {
-    symbol: loc.name,
-    kind: loc.kind,
-    signature: loc.signature,
-    path: loc.path,
-    exported: loc.exported,
-    startLine: loc.startLine,
-    endLine: loc.endLine,
-    content: rangeResult.content,
-    truncated: rangeResult.truncated ?? false,
-    ...(rangeResult.clipped === true ? { clipped: true } : {}),
-    source,
-    layer,
-  });
-}
-
-export const codeShowTool: ToolDefinition = {
-  name: "code_show",
-  description:
-    "Focus on a symbol by name and return its source code in one call. " +
-    "Provide a path to target a specific file, or omit to search the " +
-    "project. Returns source, signature, and location.",
-  schema: {
-    symbol: z.string(),
-    path: z.string().optional(),
-    ref: z.string().optional(),
-  },
-  createHandler(): ToolHandler {
-    return (args, ctx) => runCodeShow(ctx, args, { allowWarp: true });
-  },
-};

package/src/mcp/tools/daemon-monitors.ts

@@ -1,14 +0,0 @@
-import type { ToolDefinition, ToolHandler } from "../context.js";
-
-export const daemonMonitorsTool: ToolDefinition = {
-  name: "daemon_monitors",
-  description:
-    "List daemon-managed persistent repo monitors with lifecycle, backlog, and recent failure state.",
-  createHandler(): ToolHandler {
-    return async (_args, ctx) => {
-      return ctx.respond("daemon_monitors", {
-        monitors: await ctx.listDaemonMonitors(),
-      });
-    };
-  },
-};

package/src/mcp/tools/daemon-repos.ts

@@ -1,22 +0,0 @@
-import { z } from "zod";
-import type { ToolDefinition, ToolHandler } from "../context.js";
-
-export const daemonReposTool: ToolDefinition = {
-  name: "daemon_repos",
-  description:
-    "List authorized canonical repos with bounded worktree, session, backlog, and monitor summary for daemon-wide inspection.",
-  schema: {
-    repoId: z.string().optional(),
-    cwd: z.string().optional(),
-  },
-  createHandler(): ToolHandler {
-    return async (args, ctx) => {
-      return ctx.respond("daemon_repos", {
-        ...await ctx.listDaemonRepos({
-          repoId: args["repoId"] as string | undefined,
-          cwd: args["cwd"] as string | undefined,
-        }),
-      });
-    };
-  },
-};

package/src/mcp/tools/daemon-sessions.ts

@@ -1,14 +0,0 @@
-import type { ToolDefinition, ToolHandler } from "../context.js";
-
-export const daemonSessionsTool: ToolDefinition = {
-  name: "daemon_sessions",
-  description:
-    "List active daemon sessions with bind state, workspace identity, and capability posture, without exposing session-local receipts or shell output.",
-  createHandler(): ToolHandler {
-    return async (_args, ctx) => {
-      return ctx.respond("daemon_sessions", {
-        sessions: await ctx.listDaemonSessions(),
-      });
-    };
-  },
-};

package/src/mcp/tools/daemon-status.ts

@@ -1,12 +0,0 @@
-import type { ToolDefinition, ToolHandler } from "../context.js";
-
-export const daemonStatusTool: ToolDefinition = {
-  name: "daemon_status",
-  description:
-    "Return daemon-wide health, authorization counts, and default capability posture for the local control plane.",
-  createHandler(): ToolHandler {
-    return async (_args, ctx) => {
-      return ctx.respond("daemon_status", { ...await ctx.getDaemonStatus() });
-    };
-  },
-};

package/src/mcp/tools/diagnostic-models.ts

@@ -1,97 +0,0 @@
-// ---------------------------------------------------------------------------
-// Diagnostic tool response models — explicit types for diagnostic tool outputs
-// ---------------------------------------------------------------------------
-
-import type { BurdenByKind, BurdenKind } from "../burden.js";
-import type { RuntimeObservabilityState } from "../runtime-observability.js";
-import type { RuntimeCausalContext } from "../runtime-causal-context.js";
-import type { GovernorDepth } from "../../session/types.js";
-import type {
-  PersistedLocalHistorySummary,
-  RepoConcurrencySummary,
-} from "../persisted-local-history.js";
-import type { RuntimeWorkspaceOverlayFooting } from "../runtime-workspace-overlay.js";
-import type { CausalSurfaceNextAction } from "../../contracts/causal-surface-next-action.js";
-import type { SludgeReport } from "../../operations/sludge-detector.js";
-
-export interface SetBudgetResponse {
-  readonly budget: {
-    readonly total: number;
-    readonly consumed: number;
-    readonly remaining: number;
-    readonly fraction: number;
-  } | null;
-}
-
-export interface StatsResponse {
-  readonly totalReads: number;
-  readonly totalOutlines: number;
-  readonly totalRefusals: number;
-  readonly totalCacheHits: number;
-  readonly totalBytesReturned: number;
-  readonly totalBytesAvoidedByCache: number;
-  readonly totalNonReadBytesReturned: number;
-  readonly burdenByKind: Readonly<BurdenByKind>;
-}
-
-export interface ExplainResponse {
-  readonly code: string;
-  readonly meaning?: string | undefined;
-  readonly action?: string | undefined;
-  readonly error?: string | undefined;
-  readonly knownCodes?: string | undefined;
-}
-
-export interface DoctorBurdenSummary {
-  readonly totalBytesReturned: number;
-  readonly totalNonReadBytesReturned: number;
-  readonly topKind: BurdenKind | null;
-  readonly topBytesReturned: number;
-  readonly topCalls: number;
-}
-
-export interface DoctorResponse {
-  readonly projectRoot: string;
-  readonly parserHealthy: boolean;
-  readonly thresholds: { readonly lines: number; readonly bytes: number };
-  readonly sessionDepth: GovernorDepth;
-  readonly totalMessages: number;
-  readonly burdenSummary: DoctorBurdenSummary;
-  readonly runtimeObservability: RuntimeObservabilityState;
-  readonly causalContext: RuntimeCausalContext;
-  readonly latestReadEvent: PersistedLocalHistorySummary["latestReadEvent"];
-  readonly latestStageEvent: PersistedLocalHistorySummary["latestStageEvent"];
-  readonly latestTransitionEvent: PersistedLocalHistorySummary["latestTransitionEvent"];
-  readonly repoConcurrency: RepoConcurrencySummary | null;
-  readonly checkoutEpoch: unknown;
-  readonly lastTransition: unknown;
-  readonly semanticTransition: unknown;
-  readonly workspaceOverlayId: unknown;
-  readonly workspaceOverlay: unknown;
-  readonly workspaceOverlayFooting: RuntimeWorkspaceOverlayFooting | null;
-  readonly stagedTarget: unknown;
-  readonly attribution: PersistedLocalHistorySummary["attribution"];
-  readonly persistedLocalHistory: PersistedLocalHistorySummary;
-  readonly recommendedNextAction: CausalSurfaceNextAction;
-  readonly sludge?: SludgeReport | undefined;
-}
-
-export interface RunCapturePolicyBoundary {
-  readonly kind: "shell_escape_hatch";
-  readonly boundedReadContract: false;
-  readonly policyEnforced: false;
-}
-
-export interface RunCaptureResponse {
-  readonly output: string;
-  readonly totalLines: number;
-  readonly tailedLines: number;
-  readonly logPath: string | null;
-  readonly logRedactions: number;
-  readonly logPersistenceEnabled: boolean;
-  readonly truncated: boolean;
-  readonly policyBoundary: RunCapturePolicyBoundary;
-  readonly disabled?: boolean | undefined;
-  readonly error?: string | undefined;
-  readonly stderr?: string | undefined;
-}

package/src/mcp/tools/doctor.ts

@@ -1,83 +0,0 @@
-import { STATIC_THRESHOLDS } from "../../policy/evaluate.js";
-import { topBurdenKind, totalNonReadBytesReturned } from "../burden.js";
-import { buildRuntimeStagedTarget } from "../runtime-staged-target.js";
-import { deriveCausalSurfaceNextAction } from "../semantic-transition-guidance.js";
-import type { ToolDefinition, ToolHandler } from "../context.js";
-import { toJsonObject } from "../../operations/result-dto.js";
-import type { DoctorResponse } from "./diagnostic-models.js";
-import { detectSludge } from "../../operations/sludge-detector.js";
-import { z } from "zod";
-
-export const doctorTool: ToolDefinition = {
-  name: "doctor",
-  description:
-    "Runtime health check. Shows project root, parser status, active " +
-    "thresholds, session depth, message count, and burden summary.",
-  schema: {
-    sludge: z.boolean().optional(),
-    path: z.string().optional(),
-  },
-  createHandler(): ToolHandler {
-    return async (args, ctx) => {
-      const pathArg = typeof args["path"] === "string" ? args["path"] : undefined;
-      const sludge = args["sludge"] === true
-        ? await detectSludge({
-          cwd: ctx.projectRoot,
-          fs: ctx.fs,
-          git: ctx.git,
-          resolvePath: (filePath) => ctx.resolvePath(filePath),
-          ...(pathArg !== undefined ? { path: pathArg } : {}),
-        })
-        : undefined;
-      const repoState = ctx.getRepoState();
-      const causalContext = ctx.getCausalContext();
-      const workspaceOverlayFooting = await ctx.getWorkspaceOverlayFooting();
-      const metrics = ctx.metrics.snapshot();
-      const topBurden = topBurdenKind(metrics.burdenByKind);
-      const persistedLocalHistory = await ctx.getPersistedLocalHistorySummary();
-      const repoConcurrency = await ctx.getRepoConcurrencySummary();
-      const recommendedNextAction = deriveCausalSurfaceNextAction(
-        persistedLocalHistory.nextAction,
-        repoState.semanticTransition,
-        repoConcurrency,
-      );
-      const response: DoctorResponse = {
-        projectRoot: ctx.projectRoot,
-        parserHealthy: true,
-        thresholds: { lines: STATIC_THRESHOLDS.lines, bytes: STATIC_THRESHOLDS.bytes },
-        sessionDepth: ctx.governor.getGovernorDepth(),
-        totalMessages: ctx.governor.getMessageCount(),
-        burdenSummary: {
-          totalBytesReturned: metrics.bytesReturned,
-          totalNonReadBytesReturned: totalNonReadBytesReturned(metrics.burdenByKind),
-          topKind: topBurden?.kind ?? null,
-          topBytesReturned: topBurden?.bytesReturned ?? 0,
-          topCalls: topBurden?.calls ?? 0,
-        },
-        runtimeObservability: ctx.observability,
-        causalContext,
-        latestReadEvent: persistedLocalHistory.latestReadEvent,
-        latestStageEvent: persistedLocalHistory.latestStageEvent,
-        latestTransitionEvent: persistedLocalHistory.latestTransitionEvent,
-        repoConcurrency,
-        checkoutEpoch: repoState.checkoutEpoch,
-        lastTransition: repoState.lastTransition,
-        semanticTransition: repoState.semanticTransition,
-        workspaceOverlayId: repoState.workspaceOverlayId,
-        workspaceOverlay: repoState.workspaceOverlay,
-        workspaceOverlayFooting,
-        stagedTarget: buildRuntimeStagedTarget(
-          ctx.getWorkspaceStatus(),
-          causalContext,
-          repoState,
-          persistedLocalHistory.attribution,
-        ),
-        attribution: persistedLocalHistory.attribution,
-        persistedLocalHistory,
-        recommendedNextAction,
-        ...(sludge !== undefined ? { sludge } : {}),
-      };
-      return ctx.respond("doctor", toJsonObject(response));
-    };
-  },
-};

package/src/mcp/tools/explain.ts

@@ -1,84 +0,0 @@
-import { z } from "zod";
-import type { ToolDefinition, ToolHandler } from "../context.js";
-
-const EXPLANATIONS: Readonly<Record<string, { meaning: string; action: string }>> = {
-  CONTENT: {
-    meaning: "File is within size thresholds — full content returned.",
-    action: "No action needed. You have the complete file.",
-  },
-  OUTLINE: {
-    meaning: "File exceeds line or byte thresholds. Structural outline returned instead of content.",
-    action: "Use read_range with the jump table to read specific sections. Do not re-request the full file.",
-  },
-  SESSION_CAP: {
-    meaning: "Session-depth byte cap triggered. The file might fit static thresholds but exceeds the dynamic session cap.",
-    action: "Use read_range for targeted reads. Consider whether you truly need this file at this stage of the session.",
-  },
-  BINARY: {
-    meaning: "Binary file (image, PDF, etc.) cannot be usefully read as text.",
-    action: "Use file_outline for metadata. Check for a text alternative.",
-  },
-  LOCKFILE: {
-    meaning: "Machine-generated lockfile is not useful to read directly.",
-    action: "Read the package manifest (package.json, Cargo.toml, etc.) for dependency info instead.",
-  },
-  MINIFIED: {
-    meaning: "Minified file is not human-readable.",
-    action: "Look for the unminified source file.",
-  },
-  BUILD_OUTPUT: {
-    meaning: "File is in a build output directory (dist/, build/, .next/, etc.).",
-    action: "Read the source in src/ instead of the compiled output.",
-  },
-  SECRET: {
-    meaning: "File may contain secrets (keys, credentials, environment variables).",
-    action: "Check for a .example or template version of this file.",
-  },
-  BUDGET_CAP: {
-    meaning: "File exceeds the budget-proportional byte cap. No single read may consume more than 5% of remaining budget.",
-    action: "Use file_outline or read_range for targeted reads. Consider whether this file is worth the budget cost.",
-  },
-  UNSUPPORTED_LANGUAGE: {
-    meaning: "The file type has no parser-backed structural outline in the current build of Graft.",
-    action: "Use read_range or a full read when appropriate. Do not treat the empty outline as parser-derived symbol structure.",
-  },
-  GRAFTIGNORE: {
-    meaning: "File matches a pattern in .graftignore.",
-    action: "Check .graftignore if you believe this file should be readable.",
-  },
-  REREAD_UNCHANGED: {
-    meaning: "File was already read and has not changed. Cached outline returned.",
-    action: "Use the cached outline and jump table. The file content has not changed since your last read.",
-  },
-  CHANGED_SINCE_LAST_READ: {
-    meaning: "File changed since last read. Structural diff returned showing what changed.",
-    action: "Review the diff to understand what changed. Use read_range for details on changed sections.",
-  },
-};
-
-export const explainTool: ToolDefinition = {
-  name: "explain",
-  description:
-    "Explain a graft reason code. Returns human-readable meaning and " +
-    "recommended next action for any reason code returned by graft tools.",
-  schema: { code: z.string() },
-  createHandler(): ToolHandler {
-    return (args, ctx) => {
-      const code = (args["code"] as string).toUpperCase();
-      const entry = EXPLANATIONS[code];
-      if (entry === undefined) {
-        const known = Object.keys(EXPLANATIONS).join(", ");
-        return ctx.respond("explain", {
-          code,
-          error: "Unknown reason code",
-          knownCodes: known,
-        });
-      }
-      return ctx.respond("explain", {
-        code,
-        meaning: entry.meaning,
-        action: entry.action,
-      });
-    };
-  },
-};

package/src/mcp/tools/export-surface-diff.ts

@@ -1,26 +0,0 @@
-import { z } from "zod";
-import { exportSurfaceDiff, exportSurfaceDiffToJson } from "../../operations/export-surface-diff.js";
-import type { ToolDefinition, ToolHandler } from "../context.js";
-
-export const exportSurfaceDiffTool: ToolDefinition = {
-  name: "graft_exports",
-  description:
-    "Export surface diff — what changed in the public API between two " +
-    "refs? Identifies added, removed, and signature-changed exported " +
-    "symbols and derives semver impact.",
-  schema: {
-    base: z.string().optional(),
-    head: z.string().optional(),
-  },
-  createHandler(): ToolHandler {
-    return async (args, ctx) => {
-      const result = await exportSurfaceDiff({
-        cwd: ctx.projectRoot,
-        git: ctx.git,
-        base: args["base"] as string | undefined,
-        head: args["head"] as string | undefined,
-      });
-      return ctx.respond("graft_exports", exportSurfaceDiffToJson(result));
-    };
-  },
-};