@jstn-sdk/ma 0.1.11 → 0.1.12

package/src/runtime/orchestrator.js

@@ -0,0 +1,158 @@
+import { randomUUID } from "node:crypto";
+import { ensureDir, readJson, writeFileIfMissing, writeJson } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+import { guardLeaderMutation } from "./runtime-state.js";
+
+export function getTaskRoot() {
+  return getRuntimeSubsystemPath("tasks");
+}
+
+export function getTaskRegistryPath() {
+  return getRuntimeSubsystemPath("tasks", "registry.json");
+}
+
+export function getTaskMailboxRoot() {
+  return getRuntimeSubsystemPath("tasks", "mailbox");
+}
+
+export function getTaskLockRoot() {
+  return getRuntimeSubsystemPath("tasks", "locks");
+}
+
+function validateTaskRegistry(registry) {
+  if (
+    !registry ||
+    typeof registry !== "object" ||
+    typeof registry.leader !== "string" ||
+    !Array.isArray(registry.workers) ||
+    !Array.isArray(registry.tasks)
+  ) {
+    throw new Error("Task registry must contain leader, workers, and tasks");
+  }
+
+  return registry;
+}
+
+function normalizeTask(task) {
+  const title = task?.title?.trim();
+  if (!title) {
+    throw new Error("team_run.submit_task requires a task title");
+  }
+
+  const metadata =
+    task?.metadata && typeof task.metadata === "object" && !Array.isArray(task.metadata)
+      ? { ...task.metadata }
+      : {};
+
+  return {
+    id: task.id ?? `task-${randomUUID()}`,
+    title,
+    status: task.status ?? "queued",
+    owner: task.owner ?? null,
+    createdAt: task.createdAt ?? new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    metadata: {
+      classification: metadata.classification ?? "durable-team-task",
+      ...metadata,
+    },
+  };
+}
+
+export async function seedOrchestratorArtifacts() {
+  await ensureDir(getTaskRoot());
+  await ensureDir(getTaskMailboxRoot());
+  await ensureDir(getTaskLockRoot());
+  await writeFileIfMissing(
+    getTaskRegistryPath(),
+    `${JSON.stringify(
+      {
+        schemaVersion: "0.1.0",
+        leader: "leader",
+        workers: [],
+        tasks: [],
+      },
+      null,
+      2,
+    )}\n`,
+  );
+}
+
+export async function loadTaskRegistry() {
+  return validateTaskRegistry(await readJson(getTaskRegistryPath()));
+}
+
+export async function saveTaskRegistry(registry) {
+  validateTaskRegistry(registry);
+  await writeJson(getTaskRegistryPath(), registry);
+  return registry;
+}
+
+export async function submitTask(task, options = {}) {
+  const guard = await guardLeaderMutation({
+    actor: options.actor,
+    kind: "team-run-submit",
+    payload: task,
+  });
+  if (!guard.allowed) {
+    return { proposed: true, proposalPath: guard.proposalPath };
+  }
+
+  const registry = await loadTaskRegistry();
+  const nextTask = normalizeTask(task);
+  registry.tasks.push(nextTask);
+  await saveTaskRegistry(registry);
+  return { proposed: false, proposalPath: null, task: nextTask };
+}
+
+export async function getTask(taskId) {
+  const registry = await loadTaskRegistry();
+  const task = registry.tasks.find((entry) => entry.id === taskId);
+  if (!task) {
+    throw new Error(`Unknown task: ${taskId}`);
+  }
+
+  return task;
+}
+
+export async function listTasks() {
+  const registry = await loadTaskRegistry();
+  return registry.tasks;
+}
+
+export async function listMaestroTasks() {
+  const tasks = await listTasks();
+  return tasks.filter((task) => task.metadata?.managerOwner === "$maestro");
+}
+
+export async function controlTask(taskId, action, options = {}) {
+  const guard = await guardLeaderMutation({
+    actor: options.actor,
+    kind: "team-run-control",
+    payload: { taskId, action },
+  });
+  if (!guard.allowed) {
+    return { proposed: true, proposalPath: guard.proposalPath };
+  }
+
+  const registry = await loadTaskRegistry();
+  const task = registry.tasks.find((entry) => entry.id === taskId);
+  if (!task) {
+    throw new Error(`Unknown task: ${taskId}`);
+  }
+
+  const statusByAction = {
+    start: "running",
+    complete: "done",
+    block: "blocked",
+    cancel: "cancelled",
+  };
+  const nextStatus = statusByAction[action];
+  if (!nextStatus) {
+    throw new Error(`Unsupported team_run control action: ${action}`);
+  }
+
+  task.status = nextStatus;
+  task.updatedAt = new Date().toISOString();
+  await saveTaskRegistry(registry);
+  return { proposed: false, proposalPath: null, task };
+}

