@flyingrobots/graft 0.3.5 → 0.5.0

package/src/mcp/repo-tool-job.ts

@@ -0,0 +1,302 @@
+import { z } from "zod";
+import { CanonicalJsonCodec } from "../adapters/canonical-json.js";
+import { nodeFs } from "../adapters/node-fs.js";
+import { nodeGit } from "../adapters/node-git.js";
+import { nodeProcessRunner } from "../adapters/node-process-runner.js";
+import { openWarp } from "../warp/open.js";
+import { SessionTracker, type SessionTrackerSnapshot } from "../session/tracker.js";
+import { buildReceiptResult, type McpToolReceipt, type McpToolResult } from "./receipt.js";
+import { createPathResolver, type ToolContext, type ToolDefinition, type ToolHandler } from "./context.js";
+import { resolveRunCaptureConfig } from "./run-capture-config.js";
+import { resolveRuntimeObservabilityState } from "./runtime-observability.js";
+import { Metrics, diffMetrics, type MetricsDelta, type MetricsSnapshot } from "./metrics.js";
+import { ObservationCache, type ObservationSnapshot } from "./cache.js";
+import type { RepoObservation } from "./repo-state.js";
+import type { WorkspaceCapabilityProfile, WorkspaceStatus } from "./workspace-router.js";
+import { evaluateMcpPolicy } from "./policy.js";
+import { RefusedResult } from "../policy/types.js";
+import { graftDiffTool } from "./tools/graft-diff.js";
+import { sinceTool } from "./tools/since.js";
+import { mapTool } from "./tools/map.js";
+import { codeRefsTool } from "./tools/code-refs.js";
+import { codeFindTool, runCodeFind } from "./tools/code-find.js";
+import { codeShowTool, runCodeShow } from "./tools/code-show.js";
+import { safeReadTool } from "./tools/safe-read.js";
+import { fileOutlineTool } from "./tools/file-outline.js";
+import { changedSinceTool } from "./tools/changed-since.js";
+import { buildRuntimeCausalContext } from "./runtime-causal-context.js";
+
+const codeFindLiveWorkerTool: ToolDefinition = {
+  ...codeFindTool,
+  createHandler(ctx: ToolContext): ToolHandler {
+    return (args) => runCodeFind(ctx, args, { allowWarp: false });
+  },
+};
+
+const codeShowLiveWorkerTool: ToolDefinition = {
+  ...codeShowTool,
+  createHandler(ctx: ToolContext): ToolHandler {
+    return (args) => runCodeShow(ctx, args, { allowWarp: false });
+  },
+};
+
+const OFFLOADED_REPO_TOOL_DEFINITIONS = Object.freeze({
+  safe_read: safeReadTool,
+  file_outline: fileOutlineTool,
+  changed_since: changedSinceTool,
+  graft_diff: graftDiffTool,
+  graft_since: sinceTool,
+  graft_map: mapTool,
+  code_refs: codeRefsTool,
+  code_find_live: codeFindLiveWorkerTool,
+  code_show_live: codeShowLiveWorkerTool,
+});
+
+export type OffloadedRepoToolName = keyof typeof OFFLOADED_REPO_TOOL_DEFINITIONS;
+
+export const OFFLOADED_DAEMON_REPO_TOOL_NAMES = Object.freeze(
+  Object.keys(OFFLOADED_REPO_TOOL_DEFINITIONS) as OffloadedRepoToolName[],
+);
+
+export interface RepoToolWorkerJob {
+  readonly sessionId: string;
+  readonly workspaceSliceId: string;
+  readonly traceId: string;
+  readonly seq: number;
+  readonly startedAtMs: number;
+  readonly tool: OffloadedRepoToolName;
+  readonly args: Record<string, unknown>;
+  readonly projectRoot: string;
+  readonly graftDir: string;
+  readonly graftignorePatterns: readonly string[];
+  readonly repoId: string;
+  readonly worktreeId: string;
+  readonly gitCommonDir: string;
+  readonly writerId: string;
+  readonly capabilityProfile: WorkspaceCapabilityProfile;
+  readonly repoState: RepoObservation;
+  readonly sessionSnapshot: SessionTrackerSnapshot;
+  readonly metricsSnapshot: MetricsSnapshot;
+  readonly cacheSnapshots?: Readonly<Record<string, ObservationSnapshot>>;
+}
+
+export interface RepoToolWorkerResult {
+  readonly result: McpToolResult;
+  readonly textBytes: number;
+  readonly receipt: McpToolReceipt;
+  readonly tripwireSignals: readonly string[];
+  readonly metricsDelta: MetricsDelta;
+  readonly cacheUpdates: readonly {
+    path: string;
+    observation: ObservationSnapshot | null;
+  }[];
+}
+
+function unsupported(name: string): never {
+  throw new Error(`${name} is not available in repo-tool worker mode`);
+}
+
+function wrapWithPolicyCheck(toolName: ToolDefinition["name"], inner: ToolHandler, ctx: ToolContext): ToolHandler {
+  return async (args: Record<string, unknown>) => {
+    const rawPath = args["path"];
+    if (typeof rawPath !== "string") return inner(args);
+
+    const filePath = ctx.resolvePath(rawPath);
+    let content: string;
+    try {
+      content = await ctx.fs.readFile(filePath, "utf-8");
+    } catch {
+      return inner(args);
+    }
+
+    const actual = { lines: content.split("\n").length, bytes: Buffer.byteLength(content) };
+    const policy = evaluateMcpPolicy(ctx, filePath, actual);
+    if (policy instanceof RefusedResult) {
+      ctx.metrics.recordRefusal();
+      return ctx.respond(toolName, {
+        path: filePath,
+        projection: "refused",
+        reason: policy.reason,
+        reasonDetail: policy.reasonDetail,
+        next: [...policy.next],
+        actual,
+      });
+    }
+    return inner(args);
+  };
+}
+
+function workerStatus(job: RepoToolWorkerJob): WorkspaceStatus {
+  return {
+    sessionMode: "daemon",
+    bindState: "bound",
+    repoId: job.repoId,
+    worktreeId: job.worktreeId,
+    worktreeRoot: job.projectRoot,
+    gitCommonDir: job.gitCommonDir,
+    graftDir: job.graftDir,
+    capabilityProfile: job.capabilityProfile,
+  };
+}
+
+function buildWorkerContext(
+  job: RepoToolWorkerJob,
+): { ctx: ToolContext; metrics: Metrics; session: SessionTracker; takeResponse: () => RepoToolWorkerResult } {
+  const codec = new CanonicalJsonCodec();
+  const session = SessionTracker.fromSnapshot(job.sessionSnapshot);
+  const metrics = Metrics.fromSnapshot(job.metricsSnapshot);
+  const cache = ObservationCache.fromSnapshots(job.cacheSnapshots);
+  const trackedCachePaths = new Set<string>(Object.keys(job.cacheSnapshots ?? {}));
+  if (typeof job.args["path"] === "string") {
+    trackedCachePaths.add(createPathResolver(job.projectRoot)(job.args["path"]));
+  }
+  let response: Omit<RepoToolWorkerResult, "metricsDelta" | "cacheUpdates"> | null = null;
+
+  const ctx: ToolContext = {
+    projectRoot: job.projectRoot,
+    graftDir: job.graftDir,
+    graftignorePatterns: job.graftignorePatterns,
+    session,
+    cache,
+    metrics,
+    fs: nodeFs,
+    codec,
+    process: nodeProcessRunner,
+    git: nodeGit,
+    runCapture: resolveRunCaptureConfig({}),
+    observability: resolveRuntimeObservabilityState({ graftDir: job.graftDir }),
+    respond(tool, data) {
+      const tripwires = session.checkTripwires();
+      const built = buildReceiptResult(tool, data, {
+        sessionId: job.sessionId,
+        traceId: job.traceId,
+        seq: job.seq,
+        latencyMs: Date.now() - job.startedAtMs,
+        codec,
+        metrics: metrics.snapshot(),
+        tripwires,
+        budget: session.getBudget(),
+      });
+      response = {
+        result: built.result,
+        textBytes: built.textBytes,
+        receipt: built.receipt,
+        tripwireSignals: tripwires.map((wire) => wire.signal),
+      };
+      return built.result;
+    },
+    resolvePath: createPathResolver(job.projectRoot),
+    getWarp() {
+      return openWarp({ cwd: job.projectRoot, writerId: job.writerId });
+    },
+    getRepoState() {
+      return job.repoState;
+    },
+    getCausalContext() {
+      return buildRuntimeCausalContext({
+        transportSessionId: job.sessionId,
+        workspaceSliceId: job.workspaceSliceId,
+        repoId: job.repoId,
+        worktreeId: job.worktreeId,
+        checkoutEpoch: job.repoState.checkoutEpoch,
+        warpWriterId: job.writerId,
+      });
+    },
+    getPersistedLocalHistorySummary() {
+      return unsupported("getPersistedLocalHistorySummary");
+    },
+    getPersistedLocalActivityWindow() {
+      return unsupported("getPersistedLocalActivityWindow");
+    },
+    getRepoConcurrencySummary() {
+      return Promise.resolve(null);
+    },
+    getWorkspaceOverlayFooting() {
+      return unsupported("getWorkspaceOverlayFooting");
+    },
+    declareCausalAttach() {
+      return unsupported("declareCausalAttach");
+    },
+    getWorkspaceStatus() {
+      return workerStatus(job);
+    },
+    bindWorkspace() {
+      return unsupported("bindWorkspace");
+    },
+    rebindWorkspace() {
+      return unsupported("rebindWorkspace");
+    },
+    getDaemonStatus() {
+      return unsupported("getDaemonStatus");
+    },
+    listDaemonRepos() {
+      return unsupported("listDaemonRepos");
+    },
+    listDaemonSessions() {
+      return unsupported("listDaemonSessions");
+    },
+    listDaemonMonitors() {
+      return unsupported("listDaemonMonitors");
+    },
+    startMonitor() {
+      return unsupported("startMonitor");
+    },
+    pauseMonitor() {
+      return unsupported("pauseMonitor");
+    },
+    resumeMonitor() {
+      return unsupported("resumeMonitor");
+    },
+    stopMonitor() {
+      return unsupported("stopMonitor");
+    },
+    listWorkspaceAuthorizations() {
+      return unsupported("listWorkspaceAuthorizations");
+    },
+    authorizeWorkspace() {
+      return unsupported("authorizeWorkspace");
+    },
+    revokeWorkspace() {
+      return unsupported("revokeWorkspace");
+    },
+  };
+
+  return {
+    ctx,
+    metrics,
+    session,
+    takeResponse() {
+      if (response === null) {
+        throw new Error(`repo-tool worker ${job.tool} completed without calling respond()`);
+      }
+      return {
+        ...response,
+        metricsDelta: diffMetrics(job.metricsSnapshot, metrics.snapshot()),
+        cacheUpdates: [...trackedCachePaths].map((filePath) => {
+          return {
+            path: filePath,
+            observation: cache.snapshotEntry(filePath),
+          };
+        }),
+      };
+    },
+  };
+}
+
+function resolveRepoToolDefinition(tool: OffloadedRepoToolName): ToolDefinition {
+  return OFFLOADED_REPO_TOOL_DEFINITIONS[tool];
+}
+
+export async function runRepoToolJob(job: RepoToolWorkerJob): Promise<RepoToolWorkerResult> {
+  const definition = resolveRepoToolDefinition(job.tool);
+  const { ctx, takeResponse } = buildWorkerContext(job);
+  const rawHandler = definition.createHandler(ctx);
+  const handler = definition.policyCheck === true ? wrapWithPolicyCheck(definition.name, rawHandler, ctx) : rawHandler;
+
+  if (definition.schema !== undefined) {
+    z.object(definition.schema).strict().parse(job.args);
+  }
+
+  await handler(job.args);
+  return takeResponse();
+}

