@jstn-sdk/ma 0.1.12 → 0.14.0

package/src/runtime/active-autonomy-core.js

@@ -0,0 +1,208 @@
+import { ensureDir, readJson, writeFileIfMissing } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+export const activeAutonomyCoreSchemaVersion = "0.1.0";
+
+export function getActiveAutonomyCorePath() {
+  return getRuntimeSubsystemPath("context", "active-autonomy-core.json");
+}
+
+export function createDefaultActiveAutonomyCore() {
+  return {
+    schemaVersion: activeAutonomyCoreSchemaVersion,
+    product: "Meta-Architect",
+    purpose:
+      "Canonical MA contract that prevents passive chatbot behavior across prompts, skills, runtime hooks, and contributor rules.",
+    autonomy_directive: {
+      placement: "top_of_workspace_contract_before_other_guidance",
+      text: [
+        "YOU ARE AN AUTONOMOUS META-ARCHITECT WORKSPACE AGENT.",
+        "EXECUTE CLEAR, SAFE, REVERSIBLE, ALREADY-REQUESTED WORK TO VERIFIED COMPLETION.",
+        "DO NOT ASK WHETHER TO PROCEED ON AUTO-CONTINUE BRANCHES.",
+        "ASK ONLY FOR DESTRUCTIVE, IRREVERSIBLE, CREDENTIAL-GATED, EXTERNAL-PRODUCTION, OR MATERIALLY SCOPE-CHANGING ACTIONS.",
+      ],
+    },
+    decision_rule: {
+      modes: ["AUTO-CONTINUE", "ASK"],
+      auto_continue_when: [
+        "clear_user_requested_work",
+        "local_or_workspace_scoped",
+        "low_risk",
+        "reversible",
+        "non_destructive",
+        "verification_path_available",
+      ],
+      ask_only_when: [
+        "destructive_action",
+        "irreversible_action",
+        "credential_gated_action",
+        "external_production_side_effect",
+        "material_scope_change",
+        "missing_authority_blocks_progress",
+      ],
+      banned_auto_continue_phrasing: [
+        "Should I proceed?",
+        "Would you like me to continue?",
+        "If you want, I can",
+        "If you'd like, I can",
+        "Tell me if you want me to",
+        "I can continue if you want",
+      ],
+    },
+    completion_loop_contract: {
+      required_for: [
+        "$maestro",
+        "$build",
+        "ralph_execution_core",
+        "executor_roles",
+        "team_workers",
+      ],
+      stop_conditions: [
+        "verified_complete",
+        "user_cancelled",
+        "closed_ask_condition_requires_user_input",
+        "same_blocker_repeated_three_times_with_no_safe_alternative",
+      ],
+      completion_requires: [
+        "fresh_verification_evidence",
+        "explicit_outcome",
+        "changed_artifacts_or_no_change_reason",
+        "known_gaps_or_none",
+      ],
+      terminal_outcomes: ["finished", "blocked", "failed", "cancelled", "askuserQuestion"],
+    },
+    runtime_enforcement: {
+      hook_layer: "active_autonomy_runtime",
+      stall_patterns: [
+        "should i proceed",
+        "would you like me to continue",
+        "if you want, i can",
+        "if you'd like, i can",
+        "tell me if you want me to",
+        "i can continue if you want",
+        "let me know if you want me to continue",
+      ],
+      default_response:
+        "AUTO-CONTINUE: continue the current safe branch, execute the next reversible step, then verify before reporting.",
+      native_stop_policy: "block_passive_permission_handoff_when_auto_continue_applies",
+    },
+    contributor_contract: {
+      required_surfaces: [
+        "workspace_contract",
+        "role_prompts",
+        "skill_contracts",
+        "runtime_hook_policy",
+        "docs",
+        "tests",
+      ],
+      regression_targets: [
+        "closed_ask_list_present",
+        "auto_continue_mode_present",
+        "permission_handoff_banned",
+        "completion_requires_fresh_evidence",
+        "terminal_outcome_required",
+        "hook_stall_patterns_present",
+      ],
+    },
+    hard_rules: [
+      "Prompt instructions alone are insufficient; runtime hook policy must backstop passive handoffs.",
+      "AUTO-CONTINUE branches must state next action or evidence-backed result, not request permission.",
+      "ASK branches must name the exact closed-list reason that requires the user.",
+      "Completion claims require fresh verification evidence or an explicit validation gap.",
+      "Contributor edits must preserve anti-passive prompt patterns and hook policy.",
+    ],
+  };
+}
+
+export function validateActiveAutonomyCore(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("active autonomy core must be an object");
+  }
+  if (value.schemaVersion !== activeAutonomyCoreSchemaVersion) {
+    throw new Error(`Unsupported active autonomy core schemaVersion: ${value.schemaVersion}`);
+  }
+  if (!value.decision_rule || typeof value.decision_rule !== "object") {
+    throw new Error("active autonomy core requires decision_rule");
+  }
+  if (!value.decision_rule.modes?.includes("AUTO-CONTINUE")) {
+    throw new Error("active autonomy core requires AUTO-CONTINUE mode");
+  }
+  if (!value.decision_rule.modes?.includes("ASK")) {
+    throw new Error("active autonomy core requires ASK mode");
+  }
+  if (
+    !Array.isArray(value.decision_rule.ask_only_when) ||
+    value.decision_rule.ask_only_when.length === 0
+  ) {
+    throw new Error("active autonomy core requires closed ask_only_when list");
+  }
+  if (!value.runtime_enforcement?.stall_patterns?.includes("should i proceed")) {
+    throw new Error("active autonomy core requires passive stall pattern coverage");
+  }
+  if (
+    !value.completion_loop_contract?.completion_requires?.includes("fresh_verification_evidence")
+  ) {
+    throw new Error("active autonomy core requires fresh verification evidence");
+  }
+  if (JSON.stringify(value).includes(".omx")) {
+    throw new Error("active autonomy core must not expose OMX runtime paths");
+  }
+  return value;
+}
+
+export function classifyAutonomyBranch({ core, requested = true, riskSignals = [] }) {
+  const policy = validateActiveAutonomyCore(core);
+  const signals = new Set(riskSignals.map((signal) => `${signal}`.toLowerCase()));
+  const askReason = policy.decision_rule.ask_only_when.find((reason) =>
+    signals.has(reason.toLowerCase()),
+  );
+
+  if (!requested) {
+    return {
+      mode: "ASK",
+      reason: "missing_authority_blocks_progress",
+      permission_handoff_allowed: true,
+    };
+  }
+
+  if (askReason) {
+    return {
+      mode: "ASK",
+      reason: askReason,
+      permission_handoff_allowed: true,
+    };
+  }
+
+  return {
+    mode: "AUTO-CONTINUE",
+    reason: "clear_safe_reversible_requested_work",
+    permission_handoff_allowed: false,
+    next_action_contract:
+      "state the next safe action or evidence-backed result; do not ask whether to proceed",
+  };
+}
+
+export function detectPassivePermissionHandoff(text, core = createDefaultActiveAutonomyCore()) {
+  const policy = validateActiveAutonomyCore(core);
+  const normalized = `${text}`.toLowerCase();
+  return policy.decision_rule.banned_auto_continue_phrasing.some((phrase) =>
+    normalized.includes(
+      phrase
+        .toLowerCase()
+        .replace(/\.\.\.$/, "")
+        .trim(),
+    ),
+  );
+}
+
+export async function seedActiveAutonomyCoreArtifacts() {
+  await ensureDir(getRuntimeSubsystemPath("context"));
+  await writeFileIfMissing(
+    getActiveAutonomyCorePath(),
+    `${JSON.stringify(createDefaultActiveAutonomyCore(), null, 2)}\n`,
+  );
+}
+
+export async function loadActiveAutonomyCore() {
+  return validateActiveAutonomyCore(await readJson(getActiveAutonomyCorePath()));
+}

