@flyingrobots/graft 0.7.0 → 0.7.1

package/src/mcp/runtime-observability.ts

@@ -1,217 +0,0 @@
-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;
-  }
-}

package/src/mcp/runtime-staged-target.ts

@@ -1,161 +0,0 @@
-import * as crypto from "node:crypto";
-import type { AttributionSummary, StagedTarget } from "../contracts/causal-ontology.js";
-import type { RepoObservation } from "./repo-state.js";
-import type { RuntimeCausalContext } from "./runtime-causal-context.js";
-import type { WorkspaceStatus } from "./workspace-router.js";
-
-const FULL_FILE_SAFE_STATUSES = new Set(["A", "D", "R", "C", "T"]);
-
-export interface RuntimeStagedTargetNone {
-  readonly availability: "none";
-  readonly stability: "runtime_local";
-  readonly provenanceLevel: "artifact_history";
-}
-
-export interface RuntimeStagedTargetFullFile {
-  readonly availability: "full_file";
-  readonly stability: "runtime_local";
-  readonly provenanceLevel: "artifact_history";
-  readonly attribution: AttributionSummary;
-  readonly target: StagedTarget;
-}
-
-export interface RuntimeStagedTargetAmbiguous {
-  readonly availability: "ambiguous";
-  readonly stability: "runtime_local";
-  readonly provenanceLevel: "artifact_history";
-  readonly attribution: AttributionSummary;
-  readonly reason:
-    | "missing_head_commit"
-    | "missing_workspace_overlay"
-    | "modified_path_selection_requires_deeper_evidence";
-  readonly observedStagedPaths: number;
-  readonly ambiguousPaths: readonly string[];
-}
-
-export type RuntimeStagedTarget =
-  | RuntimeStagedTargetNone
-  | RuntimeStagedTargetFullFile
-  | RuntimeStagedTargetAmbiguous;
-
-interface MergedStatusEntry {
-  readonly path: string;
-  readonly stagedStatus: string;
-  readonly worktreeStatus: string;
-}
-
-function stableId(prefix: string, input: string): string {
-  return `${prefix}:${crypto.createHash("sha256").update(input).digest("hex").slice(0, 16)}`;
-}
-
-function parseMergedStatusLine(line: string): MergedStatusEntry | null {
-  if (line.length < 4) return null;
-  return {
-    stagedStatus: line[0] ?? " ",
-    worktreeStatus: line[1] ?? " ",
-    path: line.slice(3),
-  };
-}
-
-function stagedEntries(statusLines: readonly string[]): readonly MergedStatusEntry[] {
-  return statusLines
-    .map(parseMergedStatusLine)
-    .filter((entry): entry is MergedStatusEntry => entry !== null && entry.stagedStatus !== " " && entry.stagedStatus !== "?");
-}
-
-function isFullFileSafe(entry: MergedStatusEntry): boolean {
-  return entry.worktreeStatus === " " && FULL_FILE_SAFE_STATUSES.has(entry.stagedStatus);
-}
-
-export function buildRuntimeStagedTarget(
-  status: WorkspaceStatus,
-  causalContext: RuntimeCausalContext,
-  repoState: RepoObservation,
-  attribution: AttributionSummary,
-): RuntimeStagedTarget {
-  const observedEntries = stagedEntries(repoState.statusLines);
-  if (observedEntries.length === 0) {
-    return {
-      availability: "none",
-      stability: "runtime_local",
-      provenanceLevel: "artifact_history",
-    };
-  }
-
-  if (repoState.headSha === null) {
-    return {
-      availability: "ambiguous",
-      stability: "runtime_local",
-      provenanceLevel: "artifact_history",
-      attribution,
-      reason: "missing_head_commit",
-      observedStagedPaths: observedEntries.length,
-      ambiguousPaths: observedEntries.map((entry) => entry.path),
-    };
-  }
-
-  if (repoState.workspaceOverlayId === null || status.repoId === null || status.worktreeId === null) {
-    return {
-      availability: "ambiguous",
-      stability: "runtime_local",
-      provenanceLevel: "artifact_history",
-      attribution,
-      reason: "missing_workspace_overlay",
-      observedStagedPaths: observedEntries.length,
-      ambiguousPaths: observedEntries.map((entry) => entry.path),
-    };
-  }
-
-  const ambiguousEntries = observedEntries.filter((entry) => !isFullFileSafe(entry));
-  if (ambiguousEntries.length > 0) {
-    return {
-      availability: "ambiguous",
-      stability: "runtime_local",
-      provenanceLevel: "artifact_history",
-      attribution,
-      reason: "modified_path_selection_requires_deeper_evidence",
-      observedStagedPaths: observedEntries.length,
-      ambiguousPaths: ambiguousEntries.map((entry) => entry.path),
-    };
-  }
-
-  const selectionEntries = observedEntries.map((entry) => ({
-    path: entry.path,
-    symbols: [],
-    regions: [],
-  }));
-
-  const target: StagedTarget = {
-    targetId: stableId(
-      "target",
-      JSON.stringify({
-        repoId: status.repoId,
-        worktreeId: status.worktreeId,
-        checkoutEpochId: causalContext.checkoutEpochId,
-        workspaceOverlayId: repoState.workspaceOverlayId,
-        headSha: repoState.headSha,
-        paths: selectionEntries.map((entry) => entry.path),
-      }),
-    ),
-    targetKind: "staged_target",
-    repoId: status.repoId,
-    worktreeId: status.worktreeId,
-    checkoutEpochId: causalContext.checkoutEpochId,
-    workspaceOverlayId: repoState.workspaceOverlayId,
-    selectedAt: repoState.observedAt,
-    selectionKind: "full_file",
-    selectionEntries,
-    base: {
-      headCommitSha: repoState.headSha,
-      indexTreeSha: null,
-    },
-  };
-
-  return {
-    availability: "full_file",
-    stability: "runtime_local",
-    provenanceLevel: "artifact_history",
-    attribution,
-    target,
-  };
-}

