@flyingrobots/graft 0.5.0 → 0.6.0

package/src/cli/peer-command.ts

@@ -0,0 +1,59 @@
+import * as path from "node:path";
+import { CanonicalJsonCodec } from "../adapters/canonical-json.js";
+import type { CliCommandName, McpToolName } from "../contracts/capabilities.js";
+import { type JsonObject, parseJsonTextObject } from "../contracts/json-object.js";
+import {
+  attachCliSchemaMeta,
+  validateCliOutput,
+} from "../contracts/output-schemas.js";
+import { createGraftServer, type McpToolResult } from "../mcp/server.js";
+import { renderActivityView } from "./activity-render.js";
+
+const codec = new CanonicalJsonCodec();
+
+export interface Writer {
+  write(chunk: string): unknown;
+}
+
+function parseToolResult(result: McpToolResult): JsonObject {
+  const payload = result.content.find((item) => item.type === "text");
+  if (payload === undefined) {
+    throw new Error("Tool result did not contain a text payload");
+  }
+  return parseJsonTextObject(payload.text, "Tool result");
+}
+
+export function writeLine(writer: Writer, line = ""): void {
+  writer.write(`${line}\n`);
+}
+
+export function emitPeerCommand(
+  command: CliCommandName,
+  data: JsonObject,
+  json: boolean,
+  writer: Writer,
+): void {
+  const { _schema: _mcpSchema, ...rest } = data;
+  const validated = validateCliOutput(command, attachCliSchemaMeta(command, rest));
+  if (json) {
+    writer.write(`${codec.encode(validated)}\n`);
+    return;
+  }
+  if (command === "diag_activity") {
+    writer.write(`${renderActivityView(validated)}\n`);
+    return;
+  }
+  writer.write(`${JSON.stringify(validated, null, 2)}\n`);
+}
+
+export async function invokePeerCommand(
+  cwd: string,
+  tool: McpToolName,
+  args: JsonObject,
+): Promise<JsonObject> {
+  const server = createGraftServer({
+    projectRoot: cwd,
+    graftDir: path.join(cwd, ".graft"),
+  });
+  return parseToolResult(await server.callTool(tool, args));
+}

package/src/contracts/capabilities.ts

