@bastani/atomic 0.5.0-2 → 0.5.0-4

package/src/sdk/components/orchestrator-panel-store.test.ts

@@ -558,4 +558,160 @@ describe("PanelStore", () => {
       expect(emitCount.value).toBe(7);
     });
   });
+
+  // ── addSession ──────────────────────────────────────────────────────────────
+
+  describe("addSession", () => {
+    test("appends a new session to the sessions array", () => {
+      store.setWorkflowInfo("wf", "copilot", [], "prompt");
+      const beforeCount = store.sessions.length;
+
+      store.addSession({
+        name: "dynamic-1",
+        status: "running",
+        parents: ["orchestrator"],
+        startedAt: Date.now(),
+        endedAt: null,
+      });
+
+      expect(store.sessions.length).toBe(beforeCount + 1);
+      expect(store.sessions.at(-1)!.name).toBe("dynamic-1");
+      expect(store.sessions.at(-1)!.status).toBe("running");
+    });
+
+    test("increments version on add", () => {
+      store.setWorkflowInfo("wf", "copilot", [], "prompt");
+      const v = store.version;
+
+      store.addSession({
+        name: "dynamic-2",
+        status: "running",
+        parents: ["orchestrator"],
+        startedAt: Date.now(),
+        endedAt: null,
+      });
+
+      expect(store.version).toBe(v + 1);
+    });
+
+    test("notifies subscribers on add", () => {
+      const listener = mock(() => {});
+      store.subscribe(listener);
+      store.setWorkflowInfo("wf", "copilot", [], "prompt");
+      listener.mockClear();
+
+      store.addSession({
+        name: "dynamic-3",
+        status: "running",
+        parents: ["orchestrator"],
+        startedAt: Date.now(),
+        endedAt: null,
+      });
+
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    test("dynamically added session can be started/completed", () => {
+      store.setWorkflowInfo("wf", "copilot", [], "prompt");
+
+      store.addSession({
+        name: "dynamic-4",
+        status: "running",
+        parents: ["orchestrator"],
+        startedAt: Date.now(),
+        endedAt: null,
+      });
+
+      store.completeSession("dynamic-4");
+      const session = store.sessions.find((s) => s.name === "dynamic-4");
+      expect(session!.status).toBe("complete");
+      expect(session!.endedAt).not.toBeNull();
+    });
+
+    test("stores session with non-existent parent reference", () => {
+      store.setWorkflowInfo("wf", "copilot", [], "prompt");
+
+      store.addSession({
+        name: "orphan",
+        status: "running",
+        parents: ["nonexistent"],
+        startedAt: Date.now(),
+        endedAt: null,
+      });
+
+      const session = store.sessions.find((s) => s.name === "orphan");
+      expect(session).toBeDefined();
+      expect(session!.parents).toEqual(["nonexistent"]);
+    });
+
+    test("stores session with empty parents array", () => {
+      store.setWorkflowInfo("wf", "copilot", [], "prompt");
+
+      store.addSession({
+        name: "no-parent",
+        status: "running",
+        parents: [],
+        startedAt: Date.now(),
+        endedAt: null,
+      });
+
+      const session = store.sessions.find((s) => s.name === "no-parent");
+      expect(session).toBeDefined();
+      expect(session!.parents).toEqual([]);
+    });
+
+    test("nested child added after parent via addSession", () => {
+      store.setWorkflowInfo("wf", "copilot", [], "prompt");
+
+      store.addSession({
+        name: "step-1",
+        status: "running",
+        parents: ["orchestrator"],
+        startedAt: Date.now(),
+        endedAt: null,
+      });
+
+      store.addSession({
+        name: "step-1-child",
+        status: "running",
+        parents: ["step-1"],
+        startedAt: Date.now(),
+        endedAt: null,
+      });
+
+      const child = store.sessions.find((s) => s.name === "step-1-child");
+      expect(child).toBeDefined();
+      expect(child!.parents).toEqual(["step-1"]);
+    });
+  });
+
+  // ── setWorkflowInfo edge cases ─────────────────────────────────────────────
+
+  describe("setWorkflowInfo edge cases", () => {
+    test("session with inter-session parent reference preserves parents", () => {
+      store.setWorkflowInfo("wf", "copilot", [
+        { name: "step-1", parents: [] },
+        { name: "step-2", parents: ["step-1"] },
+      ], "prompt");
+
+      const step1 = store.sessions.find((s) => s.name === "step-1");
+      const step2 = store.sessions.find((s) => s.name === "step-2");
+      // step-1 with empty parents gets ["orchestrator"]
+      expect(step1!.parents).toEqual(["orchestrator"]);
+      // step-2 with explicit parent keeps it
+      expect(step2!.parents).toEqual(["step-1"]);
+    });
+
+    test("deeply nested pre-defined sessions preserve hierarchy", () => {
+      store.setWorkflowInfo("wf", "copilot", [
+        { name: "s1", parents: [] },
+        { name: "s2", parents: ["s1"] },
+        { name: "s3", parents: ["s2"] },
+      ], "prompt");
+
+      expect(store.sessions.find((s) => s.name === "s1")!.parents).toEqual(["orchestrator"]);
+      expect(store.sessions.find((s) => s.name === "s2")!.parents).toEqual(["s1"]);
+      expect(store.sessions.find((s) => s.name === "s3")!.parents).toEqual(["s2"]);
+    });
+  });
 });

