@flyingrobots/graft 0.3.1

package/src/policy/evaluate.ts

@@ -0,0 +1,178 @@
+import picomatch from "picomatch";
+import type { PolicyInput, PolicyOptions, ReasonCode, SessionDepth } from "./types.js";
+import { ContentResult, OutlineResult, RefusedResult } from "./types.js";
+import type { PolicyResult } from "./types.js";
+
+export const STATIC_THRESHOLDS = { lines: 150, bytes: 12288 } as const;
+
+const SESSION_BYTE_CAPS: Record<string, number> = {
+  early: 20480,
+  mid: 10240,
+  late: 4096,
+};
+
+const BINARY_EXTENSIONS = new Set([
+  ".png", ".jpg", ".jpeg", ".gif", ".pdf", ".zip",
+  ".wasm", ".bin", ".sqlite", ".mp4", ".mov", ".ico",
+]);
+
+const LOCKFILE_NAMES = new Set([
+  "package-lock.json", "pnpm-lock.yaml", "yarn.lock",
+  "Gemfile.lock", "poetry.lock", "Cargo.lock",
+  "composer.lock", "Pipfile.lock",
+]);
+
+const BUILD_OUTPUT_PREFIXES = ["dist/", "build/", ".next/", "out/", "target/"];
+
+const SECRET_PATTERNS: ((name: string) => boolean)[] = [
+  (n) => n === ".env" || (n.startsWith(".env.") && !n.endsWith(".example")),
+  (n) => n.endsWith(".pem"),
+  (n) => n.endsWith(".key"),
+  (n) => n.startsWith("credentials."),
+];
+
+function basename(path: string): string {
+  const i = path.lastIndexOf("/");
+  return i === -1 ? path : path.slice(i + 1);
+}
+
+function extname(path: string): string {
+  const name = basename(path);
+  const i = name.lastIndexOf(".");
+  return i <= 0 ? "" : name.slice(i);
+}
+
+function checkBan(path: string): { reason: ReasonCode; reasonDetail: string; next: string[] } | undefined {
+  const name = basename(path);
+  const ext = extname(path).toLowerCase();
+
+  if (BINARY_EXTENSIONS.has(ext)) {
+    return {
+      reason: "BINARY",
+      reasonDetail: `Binary file (${ext}) cannot be usefully read`,
+      next: ["Use file_outline to see metadata", "Check for a text alternative"],
+    };
+  }
+
+  if (LOCKFILE_NAMES.has(name)) {
+    return {
+      reason: "LOCKFILE",
+      reasonDetail: `Lockfile ${name} is machine-generated and not useful to read`,
+      next: ["Read package.json for dependency info instead"],
+    };
+  }
+
+  if (name.endsWith(".min.js") || name.endsWith(".min.css")) {
+    return {
+      reason: "MINIFIED",
+      reasonDetail: `Minified file ${name} is not human-readable`,
+      next: ["Look for the unminified source"],
+    };
+  }
+
+  for (const prefix of BUILD_OUTPUT_PREFIXES) {
+    if (path.includes("/" + prefix) || path.startsWith(prefix)) {
+      return {
+        reason: "BUILD_OUTPUT",
+        reasonDetail: `Build output path ${prefix} contains generated files`,
+        next: ["Try reading src/ instead of dist/"],
+      };
+    }
+  }
+
+  for (const check of SECRET_PATTERNS) {
+    if (check(name)) {
+      return {
+        reason: "SECRET",
+        reasonDetail: `${name} may contain secrets and should not be read`,
+        next: ["Check for a .example or template version"],
+      };
+    }
+  }
+
+  return undefined;
+}
+
+export function evaluatePolicy(input: PolicyInput, options?: PolicyOptions): PolicyResult {
+  const { path, lines, bytes } = input;
+  const actual = { lines, bytes };
+  const thresholds = { ...STATIC_THRESHOLDS };
+  const sessionDepth: SessionDepth | undefined = options?.sessionDepth;
+
+  // 1. Bans first
+  const ban = checkBan(path);
+  if (ban !== undefined) {
+    return new RefusedResult({
+      reason: ban.reason,
+      reasonDetail: ban.reasonDetail,
+      next: ban.next,
+      thresholds,
+      actual,
+      ...(sessionDepth !== undefined ? { sessionDepth } : {}),
+    });
+  }
+
+  // 2. Graftignore
+  const patterns = options?.graftignorePatterns;
+  if (patterns !== undefined && patterns.length > 0) {
+    const isMatch = picomatch(patterns);
+    if (isMatch(path)) {
+      return new RefusedResult({
+        reason: "GRAFTIGNORE",
+        reasonDetail: "File matches .graftignore pattern",
+        next: ["Check .graftignore if this file should be readable"],
+        thresholds,
+        actual,
+        ...(sessionDepth !== undefined ? { sessionDepth } : {}),
+      });
+    }
+  }
+
+  // 3. Determine effective byte cap
+  // When session depth is known (not "unknown"), the session cap replaces the static byte threshold.
+  // Static line threshold always applies.
+  const hasSessionCap = sessionDepth !== undefined && sessionDepth !== "unknown";
+  let effectiveByteCap = hasSessionCap
+    ? SESSION_BYTE_CAPS[sessionDepth] ?? STATIC_THRESHOLDS.bytes
+    : STATIC_THRESHOLDS.bytes;
+
+  // 4. Budget cap — no single read should exceed 5% of remaining budget
+  const MAX_READ_FRACTION = 0.05;
+  const budgetRemaining = options?.budgetRemaining;
+  const hasBudgetCap = budgetRemaining !== undefined && budgetRemaining >= 0;
+  let budgetTriggered = false;
+  if (hasBudgetCap) {
+    const budgetCap = Math.floor(budgetRemaining * MAX_READ_FRACTION);
+    if (budgetCap < effectiveByteCap) {
+      effectiveByteCap = budgetCap;
+      budgetTriggered = true;
+    }
+  }
+
+  const exceedsLines = lines > STATIC_THRESHOLDS.lines;
+  const exceedsBytes = bytes > effectiveByteCap;
+
+  if (!exceedsLines && !exceedsBytes) {
+    return new ContentResult({
+      thresholds,
+      actual,
+      ...(sessionDepth !== undefined ? { sessionDepth } : {}),
+    });
+  }
+
+  // Determine reason: BUDGET_CAP > SESSION_CAP > OUTLINE
+  const finalReason: "OUTLINE" | "SESSION_CAP" | "BUDGET_CAP" = exceedsLines && !exceedsBytes
+    ? "OUTLINE"
+    : exceedsBytes && budgetTriggered
+      ? "BUDGET_CAP"
+      : exceedsBytes && hasSessionCap
+        ? "SESSION_CAP"
+        : "OUTLINE";
+
+  return new OutlineResult({
+    reason: finalReason,
+    thresholds,
+    actual,
+    ...(sessionDepth !== undefined ? { sessionDepth } : {}),
+  });
+}

