@jstn-sdk/ma 0.1.13 → 0.14.1

package/src/runtime/schema-migrations.js

@@ -0,0 +1,162 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { readJson, writeJson } from "../fs-utils.js";
+
+export const runtimeSchemaVersion = "0.1.0";
+
+const SCAN_ROOTS = [".ma/context", ".ma/learning", ".ma/hooks/receipts", ".ma/obsidian", "mcp"];
+const ROOT_FILES = [".ma/setup-receipt.json"];
+
+async function listJsonFiles(root, relative = "") {
+  const directory = path.join(root, relative);
+  let entries;
+  try {
+    entries = await fs.readdir(directory, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const entry of entries) {
+    const child = path.join(relative, entry.name);
+    if (entry.isDirectory()) files.push(...(await listJsonFiles(root, child)));
+    else if (entry.isFile() && entry.name.endsWith(".json")) files.push(child);
+  }
+  return files;
+}
+
+async function migrationFiles(root) {
+  const nested = (
+    await Promise.all(SCAN_ROOTS.map((relative) => listJsonFiles(root, relative)))
+  ).flat();
+  return [...new Set([...nested, ...ROOT_FILES])].filter(async (relative) => {
+    try {
+      return (await fs.stat(path.join(root, relative))).isFile();
+    } catch {
+      return false;
+    }
+  });
+}
+
+// Promise.filter is intentionally avoided: this keeps the scan synchronous in its final form.
+async function existingMigrationFiles(root) {
+  const files = await migrationFiles(root);
+  return (
+    await Promise.all(
+      files.map(async (relative) => {
+        try {
+          return (await fs.stat(path.join(root, relative))).isFile() ? relative : null;
+        } catch {
+          return null;
+        }
+      }),
+    )
+  ).filter(Boolean);
+}
+
+export async function findOutdatedSchemas(root) {
+  const outdated = [];
+  for (const relative of await existingMigrationFiles(root)) {
+    try {
+      const value = await readJson(path.join(root, relative));
+      if (!value || Array.isArray(value) || typeof value !== "object") {
+        outdated.push({ path: relative, schemaVersion: null, error: "invalid_shape" });
+      } else if (value.schemaVersion !== runtimeSchemaVersion) {
+        outdated.push({
+          path: relative,
+          schemaVersion: value.schemaVersion ?? null,
+          expected: runtimeSchemaVersion,
+        });
+      }
+    } catch {
+      outdated.push({ path: relative, schemaVersion: null, error: "invalid_json" });
+    }
+  }
+  return outdated;
+}
+
+export async function migrateSchemas(root, { dryRun = false, rollback = false } = {}) {
+  const files = await existingMigrationFiles(root);
+  if (rollback) return rollbackSchemas(root);
+
+  const plans = [];
+  for (const relative of files) {
+    try {
+      const value = await readJson(path.join(root, relative));
+      if (!value || Array.isArray(value) || typeof value !== "object") {
+        return {
+          status: "failed",
+          migrated: [],
+          errors: [{ path: relative, error: "invalid_shape" }],
+        };
+      }
+      if (value.schemaVersion !== runtimeSchemaVersion) {
+        plans.push({ relative, value, from: value.schemaVersion ?? null });
+      }
+    } catch {
+      return {
+        status: "failed",
+        migrated: [],
+        errors: [{ path: relative, error: "invalid_json" }],
+      };
+    }
+  }
+  if (dryRun)
+    return {
+      status: plans.length ? "outdated" : "current",
+      dryRun: true,
+      migrated: plans.map(({ relative, from }) => ({
+        path: relative,
+        from,
+        to: runtimeSchemaVersion,
+      })),
+      errors: [],
+    };
+  if (plans.length === 0) return { status: "current", migrated: [], errors: [] };
+
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const backupRoot = path.join(root, ".ma", "migrations", "backups", stamp);
+  for (const { relative, value } of plans) {
+    const target = path.join(root, relative);
+    const backup = path.join(backupRoot, relative);
+    await fs.mkdir(path.dirname(backup), { recursive: true });
+    await fs.copyFile(target, backup);
+    await writeJson(target, { ...value, schemaVersion: runtimeSchemaVersion });
+  }
+  await writeJson(path.join(root, ".ma", "migrations", "latest.json"), {
+    schemaVersion: runtimeSchemaVersion,
+    createdAt: new Date().toISOString(),
+    backupRoot: path.relative(root, backupRoot),
+    files: plans.map(({ relative }) => relative),
+  });
+  return {
+    status: "migrated",
+    backupRoot: path.relative(root, backupRoot),
+    migrated: plans.map(({ relative, from }) => ({
+      path: relative,
+      from,
+      to: runtimeSchemaVersion,
+    })),
+    errors: [],
+  };
+}
+
+async function rollbackSchemas(root) {
+  let receipt;
+  try {
+    receipt = await readJson(path.join(root, ".ma", "migrations", "latest.json"));
+  } catch {
+    return { status: "current", restored: [], errors: [] };
+  }
+  const restored = [];
+  for (const relative of receipt.files ?? []) {
+    const source = path.join(root, receipt.backupRoot, relative);
+    const target = path.join(root, relative);
+    try {
+      await fs.copyFile(source, target);
+      restored.push(relative);
+    } catch {
+      return { status: "failed", restored, errors: [{ path: relative, error: "backup_missing" }] };
+    }
+  }
+  return { status: "rolled_back", restored, errors: [] };
+}

package/src/runtime/signal-hooks.js

@@ -1,4 +1,5 @@
 import fs from "node:fs/promises";
+import path from "node:path";
 import { ensureDir, readJson, writeFileIfMissing } from "../fs-utils.js";
 import { getRuntimeSubsystemPath } from "../paths.js";
 
@@ -65,3 +66,15 @@ export async function loadRuntimeHooksConfig() {
 export async function loadRuntimeHooksAuditLog() {
   return fs.readFile(getRuntimeHooksAuditPath(), "utf8");
 }
+
+export async function loadRuntimeHookReceipts() {
+  const root = path.join(getRuntimeHooksRoot(), "receipts");
+  const entries = await fs.readdir(root, { withFileTypes: true }).catch(() => []);
+  return Promise.all(
+    entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+      .sort((left, right) => right.name.localeCompare(left.name))
+      .slice(0, 20)
+      .map((entry) => readJson(path.join(root, entry.name))),
+  );
+}

package/src/runtime/skills-registry-export.js

@@ -1,7 +1,9 @@
 import { createHash } from "node:crypto";
+import { existsSync as pathExistsSync } from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { getAgentInvocation } from "../agents.js";
 import { ensureDir, readJson, writeFileIfMissing } from "../fs-utils.js";
 import { getRepoRoot, getRuntimeSubsystemPath } from "../paths.js";
 
@@ -13,6 +15,13 @@ const configHome = process.env.XDG_CONFIG_HOME || path.join(home, ".config");
 const codexHome = process.env.CODEX_HOME?.trim() || path.join(home, ".codex");
 const claudeHome = process.env.CLAUDE_CONFIG_DIR?.trim() || path.join(home, ".claude");
 
+function getOpenClawGlobalSkillsDir() {
+  if (pathExistsSync(path.join(home, ".openclaw"))) return path.join(home, ".openclaw/skills");
+  if (pathExistsSync(path.join(home, ".clawdbot"))) return path.join(home, ".clawdbot/skills");
+  if (pathExistsSync(path.join(home, ".moltbot"))) return path.join(home, ".moltbot/skills");
+  return path.join(home, ".openclaw/skills");
+}
+
 const universalTargets = [
   "codex",
   "opencode",
@@ -105,7 +114,7 @@ const nonUniversalDirs = {
   mux: ".mux/skills",
   neovate: ".neovate/skills",
   openclaw: "skills",
-  pi: ".pi/agent/skills",
+  pi: ".pi/skills",
   pochi: ".pochi/skills",
   adal: ".adal/skills",
   qoder: ".qoder/skills",
@@ -120,11 +129,57 @@ const nonUniversalDirs = {
 const globalDirOverrides = {
   codex: path.join(codexHome, "skills"),
   opencode: path.join(configHome, "opencode", "skills"),
-  cursor: path.join(home, ".cursor", "skills"),
+  cursor: path.join(home, ".agents", "skills"),
   amp: path.join(configHome, "agents", "skills"),
   "claude-code": path.join(claudeHome, "skills"),
+  "gemini-cli": path.join(home, ".gemini", "skills"),
+  "github-copilot": path.join(home, ".copilot", "skills"),
+  antigravity: path.join(home, ".gemini", "antigravity", "skills"),
+  openclaw: getOpenClawGlobalSkillsDir(),
+  pi: path.join(home, ".pi", "agent", "skills"),
+  windsurf: path.join(home, ".codeium", "windsurf", "skills"),
+  goose: path.join(configHome, "goose", "skills"),
 };
 
+const universalNativeContract = {
+  artifact: "skill",
+  path: `${canonicalSkillsDir}/{name}/SKILL.md`,
+  format: "markdown",
+  activation: "host-loads-canonical-agent-skills",
+};
+
+function surfaceForAgent(name) {
+  if (
+    [
+      "cursor",
+      "antigravity",
+      "windsurf",
+      "continue",
+      "roo",
+      "kiro-cli",
+      "junie",
+      "tabnine-cli",
+      "github-copilot",
+    ].includes(name)
+  )
+    return "ide";
+  if (["devin", "openhands", "replit"].includes(name)) return "cloud";
+  return "cli";
+}
+
+function vendorForAgent(name) {
+  if (["codex", "deepagents"].includes(name)) return "openai";
+  if (["claude-code"].includes(name)) return "anthropic";
+  if (["gemini-cli", "antigravity", "dexto", "firebender", "kimi-cli"].includes(name))
+    return "google";
+  if (["github-copilot"].includes(name)) return "github";
+  if (["cursor", "windsurf", "continue", "roo", "kiro-cli", "junie", "tabnine-cli"].includes(name))
+    return "ide";
+  if (["openclaw", "pi", "hermes-agent"].includes(name))
+    return name === "pi" ? "pi" : name === "openclaw" ? "openclaw" : "nous-research";
+  return "community";
+}
+
 export const agentRegistry = Object.fromEntries([
   ...universalTargets.map((name) => [
     name,
@@ -134,6 +189,12 @@ export const agentRegistry = Object.fromEntries([
       skillsDir: canonicalSkillsDir,
       globalSkillsDir: globalDirOverrides[name] ?? path.join(home, ".agents", "skills"),
       universal: true,
+      vendor: vendorForAgent(name),
+      product: name,
+      surface: surfaceForAgent(name),
+      support: "native",
+      native_artifacts: [universalNativeContract],
+      verification: "distribution-contract",
     },
   ]),
   ...nonUniversalTargets.map((name) => [
@@ -144,6 +205,19 @@ export const agentRegistry = Object.fromEntries([
       skillsDir: nonUniversalDirs[name],
       globalSkillsDir: globalDirOverrides[name] ?? path.join(home, nonUniversalDirs[name]),
       universal: false,
+      vendor: vendorForAgent(name),
+      product: name,
+      surface: surfaceForAgent(name),
+      support: "native",
+      native_artifacts: [
+        {
+          artifact: "skill",
+          path: `${nonUniversalDirs[name]}/{name}/SKILL.md`,
+          format: "markdown",
+          activation: "host-loads-project-skill-directory",
+        },
+      ],
+      verification: "distribution-contract",
     },
   ]),
 ]);
@@ -161,6 +235,8 @@ export function createDefaultSkillsRegistryExport() {
     canonical_dir: canonicalSkillsDir,
     universal_targets: universalTargets,
     non_universal_targets: nonUniversalTargets,
+    target_count: Object.keys(agentRegistry).length,
+    targets: agentRegistry,
     authority_boundary: {
       exported_payloads_may_mutate_release_state: false,
       exported_payloads_are_managed_workers: false,
@@ -282,7 +358,7 @@ export function resolveSkillInstallPlan({
     };
   }
 
-  if (global && agent.universal) {
+  if (global && agent.universal && targetDir === canonicalDir) {
     return {
       action: "canonical-only",
       canonicalDir,
@@ -303,9 +379,9 @@ export function resolveSkillInstallPlan({
   }
 
   return {
-    action: agent.universal ? "canonical-only" : "symlink",
+    action: agent.universal && targetDir === canonicalDir ? "canonical-only" : "symlink",
     canonicalDir,
-    targetDir: agent.universal ? canonicalDir : targetDir,
+    targetDir,
     skipped: false,
     reason: agent.universal
       ? "universal agent reads canonical directory directly"
@@ -347,7 +423,7 @@ export function createSkillCompatibilityPayload({
   };
 }
 
-export function renderSkillCompatibilitySkillMd(payload) {
+export function renderSkillCompatibilitySkillMd(payload, { agentType = "codex" } = {}) {
   if (payload?.record_type !== "skill_compatibility_payload") {
     throw new Error("Expected skill compatibility payload");
   }
@@ -362,6 +438,14 @@ export function renderSkillCompatibilitySkillMd(payload) {
     "",
     "This exported host payload is a compatibility entrypoint for Meta-Architect.",
     "",
+    "## Invocation",
+    "",
+    agentType === "generic"
+      ? "- Start the umbrella lane using this host's native Meta-Architect invocation syntax."
+      : `- Start the umbrella lane with \`${getAgentInvocation(agentType, agentType === "codex" ? "maestro" : payload.name)}\` in this host.`,
+    "- Dispatch to the canonical MA runtime as `ma run '$maestro'`.",
+    "- Lane aliases: `arch`, `sage`, `flow`, `vet`, `vibe`, and `build`.",
+    "",
     "## Authority",
     "",
     "- Route execution through `$maestro` or the owning MA lane.",
@@ -402,6 +486,7 @@ export function createHostInstallReceipt({ payload, installPlan }) {
 
 export function createSkillLockEntry({
   payload,
+  agentType = "codex",
   source = "meta-architect",
   sourceType = "local",
   sourceUrl = "skills/",
@@ -416,7 +501,7 @@ export function createSkillLockEntry({
     throw new Error("Skill lock entry requires a compatibility payload");
   }
 
-  const renderedPayload = renderSkillCompatibilitySkillMd(payload);
+  const renderedPayload = renderSkillCompatibilitySkillMd(payload, { agentType });
   const folderHash =
     skillFolderHash ??
     createHash("sha256")
@@ -479,6 +564,7 @@ export async function writeSkillCompatibilityExport({
   agentRootExists = null,
   createSymlink = fs.symlink,
   lockMetadata = {},
+  renderAgentType = agentType,
 }) {
   const effectiveAgentRootExists =
     agentRootExists ?? (await detectProjectAgentRoot(agentType, cwd));
@@ -490,10 +576,11 @@ export async function writeSkillCompatibilityExport({
     mode,
     agentRootExists: effectiveAgentRootExists,
   });
-  const skillMd = renderSkillCompatibilitySkillMd(payload);
+  const skillMd = renderSkillCompatibilitySkillMd(payload, { agentType: renderAgentType });
   const lockEntry = validateSkillLockEntry(
     createSkillLockEntry({
       payload,
+      agentType: renderAgentType,
       selectedAgentTargets: [agentType],
       ...lockMetadata,
     }),
@@ -645,6 +732,7 @@ export async function verifyCrossAgentInstallMatrix({
     const result = await writeSkillCompatibilityExport({
       payload,
       agentType,
+      renderAgentType: targets.length > 1 ? "generic" : agentType,
       cwd,
       agentRootExists: await detectProjectAgentRoot(agentType, cwd),
       createSymlink: forceFallback

package/src/runtime/task-contracts.js

@@ -0,0 +1,83 @@
+import path from "node:path";
+import { ensureDir, readJson, writeJson } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+export const taskContractSchemaVersion = "0.1.0";
+
+export function getTaskContractRoot() {
+  return getRuntimeSubsystemPath("tasks", "contracts");
+}
+
+function safeContractId(id) {
+  if (String(id ?? "").includes("/") || String(id ?? "").includes("\\"))
+    throw new Error("task contract id is required");
+  const safe = String(id ?? "")
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]/g, "-");
+  if (!safe || safe === "." || safe === "..") throw new Error("task contract id is required");
+  return safe;
+}
+
+export function createTaskContract({
+  goal,
+  contextUsed = [],
+  assumptions = [],
+  constraints = [],
+  risk = "medium",
+  verification = [],
+  stopCondition,
+  persist = true,
+}) {
+  if (!goal || !stopCondition) throw new Error("task contract requires goal and stopCondition");
+  return validateTaskContract({
+    schemaVersion: taskContractSchemaVersion,
+    record_type: "task_contract",
+    goal,
+    context_used: contextUsed,
+    assumptions,
+    constraints,
+    risk,
+    verification,
+    stop_condition: stopCondition,
+    persist,
+    created_at: new Date().toISOString(),
+  });
+}
+
+export function validateTaskContract(contract) {
+  if (
+    !contract ||
+    contract.schemaVersion !== taskContractSchemaVersion ||
+    contract.record_type !== "task_contract"
+  )
+    throw new Error("invalid task contract schema");
+  for (const field of ["goal", "stop_condition"]) {
+    if (typeof contract[field] !== "string" || contract[field].trim() === "")
+      throw new Error(`task contract requires ${field}`);
+  }
+  for (const field of ["context_used", "assumptions", "constraints", "verification"]) {
+    if (
+      !Array.isArray(contract[field]) ||
+      contract[field].some((value) => typeof value !== "string")
+    )
+      throw new Error(`task contract requires string array: ${field}`);
+  }
+  if (!["low", "medium", "high"].includes(contract.risk))
+    throw new Error(`Unsupported task contract risk: ${contract.risk}`);
+  return contract;
+}
+
+export async function writeTaskContract(id, contract) {
+  const contractId = safeContractId(id);
+  const validated = validateTaskContract(contract);
+  await ensureDir(getTaskContractRoot());
+  const contractPath = path.join(getTaskContractRoot(), `${contractId}.json`);
+  await writeJson(contractPath, validated);
+  return contractPath;
+}
+
+export async function loadTaskContract(id) {
+  return validateTaskContract(
+    await readJson(path.join(getTaskContractRoot(), `${safeContractId(id)}.json`)),
+  );
+}