@flyingrobots/graft 0.4.0 → 0.6.0

package/src/mcp/workspace-read-observation.ts

@@ -0,0 +1,103 @@
+import * as path from "node:path";
+import type { JsonObject } from "../contracts/json-object.js";
+import type { WorkspaceExecutionContext } from "./workspace-router-model.js";
+import {
+  parseAttributedReadArgs,
+  parseFileOutlineObservationResult,
+  parseReadRangeObservationResult,
+  parseSafeReadObservationResult,
+} from "./workspace-read-observation-model.js";
+
+export type AttributedReadToolName = "safe_read" | "file_outline" | "read_range";
+
+export function buildWorkspaceReadObservation(
+  execution: WorkspaceExecutionContext,
+  toolName: AttributedReadToolName,
+  args: JsonObject,
+  result: JsonObject,
+): {
+  readonly surface: string;
+  readonly projection: string;
+  readonly sourceLayer: "canonical_structural_truth" | "workspace_overlay";
+  readonly reason: string;
+  readonly footprint: {
+    readonly paths: string[];
+    readonly symbols: string[];
+    readonly regions: {
+      readonly path: string;
+      readonly startLine: number;
+      readonly endLine: number;
+    }[];
+  };
+} | null {
+  const parsedArgs = parseAttributedReadArgs(args);
+  if (parsedArgs === null) {
+    return null;
+  }
+
+  const absolutePath = execution.resolvePath(parsedArgs.path);
+  const relativePath = path.relative(execution.worktreeRoot, absolutePath);
+  const footprintPath = relativePath.startsWith("..") ? absolutePath : relativePath;
+  const sourceLayer = execution.repoState.getState().workspaceOverlayId === null
+    ? "canonical_structural_truth"
+    : "workspace_overlay";
+
+  if (toolName === "safe_read") {
+    const parsedResult = parseSafeReadObservationResult(result);
+    if (parsedResult === null) {
+      return null;
+    }
+    return {
+      surface: "safe_read",
+      projection: parsedResult.projection,
+      sourceLayer,
+      reason: parsedResult.reason ?? "SAFE_READ",
+      footprint: {
+        paths: [footprintPath],
+        symbols: [],
+        regions: [],
+      },
+    };
+  }
+
+  if (toolName === "file_outline") {
+    const parsedResult = parseFileOutlineObservationResult(result);
+    if (parsedResult === null) {
+      return null;
+    }
+    if (typeof parsedResult.error === "string" || parsedResult.reason === "UNSUPPORTED_LANGUAGE") {
+      return null;
+    }
+    return {
+      surface: "file_outline",
+      projection: "outline",
+      sourceLayer,
+      reason: parsedResult.reason ?? "FILE_OUTLINE",
+      footprint: {
+        paths: [footprintPath],
+        symbols: [],
+        regions: [],
+      },
+    };
+  }
+
+  const parsedResult = parseReadRangeObservationResult(result);
+  if (parsedResult === null) {
+    return null;
+  }
+  return {
+    surface: "read_range",
+    projection: "content",
+    sourceLayer,
+    reason: parsedResult.reason ?? "READ_RANGE",
+    footprint: {
+      paths: [footprintPath],
+      symbols: [],
+      regions: [{
+        path: footprintPath,
+        startLine: parsedResult.startLine,
+        endLine: parsedResult.endLine,
+      }],
+    },
+  };
+}

package/src/mcp/workspace-router-capability.ts

@@ -0,0 +1,32 @@
+// ---------------------------------------------------------------------------
+// workspace-router-capability — capability profile resolution for binding
+//
+// Determines which capability profile applies when a workspace is bound,
+// whether in repo_local mode (always the local profile) or daemon mode
+// (delegated to the authorization policy).
+// ---------------------------------------------------------------------------
+import {
+  DEFAULT_REPO_LOCAL_CAPABILITY_PROFILE,
+  type ResolvedWorkspace,
+  type WorkspaceAuthorizationPolicy,
+  type WorkspaceCapabilityProfile,
+  type WorkspaceMode,
+} from "./workspace-router-model.js";
+
+/**
+ * Resolve the capability profile for a workspace binding attempt.
+ *
+ * In `repo_local` mode the default local profile is always returned.
+ * In `daemon` mode the authorization policy is consulted; `null` means
+ * the workspace is not authorized.
+ */
+export async function resolveCapabilityProfile(input: {
+  readonly mode: WorkspaceMode;
+  readonly resolved: ResolvedWorkspace;
+  readonly authorizationPolicy?: WorkspaceAuthorizationPolicy | undefined;
+}): Promise<WorkspaceCapabilityProfile | null> {
+  if (input.mode === "repo_local") {
+    return DEFAULT_REPO_LOCAL_CAPABILITY_PROFILE;
+  }
+  return (await input.authorizationPolicy?.getCapabilityProfile(input.resolved)) ?? null;
+}

