buildanything 1.7.1 → 2.0.0

package/bin/adapters/cycle-counter-tool.ts

@@ -0,0 +1,155 @@
+/**
+ * Adapter: wraps Kiro's cycle-counter handlers in the SdkMcpToolDefinition
+ * shape required by @anthropic-ai/claude-agent-sdk.
+ *
+ * Kiro's file (src/orchestrator/mcp/cycle-counter.ts) is owned by Kiro and
+ * must not be edited; this adapter lives here to preserve that boundary and
+ * to keep the SDK-specific zod/CallToolResult surface out of the handler core.
+ *
+ * Kiro's handlers mutate the CounterState object in place. The adapter echoes
+ * the updated state back to the caller so the orchestrator can pipe it into
+ * a single atomic state_save (A3 crash-seam protocol).
+ *
+ * Spec: docs/migration/sdk-hybrid/MIGRATION-PLAN-FINAL.md §4 Stage 4
+ * Task: 4.2.4
+ */
+
+import { z } from "zod";
+import {
+  cycleCounterCheck,
+  clearInFlightEdge,
+  handleStaleEdge,
+  type CounterState,
+} from "../../src/orchestrator/mcp/cycle-counter.js";
+
+type ToolConstructor = typeof import("@anthropic-ai/claude-agent-sdk").tool;
+
+const inFlightEdgeSchema = z.object({
+  decision_id: z.string().min(1),
+  target_phase: z.string().min(1),
+  counter_value: z.number().int().nonnegative(),
+  started_at: z.string().min(1),
+});
+
+const counterStateSchema = z.object({
+  backward_routing_count: z.record(z.string(), z.number().int().nonnegative()),
+  backward_routing_count_by_target_phase: z.record(z.string(), z.number().int().nonnegative()),
+  in_flight_backward_edge: inFlightEdgeSchema.optional(),
+});
+
+const checkInputShape = {
+  state: counterStateSchema,
+  input: z.object({
+    decision_id: z.string().min(1),
+    target_phase: z.string().min(1),
+  }),
+  max_cycles: z.number().int().positive().optional(),
+};
+
+const clearInputShape = {
+  state: counterStateSchema,
+};
+
+const staleInputShape = {
+  state: counterStateSchema,
+  threshold_ms: z.number().int().positive().optional(),
+};
+
+export function buildCycleCounterCheckTool(tool: ToolConstructor) {
+  return tool(
+    "cycle_counter_check",
+    "Check and increment backward-routing counters (per-decision + per-target-phase). Returns {action: allow|escalate_to_user, decision_count, phase_count, state} where state is the mutated CounterState to persist via state_save.",
+    checkInputShape,
+    async (args) => {
+      try {
+        const state = args.state as CounterState;
+        const result = cycleCounterCheck(state, args.input, args.max_cycles);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ ...result, state }),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `cycle_counter_check error: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  );
+}
+
+export function buildClearInFlightEdgeTool(tool: ToolConstructor) {
+  return tool(
+    "clear_in_flight_edge",
+    "Clear the in_flight_backward_edge field (called by target phase on re-entry). Returns {state} for the caller to persist via state_save.",
+    clearInputShape,
+    async (args) => {
+      try {
+        const state = args.state as CounterState;
+        clearInFlightEdge(state);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ state }),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `clear_in_flight_edge error: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  );
+}
+
+export function buildHandleStaleEdgeTool(tool: ToolConstructor) {
+  return tool(
+    "handle_stale_edge",
+    "On --resume, if in_flight_backward_edge is older than threshold_ms (default 60000), decrement both counters and clear the edge. Returns {cleaned:boolean, state}.",
+    staleInputShape,
+    async (args) => {
+      try {
+        const state = args.state as CounterState;
+        const cleaned = handleStaleEdge(state, args.threshold_ms);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ cleaned, state }),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `handle_stale_edge error: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  );
+}

package/bin/adapters/scribe-tool.ts

@@ -0,0 +1,71 @@
+/**
+ * Adapter: wraps Kiro's scribeDecision(input, filePath) handler in the
+ * SdkMcpToolDefinition shape required by @anthropic-ai/claude-agent-sdk.
+ *
+ * Kiro's file (src/orchestrator/mcp/scribe.ts) is owned by Kiro and must
+ * not be edited; this adapter lives here to preserve that boundary and to
+ * keep the SDK-specific zod/CallToolResult surface out of the handler core.
+ *
+ * Spec: docs/migration/sdk-hybrid/MIGRATION-PLAN-FINAL.md §4 Stage 1
+ * Task: 1.2.4
+ */
+
+import { resolve } from "node:path";
+import { z } from "zod";
+import { scribeDecision, loadCounters } from "../../src/orchestrator/mcp/scribe.js";
+
+type ToolConstructor = typeof import("@anthropic-ai/claude-agent-sdk").tool;
+
+const DEFAULT_DECISIONS_PATH = "docs/plans/decisions.jsonl";
+
+const rejectedAlternativeSchema = z.object({
+  approach: z.string().min(1),
+  reason: z.string().min(1),
+  revisit_criterion: z.string().min(1),
+});
+
+const scribeInputShape = {
+  phase: z.string().min(1),
+  category: z.string().min(1),
+  summary: z.string().min(1),
+  decided_by: z.string().min(1),
+  impact_level: z.enum(["low", "medium", "high", "critical"]),
+  chosen_approach: z.string().min(1),
+  rejected_alternatives: z.array(rejectedAlternativeSchema).max(3).optional(),
+  ref: z.string().optional(),
+};
+
+export function buildScribeTool(tool: ToolConstructor, cwd: string) {
+  const decisionsPath = resolve(cwd, DEFAULT_DECISIONS_PATH);
+  loadCounters(decisionsPath);
+
+  return tool(
+    "scribe_decision",
+    "Append a decision row to docs/plans/decisions.jsonl. Single-writer per migration plan; validates against decisions.schema.json.",
+    scribeInputShape,
+    async (args) => {
+      try {
+        const row = scribeDecision(args, decisionsPath);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(row),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `scribe_decision error: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  );
+}

