@flyingrobots/graft 0.5.0 → 0.6.1

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

@@ -1,12 +1,13 @@
 import { z } from "zod";
-import { safeRead } from "../../operations/safe-read.js";
-import type { SafeReadResult } from "../../operations/safe-read.js";
+import { safeRead, type SafeReadResult } from "../../operations/safe-read.js";
+import { toJsonObject } from "../../operations/result-dto.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 { evaluateMcpPolicy, toPolicyPath } from "../policy.js";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import { evaluateMcpPolicy } from "../policy.js";
+import { toRepoPolicyPath } from "../../adapters/repo-paths.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 
 const PROJECTION_METRICS: Readonly<Record<string, ((m: Metrics) => void) | undefined>> = {
   content: (m) => { m.recordRead(); },
@@ -24,9 +25,10 @@ export const safeReadTool: ToolDefinition = {
     "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) => {
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
       const filePath = ctx.resolvePath(args["path"] as string);
+      ctx.recordFootprint({ paths: [filePath] });
 
       // Build CachedFile once — all consumers share the same snapshot,
       // eliminating TOCTOU races where the file changes between reads.
@@ -58,6 +60,9 @@ export const safeReadTool: ToolDefinition = {
 
           cacheResult.obs.touch();
           ctx.metrics.recordCacheHit(cf.actual.bytes);
+          ctx.recordFootprint({
+            symbols: cacheResult.obs.outline.map((e) => e.name),
+          });
           return ctx.respond("safe_read", {
             path: filePath,
             projection: "cache_hit",
@@ -90,6 +95,9 @@ export const safeReadTool: ToolDefinition = {
           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);
+          ctx.recordFootprint({
+            symbols: cf.outline.map((e) => e.name),
+          });
           const updatedObs = ctx.cache.get(filePath);
           return ctx.respond("safe_read", {
             path: filePath,
@@ -111,13 +119,16 @@ export const safeReadTool: ToolDefinition = {
         codec: ctx.codec,
         content: cf?.rawContent,
         intent: args["intent"] as string | undefined,
-        policyPath: toPolicyPath(ctx.projectRoot, filePath),
+        policyPath: toRepoPolicyPath(ctx.projectRoot, filePath),
         graftignorePatterns: [...ctx.graftignorePatterns],
-        sessionDepth: ctx.session.getSessionDepth(),
-        budgetRemaining: ctx.session.getBudget()?.remaining,
+        sessionDepth: ctx.governor.getGovernorDepth(),
+        budgetRemaining: ctx.governor.getBudget()?.remaining,
       });
 
       PROJECTION_METRICS[result.projection]?.(ctx.metrics);
+      if (result.outline !== undefined) {
+        ctx.recordFootprint({ symbols: result.outline.map((e) => e.name) });
+      }
 
       // Record observation for cacheable projections — uses CachedFile
       // outline (no re-read) to eliminate the snapshot race.
@@ -131,7 +142,7 @@ export const safeReadTool: ToolDefinition = {
         ctx.cache.record(filePath, cf.hash, cf.outline, cf.jumpTable, result.actual);
       }
 
-      return ctx.respond("safe_read", result);
+      return ctx.respond("safe_read", toJsonObject(result));
     };
   },
 };

package/src/mcp/tools/since.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { graftDiff } from "../../operations/graft-diff.js";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 import { evaluateMcpRefusal } from "../policy.js";
 
 export const sinceTool: ToolDefinition = {
@@ -13,8 +13,8 @@ export const sinceTool: ToolDefinition = {
     base: z.string(),
     head: z.string().optional(),
   },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async (args) => {
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
       const base = args["base"] as string;
       const head = (args["head"] as string | undefined) ?? "HEAD";
 
@@ -39,6 +39,10 @@ export const sinceTool: ToolDefinition = {
         totalChanged += file.diff.changed.length;
       }
 
+      ctx.recordFootprint({
+        paths: result.files.map((f) => f.path),
+      });
+
       return ctx.respond("graft_since", {
         ...result,
         summary: `+${String(totalAdded)} added, -${String(totalRemoved)} removed, ~${String(totalChanged)} changed across ${String(result.files.length)} files`,

package/src/mcp/tools/state.ts

@@ -1,7 +1,8 @@
 import * as path from "node:path";
 import { z } from "zod";
 import { STATE_FILENAME, stateSave, stateLoad } from "../../operations/state.js";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
+import { toJsonObject } from "../../operations/result-dto.js";
 
 export const stateSaveTool: ToolDefinition = {
   name: "state_save",
@@ -9,14 +10,14 @@ export const stateSaveTool: ToolDefinition = {
     "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) => {
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
       const result = await stateSave(args["content"] as string, {
         stateDir: ctx.graftDir,
         statePath: path.join(ctx.graftDir, STATE_FILENAME),
         fs: ctx.fs,
       });
-      return ctx.respond("state_save", result as Record<string, unknown>);
+      return ctx.respond("state_save", toJsonObject(result));
     };
   },
 };
@@ -26,13 +27,13 @@ export const stateLoadTool: ToolDefinition = {
   description:
     "Load previously saved session state. Returns null if no state has " +
     "been saved.",
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async () => {
+  createHandler(): ToolHandler {
+    return async (_args, ctx) => {
       const result = await stateLoad({
         statePath: path.join(ctx.graftDir, STATE_FILENAME),
         fs: ctx.fs,
       });
-      return ctx.respond("state_load", result as Record<string, unknown>);
+      return ctx.respond("state_load", toJsonObject(result));
     };
   },
 };

package/src/mcp/tools/stats.ts

@@ -1,13 +1,13 @@
 import { totalNonReadBytesReturned } from "../burden.js";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 
 export const statsTool: ToolDefinition = {
   name: "stats",
   description:
     "Decision metrics for the current session. Total reads, outlines, " +
     "refusals, cache hits, bytes avoided, and burden by tool kind.",
-  createHandler(ctx: ToolContext): ToolHandler {
-    return () => {
+  createHandler(): ToolHandler {
+    return (_args, ctx) => {
       const snap = ctx.metrics.snapshot();
       return ctx.respond("stats", {
         totalReads: snap.reads,

package/src/mcp/tools/workspace-authorizations.ts

@@ -1,11 +1,11 @@
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 
 export const workspaceAuthorizationsTool: ToolDefinition = {
   name: "workspace_authorizations",
   description:
     "List daemon-authorized workspaces, their capability posture, and active bound-session counts.",
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async () => {
+  createHandler(): ToolHandler {
+    return async (_args, ctx) => {
       return ctx.respond("workspace_authorizations", {
         workspaces: await ctx.listWorkspaceAuthorizations(),
       });

package/src/mcp/tools/workspace-authorize.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 
 export const workspaceAuthorizeTool: ToolDefinition = {
   name: "workspace_authorize",
@@ -9,8 +9,8 @@ export const workspaceAuthorizeTool: ToolDefinition = {
     cwd: z.string(),
     runCapture: z.boolean().optional(),
   },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async (args) => {
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
       return ctx.respond("workspace_authorize", { ...await ctx.authorizeWorkspace({
         cwd: args["cwd"] as string,
         runCapture: args["runCapture"] as boolean | undefined,

package/src/mcp/tools/workspace-bind.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 
 export const workspaceBindTool: ToolDefinition = {
   name: "workspace_bind",
@@ -11,8 +11,8 @@ export const workspaceBindTool: ToolDefinition = {
     gitCommonDir: z.string().optional(),
     repoId: z.string().optional(),
   },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async (args) => {
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
       const result = await ctx.bindWorkspace({
         cwd: args["cwd"] as string,
         worktreeRoot: args["worktreeRoot"] as string | undefined,

package/src/mcp/tools/workspace-rebind.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 
 export const workspaceRebindTool: ToolDefinition = {
   name: "workspace_rebind",
@@ -11,8 +11,8 @@ export const workspaceRebindTool: ToolDefinition = {
     gitCommonDir: z.string().optional(),
     repoId: z.string().optional(),
   },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async (args) => {
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
       const result = await ctx.rebindWorkspace({
         cwd: args["cwd"] as string,
         worktreeRoot: args["worktreeRoot"] as string | undefined,

package/src/mcp/tools/workspace-revoke.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 
 export const workspaceRevokeTool: ToolDefinition = {
   name: "workspace_revoke",
@@ -8,8 +8,8 @@ export const workspaceRevokeTool: ToolDefinition = {
   schema: {
     cwd: z.string(),
   },
-  createHandler(ctx: ToolContext): ToolHandler {
-    return async (args) => {
+  createHandler(): ToolHandler {
+    return async (args, ctx) => {
       return ctx.respond("workspace_revoke", { ...await ctx.revokeWorkspace({
         cwd: args["cwd"] as string,
       }) });

package/src/mcp/tools/workspace-status.ts

@@ -1,11 +1,11 @@
-import type { ToolDefinition, ToolContext, ToolHandler } from "../context.js";
+import type { ToolDefinition, ToolHandler } from "../context.js";
 
 export const workspaceStatusTool: ToolDefinition = {
   name: "workspace_status",
   description:
     "Return the current daemon workspace binding state and resolved capability profile.",
-  createHandler(ctx: ToolContext): ToolHandler {
-    return () => {
+  createHandler(): ToolHandler {
+    return (_args, ctx) => {
       return ctx.respond("workspace_status", { ...ctx.getWorkspaceStatus() });
     };
   },

package/src/mcp/warp-pool.ts

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

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

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import type { JsonObject } from "../contracts/json-object.js";
+
+export const attributedReadArgsSchema = z.object({
+  path: z.string(),
+}).catchall(z.unknown());
+
+const safeReadObservationResultSchema = z.object({
+  projection: z.enum(["content", "outline", "cache_hit", "diff"]),
+  reason: z.string().optional(),
+}).catchall(z.unknown());
+
+const fileOutlineObservationResultSchema = z.object({
+  reason: z.string().optional(),
+  error: z.string().optional(),
+}).catchall(z.unknown());
+
+const readRangeObservationResultSchema = z.object({
+  content: z.string(),
+  startLine: z.number().int(),
+  endLine: z.number().int(),
+  reason: z.string().optional(),
+}).catchall(z.unknown());
+
+export type AttributedReadArgs = z.infer<typeof attributedReadArgsSchema>;
+export type SafeReadObservationResult = z.infer<typeof safeReadObservationResultSchema>;
+export type FileOutlineObservationResult = z.infer<typeof fileOutlineObservationResultSchema>;
+export type ReadRangeObservationResult = z.infer<typeof readRangeObservationResultSchema>;
+
+export function parseAttributedReadArgs(args: JsonObject): AttributedReadArgs | null {
+  const parsed = attributedReadArgsSchema.safeParse(args);
+  return parsed.success ? parsed.data : null;
+}
+
+export function parseSafeReadObservationResult(result: JsonObject): SafeReadObservationResult | null {
+  const parsed = safeReadObservationResultSchema.safeParse(result);
+  return parsed.success ? parsed.data : null;
+}
+
+export function parseFileOutlineObservationResult(result: JsonObject): FileOutlineObservationResult | null {
+  const parsed = fileOutlineObservationResultSchema.safeParse(result);
+  return parsed.success ? parsed.data : null;
+}
+
+export function parseReadRangeObservationResult(result: JsonObject): ReadRangeObservationResult | null {
+  const parsed = readRangeObservationResultSchema.safeParse(result);
+  return parsed.success ? parsed.data : null;
+}

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;
+}