package/src/policy/graftignore.ts

@@ -0,0 +1,6 @@
+export function loadGraftignore(content: string): string[] {
+  return content
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith("#"));
+}

package/src/policy/types.ts

@@ -0,0 +1,86 @@
+export type ReasonCode =
+  | "CONTENT"
+  | "OUTLINE"
+  | "SESSION_CAP"
+  | "BINARY"
+  | "LOCKFILE"
+  | "MINIFIED"
+  | "BUILD_OUTPUT"
+  | "SECRET"
+  | "GRAFTIGNORE"
+  | "BUDGET_CAP";
+
+export type SessionDepth = "early" | "mid" | "late" | "unknown";
+
+export interface PolicyInput {
+  path: string;
+  lines: number;
+  bytes: number;
+}
+
+export interface PolicyOptions {
+  graftignorePatterns?: string[] | undefined;
+  sessionDepth?: SessionDepth | undefined;
+  budgetRemaining?: number | undefined;
+}
+
+// Shared fields for all results
+interface PolicyResultBase {
+  readonly thresholds: { readonly lines: number; readonly bytes: number };
+  readonly actual: { readonly lines: number; readonly bytes: number };
+  readonly sessionDepth?: SessionDepth | undefined;
+}
+
+export class ContentResult implements PolicyResultBase {
+  readonly projection = "content" as const;
+  readonly reason = "CONTENT" as const;
+  readonly thresholds: { readonly lines: number; readonly bytes: number };
+  readonly actual: { readonly lines: number; readonly bytes: number };
+  readonly sessionDepth?: SessionDepth | undefined;
+
+  constructor(opts: { thresholds: { lines: number; bytes: number }; actual: { lines: number; bytes: number }; sessionDepth?: SessionDepth | undefined }) {
+    this.thresholds = Object.freeze({ ...opts.thresholds });
+    this.actual = Object.freeze({ ...opts.actual });
+    if (opts.sessionDepth !== undefined) this.sessionDepth = opts.sessionDepth;
+    Object.freeze(this);
+  }
+}
+
+export class OutlineResult implements PolicyResultBase {
+  readonly projection = "outline" as const;
+  readonly reason: "OUTLINE" | "SESSION_CAP" | "BUDGET_CAP";
+  readonly thresholds: { readonly lines: number; readonly bytes: number };
+  readonly actual: { readonly lines: number; readonly bytes: number };
+  readonly sessionDepth?: SessionDepth | undefined;
+
+  constructor(opts: { reason: "OUTLINE" | "SESSION_CAP" | "BUDGET_CAP"; thresholds: { lines: number; bytes: number }; actual: { lines: number; bytes: number }; sessionDepth?: SessionDepth | undefined }) {
+    this.reason = opts.reason;
+    this.thresholds = Object.freeze({ ...opts.thresholds });
+    this.actual = Object.freeze({ ...opts.actual });
+    if (opts.sessionDepth !== undefined) this.sessionDepth = opts.sessionDepth;
+    Object.freeze(this);
+  }
+}
+
+export class RefusedResult implements PolicyResultBase {
+  readonly projection = "refused" as const;
+  readonly reason: ReasonCode;
+  readonly reasonDetail: string;
+  readonly next: readonly string[];
+  readonly thresholds: { readonly lines: number; readonly bytes: number };
+  readonly actual: { readonly lines: number; readonly bytes: number };
+  readonly sessionDepth?: SessionDepth | undefined;
+
+  constructor(opts: { reason: ReasonCode; reasonDetail: string; next: string[]; thresholds: { lines: number; bytes: number }; actual: { lines: number; bytes: number }; sessionDepth?: SessionDepth | undefined }) {
+    this.reason = opts.reason;
+    this.reasonDetail = opts.reasonDetail;
+    this.next = Object.freeze([...opts.next]);
+    this.thresholds = Object.freeze({ ...opts.thresholds });
+    this.actual = Object.freeze({ ...opts.actual });
+    if (opts.sessionDepth !== undefined) this.sessionDepth = opts.sessionDepth;
+    Object.freeze(this);
+  }
+}
+
+// Union type for callers that need the general type
+export type PolicyResult = ContentResult | OutlineResult | RefusedResult;

