forge-orkes 0.62.0 → 0.64.0

package/experimental/m10/source/mcp-server/index.js

@@ -0,0 +1,460 @@
+#!/usr/bin/env node
+// Forge MCP orchestrator — production server.
+// Tools: forge_claim_files, forge_release_claims, forge_list_claims, forge_queue_commit, forge_ping.
+// Lifecycle: stdio MCP is one-server-per-client. Multiple Claude Code sessions get their own
+//   server process; concurrent state shared via SQLite WAL on claims.db. Server exits when
+//   client stdin closes (orphan defense for Claude Code #33947 without pidfile sibling-kill).
+// #40207 mitigation: 8s stderr keepalive.
+// Contract: .forge/phases/m10-01-orchestration/contracts/mcp-tools.md
+// Schema: .forge/phases/m10-01-orchestration/data-model.md
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { DatabaseSync as Database } from "node:sqlite";
+import { spawnSync } from "node:child_process";
+import { mkdirSync, appendFileSync, chmodSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// --- Paths + config ---
+const REPO_ROOT = process.env.FORGE_REPO_ROOT || process.cwd();
+const SERVER_DIR = dirname(fileURLToPath(import.meta.url));
+const DB_PATH = process.env.FORGE_DB || join(SERVER_DIR, "claims.db");
+const EVENT_LOG = process.env.FORGE_EVENT_LOG || join(SERVER_DIR, "events.jsonl");
+const DEFAULT_TTL_S = 900;                 // 15 min, per data-model.md
+const KEEPALIVE_MS = 8 * 1000;             // #40207 mitigation
+const SCHEMA_VERSION = 1;
+
+// --- Ref/SHA validators (command-injection defense for attemptMerge) ---
+function isValidRef(s) {
+  return typeof s === "string" && /^[A-Za-z0-9._/-]+$/.test(s) && !s.startsWith("-") && s.length <= 255;
+}
+function isValidSha(s) {
+  return typeof s === "string" && /^[0-9a-f]{7,64}$/.test(s);
+}
+// session_id is stored in the DB and interpolated into merge commit messages.
+function isValidSessionId(s) {
+  return typeof s === "string" && /^[A-Za-z0-9_-]{1,64}$/.test(s);
+}
+
+// --- SQLite setup ---
+mkdirSync(dirname(DB_PATH), { recursive: true });
+const db = new Database(DB_PATH);
+// Claim contents are session-private; restrict to owner (single-user repo checkout assumed).
+try { chmodSync(DB_PATH, 0o600); } catch { /* best-effort; FS may not support chmod */ }
+db.exec("PRAGMA journal_mode = WAL");
+db.exec("PRAGMA busy_timeout = 5000");
+db.exec(`
+  CREATE TABLE IF NOT EXISTS claims (
+    file_path  TEXT NOT NULL,
+    session_id TEXT NOT NULL,
+    claimed_at INTEGER NOT NULL,
+    expires_at INTEGER NOT NULL,
+    reason     TEXT,
+    PRIMARY KEY (file_path)
+  );
+  CREATE INDEX IF NOT EXISTS claims_session_idx ON claims(session_id);
+  CREATE INDEX IF NOT EXISTS claims_expires_idx ON claims(expires_at);
+`);
+const currentVersion = db.prepare("PRAGMA user_version").get().user_version;
+if (currentVersion < SCHEMA_VERSION) {
+  db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
+}
+
+function nowSec() { return Math.floor(Date.now() / 1000); }
+
+// --- Event log (JSONL, append-only) ---
+// One line per tool invocation. Summarizes args/result; never logs full file lists or shas to bound size.
+function summarizeArgs(tool, args) {
+  if (!args || typeof args !== "object") return {};
+  const out = {};
+  if (typeof args.session_id === "string") out.session_id = args.session_id;
+  if (Array.isArray(args.files)) out.files_count = args.files.length;
+  if (typeof args.ttl_seconds === "number") out.ttl_seconds = args.ttl_seconds;
+  if (typeof args.reason === "string") out.reason = args.reason.slice(0, 80);
+  if (typeof args.branch === "string") out.branch = args.branch;
+  if (typeof args.target_branch === "string") out.target_branch = args.target_branch;
+  if (typeof args.base_sha === "string") out.base_sha = args.base_sha.slice(0, 12);
+  return out;
+}
+
+function summarizeResult(tool, result) {
+  if (!result || typeof result !== "object") return {};
+  const out = {};
+  if (Array.isArray(result.claimed)) out.claimed_count = result.claimed.length;
+  if (Array.isArray(result.rejected)) out.rejected_count = result.rejected.length;
+  if (Array.isArray(result.released)) out.released_count = result.released.length;
+  if (Array.isArray(result.claims)) out.claims_count = result.claims.length;
+  if (typeof result.status === "string") out.status = result.status;
+  if (Array.isArray(result.conflicted_files)) out.conflicted_count = result.conflicted_files.length;
+  if (typeof result.merged_sha === "string") out.merged_sha = result.merged_sha.slice(0, 12);
+  return out;
+}
+
+function logEvent(event) {
+  try {
+    appendFileSync(EVENT_LOG, JSON.stringify(event) + "\n");
+  } catch (e) {
+    process.stderr.write(`[forge-orchestrator] event-log write failed: ${e.message}\n`);
+  }
+}
+
+function purgeExpired() {
+  db.prepare("DELETE FROM claims WHERE expires_at <= ?").run(nowSec());
+}
+
+// --- Tool implementations ---
+function claimFiles({ session_id, files, ttl_seconds, reason }) {
+  if (!session_id || !Array.isArray(files) || files.length === 0) {
+    throw Object.assign(new Error("INVALID_INPUT: session_id and non-empty files required"), { code: "INVALID_INPUT" });
+  }
+  if (!isValidSessionId(session_id)) {
+    throw Object.assign(new Error("INVALID_INPUT: session_id must match /^[A-Za-z0-9_-]{1,64}$/"), { code: "INVALID_INPUT" });
+  }
+  purgeExpired();
+  const ttl = Number.isInteger(ttl_seconds) && ttl_seconds > 0 ? ttl_seconds : DEFAULT_TTL_S;
+  const t = nowSec();
+  const expires = t + ttl;
+  const checkStmt = db.prepare("SELECT session_id, expires_at FROM claims WHERE file_path = ? AND expires_at > ?");
+  const upsertStmt = db.prepare(`
+    INSERT INTO claims (file_path, session_id, claimed_at, expires_at, reason)
+    VALUES (?, ?, ?, ?, ?)
+    ON CONFLICT(file_path) DO UPDATE SET
+      session_id = excluded.session_id,
+      claimed_at = excluded.claimed_at,
+      expires_at = excluded.expires_at,
+      reason     = excluded.reason
+    WHERE claims.session_id = excluded.session_id OR claims.expires_at <= excluded.claimed_at
+  `);
+  const result = { claimed: [], rejected: [] };
+  db.exec("BEGIN");
+  try {
+    for (const p of files) {
+      const existing = checkStmt.get(p, t);
+      if (existing && existing.session_id !== session_id) {
+        result.rejected.push({ file: p, owner_session: existing.session_id, expires_at: existing.expires_at });
+      } else {
+        upsertStmt.run(p, session_id, t, expires, reason || null);
+        result.claimed.push(p);
+      }
+    }
+    db.exec("COMMIT");
+  } catch (e) {
+    db.exec("ROLLBACK");
+    throw e;
+  }
+  return result;
+}
+
+function releaseClaims({ session_id, files }) {
+  if (!session_id) {
+    throw Object.assign(new Error("INVALID_INPUT: session_id required"), { code: "INVALID_INPUT" });
+  }
+  if (!isValidSessionId(session_id)) {
+    throw Object.assign(new Error("INVALID_INPUT: session_id must match /^[A-Za-z0-9_-]{1,64}$/"), { code: "INVALID_INPUT" });
+  }
+  const released = [];
+  if (Array.isArray(files) && files.length > 0) {
+    const stmt = db.prepare("DELETE FROM claims WHERE file_path = ? AND session_id = ? RETURNING file_path");
+    for (const p of files) {
+      const row = stmt.get(p, session_id);
+      if (row) released.push(row.file_path);
+    }
+  } else {
+    const rows = db.prepare("DELETE FROM claims WHERE session_id = ? RETURNING file_path").all(session_id);
+    for (const r of rows) released.push(r.file_path);
+  }
+  return { released };
+}
+
+function listClaims({ session_id } = {}) {
+  purgeExpired();
+  const rows = session_id
+    ? db.prepare("SELECT file_path, session_id, claimed_at, expires_at, reason FROM claims WHERE session_id = ?").all(session_id)
+    : db.prepare("SELECT file_path, session_id, claimed_at, expires_at, reason FROM claims").all();
+  return {
+    claims: rows.map((r) => ({
+      file: r.file_path,
+      session_id: r.session_id,
+      claimed_at: r.claimed_at,
+      expires_at: r.expires_at,
+      reason: r.reason,
+    })),
+  };
+}
+
+// --- Merge queue (serialized via Node single-thread + busy flag) ---
+let queueBusy = false;
+const queue = [];
+
+function queueCommit(args) {
+  return new Promise((resolve) => {
+    queue.push({ args, resolve });
+    drainQueue();
+  });
+}
+
+function drainQueue() {
+  if (queueBusy || queue.length === 0) return;
+  queueBusy = true;
+  const job = queue.shift();
+  try {
+    const result = attemptMerge(job.args);
+    job.resolve(result);
+  } catch (e) {
+    job.resolve({ status: "error", code: "MERGE_TOOL_ERROR", error: e.message });
+  } finally {
+    queueBusy = false;
+    if (queue.length) drainQueue();
+  }
+}
+
+function git(argv, opts = {}) {
+  const r = spawnSync("git", argv, { cwd: REPO_ROOT, encoding: "utf-8", ...opts });
+  if (r.status !== 0) throw new Error(`git ${argv.join(" ")} failed: ${r.stderr}`);
+  return (r.stdout || "").trim();
+}
+// Non-throwing sibling: centralizes cwd + encoding for callers that branch on
+// exit status or need raw stdout/stderr (merge-tree conflict path, FF check, CAS update-ref).
+function gitRaw(argv, opts = {}) {
+  return spawnSync("git", argv, { cwd: REPO_ROOT, encoding: "utf-8", ...opts });
+}
+
+// stale_base is the CAS-rejection contract — built at both the pre-check and the
+// update-ref race sites. One constructor keeps the shape + guidance in sync (R039: main → target).
+function staleBaseResponse(currentTargetSha) {
+  return {
+    status: "stale_base",
+    current_target_sha: currentTargetSha,
+    guidance: `rebase onto ${currentTargetSha} and retry`,
+  };
+}
+
+function branchExists(branch) {
+  // branch validated by caller before reaching here
+  try { git(["rev-parse", "--verify", `refs/heads/${branch}`]); return true; } catch { return false; }
+}
+
+function attemptMerge({ session_id, branch, base_sha, target_branch }) {
+  if (!session_id || !branch || !base_sha) {
+    return { status: "error", code: "INVALID_INPUT", error: "session_id, branch, base_sha required" };
+  }
+  if (!isValidSessionId(session_id)) {
+    return { status: "error", code: "INVALID_INPUT", error: "session_id must match /^[A-Za-z0-9_-]{1,64}$/" };
+  }
+  if (!isValidRef(branch)) {
+    return { status: "error", code: "INVALID_INPUT", error: "branch contains invalid characters" };
+  }
+  // Ownership: a session may only merge its own branch. Convention is forge/<session_id>
+  // (orchestrating skill). Prevents one session merging another's in-flight branch.
+  if (branch !== `forge/${session_id}`) {
+    return { status: "error", code: "FORBIDDEN", error: `session ${session_id} may only merge branch forge/${session_id}` };
+  }
+  if (target_branch && !isValidRef(target_branch)) {
+    return { status: "error", code: "INVALID_INPUT", error: "target_branch contains invalid characters" };
+  }
+  if (!isValidSha(base_sha)) {
+    return { status: "error", code: "INVALID_INPUT", error: "base_sha must be a hex SHA (7-64 chars)" };
+  }
+  const targetBranch = target_branch || "main";
+  if (!branchExists(branch)) {
+    return { status: "error", code: "BRANCH_NOT_FOUND", error: `branch ${branch} not found` };
+  }
+  const currentTargetSha = git(["rev-parse", targetBranch]);
+  if (!isValidSha(currentTargetSha)) {
+    return { status: "error", code: "MERGE_TOOL_ERROR", error: "rev-parse target returned non-SHA" };
+  }
+
+  // CAS pre-check: caller rebased onto base_sha; if target moved, reject
+  if (currentTargetSha !== base_sha) {
+    return staleBaseResponse(currentTargetSha);
+  }
+
+  const branchSha = git(["rev-parse", branch]);
+  if (!isValidSha(branchSha)) {
+    return { status: "error", code: "MERGE_TOOL_ERROR", error: "rev-parse branch returned non-SHA" };
+  }
+  const mergeTreeRes = gitRaw(
+    ["merge-tree", "--write-tree", "--name-only", "-z", currentTargetSha, branchSha]
+  );
+
+  if (mergeTreeRes.status !== 0) {
+    const conflicted = (mergeTreeRes.stdout || "").split("\0").filter(Boolean);
+    return {
+      status: "conflict",
+      conflicted_files: conflicted,
+      base_sha: currentTargetSha,
+      messages: (mergeTreeRes.stderr || "").split("\n").filter(Boolean),
+    };
+  }
+
+  // -z output is NUL-separated: <tree-oid>\0<conflicted-file>\0... JS .trim() does NOT
+  // strip NUL, so the old .trim().split("\n")[0] left a \0-tailed OID that crashed
+  // commit-tree on every non-FF merge. Split on NUL and take the first field.
+  const mergedTree = (mergeTreeRes.stdout || "").split("\0")[0].trim();
+  if (!mergedTree) {
+    return { status: "error", code: "MERGE_TOOL_ERROR", error: "merge-tree produced no tree OID" };
+  }
+
+  const isFF = gitRaw(["merge-base", "--is-ancestor", currentTargetSha, branchSha]).status === 0;
+
+  let newSha;
+  if (isFF) {
+    newSha = branchSha;
+  } else {
+    const msg = `merge ${branch} into ${targetBranch} (session ${session_id})`;
+    const ct = gitRaw(["commit-tree", mergedTree, "-p", currentTargetSha, "-p", branchSha, "-m", msg]);
+    if (ct.status !== 0) throw new Error(`git commit-tree failed: ${ct.stderr}`);
+    newSha = (ct.stdout || "").trim();
+  }
+
+  // CAS via update-ref — fails if someone else advanced the ref since we read it
+  const ur = gitRaw(["update-ref", `refs/heads/${targetBranch}`, newSha, currentTargetSha]);
+  if (ur.status !== 0) {
+    return staleBaseResponse(git(["rev-parse", targetBranch]));
+  }
+
+  // Delete merged branch — best-effort
+  const deleted = gitRaw(["branch", "-D", branch]).status === 0;
+
+  return { status: "merged", new_main_sha: newSha, merged_branch_deleted: deleted };
+}
+
+// --- MCP wiring ---
+const server = new Server(
+  { name: "forge-orchestrator", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "forge_claim_files",
+      description: "Claim files for exclusive edit by a session. Returns claimed + rejected lists.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          session_id: { type: "string" },
+          files:      { type: "array", items: { type: "string" }, minItems: 1 },
+          ttl_seconds:{ type: "integer", minimum: 1 },
+          reason:     { type: "string" },
+        },
+        required: ["session_id", "files"],
+      },
+    },
+    {
+      name: "forge_release_claims",
+      description: "Release claims held by a session. Omit files to release all.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          session_id: { type: "string" },
+          files:      { type: "array", items: { type: "string" } },
+        },
+        required: ["session_id"],
+      },
+    },
+    {
+      name: "forge_list_claims",
+      description: "Read-only inspection of active claims.",
+      inputSchema: {
+        type: "object",
+        properties: { session_id: { type: "string" } },
+      },
+    },
+    {
+      name: "forge_queue_commit",
+      description: "Request auto-merge of branch onto target (default main). CAS-checked via base_sha.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          session_id:    { type: "string" },
+          branch:        { type: "string" },
+          base_sha:      { type: "string" },
+          target_branch: { type: "string" },
+        },
+        required: ["session_id", "branch", "base_sha"],
+      },
+    },
+    {
+      name: "forge_ping",
+      description: "Keepalive probe. Resets Claude Code idle timeout (#40207 workaround).",
+      inputSchema: { type: "object", properties: {} },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args = {} } = req.params;
+  const startMs = Date.now();
+  try {
+    let result;
+    switch (name) {
+      case "forge_claim_files":   result = claimFiles(args); break;
+      case "forge_release_claims": result = releaseClaims(args); break;
+      case "forge_list_claims":   result = listClaims(args); break;
+      case "forge_queue_commit":  result = await queueCommit(args); break;
+      case "forge_ping":          result = { pong: true, server_time: nowSec() }; break;
+      default: throw Object.assign(new Error(`unknown tool: ${name}`), { code: "INVALID_INPUT" });
+    }
+    logEvent({
+      ts: new Date().toISOString(),
+      tool: name,
+      args: summarizeArgs(name, args),
+      result: summarizeResult(name, result),
+      duration_ms: Date.now() - startMs,
+      ok: true,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+  } catch (e) {
+    logEvent({
+      ts: new Date().toISOString(),
+      tool: name,
+      args: summarizeArgs(name, args),
+      error: e.message,
+      code: e.code || "INTERNAL_ERROR",
+      duration_ms: Date.now() - startMs,
+      ok: false,
+    });
+    const payload = { error: e.message, code: e.code || "INTERNAL_ERROR" };
+    return { content: [{ type: "text", text: JSON.stringify(payload) }], isError: true };
+  }
+});
+
+// --- Lifecycle ---
+// stdio MCP is one-server-per-client. Sessions sharing claims.db coexist via SQLite WAL.
+// Server lifetime tied to client stdin: when client disconnects, stdin closes → exit.
+// Claims persist across server restarts via DB; sessions release explicitly via forge_release_claims.
+function cleanup() {
+  try { db.close(); } catch { /* already closed */ }
+}
+
+process.on("SIGTERM", () => { cleanup(); process.exit(0); });
+process.on("SIGINT",  () => { cleanup(); process.exit(0); });
+process.on("exit", cleanup);
+
+// --- Self-test mode (no MCP transport) ---
+if (process.argv.includes("--self-test")) {
+  const probe = claimFiles({ session_id: "self-test", files: ["/tmp/forge-self-test.txt"], reason: "self-test" });
+  if (!probe.claimed.length) { process.stderr.write(`self-test FAIL: claim returned no rows\n`); cleanup(); process.exit(1); }
+  releaseClaims({ session_id: "self-test" });
+  const list = listClaims();
+  process.stderr.write(`self-test OK: claim+release+list round-trip, schema_version=${SCHEMA_VERSION}, db=${DB_PATH}, claims_now=${list.claims.length}\n`);
+  cleanup();
+  process.exit(0);
+}
+
+// --- Run server ---
+const keepalive = setInterval(() => {
+  process.stderr.write(`[forge-orchestrator] keepalive ${new Date().toISOString()}\n`);
+}, KEEPALIVE_MS);
+keepalive.unref();
+
+// Orphan defense (#33947): exit when client stdin closes. Replaces fragile pidfile SIGTERM logic.
+process.stdin.on("end", () => { cleanup(); process.exit(0); });
+process.stdin.on("close", () => { cleanup(); process.exit(0); });
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+process.stderr.write(`[forge-orchestrator] started pid=${process.pid} db=${DB_PATH}\n`);

package/experimental/m10/source/mcp-server/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "forge-orchestrator",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Forge MCP orchestrator — file claims + commit queue for multi-agent sessions.",
+  "main": "index.js",
+  "scripts": {
+    "self-test": "node index.js --self-test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}