@bastani/atomic 0.5.0 → 0.5.1

package/.atomic/workflows/hello/claude/index.ts

@@ -8,32 +8,31 @@
  * Run: atomic workflow -n hello -a claude "describe this project"
  */
 
-import { defineWorkflow, createClaudeSession, claudeQuery } from "@bastani/atomic/workflows";
+import { defineWorkflow } from "@bastani/atomic/workflows";
 
-export default defineWorkflow({
+export default defineWorkflow<"claude">({
   name: "hello",
   description: "Two-session Claude demo: describe → summarize",
 })
   .run(async (ctx) => {
-    const describe = await ctx.session(
+    const describe = await ctx.stage(
       { name: "describe", description: "Ask Claude to describe the project" },
+      {},
+      {},
       async (s) => {
-        await createClaudeSession({ paneId: s.paneId });
-        await claudeQuery({ paneId: s.paneId, prompt: s.userPrompt });
+        await s.session.query(s.userPrompt);
         s.save(s.sessionId);
       },
     );
 
-    await ctx.session(
+    await ctx.stage(
       { name: "summarize", description: "Summarize the previous session's output" },
+      {},
+      {},
       async (s) => {
-        await createClaudeSession({ paneId: s.paneId });
         const research = await s.transcript(describe);
 
-        await claudeQuery({
-          paneId: s.paneId,
-          prompt: `Read ${research.path} and summarize it in 2-3 bullet points.`,
-        });
+        await s.session.query(`Read ${research.path} and summarize it in 2-3 bullet points.`);
         s.save(s.sessionId);
       },
     );

package/.atomic/workflows/hello/copilot/index.ts

@@ -8,7 +8,6 @@
  */
 
 import { defineWorkflow } from "@bastani/atomic/workflows";
-import { CopilotClient, approveAll } from "@github/copilot-sdk";
 
 /**
  * `CopilotSession.sendAndWait` defaults to a 60s timeout and THROWS on
@@ -17,51 +16,37 @@ import { CopilotClient, approveAll } from "@github/copilot-sdk";
  */
 const SEND_TIMEOUT_MS = 30 * 60 * 1000;
 
-export default defineWorkflow({
+export default defineWorkflow<"copilot">({
   name: "hello",
   description: "Two-session Copilot demo: describe → summarize",
 })
   .run(async (ctx) => {
-    const describe = await ctx.session(
+    const describe = await ctx.stage(
       { name: "describe", description: "Ask the agent to describe the project" },
+      {},
+      {},
       async (s) => {
-        const client = new CopilotClient({ cliUrl: s.serverUrl });
-        await client.start();
+        await s.session.sendAndWait({ prompt: s.userPrompt }, SEND_TIMEOUT_MS);
 
-        const session = await client.createSession({ onPermissionRequest: approveAll });
-        await client.setForegroundSessionId(session.sessionId);
-
-        await session.sendAndWait({ prompt: s.userPrompt }, SEND_TIMEOUT_MS);
-
-        s.save(await session.getMessages());
-
-        await session.disconnect();
-        await client.stop();
+        s.save(await s.session.getMessages());
       },
     );
 
-    await ctx.session(
+    await ctx.stage(
       { name: "summarize", description: "Summarize the previous session's output" },
+      {},
+      {},
       async (s) => {
         const research = await s.transcript(describe);
 
-        const client = new CopilotClient({ cliUrl: s.serverUrl });
-        await client.start();
-
-        const session = await client.createSession({ onPermissionRequest: approveAll });
-        await client.setForegroundSessionId(session.sessionId);
-
-        await session.sendAndWait(
+        await s.session.sendAndWait(
           {
             prompt: `Summarize the following in 2-3 bullet points:\n\n${research.content}`,
           },
           SEND_TIMEOUT_MS,
         );
 
-        s.save(await session.getMessages());
-
-        await session.disconnect();
-        await client.stop();
+        s.save(await s.session.getMessages());
       },
     );
   })

package/.atomic/workflows/hello/opencode/index.ts

@@ -8,23 +8,19 @@
  */
 
 import { defineWorkflow } from "@bastani/atomic/workflows";
-import { createOpencodeClient } from "@opencode-ai/sdk/v2";
 
-export default defineWorkflow({
+export default defineWorkflow<"opencode">({
   name: "hello",
   description: "Two-session OpenCode demo: describe → summarize",
 })
   .run(async (ctx) => {
-    const describe = await ctx.session(
+    const describe = await ctx.stage(
       { name: "describe", description: "Ask the agent to describe the project" },
+      {},
+      { title: "describe" },
       async (s) => {
-        const client = createOpencodeClient({ baseUrl: s.serverUrl });
-
-        const session = await client.session.create({ title: "describe" });
-        await client.tui.selectSession({ sessionID: session.data!.id });
-
-        const result = await client.session.prompt({
-          sessionID: session.data!.id,
+        const result = await s.client.session.prompt({
+          sessionID: s.session.id,
           parts: [{ type: "text", text: s.userPrompt }],
         });
 
@@ -32,17 +28,15 @@ export default defineWorkflow({
       },
     );
 
-    await ctx.session(
+    await ctx.stage(
       { name: "summarize", description: "Summarize the previous session's output" },
+      {},
+      { title: "summarize" },
       async (s) => {
         const research = await s.transcript(describe);
-        const client = createOpencodeClient({ baseUrl: s.serverUrl });
-
-        const session = await client.session.create({ title: "summarize" });
-        await client.tui.selectSession({ sessionID: session.data!.id });
 
-        const result = await client.session.prompt({
-          sessionID: session.data!.id,
+        const result = await s.client.session.prompt({
+          sessionID: s.session.id,
           parts: [
             {
               type: "text",

package/.atomic/workflows/hello-parallel/claude/index.ts

@@ -8,58 +8,55 @@
  * Run: atomic workflow -n hello-parallel -a claude "describe this project"
  */
 
-import { defineWorkflow, createClaudeSession, claudeQuery } from "@bastani/atomic/workflows";
+import { defineWorkflow } from "@bastani/atomic/workflows";
 
-export default defineWorkflow({
+export default defineWorkflow<"claude">({
   name: "hello-parallel",
   description: "Parallel Claude demo: describe → [summarize-a, summarize-b] → merge",
 })
   .run(async (ctx) => {
-    const describe = await ctx.session(
+    const describe = await ctx.stage(
       { name: "describe", description: "Ask Claude to describe the project" },
+      {},
+      {},
       async (s) => {
-        await createClaudeSession({ paneId: s.paneId });
-        await claudeQuery({ paneId: s.paneId, prompt: s.userPrompt });
+        await s.session.query(s.userPrompt);
         s.save(s.sessionId);
       },
     );
 
     const [summarizeA, summarizeB] = await Promise.all([
-      ctx.session(
+      ctx.stage(
         { name: "summarize-a", description: "Summarize the description as bullet points" },
+        {},
+        {},
         async (s) => {
           const research = await s.transcript(describe);
-          await createClaudeSession({ paneId: s.paneId });
-          await claudeQuery({
-            paneId: s.paneId,
-            prompt: `Read ${research.path} and summarize it in 2-3 bullet points.`,
-          });
+          await s.session.query(`Read ${research.path} and summarize it in 2-3 bullet points.`);
           s.save(s.sessionId);
         },
       ),
-      ctx.session(
+      ctx.stage(
         { name: "summarize-b", description: "Summarize the description as a one-liner" },
+        {},
+        {},
         async (s) => {
           const research = await s.transcript(describe);
-          await createClaudeSession({ paneId: s.paneId });
-          await claudeQuery({
-            paneId: s.paneId,
-            prompt: `Read ${research.path} and summarize it in a single sentence.`,
-          });
+          await s.session.query(`Read ${research.path} and summarize it in a single sentence.`);
           s.save(s.sessionId);
         },
       ),
     ]);
 
-    await ctx.session(
+    await ctx.stage(
       { name: "merge", description: "Merge both summaries into a final output" },
+      {},
+      {},
       async (s) => {
         const bullets = await s.transcript(summarizeA);
         const oneliner = await s.transcript(summarizeB);
-        await createClaudeSession({ paneId: s.paneId });
-        await claudeQuery({
-          paneId: s.paneId,
-          prompt: [
+        await s.session.query(
+          [
             "Combine the following two summaries into one concise paragraph:",
             "",
             "## Bullet points",
@@ -68,7 +65,7 @@ export default defineWorkflow({
             "## One-liner",
             oneliner.content,
           ].join("\n"),
-        });
+        );
         s.save(s.sessionId);
       },
     );

package/.atomic/workflows/hello-parallel/copilot/index.ts

@@ -9,7 +9,6 @@
  */
 
 import { defineWorkflow } from "@bastani/atomic/workflows";
-import { CopilotClient, approveAll } from "@github/copilot-sdk";
 
 /**
  * `CopilotSession.sendAndWait` defaults to a 60s timeout and THROWS on
@@ -18,89 +17,71 @@ import { CopilotClient, approveAll } from "@github/copilot-sdk";
  */
 const SEND_TIMEOUT_MS = 30 * 60 * 1000;
 
-export default defineWorkflow({
+export default defineWorkflow<"copilot">({
   name: "hello-parallel",
   description: "Parallel Copilot demo: describe → [summarize-a, summarize-b] → merge",
 })
   .run(async (ctx) => {
     // Sequential: describe
-    const describe = await ctx.session(
+    const describe = await ctx.stage(
       { name: "describe", description: "Ask the agent to describe the project" },
+      {},
+      {},
       async (s) => {
-        const client = new CopilotClient({ cliUrl: s.serverUrl });
-        await client.start();
+        await s.session.sendAndWait({ prompt: s.userPrompt }, SEND_TIMEOUT_MS);
 
-        const session = await client.createSession({ onPermissionRequest: approveAll });
-        await client.setForegroundSessionId(session.sessionId);
-        await session.sendAndWait({ prompt: s.userPrompt }, SEND_TIMEOUT_MS);
-
-        s.save(await session.getMessages());
-        await session.disconnect();
-        await client.stop();
+        s.save(await s.session.getMessages());
       },
     );
 
     // Parallel: summarize-a + summarize-b
     const [summarizeA, summarizeB] = await Promise.all([
-      ctx.session(
+      ctx.stage(
         { name: "summarize-a", description: "Summarize the description as bullet points" },
+        {},
+        {},
         async (s) => {
           const research = await s.transcript(describe);
 
-          const client = new CopilotClient({ cliUrl: s.serverUrl });
-          await client.start();
-
-          const session = await client.createSession({ onPermissionRequest: approveAll });
-          await client.setForegroundSessionId(session.sessionId);
-          await session.sendAndWait(
+          await s.session.sendAndWait(
             {
               prompt: `Summarize the following in 2-3 bullet points:\n\n${research.content}`,
             },
             SEND_TIMEOUT_MS,
           );
 
-          s.save(await session.getMessages());
-          await session.disconnect();
-          await client.stop();
+          s.save(await s.session.getMessages());
         },
       ),
-      ctx.session(
+      ctx.stage(
         { name: "summarize-b", description: "Summarize the description as a one-liner" },
+        {},
+        {},
         async (s) => {
           const research = await s.transcript(describe);
 
-          const client = new CopilotClient({ cliUrl: s.serverUrl });
-          await client.start();
-
-          const session = await client.createSession({ onPermissionRequest: approveAll });
-          await client.setForegroundSessionId(session.sessionId);
-          await session.sendAndWait(
+          await s.session.sendAndWait(
             {
               prompt: `Summarize the following in a single sentence:\n\n${research.content}`,
             },
             SEND_TIMEOUT_MS,
           );
 
-          s.save(await session.getMessages());
-          await session.disconnect();
-          await client.stop();
+          s.save(await s.session.getMessages());
         },
       ),
     ]);
 
     // Sequential: merge
-    await ctx.session(
+    await ctx.stage(
       { name: "merge", description: "Merge both summaries into a final output" },
+      {},
+      {},
       async (s) => {
         const bullets = await s.transcript(summarizeA);
         const oneliner = await s.transcript(summarizeB);
 
-        const client = new CopilotClient({ cliUrl: s.serverUrl });
-        await client.start();
-
-        const session = await client.createSession({ onPermissionRequest: approveAll });
-        await client.setForegroundSessionId(session.sessionId);
-        await session.sendAndWait(
+        await s.session.sendAndWait(
           {
             prompt: [
               "Combine the following two summaries into one concise paragraph:",
@@ -115,9 +96,7 @@ export default defineWorkflow({
           SEND_TIMEOUT_MS,
         );
 
-        s.save(await session.getMessages());
-        await session.disconnect();
-        await client.stop();
+        s.save(await s.session.getMessages());
       },
     );
   })

package/.atomic/workflows/hello-parallel/opencode/index.ts

@@ -9,23 +9,19 @@
  */
 
 import { defineWorkflow } from "@bastani/atomic/workflows";
-import { createOpencodeClient } from "@opencode-ai/sdk/v2";
 
-export default defineWorkflow({
+export default defineWorkflow<"opencode">({
   name: "hello-parallel",
   description: "Parallel OpenCode demo: describe → [summarize-a, summarize-b] → merge",
 })
   .run(async (ctx) => {
-    const describe = await ctx.session(
+    const describe = await ctx.stage(
       { name: "describe", description: "Ask the agent to describe the project" },
+      {},
+      { title: "describe" },
       async (s) => {
-        const client = createOpencodeClient({ baseUrl: s.serverUrl });
-
-        const session = await client.session.create({ title: "describe" });
-        await client.tui.selectSession({ sessionID: session.data!.id });
-
-        const result = await client.session.prompt({
-          sessionID: session.data!.id,
+        const result = await s.client.session.prompt({
+          sessionID: s.session.id,
           parts: [{ type: "text", text: s.userPrompt }],
         });
 
@@ -34,17 +30,15 @@ export default defineWorkflow({
     );
 
     const [summarizeA, summarizeB] = await Promise.all([
-      ctx.session(
+      ctx.stage(
         { name: "summarize-a", description: "Summarize the description as bullet points" },
+        {},
+        { title: "summarize-a" },
         async (s) => {
           const research = await s.transcript(describe);
-          const client = createOpencodeClient({ baseUrl: s.serverUrl });
-
-          const session = await client.session.create({ title: "summarize-a" });
-          await client.tui.selectSession({ sessionID: session.data!.id });
 
-          const result = await client.session.prompt({
-            sessionID: session.data!.id,
+          const result = await s.client.session.prompt({
+            sessionID: s.session.id,
             parts: [
               {
                 type: "text",
@@ -56,17 +50,15 @@ export default defineWorkflow({
           s.save(result.data!);
         },
       ),
-      ctx.session(
+      ctx.stage(
         { name: "summarize-b", description: "Summarize the description as a one-liner" },
+        {},
+        { title: "summarize-b" },
         async (s) => {
           const research = await s.transcript(describe);
-          const client = createOpencodeClient({ baseUrl: s.serverUrl });
 
-          const session = await client.session.create({ title: "summarize-b" });
-          await client.tui.selectSession({ sessionID: session.data!.id });
-
-          const result = await client.session.prompt({
-            sessionID: session.data!.id,
+          const result = await s.client.session.prompt({
+            sessionID: s.session.id,
             parts: [
               {
                 type: "text",
@@ -80,18 +72,16 @@ export default defineWorkflow({
       ),
     ]);
 
-    await ctx.session(
+    await ctx.stage(
       { name: "merge", description: "Merge both summaries into a final output" },
+      {},
+      { title: "merge" },
       async (s) => {
         const bullets = await s.transcript(summarizeA);
         const oneliner = await s.transcript(summarizeB);
-        const client = createOpencodeClient({ baseUrl: s.serverUrl });
-
-        const session = await client.session.create({ title: "merge" });
-        await client.tui.selectSession({ sessionID: session.data!.id });
 
-        const result = await client.session.prompt({
-          sessionID: session.data!.id,
+        const result = await s.client.session.prompt({
+          sessionID: s.session.id,
           parts: [
             {
               type: "text",

package/.atomic/workflows/ralph/claude/index.ts

@@ -10,11 +10,7 @@
  * Run: atomic workflow -n ralph -a claude "<your spec>"
  */
 
-import {
-  defineWorkflow,
-  createClaudeSession,
-  claudeQuery,
-} from "@bastani/atomic/workflows";
+import { defineWorkflow } from "@bastani/atomic/workflows";
 
 import {
   buildPlannerPrompt,
@@ -35,7 +31,7 @@ function asAgentCall(agentName: string, prompt: string): string {
   return `@"${agentName} (agent)" ${prompt}`;
 }
 
-export default defineWorkflow({
+export default defineWorkflow<"claude">({
   name: "ralph",
   description:
     "Plan → orchestrate → review → debug loop with bounded iteration",
@@ -43,73 +39,66 @@ export default defineWorkflow({
   .run(async (ctx) => {
     let consecutiveClean = 0;
     let debuggerReport = "";
-    // Track the most recent session so the next stage can declare it as a
-    // dependency — this chains planner → orchestrator → reviewer → [confirm]
-    // → [debugger] → next planner in the graph instead of showing every
-    // stage as an independent sibling under the root.
-    let prevStage: string | undefined;
-    const depsOn = (): string[] | undefined =>
-      prevStage ? [prevStage] : undefined;
 
     for (let iteration = 1; iteration <= MAX_LOOPS; iteration++) {
       // ── Plan ────────────────────────────────────────────────────────────
       const plannerName = `planner-${iteration}`;
-      await ctx.session(
-        { name: plannerName, dependsOn: depsOn() },
+      await ctx.stage(
+        { name: plannerName },
+        {},
+        {},
         async (s) => {
-          await createClaudeSession({ paneId: s.paneId });
-          await claudeQuery({
-            paneId: s.paneId,
-            prompt: asAgentCall(
+          await s.session.query(
+            asAgentCall(
               "planner",
               buildPlannerPrompt(s.userPrompt, {
                 iteration,
                 debuggerReport: debuggerReport || undefined,
               }),
             ),
-          });
+          );
           s.save(s.sessionId);
         },
       );
-      prevStage = plannerName;
+
 
       // ── Orchestrate ─────────────────────────────────────────────────────
       const orchName = `orchestrator-${iteration}`;
-      await ctx.session(
-        { name: orchName, dependsOn: depsOn() },
+      await ctx.stage(
+        { name: orchName },
+        {},
+        {},
         async (s) => {
-          await createClaudeSession({ paneId: s.paneId });
-          await claudeQuery({
-            paneId: s.paneId,
-            prompt: asAgentCall(
+          await s.session.query(
+            asAgentCall(
               "orchestrator",
               buildOrchestratorPrompt(s.userPrompt),
             ),
-          });
+          );
           s.save(s.sessionId);
         },
       );
-      prevStage = orchName;
+
 
       // ── Review (first pass) ─────────────────────────────────────────────
       let gitStatus = await safeGitStatusS();
       const reviewerName = `reviewer-${iteration}`;
-      const review = await ctx.session(
-        { name: reviewerName, dependsOn: depsOn() },
+      const review = await ctx.stage(
+        { name: reviewerName },
+        {},
+        {},
         async (s) => {
-          await createClaudeSession({ paneId: s.paneId });
-          const result = await claudeQuery({
-            paneId: s.paneId,
-            prompt: asAgentCall(
+          const result = await s.session.query(
+            asAgentCall(
               "reviewer",
               buildReviewPrompt(s.userPrompt, { gitStatus, iteration }),
             ),
-          });
+          );
           s.save(s.sessionId);
           return result.output;
         },
       );
-      prevStage = reviewerName;
+
 
       let reviewRaw = review.result;
       let parsed = parseReviewResult(reviewRaw);
@@ -121,13 +110,13 @@ export default defineWorkflow({
         // Confirmation pass — re-run reviewer only
         gitStatus = await safeGitStatusS();
         const confirmName = `reviewer-${iteration}-confirm`;
-        const confirm = await ctx.session(
-          { name: confirmName, dependsOn: depsOn() },
+        const confirm = await ctx.stage(
+          { name: confirmName },
+          {},
+          {},
           async (s) => {
-            await createClaudeSession({ paneId: s.paneId });
-            const result = await claudeQuery({
-              paneId: s.paneId,
-              prompt: asAgentCall(
+            const result = await s.session.query(
+              asAgentCall(
                 "reviewer",
                 buildReviewPrompt(s.userPrompt, {
                   gitStatus,
@@ -135,12 +124,12 @@ export default defineWorkflow({
                   isConfirmationPass: true,
                 }),
               ),
-            });
+            );
             s.save(s.sessionId);
             return result.output;
           },
         );
-        prevStage = confirmName;
+
 
         reviewRaw = confirm.result;
         parsed = parseReviewResult(reviewRaw);
@@ -158,25 +147,25 @@ export default defineWorkflow({
       // ── Debug (only if findings remain AND another iteration is allowed) ─
       if (hasActionableFindings(parsed, reviewRaw) && iteration < MAX_LOOPS) {
         const debuggerName = `debugger-${iteration}`;
-        const debugger_ = await ctx.session(
-          { name: debuggerName, dependsOn: depsOn() },
+        const debugger_ = await ctx.stage(
+          { name: debuggerName },
+          {},
+          {},
           async (s) => {
-            await createClaudeSession({ paneId: s.paneId });
-            const result = await claudeQuery({
-              paneId: s.paneId,
-              prompt: asAgentCall(
+            const result = await s.session.query(
+              asAgentCall(
                 "debugger",
                 buildDebuggerReportPrompt(parsed, reviewRaw, {
                   iteration,
                   gitStatus,
                 }),
               ),
-            });
+            );
             s.save(s.sessionId);
             return result.output;
           },
         );
-        prevStage = debuggerName;
+
         debuggerReport = extractMarkdownBlock(debugger_.result);
       }
     }