package/src/mcp/run-capture-config.ts

@@ -0,0 +1,33 @@
+export interface RunCaptureConfig {
+  readonly enabled: boolean;
+  readonly persistLogs: boolean;
+  readonly redactLogs: boolean;
+}
+
+export interface ResolveRunCaptureConfigOptions {
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  readonly overrides?: Partial<RunCaptureConfig>;
+}
+
+function parseBooleanFlag(value: string | undefined, fallback: boolean): boolean {
+  if (value === undefined) return fallback;
+  const normalized = value.trim().toLowerCase();
+  if ([ "0", "false", "no", "off" ].includes(normalized)) return false;
+  if ([ "1", "true", "yes", "on" ].includes(normalized)) return true;
+  return fallback;
+}
+
+export function resolveRunCaptureConfig(
+  options: ResolveRunCaptureConfigOptions = {},
+): RunCaptureConfig {
+  const env = options.env ?? process.env;
+  const base: RunCaptureConfig = {
+    enabled: parseBooleanFlag(env["GRAFT_ENABLE_RUN_CAPTURE"], true),
+    persistLogs: parseBooleanFlag(env["GRAFT_RUN_CAPTURE_PERSIST"], true),
+    redactLogs: parseBooleanFlag(env["GRAFT_RUN_CAPTURE_REDACT"], true),
+  };
+  return {
+    ...base,
+    ...options.overrides,
+  };
+}