@@ -40,6 +40,7 @@ export type McpToolName = typeof MCP_TOOL_NAMES[number];
 export const CLI_COMMAND_NAMES = [
   "init",
   "index",
+  "migrate_local_history",
   "read_safe",
   "read_outline",
   "read_range",
@@ -51,6 +52,7 @@ export const CLI_COMMAND_NAMES = [
   "symbol_find",
   "diag_doctor",
   "diag_activity",
+  "diag_local_history_dag",
   "diag_explain",
   "diag_stats",
   "diag_capture",
@@ -58,264 +60,349 @@ export const CLI_COMMAND_NAMES = [
 
 export type CliCommandName = typeof CLI_COMMAND_NAMES[number];
 
+export const ENTRYPOINT_SURFACES = ["api", "cli", "mcp"] as const;
+
+export type EntrypointSurface = typeof ENTRYPOINT_SURFACES[number];
+
+export type ApiExposure = "tool_bridge" | "repo_workspace" | "structured_buffer";
+
+export type CliMcpParity = "peer" | "cli_only" | "mcp_only" | "not_applicable";
+
+export interface CapabilityMatrixRow {
+  readonly id: string;
+  readonly api: "Yes" | "No";
+  readonly cli: "Yes" | "No";
+  readonly mcp: "Yes" | "No";
+  readonly apiExposure: ApiExposure | "-";
+  readonly cliMcpParity: CliMcpParity;
+  readonly cliPath: string;
+  readonly mcpTool: McpToolName | "-";
+}
+
+export interface ThreeSurfaceCapabilityBaseline {
+  readonly cliOnly: number;
+  readonly apiCliMcp: number;
+  readonly apiMcp: number;
+  readonly apiOnly: number;
+}
+
 export interface CapabilityDefinition {
   readonly id: string;
   readonly description: string;
   readonly mcpTool?: McpToolName | undefined;
   readonly cliCommand?: CliCommandName | undefined;
   readonly cliPath?: readonly [string, ...string[]] | undefined;
-  readonly parity: "peer" | "cli_only" | "mcp_only";
+  readonly apiExposure?: ApiExposure | undefined;
+  readonly surfaces: readonly EntrypointSurface[];
+  readonly cliMcpParity: CliMcpParity;
+}
+
+interface CapabilitySeed {
+  readonly id: string;
+  readonly description: string;
+  readonly mcpTool?: McpToolName | undefined;
+  readonly cliCommand?: CliCommandName | undefined;
+  readonly cliPath?: readonly [string, ...string[]] | undefined;
+  readonly apiExposure?: ApiExposure | undefined;
+  readonly cliMcpParity: CliMcpParity;
+}
+
+function defineCapability(seed: CapabilitySeed): CapabilityDefinition {
+  const apiExposure = seed.apiExposure ?? (seed.mcpTool !== undefined ? "tool_bridge" : undefined);
+  const surfaces: EntrypointSurface[] = [];
+  if (apiExposure !== undefined) {
+    surfaces.push("api");
+  }
+  if (seed.cliCommand !== undefined) {
+    surfaces.push("cli");
+  }
+  if (seed.mcpTool !== undefined) {
+    surfaces.push("mcp");
+  }
+  return {
+    ...seed,
+    ...(apiExposure !== undefined ? { apiExposure } : {}),
+    surfaces: Object.freeze(surfaces),
+  };
 }
 
 export const CAPABILITY_REGISTRY: readonly CapabilityDefinition[] = [
-  {
+  defineCapability({
     id: "init",
     description: "Initialize graft in a repo",
     cliCommand: "init",
     cliPath: ["init"],
-    parity: "cli_only",
-  },
-  {
+    cliMcpParity: "cli_only",
+  }),
+  defineCapability({
     id: "index",
     description: "Explicit WARP indexing",
     cliCommand: "index",
     cliPath: ["index"],
-    parity: "cli_only",
-  },
-  {
+    cliMcpParity: "cli_only",
+  }),
+  defineCapability({
+    id: "migrate_local_history",
+    description: "Import legacy JSON local history into the WARP graph",
+    cliCommand: "migrate_local_history",
+    cliPath: ["migrate", "local-history"],
+    cliMcpParity: "cli_only",
+  }),
+  defineCapability({
     id: "safe_read",
     description: "Policy-enforced file read",
     mcpTool: "safe_read",
     cliCommand: "read_safe",
     cliPath: ["read", "safe"],
-    parity: "peer",
-  },
-  {
+    apiExposure: "repo_workspace",
+    cliMcpParity: "peer",
+  }),
+  defineCapability({
     id: "file_outline",
     description: "Structural file outline",
     mcpTool: "file_outline",
     cliCommand: "read_outline",
     cliPath: ["read", "outline"],
-    parity: "peer",
-  },
-  {
+    apiExposure: "repo_workspace",
+    cliMcpParity: "peer",
+  }),
+  defineCapability({
     id: "read_range",
     description: "Bounded range read",
     mcpTool: "read_range",
     cliCommand: "read_range",
     cliPath: ["read", "range"],
-    parity: "peer",
-  },
-  {
+    apiExposure: "repo_workspace",
+    cliMcpParity: "peer",
+  }),
+  defineCapability({
     id: "changed_since",
     description: "Change since last observation",
     mcpTool: "changed_since",
     cliCommand: "read_changed",
     cliPath: ["read", "changed"],
-    parity: "peer",
-  },
-  {
+    apiExposure: "repo_workspace",
+    cliMcpParity: "peer",
+  }),
+  defineCapability({
     id: "graft_diff",
     description: "Structural diff between refs",
     mcpTool: "graft_diff",
     cliCommand: "struct_diff",
     cliPath: ["struct", "diff"],
-    parity: "peer",
-  },
-  {
+    cliMcpParity: "peer",
+  }),
+  defineCapability({
     id: "graft_since",
     description: "Structural changes since ref",
     mcpTool: "graft_since",
     cliCommand: "struct_since",
     cliPath: ["struct", "since"],
-    parity: "peer",
-  },
-  {
+    cliMcpParity: "peer",
+  }),
+  defineCapability({
     id: "graft_map",
     description: "Structural directory map",
     mcpTool: "graft_map",
     cliCommand: "struct_map",
     cliPath: ["struct", "map"],
-    parity: "peer",
-  },
-  {
+    cliMcpParity: "peer",
+  }),
+  defineCapability({
     id: "code_show",
     description: "Focus on a symbol by name",
     mcpTool: "code_show",
     cliCommand: "symbol_show",
     cliPath: ["symbol", "show"],
-    parity: "peer",
-  },
-  {
+    cliMcpParity: "peer",
+  }),
+  defineCapability({
     id: "code_find",
     description: "Search symbols by name or kind",
     mcpTool: "code_find",
     cliCommand: "symbol_find",
     cliPath: ["symbol", "find"],
-    parity: "peer",
-  },
-  {
+    cliMcpParity: "peer",
+  }),
+  defineCapability({
     id: "code_refs",
     description: "Search import sites, callsites, property access, or text references",
     mcpTool: "code_refs",
-    parity: "mcp_only",
-  },
-  {
+    cliMcpParity: "mcp_only",
+  }),
+  defineCapability({
     id: "daemon_repos",
     description: "List authorized canonical repos with bounded daemon-wide summary",
     mcpTool: "daemon_repos",
-    parity: "mcp_only",
-  },
-  {
+    cliMcpParity: "mcp_only",
+  }),
+  defineCapability({
     id: "daemon_status",
     description: "Inspect daemon-wide health and control-plane posture",
     mcpTool: "daemon_status",
-    parity: "mcp_only",
-  },
-  {
+    cliMcpParity: "mcp_only",
+  }),
+  defineCapability({
     id: "daemon_sessions",
     description: "List active daemon sessions",
     mcpTool: "daemon_sessions",
-    parity: "mcp_only",
-  },
-  {
+    cliMcpParity: "mcp_only",
+  }),
+  defineCapability({
     id: "daemon_monitors",
     description: "List daemon-managed persistent repo monitors",
     mcpTool: "daemon_monitors",
-    parity: "mcp_only",
-  },
-  {
+    cliMcpParity: "mcp_only",
+  }),
+  defineCapability({
     id: "monitor_start",
     description: "Start a repo-scoped persistent monitor",
     mcpTool: "monitor_start",
-    parity: "mcp_only",
-  },
-  {
+    cliMcpParity: "mcp_only",
+  }),
+  defineCapability({
     id: "monitor_pause",
     description: "Pause a repo-scoped persistent monitor",
     mcpTool: "monitor_pause",
-    parity: "mcp_only",
-  },
-  {
+    cliMcpParity: "mcp_only",
+  }),
+  defineCapability({
     id: "monitor_resume",
     description: "Resume a repo-scoped persistent monitor",
     mcpTool: "monitor_resume",
-    parity: "mcp_only",
-  },
-  {
+    cliMcpParity: "mcp_only",
+  }),
+  defineCapability({
     id: "monitor_stop",
     description: "Stop a repo-scoped persistent monitor",
     mcpTool: "monitor_stop",
-    parity: "mcp_only",
-  },
-  {
+    cliMcpParity: "mcp_only",
+  }),
+  defineCapability({
     id: "workspace_authorize",
     description: "Authorize a workspace for daemon binding",
     mcpTool: "workspace_authorize",
-    parity: "mcp_only",
-  },
-  {
+    cliMcpParity: "mcp_only",
+  }),
+  defineCapability({
     id: "workspace_authorizations",
     description: "List daemon-authorized workspaces",
     mcpTool: "workspace_authorizations",
-    parity: "mcp_only",
-  },
-  {
+    cliMcpParity: "mcp_only",
+  }),
+  defineCapability({
     id: "workspace_revoke",
     description: "Revoke daemon authorization for a workspace",
     mcpTool: "workspace_revoke",
-    parity: "mcp_only",
-  },
-  {
+    cliMcpParity: "mcp_only",
+  }),
+  defineCapability({
     id: "workspace_bind",
     description: "Bind a daemon session to a workspace",
     mcpTool: "workspace_bind",
-    parity: "mcp_only",
-  },
-  {
+    cliMcpParity: "mcp_only",
+  }),
+  defineCapability({
     id: "workspace_status",
     description: "Inspect daemon workspace binding state",
     mcpTool: "workspace_status",
-    parity: "mcp_only",
-  },
-  {
+    cliMcpParity: "mcp_only",
+  }),
+  defineCapability({
     id: "activity_view",
     description: "Inspect recent bounded local artifact history for the active workspace, anchored to the current commit when possible",
     mcpTool: "activity_view",
     cliCommand: "diag_activity",
     cliPath: ["diag", "activity"],
-    parity: "peer",
-  },
-  {
+    cliMcpParity: "peer",
+  }),
+  defineCapability({
+    id: "local_history_dag",
+    description: "Render a bounded debug DAG from WARP-backed local history",
+    cliCommand: "diag_local_history_dag",
+    cliPath: ["diag", "local-history-dag"],
+    cliMcpParity: "cli_only",
+  }),
+  defineCapability({
     id: "causal_status",
     description: "Inspect the active causal workspace and persisted local-history posture",
     mcpTool: "causal_status",
-    parity: "mcp_only",
-  },
-  {
+    cliMcpParity: "mcp_only",
+  }),
+  defineCapability({
     id: "causal_attach",
     description: "Explicitly declare lawful continuation or handoff for the current causal workspace",
     mcpTool: "causal_attach",
-    parity: "mcp_only",
-  },
-  {
+    cliMcpParity: "mcp_only",
+  }),
+  defineCapability({
     id: "workspace_rebind",
     description: "Rebind a daemon session to a different workspace",
     mcpTool: "workspace_rebind",
-    parity: "mcp_only",
-  },
-  {
+    cliMcpParity: "mcp_only",
+  }),
+  defineCapability({
     id: "run_capture",
     description: "Structured shell-output capture",
     mcpTool: "run_capture",
     cliCommand: "diag_capture",
     cliPath: ["diag", "capture"],
-    parity: "peer",
-  },
-  {
+    cliMcpParity: "peer",
+  }),
+  defineCapability({
     id: "explain",
     description: "Explain a reason code",
     mcpTool: "explain",
     cliCommand: "diag_explain",
     cliPath: ["diag", "explain"],
-    parity: "peer",
-  },
-  {
+    cliMcpParity: "peer",
+  }),
+  defineCapability({
     id: "doctor",
     description: "Runtime health and repo state",
     mcpTool: "doctor",
     cliCommand: "diag_doctor",
     cliPath: ["diag", "doctor"],
-    parity: "peer",
-  },
-  {
+    cliMcpParity: "peer",
+  }),
+  defineCapability({
     id: "stats",
     description: "Decision metrics summary",
     mcpTool: "stats",
     cliCommand: "diag_stats",
     cliPath: ["diag", "stats"],
-    parity: "peer",
-  },
-  {
+    cliMcpParity: "peer",
+  }),
+  defineCapability({
     id: "set_budget",
     description: "Session byte budget control",
     mcpTool: "set_budget",
-    parity: "mcp_only",
-  },
-  {
+    cliMcpParity: "mcp_only",
+  }),
+  defineCapability({
     id: "state_save",
     description: "Session bookmark save",
     mcpTool: "state_save",
-    parity: "mcp_only",
-  },
-  {
+    cliMcpParity: "mcp_only",
+  }),
+  defineCapability({
     id: "state_load",
     description: "Session bookmark load",
     mcpTool: "state_load",
-    parity: "mcp_only",
-  },
+    cliMcpParity: "mcp_only",
+  }),
+  defineCapability({
+    id: "structured_buffer",
+    description: "Dirty-buffer structural editor surface for in-process integrations",
+    apiExposure: "structured_buffer",
+    cliMcpParity: "not_applicable",
+  }),
 ] as const;
 
+export const API_EXPOSED_CAPABILITIES = Object.freeze(
+  CAPABILITY_REGISTRY.filter((capability) => capability.surfaces.includes("api")),
+);
+
 export const CLI_COMMAND_PATHS = Object.freeze(Object.fromEntries(
   CAPABILITY_REGISTRY
     .filter((capability) => capability.cliCommand !== undefined && capability.cliPath !== undefined)
@@ -339,3 +426,25 @@ export function cliCommandPath(command: CliCommandName): readonly [string, ...st
 export function cliCommandKey(path: readonly string[]): string {
   return path.join(" ");
 }
+
+export function buildCapabilityMatrixRows(): readonly CapabilityMatrixRow[] {
+  return CAPABILITY_REGISTRY.map((capability) => ({
+    id: capability.id,
+    api: capability.surfaces.includes("api") ? "Yes" : "No",
+    cli: capability.surfaces.includes("cli") ? "Yes" : "No",
+    mcp: capability.surfaces.includes("mcp") ? "Yes" : "No",
+    apiExposure: capability.apiExposure ?? "-",
+    cliMcpParity: capability.cliMcpParity,
+    cliPath: capability.cliPath?.join(" ") ?? "-",
+    mcpTool: capability.mcpTool ?? "-",
+  }));
+}
+
+export function buildThreeSurfaceCapabilityBaseline(): ThreeSurfaceCapabilityBaseline {
+  return {
+    cliOnly: CAPABILITY_REGISTRY.filter((capability) => capability.surfaces.join(",") === "cli").length,
+    apiCliMcp: CAPABILITY_REGISTRY.filter((capability) => capability.surfaces.join(",") === "api,cli,mcp").length,
+    apiMcp: CAPABILITY_REGISTRY.filter((capability) => capability.surfaces.join(",") === "api,mcp").length,
+    apiOnly: CAPABILITY_REGISTRY.filter((capability) => capability.surfaces.join(",") === "api").length,
+  };
+}

package/src/contracts/causal-ontology.ts

@@ -44,6 +44,8 @@ export const EVIDENCE_KINDS = [
   "explicit_user_declaration",
   "explicit_agent_declaration",
   "conflicting_actor_signal",
+  "environment_observation",
+  "session_continuity_observation",
 ] as const;
 
 export const evidenceKindSchema = z.enum(EVIDENCE_KINDS);
@@ -83,6 +85,9 @@ export type AttributionConfidence = z.infer<typeof attributionConfidenceSchema>;
 export const ATTRIBUTION_BASES = [
   "explicit_declaration",
   "git_transition",
+  "transport_session",
+  "session_continuity",
+  "environment_inference",
   "unknown_fallback",
   "conflicting_signals",
 ] as const;

package/src/contracts/json-object.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+export const jsonObjectSchema = z.object({}).catchall(z.unknown());
+
+export type JsonObject = z.infer<typeof jsonObjectSchema>;
+
+export function parseJsonObject(value: unknown, label: string): JsonObject {
+  const parsed = jsonObjectSchema.safeParse(value);
+  if (!parsed.success) {
+    throw new Error(`${label} was not a JSON object`);
+  }
+  return parsed.data;
+}
+
+export function tryParseJsonObject(value: unknown): JsonObject | null {
+  const parsed = jsonObjectSchema.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}
+
+export function parseJsonTextObject(text: string, label: string): JsonObject {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text) as unknown;
+  } catch {
+    throw new Error(`${label} was not valid JSON`);
+  }
+  return parseJsonObject(parsed, label);
+}

package/src/contracts/mcp-runtime.ts

@@ -0,0 +1,16 @@
+export const MCP_RUNTIME_MODES = ["repo-local", "daemon"] as const;
+
+export type McpRuntimeMode = typeof MCP_RUNTIME_MODES[number];
+
+export function parseMcpRuntimeMode(
+  raw: string | undefined,
+  flag: string,
+): McpRuntimeMode {
+  if (raw === undefined) {
+    return "repo-local";
+  }
+  if (raw === "repo-local" || raw === "daemon") {
+    return raw;
+  }
+  throw new Error(`${flag} must be one of: ${MCP_RUNTIME_MODES.join(", ")}`);
+}