@flyingrobots/graft 0.7.0 → 0.8.0

package/src/metrics/logger.ts

@@ -1,40 +0,0 @@
-import { RotatingNdjsonLog } from "../adapters/rotating-ndjson-log.js";
-import type { FileSystem } from "../ports/filesystem.js";
-import type { JsonCodec } from "../ports/codec.js";
-import { DecisionEntry } from "./types.js";
-
-export interface MetricsLoggerOptions {
-  readonly fs: FileSystem;
-  readonly codec: JsonCodec;
-  readonly maxBytes?: number;
-}
-
-export class MetricsLogger {
-  private readonly writer: RotatingNdjsonLog;
-
-  constructor(logPath: string, options: MetricsLoggerOptions) {
-    const writerOptions = {
-      logPath,
-      fs: options.fs,
-      codec: options.codec,
-      ...(options.maxBytes === undefined ? {} : { maxBytes: options.maxBytes }),
-    };
-    this.writer = new RotatingNdjsonLog(writerOptions);
-  }
-
-  async log(entry: Omit<DecisionEntry, "ts">): Promise<void> {
-    const full = new DecisionEntry({
-      ts: new Date().toISOString(),
-      command: entry.command,
-      path: entry.path,
-      projection: entry.projection,
-      reason: entry.reason,
-      lines: entry.lines,
-      bytes: entry.bytes,
-      estimatedBytesAvoided: entry.estimatedBytesAvoided,
-      sessionDepth: entry.sessionDepth,
-      tripwire: entry.tripwire,
-    });
-    await this.writer.append(full);
-  }
-}

package/src/metrics/types.ts

@@ -1,40 +0,0 @@
-// ---------------------------------------------------------------------------
-// DecisionEntry — runtime-backed metric event for policy decisions
-// ---------------------------------------------------------------------------
-
-export class 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 | undefined;
-  readonly sessionDepth?: string | undefined;
-  readonly tripwire?: string | null | undefined;
-
-  constructor(fields: {
-    readonly ts: string;
-    readonly command: string;
-    readonly path: string;
-    readonly projection: string;
-    readonly reason: string;
-    readonly lines: number;
-    readonly bytes: number;
-    readonly estimatedBytesAvoided?: number | undefined;
-    readonly sessionDepth?: string | undefined;
-    readonly tripwire?: string | null | undefined;
-  }) {
-    this.ts = fields.ts;
-    this.command = fields.command;
-    this.path = fields.path;
-    this.projection = fields.projection;
-    this.reason = fields.reason;
-    this.lines = fields.lines;
-    this.bytes = fields.bytes;
-    this.estimatedBytesAvoided = fields.estimatedBytesAvoided;
-    this.sessionDepth = fields.sessionDepth;
-    this.tripwire = fields.tripwire;
-  }
-}

package/src/operations/adaptive-projection.ts

@@ -1,54 +0,0 @@
-// ---------------------------------------------------------------------------
-// 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

@@ -1,59 +0,0 @@
-// ---------------------------------------------------------------------------
-// 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/cached-file.ts

@@ -1,40 +0,0 @@
-import { extractOutlineForFile } from "../parser/outline.js";
-import { detectStructuredFormat } from "../parser/lang.js";
-import type { SupportedStructuredFormat } from "../parser/lang.js";
-import type { OutlineEntry, JumpEntry } from "../parser/types.js";
-import { hashContent } from "./observation-cache.js";
-
-/**
- * Immutable snapshot of a file read. Built once from a single read,
- * shared by all consumers (cache, policy, outline extraction) to eliminate
- * TOCTOU races where the file changes between reads.
- */
-export class CachedFile {
-  /** @internal */
-  private readonly _brand = "CachedFile" as const;
-  readonly path: string;
-  readonly rawContent: string;
-  readonly hash: string;
-  readonly lang: SupportedStructuredFormat | null;
-  readonly supportsOutline: boolean;
-  readonly outline: readonly OutlineEntry[];
-  readonly jumpTable: readonly JumpEntry[];
-  readonly actual: { readonly lines: number; readonly bytes: number };
-
-  constructor(filePath: string, rawContent: string) {
-    this.path = filePath;
-    this.rawContent = rawContent;
-    this.hash = hashContent(rawContent);
-    this.actual = {
-      lines: rawContent.split("\n").length,
-      bytes: Buffer.byteLength(rawContent),
-    };
-    this.lang = detectStructuredFormat(filePath);
-    this.supportsOutline = this.lang !== null;
-    const result = extractOutlineForFile(filePath, rawContent);
-    this.outline = result?.entries ?? [];
-    this.jumpTable = result?.jumpTable ?? [];
-    Object.freeze(this.actual);
-    Object.freeze(this);
-  }
-}

package/src/operations/capture-range.ts

@@ -1,64 +0,0 @@
-// ---------------------------------------------------------------------------
-// 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

@@ -1,82 +0,0 @@
-// ---------------------------------------------------------------------------
-// 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

@@ -1,104 +0,0 @@
-// ---------------------------------------------------------------------------
-// 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

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