package/src/ports/codec.ts

@@ -0,0 +1,13 @@
+// ---------------------------------------------------------------------------
+// JsonCodec port — hexagonal boundary for JSON serialization
+// ---------------------------------------------------------------------------
+
+/**
+ * Portable JSON codec interface. Core logic imports this port, not
+ * JSON.stringify/JSON.parse directly. Implementations control key
+ * ordering, whitespace, and determinism.
+ */
+export interface JsonCodec {
+  encode(value: unknown): string;
+  decode(data: string): unknown;
+}

package/src/ports/filesystem.ts

@@ -0,0 +1,17 @@
+// ---------------------------------------------------------------------------
+// FileSystem port — hexagonal boundary for file I/O
+// ---------------------------------------------------------------------------
+
+/**
+ * Portable filesystem interface. Core logic imports this port, not node:fs.
+ * Node adapter implements it; tests can substitute a mock.
+ */
+export interface FileSystem {
+  readFile(path: string, encoding: "utf-8"): Promise<string>;
+  readFile(path: string): Promise<Buffer>;
+  writeFile(path: string, data: string, encoding: "utf-8"): Promise<void>;
+  appendFile(path: string, data: string, encoding: "utf-8"): Promise<void>;
+  mkdir(path: string, options: { recursive: true }): Promise<void>;
+  stat(path: string): Promise<{ size: number }>;
+  readFileSync(path: string, encoding: "utf-8"): string;
+}

package/src/session/tracker.ts

