@jstn-sdk/ma 0.1.13 → 0.14.1

package/src/codex-app-server.js

@@ -0,0 +1,291 @@
+import fs from "node:fs";
+import { safeSpawn } from "./process-utils.js";
+
+const PACKAGE_VERSION = JSON.parse(
+  fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+).version;
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+export class CodexRpcError extends Error {
+  constructor(message, error) {
+    super(message);
+    this.name = "CodexRpcError";
+    this.code = error?.code;
+    this.data = error?.data;
+  }
+}
+
+export class CodexAppServerClient {
+  constructor({ transport, command = "codex", timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+    this.transport = transport ?? createStdioTransport(command);
+    this.timeoutMs = timeoutMs;
+    this.nextId = 1;
+    this.pending = new Map();
+    this.notifications = new Set();
+    this.serverRequests = new Set();
+    this.transport.onMessage((message) => this.#receive(message));
+  }
+
+  async request(method, params = {}, timeoutMs = this.timeoutMs) {
+    const id = this.nextId++;
+    const message = { jsonrpc: "2.0", id, method, params };
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Codex app-server request timed out: ${method}`));
+      }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timer, method });
+      try {
+        this.transport.send(message);
+      } catch (error) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(error);
+      }
+    });
+  }
+
+  notify(method, params = {}) {
+    this.transport.send({ jsonrpc: "2.0", method, params });
+  }
+
+  onNotification(listener) {
+    this.notifications.add(listener);
+    return () => this.notifications.delete(listener);
+  }
+
+  onServerRequest(listener) {
+    this.serverRequests.add(listener);
+    return () => this.serverRequests.delete(listener);
+  }
+
+  async initialize(clientInfo = { name: "meta-architect", version: PACKAGE_VERSION }) {
+    const result = await this.request("initialize", {
+      clientInfo,
+      capabilities: {},
+    });
+    this.notify("initialized", {});
+    return result;
+  }
+
+  startThread(params = {}) {
+    return this.request("thread/start", params);
+  }
+
+  resumeThread(params) {
+    return this.request("thread/resume", params);
+  }
+
+  forkThread(params) {
+    return this.request("thread/fork", params);
+  }
+
+  listThreads(params = {}) {
+    return this.request("thread/list", params);
+  }
+
+  archiveThread(params) {
+    return this.request("thread/archive", params);
+  }
+
+  startTurn(params) {
+    return this.request("turn/start", params);
+  }
+
+  interruptTurn(params) {
+    return this.request("turn/interrupt", params);
+  }
+
+  readConfig(params = {}) {
+    return this.request("config/read", params);
+  }
+
+  writeConfig(params = {}) {
+    return this.request("config/batchWrite", params);
+  }
+
+  close() {
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error("Codex app-server client closed"));
+    }
+    this.pending.clear();
+    return this.transport.close?.();
+  }
+
+  #receive(message) {
+    if (message && Object.hasOwn(message, "id")) {
+      const pending = this.pending.get(message.id);
+      if (!pending) {
+        if (message.method) {
+          for (const listener of this.serverRequests)
+            listener(message, (result) => this.#respond(message.id, result));
+        } else {
+          this.#respond(message.id, undefined, { code: -32600, message: "Unknown response id" });
+        }
+        return;
+      }
+      clearTimeout(pending.timer);
+      this.pending.delete(message.id);
+      if (message.error)
+        pending.reject(
+          new CodexRpcError(`Codex app-server ${pending.method} failed`, message.error),
+        );
+      else pending.resolve(message.result);
+      return;
+    }
+    for (const listener of this.notifications) listener(message);
+  }
+
+  #respond(id, result, error) {
+    this.transport.send({ jsonrpc: "2.0", id, ...(error ? { error } : { result }) });
+  }
+}
+
+export function createStdioTransport(command = "codex") {
+  const child = safeSpawn(command, ["app-server", "--stdio"], {
+    stdio: ["pipe", "pipe", "inherit"],
+    shell: false,
+  });
+  let buffer = "";
+  const listeners = new Set();
+  child.stdout.on("data", (chunk) => {
+    buffer += chunk.toString();
+    for (;;) {
+      const newline = buffer.indexOf("\n");
+      if (newline < 0) break;
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (!line) continue;
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      for (const listener of listeners) listener(message);
+    }
+  });
+  return {
+    send(message) {
+      if (!child.stdin.writable) throw new Error("Codex app-server stdin is closed");
+      child.stdin.write(`${JSON.stringify(message)}\n`);
+    },
+    onMessage(listener) {
+      listeners.add(listener);
+    },
+    close() {
+      child.kill();
+    },
+    child,
+  };
+}
+
+export function parseCodexJsonl(text) {
+  return text
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line, index) => {
+      try {
+        return JSON.parse(line);
+      } catch (error) {
+        throw new Error(`Invalid Codex exec JSONL at line ${index + 1}: ${error.message}`);
+      }
+    });
+}
+
+export function runCodexExec({
+  prompt,
+  args = [],
+  command = "codex",
+  cwd,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+} = {}) {
+  if (typeof prompt !== "string" || !prompt.trim()) throw new Error("Codex exec requires a prompt");
+  return new Promise((resolve, reject) => {
+    const child = safeSpawn(command, ["exec", "--json", ...args, prompt], {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: false,
+    });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      reject(new Error("Codex exec timed out"));
+    }, timeoutMs);
+    child.stdout.on("data", (chunk) => (stdout += chunk));
+    child.stderr.on("data", (chunk) => (stderr += chunk));
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      let events;
+      try {
+        events = parseCodexJsonl(stdout);
+      } catch (error) {
+        reject(error);
+        return;
+      }
+      if (code !== 0) {
+        reject(new Error(`Codex exec failed with exit code ${code}: ${stderr.trim()}`));
+        return;
+      }
+      resolve({ code, events, stderr: stderr.trim() });
+    });
+  });
+}
+
+export function generateCodexBindings({
+  kind = "ts",
+  outDir,
+  command = "codex",
+  cwd,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+} = {}) {
+  if (!outDir) throw new Error("Codex binding generation requires an output directory");
+  const generator = kind === "json-schema" ? "generate-json-schema" : "generate-ts";
+  return new Promise((resolve, reject) => {
+    const child = safeSpawn(command, ["app-server", generator, "--out", outDir], {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: false,
+    });
+    let stderr = "";
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      reject(new Error("Codex binding generation timed out"));
+    }, timeoutMs);
+    child.stderr.on("data", (chunk) => (stderr += chunk));
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (code !== 0)
+        reject(
+          new Error(`Codex binding generation failed with exit code ${code}: ${stderr.trim()}`),
+        );
+      else resolve({ code: code ?? 0, output: outDir, kind });
+    });
+  });
+}
+
+export function validateStructuredResult(value, schema) {
+  if (!schema || typeof schema !== "object") throw new Error("Output schema is required");
+  if (schema.type === "object" && (!value || typeof value !== "object" || Array.isArray(value)))
+    return false;
+  for (const required of schema.required ?? []) if (!Object.hasOwn(value, required)) return false;
+  for (const [key, rule] of Object.entries(schema.properties ?? {})) {
+    if (!Object.hasOwn(value, key)) continue;
+    if (rule.type === "string" && typeof value[key] !== "string") return false;
+    if (rule.type === "number" && typeof value[key] !== "number") return false;
+    if (rule.type === "boolean" && typeof value[key] !== "boolean") return false;
+  }
+  return true;
+}

package/src/fs-utils.js

@@ -1,5 +1,10 @@
+import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { writeJsonAtomically } from "./setup-lifecycle.js";
+
+export const RUNTIME_STATE_MAX_BYTES = 50 * 1024 * 1024;
+const localRuntimeLocks = new Map();
 
 export async function readJson(filePath) {
   const raw = await fs.readFile(filePath, "utf8");
@@ -7,8 +12,175 @@ export async function readJson(filePath) {
 }
 
 export async function writeJson(filePath, value) {
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
-  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`);
+  await withRuntimeStateLock(filePath, () => writeJsonAtomically(filePath, value), { wait: true });
+}
+
+export async function writeTextAtomically(filePath, content) {
+  await withRuntimeStateLock(filePath, () => writeTextAtomicallyUnlocked(filePath, content), {
+    wait: true,
+  });
+}
+
+async function writeTextAtomicallyUnlocked(filePath, content) {
+  const temporary = `${filePath}.tmp-${randomUUID()}`;
+  try {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(temporary, content);
+    await fs.rename(temporary, filePath);
+  } catch (error) {
+    await fs.rm(temporary, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+function runtimeStateRoot(filePath) {
+  const absolute = path.resolve(filePath);
+  const parts = absolute.split(path.sep);
+  const maIndex = parts.lastIndexOf(".ma");
+  if (maIndex < 0) return null;
+  return path.join(path.sep, ...parts.slice(0, maIndex + 1));
+}
+
+function runtimeStateLockName(filePath, root) {
+  const relative = path.relative(root, path.resolve(filePath));
+  const subsystem = relative.split(path.sep)[0] || "root";
+  return `.runtime-${subsystem.replace(/[^a-zA-Z0-9_.-]/g, "_")}.lock`;
+}
+
+async function writeRecoveryReceipt(root, reason, details) {
+  const receiptPath = path.join(
+    root,
+    "state",
+    "recovery-receipts",
+    `runtime-${Date.now()}-${randomUUID()}.json`,
+  );
+  await writeJsonAtomically(receiptPath, {
+    schemaVersion: "0.1.0",
+    record_type: "runtime_recovery_receipt",
+    generatedAt: new Date().toISOString(),
+    reason,
+    ...details,
+  });
+}
+
+export async function withRuntimeStateLock(filePath, action, options = {}) {
+  const root = runtimeStateRoot(filePath);
+  if (!root) return action();
+  const lockPath = path.join(root, "state", runtimeStateLockName(filePath, root));
+  if (localRuntimeLocks.has(lockPath) && !options.wait) {
+    throw new Error(`Meta-Architect runtime state is busy: ${path.relative(root, filePath)}`);
+  }
+  const previous = localRuntimeLocks.get(lockPath) ?? Promise.resolve();
+  let release;
+  const current = new Promise((resolve) => {
+    release = resolve;
+  });
+  localRuntimeLocks.set(lockPath, current);
+  await previous;
+  try {
+    return await withExternalRuntimeStateLock(lockPath, filePath, root, action, options);
+  } finally {
+    release();
+    if (localRuntimeLocks.get(lockPath) === current) localRuntimeLocks.delete(lockPath);
+  }
+}
+
+async function withExternalRuntimeStateLock(lockPath, filePath, root, action, options) {
+  const staleMs = options.staleMs ?? 60 * 60 * 1000;
+  await fs.mkdir(path.dirname(lockPath), { recursive: true });
+  let recovered = false;
+  for (;;) {
+    try {
+      await fs.mkdir(lockPath);
+      await fs.writeFile(
+        path.join(lockPath, "owner.json"),
+        `${JSON.stringify({ pid: process.pid, createdAt: Date.now(), filePath: path.resolve(filePath) })}\n`,
+        { mode: 0o600 },
+      );
+      break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      const ownerPath = path.join(lockPath, "owner.json");
+      const ownerText = await fs.readFile(ownerPath, "utf8").catch(() => null);
+      const stat = await fs.stat(lockPath).catch(() => null);
+      let owner;
+      try {
+        owner = ownerText ? JSON.parse(ownerText) : null;
+      } catch {
+        throw new Error(
+          "Meta-Architect runtime lock is corrupt; remove it only after confirming no writer is running",
+        );
+      }
+      const alive =
+        Number.isInteger(owner?.pid) &&
+        (() => {
+          try {
+            process.kill(owner.pid, 0);
+            return true;
+          } catch {
+            return false;
+          }
+        })();
+      const stale = owner ? !alive : Boolean(stat && Date.now() - stat.mtimeMs > staleMs);
+      if (!stale) {
+        if (!options.wait)
+          throw new Error(`Meta-Architect runtime state is busy: ${path.relative(root, filePath)}`);
+        if (stat && Date.now() - stat.mtimeMs < staleMs) {
+          await new Promise((resolve) => setTimeout(resolve, 5));
+          continue;
+        }
+        throw new Error(
+          `Meta-Architect runtime state lock timed out: ${path.relative(root, filePath)}`,
+        );
+      }
+      await fs.rm(lockPath, { recursive: true, force: true });
+      recovered = true;
+    }
+  }
+  try {
+    if (recovered)
+      await writeRecoveryReceipt(root, "stale-runtime-lock", {
+        filePath: path.relative(root, filePath),
+      });
+    return await action();
+  } finally {
+    await fs.rm(lockPath, { recursive: true, force: true });
+  }
+}
+
+export async function inspectRuntimeStateHealth(root) {
+  const stateRoot = path.join(path.resolve(root), ".ma");
+  const findings = [];
+  let totalBytes = 0;
+  async function walk(current) {
+    const entries = await fs.readdir(current, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+      const target = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name.endsWith(".lock"))
+          findings.push({ type: "lock", path: path.relative(root, target) });
+        else await walk(target);
+        continue;
+      }
+      totalBytes += (await fs.stat(target).catch(() => ({ size: 0 }))).size;
+      if (entry.name.includes(".tmp-")) {
+        findings.push({ type: "temporary", path: path.relative(root, target) });
+        continue;
+      }
+      if (entry.name.endsWith(".json")) {
+        try {
+          JSON.parse(await fs.readFile(target, "utf8"));
+        } catch {
+          findings.push({ type: "corrupt-json", path: path.relative(root, target) });
+        }
+      }
+    }
+  }
+  await walk(stateRoot);
+  if (totalBytes > RUNTIME_STATE_MAX_BYTES) {
+    findings.push({ type: "oversized", path: path.relative(root, stateRoot), bytes: totalBytes });
+  }
+  return findings;
 }
 
 export async function ensureDir(dirPath) {
@@ -19,7 +191,6 @@ export async function writeFileIfMissing(filePath, content) {
   try {
     await fs.access(filePath);
   } catch {
-    await fs.mkdir(path.dirname(filePath), { recursive: true });
-    await fs.writeFile(filePath, content);
+    await writeTextAtomically(filePath, content);
   }
 }

package/src/launcher.js

@@ -1,14 +1,17 @@
-import { spawnSync } from "node:child_process";
 import path from "node:path";
+import { getAgent, resolveAgentCommand } from "./agents.js";
+import { safeSpawnSync } from "./process-utils.js";
 
 const nativeCommands = new Set([
   "bootstrap",
   "doctor",
   "setup",
+  "migrate",
   "init",
   "idea",
   "skills",
   "core-ingest",
+  "agent-compat",
   "obsidian",
   "obsidian-index",
   "sdk-path",
@@ -17,9 +20,11 @@ const nativeCommands = new Set([
   "merge",
   "release",
   "run",
+  "task",
+  "hook",
 ]);
 
-export function shouldDelegateToCodex(args) {
+export function shouldDelegateToAgent(args) {
   if (args.length === 0) {
     return true;
   }
@@ -27,36 +32,34 @@ export function shouldDelegateToCodex(args) {
   return !nativeCommands.has(args[0]);
 }
 
-function normalizeCodexArgs(args) {
+function normalizeAgentArgs(args) {
   return args.filter((arg) => arg !== "--madmax" && arg !== "--high");
 }
 
-function resolveCodexCommand() {
-  if (process.env.MA_CODEX_BIN) {
-    return process.env.MA_CODEX_BIN;
-  }
-
-  return "codex";
-}
-
-export function runCodex(args) {
-  const codexCommand = resolveCodexCommand();
-  const codexArgs = normalizeCodexArgs(args);
-  const commandArgs =
-    path.extname(codexCommand) === ".js" || path.extname(codexCommand) === ".mjs"
-      ? [codexCommand, ...codexArgs]
-      : codexArgs;
-  const command = commandArgs[0] === codexCommand ? process.execPath : codexCommand;
-  const finalArgs = command === process.execPath ? commandArgs : codexArgs;
-  const result = spawnSync(command, finalArgs, { stdio: "inherit" });
+export function runAgent(args, agentType = process.env.MA_AGENT || "codex") {
+  const agent = getAgent(agentType);
+  const agentCommand = resolveAgentCommand(agent.id);
+  if (!agentCommand) throw new Error(`Agent "${agent.id}" has no executable command`);
+  const agentArgs = normalizeAgentArgs(args);
+  const commandArgs = [".js", ".mjs", ".cjs"].includes(path.extname(agentCommand))
+    ? [agentCommand, ...agentArgs]
+    : agentArgs;
+  const command = commandArgs[0] === agentCommand ? process.execPath : agentCommand;
+  const finalArgs = command === process.execPath ? commandArgs : agentArgs;
+  const result = safeSpawnSync(command, finalArgs, { stdio: "inherit" });
 
   if (result.error) {
     if (result.error.code === "ENOENT") {
-      throw new Error("Codex not found. Install it with: npm install -g @openai/codex");
+      throw new Error(`${agent.displayName} not found. Install the selected agent and retry.`);
     }
 
-    throw new Error(`Failed to start Codex: ${result.error.message}`);
+    throw new Error(`Failed to start ${agent.displayName}: ${result.error.message}`);
   }
 
   return typeof result.status === "number" ? result.status : 1;
 }
+
+export const shouldDelegateToCodex = shouldDelegateToAgent;
+export function runCodex(args) {
+  return runAgent(args, "codex");
+}

package/src/mcp-config.js

@@ -4,7 +4,15 @@ 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 localCapabilityNames = [
+  "_state",
+  "memory",
+  "trace",
+  "team_run",
+  "code_intel",
+  "playbooks",
+  "context",
+];
 const localCapabilityNameSet = new Set(localCapabilityNames);
 
 function validateObjectWithArray(parsed, arrayField, label) {