@flyingrobots/graft 0.3.1

package/src/mcp/tools/safe-read.ts

@@ -0,0 +1,135 @@
+import { z } from "zod";
+import { safeRead } from "../../operations/safe-read.js";
+import type { SafeReadResult } from "../../operations/safe-read.js";
+import { evaluatePolicy } from "../../policy/evaluate.js";
+import { RefusedResult } from "../../policy/types.js";
+import { diffOutlines } from "../../parser/diff.js";
+import { CachedFile } from "../cached-file.js";
+import type { Metrics } from "../metrics.js";
+import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+
+const PROJECTION_METRICS: Readonly<Record<string, ((m: Metrics) => void) | undefined>> = {
+  content: (m) => { m.recordRead(); },
+  outline: (m) => { m.recordOutline(); },
+  refused: (m) => { m.recordRefusal(); },
+};
+
+const CACHEABLE_PROJECTIONS: ReadonlySet<SafeReadResult["projection"]> = new Set(["content", "outline"]);
+
+export const safeReadTool: ToolDefinition = {
+  name: "safe_read",
+  description:
+    "Policy-enforced file read. Returns full content for small files, " +
+    "structural outline with jump table for large files, or refusal with " +
+    "reason code for banned files. Detects re-reads and returns cached " +
+    "outlines or structural diffs.",
+  schema: { path: z.string(), intent: z.string().optional() },
+  createHandler(ctx: ToolContext): ToolHandler {
+    return async (args) => {
+      const filePath = ctx.resolvePath(args["path"] as string);
+
+      // Build CachedFile once — all consumers share the same snapshot,
+      // eliminating TOCTOU races where the file changes between reads.
+      let cf: CachedFile | null = null;
+      try {
+        const rawContent = ctx.fs.readFileSync(filePath, "utf-8");
+        cf = new CachedFile(filePath, rawContent);
+      } catch {
+        // File doesn't exist or can't be read — proceed to safeRead for error handling
+      }
+
+      // Check cache if we could read the file
+      if (cf !== null) {
+        const cacheResult = ctx.cache.check(filePath, cf.rawContent);
+        if (cacheResult.hit) {
+          // Defense: re-check policy before returning cached data.
+          const policy = evaluatePolicy(
+            { path: filePath, lines: cf.actual.lines, bytes: cf.actual.bytes },
+            { sessionDepth: ctx.session.getSessionDepth(), budgetRemaining: ctx.session.getBudget()?.remaining },
+          );
+          if (policy instanceof RefusedResult) {
+            ctx.metrics.recordRefusal();
+            return ctx.respond("safe_read", {
+              path: filePath,
+              projection: "refused",
+              reason: policy.reason,
+              reasonDetail: policy.reasonDetail,
+              next: [...policy.next],
+              actual: cf.actual,
+            });
+          }
+
+          cacheResult.obs.touch();
+          ctx.metrics.recordCacheHit(cf.actual.bytes);
+          return ctx.respond("safe_read", {
+            path: filePath,
+            projection: "cache_hit",
+            reason: "REREAD_UNCHANGED",
+            outline: cacheResult.obs.outline,
+            jumpTable: cacheResult.obs.jumpTable,
+            actual: cf.actual,
+            readCount: cacheResult.obs.readCount,
+            estimatedBytesAvoided: cf.actual.bytes,
+            lastReadAt: cacheResult.obs.lastReadAt,
+          });
+        }
+
+        // File changed since last observation — compute structural diff
+        if (cacheResult.stale !== null) {
+          // Defense: re-check policy before returning structural data.
+          const policy = evaluatePolicy(
+            { path: filePath, lines: cf.actual.lines, bytes: cf.actual.bytes },
+            { sessionDepth: ctx.session.getSessionDepth(), budgetRemaining: ctx.session.getBudget()?.remaining },
+          );
+          if (policy instanceof RefusedResult) {
+            ctx.metrics.recordRefusal();
+            return ctx.respond("safe_read", {
+              path: filePath,
+              projection: "refused",
+              reason: policy.reason,
+              reasonDetail: policy.reasonDetail,
+              next: [...policy.next],
+              actual: cf.actual,
+            });
+          }
+
+          const diff = diffOutlines(cacheResult.stale.outline, cf.outline);
+          const newReadCount = cacheResult.stale.readCount + 1;
+          ctx.cache.record(filePath, cf.hash, cf.outline, cf.jumpTable, cf.actual);
+          const updatedObs = ctx.cache.get(filePath);
+          return ctx.respond("safe_read", {
+            path: filePath,
+            projection: "diff",
+            reason: "CHANGED_SINCE_LAST_READ",
+            diff,
+            outline: cf.outline,
+            jumpTable: cf.jumpTable,
+            actual: cf.actual,
+            readCount: newReadCount,
+            lastReadAt: updatedObs?.lastReadAt ?? new Date().toISOString(),
+          });
+        }
+      }
+
+      // First read — pass rawContent to avoid double-read (TOCTOU)
+      const result = await safeRead(filePath, {
+        fs: ctx.fs,
+        codec: ctx.codec,
+        content: cf?.rawContent,
+        intent: args["intent"] as string | undefined,
+        sessionDepth: ctx.session.getSessionDepth(),
+        budgetRemaining: ctx.session.getBudget()?.remaining,
+      });
+
+      PROJECTION_METRICS[result.projection]?.(ctx.metrics);
+
+      // Record observation for cacheable projections — uses CachedFile
+      // outline (no re-read) to eliminate the snapshot race.
+      if (cf !== null && result.actual !== undefined && CACHEABLE_PROJECTIONS.has(result.projection)) {
+        ctx.cache.record(filePath, cf.hash, cf.outline, cf.jumpTable, result.actual);
+      }
+
+      return ctx.respond("safe_read", result);
+    };
+  },
+};

