@flyingrobots/graft 0.4.0 → 0.6.0

package/src/mcp/repo-tool-worker-context.ts

@@ -0,0 +1,212 @@
+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 { createRepoPathResolver } from "../adapters/repo-paths.js";
+import { openWarp } from "../warp/open.js";
+import { GovernorTracker } from "../session/tracker.js";
+import { RefusedResult } from "../policy/types.js";
+import type { WorkspaceStatus } from "./workspace-router.js";
+import { buildReceiptResult } from "./receipt.js";
+import type { ToolContext, ToolDefinition, ToolHandler } from "./context.js";
+import { Metrics, diffMetrics } from "./metrics.js";
+import { ObservationCache } from "./cache.js";
+import { evaluateMcpPolicy } from "./policy.js";
+import { resolveRunCaptureConfig } from "./run-capture-config.js";
+import { resolveRuntimeObservabilityState } from "./runtime-observability.js";
+import { buildRuntimeCausalContext } from "./runtime-causal-context.js";
+import type { RepoToolWorkerJob, RepoToolWorkerResult } from "./repo-tool-job.js";
+
+function unsupported(name: string): never {
+  throw new Error(`${name} is not available in repo-tool worker mode`);
+}
+
+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,
+  };
+}
+
+export function wrapWithPolicyCheck(
+  toolName: ToolDefinition["name"],
+  inner: ToolHandler,
+): ToolHandler {
+  return async (args: Record<string, unknown>, ctx: ToolContext) => {
+    const rawPath = args["path"];
+    if (typeof rawPath !== "string") return inner(args, ctx);
+
+    const filePath = ctx.resolvePath(rawPath);
+    let content: string;
+    try {
+      content = await ctx.fs.readFile(filePath, "utf-8");
+    } catch {
+      return inner(args, ctx);
+    }
+
+    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, ctx);
+  };
+}
+
+export function buildRepoToolWorkerContext(
+  job: RepoToolWorkerJob,
+): { ctx: ToolContext; takeResponse: () => RepoToolWorkerResult } {
+  const codec = new CanonicalJsonCodec();
+  const governor = GovernorTracker.fromSnapshot(job.governorSnapshot);
+  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(createRepoPathResolver(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,
+    governor,
+    cache,
+    metrics,
+    fs: nodeFs,
+    codec,
+    process: nodeProcessRunner,
+    git: nodeGit,
+    runCapture: resolveRunCaptureConfig({}),
+    observability: resolveRuntimeObservabilityState({ graftDir: job.graftDir }),
+    respond(tool, data) {
+      const tripwires = governor.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: governor.getBudget(),
+      });
+      response = {
+        result: built.result,
+        textBytes: built.textBytes,
+        receipt: built.receipt,
+        tripwireSignals: tripwires.map((wire) => wire.signal),
+      };
+      return built.result;
+    },
+    recordFootprint() {
+      // Worker-thread footprints are not collected — the main thread
+      // captures footprint via AsyncLocalStorage in the invocation engine.
+    },
+    resolvePath: createRepoPathResolver(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,
+    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) => ({
+          path: filePath,
+          observation: cache.snapshotEntry(filePath),
+        })),
+      };
+    },
+  };
+}

package/src/mcp/repo-workspace.ts

@@ -0,0 +1,21 @@
+import { toRepoPolicyPath } from "../adapters/repo-paths.js";
+import { RepoWorkspace } from "../operations/repo-workspace.js";
+import type { ToolContext } from "./context.js";
+
+export function createRepoWorkspaceFromToolContext(
+  ctx: Pick<
+    ToolContext,
+    "projectRoot" | "fs" | "codec" | "graftignorePatterns" | "resolvePath" | "governor" | "cache"
+  >,
+): RepoWorkspace {
+  return new RepoWorkspace({
+    projectRoot: ctx.projectRoot,
+    fs: ctx.fs,
+    codec: ctx.codec,
+    graftignorePatterns: ctx.graftignorePatterns,
+    resolvePath: ctx.resolvePath,
+    toPolicyPath: (resolvedPath) => toRepoPolicyPath(ctx.projectRoot, resolvedPath),
+    governor: ctx.governor,
+    cache: ctx.cache,
+  });
+}

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,217 @@
+import * as path from "node:path";
+import { ZodError } from "zod";
+import { RotatingNdjsonLog } from "../adapters/rotating-ndjson-log.js";
+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 { GovernorDepth } 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: GovernorDepth;
+}
+
+/**
+ * Per-tool-call footprint capturing which files, symbols, and regions
+ * were observed. Enables provenance tracing at sub-file granularity.
+ */
+export interface ToolCallFootprint {
+  /** File paths read or scanned by this tool call. */
+  readonly paths: readonly string[];
+  /** Symbol names inspected (when available from outline/precision tools). */
+  readonly symbols: readonly string[];
+  /** Line regions accessed (when available from read_range). */
+  readonly regions: readonly ToolCallFootprintRegion[];
+}
+
+/** A line region within a specific file. */
+export interface ToolCallFootprintRegion {
+  readonly path: string;
+  readonly startLine: number;
+  readonly endLine: number;
+}
+
+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: GovernorDepth;
+  readonly tripwireSignals: readonly string[];
+  readonly metrics: MetricsSnapshot;
+  /** Optional sub-file footprint for provenance granularity. */
+  readonly footprint?: ToolCallFootprint;
+}
+
+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: GovernorDepth;
+  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 = await fs.readFile(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 { sanitizeArgValues } from "./secret-scrub.js";
+
+export function sanitizeArgKeys(args: Record<string, unknown>): string[] {
+  return Object.keys(args).sort();
+}
+
+export class RuntimeEventLogger {
+  private readonly logWriter: RotatingNdjsonLog;
+  private queue: Promise<void> = Promise.resolve();
+
+  constructor(options: RuntimeEventLoggerOptions) {
+    this.logWriter = new RotatingNdjsonLog({
+      fs: options.fs,
+      codec: options.codec,
+      logPath: options.logPath,
+      maxBytes: options.maxBytes,
+    });
+  }
+
+  log(event: RuntimeEvent): Promise<void> {
+    const prior = this.queue.catch((_error: unknown) => undefined);
+    this.queue = prior
+      .then(async () => {
+        await this.logWriter.append({
+          ts: new Date().toISOString(),
+          ...event,
+        });
+      });
+    return this.queue;
+  }
+}