package/src/mcp/runtime-workspace-overlay.ts

@@ -1,255 +0,0 @@
-import * as path from "node:path";
-import type { FileSystem } from "../ports/filesystem.js";
-import type { GitClient } from "../ports/git.js";
-import {
-  isRecognizedTargetGitHook,
-  isTargetGitTransitionHookName,
-  resolveGitHooksPath,
-  TARGET_GIT_TRANSITION_HOOKS,
-} from "../git/target-git-hook-bootstrap.js";
-import type {
-  RepoTransition,
-  WorkspaceOverlaySummary,
-} from "./repo-state.js";
-
-export type GitHookBootstrapPosture = "absent" | "external_unknown" | "installed";
-export type WorkspaceOverlayObservationMode =
-  | "inferred_between_tool_calls"
-  | "hook_observed_checkout_boundaries";
-export type WorkspaceOverlayLineagePosture =
-  | "stable"
-  | "forked_after_transition";
-export type WorkspaceOverlayBoundaryAuthority =
-  | "none"
-  | "repo_snapshot"
-  | "hook_observed";
-export type WorkspaceOverlayDegradedReason =
-  | "target_repo_hooks_absent"
-  | "target_repo_hooks_unrecognized"
-  | "local_edit_watchers_absent";
-
-export interface GitTransitionHookEvent {
-  readonly hookName: (typeof TARGET_GIT_TRANSITION_HOOKS)[number];
-  readonly hookArgs: readonly string[];
-  readonly worktreeRoot: string;
-  readonly observedAt: string;
-}
-
-export interface GitHookBootstrapStatus {
-  readonly posture: GitHookBootstrapPosture;
-  readonly configuredCoreHooksPath: string | null;
-  readonly resolvedHooksPath: string;
-  readonly requiredHooks: readonly string[];
-  readonly presentHooks: readonly string[];
-  readonly missingHooks: readonly string[];
-  readonly supportsCheckoutBoundaries: boolean;
-}
-
-export interface RuntimeWorkspaceOverlayFooting {
-  readonly observationMode: WorkspaceOverlayObservationMode;
-  readonly lineagePosture: WorkspaceOverlayLineagePosture;
-  readonly boundaryAuthority: WorkspaceOverlayBoundaryAuthority;
-  readonly degraded: true;
-  readonly degradedReason: WorkspaceOverlayDegradedReason;
-  readonly checkoutEpoch: number;
-  readonly lastTransition: RepoTransition | null;
-  readonly workspaceOverlayId: string | null;
-  readonly workspaceOverlay: WorkspaceOverlaySummary | null;
-  readonly hookBootstrap: GitHookBootstrapStatus;
-  readonly latestHookEvent: GitTransitionHookEvent | null;
-}
-
-async function readGitConfig(
-  gitClient: GitClient,
-  cwd: string,
-  key: string,
-): Promise<string | null> {
-  const result = await gitClient.run({
-    args: ["config", "--get", key],
-    cwd,
-  });
-  if (result.status !== 0) {
-    return null;
-  }
-  const value = result.stdout.trim();
-  return value.length > 0 ? value : null;
-}
-
-async function fileExists(fs: FileSystem, targetPath: string): Promise<boolean> {
-  try {
-    await fs.readFile(targetPath, "utf-8");
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function equivalentWorktreeRoots(left: string, right: string): boolean {
-  const leftResolved = path.resolve(left);
-  const rightResolved = path.resolve(right);
-  if (leftResolved === rightResolved) {
-    return true;
-  }
-  return (
-    leftResolved === `/private${rightResolved}`
-    || rightResolved === `/private${leftResolved}`
-  );
-}
-
-function parseHookEventLine(
-  line: string,
-  worktreeRoot: string,
-): GitTransitionHookEvent | null {
-  try {
-    const parsed = JSON.parse(line) as Record<string, unknown>;
-    const hookName = parsed["hookName"];
-    const hookArgs = parsed["hookArgs"];
-    const observedAt = parsed["observedAt"];
-    const observedWorktreeRoot = parsed["worktreeRoot"];
-    if (
-      typeof hookName !== "string"
-      || !isTargetGitTransitionHookName(hookName)
-      || !Array.isArray(hookArgs)
-      || !hookArgs.every((value) => typeof value === "string")
-      || typeof observedAt !== "string"
-      || typeof observedWorktreeRoot !== "string"
-      || !equivalentWorktreeRoots(observedWorktreeRoot, worktreeRoot)
-    ) {
-      return null;
-    }
-    return {
-      hookName,
-      hookArgs,
-      worktreeRoot: observedWorktreeRoot,
-      observedAt,
-    };
-  } catch {
-    return null;
-  }
-}
-
-async function readLatestHookEvent(
-  fs: FileSystem,
-  worktreeRoot: string,
-): Promise<GitTransitionHookEvent | null> {
-  const logPath = path.join(worktreeRoot, ".graft", "runtime", "git-transitions.ndjson");
-  try {
-    const content = await fs.readFile(logPath, "utf-8");
-    const lines = content.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.length > 0);
-    for (let index = lines.length - 1; index >= 0; index -= 1) {
-      const line = lines[index];
-      if (line === undefined) continue;
-      const parsed = parseHookEventLine(line, worktreeRoot);
-      if (parsed !== null) {
-        return parsed;
-      }
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
-export async function inspectGitHookBootstrap(
-  fs: FileSystem,
-  gitClient: GitClient,
-  worktreeRoot: string,
-  gitCommonDir: string,
-): Promise<GitHookBootstrapStatus> {
-  const configuredCoreHooksPath = await readGitConfig(
-    gitClient,
-    worktreeRoot,
-    "core.hooksPath",
-  );
-  const resolvedHooksPath = resolveGitHooksPath(
-    worktreeRoot,
-    gitCommonDir,
-    configuredCoreHooksPath,
-  );
-
-  const presentHooks: string[] = [];
-  const missingHooks: string[] = [];
-  let recognizedHooks = 0;
-  let externalHooks = 0;
-  for (const hookName of TARGET_GIT_TRANSITION_HOOKS) {
-    const hookPath = path.join(resolvedHooksPath, hookName);
-    if (await fileExists(fs, hookPath)) {
-      presentHooks.push(hookName);
-      try {
-        const content = await fs.readFile(hookPath, "utf-8");
-        if (isRecognizedTargetGitHook(content, hookName)) {
-          recognizedHooks += 1;
-        } else {
-          externalHooks += 1;
-        }
-      } catch {
-        externalHooks += 1;
-      }
-    } else {
-      missingHooks.push(hookName);
-    }
-  }
-
-  const allHooksInstalled = recognizedHooks === TARGET_GIT_TRANSITION_HOOKS.length;
-  return {
-    posture: allHooksInstalled
-      ? "installed"
-      : (presentHooks.length === 0 ? "absent" : "external_unknown"),
-    configuredCoreHooksPath,
-    resolvedHooksPath,
-    requiredHooks: [...TARGET_GIT_TRANSITION_HOOKS],
-    presentHooks,
-    missingHooks,
-    supportsCheckoutBoundaries: allHooksInstalled && externalHooks === 0,
-  };
-}
-
-export async function buildRuntimeWorkspaceOverlayFooting(
-  fs: FileSystem,
-  gitClient: GitClient,
-  worktreeRoot: string,
-  gitCommonDir: string,
-  repoState: {
-    readonly checkoutEpoch: number;
-    readonly lastTransition: RepoTransition | null;
-    readonly workspaceOverlayId: string | null;
-    readonly workspaceOverlay: WorkspaceOverlaySummary | null;
-  },
-): Promise<RuntimeWorkspaceOverlayFooting> {
-  const hookBootstrap = await inspectGitHookBootstrap(
-    fs,
-    gitClient,
-    worktreeRoot,
-    gitCommonDir,
-  );
-  const latestHookEvent = hookBootstrap.supportsCheckoutBoundaries
-    ? await readLatestHookEvent(fs, worktreeRoot)
-    : null;
-  const lineagePosture = repoState.checkoutEpoch > 0 || latestHookEvent !== null || repoState.lastTransition !== null
-    ? "forked_after_transition"
-    : "stable";
-  const boundaryAuthority = latestHookEvent !== null
-    ? "hook_observed"
-    : (repoState.lastTransition !== null || repoState.checkoutEpoch > 0
-        ? "repo_snapshot"
-        : "none");
-  return {
-    observationMode: latestHookEvent === null
-      ? "inferred_between_tool_calls"
-      : "hook_observed_checkout_boundaries",
-    lineagePosture,
-    boundaryAuthority,
-    degraded: true,
-    degradedReason: hookBootstrap.supportsCheckoutBoundaries
-      ? "local_edit_watchers_absent"
-      : (hookBootstrap.posture === "absent"
-          ? "target_repo_hooks_absent"
-          : "target_repo_hooks_unrecognized"),
-    checkoutEpoch: repoState.checkoutEpoch,
-    lastTransition: repoState.lastTransition,
-    workspaceOverlayId: repoState.workspaceOverlayId,
-    workspaceOverlay: repoState.workspaceOverlay,
-    hookBootstrap,
-    latestHookEvent,
-  };
-}