package/src/mcp/tools/state.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { stateSave, stateLoad } from "../../operations/state.js";
+import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+
+export const stateSaveTool: ToolDefinition = {
+  name: "state_save",
+  description:
+    "Save session working state (max 8 KB). Use for session bookmarks: " +
+    "current task, files modified, next planned actions.",
+  schema: { content: z.string() },
+  createHandler(ctx: ToolContext): ToolHandler {
+    return async (args) => {
+      const result = await stateSave(args["content"] as string, { graftDir: ctx.graftDir, fs: ctx.fs });
+      return ctx.respond("state_save", result as Record<string, unknown>);
+    };
+  },
+};
+
+export const stateLoadTool: ToolDefinition = {
+  name: "state_load",
+  description:
+    "Load previously saved session state. Returns null if no state has " +
+    "been saved.",
+  createHandler(ctx: ToolContext): ToolHandler {
+    return async () => {
+      const result = await stateLoad({ graftDir: ctx.graftDir, fs: ctx.fs });
+      return ctx.respond("state_load", result as Record<string, unknown>);
+    };
+  },
+};

package/src/mcp/tools/stats.ts

@@ -0,0 +1,20 @@
+import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+
+export const statsTool: ToolDefinition = {
+  name: "stats",
+  description:
+    "Decision metrics for the current session. Total reads, outlines, " +
+    "refusals, cache hits, and bytes avoided.",
+  createHandler(ctx: ToolContext): ToolHandler {
+    return () => {
+      const snap = ctx.metrics.snapshot();
+      return ctx.respond("stats", {
+        totalReads: snap.reads,
+        totalOutlines: snap.outlines,
+        totalRefusals: snap.refusals,
+        totalCacheHits: snap.cacheHits,
+        totalBytesAvoidedByCache: snap.bytesAvoided,
+      });
+    };
+  },
+};

package/src/metrics/logger.ts

@@ -0,0 +1,69 @@
+import * as path from "node:path";
+import type { FileSystem } from "../ports/filesystem.js";
+import type { JsonCodec } from "../ports/codec.js";
+import type { DecisionEntry } from "./types.js";
+
+export interface MetricsLoggerOptions {
+  readonly fs: FileSystem;
+  readonly codec: JsonCodec;
+  readonly maxBytes?: number;
+}
+
+const DEFAULT_MAX_BYTES = 1_048_576; // 1 MB
+
+export class MetricsLogger {
+  private readonly logPath: string;
+  private readonly fs: FileSystem;
+  private readonly codec: JsonCodec;
+  private readonly maxBytes: number;
+
+  constructor(logPath: string, options: MetricsLoggerOptions) {
+    this.logPath = logPath;
+    this.fs = options.fs;
+    this.codec = options.codec;
+    this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+  }
+
+  async log(entry: Omit<DecisionEntry, "ts">): Promise<void> {
+    const full: DecisionEntry = {
+      ts: new Date().toISOString(),
+      ...entry,
+    };
+
+    const line = this.codec.encode(full) + "\n";
+
+    const dir = path.dirname(this.logPath);
+    await this.fs.mkdir(dir, { recursive: true });
+    await this.fs.appendFile(this.logPath, line, "utf-8");
+
+    await this.rotateIfNeeded();
+  }
+
+  private async rotateIfNeeded(): Promise<void> {
+    let stat: { size: number };
+    try {
+      stat = await this.fs.stat(this.logPath);
+    } catch {
+      return;
+    }
+
+    if (stat.size <= this.maxBytes) {
+      return;
+    }
+
+    const content = await this.fs.readFile(this.logPath, "utf-8");
+    const lines = content.trimEnd().split("\n");
+
+    // Keep the most recent half of lines to get well under the limit
+    let kept = lines.slice(Math.ceil(lines.length / 2));
+    let result = kept.join("\n") + "\n";
+
+    // If still over, keep halving
+    while (Buffer.byteLength(result, "utf-8") > this.maxBytes && kept.length > 1) {
+      kept = kept.slice(Math.ceil(kept.length / 2));
+      result = kept.join("\n") + "\n";
+    }
+
+    await this.fs.writeFile(this.logPath, result, "utf-8");
+  }
+}

