@jstn-sdk/ma 0.1.12 → 0.14.0

package/src/runtime/live-agent-verification.js

@@ -0,0 +1,122 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { agentRegistry as executableAgents, resolveAgentCommand } from "../agents.js";
+import {
+  agentRegistry,
+  createSkillCompatibilityPayload,
+  verifyCrossAgentInstallMatrix,
+} from "./skills-registry-export.js";
+
+const defaultTimeoutMs = 5000;
+
+function runVersionProbe(command, timeoutMs, args = ["--version"]) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(result);
+    };
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      finish({ ok: false, reason: "version probe timed out" });
+    }, timeoutMs);
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.once("error", (error) => finish({ ok: false, reason: error.message }));
+    child.once("close", (code) =>
+      finish({
+        ok: code === 0,
+        version: stdout.trim(),
+        reason: code === 0 ? null : stderr.trim() || `exited with code ${code}`,
+      }),
+    );
+  });
+}
+
+function normalizeProbeCommand(command) {
+  return [".js", ".mjs", ".cjs"].includes(path.extname(command))
+    ? { command: process.execPath, args: [command, "--version"] }
+    : { command, args: ["--version"] };
+}
+
+export async function verifyLiveAgentMatrix({
+  cwd = process.cwd(),
+  targets = Object.keys(agentRegistry),
+  timeoutMs = defaultTimeoutMs,
+} = {}) {
+  const root = path.resolve(cwd);
+  const tempRoot = await fsTempDirectory();
+  try {
+    const payload = createSkillCompatibilityPayload({
+      name: "live-agent-verification",
+      capabilities: ["maestro", "agent-compatibility"],
+    });
+    const distribution = await verifyCrossAgentInstallMatrix({
+      payload,
+      cwd: tempRoot,
+      targets,
+      existingAgentRoots: targets,
+    });
+    const results = [];
+    for (const [index, target] of targets.entries()) {
+      const distributionResult = distribution.results[index];
+      const command = executableAgents[target]?.probeable ? resolveAgentCommand(target) : null;
+      if (!command) {
+        results.push({
+          target,
+          status: distributionResult?.ok ? "distribution-only" : "blocked",
+          version: null,
+          command: null,
+          distribution: distributionResult?.ok === true,
+          reason: "No safe non-interactive host command is registered for this target.",
+        });
+        continue;
+      }
+      const normalized = normalizeProbeCommand(command);
+      const probe = await runVersionProbe(normalized.command, timeoutMs, normalized.args);
+      results.push({
+        target,
+        status: probe.ok && distributionResult?.ok ? "runtime-verified" : "blocked",
+        version: probe.version ?? null,
+        command,
+        distribution: distributionResult?.ok === true,
+        reason: probe.ok ? null : probe.reason,
+      });
+    }
+    return {
+      schemaVersion: "0.1.0",
+      record_type: "live_agent_verification",
+      cwd: root,
+      target_count: results.length,
+      runtime_verified: results.filter((result) => result.status === "runtime-verified").length,
+      distribution_only: results.filter((result) => result.status === "distribution-only").length,
+      blocked: results.filter((result) => result.status === "blocked").length,
+      results,
+      production_evidence: false,
+    };
+  } finally {
+    await fsTempRemove(tempRoot);
+  }
+}
+
+async function fsTempDirectory() {
+  return fs.mkdtemp(path.join(os.tmpdir(), "ma-live-agents-"));
+}
+
+async function fsTempRemove(directory) {
+  await fs.rm(directory, { recursive: true, force: true });
+}

package/src/runtime/maestro-events.js

@@ -0,0 +1,18 @@
+import fs from "node:fs/promises";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+export function getMaestroEventsPath() {
+  return getRuntimeSubsystemPath("logs", "maestro-events.ndjson");
+}
+
+export async function appendMaestroEvent(record) {
+  const event = {
+    schemaVersion: "0.1.0",
+    timestamp: new Date().toISOString(),
+    ...record,
+  };
+  const target = getMaestroEventsPath();
+  await fs.mkdir(getRuntimeSubsystemPath("logs"), { recursive: true });
+  await fs.appendFile(target, `${JSON.stringify(event)}\n`, "utf8");
+  return event;
+}

package/src/runtime/maestro-manager.js

@@ -524,6 +524,25 @@ export function chooseMaestroManagerAction({
     };
   }
 