package/src/mcp/workspace-router-history.ts

@@ -0,0 +1,233 @@
+// ---------------------------------------------------------------------------
+// workspace-router-history — persisted local history query operations
+//
+// Pure functions that query and observe persisted local history state.
+// Extracted from WorkspaceRouter to separate history concerns from
+// workspace lifecycle orchestration.
+// ---------------------------------------------------------------------------
+import { buildRuntimeStagedTarget } from "./runtime-staged-target.js";
+import {
+  buildWorkspaceReadObservation,
+  type AttributedReadToolName,
+} from "./workspace-read-observation.js";
+import type {
+  PersistedLocalActivityWindow,
+  PersistedLocalHistoryStore,
+  RepoConcurrencySummary,
+  PersistedLocalHistorySummary,
+  PersistedLocalHistoryContext,
+} from "./persisted-local-history.js";
+import type { PersistedLocalHistoryGraphContext } from "./persisted-local-history-graph.js";
+import type { RepoObservation } from "./repo-state.js";
+import type { RuntimeCausalContext } from "./runtime-causal-context.js";
+import type {
+  WorkspaceExecutionContext,
+  WorkspaceStatus,
+} from "./workspace-router-model.js";
+import type { JsonObject } from "../contracts/json-object.js";
+import type { BoundWorkspace } from "./workspace-router-runtime.js";
+
+// ---------------------------------------------------------------------------
+// Unbound fallback — returned when no workspace is bound
+// ---------------------------------------------------------------------------
+
+export const UNBOUND_PERSISTED_LOCAL_HISTORY_SUMMARY: PersistedLocalHistorySummary = Object.freeze({
+  availability: "none",
+  persistence: "persisted_local_history",
+  historyPath: null,
+  totalContinuityRecords: 0,
+  active: false,
+  lastOperation: null,
+  lastObservedAt: null,
+  continuityKey: null,
+  causalSessionId: null,
+  strandId: null,
+  checkoutEpochId: null,
+  continuedFromCausalSessionId: null,
+  continuityConfidence: "unknown",
+  continuityEvidence: [],
+  attribution: Object.freeze({
+    actor: Object.freeze({
+      actorId: "unknown",
+      actorKind: "unknown",
+      displayName: "Unknown",
+      source: "persisted_local_history.fallback",
+      authorityScope: "inferred",
+    }),
+    confidence: "unknown",
+    basis: "unknown_fallback",
+    evidence: [],
+  }),
+  latestReadEvent: null,
+  latestStageEvent: null,
+  latestTransitionEvent: null,
+  preserves: Object.freeze([
+    "continuity_operations",
+    "read_events",
+    "stage_events",
+    "transition_events",
+    "runtime_context_ids",
+    "workspace_overlay_snapshots",
+  ]),
+  excludes: Object.freeze([
+    "raw_chat_transcripts",
+    "queue_bookkeeping",
+    "canonical_provenance",
+    "canonical_structural_truth",
+  ]),
+  nextAction: "bind_workspace_to_begin_local_history",
+} as PersistedLocalHistorySummary);
+
+export const UNBOUND_PERSISTED_LOCAL_ACTIVITY_WINDOW = Object.freeze({
+  historyPath: null,
+  totalMatchingItems: 0,
+  truncated: false,
+  items: Object.freeze([]),
+});
+
+// ---------------------------------------------------------------------------
+// History query functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Retrieve the persisted local history summary for a bound workspace,
+ * including side-effect observations for semantic transitions and staged targets.
+ */
+export async function queryPersistedLocalHistorySummary(input: {
+  readonly persistedLocalHistory: PersistedLocalHistoryStore;
+  readonly binding: BoundWorkspace;
+  readonly status: WorkspaceStatus;
+  readonly buildCausalContext: (
+    binding: BoundWorkspace,
+    observation: { readonly checkoutEpoch: number },
+  ) => RuntimeCausalContext;
+  readonly buildHistoryContext: (
+    binding: BoundWorkspace,
+    observation: RepoObservation,
+  ) => PersistedLocalHistoryContext;
+  readonly buildGraphContext: (
+    binding: BoundWorkspace,
+  ) => Promise<PersistedLocalHistoryGraphContext | null>;
+}): Promise<PersistedLocalHistorySummary> {
+  const { persistedLocalHistory, binding, status, buildCausalContext, buildHistoryContext, buildGraphContext } = input;
+  const repoState = binding.slice.repoState;
+  if (repoState === null) {
+    return UNBOUND_PERSISTED_LOCAL_HISTORY_SUMMARY;
+  }
+  const observation = repoState.getState();
+  const causalContext = buildCausalContext(binding, observation);
+  const graph = await buildGraphContext(binding);
+  let summary = await persistedLocalHistory.summarize(status, causalContext, graph);
+
+  if (observation.semanticTransition !== null) {
+    await persistedLocalHistory.noteSemanticTransitionObservation({
+      current: buildHistoryContext(binding, observation),
+      semanticTransition: observation.semanticTransition,
+      transition: observation.lastTransition,
+      attribution: summary.attribution,
+      graph,
+    });
+    summary = await persistedLocalHistory.summarize(status, causalContext, graph);
+  }
+
+  const stagedTarget = buildRuntimeStagedTarget(status, causalContext, observation, summary.attribution);
+
+  if (stagedTarget.availability === "full_file") {
+    await persistedLocalHistory.noteStageObservation({
+      current: buildHistoryContext(binding, observation),
+      stagedTarget,
+      attribution: summary.attribution,
+      graph,
+    });
+    return persistedLocalHistory.summarize(status, causalContext, graph);
+  }
+
+  return summary;
+}
+
+/**
+ * Retrieve the repo concurrency summary for a bound workspace.
+ */
+export async function queryRepoConcurrencySummary(input: {
+  readonly persistedLocalHistory: PersistedLocalHistoryStore;
+  readonly status: WorkspaceStatus;
+  readonly buildGraphContext: (
+    binding: BoundWorkspace,
+  ) => Promise<PersistedLocalHistoryGraphContext | null>;
+  readonly binding: BoundWorkspace;
+}): Promise<RepoConcurrencySummary | null> {
+  return input.persistedLocalHistory.summarizeRepoConcurrency(
+    input.status,
+    await input.buildGraphContext(input.binding),
+  );
+}
+
+/**
+ * Retrieve the persisted local activity window for a bound workspace.
+ */
+export async function queryPersistedLocalActivityWindow(input: {
+  readonly persistedLocalHistory: PersistedLocalHistoryStore;
+  readonly binding: BoundWorkspace;
+  readonly status: WorkspaceStatus;
+  readonly limit: number;
+  readonly buildCausalContext: (
+    binding: BoundWorkspace,
+    observation: { readonly checkoutEpoch: number },
+  ) => RuntimeCausalContext;
+  readonly buildGraphContext: (
+    binding: BoundWorkspace,
+  ) => Promise<PersistedLocalHistoryGraphContext | null>;
+  readonly refreshSummary: () => Promise<void>;
+}): Promise<PersistedLocalActivityWindow> {
+  const { persistedLocalHistory, binding, status, limit, buildCausalContext, buildGraphContext, refreshSummary } = input;
+  const repoState = binding.slice.repoState;
+  if (repoState === null) {
+    return { ...UNBOUND_PERSISTED_LOCAL_ACTIVITY_WINDOW, limit } as PersistedLocalActivityWindow;
+  }
+  await refreshSummary();
+  const observation = repoState.getState();
+  const causalContext = buildCausalContext(binding, observation);
+  const graph = await buildGraphContext(binding);
+  return persistedLocalHistory.listRecentActivity(status, causalContext, limit, graph);
+}
+
+/**
+ * Record a read observation against persisted local history.
+ */
+export async function noteReadObservation(input: {
+  readonly persistedLocalHistory: PersistedLocalHistoryStore;
+  readonly execution: WorkspaceExecutionContext;
+  readonly toolName: AttributedReadToolName;
+  readonly args: JsonObject;
+  readonly result: JsonObject;
+  readonly buildHistoryContextFromExecution: (
+    execution: WorkspaceExecutionContext,
+    observation: RepoObservation,
+  ) => PersistedLocalHistoryContext;
+  readonly buildGraphContextFromExecution: (
+    execution: WorkspaceExecutionContext,
+  ) => Promise<PersistedLocalHistoryGraphContext | null>;
+}): Promise<void> {
+  const {
+    persistedLocalHistory, execution, toolName, args, result,
+    buildHistoryContextFromExecution, buildGraphContextFromExecution,
+  } = input;
+
+  const readObservation = buildWorkspaceReadObservation(execution, toolName, args, result);
+  if (readObservation === null) {
+    return;
+  }
+
+  const summary = await persistedLocalHistory.summarize(
+    execution.status,
+    execution.getCausalContext(),
+    await buildGraphContextFromExecution(execution),
+  );
+
+  await persistedLocalHistory.noteReadObservation({
+    current: buildHistoryContextFromExecution(execution, execution.repoState.getState()),
+    attribution: summary.attribution,
+    graph: await buildGraphContextFromExecution(execution),
+    ...readObservation,
+  });
+}

