@bastani/atomic 0.5.0-3 → 0.5.0-5

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

@@ -1,18 +1,12 @@
 /**
  * Ralph workflow for Copilot — plan → orchestrate → review → debug loop.
  *
- * One CopilotClient backs every iteration; each loop step creates a fresh
- * sub-session bound to the appropriate sub-agent (planner, orchestrator,
- * reviewer, debugger). The loop terminates when:
+ * Each sub-agent invocation spawns its own visible session in the graph,
+ * so users can see each iteration's progress in real time. The loop
+ * terminates when:
  *   - {@link MAX_LOOPS} iterations have completed, OR
  *   - Two consecutive reviewer passes return zero findings.
  *
- * A loop is one cycle of plan → orchestrate → review. When a review returns
- * zero findings on the FIRST pass we re-run only the reviewer (still inside
- * the same loop iteration) to confirm; if that confirmation pass is also
- * clean we stop. The debugger only runs when findings remain, and its
- * markdown report is fed back into the next iteration's planner.
- *
  * Run: atomic workflow -n ralph -a copilot "<your spec>"
  */
 
@@ -33,16 +27,45 @@ import { safeGitStatusS } from "../helpers/git.ts";
 
 const MAX_LOOPS = 10;
 const CONSECUTIVE_CLEAN_THRESHOLD = 2;
+/**
+ * Per-agent send timeout. `CopilotSession.sendAndWait` defaults to 60s, which
+ * is far too short for real planner/orchestrator/reviewer/debugger work — a
+ * timeout there throws and aborts the whole workflow before the next stage
+ * can run. 30 minutes gives each sub-agent ample headroom while still
+ * surfacing truly hung sessions.
+ */
+const AGENT_SEND_TIMEOUT_MS = 30 * 60 * 1000;
 