package/src/metrics/types.ts

@@ -0,0 +1,12 @@
+export interface DecisionEntry {
+  readonly ts: string;
+  readonly command: string;
+  readonly path: string;
+  readonly projection: string;
+  readonly reason: string;
+  readonly lines: number;
+  readonly bytes: number;
+  readonly estimatedBytesAvoided?: number;
+  readonly sessionDepth?: string;
+  readonly tripwire?: string | null;
+}

package/src/operations/file-outline.ts

@@ -0,0 +1,38 @@
+import { extractOutline } from "../parser/outline.js";
+import type { OutlineEntry, JumpEntry } from "../parser/types.js";
+import type { FileSystem } from "../ports/filesystem.js";
+
+export interface FileOutlineResult {
+  [key: string]: unknown;
+  path: string;
+  outline: OutlineEntry[];
+  jumpTable: JumpEntry[];
+  partial?: boolean | undefined;
+  error?: string | undefined;
+}
+
+export async function fileOutline(
+  filePath: string,
+  opts: { fs: FileSystem },
+): Promise<FileOutlineResult> {
+  let content: string;
+  try {
+    content = await opts.fs.readFile(filePath, "utf-8");
+  } catch {
+    return {
+      path: filePath,
+      outline: [],
+      jumpTable: [],
+      error: "File not found",
+    };
+  }
+
+  const result = extractOutline(content);
+
+  return {
+    path: filePath,
+    outline: result.entries,
+    jumpTable: result.jumpTable ?? [],
+    ...(result.partial === true ? { partial: true } : {}),
+  };
+}

package/src/operations/graft-diff.ts

