@flyingrobots/graft 0.6.1 → 0.7.0

package/src/mcp/warp-pool.ts

@@ -1,22 +1,22 @@
-import type { WarpHandle } from "../ports/warp.js";
+import type WarpApp from "@git-stunts/git-warp";
 import { DEFAULT_WARP_WRITER_ID } from "../warp/writer-id.js";
 
 export interface WarpPool {
-  getOrOpen(repoId: string, worktreeRoot: string, writerId?: string): Promise<WarpHandle>;
+  getOrOpen(repoId: string, worktreeRoot: string, writerId?: string): Promise<WarpApp>;
   size(): number;
 }
 
 export class InMemoryWarpPool implements WarpPool {
-  private readonly opened = new Map<string, Map<string, Promise<WarpHandle>>>();
+  private readonly opened = new Map<string, Map<string, Promise<WarpApp>>>();
 
-  constructor(private readonly openWarp: (worktreeRoot: string, writerId: string) => Promise<WarpHandle>) {}
+  constructor(private readonly openWarp: (worktreeRoot: string, writerId: string) => Promise<WarpApp>) {}
 
-  getOrOpen(repoId: string, worktreeRoot: string, writerId: string = DEFAULT_WARP_WRITER_ID): Promise<WarpHandle> {
+  getOrOpen(repoId: string, worktreeRoot: string, writerId: string = DEFAULT_WARP_WRITER_ID): Promise<WarpApp> {
     const repoHandles = this.opened.get(repoId);
     const cached = repoHandles?.get(writerId);
     if (cached !== undefined) return cached;
 
-    const nextRepoHandles = repoHandles ?? new Map<string, Promise<WarpHandle>>();
+    const nextRepoHandles = repoHandles ?? new Map<string, Promise<WarpApp>>();
     const opened = this.openWarp(worktreeRoot, writerId).catch((error: unknown) => {
       const current = this.opened.get(repoId);
       current?.delete(writerId);

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

@@ -4,7 +4,7 @@ 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";
+import type { WarpContext } from "../warp/context.js";
 
 export type WorkspaceMode = "repo_local" | "daemon";
 export type WorkspaceBindState = "bound" | "unbound";
@@ -89,7 +89,7 @@ export interface WorkspaceExecutionContext {
   readonly metrics: Metrics;
   readonly graftDir: string;
   readonly repoState: RepoStateTracker;
-  readonly getWarp: () => Promise<WarpHandle>;
+  readonly getWarp: () => Promise<WarpContext>;
 }
 
 export interface ResolvedWorkspace {

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

@@ -2,7 +2,7 @@ import * as path from "node:path";
 import { createRepoPathResolver } from "../adapters/repo-paths.js";
 import type { FileSystem } from "../ports/filesystem.js";
 import type { GitClient } from "../ports/git.js";
-import type { WarpHandle } from "../ports/warp.js";
+import type { WarpContext } from "../warp/context.js";
 import { DEFAULT_WARP_WRITER_ID } from "../warp/writer-id.js";
 import { GovernorTracker } from "../session/tracker.js";
 import { ObservationCache } from "./cache.js";
@@ -48,7 +48,7 @@ export interface BoundWorkspace {
   readonly warpWriterId: string;
   readonly transportSessionId: string;
   readonly slice: WorkspaceSlice;
-  readonly getWarp: () => Promise<WarpHandle>;
+  readonly getWarp: () => Promise<WarpContext>;
 }
 
 export function createWorkspaceSlice(input: {
@@ -94,11 +94,14 @@ export async function createBoundWorkspace(input: {
     transportSessionId: input.transportSessionId,
     warpWriterId: input.warpWriterId ?? DEFAULT_WARP_WRITER_ID,
     slice: input.slice,
-    getWarp: () => input.warpPool.getOrOpen(
-      input.resolved.repoId,
-      input.resolved.worktreeRoot,
-      input.warpWriterId ?? DEFAULT_WARP_WRITER_ID,
-    ),
+    getWarp: async () => ({
+      app: await input.warpPool.getOrOpen(
+        input.resolved.repoId,
+        input.resolved.worktreeRoot,
+        input.warpWriterId ?? DEFAULT_WARP_WRITER_ID,
+      ),
+      strandId: null,
+    }),
   };
 }
 
@@ -193,7 +196,7 @@ export async function resolveCheckoutBoundaryHookEvent(input: {
 
 export async function buildPersistedLocalHistoryGraphContext(
   worktreeRoot: string,
-  getWarp: () => Promise<WarpHandle>,
+  getWarp: () => Promise<WarpContext>,
 ): Promise<PersistedLocalHistoryGraphContext | null> {
   try {
     return {

package/src/mcp/workspace-router.ts

@@ -37,7 +37,7 @@ import {
 import { resolveWorkspaceRequest, stableWorkspaceId } from "./workspace-router-resolution.js";
 import type { FileSystem } from "../ports/filesystem.js";
 import type { GitClient } from "../ports/git.js";
-import type { WarpHandle } from "../ports/warp.js";
+import type { WarpContext } from "../warp/context.js";
 import type { JsonObject } from "../contracts/json-object.js";
 import type { WarpPool } from "./warp-pool.js";
 import { DEFAULT_WARP_WRITER_ID } from "../warp/writer-id.js";
@@ -87,6 +87,7 @@ interface WorkspaceRouterOptions {
   readonly authorizationPolicy?: WorkspaceAuthorizationPolicy | undefined;
   readonly sharedAttachPolicy?: WorkspaceSharedAttachPolicy | undefined;
   readonly persistedLocalHistory: PersistedLocalHistoryStore;
+  readonly persistedLocalHistoryGraph?: boolean;
 }
 
 export class WorkspaceRouter {
@@ -197,7 +198,7 @@ export class WorkspaceRouter {
     return this.requireBinding().resolvePath;
   }
 
-  getWarp(): Promise<WarpHandle> {
+  getWarp(): Promise<WarpContext> {
     return this.requireBinding().getWarp();
   }
 
@@ -670,12 +671,18 @@ export class WorkspaceRouter {
   private async buildPersistedLocalHistoryGraphContext(
     binding: BoundWorkspace,
   ): Promise<PersistedLocalHistoryGraphContext | null> {
+    if (this.options.persistedLocalHistoryGraph === false) {
+      return null;
+    }
     return buildPersistedLocalHistoryGraphContext(binding.worktreeRoot, binding.getWarp);
   }
 
   private async buildPersistedLocalHistoryGraphContextFromExecution(
     execution: WorkspaceExecutionContext,
   ): Promise<PersistedLocalHistoryGraphContext | null> {
+    if (this.options.persistedLocalHistoryGraph === false) {
+      return null;
+    }
     return buildPersistedLocalHistoryGraphContext(execution.worktreeRoot, execution.getWarp);
   }
 }

package/src/operations/adaptive-projection.ts

@@ -0,0 +1,54 @@
+// ---------------------------------------------------------------------------
+// Adaptive Projection Selection — structural auto-selection
+// ---------------------------------------------------------------------------
+
+/** Structural metrics for projection selection. */
+export interface ProjectionCandidate {
+  readonly fileLines: number;
+  readonly fileBytes: number;
+  readonly symbolCount: number;
+  readonly outlineCompressionRatio: number;
+  readonly targetSymbol?: string;
+}
+
+/** Selected projection with reasoning. */
+export interface ProjectionSelection {
+  readonly projection: "outline" | "content" | "range";
+  readonly reason: string;
+}
+
+const SMALL_FILE_THRESHOLD = 50;
+const HORIZON_RATIO = 0.7;
+
+/**
+ * Select the optimal projection based on structural metrics.
+ *
+ * - Dense large files → outline (saves the most context)
+ * - Small or irreducibly complex files → content (outline doesn't help)
+ * - Targeted symbol investigation → range (surgical read)
+ */
+export function selectProjection(candidate: ProjectionCandidate): ProjectionSelection {
+  // If a specific symbol is targeted, use range
+  if (candidate.targetSymbol !== undefined) {
+    return {
+      projection: "range",
+      reason: `Targeted read for symbol "${candidate.targetSymbol}" — range is most efficient.`,
+    };
+  }
+
+  // Small files or high compression ratio → content
+  if (candidate.fileLines <= SMALL_FILE_THRESHOLD || candidate.outlineCompressionRatio >= HORIZON_RATIO) {
+    return {
+      projection: "content",
+      reason: candidate.fileLines <= SMALL_FILE_THRESHOLD
+        ? `Small file (${String(candidate.fileLines)} lines) — content fits easily.`
+        : `Outline is ${String(Math.round(candidate.outlineCompressionRatio * 100))}% of content — outline provides negligible savings.`,
+    };
+  }
+
+  // Default: outline for larger files with good compression
+  return {
+    projection: "outline",
+    reason: `${String(candidate.fileLines)} lines, ${String(candidate.symbolCount)} symbols, ${String(Math.round(candidate.outlineCompressionRatio * 100))}% compression — outline is efficient.`,
+  };
+}

package/src/operations/agent-handoff.ts

@@ -0,0 +1,59 @@
+// ---------------------------------------------------------------------------
+// Agent Handoff Protocol — structured session transfer
+// ---------------------------------------------------------------------------
+
+import type { ObservationCache } from "./observation-cache.js";
+
+/** The structured handoff payload. */
+export interface HandoffPayload {
+  readonly sessionId: string;
+  readonly filesRead: readonly string[];
+  readonly symbolsInspected: readonly string[];
+  readonly observations: number;
+  readonly budgetConsumed: string;
+}
+
+/** Options for building a handoff. */
+export interface HandoffOptions {
+  readonly cache: ObservationCache;
+  readonly sessionId: string;
+  readonly budgetTotal?: number;
+  readonly budgetConsumed?: number;
+}
+
+/**
+ * Build a structured handoff payload from the current session state.
+ *
+ * Projects the observation cache into a portable JSON payload that
+ * a receiving agent can use to understand what the departing agent
+ * knew and where it left off.
+ */
+export function buildHandoff(options: HandoffOptions): HandoffPayload {
+  const { cache, sessionId } = options;
+
+  const filesRead: string[] = [];
+  const symbolsInspected: string[] = [];
+  let observationCount = 0;
+
+  for (const [filePath, observation] of cache.allEntries()) {
+    filesRead.push(filePath);
+    for (const entry of observation.outline) {
+      symbolsInspected.push(entry.name);
+    }
+    observationCount++;
+  }
+
+  let budgetStr = "unknown";
+  if (options.budgetTotal !== undefined && options.budgetConsumed !== undefined && options.budgetTotal > 0) {
+    const pct = Math.round((options.budgetConsumed / options.budgetTotal) * 100);
+    budgetStr = `${String(pct)}%`;
+  }
+
+  return {
+    sessionId,
+    filesRead,
+    symbolsInspected,
+    observations: observationCount,
+    budgetConsumed: budgetStr,
+  };
+}

package/src/operations/capture-range.ts

@@ -0,0 +1,64 @@
+// ---------------------------------------------------------------------------
+// Capture Range — opaque handles for run_capture output
+// ---------------------------------------------------------------------------
+
+
+
+interface CaptureEntry {
+  readonly sessionId: string;
+  readonly content: string;
+  readonly lines: readonly string[];
+}
+
+/** Result of a range retrieval. */
+export type CaptureRangeResult =
+  | { readonly ok: true; readonly lines: readonly string[]; readonly totalLines: number }
+  | { readonly ok: false; readonly error: string };
+
+/**
+ * Registry of opaque capture handles.
+ *
+ * Maps UUIDs to capture content. Handles are session-scoped — a
+ * handle from one session is rejected in another.
+ */
+export class CaptureHandleRegistry {
+  private nextId = 0;
+  private readonly entries = new Map<string, CaptureEntry>();
+
+  /**
+   * Register capture content and return an opaque handle.
+   */
+  register(sessionId: string, content: string): string {
+    const handle = `capture-${String(++this.nextId)}`;
+    const lines = content.split("\n").filter(
+      (line, index, arr) => index < arr.length - 1 || line.length > 0,
+    );
+    this.entries.set(handle, { sessionId, content, lines });
+    return handle;
+  }
+
+  /**
+   * Retrieve a line range from a capture handle.
+   *
+   * @param handle - The opaque handle from register()
+   * @param sessionId - The requesting session (must match the registering session)
+   * @param start - 1-based start line (inclusive)
+   * @param end - 1-based end line (inclusive)
+   */
+  getRange(handle: string, sessionId: string, start: number, end: number): CaptureRangeResult {
+    const entry = this.entries.get(handle);
+    if (entry === undefined) {
+      return { ok: false, error: "Capture handle not found" };
+    }
+    if (entry.sessionId !== sessionId) {
+      return { ok: false, error: "Capture handle belongs to a different session" };
+    }
+
+    const totalLines = entry.lines.length;
+    const clampedStart = Math.max(1, start);
+    const clampedEnd = Math.min(totalLines, end);
+    const lines = entry.lines.slice(clampedStart - 1, clampedEnd);
+
+    return { ok: true, lines, totalLines };
+  }
+}

package/src/operations/conversation-primer.ts

@@ -0,0 +1,82 @@
+// ---------------------------------------------------------------------------
+// Conversation Primer — auto-orient agent at session start via graft_map
+// ---------------------------------------------------------------------------
+
+import type { GitClient } from "../ports/git.js";
+import type { FileSystem } from "../ports/filesystem.js";
+import type { PathOps } from "../ports/paths.js";
+
+/** Result of building a conversation primer. */
+export interface ConversationPrimerResult {
+  readonly scope: string;
+  readonly files: readonly string[];
+  readonly truncated: boolean;
+  readonly totalFiles: number;
+}
+
+/** Options for building a primer. */
+export interface ConversationPrimerOptions {
+  readonly cwd: string;
+  readonly git: GitClient;
+  readonly fs: FileSystem;
+  readonly pathOps: PathOps;
+  readonly scope?: string;
+  readonly maxFiles?: number;
+}
+
+/** Common source directory names, in priority order. */
+const COMMON_SCOPES = ["src", "lib", "app", "packages"];
+
+async function isDirectory(fileSystem: FileSystem, dirPath: string): Promise<boolean> {
+  try {
+    await fileSystem.readdir(dirPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build a conversation primer for the given project.
+ *
+ * Auto-detects the best scope (src/, lib/, etc.) or uses an explicit
+ * scope. Returns a list of tracked files, truncated if beyond maxFiles.
+ */
+export async function buildConversationPrimer(
+  options: ConversationPrimerOptions,
+): Promise<ConversationPrimerResult> {
+  const { cwd, git, fs: fileSystem, pathOps, maxFiles = 50 } = options;
+
+  // Detect scope
+  let scope = options.scope ?? ".";
+  if (options.scope === undefined) {
+    for (const candidate of COMMON_SCOPES) {
+      const candidatePath = pathOps.join(cwd, candidate);
+      if (await isDirectory(fileSystem, candidatePath)) {
+        scope = candidate;
+        break;
+      }
+    }
+  }
+
+  // List tracked files via git ls-files (allowed by plumbing)
+  const lsResult = await git.run({
+    cwd,
+    args: ["ls-files", "--", scope],
+  });
+
+  const allFiles = lsResult.stdout
+    .split("\n")
+    .map((f) => f.trim())
+    .filter((f) => f.length > 0);
+
+  const truncated = allFiles.length > maxFiles;
+  const files = truncated ? allFiles.slice(0, maxFiles) : allFiles;
+
+  return {
+    scope,
+    files,
+    truncated,
+    totalFiles: allFiles.length,
+  };
+}

package/src/operations/cross-session-resume.ts

@@ -0,0 +1,104 @@
+// ---------------------------------------------------------------------------
+// Cross-session resume — structural diff from saved HEAD to current HEAD
+// ---------------------------------------------------------------------------
+
+import type { GitClient } from "../ports/git.js";
+
+/** A file that changed between saved HEAD and current HEAD. */
+export interface ResumeChangedFile {
+  readonly path: string;
+  readonly status: "added" | "modified" | "deleted" | "renamed";
+}
+
+/** Result of attempting to resume from a saved session state. */
+export interface SessionResumeResult {
+  readonly resumable: boolean;
+  readonly currentHead: string;
+  readonly savedHead: string;
+  readonly changedFiles: readonly ResumeChangedFile[];
+  readonly commitsBehind: number;
+  readonly error?: string;
+}
+
+export interface SessionResumeOptions {
+  readonly cwd: string;
+  readonly savedHeadSha: string;
+  readonly git: GitClient;
+}
+
+/**
+ * Build a structural resume from a saved HEAD to current HEAD.
+ *
+ * Uses plumbing-safe git commands (diff-tree, rev-list, log) to
+ * find changed files and count commits between two points.
+ */
+export async function buildSessionResume(
+  options: SessionResumeOptions,
+): Promise<SessionResumeResult> {
+  const { cwd, savedHeadSha, git } = options;
+
+  const headResult = await git.run({ cwd, args: ["rev-parse", "HEAD"] });
+  const currentHead = headResult.stdout.trim();
+  if (headResult.status !== 0 || currentHead.length === 0) {
+    return {
+      resumable: false, currentHead: "", savedHead: savedHeadSha,
+      changedFiles: [], commitsBehind: 0,
+      error: "Cannot resolve current HEAD",
+    };
+  }
+
+  // Check if saved HEAD exists in the repo
+  const verifyResult = await git.run({ cwd, args: ["cat-file", "-t", savedHeadSha] });
+  if (verifyResult.stdout.trim() !== "commit") {
+    return {
+      resumable: false, currentHead, savedHead: savedHeadSha,
+      changedFiles: [], commitsBehind: 0,
+      error: "Saved HEAD SHA not found in repository",
+    };
+  }
+
+  if (currentHead === savedHeadSha) {
+    return {
+      resumable: true, currentHead, savedHead: savedHeadSha,
+      changedFiles: [], commitsBehind: 0,
+    };
+  }
+
+  // Use diff-tree (plumbing-safe) with -r for recursive
+  const diffResult = await git.run({
+    cwd,
+    args: ["diff-tree", "-r", "--name-status", "--no-commit-id", savedHeadSha, currentHead],
+  });
+  const changedFiles: ResumeChangedFile[] = [];
+  const diffOutput = diffResult.stdout.trim();
+
+  if (diffOutput.length > 0) {
+    for (const line of diffOutput.split("\n")) {
+      const parts = line.split("\t");
+      if (parts.length < 2) continue;
+      const statusChar = (parts[0] ?? "").charAt(0);
+      const filePath = parts[parts.length - 1] ?? "";
+
+      let status: ResumeChangedFile["status"];
+      switch (statusChar) {
+        case "A": status = "added"; break;
+        case "D": status = "deleted"; break;
+        case "R": status = "renamed"; break;
+        default: status = "modified"; break;
+      }
+      changedFiles.push({ path: filePath, status });
+    }
+  }
+
+  // Count commits
+  const countResult = await git.run({
+    cwd,
+    args: ["rev-list", "--count", `${savedHeadSha}..${currentHead}`],
+  });
+  const commitsBehind = parseInt(countResult.stdout.trim(), 10) || 0;
+
+  return {
+    resumable: true, currentHead, savedHead: savedHeadSha,
+    changedFiles, commitsBehind,
+  };
+}

package/src/operations/deterministic-replay.ts

@@ -0,0 +1,143 @@
+// ---------------------------------------------------------------------------
+// Deterministic Scenario Replay — re-drive sessions for CI regression
+// ---------------------------------------------------------------------------
+
+import type { FileSystem } from "../ports/filesystem.js";
+
+/** A recorded tool call with its expected result. */
+export interface RecordedToolCall {
+  readonly tool: string;
+  readonly args: Readonly<Record<string, unknown>>;
+  readonly expectedResult: Readonly<Record<string, unknown>>;
+}
+
+/** A replay scenario: filesystem snapshot + recorded calls. */
+interface _ReplayScenario {
+  readonly files: Readonly<Record<string, string>>;
+  readonly calls: readonly RecordedToolCall[];
+}
+
+/** A single mismatch between expected and actual. */
+export interface ReplayFailure {
+  readonly index: number;
+  readonly tool: string;
+  readonly expected: Readonly<Record<string, unknown>>;
+  readonly actual: Readonly<Record<string, unknown>>;
+}
+
+/** Result of replaying a scenario. */
+export interface ReplayResult {
+  readonly passed: boolean;
+  readonly total: number;
+  readonly matched: number;
+  readonly mismatched: number;
+  readonly failures: readonly ReplayFailure[];
+}
+
+/** Handler that executes a tool call and returns the result. */
+export type ToolCallHandler = (
+  tool: string,
+  args: Readonly<Record<string, unknown>>,
+) => Promise<Readonly<Record<string, unknown>>>;
+
+/**
+ * Create a mock FileSystem from a snapshot map.
+ *
+ * Keys are file paths, values are file contents. Provides readFile,
+ * readdir, stat, and other FileSystem methods backed by the map.
+ */
+export function createSnapshotFs(
+  files: Readonly<Record<string, string>>,
+): FileSystem {
+  const fileMap = new Map(Object.entries(files));
+
+  return {
+    readFile(path: string, _encoding?: string): Promise<string> {
+      const content = fileMap.get(path);
+      if (content === undefined) {
+        return Promise.reject(new Error(`File not found in snapshot: ${path}`));
+      }
+      return Promise.resolve(content);
+    },
+
+    readFileSync(path: string): string {
+      const content = fileMap.get(path);
+      if (content === undefined) {
+        throw new Error(`File not found in snapshot: ${path}`);
+      }
+      return content;
+    },
+
+    readdir(dirPath: string): Promise<string[]> {
+      const prefix = dirPath.endsWith("/") ? dirPath : `${dirPath}/`;
+      const entries = new Set<string>();
+      for (const key of fileMap.keys()) {
+        if (key.startsWith(prefix)) {
+          const rest = key.slice(prefix.length);
+          const firstSegment = rest.split("/")[0];
+          if (firstSegment !== undefined && firstSegment.length > 0) {
+            entries.add(firstSegment);
+          }
+        }
+      }
+      return Promise.resolve([...entries].sort());
+    },
+
+    writeFile(): Promise<void> {
+      return Promise.resolve();
+    },
+
+    appendFile(): Promise<void> {
+      return Promise.resolve();
+    },
+
+    mkdir(): Promise<void> {
+      return Promise.resolve();
+    },
+
+    stat(path: string): Promise<{ size: number }> {
+      const content = fileMap.get(path);
+      return Promise.resolve({ size: content?.length ?? 0 });
+    },
+  } as unknown as FileSystem;
+}
+
+/**
+ * Replay a sequence of recorded tool calls against a handler.
+ *
+ * Compares each actual result to the expected result from the
+ * recording. Returns pass/fail with details on mismatches.
+ */
+export async function replayToolCalls(
+  calls: readonly RecordedToolCall[],
+  handler: ToolCallHandler,
+): Promise<ReplayResult> {
+  const failures: ReplayFailure[] = [];
+  let matched = 0;
+
+  for (let i = 0; i < calls.length; i++) {
+    const call = calls[i] ?? { tool: "", args: {}, expectedResult: {} };
+    const actual = await handler(call.tool, call.args);
+    const expectedJson = JSON.stringify(call.expectedResult);
+    const actualJson = JSON.stringify(actual);
+
+    if (expectedJson === actualJson) {
+      matched++;
+    } else {
+      failures.push({
+        index: i,
+        tool: call.tool,
+        expected: call.expectedResult,
+        actual,
+      });
+    }
+  }
+
+  return {
+    passed: failures.length === 0,
+    total: calls.length,
+    matched,
+    mismatched: failures.length,
+    failures,
+  };
+}