package/src/mcp/runtime-causal-context.ts

@@ -0,0 +1,72 @@
+import * as crypto from "node:crypto";
+
+export interface RuntimeCausalContext {
+  readonly transportSessionId: string;
+  readonly workspaceSliceId: string;
+  readonly causalSessionId: string;
+  readonly strandId: string;
+  readonly checkoutEpochId: string;
+  readonly warpWriterId: string;
+  readonly stability: "runtime_local";
+  readonly provenanceLevel: "artifact_history";
+}
+
+function stableId(prefix: string, input: string): string {
+  return `${prefix}:${crypto.createHash("sha256").update(input).digest("hex").slice(0, 16)}`;
+}
+
+export function buildCheckoutEpochId(
+  repoId: string,
+  worktreeId: string,
+  checkoutEpoch: number,
+): string {
+  return stableId("epoch", `${repoId}:${worktreeId}:${String(checkoutEpoch)}`);
+}
+
+export function buildCausalSessionId(
+  repoId: string,
+  worktreeId: string,
+  transportSessionId: string,
+  workspaceSliceId: string,
+): string {
+  return stableId("causal", `${repoId}:${worktreeId}:${transportSessionId}:${workspaceSliceId}`);
+}
+
+export function buildStrandId(
+  causalSessionId: string,
+  checkoutEpochId: string,
+  warpWriterId: string,
+): string {
+  return stableId("strand", `${causalSessionId}:${checkoutEpochId}:${warpWriterId}`);
+}
+
+export function buildRuntimeCausalContext(input: {
+  readonly transportSessionId: string;
+  readonly workspaceSliceId: string;
+  readonly repoId: string;
+  readonly worktreeId: string;
+  readonly checkoutEpoch: number;
+  readonly warpWriterId: string;
+}): RuntimeCausalContext {
+  const checkoutEpochId = buildCheckoutEpochId(
+    input.repoId,
+    input.worktreeId,
+    input.checkoutEpoch,
+  );
+  const causalSessionId = buildCausalSessionId(
+    input.repoId,
+    input.worktreeId,
+    input.transportSessionId,
+    input.workspaceSliceId,
+  );
+  return {
+    transportSessionId: input.transportSessionId,
+    workspaceSliceId: input.workspaceSliceId,
+    causalSessionId,
+    strandId: buildStrandId(causalSessionId, checkoutEpochId, input.warpWriterId),
+    checkoutEpochId,
+    warpWriterId: input.warpWriterId,
+    stability: "runtime_local",
+    provenanceLevel: "artifact_history",
+  };
+}