@@ -0,0 +1,117 @@
+import * as path from "node:path";
+import type { FileSystem } from "../ports/filesystem.js";
+import { getChangedFiles, getFileAtRef } from "../git/diff.js";
+import { detectLang } from "../parser/lang.js";
+import { extractOutline } from "../parser/outline.js";
+import { diffOutlines, OutlineDiff } from "../parser/diff.js";
+
+export interface FileDiff {
+  path: string;
+  status: "modified" | "added" | "deleted";
+  summary: string;
+  diff: OutlineDiff;
+}
+
+function buildSummary(filePath: string, status: string, diff: OutlineDiff): string {
+  const parts: string[] = [];
+  if (diff.added.length > 0) parts.push(`+${String(diff.added.length)} added`);
+  if (diff.removed.length > 0) parts.push(`-${String(diff.removed.length)} removed`);
+  if (diff.changed.length > 0) parts.push(`~${String(diff.changed.length)} changed`);
+  if (diff.unchangedCount > 0) parts.push(`=${String(diff.unchangedCount)} unchanged`);
+  const stats = parts.length > 0 ? parts.join(", ") : "no structural changes";
+  return `${filePath} | ${status} | ${stats}`;
+}
+
+export interface GraftDiffResult {
+  [key: string]: unknown;
+  base: string;
+  head: string;
+  files: FileDiff[];
+}
+
+export interface GraftDiffOptions {
+  cwd: string;
+  fs: FileSystem;
+  base?: string | undefined;
+  head?: string | undefined;
+  path?: string | undefined;
+}
+
+function emptyDiff(): OutlineDiff {
+  return new OutlineDiff({ added: [], removed: [], changed: [], unchangedCount: 0 });
+}
+
+
+/**
+ * Compute structural diffs between two git refs (or working tree).
+ */
+export function graftDiff(opts: GraftDiffOptions): GraftDiffResult {
+  const base = opts.base ?? "HEAD";
+  const headLabel = opts.head ?? "working tree";
+  const cwd = opts.cwd;
+
+  let changedFiles = getChangedFiles({
+    cwd,
+    base,
+    head: opts.head,
+  });
+
+  // Filter by path if provided
+  if (opts.path !== undefined) {
+    changedFiles = changedFiles.filter((f) => f === opts.path);
+  }
+
+  const files: FileDiff[] = [];
+
+  for (const filePath of changedFiles) {
+    const lang = detectLang(filePath);
+
+    // Get content at base (null = file absent at ref)
+    const baseContent = getFileAtRef(base, filePath, cwd);
+
+    // Get content at head (null = file absent at ref/worktree)
+    let headContent: string | null;
+    if (opts.head !== undefined) {
+      headContent = getFileAtRef(opts.head, filePath, cwd);
+    } else {
+      const fullPath = path.join(cwd, filePath);
+      try {
+        headContent = opts.fs.readFileSync(fullPath, "utf-8");
+      } catch {
+        headContent = null;
+      }
+    }
+
+    // Determine status
+    let status: "modified" | "added" | "deleted";
+    if (baseContent === null && headContent === null) {
+      // Both absent — file listed in diff but unreadable at both refs. Skip.
+      continue;
+    } else if (baseContent === null) {
+      status = "added";
+    } else if (headContent === null) {
+      status = "deleted";
+    } else {
+      status = "modified";
+    }
+
+    // Compute structural diff (only for supported languages)
+    if (lang === null) {
+      const empty = emptyDiff();
+      files.push({ path: filePath, status, summary: buildSummary(filePath, status, empty), diff: empty });
+      continue;
+    }
+
+    const baseOutline = baseContent !== null
+      ? extractOutline(baseContent, lang).entries
+      : [];
+    const headOutline = headContent !== null
+      ? extractOutline(headContent, lang).entries
+      : [];
+
+    const diff = diffOutlines(baseOutline, headOutline);
+    files.push({ path: filePath, status, summary: buildSummary(filePath, status, diff), diff });
+  }
+
+  return { base, head: headLabel, files };
+}

package/src/operations/read-range.ts

@@ -0,0 +1,65 @@
+import type { FileSystem } from "../ports/filesystem.js";
+
+const MAX_RANGE_LINES = 250;
+
+export interface ReadRangeResult {
+  [key: string]: unknown;
+  path: string;
+  content?: string | undefined;
+  startLine?: number | undefined;
+  endLine?: number | undefined;
+  reason?: string | undefined;
+  truncated?: boolean | undefined;
+  clipped?: boolean | undefined;
+}
+
+export async function readRange(
+  filePath: string,
+  start: number,
+  end: number,
+  opts: { fs: FileSystem },
+): Promise<ReadRangeResult> {
+  let raw: string;
+  try {
+    raw = await opts.fs.readFile(filePath, "utf-8");
+  } catch {
+    return { path: filePath, reason: "NOT_FOUND" };
+  }
+
+  if (start > end) {
+    return { path: filePath, reason: "INVALID_RANGE" };
+  }
+
+  const allLines = raw.split("\n");
+  const totalLines = allLines.length;
+
+  let effectiveEnd = end;
+  let truncated = false;
+  let clipped = false;
+
+  // Check if range exceeds 250 lines
+  if (effectiveEnd - start + 1 > MAX_RANGE_LINES) {
+    effectiveEnd = start + MAX_RANGE_LINES - 1;
+    truncated = true;
+  }
+
+  // Clip to EOF
+  if (effectiveEnd > totalLines) {
+    effectiveEnd = totalLines;
+    clipped = true;
+  }
+
+  // Extract lines (1-based to 0-based)
+  const selected = allLines.slice(start - 1, effectiveEnd);
+  const content = selected.join("\n");
+
+  return {
+    path: filePath,
+    content,
+    startLine: start,
+    endLine: effectiveEnd,
+    ...(truncated ? { truncated: true, reason: "RANGE_EXCEEDED" } : {}),
+    ...(clipped && !truncated ? { clipped: true } : {}),
+    ...(clipped && truncated ? { clipped: true } : {}),
+  };
+}

package/src/operations/safe-read.ts