package/src/runtime/runtime-state.js

@@ -0,0 +1,382 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { readJson, writeJson } from "../fs-utils.js";
+import { getRuntimeReadPath } from "../paths.js";
+import { createDefaultReleaseState, validateReleaseState } from "../release-state.js";
+import {
+  getContinuityIndexPath,
+  getContinuityNotesPath,
+  seedContinuityArtifacts,
+} from "./continuity-notes.js";
+import {
+  getGuidanceIncludeGraphPath,
+  getMergedGuidancePath,
+  seedGuidanceStackArtifacts,
+} from "./guidance-stack.js";
+import { getManagerRunsPath, seedMaestroManagerArtifacts } from "./maestro-manager.js";
+import {
+  getTaskLockRoot,
+  getTaskMailboxRoot,
+  getTaskRegistryPath,
+  seedOrchestratorArtifacts,
+} from "./orchestrator.js";
+import {
+  getRuntimeHooksAuditPath,
+  getRuntimeHooksConfigPath,
+  seedSignalHookArtifacts,
+} from "./signal-hooks.js";
+import { getWorkspacesIndexPath, seedWorkspaceArtifacts } from "./workspaces.js";
+
+const runtimeSubsystemSeeders = [
+  seedGuidanceStackArtifacts,
+  seedContinuityArtifacts,
+  seedSignalHookArtifacts,
+  seedOrchestratorArtifacts,
+  seedWorkspaceArtifacts,
+  seedMaestroManagerArtifacts,
+];
+const defaultMergedGuidance = {
+  schemaVersion: "0.1.0",
+  sources: [],
+  content: "",
+};
+const defaultGuidanceGraph = {
+  schemaVersion: "0.1.0",
+  roots: [],
+  edges: [],
+};
+const defaultContinuityIndex = {
+  schemaVersion: "0.1.0",
+  sessionCount: 0,
+  lastUpdatedAt: null,
+};
+const defaultHookConfig = {
+  schemaVersion: "0.1.0",
+  compatibilityNamespace: ["prebuild", "prerelease"],
+  runtimeNamespace: [
+    "prompt_submit",
+    "pre_action",
+    "post_action",
+    "failure",
+    "session_start",
+    "cwd_changed",
+    "file_changed",
+    "workspace_created",
+  ],
+  hooks: [],
+};
+const defaultTaskRegistry = {
+  schemaVersion: "0.1.0",
+  leader: "leader",
+  workers: [],
+  tasks: [],
+};
+const defaultWorkspaceIndex = {
+  schemaVersion: "0.1.0",
+  items: [],
+};
+const defaultDecisions = {
+  schemaVersion: "0.1.0",
+  decisions: [],
+};
+const defaultManagerRuns = {
+  schemaVersion: "0.1.0",
+  runs: [],
+};
+const terminalManagerStates = new Set(["completed", "blocked", "failed", "cancelled"]);
+
+function coerceValidated(value, fallback, label, predicate, invalidArtifacts) {
+  if (predicate(value)) {
+    return value;
+  }
+
+  invalidArtifacts.push(label);
+  return fallback;
+}
+
+export async function ensureRuntimeSubsystems() {
+  for (const seedRuntimeSubsystem of runtimeSubsystemSeeders) {
+    await seedRuntimeSubsystem();
+  }
+}
+
+function getMailboxProposalPath(kind) {
+  return path.join(getTaskMailboxRoot(), `${Date.now()}-${kind}-${randomUUID()}.json`);
+}
+
+export function isLeaderActor(actor = "leader") {
+  return actor === "leader";
+}
+
+export async function loadLeaderAuthority() {
+  try {
+    const registry = await readJson(getTaskRegistryPath());
+    const isValidRegistry =
+      registry &&
+      typeof registry === "object" &&
+      typeof registry.leader === "string" &&
+      Array.isArray(registry.workers) &&
+      Array.isArray(registry.tasks);
+
+    if (!isValidRegistry) {
+      return { state: "invalid", leaderActor: null };
+    }
+
+    return { state: "ok", leaderActor: registry.leader };
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return { state: "missing", leaderActor: "leader" };
+    }
+
+    return { state: "invalid", leaderActor: null };
+  }
+}
+
+export async function assertLeaderAuthority(actor) {
+  const authority = await loadLeaderAuthority();
+  if (authority.state === "invalid") {
+    throw new Error("Invalid runtime authority: tasks.registry");
+  }
+
+  const leaderActor = authority.leaderActor ?? "leader";
+  const effectiveActor = actor ?? leaderActor;
+  if (effectiveActor !== leaderActor) {
+    throw new Error("Leader authority required");
+  }
+
+  return authority;
+}
+
+export async function queueMailboxProposal({ actor, kind, payload }) {
+  const proposal = {
+    schemaVersion: "0.1.0",
+    actor,
+    kind,
+    payload,
+    proposedAt: new Date().toISOString(),
+  };
+  const target = getMailboxProposalPath(kind);
+  await writeJson(target, proposal);
+  return target;
+}
+
+export async function guardLeaderMutation({ actor, kind, payload }) {
+  const authority = await loadLeaderAuthority();
+  if (authority.state === "invalid") {
+    throw new Error("Invalid runtime authority: tasks.registry");
+  }
+  const leaderActor = authority.leaderActor ?? "leader";
+  const effectiveActor = actor ?? leaderActor;
+  if (effectiveActor === leaderActor) {
+    return { allowed: true, proposalPath: null };
+  }
+
+  const proposalPath = await queueMailboxProposal({ actor: effectiveActor, kind, payload });
+  return { allowed: false, proposalPath };
+}
+
+export async function loadRuntimeSnapshot() {
+  const missingArtifacts = [];
+  const invalidArtifacts = [];
+  const readJsonWithStatus = async (filePath, fallback, label) => {
+    try {
+      return await readJson(filePath);
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+        missingArtifacts.push(label);
+      } else {
+        invalidArtifacts.push(label);
+      }
+      return fallback;
+    }
+  };
+  const readTextWithStatus = async (filePath, fallback, label) => {
+    try {
+      return await fs.readFile(filePath, "utf8");
+    } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+        missingArtifacts.push(label);
+      } else {
+        invalidArtifacts.push(label);
+      }
+      return fallback;
+    }
+  };
+  const mailboxEntries = await fs.readdir(getTaskMailboxRoot()).catch(() => {
+    missingArtifacts.push("tasks.mailbox");
+    return [];
+  });
+  await fs.access(getRuntimeHooksAuditPath()).catch(() => {
+    missingArtifacts.push("hooks.audit");
+  });
+  await fs.access(getTaskLockRoot()).catch(() => {
+    missingArtifacts.push("tasks.locks");
+  });
+
+  const [
+    mergedGuidance,
+    guidanceGraph,
+    continuityIndex,
+    continuityNotes,
+    hookConfig,
+    taskRegistry,
+    workspaceIndex,
+    release,
+    decisions,
+    managerRuns,
+  ] = await Promise.all([
+    readJsonWithStatus(getMergedGuidancePath(), defaultMergedGuidance, "guidance.merged"),
+    readJsonWithStatus(
+      getGuidanceIncludeGraphPath(),
+      defaultGuidanceGraph,
+      "guidance.includeGraph",
+    ),
+    readJsonWithStatus(getContinuityIndexPath(), defaultContinuityIndex, "memory.index"),
+    readTextWithStatus(getContinuityNotesPath(), "", "memory.notes"),
+    readJsonWithStatus(getRuntimeHooksConfigPath(), defaultHookConfig, "hooks.config"),
+    readJsonWithStatus(getTaskRegistryPath(), defaultTaskRegistry, "tasks.registry"),
+    readJsonWithStatus(getWorkspacesIndexPath(), defaultWorkspaceIndex, "workspaces.index"),
+    (async () => {
+      try {
+        return validateReleaseState(
+          JSON.parse(await fs.readFile(getRuntimeReadPath("release.json"), "utf8")),
+        );
+      } catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+          missingArtifacts.push("runtime.release");
+        } else {
+          invalidArtifacts.push("runtime.release");
+        }
+
+        return createDefaultReleaseState();
+      }
+    })(),
+    readJsonWithStatus(getRuntimeReadPath("decisions.json"), defaultDecisions, "runtime.decisions"),
+    readJsonWithStatus(getManagerRunsPath(), defaultManagerRuns, "runtime.managerRuns"),
+  ]);
+  const validatedMergedGuidance = coerceValidated(
+    mergedGuidance,
+    defaultMergedGuidance,
+    "guidance.merged",
+    (value) =>
+      value &&
+      typeof value === "object" &&
+      Array.isArray(value.sources) &&
+      typeof value.content === "string",
+    invalidArtifacts,
+  );
+  const validatedGuidanceGraph = coerceValidated(
+    guidanceGraph,
+    defaultGuidanceGraph,
+    "guidance.includeGraph",
+    (value) =>
+      value &&
+      typeof value === "object" &&
+      Array.isArray(value.roots) &&
+      Array.isArray(value.edges),
+    invalidArtifacts,
+  );
+  const validatedContinuityIndex = coerceValidated(
+    continuityIndex,
+    defaultContinuityIndex,
+    "memory.index",
+    (value) =>
+      value &&
+      typeof value === "object" &&
+      typeof value.sessionCount === "number" &&
+      "lastUpdatedAt" in value,
+    invalidArtifacts,
+  );
+  const validatedHookConfig = coerceValidated(
+    hookConfig,
+    defaultHookConfig,
+    "hooks.config",
+    (value) =>
+      value &&
+      typeof value === "object" &&
+      Array.isArray(value.compatibilityNamespace) &&
+      Array.isArray(value.runtimeNamespace) &&
+      Array.isArray(value.hooks),
+    invalidArtifacts,
+  );
+  const validatedTaskRegistry = coerceValidated(
+    taskRegistry,
+    defaultTaskRegistry,
+    "tasks.registry",
+    (value) =>
+      value &&
+      typeof value === "object" &&
+      typeof value.leader === "string" &&
+      Array.isArray(value.workers) &&
+      Array.isArray(value.tasks),
+    invalidArtifacts,
+  );
+  const validatedWorkspaceIndex = coerceValidated(
+    workspaceIndex,
+    defaultWorkspaceIndex,
+    "workspaces.index",
+    (value) => value && typeof value === "object" && Array.isArray(value.items),
+    invalidArtifacts,
+  );
+  const validatedDecisions = coerceValidated(
+    decisions,
+    defaultDecisions,
+    "runtime.decisions",
+    (value) => value && typeof value === "object" && Array.isArray(value.decisions),
+    invalidArtifacts,
+  );
+  const validatedManagerRuns = coerceValidated(
+    managerRuns,
+    defaultManagerRuns,
+    "runtime.managerRuns",
+    (value) => value && typeof value === "object" && Array.isArray(value.runs),
+    invalidArtifacts,
+  );
+
+  return {
+    mergedGuidance: validatedMergedGuidance,
+    guidanceGraph: validatedGuidanceGraph,
+    continuityIndex: validatedContinuityIndex,
+    continuityNotes,
+    hookConfig: validatedHookConfig,
+    taskRegistry: validatedTaskRegistry,
+    mailboxEntries,
+    workspaceIndex: validatedWorkspaceIndex,
+    release,
+    decisions: validatedDecisions,
+    managerRuns: validatedManagerRuns,
+    missingArtifacts,
+    invalidArtifacts,
+  };
+}
+
+export function createRuntimeSummary(snapshot) {
+  const trimmedNotes = snapshot.continuityNotes.trim();
+  return {
+    guidanceSourceCount: snapshot.mergedGuidance.sources.length,
+    guidanceIncludeRoots: snapshot.guidanceGraph.roots.length,
+    continuitySessionCount: snapshot.continuityIndex.sessionCount,
+    continuityHasNotes:
+      trimmedNotes.length > 0 &&
+      trimmedNotes !== "# Continuity Notes\n\nNo continuity notes captured yet.",
+    compatibilityHookCount: snapshot.hookConfig.compatibilityNamespace.length,
+    runtimeHookCount: snapshot.hookConfig.runtimeNamespace.length,
+    configuredRuntimeHookCount: snapshot.hookConfig.hooks.length,
+    workerCount: snapshot.taskRegistry.workers.length,
+    taskCount: snapshot.taskRegistry.tasks.length,
+    pendingMailboxCount: snapshot.mailboxEntries.length,
+    workspaceCount: snapshot.workspaceIndex.items.length,
+    decisionCount: snapshot.decisions.decisions.length,
+    managerRunCount: snapshot.managerRuns.runs.length,
+    activeManagerRunCount: snapshot.managerRuns.runs.filter(
+      (run) => !terminalManagerStates.has(run.state),
+    ).length,
+    waitingReviewManagerRunCount: snapshot.managerRuns.runs.filter(
+      (run) => run.state === "waiting-review",
+    ).length,
+    buildStatus: snapshot.release.build_status,
+    missingArtifacts: snapshot.missingArtifacts,
+    invalidArtifacts: snapshot.invalidArtifacts,
+  };
+}