+  if (["READY", "RUNNING"].includes(releaseState.build_status)) {
+    return {
+      mode: "helper+gated",
+      nextAction: "dispatch-gated",
+      dispatchPlan: {
+        helpers: [],
+        gated: [
+          createGatedPlan(
+            "$build",
+            "Advance the bounded build execution substep and persist lane-owned build evidence.",
+            { prerequisites: ["build_status=READY|RUNNING"] },
+          ),
+        ],
+        team: null,
+      },
+      reason: recommendation?.why ?? "The build lane still owns the next bounded execution step.",
+    };
+  }
+
   if (releaseState.merge_status !== "MERGED_TO_DEVELOPMENT") {
     return {
       mode: "team",

package/src/runtime/maestro-output.js

@@ -0,0 +1,58 @@
+export function createMaestroView(maestroState) {
+  const tracks = Object.entries(maestroState?.runtime_tracks ?? {}).map(([id, track]) => ({
+    id,
+    gate: track.active_gate ?? "none",
+    status: track.status ?? "unknown",
+    blockers: Array.isArray(track.blockers) ? track.blockers : [],
+  }));
+  const locks = Object.entries(maestroState?.downstream_lock_table ?? {}).map(([gate, lock]) => ({
+    gate,
+    status: lock.is_locked ? "locked" : "unlocked",
+    lockedBy: Array.isArray(lock.locked_by) ? lock.locked_by : [],
+    unlockCriteria: lock.unlock_criteria ?? null,
+  }));
+  const blockers = tracks.flatMap((track) =>
+    track.blockers.map((message) => `${track.id}: ${message}`),
+  );
+  return {
+    schemaVersion: "0.1.0",
+    scope: "maestro",
+    globalStatus: maestroState?.global_status ?? "unknown",
+    orchestrationId: maestroState?.orchestration_id ?? null,
+    tracks,
+    locks,
+    blockers,
+    nextAction:
+      blockers[0] ??
+      (locks.some((lock) => lock.status === "locked")
+        ? "Resolve downstream locks"
+        : "Continue active lane"),
+  };
+}
+
+export function formatMaestroView(view) {
+  const lines = [
+    "Maestro View",
+    "Meta-Architect / Maestro",
+    "========================",
+    `Global status: ${view.globalStatus}`,
+    `Orchestration id: ${view.orchestrationId ?? "not started"}`,
+    `Status: ${view.globalStatus}`,
+    `Run: ${view.orchestrationId ?? "not started"}`,
+    "",
+    "Lane        Gate                  Status",
+    "----------  --------------------  ----------",
+  ];
+  if (view.tracks.length === 0) lines.push("none");
+  for (const track of view.tracks)
+    lines.push(`${track.id.padEnd(10)}  ${track.gate.padEnd(20)}  ${track.status}`);
+  lines.push("", "Blockers");
+  lines.push(...(view.blockers.length ? view.blockers.map((item) => `- ${item}`) : ["- none"]));
+  lines.push("", `Next: ${view.nextAction}`, "", "Downstream locks");
+  lines.push(
+    ...(view.locks.length
+      ? view.locks.map((lock) => `- ${lock.gate}: ${lock.status}`)
+      : ["- none"]),
+  );
+  return `${lines.join("\n")}\n`;
+}

package/src/runtime/maestro-state.js

@@ -0,0 +1,125 @@
+import { randomUUID } from "node:crypto";
+import { readJson, writeFileIfMissing, writeJson } from "../fs-utils.js";
+import { getRuntimeStatePath } from "../paths.js";
+
+const defaultDependencyGraph = {
+  description: "Topological map of gate execution dependencies.",
+  nodes: {
+    $arch: { dependencies: [] },
+    $sage: { dependencies: ["$arch"] },
+    $flow: { dependencies: ["$sage"] },
+    $vet: { dependencies: ["$sage"] },
+    $vibe: { dependencies: ["$sage"] },
+    $build: { dependencies: ["$flow", "$vet", "$vibe"] },
+  },
+};
+
+const validGlobalStatuses = new Set([
+  "IDLE",
+  "READY",
+  "RUNNING",
+  "COMPLETED",
+  "DEGRADED_HEALING",
+  "LOCKED",
+]);
+
+export function getMaestroStatePath() {
+  return getRuntimeStatePath("maestro-state.json");
+}
+
+export function createDefaultMaestroState() {
+  return {
+    schemaVersion: "0.1.0",
+    orchestration_id: null,
+    timestamp: null,
+    global_status: "IDLE",
+    configuration: {
+      auto_heal: false,
+      max_healing_attempts: 2,
+      concurrency_limit: 4,
+    },
+    dependency_graph: defaultDependencyGraph,
+    runtime_tracks: {},
+    downstream_lock_table: {},
+  };
+}
+
+export function validateMaestroState(state) {
+  if (!state || typeof state !== "object" || Array.isArray(state)) {
+    throw new Error("Maestro state must be an object");
+  }
+  if (state.schemaVersion !== "0.1.0") {
+    throw new Error(`Unsupported maestro state schemaVersion: ${state.schemaVersion}`);
+  }
+  if (!(state.orchestration_id === null || typeof state.orchestration_id === "string")) {
+    throw new Error("maestro_state.orchestration_id must be null or a string");
+  }
+  if (!(state.timestamp === null || typeof state.timestamp === "string")) {
+    throw new Error("maestro_state.timestamp must be null or a string");
+  }
+  if (!validGlobalStatuses.has(state.global_status)) {
+    throw new Error(`Unsupported maestro_state.global_status: ${state.global_status}`);
+  }
+  if (!state.configuration || typeof state.configuration !== "object") {
+    throw new Error("maestro_state.configuration must be an object");
+  }
+  if (!state.dependency_graph || typeof state.dependency_graph !== "object") {
+    throw new Error("maestro_state.dependency_graph must be an object");
+  }
+  if (!state.runtime_tracks || typeof state.runtime_tracks !== "object") {
+    throw new Error("maestro_state.runtime_tracks must be an object");
+  }
+  if (!state.downstream_lock_table || typeof state.downstream_lock_table !== "object") {
+    throw new Error("maestro_state.downstream_lock_table must be an object");
+  }
+
+  return state;
+}
+
+export async function seedMaestroStateArtifacts() {
+  await writeFileIfMissing(
+    getMaestroStatePath(),
+    `${JSON.stringify(createDefaultMaestroState(), null, 2)}\n`,
+  );
+}
+
+export async function loadMaestroState() {
+  return validateMaestroState(await readJson(getMaestroStatePath()));
+}
+
+export async function loadMaestroStateOrDefault() {
+  try {
+    return await loadMaestroState();
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return createDefaultMaestroState();
+    }
+
+    throw error;
+  }
+}
+
+export async function saveMaestroState(state) {
+  validateMaestroState(state);
+  await writeJson(getMaestroStatePath(), state);
+  return state;
+}
+
+export function beginMaestroOrchestration(state, { globalStatus, configuration = null } = {}) {
+  const next = structuredClone(state);
+  if (
+    next.orchestration_id === null ||
+    ["IDLE", "COMPLETED", "LOCKED"].includes(next.global_status)
+  ) {
+    next.orchestration_id = `ma_run_${Date.now()}_${randomUUID().slice(0, 8)}`;
+  }
+  next.timestamp = new Date().toISOString();
+  next.global_status = globalStatus;
+  if (configuration) {
+    next.configuration = {
+      ...next.configuration,
+      ...configuration,
+    };
+  }
+  return next;
+}

package/src/runtime/managed-markdown.js

@@ -0,0 +1,29 @@
+const START = "<!-- MA:MANAGED:START";
+const END = "<!-- MA:MANAGED:END -->";
+
+export function createManagedMarkdownBlock({ id, source, body }) {
+  return `${START} id=${id} source=${source} -->\n${body.trim()}\n${END}\n`;
+}
+
+export function replaceManagedMarkdownBlock(existing, generated, id) {
+  const marker = new RegExp(
+    `<!-- MA:MANAGED:START id=${escapeRegExp(id)}[^>]*-->[\\s\\S]*?${END}`,
+    "g",
+  );
+  const starts = existing.match(/<!-- MA:MANAGED:START\b/g)?.length ?? 0;
+  const ends = existing.match(new RegExp(escapeRegExp(END), "g"))?.length ?? 0;
+  if (starts === 1 && ends === 1 && marker.test(existing))
+    return existing.replace(marker, generated.trim());
+  return `${existing.trimEnd()}\n\n${generated}`;
+}
+
+export function removeManagedMarkdownBlock(existing, id) {
+  const marker = new RegExp(
+    `\\n?<!-- MA:MANAGED:START id=${escapeRegExp(id)}[^>]*-->[\\s\\S]*?${END}\\n?`,
+  );
+  return existing.replace(marker, "");
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/runtime/mcp-authority.js

@@ -0,0 +1,147 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { writeJson } from "../fs-utils.js";
+import { getRuntimeWritePath } from "../paths.js";
+import { resolveHookProfile } from "./hook-profiles.js";
+import { maskSensitiveText } from "./redaction-gateway.js";
+import { queueMailboxProposal } from "./runtime-state.js";
+
+const writePolicies = {
+  "state.sync_release_status": "state-write",
+  "state.append_decision": "state-write",
+  "memory.store_note": "memory-write",
+  "team_run.submit_task": "task-control",
+  "team_run.control_task": "task-control",
+};
+
+function getField(options, camel, snake) {
+  return options?.[camel] ?? options?.[snake];
+}
+
+function getProfile(options) {
+  const requested = getField(options, "profile", "profile") ?? process.env.MA_MCP_PROFILE;
+  return requested ? resolveHookProfile(requested) : resolveHookProfile();
+}
+
+function validateMetadata(options) {
+  const metadata = {
+    actor: getField(options, "actor", "actor"),
+    authority: options?.authority ?? getField(options, "authorityBoundary", "authority_boundary"),
+    reason: getField(options, "reason", "reason"),
+    evidence: getField(options, "evidence", "evidence"),
+  };
+  const missing = Object.entries(metadata)
+    .filter(([, value]) => value == null || (typeof value === "string" && value.trim() === ""))
+    .map(([key]) => key);
+  return { metadata, missing };
+}
+
+function receiptPath() {
+  return path.join(getRuntimeWritePath("mcp", "receipts"), `${Date.now()}-${randomUUID()}.json`);
+}
+
+async function writeAuditReceipt({ tool, classification, profile, metadata, outcome, reason }) {
+  const safe = maskSensitiveText(
+    JSON.stringify({
+      actor: metadata.actor,
+      authority: metadata.authority,
+      reason: metadata.reason,
+      evidence: metadata.evidence,
+    }),
+  ).sanitizedText;
+  const receipt = {
+    schemaVersion: "0.1.0",
+    record_type: "mcp_write_audit_receipt",
+    tool,
+    classification,
+    profile: profile.id,
+    outcome,
+    denial_reason: reason ?? null,
+    metadata: JSON.parse(safe),
+    recordedAt: new Date().toISOString(),
+  };
+  const target = receiptPath();
+  await writeJson(target, receipt);
+  await fs.chmod(target, 0o600).catch(() => {});
+  return target;
+}
+
+export function listMcpWritePolicies() {
+  return Object.entries(writePolicies).map(([tool, classification]) => ({ tool, classification }));
+}
+
+export function mcpWriteCapabilityStatus() {
+  const profile = resolveHookProfile(
+    process.env.MA_MCP_PROFILE ?? process.env.MA_PROFILE ?? "local",
+  );
+  return {
+    profile: profile.id,
+    readOnly: profile.readOnly === true,
+    tools: listMcpWritePolicies(),
+    detail: profile.readOnly
+      ? `MCP writes disabled by ${profile.id} profile`
+      : `MCP writes require actor, authority, reason, and evidence in ${profile.id} profile`,
+  };
+}
+
+export async function loadMcpAuditReceipts() {
+  const root = getRuntimeWritePath("mcp", "receipts");
+  const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+  const receipts = [];
+  for (const entry of entries.filter((item) => item.isFile() && item.name.endsWith(".json"))) {
+    try {
+      receipts.push(JSON.parse(await fs.readFile(path.join(root, entry.name), "utf8")));
+    } catch {
+      // Ignore incomplete receipts; doctor can still report the directory.
+    }
+  }
+  return receipts.sort((a, b) => `${a.recordedAt}`.localeCompare(`${b.recordedAt}`));
+}
+
+export async function withMcpWriteGate({ tool, options = {}, payload = {} }, operation) {
+  const classification = writePolicies[tool];
+  if (!classification) throw new Error(`Unknown MCP write tool: ${tool}`);
+  const profile = getProfile(options);
+  const { metadata, missing } = validateMetadata(options);
+
+  if (profile.readOnly === true) {
+    const auditReceipt = await writeAuditReceipt({
+      tool,
+      classification,
+      profile,
+      metadata,
+      outcome: "denied",
+      reason: "profile_read_only",
+    });
+    return { proposed: false, denied: true, reason: "profile_read_only", auditReceipt };
+  }
+
+  if (missing.length > 0) {
+    const proposalPath = await queueMailboxProposal({
+      actor: metadata.actor ?? "mcp-unknown",
+      kind: `mcp-${classification}`,
+      payload: { tool, payload, missingAuthority: missing },
+    });
+    const auditReceipt = await writeAuditReceipt({
+      tool,
+      classification,
+      profile,
+      metadata,
+      outcome: "proposed",
+      reason: `missing_authority:${missing.join(",")}`,
+    });
+    return { proposed: true, proposalPath, auditReceipt, reason: "missing_authority" };
+  }
+
+  const result = await operation(metadata);
+  const auditReceipt = await writeAuditReceipt({
+    tool,
+    classification,
+    profile,
+    metadata,
+    outcome: result?.proposed ? "proposed" : "allowed",
+    reason: result?.proposed ? "leader_authority_required" : null,
+  });
+  return { ...result, auditReceipt };
+}