@ludecker/aaac 1.0.0 → 1.1.0

package/src/run-engine/gate-write.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/** preToolUse — deny code edits outside execute phase for THIS chat only. */
+import path from "path";
+import {
+  loadActiveRun,
+  loadRunManifest,
+  loadEnforcement,
+  isEditPhase,
+  isArtifactPath,
+  conversationIdFromHook,
+  runDir,
+  writeJson,
+  isoNow,
+} from "./lib.mjs";
+import { recordLog } from "./log.mjs";
+
+let input = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (c) => (input += c));
+process.stdin.on("end", () => {
+  const deny = (userMessage, agentMessage, detail) => {
+    console.log(JSON.stringify({ permission: "deny", user_message: userMessage, agent_message: agentMessage }));
+    process.exit(0);
+  };
+  const allow = () => {
+    console.log(JSON.stringify({ permission: "allow" }));
+    process.exit(0);
+  };
+
+  const persistEditEvent = (manifest, runId, event, detail) => {
+    recordLog(manifest, {
+      event,
+      phase: manifest.phase,
+      phase_kind: manifest.phase_kind,
+      detail,
+      level: "debug",
+    });
+    manifest.updated_at = isoNow();
+    writeJson(path.join(runDir(runId), "run.json"), manifest);
+  };
+
+  let hook;
+  try {
+    hook = JSON.parse(input || "{}");
+  } catch {
+    allow();
+  }
+
+  const toolName = hook.tool_name ?? hook.toolName ?? "";
+  if (!/^(Write|StrReplace|Delete|EditNotebook|ApplyPatch)$/i.test(toolName)) allow();
+
+  const conversationId = conversationIdFromHook(hook);
+  if (!conversationId) allow();
+
+  const active = loadActiveRun(conversationId);
+  if (!active?.run_id || active.status === "completed") allow();
+
+  const manifest = loadRunManifest(active.run_id);
+  if (!manifest || manifest.status === "completed") allow();
+  if (manifest.conversation_id && manifest.conversation_id !== conversationId) allow();
+
+  const enforcement = loadEnforcement();
+  const filePath =
+    hook.tool_input?.path ?? hook.toolInput?.path ?? hook.tool_input?.file_path ?? hook.arguments?.path ?? "";
+
+  if (filePath && isArtifactPath(filePath, enforcement)) {
+    persistEditEvent(manifest, active.run_id, "edit_allowed", `artifact path: ${filePath}`);
+    allow();
+  }
+
+  if (manifest.awaiting_approval || manifest.status === "blocked") {
+    persistEditEvent(manifest, active.run_id, "edit_denied", `blocked at gate: ${manifest.blocked_reason ?? "approval"}`);
+    deny(`AAAC Run ${active.run_id} blocked at gate.`, `Run blocked. Run: ${active.run_id}`);
+  }
+
+  if (isEditPhase(manifest.phase, enforcement)) {
+    persistEditEvent(manifest, active.run_id, "edit_allowed", `${toolName} in phase ${manifest.phase}`);
+    allow();
+  }
+  if (enforcement.artifact_write_phases?.includes(manifest.phase) && filePath) {
+    persistEditEvent(manifest, active.run_id, "edit_allowed", `artifact_write phase ${manifest.phase}`);
+    allow();
+  }
+
+  persistEditEvent(
+    manifest,
+    active.run_id,
+    "edit_denied",
+    `${toolName} blocked in phase ${manifest.phase}${filePath ? `: ${filePath}` : ""}`,
+  );
+  deny(
+    `AAAC: edits blocked in phase "${manifest.phase}" (this chat). Run: ${active.run_id}`,
+    `Cannot ${toolName} during "${manifest.phase}". Chat ${conversationId}. Advance phase first.`,
+  );
+});