package/src/mcp/workspace-router-model.ts

@@ -0,0 +1,131 @@
+import type { ObservationCache } from "./cache.js";
+import type { Metrics } from "./metrics.js";
+import type { RepoStateTracker } from "./repo-state.js";
+import type { RuntimeCausalContext } from "./runtime-causal-context.js";
+import type { PersistedLocalHistorySummary } from "./persisted-local-history.js";
+import type { GovernorTracker } from "../session/tracker.js";
+import type { WarpHandle } from "../ports/warp.js";
+
+export type WorkspaceMode = "repo_local" | "daemon";
+export type WorkspaceBindState = "bound" | "unbound";
+export type WorkspaceBindAction = "bind" | "rebind";
+
+export interface WorkspaceCapabilityProfile {
+  readonly boundedReads: boolean;
+  readonly structuralTools: boolean;
+  readonly precisionTools: boolean;
+  readonly stateBookmarks: boolean;
+  readonly runtimeLogs: "session_local_only";
+  readonly runCapture: boolean;
+}
+
+export interface WorkspaceStatus {
+  readonly sessionMode: WorkspaceMode;
+  readonly bindState: WorkspaceBindState;
+  readonly repoId: string | null;
+  readonly worktreeId: string | null;
+  readonly worktreeRoot: string | null;
+  readonly gitCommonDir: string | null;
+  readonly graftDir: string | null;
+  readonly capabilityProfile: WorkspaceCapabilityProfile | null;
+}
+
+export interface WorkspaceActionResult extends WorkspaceStatus {
+  readonly ok: boolean;
+  readonly action: WorkspaceBindAction;
+  readonly freshSessionSlice: boolean;
+  readonly errorCode?: string;
+  readonly error?: string;
+}
+
+export interface CausalAttachResult extends WorkspaceStatus {
+  readonly ok: boolean;
+  readonly action: "attach";
+  readonly persistedLocalHistory: PersistedLocalHistorySummary;
+  readonly errorCode?: string;
+  readonly error?: string;
+}
+
+export interface WorkspaceBindRequest {
+  readonly cwd: string;
+  readonly worktreeRoot?: string | undefined;
+  readonly gitCommonDir?: string | undefined;
+  readonly repoId?: string | undefined;
+}
+
+export class WorkspaceBindingRequiredError extends Error {
+  readonly code = "UNBOUND_WORKSPACE";
+
+  constructor(toolName: string) {
+    super(`Tool ${toolName} requires an active workspace binding. Call workspace_bind first.`);
+    this.name = "WorkspaceBindingRequiredError";
+  }
+}
+
+export class WorkspaceCapabilityDeniedError extends Error {
+  readonly code = "CAPABILITY_DENIED";
+
+  constructor(toolName: string) {
+    super(`Tool ${toolName} is not enabled in the daemon default capability profile.`);
+    this.name = "WorkspaceCapabilityDeniedError";
+  }
+}
+
+export interface WorkspaceExecutionContext {
+  readonly sliceId: string;
+  readonly repoId: string;
+  readonly worktreeId: string;
+  readonly projectRoot: string;
+  readonly worktreeRoot: string;
+  readonly gitCommonDir: string;
+  readonly graftignorePatterns: readonly string[];
+  readonly resolvePath: (input: string) => string;
+  readonly capabilityProfile: WorkspaceCapabilityProfile;
+  readonly warpWriterId: string;
+  getCausalContext(): RuntimeCausalContext;
+  readonly status: WorkspaceStatus;
+  readonly governor: GovernorTracker;
+  readonly cache: ObservationCache;
+  readonly metrics: Metrics;
+  readonly graftDir: string;
+  readonly repoState: RepoStateTracker;
+  readonly getWarp: () => Promise<WarpHandle>;
+}
+
+export interface ResolvedWorkspace {
+  readonly repoId: string;
+  readonly worktreeId: string;
+  readonly worktreeRoot: string;
+  readonly gitCommonDir: string;
+}
+
+export interface WorkspaceAuthorizationPolicy {
+  getCapabilityProfile(resolved: ResolvedWorkspace): Promise<WorkspaceCapabilityProfile | null>;
+  noteBound(resolved: ResolvedWorkspace): Promise<void>;
+}
+
+export interface WorkspaceSharedAttachPolicy {
+  resolveSharedAttachSource(input: {
+    readonly sessionId: string;
+    readonly repoId: string;
+    readonly worktreeId: string;
+  }): import("./persisted-local-history.js").PersistedLocalHistorySharedAttachSource | null;
+}
+
+export const DEFAULT_DAEMON_CAPABILITY_PROFILE: WorkspaceCapabilityProfile = Object.freeze({
+  boundedReads: true,
+  structuralTools: true,
+  precisionTools: true,
+  stateBookmarks: true,
+  runtimeLogs: "session_local_only",
+  runCapture: false,
+});
+
+export const DEFAULT_REPO_LOCAL_CAPABILITY_PROFILE: WorkspaceCapabilityProfile = Object.freeze({
+  boundedReads: true,
+  structuralTools: true,
+  precisionTools: true,
+  stateBookmarks: true,
+  runtimeLogs: "session_local_only",
+  runCapture: true,
+});

