@bastani/atomic 0.5.13 → 0.5.14

package/src/sdk/components/workflow-picker-panel.tsx

@@ -556,42 +556,56 @@ function EmptyPreview({
 
 const TEXT_FIELD_LINES = 3;
 
-
-const NOOP_CHANGE_REF: React.RefObject<((value: string) => void) | null> = { current: null };
-
 function TextAreaContent({
   value,
   placeholder,
   focused,
-  onChangeRef,
+  onInput,
 }: {
   value: string;
   placeholder: string;
   focused: boolean;
-  onChangeRef?: React.RefObject<((value: string) => void) | null>;
+  onInput: (value: string) => void;
 }) {
   const theme = usePickerTheme();
-  const ref = useRef<TextareaRenderable>(null);
-  const changeRef = onChangeRef ?? NOOP_CHANGE_REF;
+  const instanceRef = useRef<TextareaRenderable | null>(null);
+  const onInputRef = useLatest(onInput);
+  const lastTextRef = useRef(value);
 
-  // Sync external value → textarea when it diverges (e.g. initial value).
+  const refCallback = useCallback((instance: TextareaRenderable | null) => {
+    instanceRef.current = instance;
+  }, []);
+
+  // Sync external value → textarea when it diverges (e.g. initial value
+  // or reset after phase transition).
   useEffect(() => {
-    if (ref.current && ref.current.plainText !== value) {
-      ref.current.setText(value);
+    if (instanceRef.current && instanceRef.current.plainText !== value) {
+      instanceRef.current.setText(value);
+      lastTextRef.current = value;
     }
   }, [value]);
 
-  // Wire onContentChange as a prop so the reconciler sets it during the
-  // commit phase (via the constructor and setProperty's default branch),
-  // guaranteeing it is active before the textarea can receive key events.
-  // The previous useEffect approach deferred setup as a passive effect
-  // (ConcurrentRoot schedules these via setTimeout) — creating a window
-  // where keystrokes reached the focused textarea before the listener
-  // existed, silently dropping content-change notifications and leaving
-  // fieldValues stale.
+  // Detect text changes after each keypress. The native Zig edit buffer's
+  // "content-changed" event is unreliable for propagating to the JS
+  // _contentChangeListener in certain installed environments. Instead,
+  // we hook into useKeyboard (which fires before the textarea processes
+  // the key) and defer the read with queueMicrotask so the textarea has
+  // processed the keystroke by the time we read plainText.
+  useKeyboard(useCallback(() => {
+    queueMicrotask(() => {
+      const inst = instanceRef.current;
+      if (!inst) return;
+      const current = inst.plainText;
+      if (current !== lastTextRef.current) {
+        lastTextRef.current = current;
+        onInputRef.current(current);
+      }
+    });
+  }, []));
+
   return (
     <textarea
-      ref={ref}
+      ref={refCallback}
       initialValue={value}
       placeholder={placeholder}
       focused={focused}
@@ -602,9 +616,6 @@ function TextAreaContent({
       placeholderColor={theme.textDim}
       wrapMode="word"
       flexGrow={1}
-      onContentChange={() => {
-        changeRef.current?.(ref.current?.plainText ?? "");
-      }}
     />
   );
 }
@@ -685,14 +696,12 @@ const Field = memo(function Field({
   value,
   focused,
   onFieldInput,
-  onTextChangeRef,
 }: {
   id?: string;
   field: WorkflowInput;
   value: string;
   focused: boolean;
   onFieldInput: (fieldName: string, value: string) => void;
-  onTextChangeRef?: React.RefObject<((value: string) => void) | null>;
 }) {
   const theme = usePickerTheme();
   const borderCol = focused ? theme.primary : theme.border;
@@ -730,7 +739,7 @@ const Field = memo(function Field({
             value={value}
             placeholder={field.placeholder ?? ""}
             focused={focused}
-            onChangeRef={onTextChangeRef}
+            onInput={onInput}
           />
         ) : field.type === "string" ? (
           <StringContent
@@ -769,7 +778,6 @@ function InputPhase({
   values,
   focusedFieldIdx,
   onFieldInput,
-  onTextChangeRef,
 }: {
   workflow: WorkflowWithMetadata;
   agent: AgentType;
@@ -777,7 +785,6 @@ function InputPhase({
   values: Record<string, string>;
   focusedFieldIdx: number;
   onFieldInput: (fieldName: string, value: string) => void;
-  onTextChangeRef: React.RefObject<((value: string) => void) | null>;
 }) {
   const theme = usePickerTheme();
   const isStructured = workflow.inputs.length > 0;
@@ -924,11 +931,6 @@ function InputPhase({
               value={values[f.name] ?? ""}
               focused={active}
               onFieldInput={onFieldInput}
-              onTextChangeRef={
-                f.type === "text" && active
-                  ? onTextChangeRef
-                  : undefined
-              }
             />
           );
         })}
@@ -1371,16 +1373,6 @@ export function WorkflowPicker({
   }, [currentFields, fieldValues]);
   const isFormValid = invalidFieldIndices.length === 0;
 
-  // Textarea change callback ref — useLatest keeps .current in sync
-  // each render so the textarea effect doesn't need to re-attach.
-  const textChangeRef = useLatest(
-    currentField
-      ? (text: string) => {
-          setFieldValues((prev) => ({ ...prev, [currentField.name]: text }));
-        }
-      : null,
-  );
-
   // Stable callback for field input — the setter is referentially stable.
   const onFieldInput = useCallback(
     (name: string, v: string) => setFieldValues((prev) => ({ ...prev, [name]: v })),
@@ -1466,7 +1458,6 @@ export function WorkflowPicker({
             values={fieldValues}
             focusedFieldIdx={confirmOpen ? -1 : focusedFieldIdx}
             onFieldInput={onFieldInput}
-            onTextChangeRef={textChangeRef}
           />
         ) : null}
 

package/src/sdk/runtime/discovery.ts

@@ -2,10 +2,13 @@
  * Workflow discovery — finds workflow definitions from disk.
  *
  * Workflows are discovered from:
- *   1. .atomic/workflows/<name>/<agent>/index.ts (project-local)
- *   2. ~/.atomic/workflows/<name>/<agent>/index.ts (global)
+ *   1. src/sdk/workflows/builtin/<name>/<agent>/index.ts (SDK-shipped builtins)
+ *   2. .atomic/workflows/<name>/<agent>/index.ts (project-local)
+ *   3. ~/.atomic/workflows/<name>/<agent>/index.ts (global)
  *
- * Project-local workflows take precedence over global ones with the same name.
+ * All three sources use the same scanning function (`discoverFromBaseDir`)
+ * so registration is uniform. Builtin names are reserved — project-local
+ * and global workflows with the same name are dropped during merge.
  */
 
 import { join } from "node:path";
@@ -77,7 +80,7 @@ async function loadWorkflowsGitignore(workflowsDir: string): Promise<ignore.Igno
  */
 async function discoverFromBaseDir(
   baseDir: string,
-  source: "local" | "global",
+  source: "local" | "global" | "builtin",
   agentFilter?: AgentType,
 ): Promise<DiscoveredWorkflow[]> {
   const workflows: DiscoveredWorkflow[] = [];
@@ -91,7 +94,11 @@ async function discoverFromBaseDir(
     return workflows;
   }
 
-  const ig = await loadWorkflowsGitignore(baseDir);
+  // Builtin workflows live inside the SDK source tree — skip .gitignore
+  // handling to avoid writing files into node_modules or the SDK dir.
+  const ig = source === "builtin"
+    ? ignore()
+    : await loadWorkflowsGitignore(baseDir);
 
   for (const wfEntry of workflowEntries) {
     if (!wfEntry.isDirectory()) continue;
@@ -140,41 +147,6 @@ const BUILTIN_WORKFLOWS_DIR = join(
   Bun.fileURLToPath(new URL("../workflows/builtin", import.meta.url)),
 );
 
-/**
- * Discover built-in workflows shipped as SDK modules.
- *
- * Scans `src/sdk/workflows/builtin/<name>/<agent>/index.ts` for known
- * workflow directories. Returns entries with `source: "builtin"`.
- */
-async function discoverBuiltinWorkflows(
-  agentFilter?: AgentType,
-): Promise<DiscoveredWorkflow[]> {
-  const results: DiscoveredWorkflow[] = [];
-  const agents = agentFilter ? [agentFilter] : AGENTS;
-
-  let workflowEntries;
-  try {
-    workflowEntries = await readdir(BUILTIN_WORKFLOWS_DIR, { withFileTypes: true });
-  } catch {
-    return results;
-  }
-
-  const workflowNames = workflowEntries
-    .filter((d) => d.isDirectory())
-    .map((d) => d.name);
-
-  for (const name of workflowNames) {
-    for (const agent of agents) {
-      const indexPath = join(BUILTIN_WORKFLOWS_DIR, name, agent, "index.ts");
-      if (await Bun.file(indexPath).exists()) {
-        results.push({ name, agent, path: indexPath, source: "builtin" });
-      }
-    }
-  }
-
-  return results;
-}
-
 /**
  * Discover all available workflows from built-in, global, and local sources.
  * Optionally filter by agent.
@@ -221,7 +193,7 @@ export async function discoverWorkflows(
   // reserved by a builtin `ralph` for claude, even when the discovery
   // call was filtered to copilot.
   const [allBuiltins, globalResults, localResults] = await Promise.all([
-    discoverBuiltinWorkflows(),
+    discoverFromBaseDir(BUILTIN_WORKFLOWS_DIR, "builtin"),
     discoverFromBaseDir(globalDir, "global", agentFilter),
     discoverFromBaseDir(localDir, "local", agentFilter),
   ]);

package/src/sdk/runtime/executor.ts

@@ -85,6 +85,7 @@ const AGENT_CLI: Record<
       // which the idle detection in claude.ts watches for to know when the
       // agent has finished processing a prompt.
       CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS: "1",
+      CLAUDE_CODE_NO_FLICKER: "1",
     },
   },
 };

package/src/sdk/workflows/builtin/deep-research-codebase/claude/index.ts

@@ -85,13 +85,18 @@ import {
 // until Claude reports idle or a result (success, error_max_turns, etc.).
 
 export default defineWorkflow({
-    name: "deep-research-codebase",
-    description:
-      "Deterministic deep codebase research: scout → LOC-driven parallel explorers → aggregator",
-    inputs: [
-      { name: "prompt", type: "text", required: true, description: "research question" },
-    ],
-  })
+  name: "deep-research-codebase",
+  description:
+    "Deterministic deep codebase research: scout → LOC-driven parallel explorers → aggregator",
+  inputs: [
+    {
+      name: "prompt",
+      type: "text",
+      required: true,
+      description: "research question",
+    },
+  ],
+})
   .for<"claude">()
   .run(async (ctx) => {
     // Destructure once so every stage below can close over a bare
@@ -115,7 +120,8 @@ export default defineWorkflow({
       ctx.stage(
         {
           name: "codebase-scout",
-          description: "Map codebase, count LOC, partition for parallel explorers",
+          description:
+            "Map codebase, count LOC, partition for parallel explorers",
         },
         {},
         {},
@@ -175,29 +181,28 @@ export default defineWorkflow({
       ctx.stage(
         {
           name: "research-history",
-          description: "Surface prior research via research-locator + research-analyzer",
+          description:
+            "Surface prior research via research-locator + research-analyzer",
+        },
+        {
+          chatFlags: [
+            "--allow-dangerously-skip-permissions",
+            "--dangerously-skip-permissions",
+          ],
         },
-        {},
         {},
         async (s) => {
           // Dispatches codebase-research-locator → codebase-research-analyzer
           // over the project's research/ directory and outputs a ≤400-word
           // synthesis as prose (no file write — consumed via transcript).
-          await s.session.query(
-            buildHistoryPrompt({ question: prompt, root }),
-          );
+          await s.session.query(buildHistoryPrompt({ question: prompt, root }));
           s.save(s.sessionId);
         },
       ),
     ]);
 
-    const {
-      partitions,
-      explorerCount,
-      scratchDir,
-      totalLoc,
-      totalFiles,
-    } = scout.result;
+    const { partitions, explorerCount, scratchDir, totalLoc, totalFiles } =
+      scout.result;
 
     // Pull both scout transcripts ONCE at the workflow level so every
     // explorer + the aggregator can embed them in their prompts. Both
@@ -229,9 +234,16 @@ export default defineWorkflow({
             name: `explorer-${i}`,
             description: `Explore ${partition
               .map((u) => u.path)
-              .join(", ")} (${partition.reduce((s, u) => s + u.fileCount, 0)} files)`,
+              .join(
+                ", ",
+              )} (${partition.reduce((s, u) => s + u.fileCount, 0)} files)`,
+          },
+          {
+            chatFlags: [
+              "--allow-dangerously-skip-permissions",
+              "--dangerously-skip-permissions",
+            ],
           },
-          {},
           {},
           async (s) => {
             await s.session.query(
@@ -278,9 +290,15 @@ export default defineWorkflow({
     await ctx.stage(
       {
         name: "aggregator",
-        description: "Synthesize explorer findings + history into final research doc",
+        description:
+          "Synthesize explorer findings + history into final research doc",
+      },
+      {
+        chatFlags: [
+          "--allow-dangerously-skip-permissions",
+          "--dangerously-skip-permissions",
+        ],
       },
-      {},
       {},
       async (s) => {
         await s.session.query(

package/src/sdk/workflows/builtin/deep-research-codebase/helpers/heuristic.ts

@@ -1,33 +1,19 @@
+/** Target LOC per explorer sub-agent. */
+const LOC_PER_EXPLORER = 2_500;
+
 /**
  * Determine how many parallel explorer sub-agents to spawn for the
  * deep-research-codebase workflow, based on lines of code in the codebase.
  *
- * The heuristic balances coverage against coordination overhead:
- *   - Too few explorers leave parts of the codebase under-investigated.
- *   - Too many explorers flood the aggregator with redundant findings,
- *     burn tokens on coordination, and exhaust tmux/process budgets.
- *
- * Tier choices were anchored to the rough sizes of common project shapes:
- *
- *   <    5,000 LOC →  2 explorers   scripts, single-purpose tools
- *   <   25,000 LOC →  3 explorers   small libraries, CLI utilities
- *   <  100,000 LOC →  5 explorers   medium applications
- *   <  500,000 LOC →  7 explorers   large applications, small monorepos
- *   <2,000,000 LOC →  9 explorers   large monorepos
- *   ≥2,000,000 LOC → 12 explorers   massive monorepos (hard cap)
- *
- * The hard cap of 12 prevents runaway parallelism: each explorer is a
- * Claude tmux pane plus an LLM session, so the cost grows linearly in
- * tokens, processes, and walltime as well as in aggregator context.
+ * Scales linearly: one explorer per `LOC_PER_EXPLORER` (2.5K) lines of code,
+ * with a floor of 2 for tiny or empty codebases. The actual number of
+ * spawned explorers is still bounded by the number of partition units
+ * the scout finds (see `partitionUnits` in ./scout.ts), so we never get
+ * more explorers than the natural granularity of the codebase allows.
  */
 export function calculateExplorerCount(loc: number): number {
   if (!Number.isFinite(loc) || loc <= 0) return 2;
-  if (loc < 5_000) return 2;
-  if (loc < 25_000) return 3;
-  if (loc < 100_000) return 5;
-  if (loc < 500_000) return 7;
-  if (loc < 2_000_000) return 9;
-  return 12;
+  return Math.max(2, Math.ceil(loc / LOC_PER_EXPLORER));
 }
 
 /** Human-readable rationale for the heuristic decision — surfaced in logs/prompts. */

package/src/sdk/workflows/builtin/ralph/claude/index.ts

@@ -66,7 +66,8 @@ async function queryWithStructuredOutput(
         msg.subtype === "success" &&
         (msg as Record<string, unknown>).structured_output
       ) {
-        structured = (msg as Record<string, unknown>).structured_output as ReviewResult;
+        structured = (msg as Record<string, unknown>)
+          .structured_output as ReviewResult;
       }
     }
   }
@@ -82,7 +83,12 @@ export default defineWorkflow({
   description:
     "Plan → orchestrate → review → debug loop with bounded iteration",
   inputs: [
-    { name: "prompt", type: "text", required: true, description: "task prompt" },
+    {
+      name: "prompt",
+      type: "text",
+      required: true,
+      description: "task prompt",
+    },
   ],
 })
   .for<"claude">()
@@ -94,7 +100,14 @@ export default defineWorkflow({
       // ── Plan ────────────────────────────────────────────────────────────
       await ctx.stage(
         { name: `planner-${iteration}` },
-        { chatFlags: ["--agent", "planner", "--allow-dangerously-skip-permissions", "--dangerously-skip-permissions"] },
+        {
+          chatFlags: [
+            "--agent",
+            "planner",
+            "--allow-dangerously-skip-permissions",
+            "--dangerously-skip-permissions",
+          ],
+        },
         {},
         async (s) => {
           await s.session.query(
@@ -110,7 +123,14 @@ export default defineWorkflow({
       // ── Orchestrate ─────────────────────────────────────────────────────
       await ctx.stage(
         { name: `orchestrator-${iteration}` },
-        { chatFlags: ["--agent", "orchestrator", "--allow-dangerously-skip-permissions", "--dangerously-skip-permissions"] },
+        {
+          chatFlags: [
+            "--agent",
+            "orchestrator",
+            "--allow-dangerously-skip-permissions",
+            "--dangerously-skip-permissions",
+          ],
+        },
         {},
         async (s) => {
           await s.session.query(buildOrchestratorPrompt(prompt));
@@ -128,10 +148,11 @@ export default defineWorkflow({
           {},
           {},
           async (s) => {
-            const result = await s.session.query(
-              discoveryPrompts.locator,
-              { agent: "codebase-locator", permissionMode: "bypassPermissions", allowDangerouslySkipPermissions: true },
-            );
+            const result = await s.session.query(discoveryPrompts.locator, {
+              agent: "codebase-locator",
+              permissionMode: "bypassPermissions",
+              allowDangerouslySkipPermissions: true,
+            });
             s.save(s.sessionId);
             return extractAssistantText(result, 0);
           },
@@ -141,10 +162,11 @@ export default defineWorkflow({
           {},
           {},
           async (s) => {
-            const result = await s.session.query(
-              discoveryPrompts.analyzer,
-              { agent: "codebase-analyzer", permissionMode: "bypassPermissions", allowDangerouslySkipPermissions: true },
-            );
+            const result = await s.session.query(discoveryPrompts.analyzer, {
+              agent: "codebase-analyzer",
+              permissionMode: "bypassPermissions",
+              allowDangerouslySkipPermissions: true,
+            });
             s.save(s.sessionId);
             return extractAssistantText(result, 0);
           },
@@ -156,7 +178,11 @@ export default defineWorkflow({
           async (s) => {
             const result = await s.session.query(
               discoveryPrompts.patternFinder,
-              { agent: "codebase-pattern-finder", permissionMode: "bypassPermissions", allowDangerouslySkipPermissions: true },
+              {
+                agent: "codebase-pattern-finder",
+                permissionMode: "bypassPermissions",
+                allowDangerouslySkipPermissions: true,
+              },
             );
             s.save(s.sessionId);
             return extractAssistantText(result, 0);
@@ -165,9 +191,12 @@ export default defineWorkflow({
       ]);
 
       const discoveryContext = [
-        "### Infrastructure Files (codebase-locator)\n\n" + locatorResult.result,
-        "### Infrastructure Analysis (codebase-analyzer)\n\n" + analyzerResult.result,
-        "### Build & Test Patterns (codebase-pattern-finder)\n\n" + patternResult.result,
+        "### Infrastructure Files (codebase-locator)\n\n" +
+          locatorResult.result,
+        "### Infrastructure Analysis (codebase-analyzer)\n\n" +
+          analyzerResult.result,
+        "### Build & Test Patterns (codebase-pattern-finder)\n\n" +
+          patternResult.result,
       ].join("\n\n---\n\n");
 
       // ── Review (two parallel passes) ────────────────────────────────────
@@ -178,26 +207,16 @@ export default defineWorkflow({
       });
 
       const [reviewA, reviewB] = await Promise.all([
-        ctx.stage(
-          { name: `reviewer-${iteration}-a` },
-          {},
-          {},
-          async (s) => {
-            const result = await queryWithStructuredOutput(reviewPrompt);
-            s.save(s.sessionId);
-            return result;
-          },
-        ),
-        ctx.stage(
-          { name: `reviewer-${iteration}-b` },
-          {},
-          {},
-          async (s) => {
-            const result = await queryWithStructuredOutput(reviewPrompt);
-            s.save(s.sessionId);
-            return result;
-          },
-        ),
+        ctx.stage({ name: `reviewer-${iteration}-a` }, {}, {}, async (s) => {
+          const result = await queryWithStructuredOutput(reviewPrompt);
+          s.save(s.sessionId);
+          return result;
+        }),
+        ctx.stage({ name: `reviewer-${iteration}-b` }, {}, {}, async (s) => {
+          const result = await queryWithStructuredOutput(reviewPrompt);
+          s.save(s.sessionId);
+          return result;
+        }),
       ]);
 
       const merged = mergeReviewResults(reviewA.result, reviewB.result);
@@ -211,7 +230,14 @@ export default defineWorkflow({
       if (iteration < MAX_LOOPS) {
         const debugger_ = await ctx.stage(
           { name: `debugger-${iteration}` },
-          { chatFlags: ["--agent", "debugger", "--allow-dangerously-skip-permissions", "--dangerously-skip-permissions"] },
+          {
+            chatFlags: [
+              "--agent",
+              "debugger",
+              "--allow-dangerously-skip-permissions",
+              "--dangerously-skip-permissions",
+            ],
+          },
           {},
           async (s) => {
             const result = await s.session.query(

package/src/sdk/workflows/builtin/ralph/copilot/index.ts

@@ -79,7 +79,12 @@ export default defineWorkflow({
   description:
     "Plan → orchestrate → review → debug loop with bounded iteration",
   inputs: [
-    { name: "prompt", type: "text", required: true, description: "task prompt" },
+    {
+      name: "prompt",
+      type: "text",
+      required: true,
+      description: "task prompt",
+    },
   ],
 })
   .for<"copilot">()
@@ -162,9 +167,12 @@ export default defineWorkflow({
       ]);
 
       const discoveryContext = [
-        "### Infrastructure Files (codebase-locator)\n\n" + locatorResult.result,
-        "### Infrastructure Analysis (codebase-analyzer)\n\n" + analyzerResult.result,
-        "### Build & Test Patterns (codebase-pattern-finder)\n\n" + patternResult.result,
+        "### Infrastructure Files (codebase-locator)\n\n" +
+          locatorResult.result,
+        "### Infrastructure Analysis (codebase-analyzer)\n\n" +
+          analyzerResult.result,
+        "### Build & Test Patterns (codebase-pattern-finder)\n\n" +
+          patternResult.result,
       ].join("\n\n---\n\n");
 
       // ── Review (two parallel passes) ──────────────────────────────────