package/src/run-engine/init-run.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+/** Create AAAC Run — stdin: Cursor beforeSubmitPrompt hook JSON (conversation-scoped). */
+import fs from "fs";
+import {
+  loadRegistry,
+  parseAaacPrompt,
+  resolvePending,
+  runDir,
+  slugify,
+  isoNow,
+  phaseKind,
+  writeJson,
+  saveActiveRun,
+  conversationIdFromHook,
+  promptFromHook,
+} from "./lib.mjs";
+import { recordLog, recordDecision } from "./log.mjs";
+
+async function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => (data += chunk));
+    process.stdin.on("end", () => resolve(data));
+    if (process.stdin.isTTY) resolve("");
+  });
+}
+
+const stdin = await readStdin();
+let hook = {};
+try {
+  hook = stdin ? JSON.parse(stdin) : {};
+} catch {
+  hook = {};
+}
+
+const prompt = process.argv[2] ?? promptFromHook(hook);
+const conversationId = conversationIdFromHook(hook);
+const parsed = parseAaacPrompt(prompt);
+
+if (!parsed) {
+  console.log(JSON.stringify({ ok: true, aaac: false }));
+  process.exit(0);
+}
+
+if (!conversationId) {
+  console.log(
+    JSON.stringify({
+      ok: false,
+      aaac: true,
+      error: "missing conversation_id — cannot scope Run to this chat",
+    }),
+  );
+  process.exit(0);
+}
+
+const registry = loadRegistry();
+const pending = resolvePending(parsed.command, registry);
+const now = isoNow();
+const date = now.slice(0, 10).replace(/-/g, "");
+const convShort = conversationId.slice(0, 8);
+const runId = `run_${date}_${slugify(parsed.command + (parsed.domain ? `-${parsed.domain}` : ""))}-${convShort}`;
+
+const entry = registry.commands[parsed.command];
+fs.mkdirSync(runDir(runId), { recursive: true });
+
+const manifest = {
+  run_id: runId,
+  conversation_id: conversationId,
+  command: parsed.command,
+  verb: entry.verb ?? parsed.command.split("-")[0],
+  object: entry.object ?? null,
+  domain: parsed.domain,
+  intent: parsed.intent,
+  orchestrator: entry.orchestrator ?? null,
+  status: "running",
+  phase: pending[0],
+  phase_kind: phaseKind(pending[0], registry),
+  awaiting_approval: false,
+  blocked_reason: null,
+  completed: [],
+  pending: pending.slice(1),
+  decisions: [],
+  artifacts: {},
+  checkpoints: [],
+  log: [],
+  capabilities_resolved: {},
+  confidence: { architecture: null, requirements: null, scope: null },
+  gates: { stack: entry.gate_stack ?? null, results: {} },
+  swarm: { task_launches_this_phase: 0, phase: pending[0] },
+  enforcement: { edit_allowed: false, hook_version: 2 },
+  created_at: now,
+  updated_at: now,
+};
+
+recordLog(manifest, {
+  event: "command_parsed",
+  phase: "dispatch",
+  phase_kind: "work",
+  detail: parsed.raw,
+  level: "info",
+});
+
+recordDecision(manifest, {
+  phase: "dispatch",
+  decision: "command_parsed",
+  reason: `Parsed /${parsed.command}`,
+  evidence: parsed.raw,
+});
+
+recordLog(manifest, {
+  event: "graph_resolved",
+  phase: "dispatch",
+  phase_kind: "work",
+  detail: `orchestrator=${entry.orchestrator ?? "null"} pending=${pending.length} phases`,
+  level: "debug",
+});
+
+recordLog(manifest, {
+  event: "run_created",
+  phase: pending[0],
+  phase_kind: phaseKind(pending[0], registry),
+  detail: `Run for /${parsed.command} chat=${convShort}`,
+  level: "info",
+});
+
+recordDecision(manifest, {
+  phase: "dispatch",
+  decision: "run_created",
+  reason: "Hook-initiated Run (conversation-scoped)",
+  evidence: parsed.raw,
+});
+
+recordLog(manifest, {
+  event: "phase_start",
+  phase: pending[0],
+  phase_kind: phaseKind(pending[0], registry),
+  detail: `Run for /${parsed.command} chat=${convShort}`,
+  level: "info",
+});
+
+manifest.updated_at = now;
+writeJson(`${runDir(runId)}/run.json`, manifest);
+saveActiveRun(conversationId, {
+  run_id: runId,
+  conversation_id: conversationId,
+  command: parsed.command,
+  phase: pending[0],
+  status: "running",
+  task_launches_this_phase: 0,
+  edit_allowed: false,
+  started_at: now,
+});
+
+console.log(
+  JSON.stringify({
+    ok: true,
+    aaac: true,
+    run_id: runId,
+    conversation_id: conversationId,
+    command: parsed.command,
+    phase: pending[0],
+    message: `AAAC Run ${runId} created for this chat only.`,
+  }),
+);