package/src/runtime/agent-compat.js

@@ -0,0 +1,31 @@
+import { createRequire } from "node:module";
+import { Agents } from "@jstn-sdk/agents";
+
+const require = createRequire(import.meta.url);
+const agentCompatMetadata = require("@jstn-sdk/agents/package.json");
+
+export const agentCompatPackage = "@jstn-sdk/agents";
+export const agentCompatVersion = agentCompatMetadata.version;
+
+export function listAgentCompatAdapters() {
+  return Agents.list().map(({ id, vendor, product, surface, support, verification }) => ({
+    id,
+    vendor,
+    product,
+    surface,
+    support,
+    verification,
+  }));
+}
+
+export function detectAgentEnvironments(root) {
+  return Agents.detect(root);
+}
+
+export function compileAgentIntegrations(manifest, options = {}) {
+  return Agents.compile(manifest, options);
+}
+
+export function validateAgentIntegrations(root, options = {}) {
+  return Agents.validate(root, options);
+}

package/src/runtime/alignment-sentinel.js

@@ -0,0 +1,165 @@
+import { readJson, writeFileIfMissing, writeJson } from "../fs-utils.js";
+import { getRuntimeStatePath } from "../paths.js";
+
+const driftRuleDefinitions = [
+  {
+    skill: "$arch",
+    expectedDecisionStatus: "APPROVED",
+    releaseField: "architecture_status",
+    allowedReleaseValues: ["APPROVED"],
+    findingCode: "architecture_status_regressed",
+  },
+  {
+    skill: "$sage",
+    expectedDecisionStatus: "VERIFIED",
+    releaseField: "evidence_status",
+    allowedReleaseValues: ["VERIFIED"],
+    findingCode: "evidence_status_regressed",
+  },
+  {
+    skill: "$flow",
+    expectedDecisionStatus: "GREEN",
+    releaseField: "logic_status",
+    allowedReleaseValues: ["GREEN"],
+    findingCode: "logic_status_regressed",
+  },
+  {
+    skill: "$vet",
+    expectedDecisionStatus: "GREEN",
+    releaseField: "security_status",
+    allowedReleaseValues: ["GREEN"],
+    findingCode: "security_status_regressed",
+  },
+  {
+    skill: "$vibe",
+    expectedDecisionStatus: "GREEN",
+    releaseField: "experience_status",
+    allowedReleaseValues: ["GREEN", "WAIVED"],
+    findingCode: "experience_status_regressed",
+  },
+  {
+    skill: "$build",
+    expectedDecisionStatus: "DONE",
+    releaseField: "build_status",
+    allowedReleaseValues: ["DONE"],
+    findingCode: "build_status_regressed",
+  },
+];
+
+export function getAlignmentSentinelPath() {
+  return getRuntimeStatePath("alignment-sentinel.json");
+}
+
+export function createDefaultAlignmentSentinelReport() {
+  return {
+    schemaVersion: "0.1.0",
+    lastRunAt: null,
+    driftStatus: "CLEAR",
+    rebootPlanned: false,
+    rebootReason: null,
+    resumeTrigger: "$maestro",
+    baselineArtifacts: [
+      ".ma/release.json",
+      ".ma/decisions.json",
+      ".ma/state/manager-runs.json",
+      ".ma/state/maestro-state.json",
+    ],
+    findings: [],
+  };
+}
+
+export async function seedAlignmentSentinelArtifacts() {
+  await writeFileIfMissing(
+    getAlignmentSentinelPath(),
+    `${JSON.stringify(createDefaultAlignmentSentinelReport(), null, 2)}\n`,
+  );
+}
+
+export async function loadAlignmentSentinelReportOrDefault() {
+  try {
+    return await readJson(getAlignmentSentinelPath());
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return createDefaultAlignmentSentinelReport();
+    }
+
+    throw error;
+  }
+}
+
+export async function saveAlignmentSentinelReport(report) {
+  await writeJson(getAlignmentSentinelPath(), report);
+  return report;
+}
+
+function getLatestDecisionBySkill(decisions = []) {
+  const latestBySkill = new Map();
+  for (const decision of decisions) {
+    if (!decision?.skill) {
+      continue;
+    }
+
+    latestBySkill.set(decision.skill, decision);
+  }
+  return latestBySkill;
+}
+
+export function evaluateAlignmentDrift({ releaseState, decisionLog }) {
+  const latestDecisions = getLatestDecisionBySkill(decisionLog?.decisions ?? []);
+  const findings = [];
+
+  for (const rule of driftRuleDefinitions) {
+    const latestDecision = latestDecisions.get(rule.skill);
+    if (!latestDecision || latestDecision.status !== rule.expectedDecisionStatus) {
+      continue;
+    }
+
+    const actualReleaseValue = releaseState?.[rule.releaseField];
+    if (rule.allowedReleaseValues.includes(actualReleaseValue)) {
+      continue;
+    }
+
+    findings.push({
+      severity: "blocking",
+      findingCode: rule.findingCode,
+      skill: rule.skill,
+      expectedDecisionStatus: rule.expectedDecisionStatus,
+      releaseField: rule.releaseField,
+      expectedReleaseValues: rule.allowedReleaseValues,
+      actualReleaseValue,
+      decisionTimestamp: latestDecision.timestamp ?? null,
+      decisionSummary: latestDecision.decision ?? null,
+    });
+  }
+
+  return {
+    driftStatus: findings.length > 0 ? "DRIFTED" : "CLEAR",
+    rebootPlanned: findings.length > 0,
+    rebootReason:
+      findings.length > 0
+        ? "Release state drifted from the latest approved lane-owned decisions."
+        : null,
+    resumeTrigger: "$maestro",
+    findings,
+  };
+}
+
+export function createAlignmentRecoveryPlan(report) {
+  const findings = report?.findings ?? [];
+  return {
+    record_type: "alignment_recovery_plan",
+    driftStatus: report?.driftStatus ?? (findings.length > 0 ? "DRIFTED" : "CLEAR"),
+    rebootPlanned: findings.length > 0,
+    resumeTrigger: report?.resumeTrigger ?? "$maestro",
+    requiredActions: findings.map((finding) => ({
+      skill: finding.skill,
+      repairField: finding.releaseField,
+      expectedValues: finding.expectedReleaseValues,
+      actualValue: finding.actualReleaseValue,
+      action:
+        "Rehydrate from baseline runtime artifacts, then rerun the owning lane or restore lane-owned release state before worker dispatch resumes.",
+    })),
+    mayDispatchWorkers: findings.length === 0,
+    mayMutateReleaseStateDirectly: false,
+  };
+}