-/** Concatenate the text content of every assistant message in an event stream. */
-function getLastAssistantText(messages: SessionEvent[]): string {
-  const assistantMessages = messages.filter(
-    (m): m is Extract<SessionEvent, { type: "assistant.message" }> =>
-      m.type === "assistant.message",
-  );
-  const last = assistantMessages.at(-1);
-  if (!last) return "";
-  return last.data.content;
+/**
+ * Concatenate the text content of every top-level assistant message in the
+ * event stream.
+ *
+ * Why not just `.at(-1)`? Two traps:
+ *
+ * 1. A single Copilot turn is one `assistant.message` event that carries BOTH
+ *    prose AND a `toolRequests[]` array. When the model ends a turn with
+ *    tool-calls-only (e.g. the planner's final `TaskList` verification call),
+ *    `content` is an empty string — picking the final message drops the
+ *    planner's actual reasoning from the earlier turns.
+ * 2. `assistant.message` events have a `parentToolCallId` field populated when
+ *    they originate from a sub-agent spawned by the parent. `getMessages()`
+ *    returns the complete history including those, so `.at(-1)` can land on a
+ *    sub-agent's final message instead of the top-level agent's. Filter them
+ *    out to get only the agent's own turns.
+ *
+ * Joining every non-empty top-level content string preserves the full
+ * commentary across all turns, which is what downstream stages (e.g. the
+ * orchestrator reading the planner's handoff) actually need.
+ */
+function getAssistantText(messages: SessionEvent[]): string {
+  return messages
+    .filter(
+      (m): m is Extract<SessionEvent, { type: "assistant.message" }> =>
+        m.type === "assistant.message" && !m.data.parentToolCallId,
+    )
+    .map((m) => m.data.content)
+    .filter((c) => c.length > 0)
+    .join("\n\n");
 }
 
 export default defineWorkflow({
@@ -50,113 +73,190 @@ export default defineWorkflow({
   description:
     "Plan → orchestrate → review → debug loop with bounded iteration",
 })
-  .session({
-    name: "ralph-loop",
-    description:
-      "Drive plan/orchestrate/review/debug iterations until clean or capped",
-    run: async (ctx) => {
-      const client = new CopilotClient({ cliUrl: ctx.serverUrl });
-      await client.start();
-
-      let lastMessages: SessionEvent[] = [];
-
-      /**
-       * Spin up a fresh sub-session bound to the named agent, send the
-       * prompt, await the response, then disconnect. Returns the text of the
-       * last assistant message so the caller can parse it.
-       */
-      async function runAgent(agent: string, prompt: string): Promise<string> {
-        const session = await client.createSession({
-          agent,
-          onPermissionRequest: approveAll,
-        });
-        await client.setForegroundSessionId(session.sessionId);
-
-        await session.sendAndWait({ prompt });
-
-        const messages = await session.getMessages();
-        lastMessages = messages;
-
-        await session.disconnect();
-        return getLastAssistantText(messages);
-      }
-
-      try {
-        let consecutiveClean = 0;
-        let debuggerReport = "";
+  .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 ──────────────────────────────────────────────────────────
-          await runAgent(
-            "planner",
-            buildPlannerPrompt(ctx.userPrompt, {
-              iteration,
-              debuggerReport: debuggerReport || undefined,
-            }),
+    for (let iteration = 1; iteration <= MAX_LOOPS; iteration++) {
+      // ── Plan ──────────────────────────────────────────────────────────
+      const plannerName = `planner-${iteration}`;
+      const planner = await ctx.session(
+        { name: plannerName, dependsOn: depsOn() },
+        async (s) => {
+          const client = new CopilotClient({ cliUrl: s.serverUrl });
+          await client.start();
+          const session = await client.createSession({
+            agent: "planner",
+            onPermissionRequest: approveAll,
+          });
+          await client.setForegroundSessionId(session.sessionId);
+          await session.sendAndWait(
+            {
+              prompt: buildPlannerPrompt(s.userPrompt, {
+                iteration,
+                debuggerReport: debuggerReport || undefined,
+              }),
+            },
+            AGENT_SEND_TIMEOUT_MS,
           );
+          const messages = await session.getMessages();
+          s.save(messages);
+          await session.disconnect();
+          await client.stop();
+          return getAssistantText(messages);
+        },
+      );
+      prevStage = plannerName;
 
-          // ── Orchestrate ───────────────────────────────────────────────────
-          await runAgent("orchestrator", buildOrchestratorPrompt());
-
-          // ── Review (first pass) ───────────────────────────────────────────
-          let gitStatus = await safeGitStatusS();
-          let reviewRaw = await runAgent(
-            "reviewer",
-            buildReviewPrompt(ctx.userPrompt, { gitStatus, iteration }),
+      // ── Orchestrate ───────────────────────────────────────────────────
+      const orchName = `orchestrator-${iteration}`;
+      await ctx.session(
+        { name: orchName, dependsOn: depsOn() },
+        async (s) => {
+          const client = new CopilotClient({ cliUrl: s.serverUrl });
+          await client.start();
+          const session = await client.createSession({
+            agent: "orchestrator",
+            onPermissionRequest: approveAll,
+          });
+          await client.setForegroundSessionId(session.sessionId);
+          await session.sendAndWait(
+            {
+              prompt: buildOrchestratorPrompt(s.userPrompt, {
+                plannerNotes: planner.result,
+              }),
+            },
+            AGENT_SEND_TIMEOUT_MS,
           );
-          let parsed = parseReviewResult(reviewRaw);
+          s.save(await session.getMessages());
+          await session.disconnect();
+          await client.stop();
+        },
+      );
+      prevStage = orchName;
 
-          if (!hasActionableFindings(parsed, reviewRaw)) {
-            consecutiveClean += 1;
-            if (consecutiveClean >= CONSECUTIVE_CLEAN_THRESHOLD) {
-              break;
-            }
-
-            // Confirmation pass — re-run reviewer only, NOT plan/orchestrate.
-            gitStatus = await safeGitStatusS();
-            reviewRaw = await runAgent(
-              "reviewer",
-              buildReviewPrompt(ctx.userPrompt, {
+      // ── Review (first pass) ───────────────────────────────────────────
+      let gitStatus = await safeGitStatusS();
+      const reviewerName = `reviewer-${iteration}`;
+      const review = await ctx.session(
+        { name: reviewerName, dependsOn: depsOn() },
+        async (s) => {
+          const client = new CopilotClient({ cliUrl: s.serverUrl });
+          await client.start();
+          const session = await client.createSession({
+            agent: "reviewer",
+            onPermissionRequest: approveAll,
+          });
+          await client.setForegroundSessionId(session.sessionId);
+          await session.sendAndWait(
+            {
+              prompt: buildReviewPrompt(s.userPrompt, {
                 gitStatus,
                 iteration,
-                isConfirmationPass: true,
               }),
-            );
-            parsed = parseReviewResult(reviewRaw);
+            },
+            AGENT_SEND_TIMEOUT_MS,
+          );
+          const messages = await session.getMessages();
+          s.save(messages);
+          await session.disconnect();
+          await client.stop();
+          return getAssistantText(messages);
+        },
+      );
+      prevStage = reviewerName;
 
-            if (!hasActionableFindings(parsed, reviewRaw)) {
-              consecutiveClean += 1;
-              if (consecutiveClean >= CONSECUTIVE_CLEAN_THRESHOLD) {
-                break;
-              }
-            } else {
-              consecutiveClean = 0;
-              // fall through to debugger
-            }
-          } else {
-            consecutiveClean = 0;
-          }
+      let reviewRaw = review.result;
+      let parsed = parseReviewResult(reviewRaw);
 
-          // ── Debug (only if findings remain AND another iteration is allowed) ─
-          if (
-            hasActionableFindings(parsed, reviewRaw) &&
-            iteration < MAX_LOOPS
-          ) {
-            const debuggerRaw = await runAgent(
-              "debugger",
-              buildDebuggerReportPrompt(parsed, reviewRaw, {
-                iteration,
-                gitStatus,
-              }),
+      if (!hasActionableFindings(parsed, reviewRaw)) {
+        consecutiveClean += 1;
+        if (consecutiveClean >= CONSECUTIVE_CLEAN_THRESHOLD) break;
+
+        // Confirmation pass — re-run reviewer only
+        gitStatus = await safeGitStatusS();
+        const confirmName = `reviewer-${iteration}-confirm`;
+        const confirm = await ctx.session(
+          { name: confirmName, dependsOn: depsOn() },
+          async (s) => {
+            const client = new CopilotClient({ cliUrl: s.serverUrl });
+            await client.start();
+            const session = await client.createSession({
+              agent: "reviewer",
+              onPermissionRequest: approveAll,
+            });
+            await client.setForegroundSessionId(session.sessionId);
+            await session.sendAndWait(
+              {
+                prompt: buildReviewPrompt(s.userPrompt, {
+                  gitStatus,
+                  iteration,
+                  isConfirmationPass: true,
+                }),
+              },
+              AGENT_SEND_TIMEOUT_MS,
             );
-            debuggerReport = extractMarkdownBlock(debuggerRaw);
-          }
+            const messages = await session.getMessages();
+            s.save(messages);
+            await session.disconnect();
+            await client.stop();
+            return getAssistantText(messages);
+          },
+        );
+        prevStage = confirmName;
+
+        reviewRaw = confirm.result;
+        parsed = parseReviewResult(reviewRaw);
+
+        if (!hasActionableFindings(parsed, reviewRaw)) {
+          consecutiveClean += 1;
+          if (consecutiveClean >= CONSECUTIVE_CLEAN_THRESHOLD) break;
+        } else {
+          consecutiveClean = 0;
         }
+      } else {
+        consecutiveClean = 0;
+      }
 
-        ctx.save(lastMessages);
-      } finally {
-        await client.stop();
+      // ── 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() },
+          async (s) => {
+            const client = new CopilotClient({ cliUrl: s.serverUrl });
+            await client.start();
+            const session = await client.createSession({
+              agent: "debugger",
+              onPermissionRequest: approveAll,
+            });
+            await client.setForegroundSessionId(session.sessionId);
+            await session.sendAndWait(
+              {
+                prompt: buildDebuggerReportPrompt(parsed, reviewRaw, {
+                  iteration,
+                  gitStatus,
+                }),
+              },
+              AGENT_SEND_TIMEOUT_MS,
+            );
+            const messages = await session.getMessages();
+            s.save(messages);
+            await session.disconnect();
+            await client.stop();
+            return getAssistantText(messages);
+          },
+        );
+        prevStage = debuggerName;
+        debuggerReport = extractMarkdownBlock(debugger_.result);
       }
-    },
+    }
   })
   .compile();

package/.atomic/workflows/ralph/helpers/prompts.ts

@@ -110,14 +110,57 @@ and persist them via TaskCreate.
 // ORCHESTRATOR
 // ============================================================================
 
+export interface OrchestratorContext {
+  /**
+   * Trailing commentary from the planner's last assistant message, if any.
+   * The Copilot and OpenCode workflows create a fresh session for each
+   * sub-agent, so the planner's in-session output is NOT automatically
+   * visible to the orchestrator — only what the planner persisted via
+   * `TaskCreate`. Forward the planner's final text here so the orchestrator
+   * sees any caveats, risks, or execution hints that didn't fit into task
+   * bodies.
+   */
+  plannerNotes?: string;
+}
+
 /**
  * Build the orchestrator prompt. The orchestrator retrieves the planner's
  * task list, validates the dependency graph, and spawns parallel workers.
+ *
+ * @param spec - The original user specification. Required because the
+ *   orchestrator runs in a fresh session on Copilot/OpenCode and needs the
+ *   end-user goal to resolve ambiguous tasks.
+ * @param context - Optional planner handoff context (trailing commentary).
  */
-export function buildOrchestratorPrompt(): string {
+export function buildOrchestratorPrompt(
+  spec: string,
+  context: OrchestratorContext = {},
+): string {
+  const plannerNotes = context.plannerNotes?.trim() ?? "";
+  const plannerSection =
+    plannerNotes.length > 0
+      ? `## Planner Notes (trailing commentary)
+
+The planner produced the notes below alongside the task list. They capture
+caveats, risks, or execution hints that did not fit into individual task
+bodies. Treat them as guidance, not as task definitions.
+
+<planner_notes>
+${plannerNotes}
+</planner_notes>
+
+`
+      : "";
+
   return `You are an orchestrator managing a set of implementation tasks.
 
-## Retrieve Task List
+## Original User Specification
+
+<specification>
+${spec}
+</specification>
+
+${plannerSection}## Retrieve Task List
 
 Start by retrieving the current task list using your TaskList tool. The
 planner has already created all tasks; you MUST retrieve them before any