package/src/sdk/components/orchestrator-panel-store.ts

@@ -15,6 +15,7 @@ export class PanelStore {
   fatalError: string | null = null;
   completionReached = false;
   exitResolve: (() => void) | null = null;
+  abortResolve: (() => void) | null = null;
 
   private listeners = new Set<Listener>();
 
@@ -81,6 +82,11 @@ export class PanelStore {
     this.emit();
   }
 
+  addSession(session: SessionData): void {
+    this.sessions.push(session);
+    this.emit();
+  }
+
   setCompletion(workflowName: string, transcriptsPath: string): void {
     this.completionInfo = { workflowName, transcriptsPath };
     const orch = this.sessions.find((s) => s.name === "orchestrator");
@@ -111,6 +117,24 @@ export class PanelStore {
     }
   }
 
+  /** Safely invoke abortResolve at most once to signal mid-execution quit. */
+  resolveAbort(): void {
+    if (this.abortResolve) {
+      const resolve = this.abortResolve;
+      this.abortResolve = null;
+      resolve();
+    }
+  }
+
+  /** Quit the workflow — routes to the correct handler based on current phase. */
+  requestQuit(): void {
+    if (this.completionReached) {
+      this.resolveExit();
+    } else {
+      this.resolveAbort();
+    }
+  }
+
   markCompletionReached(): void {
     this.completionReached = true;
     this.emit();

package/src/sdk/components/orchestrator-panel.tsx

@@ -111,6 +111,17 @@ export class OrchestratorPanel {
     this.store.failSession(name, message);
   }
 
+  /** Dynamically add a new session node to the graph UI. */
+  addSession(name: string, parents: string[]): void {
+    this.store.addSession({
+      name,
+      status: "running",
+      parents,
+      startedAt: Date.now(),
+      endedAt: null,
+    });
+  }
+
   /** Show the workflow-complete banner with a link to saved transcripts. */
   showCompletion(workflowName: string, transcriptsPath: string): void {
     this.store.setCompletion(workflowName, transcriptsPath);
@@ -132,6 +143,16 @@ export class OrchestratorPanel {
     });
   }
 
+  /**
+   * Returns a promise that resolves when the user requests a mid-execution quit
+   * (via `q` or `Ctrl+C`). Race this against the workflow run.
+   */
+  waitForAbort(): Promise<void> {
+    return new Promise<void>((resolve) => {
+      this.store.abortResolve = resolve;
+    });
+  }
+
   /** Tear down the terminal renderer and release resources. Idempotent. */
   destroy(): void {
     if (this.destroyed) return;

package/src/sdk/components/session-graph-panel.tsx

@@ -180,15 +180,9 @@ export function SessionGraphPanel() {
 
   // Keyboard handling
   useKeyboard((key) => {
-    // Ctrl+C always exits
-    if (key.ctrl && key.name === "c") {
-      store.resolveExit();
-      return;
-    }
-
-    // After completion: only q exits (Enter is for attach, Escape is too easy to hit)
-    if (store.completionReached && key.name === "q") {
-      store.resolveExit();
+    // Ctrl+C or q: quit the workflow (abort if running, exit if completed)
+    if ((key.ctrl && key.name === "c") || key.name === "q") {
+      store.requestQuit();
       return;
     }
 

package/src/sdk/components/statusline.tsx

@@ -1,6 +1,6 @@
 /** @jsxImportSource @opentui/react */
 
-import { useStore, useGraphTheme } from "./orchestrator-panel-contexts.ts";
+import { useGraphTheme } from "./orchestrator-panel-contexts.ts";
 import { statusIcon, statusColor, statusLabel } from "./status-helpers.ts";
 import type { LayoutNode } from "./layout.ts";
 
@@ -11,11 +11,9 @@ export function Statusline({
   focusedNode: LayoutNode | undefined;
   attachMsg: string;
 }) {
-  const store = useStore();
   const theme = useGraphTheme();
   const ni = focusedNode ? statusIcon(focusedNode.status) : "";
   const nc = focusedNode ? statusColor(focusedNode.status, theme) : theme.textDim;
-  const canExit = store.completionReached;
 
   return (
     <box height={1} flexDirection="row" backgroundColor={theme.backgroundElement}>
@@ -52,9 +50,9 @@ export function Statusline({
             <span fg={theme.textDim}> {"\u00B7"} </span>
             <span fg={theme.text}>{"\u21B5"}</span>
             <span fg={theme.textMuted}> attach</span>
-            {canExit ? <span fg={theme.textDim}> {"\u00B7"} </span> : null}
-            {canExit ? <span fg={theme.text}>q</span> : null}
-            {canExit ? <span fg={theme.textMuted}> quit</span> : null}
+            <span fg={theme.textDim}> {"\u00B7"} </span>
+            <span fg={theme.text}>q</span>
+            <span fg={theme.textMuted}> quit</span>
           </text>
         )}
       </box>

package/src/sdk/define-workflow.test.ts

@@ -0,0 +1,71 @@
+import { test, expect, describe } from "bun:test";
+import { defineWorkflow, WorkflowBuilder } from "./define-workflow.ts";
+
+describe("defineWorkflow", () => {
+  test("returns a WorkflowBuilder", () => {
+    const builder = defineWorkflow({ name: "test" });
+    expect(builder).toBeInstanceOf(WorkflowBuilder);
+    expect(builder.__brand).toBe("WorkflowBuilder");
+  });
+
+  test("throws on empty name", () => {
+    expect(() => defineWorkflow({ name: "" })).toThrow("Workflow name is required");
+  });
+
+  test("throws on whitespace-only name", () => {
+    expect(() => defineWorkflow({ name: "   " })).toThrow("Workflow name is required");
+  });
+});
+
+describe("WorkflowBuilder.run()", () => {
+  test("accepts a function and returns this for chaining", () => {
+    const builder = defineWorkflow({ name: "test" });
+    const result = builder.run(async () => {});
+    expect(result).toBe(builder);
+  });
+
+  test("throws if called twice", () => {
+    const builder = defineWorkflow({ name: "test" }).run(async () => {});
+    expect(() => builder.run(async () => {})).toThrow("run() can only be called once");
+  });
+
+  test("throws if argument is not a function", () => {
+    const builder = defineWorkflow({ name: "test" });
+    expect(() => builder.run("not a function" as never)).toThrow("run() requires a function");
+  });
+});
+
+describe("WorkflowBuilder.compile()", () => {
+  test("produces a WorkflowDefinition with correct brand", () => {
+    const def = defineWorkflow({ name: "test" })
+      .run(async () => {})
+      .compile();
+    expect(def.__brand).toBe("WorkflowDefinition");
+  });
+
+  test("preserves name and description", () => {
+    const def = defineWorkflow({ name: "my-wf", description: "A description" })
+      .run(async () => {})
+      .compile();
+    expect(def.name).toBe("my-wf");
+    expect(def.description).toBe("A description");
+  });
+
+  test("defaults description to empty string", () => {
+    const def = defineWorkflow({ name: "test" })
+      .run(async () => {})
+      .compile();
+    expect(def.description).toBe("");
+  });
+
+  test("stores the run function", () => {
+    const fn = async () => {};
+    const def = defineWorkflow({ name: "test" }).run(fn).compile();
+    expect(def.run).toBe(fn);
+  });
+
+  test("throws if no run callback was provided", () => {
+    const builder = defineWorkflow({ name: "test" });
+    expect(() => builder.compile()).toThrow("has no run callback");
+  });
+});

package/src/sdk/define-workflow.ts

@@ -1,75 +1,71 @@
 /**
- * Workflow Builder — chainable DSL for defining multi-session workflows.
+ * Workflow Builder — defines a workflow with a single `.run()` entry point.
  *
  * Usage:
- *   defineWorkflow({ name: "ralph", description: "..." })
- *     .session({ name: "research", run: async (ctx) => { ... } })
- *     .session({ name: "plan", run: async (ctx) => { ... } })
+ *   defineWorkflow({ name: "my-workflow", description: "..." })
+ *     .run(async (ctx) => {
+ *       await ctx.session({ name: "research" }, async (s) => { ... });
+ *       await ctx.session({ name: "plan" }, async (s) => { ... });
+ *     })
  *     .compile()
  */
 
-import type { WorkflowOptions, SessionOptions, WorkflowDefinition } from "./types.ts";
+import type { WorkflowOptions, WorkflowContext, WorkflowDefinition } from "./types.ts";
 
 /**
- * Chainable workflow builder. Records session definitions in order,
- * then .compile() seals them into a WorkflowDefinition.
+ * Chainable workflow builder. Records the run callback,
+ * then .compile() seals it into a WorkflowDefinition.
  */
 export class WorkflowBuilder {
   /** @internal Brand for detection across package boundaries */
   readonly __brand = "WorkflowBuilder" as const;
   private readonly options: WorkflowOptions;
-  private readonly stepDefs: SessionOptions[][] = [];
-  private readonly namesSeen = new Set<string>();
+  private runFn: ((ctx: WorkflowContext) => Promise<void>) | null = null;
 
   constructor(options: WorkflowOptions) {
     this.options = options;
   }
 
   /**
-   * Add a session (or parallel group of sessions) to the workflow.
+   * Set the workflow's entry point.
    *
-   * Pass a single SessionOptions for sequential execution.
-   * Pass an array of SessionOptions for parallel execution —
-   * all sessions in the array run concurrently, and the next
-   * .session() call waits for the entire group to complete.
+   * The callback receives a {@link WorkflowContext} with `session()` for
+   * spawning agent sessions, and `transcript()` / `getMessages()` for
+   * reading completed session outputs. Use native TypeScript control flow
+   * (loops, conditionals, `Promise.all()`) for orchestration.
    */
-  session(opts: SessionOptions | SessionOptions[]): this {
-    const step = Array.isArray(opts) ? opts : [opts];
-    if (step.length === 0) {
-      throw new Error("session() requires at least one SessionOptions.");
+  run(fn: (ctx: WorkflowContext) => Promise<void>): this {
+    if (this.runFn) {
+      throw new Error("run() can only be called once per workflow.");
     }
-    for (const s of step) {
-      if (!s.name || s.name.trim() === "") {
-        throw new Error("Session name is required.");
-      }
-      if (typeof s.run !== "function") {
-        throw new Error(`Session "${s.name}": run must be a function, got ${typeof s.run}.`);
-      }
-      if (this.namesSeen.has(s.name)) {
-        throw new Error(`Duplicate session name: "${s.name}"`);
-      }
-      this.namesSeen.add(s.name);
+    if (typeof fn !== "function") {
+      throw new Error(`run() requires a function, got ${typeof fn}.`);
     }
-    this.stepDefs.push(step);
+    this.runFn = fn;
     return this;
   }
 
   /**
    * Compile the workflow into a sealed WorkflowDefinition.
    *
-   * After calling compile(), no more sessions can be added.
-   * The returned object is consumed by the Atomic CLI runtime.
+   * After calling compile(), the returned object is consumed by the
+   * Atomic CLI runtime.
    */
   compile(): WorkflowDefinition {
-    if (this.stepDefs.length === 0) {
-      throw new Error(`Workflow "${this.options.name}" has no sessions. Add at least one .session() call.`);
+    if (!this.runFn) {
+      throw new Error(
+        `Workflow "${this.options.name}" has no run callback. ` +
+          `Add a .run(async (ctx) => { ... }) call before .compile().`,
+      );
     }
 
+    const runFn = this.runFn;
+
     return {
       __brand: "WorkflowDefinition" as const,
       name: this.options.name,
       description: this.options.description ?? "",
-      steps: Object.freeze(this.stepDefs.map((step) => Object.freeze([...step]))),
+      run: runFn,
     };
   }
 }
@@ -82,11 +78,18 @@ export class WorkflowBuilder {
  * import { defineWorkflow } from "@bastani/atomic/workflows";
  *
  * export default defineWorkflow({
- *   name: "ralph",
- *   description: "Research, plan, implement",
+ *   name: "hello",
+ *   description: "Two-session demo",
  * })
- *   .session({ name: "research", run: async (ctx) => { ... } })
- *   .session({ name: "plan", run: async (ctx) => { ... } })
+ *   .run(async (ctx) => {
+ *     const describe = await ctx.session({ name: "describe" }, async (s) => {
+ *       // ... agent SDK code using s.serverUrl, s.paneId, s.save() ...
+ *     });
+ *     await ctx.session({ name: "summarize" }, async (s) => {
+ *       const research = await s.transcript(describe);
+ *       // ...
+ *     });
+ *   })
  *   .compile();
  * ```
  */

package/src/sdk/errors.ts

@@ -20,7 +20,7 @@ export class WorkflowNotCompiledError extends Error {
       `Workflow at ${path} was defined but not compiled.\n` +
       `  Add .compile() at the end of your defineWorkflow() chain:\n\n` +
       `    export default defineWorkflow({ ... })\n` +
-      `      .session({ ... })\n` +
+      `      .run(async (ctx) => { ... })\n` +
       `      .compile();`,
     );
     this.name = "WorkflowNotCompiledError";

package/src/sdk/index.ts

@@ -19,7 +19,10 @@ export type {
   SavedMessage,
   SaveTranscript,
   SessionContext,
-  SessionOptions,
+  SessionRef,
+  SessionHandle,
+  SessionRunOptions,
+  WorkflowContext,
   WorkflowOptions,
   WorkflowDefinition,
 } from "./types.ts";

package/src/sdk/providers/claude.ts

@@ -307,7 +307,7 @@ export function validateClaudeWorkflow(source: string): ClaudeValidationWarning[
         rule: "claude/create-session",
         message:
           "Could not verify that createClaudeSession is called before claudeQuery(). " +
-          "Call createClaudeSession({ paneId: ctx.paneId }) to start the Claude CLI before sending queries.",
+          "Call createClaudeSession({ paneId: s.paneId }) to start the Claude CLI before sending queries.",
       });
     }
   }

package/src/sdk/providers/copilot.ts

@@ -2,7 +2,7 @@
  * Copilot workflow source validation.
  *
  * Checks that Copilot workflow source files follow required patterns:
- * - `cliUrl` is wired to `ctx.serverUrl` (or destructured `serverUrl`)
+ * - `cliUrl` is wired to the session context's `serverUrl`
  * - `setForegroundSessionId` is called after creating a session
  */
 
@@ -18,11 +18,13 @@ export function validateCopilotWorkflow(source: string): CopilotValidationWarnin
   const warnings: CopilotValidationWarning[] = [];
 
   if (/\bCopilotClient\b/.test(source)) {
-    if (!/cliUrl\s*:\s*(?:ctx\.serverUrl|serverUrl)/.test(source)) {
+    // Accept any identifier before .serverUrl (e.g., s.serverUrl, ctx.serverUrl)
+    // or a destructured `serverUrl` variable
+    if (!/cliUrl\s*:\s*(?:\w+\.serverUrl|serverUrl)/.test(source)) {
       warnings.push({
         rule: "copilot/cli-url",
         message:
-          "Could not verify that CopilotClient is created with { cliUrl: ctx.serverUrl }. " +
+          "Could not verify that CopilotClient is created with { cliUrl: s.serverUrl }. " +
           "This is required to connect to the workflow's agent pane.",
       });
     }

package/src/sdk/providers/opencode.ts

@@ -2,7 +2,7 @@
  * OpenCode workflow source validation.
  *
  * Checks that OpenCode workflow source files follow required patterns:
- * - `baseUrl` is wired to `ctx.serverUrl` (or destructured `serverUrl`)
+ * - `baseUrl` is wired to the session context's `serverUrl`
  * - `tui.selectSession` is called after creating a session
  */
 
@@ -18,11 +18,13 @@ export function validateOpenCodeWorkflow(source: string): OpenCodeValidationWarn
   const warnings: OpenCodeValidationWarning[] = [];
 
   if (/\bcreateOpencodeClient\b/.test(source)) {
-    if (!/baseUrl\s*:\s*(?:ctx\.serverUrl|serverUrl)/.test(source)) {
+    // Accept any identifier before .serverUrl (e.g., s.serverUrl, ctx.serverUrl)
+    // or a destructured `serverUrl` variable
+    if (!/baseUrl\s*:\s*(?:\w+\.serverUrl|serverUrl)/.test(source)) {
       warnings.push({
         rule: "opencode/base-url",
         message:
-          "Could not verify that createOpencodeClient is called with { baseUrl: ctx.serverUrl }. " +
+          "Could not verify that createOpencodeClient is called with { baseUrl: s.serverUrl }. " +
           "This is required to connect to the workflow's agent pane.",
       });
     }