package/src/mcp/runtime-observability.ts

@@ -0,0 +1,219 @@
+import * as path from "node:path";
+import { ZodError } from "zod";
+import type { JsonCodec } from "../ports/codec.js";
+import type { FileSystem } from "../ports/filesystem.js";
+import type { MetricsSnapshot } from "./metrics.js";
+import type { BurdenKind } from "./burden.js";
+import type { SessionDepth } from "../session/types.js";
+
+export type RuntimeLogPolicy = "metadata_only";
+
+export interface RuntimeObservabilityState {
+  readonly enabled: boolean;
+  readonly logPath: string;
+  readonly maxBytes: number;
+  readonly logPolicy: RuntimeLogPolicy;
+}
+
+export interface ResolveRuntimeObservabilityOptions {
+  readonly graftDir: string;
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  readonly overrides?: Partial<RuntimeObservabilityState>;
+}
+
+const DEFAULT_MAX_BYTES = 1_048_576;
+const DEFAULT_POLICY: RuntimeLogPolicy = "metadata_only";
+
+function parseBooleanFlag(value: string | undefined, fallback: boolean): boolean {
+  if (value === undefined) return fallback;
+  const normalized = value.trim().toLowerCase();
+  if ([ "0", "false", "no", "off" ].includes(normalized)) return false;
+  if ([ "1", "true", "yes", "on" ].includes(normalized)) return true;
+  return fallback;
+}
+
+function parsePositiveInteger(value: string | undefined, fallback: number): number {
+  if (value === undefined) return fallback;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+export function resolveRuntimeObservabilityState(
+  options: ResolveRuntimeObservabilityOptions,
+): RuntimeObservabilityState {
+  const env = options.env ?? process.env;
+  const base: RuntimeObservabilityState = {
+    enabled: parseBooleanFlag(env["GRAFT_ENABLE_MCP_RUNTIME_LOG"], true),
+    logPath: env["GRAFT_MCP_RUNTIME_LOG_PATH"]?.trim() ?? path.join(options.graftDir, "logs", "mcp-runtime.ndjson"),
+    maxBytes: parsePositiveInteger(env["GRAFT_MCP_RUNTIME_LOG_MAX_BYTES"], DEFAULT_MAX_BYTES),
+    logPolicy: DEFAULT_POLICY,
+  };
+  return {
+    ...base,
+    ...options.overrides,
+  };
+}
+
+export interface RuntimeSessionStartedEvent {
+  readonly event: "session_started";
+  readonly sessionId: string;
+  readonly logPath: string;
+  readonly logPolicy: RuntimeLogPolicy;
+}
+
+export interface RuntimeToolCallStartedEvent {
+  readonly event: "tool_call_started";
+  readonly sessionId: string;
+  readonly traceId: string;
+  readonly tool: string;
+  readonly argKeys: readonly string[];
+  readonly sessionDepth: SessionDepth;
+}
+
+export interface RuntimeToolCallCompletedEvent {
+  readonly event: "tool_call_completed";
+  readonly sessionId: string;
+  readonly traceId: string;
+  readonly seq: number;
+  readonly tool: string;
+  readonly latencyMs: number;
+  readonly projection: string;
+  readonly reason: string;
+  readonly burdenKind: BurdenKind;
+  readonly nonReadBurden: boolean;
+  readonly returnedBytes: number;
+  readonly fileBytes: number | null;
+  readonly sessionDepth: SessionDepth;
+  readonly tripwireSignals: readonly string[];
+  readonly metrics: MetricsSnapshot;
+}
+
+export type RuntimeFailureKind = "validation_error" | "tool_error" | "unknown_error";
+
+export interface RuntimeToolCallFailedEvent {
+  readonly event: "tool_call_failed";
+  readonly sessionId: string;
+  readonly traceId: string;
+  readonly tool: string;
+  readonly latencyMs: number;
+  readonly sessionDepth: SessionDepth;
+  readonly argKeys: readonly string[];
+  readonly errorKind: RuntimeFailureKind;
+  readonly errorName: string;
+}
+
+type RuntimeEvent =
+  | RuntimeSessionStartedEvent
+  | RuntimeToolCallStartedEvent
+  | RuntimeToolCallCompletedEvent
+  | RuntimeToolCallFailedEvent;
+
+export interface RuntimeEventLoggerOptions {
+  readonly fs: FileSystem;
+  readonly codec: JsonCodec;
+  readonly logPath: string;
+  readonly maxBytes: number;
+}
+
+export async function ensureGraftDirExcluded(
+  projectRoot: string,
+  graftDir: string,
+  fs: FileSystem,
+): Promise<void> {
+  const relative = path.relative(projectRoot, graftDir);
+  if (relative.length === 0 || relative.startsWith("..") || path.isAbsolute(relative)) {
+    return;
+  }
+
+  const entry = relative.replaceAll(path.sep, "/").replace(/\/?$/, "/");
+  const excludePath = path.join(projectRoot, ".git", "info", "exclude");
+
+  let existing: string;
+  try {
+    existing = fs.readFileSync(excludePath, "utf-8");
+  } catch {
+    return;
+  }
+
+  const entries = existing
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+
+  if (entries.includes(entry)) {
+    return;
+  }
+
+  const prefix = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+  await fs.appendFile(excludePath, `${prefix}${entry}\n`, "utf-8");
+}
+
+export function classifyRuntimeFailure(error: unknown): {
+  kind: RuntimeFailureKind;
+  name: string;
+} {
+  if (error instanceof ZodError) {
+    return { kind: "validation_error", name: error.name };
+  }
+  if (error instanceof Error) {
+    return { kind: "tool_error", name: error.name };
+  }
+  return { kind: "unknown_error", name: "UnknownError" };
+}
+
+export function sanitizeArgKeys(args: Record<string, unknown>): string[] {
+  return Object.keys(args).sort();
+}
+
+export class RuntimeEventLogger {
+  private readonly fs: FileSystem;
+  private readonly codec: JsonCodec;
+  private readonly logPath: string;
+  private readonly maxBytes: number;
+  private queue: Promise<void> = Promise.resolve();
+
+  constructor(options: RuntimeEventLoggerOptions) {
+    this.fs = options.fs;
+    this.codec = options.codec;
+    this.logPath = options.logPath;
+    this.maxBytes = options.maxBytes;
+  }
+
+  log(event: RuntimeEvent): Promise<void> {
+    const prior = this.queue.catch((_error: unknown) => undefined);
+    this.queue = prior
+      .then(async () => {
+        const line = this.codec.encode({ ts: new Date().toISOString(), ...event }) + "\n";
+        const dir = path.dirname(this.logPath);
+        await this.fs.mkdir(dir, { recursive: true });
+        await this.fs.appendFile(this.logPath, line, "utf-8");
+        await this.rotateIfNeeded();
+      });
+    return this.queue;
+  }
+
+  private async rotateIfNeeded(): Promise<void> {
+    let stat: { size: number };
+    try {
+      stat = await this.fs.stat(this.logPath);
+    } catch {
+      return;
+    }
+
+    if (stat.size <= this.maxBytes) {
+      return;
+    }
+
+    const content = await this.fs.readFile(this.logPath, "utf-8");
+    const lines = content.trimEnd().split("\n");
+    let kept = lines.slice(Math.ceil(lines.length / 2));
+    let result = kept.join("\n") + "\n";
+
+    while (Buffer.byteLength(result, "utf-8") > this.maxBytes && kept.length > 1) {
+      kept = kept.slice(Math.ceil(kept.length / 2));
+      result = kept.join("\n") + "\n";
+    }
+
+    await this.fs.writeFile(this.logPath, result, "utf-8");
+  }
+}