@jstn-sdk/ma 0.1.11 → 0.1.13

package/src/decision-log.js

@@ -1,5 +1,6 @@
 import { readJson, writeJson } from "./fs-utils.js";
 import { getRuntimeReadPath, getRuntimeWritePath } from "./paths.js";
+import { guardLeaderMutation } from "./runtime/runtime-state.js";
 
 function validateDecisionShape(entry) {
   const required = ["decision", "status", "evidence", "blockers", "next_allowed_triggers"];
@@ -20,7 +21,16 @@ export async function loadDecisionLog() {
   return parsed;
 }
 
-export async function appendDecision(entry) {
+export async function appendDecision(entry, options = {}) {
+  const guard = await guardLeaderMutation({
+    actor: options.actor,
+    kind: "decision-append",
+    payload: entry,
+  });
+  if (!guard.allowed) {
+    return { proposed: true, proposalPath: guard.proposalPath };
+  }
+
   validateDecisionShape(entry);
   const log = await loadDecisionLog();
   log.decisions.push({
@@ -29,12 +39,5 @@ export async function appendDecision(entry) {
   });
 
   await writeJson(getRuntimeWritePath("decisions.json"), log);
-}
-
-export async function updateDecisionStatuses(statusUpdates) {
-  const log = await loadDecisionLog();
-  for (const [field, value] of Object.entries(statusUpdates)) {
-    log[field] = value;
-  }
-  await writeJson(getRuntimeWritePath("decisions.json"), log);
+  return { proposed: false, proposalPath: null };
 }

package/src/launcher.js

@@ -8,8 +8,12 @@ const nativeCommands = new Set([
   "init",
   "idea",
   "skills",
+  "core-ingest",
+  "obsidian",
+  "obsidian-index",
   "sdk-path",
   "status",
+  "verify",
   "merge",
   "release",
   "run",

package/src/mcp-config.js

@@ -1,7 +1,26 @@
 import fs from "node:fs/promises";
-import { getMcpServersPath } from "./paths.js";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { getBundledMcpPath, getMcpLocalCapabilitiesPath, getMcpServersPath } from "./paths.js";
 
 const gitMcpRepoPattern = /^https:\/\/gitmcp\.io\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const localCapabilityNames = ["_state", "memory", "trace", "team_run", "code_intel", "playbooks"];
+const localCapabilityNameSet = new Set(localCapabilityNames);
+
+function validateObjectWithArray(parsed, arrayField, label) {
+  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed[arrayField])) {
+    throw new Error(`${label} must be an object with a ${arrayField} array`);
+  }
+
+  return parsed;
+}
+
+function normalizeGitMcpDescriptor(server) {
+  return {
+    ...server,
+    kind: server.kind ?? "gitmcp-evidence",
+  };
+}
 
 export function isValidGitMcpEndpoint(url) {
   return gitMcpRepoPattern.test(url);
@@ -9,18 +28,25 @@ export function isValidGitMcpEndpoint(url) {
 
 export async function loadMcpServers() {
   const raw = await fs.readFile(getMcpServersPath(), "utf8");
-  const parsed = JSON.parse(raw);
-
-  if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.servers)) {
-    throw new Error("mcp/servers.json must be an object with a servers array");
-  }
-
-  return parsed;
+  const parsed = validateObjectWithArray(JSON.parse(raw), "servers", "mcp/servers.json");
+  return {
+    ...parsed,
+    servers: parsed.servers.map(normalizeGitMcpDescriptor),
+  };
 }
 
 export async function validateMcpServers() {
   const parsed = await loadMcpServers();
   for (const server of parsed.servers) {
+    if (server.kind !== "gitmcp-evidence") {
+      throw new Error(`Invalid GitMCP descriptor kind: ${server.kind ?? "(missing)"}`);
+    }
+    if (typeof server.category !== "string" || server.category.trim() === "") {
+      throw new Error("GitMCP descriptors require a category");
+    }
+    if (typeof server.repo !== "string" || server.repo.trim() === "") {
+      throw new Error("GitMCP descriptors require a repo");
+    }
     if (!isValidGitMcpEndpoint(server.endpoint)) {
       throw new Error(`Invalid GitMCP endpoint: ${server.endpoint}`);
     }
@@ -28,3 +54,99 @@ export async function validateMcpServers() {
 
   return parsed;
 }
+
+export async function loadLocalCapabilities() {
+  const raw = await fs.readFile(getMcpLocalCapabilitiesPath(), "utf8");
+  return validateObjectWithArray(JSON.parse(raw), "capabilities", "mcp/local-capabilities.json");
+}
+
+export function getSupportedLocalCapabilities() {
+  return [...localCapabilityNames];
+}
+
+export async function validateLocalCapabilities() {
+  const parsed = await loadLocalCapabilities();
+  const seen = new Set();
+
+  for (const descriptor of parsed.capabilities) {
+    if (descriptor.kind !== "local-capability") {
+      throw new Error(`Invalid local capability kind: ${descriptor.kind ?? "(missing)"}`);
+    }
+    if (!localCapabilityNameSet.has(descriptor.capability)) {
+      throw new Error(`Unsupported local capability: ${descriptor.capability}`);
+    }
+    if (seen.has(descriptor.capability)) {
+      throw new Error(`Duplicate local capability: ${descriptor.capability}`);
+    }
+    if (descriptor.transport !== "inproc") {
+      throw new Error(
+        `Local capability ${descriptor.capability} must use inproc transport, received ${descriptor.transport}`,
+      );
+    }
+    if (typeof descriptor.module !== "string" || descriptor.module.trim() === "") {
+      throw new Error(`Local capability ${descriptor.capability} requires a module`);
+    }
+    if (typeof descriptor.readinessCheck !== "string" || descriptor.readinessCheck.trim() === "") {
+      throw new Error(`Local capability ${descriptor.capability} requires a readinessCheck`);
+    }
+    if (descriptor.seededByBootstrap !== true) {
+      throw new Error(
+        `Local capability ${descriptor.capability} must declare seededByBootstrap: true`,
+      );
+    }
+    seen.add(descriptor.capability);
+  }
+
+  for (const capability of localCapabilityNames) {
+    if (!seen.has(capability)) {
+      throw new Error(`Missing local capability descriptor: ${capability}`);
+    }
+  }
+
+  return parsed;
+}
+
+export function resolveLocalCapabilityModulePath(descriptor) {
+  if (path.isAbsolute(descriptor.module)) {
+    throw new Error(`Local capability ${descriptor.capability} cannot use an absolute module path`);
+  }
+
+  const bundledLocalRoot = path.resolve(getBundledMcpPath("local"));
+  const resolvedModulePath = path.resolve(getBundledMcpPath(descriptor.module));
+  if (!resolvedModulePath.startsWith(`${bundledLocalRoot}${path.sep}`)) {
+    throw new Error(
+      `Local capability ${descriptor.capability} must resolve inside bundled mcp/local`,
+    );
+  }
+
+  return resolvedModulePath;
+}
+
+export async function loadLocalCapabilityModule(descriptor) {
+  const modulePath = resolveLocalCapabilityModulePath(descriptor);
+  return import(pathToFileURL(modulePath).href);
+}
+
+export async function runLocalCapabilityReadinessChecks() {
+  const parsed = await validateLocalCapabilities();
+  const results = [];
+
+  for (const descriptor of parsed.capabilities) {
+    const moduleExports = await loadLocalCapabilityModule(descriptor);
+    const readinessCheck = moduleExports[descriptor.readinessCheck];
+    if (typeof readinessCheck !== "function") {
+      throw new Error(
+        `Local capability ${descriptor.capability} is missing readiness export ${descriptor.readinessCheck}`,
+      );
+    }
+
+    const outcome = await readinessCheck();
+    results.push({
+      capability: descriptor.capability,
+      ready: outcome?.ready !== false,
+      detail: outcome?.detail ?? "",
+    });
+  }
+
+  return results;
+}

package/src/mcp-live-client.js

@@ -1,3 +1,54 @@
+import { spawn } from "node:child_process";
+
+const GITMCP_ENDPOINT_PATTERN = /^https:\/\/gitmcp\.io\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const BRIDGE_COMMAND_ENV = "MA_MCP_REMOTE_BRIDGE_CMD";
+const REQUEST_TIMEOUT_ENV = "MA_MCP_REQUEST_TIMEOUT_MS";
+const DEFAULT_REQUEST_TIMEOUT_MS = 15000;
+
+function readRequestTimeoutMs() {
+  const raw = process.env[REQUEST_TIMEOUT_ENV]?.trim();
+  if (!raw) return DEFAULT_REQUEST_TIMEOUT_MS;
+
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return DEFAULT_REQUEST_TIMEOUT_MS;
+  }
+
+  return Math.max(50, Math.floor(parsed));
+}
+
+export class McpRemoteTransportRequiredError extends Error {
+  constructor(endpoint, status, bodyPreview = "") {
+    const bridgeHint =
+      `Set ${BRIDGE_COMMAND_ENV} to a trusted stdio bridge command with {url}, ` +
+      "for example a preinstalled mcp-remote wrapper, then rerun $sage.";
+    const bodyHint = bodyPreview ? ` Response preview: ${bodyPreview}` : "";
+    super(
+      `Remote MCP endpoint requires a bridge transport: ${endpoint} returned HTTP ${status}. ${bridgeHint}${bodyHint}`,
+    );
+    this.name = "McpRemoteTransportRequiredError";
+    this.endpoint = endpoint;
+    this.status = status;
+    this.bridgeEnv = BRIDGE_COMMAND_ENV;
+  }
+}
+
+export function isGitMcpEndpoint(endpoint) {
+  return GITMCP_ENDPOINT_PATTERN.test(endpoint);
+}
+
+export function hasConfiguredMcpRemoteBridge() {
+  return Boolean(process.env[BRIDGE_COMMAND_ENV]?.trim());
+}
+
+export function createMcpLiveClient(endpoint) {
+  if (hasConfiguredMcpRemoteBridge()) {
+    return new McpStdioBridgeClient(endpoint, process.env[BRIDGE_COMMAND_ENV]);
+  }
+
+  return new McpSseClient(endpoint);
+}
+
 export class McpSseClient {
   constructor(baseUrl) {
     this.baseUrl = baseUrl;
@@ -17,6 +68,10 @@ export class McpSseClient {
     });
 
     if (!response.ok || !response.body) {
+      const bodyPreview = await readResponsePreview(response);
+      if (isGitMcpEndpoint(this.baseUrl) && response.status === 405) {
+        throw new McpRemoteTransportRequiredError(this.baseUrl, response.status, bodyPreview);
+      }
       throw new Error(`Failed to open MCP SSE stream: ${response.status}`);
     }
 
@@ -26,7 +81,7 @@ export class McpSseClient {
       5000,
       "Timed out waiting for MCP endpoint event",
     );
-    if (!endpointEvent || endpointEvent.event !== "endpoint") {
+    if (endpointEvent?.event !== "endpoint") {
       throw new Error("MCP server did not provide an endpoint event");
     }
 
@@ -38,7 +93,7 @@ export class McpSseClient {
       capabilities: {},
       clientInfo: {
         name: "meta-architect",
-        version: "0.1.11",
+        version: "0.1.13-dev",
       },
     });
 
@@ -52,7 +107,7 @@ export class McpSseClient {
       const timeout = setTimeout(() => {
         this.pending.delete(id);
         reject(new Error(`Timed out waiting for MCP response to ${method}`));
-      }, 15000);
+      }, readRequestTimeoutMs());
 
       this.pending.set(id, {
         resolve: (payload) => {
@@ -171,6 +226,237 @@ export class McpSseClient {
   }
 }
 
+export class McpStdioBridgeClient {
+  constructor(endpoint, commandTemplate, spawnImpl = spawn) {
+    this.endpoint = endpoint;
+    this.commandTemplate = commandTemplate;
+    this.spawnImpl = spawnImpl;
+    this.child = null;
+    this.buffer = "";
+    this.pending = new Map();
+    this.nextId = 1;
+    this.stderr = "";
+    this.closed = false;
+  }
+
+  async connect() {
+    const { command, args } = buildBridgeCommand(this.commandTemplate, this.endpoint);
+    this.child = this.spawnImpl(command, args, {
+      stdio: ["pipe", "pipe", "pipe"],
+      env: process.env,
+    });
+
+    this.child.stdout.setEncoding("utf8");
+    this.child.stderr.setEncoding("utf8");
+    this.child.stdout.on("data", (chunk) => this.#handleStdout(chunk));
+    this.child.stderr.on("data", (chunk) => {
+      this.stderr = `${this.stderr}${chunk}`.slice(-2000);
+    });
+    this.child.on("error", (error) => {
+      this.closed = true;
+      for (const [, handlers] of this.pending) {
+        handlers.reject(new Error(`MCP bridge failed to start: ${error.message}`));
+      }
+      this.pending.clear();
+    });
+    this.child.on("exit", (code, signal) => {
+      this.closed = true;
+      const reason = signal
+        ? `MCP bridge exited with signal ${signal}`
+        : `MCP bridge exited with code ${code}`;
+      for (const [, handlers] of this.pending) {
+        handlers.reject(new Error(`${reason}${this.stderr ? `: ${this.stderr.trim()}` : ""}`));
+      }
+      this.pending.clear();
+    });
+
+    const initResult = await this.request("initialize", {
+      protocolVersion: "2025-03-26",
+      capabilities: {},
+      clientInfo: {
+        name: "meta-architect",
+        version: "0.1.13-dev",
+      },
+    });
+
+    await this.notify("notifications/initialized");
+    return initResult;
+  }
+
+  async request(method, params = {}) {
+    const id = this.nextId++;
+    const responsePromise = new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Timed out waiting for MCP bridge response to ${method}`));
+      }, readRequestTimeoutMs());
+
+      this.pending.set(id, {
+        resolve: (payload) => {
+          clearTimeout(timeout);
+          resolve(payload);
+        },
+        reject: (error) => {
+          clearTimeout(timeout);
+          reject(error);
+        },
+      });
+    });
+
+    this.#send({
+      jsonrpc: "2.0",
+      id,
+      method,
+      params,
+    });
+
+    return responsePromise;
+  }
+
+  async notify(method, params = {}) {
+    this.#send({
+      jsonrpc: "2.0",
+      method,
+      params,
+    });
+  }
+
+  async close() {
+    if (!this.child || this.closed) return;
+    this.child.stdin.end();
+    this.child.kill();
+    await new Promise((resolve) => {
+      const timeout = setTimeout(resolve, 1000);
+      this.child.once("exit", () => {
+        clearTimeout(timeout);
+        resolve();
+      });
+    });
+  }
+
+  #send(message) {
+    if (!this.child?.stdin.writable) {
+      throw new Error("MCP bridge is not writable");
+    }
+    this.child.stdin.write(`${JSON.stringify(message)}\n`);
+  }
+
+  #handleStdout(chunk) {
+    this.buffer += chunk;
+    while (true) {
+      const newlineIndex = this.buffer.indexOf("\n");
+      if (newlineIndex === -1) return;
+
+      const line = this.buffer.slice(0, newlineIndex).trim();
+      this.buffer = this.buffer.slice(newlineIndex + 1);
+      if (!line?.startsWith("{")) continue;
+
+      let payload;
+      try {
+        payload = JSON.parse(line);
+      } catch {
+        continue;
+      }
+
+      if (typeof payload.id !== "number" || !this.pending.has(payload.id)) {
+        continue;
+      }
+
+      const handlers = this.pending.get(payload.id);
+      this.pending.delete(payload.id);
+      if (payload.error) {
+        handlers.reject(new Error(payload.error.message ?? "Unknown MCP bridge error"));
+      } else {
+        handlers.resolve(payload.result);
+      }
+    }
+  }
+}
+
+function buildBridgeCommand(commandTemplate, endpoint) {
+  const template = commandTemplate?.trim();
+  if (!template) {
+    throw new Error(`${BRIDGE_COMMAND_ENV} is empty`);
+  }
+
+  const parts = splitCommand(template);
+  if (parts.length === 0) {
+    throw new Error(`${BRIDGE_COMMAND_ENV} is empty`);
+  }
+
+  const substituted = parts.map((part) => part.replaceAll("{url}", endpoint));
+  if (!template.includes("{url}")) {
+    substituted.push(endpoint);
+  }
+
+  const [command, ...args] = substituted;
+  return { command, args };
+}
+
+async function readResponsePreview(response) {
+  try {
+    return (await response.text()).replace(/\s+/g, " ").trim().slice(0, 240);
+  } catch {
+    return "";
+  }
+}
+
+function splitCommand(command) {
+  const parts = [];
+  let current = "";
+  let quote = null;
+  let escaping = false;
+
+  for (const char of command) {
+    if (escaping) {
+      current += char;
+      escaping = false;
+      continue;
+    }
+
+    if (char === "\\") {
+      escaping = true;
+      continue;
+    }
+
+    if (quote) {
+      if (char === quote) {
+        quote = null;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+
+    if (char === "'" || char === '"') {
+      quote = char;
+      continue;
+    }
+
+    if (/\s/.test(char)) {
+      if (current) {
+        parts.push(current);
+        current = "";
+      }
+      continue;
+    }
+
+    current += char;
+  }
+
+  if (escaping) {
+    current += "\\";
+  }
+  if (quote) {
+    throw new Error(`${BRIDGE_COMMAND_ENV} has an unterminated quote`);
+  }
+  if (current) {
+    parts.push(current);
+  }
+
+  return parts;
+}
+
 export function parseSseEvent(rawEvent) {
   const event = { event: "message", data: "" };
   for (const line of rawEvent.split("\n")) {

package/src/paths.js

@@ -13,6 +13,14 @@ export function getRuntimeRoot() {
   return path.join(getRepoRoot(), ".ma");
 }
 
+export function getRuntimeSubsystemPath(subsystem, ...parts) {
+  return path.join(getRuntimeRoot(), subsystem, ...parts);
+}
+
+export function getRuntimeStatePath(...parts) {
+  return getRuntimeSubsystemPath("state", ...parts);
+}
+
 export function getRuntimeWritePath(...parts) {
   return path.join(getRuntimeRoot(), ...parts);
 }
@@ -21,6 +29,34 @@ export function getRuntimeReadPath(...parts) {
   return path.join(getRuntimeRoot(), ...parts);
 }
 
+export function getMcpRootPath() {
+  return path.join(getRepoRoot(), "mcp");
+}
+
+export function getBundledMcpPath(...parts) {
+  return path.join(packageRoot, "mcp", ...parts);
+}
+
 export function getMcpServersPath() {
-  return path.join(getRepoRoot(), "mcp", "servers.json");
+  return path.join(getMcpRootPath(), "servers.json");
+}
+
+export function getMcpLocalCapabilitiesPath() {
+  return path.join(getMcpRootPath(), "local-capabilities.json");
+}
+
+export function getRuntimeMcpPolicyPath() {
+  return getRuntimeWritePath(".mcp.json");
+}
+
+export function getBundledNativePlaybooksPath() {
+  return getBundledMcpPath("native-playbooks.json");
+}
+
+export function getBundledDocsPath(...parts) {
+  return path.join(packageRoot, "docs", ...parts);
+}
+
+export function getBundledSkillsPath(...parts) {
+  return path.join(packageRoot, "skills", ...parts);
 }

package/src/policy.js

@@ -19,5 +19,5 @@ export function validateMergeTarget(sourceBranch, targetBranch) {
 }
 
 export function canMarkBuildDone(releaseState) {
-  return ["READY", "RUNNING"].includes(releaseState.build_status);
+  return releaseState.build_status === "DONE";
 }