package/bin/adapters/state-save-tool.ts

@@ -0,0 +1,130 @@
+/**
+ * Adapter: wraps Kiro's state-save handler (stateSave/stateRead/verifyIntegrity)
+ * in the SdkMcpToolDefinition shape required by @anthropic-ai/claude-agent-sdk.
+ *
+ * Kiro's file (src/orchestrator/mcp/state-save.ts) is owned by Kiro and must
+ * not be edited; this adapter lives here to preserve that boundary and to
+ * keep the SDK-specific zod/CallToolResult surface out of the handler core.
+ *
+ * Spec: docs/migration/sdk-hybrid/MIGRATION-PLAN-FINAL.md §4 Stage 3
+ * Task: 3.2.4
+ */
+
+import { z } from "zod";
+import {
+  stateSave,
+  stateRead,
+  verifyIntegrity,
+} from "../../src/orchestrator/mcp/state-save.js";
+
+type ToolConstructor = typeof import("@anthropic-ai/claude-agent-sdk").tool;
+
+const saveInputShape = {
+  path: z.string().min(1),
+  state: z.record(z.string(), z.unknown()),
+};
+
+const readInputShape = {
+  path: z.string().min(1),
+};
+
+const verifyInputShape = {
+  path: z.string().min(1),
+  expected_sha256: z.string().min(1),
+};
+
+export function buildStateSaveTool(tool: ToolConstructor) {
+  return tool(
+    "state_save",
+    "Atomically persist state to a JSON file via write-to-.tmp + fsync + rename. Returns {success, path, sha256, bytesWritten}. Single writer for .build-state.json.",
+    saveInputShape,
+    async (args) => {
+      try {
+        const result = stateSave(args.path, args.state as Record<string, unknown>);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `state_save error: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  );
+}
+
+export function buildStateReadTool(tool: ToolConstructor) {
+  return tool(
+    "state_read",
+    "Read state from a JSON file and compute its SHA-256 checksum. Returns {state, sha256}.",
+    readInputShape,
+    async (args) => {
+      try {
+        const result = stateRead(args.path);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `state_read error: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  );
+}
+
+export function buildVerifyIntegrityTool(tool: ToolConstructor) {
+  return tool(
+    "verify_integrity",
+    "Verify a state file's SHA-256 matches the expected checksum. Returns {matches:boolean}.",
+    verifyInputShape,
+    async (args) => {
+      try {
+        const matches = verifyIntegrity(args.path, args.expected_sha256);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ matches }),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `verify_integrity error: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  );
+}

package/bin/adapters/write-lease-tool.ts

@@ -0,0 +1,127 @@
+/**
+ * Adapter: wraps Kiro's write-lease handler (acquire/release/list) in the
+ * SdkMcpToolDefinition shape required by @anthropic-ai/claude-agent-sdk.
+ *
+ * Kiro's file (src/orchestrator/mcp/write-lease.ts) is owned by Kiro and must
+ * not be edited; this adapter lives here to preserve that boundary and to
+ * keep the SDK-specific zod/CallToolResult surface out of the handler core.
+ *
+ * Spec: docs/migration/sdk-hybrid/MIGRATION-PLAN-FINAL.md §A5
+ * Task: 2.3.4
+ */
+
+import { z } from "zod";
+import {
+  acquireWriteLease,
+  releaseLease,
+  getActiveLeases,
+} from "../../src/orchestrator/mcp/write-lease.js";
+
+type ToolConstructor = typeof import("@anthropic-ai/claude-agent-sdk").tool;
+
+const acquireInputShape = {
+  task_id: z.string().min(1),
+  file_paths: z.array(z.string().min(1)).min(1),
+};
+
+const releaseInputShape = {
+  task_id: z.string().min(1),
+};
+
+const listInputShape = {} as const;
+
+export function buildAcquireWriteLeaseTool(tool: ToolConstructor) {
+  return tool(
+    "acquire_write_lease",
+    "Acquire an exclusive write lease on one or more file paths for a task. Returns granted:true with the lease, or granted:false with conflict details when another task holds an overlapping lease.",
+    acquireInputShape,
+    async (args) => {
+      try {
+        const result = acquireWriteLease(args.task_id, args.file_paths);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `acquire_write_lease error: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  );
+}
+
+export function buildReleaseWriteLeaseTool(tool: ToolConstructor) {
+  return tool(
+    "release_write_lease",
+    "Release all write leases held by a task. Called by SubagentStop hook on dispatch return. Returns released:true if a lease existed, false otherwise.",
+    releaseInputShape,
+    async (args) => {
+      try {
+        const released = releaseLease(args.task_id);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ released }),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `release_write_lease error: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  );
+}
+
+export function buildListWriteLeasesTool(tool: ToolConstructor) {
+  return tool(
+    "list_write_leases",
+    "List all active write leases (holder, paths, acquired_at). Read-only; intended for orchestrator diagnostics and .build-state.json persistence snapshots.",
+    listInputShape,
+    async () => {
+      try {
+        const leases = getActiveLeases();
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ leases }),
+            },
+          ],
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `list_write_leases error: ${message}`,
+            },
+          ],
+        };
+      }
+    },
+  );
+}

package/bin/buildanything-runtime.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+'use strict';
+
+// Thin shim: delegates to the TypeScript entry via tsx.
+// Mirrors the hook pattern (npx --no-install tsx) used by subagent-start,
+// pre-tool-use, and compile-writer-owner-cache — consistent behavior across
+// the whole plugin when tsx is not globally installed.
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+const tsEntry = path.join(__dirname, 'buildanything-runtime.ts');
+const result = spawnSync('npx', ['--no-install', 'tsx', tsEntry, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+});
+process.exit(result.status ?? (result.error ? 1 : 0));