@@ -0,0 +1,96 @@
+import { evaluatePolicy } from "../policy/evaluate.js";
+import { ContentResult, RefusedResult } from "../policy/types.js";
+import type { SessionDepth } from "../policy/types.js";
+import { extractOutline } from "../parser/outline.js";
+import type { OutlineEntry, JumpEntry } from "../parser/types.js";
+import type { FileSystem } from "../ports/filesystem.js";
+import type { JsonCodec } from "../ports/codec.js";
+
+export interface SafeReadResult {
+  [key: string]: unknown;
+  path: string;
+  projection: "content" | "outline" | "refused" | "error";
+  reason: string;
+  content?: string | undefined;
+  outline?: OutlineEntry[] | undefined;
+  jumpTable?: JumpEntry[] | undefined;
+  estimatedBytesAvoided?: number | undefined;
+  next?: string[] | undefined;
+  actual?: { lines: number; bytes: number } | undefined;
+  thresholds?: { lines: number; bytes: number } | undefined;
+  sessionDepth?: SessionDepth | undefined;
+}
+
+export interface SafeReadOptions {
+  fs: FileSystem;
+  codec: JsonCodec;
+  content?: string | undefined;
+  intent?: string | undefined;
+  sessionDepth?: SessionDepth | undefined;
+  budgetRemaining?: number | undefined;
+}
+
+export async function safeRead(
+  filePath: string,
+  options: SafeReadOptions,
+): Promise<SafeReadResult> {
+  let content: string;
+  let bytes: number;
+
+  if (options.content !== undefined) {
+    content = options.content;
+    bytes = Buffer.byteLength(content, "utf-8");
+  } else {
+    let raw: Buffer;
+    try {
+      raw = await options.fs.readFile(filePath);
+    } catch {
+      return {
+        path: filePath,
+        projection: "error",
+        reason: "NOT_FOUND",
+      };
+    }
+    content = raw.toString("utf-8");
+    bytes = raw.byteLength;
+  }
+
+  const lines = content.split("\n").length;
+
+  const policy = evaluatePolicy(
+    { path: filePath, lines, bytes },
+    { sessionDepth: options.sessionDepth, budgetRemaining: options.budgetRemaining },
+  );
+
+  const base: SafeReadResult = {
+    path: filePath,
+    projection: policy.projection,
+    reason: policy.reason,
+    actual: policy.actual,
+    thresholds: policy.thresholds,
+    ...(policy.sessionDepth !== undefined ? { sessionDepth: policy.sessionDepth } : {}),
+  };
+
+  if (policy instanceof ContentResult) {
+    return { ...base, content };
+  }
+
+  if (policy instanceof RefusedResult) {
+    return {
+      ...base,
+      next: [...policy.next],
+    };
+  }
+
+  // projection === "outline"
+  const outlineResult = extractOutline(content);
+  const outlineJson = options.codec.encode(outlineResult);
+  const estimatedBytesAvoided = bytes - Buffer.byteLength(outlineJson, "utf-8");
+
+  return {
+    ...base,
+    outline: outlineResult.entries,
+    jumpTable: outlineResult.jumpTable,
+    estimatedBytesAvoided: estimatedBytesAvoided > 0 ? estimatedBytesAvoided : 0,
+  };
+}

package/src/operations/state.ts

@@ -0,0 +1,33 @@
+import * as path from "node:path";
+import type { FileSystem } from "../ports/filesystem.js";
+
+const MAX_STATE_BYTES = 8192;
+const STATE_FILENAME = "state.md";
+
+export async function stateSave(
+  content: string,
+  opts: { graftDir: string; fs: FileSystem },
+): Promise<{ ok: boolean; reason?: string | undefined }> {
+  const bytes = Buffer.byteLength(content, "utf-8");
+  if (bytes > MAX_STATE_BYTES) {
+    return { ok: false, reason: `State exceeds 8 KB limit (${String(bytes)} bytes)` };
+  }
+
+  const filePath = path.join(opts.graftDir, STATE_FILENAME);
+  await opts.fs.mkdir(opts.graftDir, { recursive: true });
+  await opts.fs.writeFile(filePath, content, "utf-8");
+
+  return { ok: true };
+}
+
+export async function stateLoad(
+  opts: { graftDir: string; fs: FileSystem },
+): Promise<{ content: string | null }> {
+  const filePath = path.join(opts.graftDir, STATE_FILENAME);
+  try {
+    const content = await opts.fs.readFile(filePath, "utf-8");
+    return { content };
+  } catch {
+    return { content: null };
+  }
+}