@flyingrobots/graft 0.4.0 → 0.6.0

package/src/mcp/repo-state-transition.ts

@@ -0,0 +1,151 @@
+import type { GitClient } from "../ports/git.js";
+import type { RepoSnapshot, RepoTransition } from "./repo-state-types.js";
+import { isAncestor } from "./repo-state-git.js";
+
+function samePosition(a: RepoSnapshot, b: RepoSnapshot): boolean {
+  return a.headRef === b.headRef && a.headSha === b.headSha;
+}
+
+function parseCheckoutTarget(value: string): string | null {
+  if (/^[0-9a-f]{7,40}$/i.test(value)) {
+    return null;
+  }
+  return value;
+}
+
+function parseTransitionFromReflog(
+  previous: RepoSnapshot,
+  current: RepoSnapshot,
+  bootstrapTimestampSec: number,
+  allowBootstrap: boolean,
+): RepoTransition | null {
+  const entry = current.headReflog;
+  if (entry === null) {
+    return null;
+  }
+  const hasFreshReflog = previous.headReflog?.raw !== entry.raw;
+  const bootstrapEligible = allowBootstrap && entry.timestampSec !== null && entry.timestampSec >= bootstrapTimestampSec;
+  if (!hasFreshReflog && !bootstrapEligible) {
+    return null;
+  }
+
+  const checkout = /^checkout: moving from (.+) to (.+)$/.exec(entry.subject);
+  if (checkout !== null) {
+    const fromRef = checkout[1];
+    const toTarget = checkout[2];
+    if (fromRef === undefined || toTarget === undefined) {
+      return null;
+    }
+    const toRef = parseCheckoutTarget(toTarget);
+    return {
+      kind: "checkout",
+      fromRef,
+      toRef,
+      fromCommit: entry.previousSha,
+      toCommit: entry.nextSha ?? current.headSha,
+      evidence: { reflogSubject: entry.subject },
+    };
+  }
+
+  const merge = /^merge ([^:]+):/.exec(entry.subject);
+  if (merge !== null) {
+    const fromRef = merge[1];
+    if (fromRef === undefined) {
+      return null;
+    }
+    return {
+      kind: "merge",
+      fromRef,
+      toRef: current.headRef,
+      fromCommit: entry.previousSha,
+      toCommit: entry.nextSha ?? current.headSha,
+      evidence: { reflogSubject: entry.subject },
+    };
+  }
+
+  if (entry.subject.startsWith("reset: ")) {
+    return {
+      kind: "reset",
+      fromRef: previous.headRef,
+      toRef: current.headRef,
+      fromCommit: entry.previousSha,
+      toCommit: entry.nextSha ?? current.headSha,
+      evidence: { reflogSubject: entry.subject },
+    };
+  }
+
+  if (entry.subject.startsWith("rebase (")) {
+    return {
+      kind: "rebase",
+      fromRef: previous.headRef,
+      toRef: current.headRef,
+      fromCommit: entry.previousSha,
+      toCommit: entry.nextSha ?? current.headSha,
+      evidence: { reflogSubject: entry.subject },
+    };
+  }
+
+  return null;
+}
+
+export async function detectTransition(
+  gitClient: GitClient,
+  cwd: string,
+  previous: RepoSnapshot,
+  current: RepoSnapshot,
+  bootstrapTimestampSec: number,
+  allowBootstrap: boolean,
+): Promise<RepoTransition | null> {
+  const reflogTransition = parseTransitionFromReflog(previous, current, bootstrapTimestampSec, allowBootstrap);
+  if (reflogTransition !== null) {
+    return reflogTransition;
+  }
+
+  if (samePosition(previous, current)) return null;
+
+  if (previous.headRef !== current.headRef) {
+    return {
+      kind: "checkout",
+      fromRef: previous.headRef,
+      toRef: current.headRef,
+      fromCommit: previous.headSha,
+      toCommit: current.headSha,
+      evidence: { reflogSubject: null },
+    };
+  }
+
+  if (current.parentShas.length > 1 && previous.headSha !== null && current.parentShas.includes(previous.headSha)) {
+    return {
+      kind: "merge",
+      fromRef: previous.headRef,
+      toRef: current.headRef,
+      fromCommit: previous.headSha,
+      toCommit: current.headSha,
+      evidence: { reflogSubject: null },
+    };
+  }
+
+  if (await isAncestor(gitClient, cwd, current.headSha, previous.headSha)) {
+    return {
+      kind: "reset",
+      fromRef: previous.headRef,
+      toRef: current.headRef,
+      fromCommit: previous.headSha,
+      toCommit: current.headSha,
+      evidence: { reflogSubject: null },
+    };
+  }
+
+  if (!(await isAncestor(gitClient, cwd, previous.headSha, current.headSha))) {
+    return {
+      kind: "rebase",
+      fromRef: previous.headRef,
+      toRef: current.headRef,
+      fromCommit: previous.headSha,
+      toCommit: current.headSha,
+      evidence: { reflogSubject: null },
+    };
+  }
+
+  return null;
+}

package/src/mcp/repo-state-types.ts