package/src/mcp/workspace-router-resolution.ts

@@ -0,0 +1,71 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { GitClient } from "../ports/git.js";
+import type { ResolvedWorkspace, WorkspaceBindRequest } from "./workspace-router-model.js";
+
+interface WorkspaceBindError {
+  readonly code: string;
+  readonly message: string;
+}
+
+export function stableWorkspaceId(prefix: string, input: string): string {
+  return `${prefix}:${crypto.createHash("sha256").update(input).digest("hex").slice(0, 16)}`;
+}
+
+async function readGitValue(git: GitClient, cwd: string, args: readonly string[]): Promise<string | null> {
+  const result = await git.run({ args, cwd });
+  if (result.error !== undefined || result.status !== 0) {
+    return null;
+  }
+  const trimmed = result.stdout.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function toAbsolutePath(base: string, value: string): string {
+  return path.isAbsolute(value) ? value : path.resolve(base, value);
+}
+
+/**
+ * Resolve symlinks to get the canonical filesystem path.
+ * Prevents identity drift from path aliases (e.g. /tmp vs /private/tmp on macOS).
+ * Falls back to the input path if realpath fails (e.g. path does not exist yet).
+ */
+function canonicalize(inputPath: string): string {
+  try {
+    return fs.realpathSync(inputPath);
+  } catch {
+    return inputPath;
+  }
+}
+
+export async function resolveWorkspaceRequest(
+  git: GitClient,
+  request: WorkspaceBindRequest,
+): Promise<ResolvedWorkspace | WorkspaceBindError> {
+  const cwd = path.resolve(request.cwd);
+  const worktreeRoot = await readGitValue(git, cwd, ["rev-parse", "--path-format=absolute", "--show-toplevel"]);
+  if (worktreeRoot === null) {
+    return {
+      code: "NOT_A_GIT_REPO",
+      message: `cwd is not inside a git worktree: ${cwd}`,
+    };
+  }
+
+  const rawGitCommonDir = await readGitValue(git, cwd, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+  if (rawGitCommonDir === null) {
+    return {
+      code: "WORKSPACE_RESOLUTION_FAILED",
+      message: `Unable to resolve git common dir from ${cwd}`,
+    };
+  }
+
+  const gitCommonDir = canonicalize(toAbsolutePath(worktreeRoot, rawGitCommonDir));
+  const canonicalWorktreeRoot = canonicalize(worktreeRoot);
+  return {
+    repoId: stableWorkspaceId("repo", gitCommonDir),
+    worktreeId: stableWorkspaceId("worktree", canonicalWorktreeRoot),
+    worktreeRoot: canonicalWorktreeRoot,
+    gitCommonDir,
+  };
+}