package/src/run-engine/lib.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export const CURSOR_ROOT = path.resolve(__dirname, "../../..");
+export const AAAC_ROOT = path.join(CURSOR_ROOT, "aaac");
+export const STATE_ROOT = path.join(AAAC_ROOT, "state");
+export const RUNS_ROOT = path.join(STATE_ROOT, "runs");
+export const ACTIVE_RUN_PATH = path.join(STATE_ROOT, "active-run.json");
+export const ACTIVE_RUNS_DIR = path.join(STATE_ROOT, "active-runs");
+export const REGISTRY_PATH = path.join(AAAC_ROOT, "runtime-registry.json");
+export const ENFORCEMENT_PATH = path.join(AAAC_ROOT, "enforcement.json");
+
+export function readJson(filePath, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+export function writeJson(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+export function loadRegistry() {
+  const reg = readJson(REGISTRY_PATH);
+  if (!reg?.commands) {
+    throw new Error(`Missing ${REGISTRY_PATH}. Run: node .cursor/aaac/generate-graph.mjs`);
+  }
+  return reg;
+}
+
+export function loadEnforcement() {
+  return readJson(ENFORCEMENT_PATH, {
+    edit_phases: ["execute", "sync_inventory", "persist", "write"],
+    swarm_min_agents: {},
+    allowed_path_prefixes: {},
+  });
+}
+
+export function conversationIdFromHook(hook) {
+  return hook?.conversation_id ?? hook?.conversationId ?? hook?.session_id ?? hook?.sessionId ?? null;
+}
+
+export function activeRunPath(conversationId) {
+  if (!conversationId) return ACTIVE_RUN_PATH;
+  const safe = conversationId.replace(/[^a-zA-Z0-9-]/g, "_");
+  return path.join(ACTIVE_RUNS_DIR, `${safe}.json`);
+}
+
+export function loadActiveRun(conversationId = null) {
+  if (conversationId) return readJson(activeRunPath(conversationId));
+  return readJson(ACTIVE_RUN_PATH);
+}
+
+export function saveActiveRun(conversationId, data) {
+  if (!conversationId) {
+    writeJson(ACTIVE_RUN_PATH, data);
+    return;
+  }
+  writeJson(activeRunPath(conversationId), data);
+}
+
+export function loadRunManifest(runId) {
+  return readJson(path.join(RUNS_ROOT, runId, "run.json"));
+}
+
+export function runDir(runId) {
+  return path.join(RUNS_ROOT, runId);
+}
+
+export function parseAaacPrompt(text) {
+  if (!text || typeof text !== "string") return null;
+  const registry = loadRegistry();
+  const trimmed = text.trim();
+  const match = trimmed.match(/^\/([a-z][a-z0-9-]*)(?:\s+(\S+))?(?:\s+"([^"]*)"|(?:\s+([\s\S]+))?)?$/);
+  if (!match) return null;
+  let command = match[1];
+  const aliasTarget = registry.aliases?.[command];
+  if (aliasTarget) command = aliasTarget;
+  if (!registry.commands[command]) return null;
+  let domain = match[2] ?? null;
+  let intent = (match[3] ?? match[4] ?? "").trim();
+  if (domain && (domain.includes(" ") || domain.startsWith('"'))) {
+    intent = `${domain} ${intent}`.trim();
+    domain = null;
+  }
+  if (domain && !intent && !domain.match(/^[a-z]+$/)) {
+    intent = domain;
+    domain = null;
+  }
+  return { command, domain, intent, raw: trimmed };
+}
+
+export function resolvePending(command, registry) {
+  const entry = registry.commands[command];
+  if (!entry?.pending?.length) throw new Error(`No pending phases for command: ${command}`);
+  return entry.pending;
+}
+
+export function slugify(s) {
+  return (s || "run").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40);
+}
+
+export function isoNow() {
+  return new Date().toISOString();
+}
+
+export function isGatePhase(phase, registry) {
+  return Boolean(registry.gate_phases?.[phase]);
+}
+
+export function isEditPhase(phase, enforcement) {
+  return enforcement.edit_phases.includes(phase);
+}
+
+export function isArtifactPath(filePath, enforcement) {
+  const normalized = filePath.replace(/\\/g, "/");
+  const prefixes = [
+    ...(enforcement.allowed_path_prefixes?.run_artifacts ?? []),
+    ...(enforcement.allowed_path_prefixes?.write_article ?? []),
+  ];
+  return prefixes.some((p) => normalized.includes(p.replace(/^\.\//, "")));
+}
+
+export function phaseKind(phase, registry) {
+  return isGatePhase(phase, registry) ? "gate" : "work";
+}
+
+export function promptFromHook(hook) {
+  return hook?.prompt ?? hook?.text ?? hook?.content ?? "";
+}

package/src/run-engine/log-dump.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * Dump Run manifest log + decisions.
+ * Usage: log-dump.mjs <run_id> [--level debug] [--format timeline|json|pretty]
+ */
+import { loadRunManifest } from "./lib.mjs";
+import { filterLogByLevel, formatTimeline } from "./log.mjs";
+
+function parseArgs(argv) {
+  const args = { runId: null, level: "debug", format: "timeline" };
+  const positional = [];
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--level" && argv[i + 1]) {
+      args.level = argv[++i];
+    } else if (arg === "--format" && argv[i + 1]) {
+      args.format = argv[++i];
+    } else if (!arg.startsWith("-")) {
+      positional.push(arg);
+    }
+  }
+  args.runId = positional[0];
+  return args;
+}
+
+const args = parseArgs(process.argv);
+
+if (!args.runId) {
+  console.error("Usage: log-dump.mjs <run_id> [--level debug] [--format timeline|json|pretty]");
+  process.exit(1);
+}
+
+const manifest = loadRunManifest(args.runId);
+if (!manifest) {
+  console.error(`Run not found: ${args.runId}`);
+  process.exit(1);
+}
+
+const filteredLog = filterLogByLevel(manifest.log ?? [], args.level);
+
+if (args.format === "json") {
+  console.log(
+    JSON.stringify(
+      {
+        run_id: manifest.run_id,
+        command: manifest.command,
+        verb: manifest.verb,
+        status: manifest.status,
+        phase: manifest.phase,
+        log: filteredLog,
+        decisions: manifest.decisions ?? [],
+      },
+      null,
+      2,
+    ),
+  );
+  process.exit(0);
+}
+
+if (args.format === "pretty") {
+  console.log(`Run: ${manifest.run_id}  /${manifest.command}  status=${manifest.status}  phase=${manifest.phase}`);
+  console.log(`Log entries (level>=${args.level}): ${filteredLog.length}`);
+  console.log("--- log ---");
+  for (const e of filteredLog) {
+    const skill = e.skill ? ` skill=${e.skill}` : "";
+    console.log(`${e.at} [${e.level ?? "info"}] ${e.phase} :: ${e.event}${skill} — ${e.detail}`);
+  }
+  console.log("--- decisions ---");
+  for (const d of manifest.decisions ?? []) {
+    console.log(`${d.at} ${d.phase} :: ${d.decision} — ${d.reason}`);
+    if (d.evidence) console.log(`  evidence: ${d.evidence}`);
+  }
+  process.exit(0);
+}
+
+console.log(formatTimeline({ ...manifest, log: filteredLog }, { minLevel: args.level }));

package/src/run-engine/log-trace.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/** Reconstruct chronological trace for a Run. Usage: log-trace.mjs <run_id> */
+import { loadRunManifest } from "./lib.mjs";
+import { buildTrace } from "./log.mjs";
+
+const runId = process.argv[2];
+if (!runId) {
+  console.error("Usage: log-trace.mjs <run_id>");
+  process.exit(1);
+}
+
+const manifest = loadRunManifest(runId);
+if (!manifest) {
+  console.error(`Run not found: ${runId}`);
+  process.exit(1);
+}
+
+console.log(buildTrace(manifest));