@@ -0,0 +1,107 @@
+export type WorldlineLayer = "commit_worldline" | "ref_view" | "workspace_overlay";
+export type RepoTransitionKind = "checkout" | "reset" | "merge" | "rebase";
+export type RepoSemanticTransitionKind =
+  | "index_update"
+  | "conflict_resolution"
+  | "merge_phase"
+  | "rebase_phase"
+  | "bulk_transition"
+  | "unknown";
+export type RepoSemanticTransitionAuthority =
+  | "authoritative_git_state"
+  | "repo_snapshot";
+export type RepoSemanticTransitionPhase =
+  | "started"
+  | "conflicted"
+  | "resolved_waiting_commit"
+  | "continued"
+  | "completed_or_cleared";
+
+export interface RepoTransition {
+  readonly kind: RepoTransitionKind;
+  readonly fromRef: string | null;
+  readonly toRef: string | null;
+  readonly fromCommit: string | null;
+  readonly toCommit: string | null;
+  readonly evidence: {
+    readonly reflogSubject: string | null;
+  };
+}
+
+export interface RepoSemanticTransition {
+  readonly kind: RepoSemanticTransitionKind;
+  readonly authority: RepoSemanticTransitionAuthority;
+  readonly phase: RepoSemanticTransitionPhase | null;
+  readonly summary: string;
+  readonly evidence: {
+    readonly totalPaths: number;
+    readonly stagedPaths: number;
+    readonly changedPaths: number;
+    readonly untrackedPaths: number;
+    readonly unmergedPaths: number;
+    readonly mergeInProgress: boolean;
+    readonly rebaseInProgress: boolean;
+    readonly rebaseStep: number | null;
+    readonly rebaseTotalSteps: number | null;
+    readonly lastTransitionKind: RepoTransitionKind | null;
+    readonly reflogSubject: string | null;
+  };
+}
+
+export interface WorkspaceOverlaySummary {
+  readonly dirty: true;
+  readonly totalPaths: number;
+  readonly stagedPaths: number;
+  readonly changedPaths: number;
+  readonly untrackedPaths: number;
+  readonly actorGuess: "unknown";
+  readonly confidence: "low";
+  readonly evidence: {
+    readonly source: "git status --porcelain";
+    readonly reflogSubject: string | null;
+    readonly sample: readonly string[];
+  };
+}
+
+export interface RepoObservation {
+  readonly checkoutEpoch: number;
+  readonly headRef: string | null;
+  readonly headSha: string | null;
+  readonly dirty: boolean;
+  readonly observedAt: string;
+  readonly lastTransition: RepoTransition | null;
+  readonly semanticTransition: RepoSemanticTransition | null;
+  readonly workspaceOverlayId: string | null;
+  readonly workspaceOverlay: WorkspaceOverlaySummary | null;
+  readonly statusLines: readonly string[];
+}
+
+export interface RebaseProgressState {
+  readonly inProgress: boolean;
+  readonly step: number | null;
+  readonly total: number | null;
+}
+
+export interface RepoSnapshot {
+  readonly headRef: string | null;
+  readonly headSha: string | null;
+  readonly parentShas: readonly string[];
+  readonly observedAt: string;
+  readonly statusLines: readonly string[];
+  readonly dirty: boolean;
+  readonly stagedPaths: number;
+  readonly changedPaths: number;
+  readonly untrackedPaths: number;
+  readonly unmergedPaths: number;
+  readonly mergeInProgress: boolean;
+  readonly rebase: RebaseProgressState;
+  readonly headReflog: HeadReflogEntry | null;
+}
+
+export interface HeadReflogEntry {
+  readonly raw: string;
+  readonly previousSha: string | null;
+  readonly nextSha: string | null;
+  readonly timestampSec: number | null;
+  readonly subject: string;
+}

package/src/mcp/repo-state.ts