package/src/runtime/signal-hooks.js

@@ -0,0 +1,52 @@
+import fs from "node:fs/promises";
+import { ensureDir, readJson, writeFileIfMissing } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+const runtimeEvents = [
+  "prompt_submit",
+  "pre_action",
+  "post_action",
+  "failure",
+  "session_start",
+  "cwd_changed",
+  "file_changed",
+  "workspace_created",
+];
+
+export function getRuntimeHooksRoot() {
+  return getRuntimeSubsystemPath("hooks");
+}
+
+export function getRuntimeHooksConfigPath() {
+  return getRuntimeSubsystemPath("hooks", "config.json");
+}
+
+export function getRuntimeHooksAuditPath() {
+  return getRuntimeSubsystemPath("hooks", "audit.log");
+}
+
+export async function seedSignalHookArtifacts() {
+  await ensureDir(getRuntimeHooksRoot());
+  await writeFileIfMissing(
+    getRuntimeHooksConfigPath(),
+    `${JSON.stringify(
+      {
+        schemaVersion: "0.1.0",
+        compatibilityNamespace: ["prebuild", "prerelease"],
+        runtimeNamespace: runtimeEvents,
+        hooks: [],
+      },
+      null,
+      2,
+    )}\n`,
+  );
+  await writeFileIfMissing(getRuntimeHooksAuditPath(), "");
+}
+
+export async function loadRuntimeHooksConfig() {
+  return readJson(getRuntimeHooksConfigPath());
+}
+
+export async function loadRuntimeHooksAuditLog() {
+  return fs.readFile(getRuntimeHooksAuditPath(), "utf8");
+}

package/src/runtime/startup-path.js

@@ -0,0 +1,14 @@
+export function createStartupCheckpoint(name, startedAt = Date.now()) {
+  return {
+    name,
+    startedAt,
+  };
+}
+
+export function completeStartupCheckpoint(checkpoint, endedAt = Date.now()) {
+  return {
+    ...checkpoint,
+    endedAt,
+    durationMs: endedAt - checkpoint.startedAt,
+  };
+}

package/src/runtime/workspaces.js

@@ -0,0 +1,25 @@
+import { ensureDir, writeFileIfMissing } from "../fs-utils.js";
+import { getRuntimeSubsystemPath } from "../paths.js";
+
+export function getWorkspacesRoot() {
+  return getRuntimeSubsystemPath("workspaces");
+}
+
+export function getWorkspacesIndexPath() {
+  return getRuntimeSubsystemPath("workspaces", "index.json");
+}
+
+export async function seedWorkspaceArtifacts() {
+  await ensureDir(getWorkspacesRoot());
+  await writeFileIfMissing(
+    getWorkspacesIndexPath(),
+    `${JSON.stringify(
+      {
+        schemaVersion: "0.1.0",
+        items: [],
+      },
+      null,
+      2,
+    )}\n`,
+  );
+}