@bastani/atomic 0.5.20 → 0.5.21-1

package/src/sdk/runtime/status-writer.test.ts

@@ -0,0 +1,245 @@
+/**
+ * Unit tests for the workflow status writer.
+ *
+ * Covers the pure helpers (overall-status derivation, snapshot
+ * construction, tmux-name → run-id parsing) and the file I/O round
+ * trip against a real temp directory.
+ */
+
+import { describe, test, expect } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  buildSnapshot,
+  deriveOverallStatus,
+  readSnapshot,
+  workflowRunIdFromTmuxName,
+  writeSnapshot,
+  type WorkflowStatusSnapshot,
+} from "./status-writer.ts";
+import type { SessionData } from "../components/orchestrator-panel-types.ts";
+
+function session(
+  name: string,
+  status: SessionData["status"],
+  extra: Partial<SessionData> = {},
+): SessionData {
+  return {
+    name,
+    status,
+    parents: [],
+    startedAt: 1000,
+    endedAt: null,
+    ...extra,
+  };
+}
+
+// ─── deriveOverallStatus ────────────────────────────────────────────
+
+describe("deriveOverallStatus", () => {
+  test("returns 'error' when fatalError is set, even if completion is reached", () => {
+    expect(
+      deriveOverallStatus({
+        sessions: [],
+        fatalError: "boom",
+        completionReached: true,
+      }),
+    ).toBe("error");
+  });
+
+  test("returns 'error' when any session ended in error", () => {
+    expect(
+      deriveOverallStatus({
+        sessions: [session("a", "complete"), session("b", "error")],
+        fatalError: null,
+        completionReached: false,
+      }),
+    ).toBe("error");
+  });
+
+  test("returns 'needs_review' when any session is awaiting_input", () => {
+    expect(
+      deriveOverallStatus({
+        sessions: [session("a", "running"), session("b", "awaiting_input")],
+        fatalError: null,
+        completionReached: false,
+      }),
+    ).toBe("needs_review");
+  });
+
+  test("'needs_review' wins over 'completed' so a HIL pause near the end isn't reported as done", () => {
+    expect(
+      deriveOverallStatus({
+        sessions: [session("a", "complete"), session("b", "awaiting_input")],
+        fatalError: null,
+        completionReached: true,
+      }),
+    ).toBe("needs_review");
+  });
+
+  test("returns 'completed' when completionReached and nothing errored or paused", () => {
+    expect(
+      deriveOverallStatus({
+        sessions: [session("a", "complete"), session("b", "complete")],
+        fatalError: null,
+        completionReached: true,
+      }),
+    ).toBe("completed");
+  });
+
+  test("returns 'in_progress' as the default", () => {
+    expect(
+      deriveOverallStatus({
+        sessions: [session("a", "running")],
+        fatalError: null,
+        completionReached: false,
+      }),
+    ).toBe("in_progress");
+  });
+});
+
+// ─── workflowRunIdFromTmuxName ──────────────────────────────────────
+
+describe("workflowRunIdFromTmuxName", () => {
+  test("extracts the trailing 8-hex segment from a workflow session name", () => {
+    expect(workflowRunIdFromTmuxName("atomic-wf-claude-ralph-a1b2c3d4")).toBe(
+      "a1b2c3d4",
+    );
+  });
+
+  test("handles workflow names containing hyphens", () => {
+    expect(
+      workflowRunIdFromTmuxName("atomic-wf-claude-deep-research-12345678"),
+    ).toBe("12345678");
+  });
+
+  test("returns null for chat sessions", () => {
+    expect(workflowRunIdFromTmuxName("atomic-chat-claude-deadbeef")).toBeNull();
+  });
+
+  test("returns null when the suffix is not 8-char hex", () => {
+    expect(workflowRunIdFromTmuxName("atomic-wf-claude-ralph-not-hex")).toBeNull();
+  });
+
+  test("returns null for an unrelated session name", () => {
+    expect(workflowRunIdFromTmuxName("my-session")).toBeNull();
+  });
+});
+
+// ─── buildSnapshot ──────────────────────────────────────────────────
+
+describe("buildSnapshot", () => {
+  test("populates schemaVersion + identifying fields and clones session arrays", () => {
+    const fixed = new Date("2026-01-01T00:00:00.000Z");
+    const sourceParents = ["orchestrator"];
+    const sourceSession = session("orchestrator", "running", { parents: sourceParents });
+    const snap = buildSnapshot(
+      {
+        workflowRunId: "abcd1234",
+        tmuxSession: "atomic-wf-claude-ralph-abcd1234",
+        workflowName: "ralph",
+        agent: "claude",
+        prompt: "hello",
+        fatalError: null,
+        completionReached: false,
+        sessions: [sourceSession],
+      },
+      () => fixed,
+    );
+
+    expect(snap.schemaVersion).toBe(1);
+    expect(snap.workflowRunId).toBe("abcd1234");
+    expect(snap.tmuxSession).toBe("atomic-wf-claude-ralph-abcd1234");
+    expect(snap.workflowName).toBe("ralph");
+    expect(snap.agent).toBe("claude");
+    expect(snap.prompt).toBe("hello");
+    expect(snap.overall).toBe("in_progress");
+    expect(snap.updatedAt).toBe("2026-01-01T00:00:00.000Z");
+    expect(snap.sessions).toHaveLength(1);
+    expect(snap.sessions[0]!.name).toBe("orchestrator");
+    // parents must be cloned, not aliased to the input array — otherwise
+    // a later panel-store mutation would silently rewrite a snapshot
+    // that we already handed to a consumer.
+    expect(snap.sessions[0]!.parents).not.toBe(sourceParents);
+    expect(snap.sessions[0]!.parents).toEqual(sourceParents);
+  });
+
+  test("propagates the derived overall status from the inputs", () => {
+    const snap = buildSnapshot({
+      workflowRunId: "abcd1234",
+      tmuxSession: "x",
+      workflowName: "ralph",
+      agent: "claude",
+      prompt: "",
+      fatalError: null,
+      completionReached: true,
+      sessions: [session("a", "complete")],
+    });
+    expect(snap.overall).toBe("completed");
+  });
+});
+
+// ─── write/read round trip ──────────────────────────────────────────
+
+describe("writeSnapshot + readSnapshot", () => {
+  test("persists a snapshot and reads it back unchanged", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "atomic-status-"));
+    try {
+      const snap: WorkflowStatusSnapshot = buildSnapshot({
+        workflowRunId: "abcd1234",
+        tmuxSession: "atomic-wf-claude-ralph-abcd1234",
+        workflowName: "ralph",
+        agent: "claude",
+        prompt: "hello",
+        fatalError: null,
+        completionReached: false,
+        sessions: [session("orchestrator", "running")],
+      });
+
+      await writeSnapshot(dir, snap);
+      const back = await readSnapshot(dir);
+      expect(back).not.toBeNull();
+      expect(back!.workflowRunId).toBe("abcd1234");
+      expect(back!.overall).toBe("in_progress");
+      expect(back!.sessions).toHaveLength(1);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("returns null when status.json does not exist", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "atomic-status-"));
+    try {
+      const back = await readSnapshot(dir);
+      expect(back).toBeNull();
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("returns null when status.json is malformed JSON", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "atomic-status-"));
+    try {
+      await Bun.write(join(dir, "status.json"), "not-json");
+      const back = await readSnapshot(dir);
+      expect(back).toBeNull();
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("returns null when status.json fails the snapshot shape guard", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "atomic-status-"));
+    try {
+      await Bun.write(
+        join(dir, "status.json"),
+        JSON.stringify({ schemaVersion: 99, foo: "bar" }),
+      );
+      const back = await readSnapshot(dir);
+      expect(back).toBeNull();
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/sdk/runtime/status-writer.ts

@@ -0,0 +1,201 @@
+/**
+ * Workflow status snapshot — bridges the in-process panel state with
+ * out-of-process consumers (e.g. `atomic workflow status`).
+ *
+ * The orchestrator subscribes to its `PanelStore` and writes a fresh
+ * snapshot to `~/.atomic/sessions/<workflowRunId>/status.json` every
+ * time the store mutates. Consumers read that file to derive the
+ * overall workflow state without needing IPC into the orchestrator.
+ */
+
+import { join } from "node:path";
+import type { SessionData, SessionStatus } from "../components/orchestrator-panel-types.ts";
+
+/** File name used for the status snapshot inside each workflow's session directory. */
+export const STATUS_FILE_NAME = "status.json";
+
+/** High-level workflow state surfaced to the agent / CLI consumer. */
+export type WorkflowOverallStatus =
+  | "in_progress"
+  | "error"
+  | "completed"
+  | "needs_review";
+
+/** Per-session entry mirrored from the orchestrator's panel store. */
+export interface WorkflowStatusSession {
+  name: string;
+  status: SessionStatus;
+  parents: string[];
+  error?: string;
+  startedAt: number | null;
+  endedAt: number | null;
+}
+
+/**
+ * Snapshot persisted to disk for `atomic workflow status` to read.
+ * Schema is versioned so future readers can stay backwards-compatible.
+ */
+export interface WorkflowStatusSnapshot {
+  schemaVersion: 1;
+  workflowRunId: string;
+  tmuxSession: string;
+  workflowName: string;
+  agent: string;
+  prompt: string;
+  /** Overall state derived from per-session status + completion flags. */
+  overall: WorkflowOverallStatus;
+  /** True when the orchestrator has shown its completion banner. */
+  completionReached: boolean;
+  /** Fatal-error message set via `panel.showFatalError`, if any. */
+  fatalError: string | null;
+  /** Wall-clock time of the snapshot in ISO-8601 format. */
+  updatedAt: string;
+  sessions: WorkflowStatusSession[];
+}
+
+/**
+ * Inputs the writer needs to render a snapshot — a strict subset of
+ * `PanelStore` so the writer doesn't depend on the renderer module.
+ */
+export interface StatusWriterInputs {
+  workflowRunId: string;
+  tmuxSession: string;
+  workflowName: string;
+  agent: string;
+  prompt: string;
+  fatalError: string | null;
+  completionReached: boolean;
+  sessions: readonly SessionData[];
+}
+
+/**
+ * Derive the overall workflow state from per-session statuses + the
+ * orchestrator-level completion / fatal-error flags.
+ *
+ * Precedence (highest first):
+ *   1. `error`          — fatal error or any session ended in error
+ *   2. `needs_review`   — at least one session is awaiting human input (HIL)
+ *   3. `completed`      — completion banner reached and nothing errored
+ *   4. `in_progress`    — default
+ *
+ * `needs_review` outranks `completed` so an agent that pauses for HIL
+ * right at the end is never reported as done while still waiting.
+ */
+export function deriveOverallStatus(input: {
+  sessions: readonly SessionData[];
+  completionReached: boolean;
+  fatalError: string | null;
+}): WorkflowOverallStatus {
+  if (input.fatalError !== null) return "error";
+  if (input.sessions.some((s) => s.status === "error")) return "error";
+  if (input.sessions.some((s) => s.status === "awaiting_input")) {
+    return "needs_review";
+  }
+  if (input.completionReached) return "completed";
+  return "in_progress";
+}
+
+/** Build a snapshot from the writer inputs (pure — exported for tests). */
+export function buildSnapshot(
+  input: StatusWriterInputs,
+  now: () => Date = () => new Date(),
+): WorkflowStatusSnapshot {
+  return {
+    schemaVersion: 1,
+    workflowRunId: input.workflowRunId,
+    tmuxSession: input.tmuxSession,
+    workflowName: input.workflowName,
+    agent: input.agent,
+    prompt: input.prompt,
+    overall: deriveOverallStatus({
+      sessions: input.sessions,
+      completionReached: input.completionReached,
+      fatalError: input.fatalError,
+    }),
+    completionReached: input.completionReached,
+    fatalError: input.fatalError,
+    updatedAt: now().toISOString(),
+    sessions: input.sessions.map((s) => ({
+      name: s.name,
+      status: s.status,
+      parents: [...s.parents],
+      ...(s.error !== undefined ? { error: s.error } : {}),
+      startedAt: s.startedAt,
+      endedAt: s.endedAt,
+    })),
+  };
+}
+
+/** Absolute path of the status file for a given workflow run directory. */
+export function statusFilePath(sessionDir: string): string {
+  return join(sessionDir, STATUS_FILE_NAME);
+}
+
+/**
+ * Write a snapshot to `<sessionDir>/status.json`. Uses an atomic
+ * write-then-rename so concurrent readers never see partial JSON.
+ * Errors are swallowed — the orchestrator must keep running even if
+ * the status file can't be persisted.
+ */
+export async function writeSnapshot(
+  sessionDir: string,
+  snapshot: WorkflowStatusSnapshot,
+): Promise<void> {
+  const finalPath = statusFilePath(sessionDir);
+  const tmpPath = `${finalPath}.tmp-${process.pid}`;
+  try {
+    await Bun.write(tmpPath, JSON.stringify(snapshot, null, 2));
+    const { rename } = await import("node:fs/promises");
+    await rename(tmpPath, finalPath);
+  } catch {
+    // Best-effort — never fail the workflow because of a status write.
+  }
+}
+
+/**
+ * Read a snapshot from disk. Returns `null` when the file doesn't
+ * exist or fails to parse — callers fall back to deriving status from
+ * the live tmux session list.
+ */
+export async function readSnapshot(
+  sessionDir: string,
+): Promise<WorkflowStatusSnapshot | null> {
+  try {
+    const file = Bun.file(statusFilePath(sessionDir));
+    if (!(await file.exists())) return null;
+    const parsed: unknown = JSON.parse(await file.text());
+    if (!isSnapshot(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** Runtime guard for deserialised snapshots — keeps the reader type-safe. */
+function isSnapshot(value: unknown): value is WorkflowStatusSnapshot {
+  if (!value || typeof value !== "object") return false;
+  const v = value as Record<string, unknown>;
+  return (
+    v.schemaVersion === 1 &&
+    typeof v.workflowRunId === "string" &&
+    typeof v.tmuxSession === "string" &&
+    typeof v.overall === "string" &&
+    Array.isArray(v.sessions)
+  );
+}
+
+/**
+ * Extract the `workflowRunId` (the trailing 8-hex segment) from a
+ * tmux session name shaped `atomic-wf-<agent>-<name>-<id>`. Returns
+ * `null` for non-workflow sessions or names that don't end in a
+ * UUID-style suffix.
+ */
+export function workflowRunIdFromTmuxName(name: string): string | null {
+  if (!name.startsWith("atomic-wf-")) return null;
+  const lastDash = name.lastIndexOf("-");
+  if (lastDash < 0) return null;
+  const candidate = name.slice(lastDash + 1);
+  // generateId() produces an 8-char hex slice from crypto.randomUUID.
+  if (!/^[0-9a-f]{8}$/i.test(candidate)) return null;
+  return candidate;
+}

package/src/sdk/runtime/version-compat.ts

@@ -0,0 +1,68 @@
+/**
+ * Tiny semver comparator used to check a workflow's declared
+ * `minSDKVersion` against the bundled CLI {@link VERSION}.
+ *
+ * Accepts the subset of semver we actually ship: `MAJOR.MINOR.PATCH`
+ * with an optional numeric prerelease (e.g. `0.5.21`, `0.5.21-0`).
+ * Anything more exotic (build metadata, alpha tags) is treated as a
+ * plain string and compared lexicographically on the prerelease tail,
+ * which is good enough for "is the installed CLI new enough?".
+ *
+ * Isolated from the `semver` npm package so the workflow loader stays
+ * dependency-free — this check runs for every discovered workflow on
+ * every CLI launch.
+ */
+
+interface ParsedVersion {
+  major: number;
+  minor: number;
+  patch: number;
+  prerelease: string;
+}
+
+function parseVersion(v: string): ParsedVersion | null {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(v.trim());
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ?? "",
+  };
+}
+
+/**
+ * Return a negative number if `a < b`, positive if `a > b`, 0 if equal.
+ * Unparseable inputs compare as equal so we never block a workflow over
+ * a typo in its `minSDKVersion` — the visible load error is friendlier
+ * than a hard refusal.
+ */
+export function compareVersions(a: string, b: string): number {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  if (!pa || !pb) return 0;
+
+  if (pa.major !== pb.major) return pa.major - pb.major;
+  if (pa.minor !== pb.minor) return pa.minor - pb.minor;
+  if (pa.patch !== pb.patch) return pa.patch - pb.patch;
+
+  // Per semver, a version without a prerelease outranks one with a
+  // prerelease at the same MAJOR.MINOR.PATCH (1.0.0 > 1.0.0-0).
+  if (pa.prerelease === "" && pb.prerelease !== "") return 1;
+  if (pa.prerelease !== "" && pb.prerelease === "") return -1;
+  if (pa.prerelease === pb.prerelease) return 0;
+  return pa.prerelease < pb.prerelease ? -1 : 1;
+}
+
+/**
+ * True when the current CLI is new enough to run a workflow that
+ * declared `minRequired`. A null/undefined requirement always
+ * satisfies — workflows that don't opt in are treated as compatible.
+ */
+export function satisfiesMinVersion(
+  current: string,
+  minRequired: string | null | undefined,
+): boolean {
+  if (!minRequired) return true;
+  return compareVersions(current, minRequired) >= 0;
+}

package/src/sdk/types.ts

@@ -366,6 +366,22 @@ export interface WorkflowOptions<
    * and enforce them on `ctx.inputs`.
    */
   inputs?: I;
+  /**
+   * Minimum Atomic CLI version this workflow is known to work with.
+   *
+   * When set, the CLI refuses to load the workflow on an older install
+   * and surfaces an actionable "update required" entry in the picker
+   * and `atomic workflow -l` output instead of silently dropping it.
+   *
+   * Leave unset (the default) to opt out entirely — the workflow will
+   * be treated as compatible with every CLI version. Use this when you
+   * consume a new SDK feature (new provider API, a new field on the
+   * stage options, etc.) that older installs can't honour.
+   *
+   * Accepts `MAJOR.MINOR.PATCH` with an optional numeric prerelease
+   * (`0.6.0`, `0.6.0-0`). Invalid strings are ignored.
+   */
+  minSDKVersion?: string;
 }
 
 /**
@@ -377,6 +393,11 @@ export interface WorkflowDefinition<A extends AgentType = AgentType, N extends s
   readonly description: string;
   /** Declared input schema — empty array for free-form workflows. */
   readonly inputs: readonly WorkflowInput[];
+  /**
+   * Minimum Atomic SDK version required. `null` when the workflow
+   * declared no requirement — treated as compatible with every CLI.
+   */
+  readonly minSDKVersion: string | null;
   /** The workflow's entry point. Called by the executor with a WorkflowContext. */
   readonly run: (ctx: WorkflowContext<A, N>) => Promise<void>;
 }

package/src/sdk/workflows/index.ts

@@ -105,6 +105,7 @@ export {
 export type {
   DiscoveredWorkflow,
   WorkflowWithMetadata,
+  WorkflowMetadataStatus,
 } from "../runtime/discovery.ts";
 
 // Runtime — workflow loader pipeline