@@ -0,0 +1,146 @@
+import type { GitClient } from "../ports/git.js";
+import type { FileSystem } from "../ports/filesystem.js";
+import type { RepoObservation, RepoSnapshot } from "./repo-state-types.js";
+import { captureSnapshot } from "./repo-state-git.js";
+import { detectTransition } from "./repo-state-transition.js";
+import { buildObservation, buildSemanticTransition } from "./repo-state-observation.js";
+
+// Re-export all public types and interfaces for downstream consumers.
+export type {
+  WorldlineLayer,
+  RepoTransitionKind,
+  RepoSemanticTransitionKind,
+  RepoSemanticTransitionAuthority,
+  RepoSemanticTransitionPhase,
+  RepoTransition,
+  RepoSemanticTransition,
+  WorkspaceOverlaySummary,
+  RepoObservation,
+} from "./repo-state-types.js";
+
+/**
+ * Default debounce window in milliseconds for coalescing rapid observe() calls.
+ * Set to 0 (disabled) by default — callers opt in via constructor options.
+ */
+const DEFAULT_OBSERVE_DEBOUNCE_MS = 0;
+
+export class RepoStateTracker {
+  private checkoutEpoch = 0;
+  private snapshot: RepoSnapshot | null = null;
+  private observation: RepoObservation = {
+    checkoutEpoch: 0,
+    headRef: null,
+    headSha: null,
+    dirty: false,
+    observedAt: new Date(0).toISOString(),
+    lastTransition: null,
+    semanticTransition: null,
+    workspaceOverlayId: null,
+    workspaceOverlay: null,
+    statusLines: [],
+  };
+  private initialization: Promise<void> | null = null;
+  private readonly startedAtSec = Math.floor(Date.now() / 1000);
+  private hasObservedTransition = false;
+
+  /** Pending observe promise used for debounce coalescing. */
+  private pendingObserve: Promise<RepoObservation> | null = null;
+  /** Timestamp of the last completed observation (ms since epoch). */
+  private lastObservedAtMs = 0;
+
+  private readonly debounceMs: number;
+
+  constructor(
+    private readonly cwd: string,
+    private readonly fs: FileSystem,
+    private readonly gitClient: GitClient,
+    options?: { debounceMs?: number },
+  ) {
+    this.debounceMs = options?.debounceMs ?? DEFAULT_OBSERVE_DEBOUNCE_MS;
+  }
+
+  /**
+   * Observe the current repo state.
+   *
+   * If another observe() call is already in flight, this returns the same
+   * pending result (coalescing). If a previous observation completed within
+   * the debounce window, the cached result is returned immediately without
+   * spawning new git processes.
+   */
+  async observe(): Promise<RepoObservation> {
+    // Coalesce: reuse an in-flight observation.
+    if (this.pendingObserve !== null) {
+      return this.pendingObserve;
+    }
+
+    // Debounce: return cached result if the last observation is fresh.
+    const elapsed = Date.now() - this.lastObservedAtMs;
+    if (this.lastObservedAtMs > 0 && elapsed < this.debounceMs) {
+      return this.observation;
+    }
+
+    this.pendingObserve = this.performObserve();
+
+    try {
+      return await this.pendingObserve;
+    } finally {
+      this.pendingObserve = null;
+    }
+  }
+
+  async initialize(): Promise<void> {
+    if (this.initialization !== null) {
+      await this.initialization;
+      return;
+    }
+
+    this.initialization = (async () => {
+      const snapshot = await captureSnapshot(this.cwd, this.fs, this.gitClient);
+      this.snapshot = snapshot;
+      this.observation = buildObservation(
+        snapshot,
+        this.checkoutEpoch,
+        null,
+        buildSemanticTransition(null, snapshot, null),
+      );
+    })();
+
+    await this.initialization;
+  }
+
+  getState(): RepoObservation {
+    return this.observation;
+  }
+
+  /** Core observation logic, separated from debounce/coalesce control. */
+  private async performObserve(): Promise<RepoObservation> {
+    await this.initialize();
+    const previousSnapshot = this.snapshot;
+    if (previousSnapshot === null) {
+      return this.observation;
+    }
+    const nextSnapshot = await captureSnapshot(this.cwd, this.fs, this.gitClient);
+    const transition = await detectTransition(
+      this.gitClient,
+      this.cwd,
+      previousSnapshot,
+      nextSnapshot,
+      this.startedAtSec,
+      !this.hasObservedTransition,
+    );
+    if (transition !== null) {
+      this.checkoutEpoch++;
+      this.hasObservedTransition = true;
+    }
+
+    this.snapshot = nextSnapshot;
+    this.observation = buildObservation(
+      nextSnapshot,
+      this.checkoutEpoch,
+      transition ?? this.observation.lastTransition,
+      buildSemanticTransition(previousSnapshot, nextSnapshot, transition),
+    );
+    this.lastObservedAtMs = Date.now();
+    return this.observation;
+  }
+}

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

@@ -0,0 +1,102 @@
+import { z } from "zod";
+import type { GovernorTrackerSnapshot } from "../session/tracker.js";
+import type { McpToolReceipt, McpToolResult } from "./receipt.js";
+import type { ToolDefinition, ToolHandler } from "./context.js";
+import type { MetricsDelta, MetricsSnapshot } from "./metrics.js";
+import type { ObservationSnapshot } from "./cache.js";
+import type { RepoObservation } from "./repo-state.js";
+import type { WorkspaceCapabilityProfile } from "./workspace-router.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 { buildRepoToolWorkerContext, wrapWithPolicyCheck } from "./repo-tool-worker-context.js";
+
+const codeFindLiveWorkerTool: ToolDefinition = {
+  ...codeFindTool,
+  createHandler(): ToolHandler {
+    return (args, ctx) => runCodeFind(ctx, args, { allowWarp: false });
+  },
+};
+
+const codeShowLiveWorkerTool: ToolDefinition = {
+  ...codeShowTool,
+  createHandler(): ToolHandler {
+    return (args, ctx) => 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 governorSnapshot: GovernorTrackerSnapshot;
+  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 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 } = buildRepoToolWorkerContext(job);
+  const rawHandler = definition.createHandler();
+  const handler = definition.policyCheck === true ? wrapWithPolicyCheck(definition.name, rawHandler) : rawHandler;
+
+  if (definition.schema !== undefined) {
+    z.object(definition.schema).strict().parse(job.args);
+  }
+
+  await handler(job.args, ctx);
+  return takeResponse();
+}