@@ -0,0 +1,114 @@
+import { Tripwire } from "./types.js";
+import type { SessionDepth } from "./types.js";
+
+const EDIT_BASH_TOOLS = new Set(["Edit", "Bash"]);
+const LATE_READ_BYTE_THRESHOLD = 20480;
+const LATE_READ_MESSAGE_THRESHOLD = 300;
+
+export class SessionTracker {
+  private totalMessages = 0;
+  private toolCallsSinceUser = 0;
+  private editBashTransitions = 0;
+  private lastEditBashTool: string | null = null;
+  private budgetBytes: number | null = null;
+  private consumedBytes = 0;
+
+  getMessageCount(): number {
+    return this.totalMessages;
+  }
+
+  recordMessage(): void {
+    this.totalMessages++;
+  }
+
+  recordToolCall(toolName: string): void {
+    this.toolCallsSinceUser++;
+
+    if (EDIT_BASH_TOOLS.has(toolName)) {
+      // Count full Edit→Bash cycles, not individual alternations.
+      // Each Edit followed by Bash is one cycle.
+      if (this.lastEditBashTool === "Edit" && toolName === "Bash") {
+        this.editBashTransitions++;
+      }
+      this.lastEditBashTool = toolName;
+    }
+  }
+
+  recordUserMessage(): void {
+    this.toolCallsSinceUser = 0;
+  }
+
+  checkTripwires(): Tripwire[] {
+    const wires: Tripwire[] = [];
+
+    if (this.totalMessages > 500) {
+      wires.push(new Tripwire({
+        signal: "SESSION_LONG",
+        recommendation:
+          "Session exceeds 500 messages. Use state_save to persist context and start a new session.",
+      }));
+    }
+
+    if (this.editBashTransitions > 30) {
+      wires.push(new Tripwire({
+        signal: "EDIT_BASH_LOOP",
+        recommendation:
+          "Detected repeated edit/bash cycling. Step back and rethink the approach.",
+      }));
+    }
+
+    if (this.toolCallsSinceUser > 80) {
+      wires.push(new Tripwire({
+        signal: "RUNAWAY_TOOLS",
+        recommendation:
+          "Over 80 tool calls without user input. Pause and check in with the user.",
+      }));
+    }
+
+    return wires;
+  }
+
+  checkLateRead(outputBytes: number): Tripwire | null {
+    if (
+      outputBytes > LATE_READ_BYTE_THRESHOLD &&
+      this.totalMessages > LATE_READ_MESSAGE_THRESHOLD
+    ) {
+      return new Tripwire({
+        signal: "LATE_LARGE_READ",
+        recommendation:
+          "Large read late in session. Use file_outline or read_range instead.",
+      });
+    }
+    return null;
+  }
+
+  setBudget(bytes: number): void {
+    if (bytes <= 0) throw new Error("Budget must be positive");
+    this.budgetBytes = bytes;
+  }
+
+  recordBytesConsumed(bytes: number): void {
+    this.consumedBytes += bytes;
+  }
+
+  getBudget(): { total: number; consumed: number; remaining: number; fraction: number } | null {
+    if (this.budgetBytes === null) return null;
+    const remaining = Math.max(0, this.budgetBytes - this.consumedBytes);
+    return {
+      total: this.budgetBytes,
+      consumed: this.consumedBytes,
+      remaining,
+      fraction: Math.round((this.consumedBytes / this.budgetBytes) * 1000) / 1000,
+    };
+  }
+
+  getSessionDepth(): SessionDepth {
+    if (this.totalMessages < 100) {
+      return "early";
+    }
+    if (this.totalMessages <= 500) {
+      return "mid";
+    }
+    return "late";
+  }
+}

package/src/session/types.ts

@@ -0,0 +1,20 @@
+export class Tripwire {
+  /** @internal */
+  private readonly _brand = "Tripwire" as const;
+  readonly signal: string;
+  readonly recommendation: string;
+
+  constructor(opts: { signal: string; recommendation: string }) {
+    if (opts.signal.trim().length === 0) {
+      throw new Error("Tripwire: signal must be non-empty");
+    }
+    if (opts.recommendation.trim().length === 0) {
+      throw new Error("Tripwire: recommendation must be non-empty");
+    }
+    this.signal = opts.signal.trim();
+    this.recommendation = opts.recommendation.trim();
+    Object.freeze(this);
+  }
+}
+
+export type SessionDepth = "early" | "mid" | "late";