@bastani/atomic 0.5.12-3 → 0.5.12-5

package/src/sdk/types.ts

@@ -175,7 +175,7 @@ export interface WorkflowInput {
   /** Default value pre-filled into the field. Enums use this to pick their initial value. */
   default?: string;
   /** Allowed values — required when `type` is `"enum"`. */
-  values?: string[];
+  values?: readonly string[];
 }
 
 // ─── Core types ─────────────────────────────────────────────────────────────
@@ -254,7 +254,7 @@ export interface SessionRunOptions {
  * Created by `ctx.stage(opts, clientOpts, sessionOpts, fn)` — the callback
  * receives this as its argument with pre-initialized `client` and `session`.
  */
-export interface SessionContext<A extends AgentType = AgentType> {
+export interface SessionContext<A extends AgentType = AgentType, N extends string = string> {
   /** Provider-specific SDK client (auto-created by runtime) */
   client: ProviderClient<A>;
   /** Provider-specific session (auto-created by runtime) */
@@ -263,12 +263,12 @@ export interface SessionContext<A extends AgentType = AgentType> {
    * Structured inputs for this workflow run. Populated from CLI flags
    * (`--<name>=<value>`) or the interactive picker.
    *
-   * Free-form workflows (no declared `inputs` schema) receive their
-   * single positional prompt under the `prompt` key — so
-   * `s.inputs.prompt` is the canonical way to read the user's prompt
-   * regardless of whether the workflow is structured or free-form.
+   * When the workflow declares an `inputs` schema, only the declared
+   * field names are valid keys — accessing undeclared fields is a
+   * compile-time error. Free-form workflows (no declared schema)
+   * allow any key, including the conventional `prompt` key.
    */
-  inputs: Record<string, string>;
+  inputs: { [K in N]?: string };
   /** Which agent is running */
   agent: A;
   /**
@@ -301,7 +301,7 @@ export interface SessionContext<A extends AgentType = AgentType> {
     options: SessionRunOptions,
     clientOpts: StageClientOptions<A>,
     sessionOpts: StageSessionOptions<A>,
-    run: (ctx: SessionContext<A>) => Promise<T>,
+    run: (ctx: SessionContext<A, N>) => Promise<T>,
   ): Promise<SessionHandle<T>>;
 }
 
@@ -309,17 +309,17 @@ export interface SessionContext<A extends AgentType = AgentType> {
  * Top-level context provided to the workflow's `.run()` callback.
  * Does not have session-specific fields (paneId, save, etc.).
  */
-export interface WorkflowContext<A extends AgentType = AgentType> {
+export interface WorkflowContext<A extends AgentType = AgentType, N extends string = string> {
   /**
    * Structured inputs for this workflow run. Populated from CLI flags
    * (`--<name>=<value>`) or the interactive picker.
    *
-   * Free-form workflows (no declared `inputs` schema) receive their
-   * single positional prompt under the `prompt` key — so
-   * `ctx.inputs.prompt` is the canonical way to read the user's prompt
-   * regardless of whether the workflow is structured or free-form.
+   * When the workflow declares an `inputs` schema, only the declared
+   * field names are valid keys — accessing undeclared fields is a
+   * compile-time error. Free-form workflows (no declared schema)
+   * allow any key, including the conventional `prompt` key.
    */
-  inputs: Record<string, string>;
+  inputs: { [K in N]?: string };
   /** Which agent is running */
   agent: A;
   /**
@@ -332,7 +332,7 @@ export interface WorkflowContext<A extends AgentType = AgentType> {
     options: SessionRunOptions,
     clientOpts: StageClientOptions<A>,
     sessionOpts: StageSessionOptions<A>,
-    run: (ctx: SessionContext<A>) => Promise<T>,
+    run: (ctx: SessionContext<A, N>) => Promise<T>,
   ): Promise<SessionHandle<T>>;
   /**
    * Get a completed session's transcript as rendered text.
@@ -349,7 +349,9 @@ export interface WorkflowContext<A extends AgentType = AgentType> {
 /**
  * Options for defining a workflow.
  */
-export interface WorkflowOptions {
+export interface WorkflowOptions<
+  I extends readonly WorkflowInput[] = readonly WorkflowInput[],
+> {
   /** Unique workflow name */
   name: string;
   /** Human-readable description */
@@ -359,19 +361,22 @@ export interface WorkflowOptions {
    * `--<name>` flag per entry and the interactive picker renders one form
    * field per entry. Leave unset to keep the workflow free-form (a single
    * positional prompt argument).
+   *
+   * Write the array inline so TypeScript can infer literal input names
+   * and enforce them on `ctx.inputs`.
    */
-  inputs?: WorkflowInput[];
+  inputs?: I;
 }
 
 /**
  * A compiled workflow definition — the sealed output of defineWorkflow().compile().
  */
-export interface WorkflowDefinition<A extends AgentType = AgentType> {
+export interface WorkflowDefinition<A extends AgentType = AgentType, N extends string = string> {
   readonly __brand: "WorkflowDefinition";
   readonly name: string;
   readonly description: string;
   /** Declared input schema — empty array for free-form workflows. */
   readonly inputs: readonly WorkflowInput[];
   /** The workflow's entry point. Called by the executor with a WorkflowContext. */
-  readonly run: (ctx: WorkflowContext<A>) => Promise<void>;
+  readonly run: (ctx: WorkflowContext<A, N>) => Promise<void>;
 }

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

@@ -79,32 +79,23 @@ import {
   slugifyPrompt,
 } from "../helpers/prompts.ts";
 
-// ── Timeouts ────────────────────────────────────────────────────────────────
-// Every s.session.query() call passes one of these explicitly — never relying
-// on the 300-second default. Explorer and aggregator stages dispatch sub-agents
-// and can easily run 30+ minutes; a premature timeout causes the stage to
-// complete early, which makes Promise.all resolve and the next stage to launch
-// before parallel stages finish.
-const SCOUT_TIMEOUT_MS = 15 * 60 * 1000; // 15 min — short orientation call
-const HISTORY_TIMEOUT_MS = 20 * 60 * 1000; // 20 min — reads research/ docs
-const EXPLORER_TIMEOUT_MS = 45 * 60 * 1000; // 45 min — multi-step sub-agent dispatch
-const AGGREGATOR_TIMEOUT_MS = 45 * 60 * 1000; // 45 min — reads N explorer reports
+// ── Idle detection ─────────────────────────────────────────────────────────
+// Completion is detected by watching the session JSONL file for idle and result
+// events from Claude's own SDK — no manual timeout is needed. The loop runs
+// until Claude reports idle or a result (success, error_max_turns, etc.).
 
-// Between sub-agent dispatches Claude's TUI briefly shows the prompt indicator
-// without an active-task spinner. Requiring 3 consecutive idle detections
-// prevents the query from returning during these transient gaps.
-const EXPLORER_IDLE_CONFIRM = 3;
-const AGGREGATOR_IDLE_CONFIRM = 3;
-
-export default defineWorkflow<"claude">({
+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" },
+    ],
   })
+  .for<"claude">()
   .run(async (ctx) => {
-    // Free-form workflows receive their positional prompt under
-    // `inputs.prompt`; destructure once so every stage below can close
-    // over a bare `prompt` string without re-reaching into ctx.inputs.
+    // Destructure once so every stage below can close over a bare
+    // `prompt` string without re-reaching into ctx.inputs.
     const prompt = ctx.inputs.prompt ?? "";
     const root = getCodebaseRoot();
     const startedAt = new Date();
@@ -166,7 +157,6 @@ export default defineWorkflow<"claude">({
               explorerCount: actualCount,
               partitionPreview: partitions,
             }),
-            { timeoutMs: SCOUT_TIMEOUT_MS },
           );
           s.save(s.sessionId);
 
@@ -195,7 +185,6 @@ export default defineWorkflow<"claude">({
           // synthesis as prose (no file write — consumed via transcript).
           await s.session.query(
             buildHistoryPrompt({ question: prompt, root }),
-            { timeoutMs: HISTORY_TIMEOUT_MS },
           );
           s.save(s.sessionId);
         },
@@ -255,10 +244,6 @@ export default defineWorkflow<"claude">({
                 scratchPath,
                 root,
               }),
-              {
-                timeoutMs: EXPLORER_TIMEOUT_MS,
-                idleConfirmCount: EXPLORER_IDLE_CONFIRM,
-              },
             );
             s.save(s.sessionId);
 
@@ -309,10 +294,6 @@ export default defineWorkflow<"claude">({
             scoutOverview,
             historyOverview,
           }),
-          {
-            timeoutMs: AGGREGATOR_TIMEOUT_MS,
-            idleConfirmCount: AGGREGATOR_IDLE_CONFIRM,
-          },
         );
         s.save(s.sessionId);
       },

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

@@ -63,15 +63,18 @@ import {
   slugifyPrompt,
 } from "../helpers/prompts.ts";
 
-export default defineWorkflow<"copilot">({
+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" },
+    ],
   })
+  .for<"copilot">()
   .run(async (ctx) => {
-    // Free-form workflows receive their positional prompt under
-    // `inputs.prompt`; destructure once so every stage below can close
-    // over a bare `prompt` string without re-reaching into ctx.inputs.
+    // Destructure once so every stage below can close over a bare
+    // `prompt` string without re-reaching into ctx.inputs.
     const prompt = ctx.inputs.prompt ?? "";
     const root = getCodebaseRoot();
     const startedAt = new Date();

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

@@ -66,13 +66,17 @@ import {
   slugifyPrompt,
 } from "../helpers/prompts.ts";
 
-export default defineWorkflow<"opencode">({
+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" },
+    ],
   })
+  .for<"opencode">()
   .run(async (ctx) => {
-    // Free-form workflows receive their positional prompt under
+    // Destructure once so every stage below can close over a bare
     // `inputs.prompt`; destructure once so every stage below can close
     // over a bare `prompt` string without re-reaching into ctx.inputs.
     const prompt = ctx.inputs.prompt ?? "";

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

@@ -14,7 +14,7 @@
  * Run: atomic workflow -n ralph -a claude "<your spec>"
  */
 
-import { defineWorkflow } from "../../../index.ts";
+import { defineWorkflow, extractAssistantText } from "../../../index.ts";
 import { query as claudeSdkQuery } from "@anthropic-ai/claude-agent-sdk";
 
 import {
@@ -36,13 +36,9 @@ import { captureBranchChangeset } from "../helpers/git.ts";
 const MAX_LOOPS = 10;
 
 // The orchestrator stage implements the actual code changes and can run for
-// a very long time on large tasks. 24 hours prevents premature timeout.
-const ORCHESTRATOR_TIMEOUT_MS = 24 * 60 * 60 * 1000; // 24 hours
-
-/** Wrap a prompt with a Claude Code @-mention so the named sub-agent runs it. */
-function asAgentCall(agentName: string, prompt: string): string {
-  return `@"${agentName} (agent)" ${prompt}`;
-}
+// a very long time on large tasks. Completion is detected via session file
+// watching for idle and result events from Claude's own SDK — no manual
+// timeout is needed.
 
 /**
  * Run the Claude Agent SDK's `query()` with structured output and collect
@@ -65,7 +61,7 @@ async function queryWithStructuredOutput(
     },
   })) {
     if (msg.type === "result") {
-      raw = String((msg as Record<string, unknown>).output ?? "");
+      raw = String((msg as Record<string, unknown>).result ?? "");
       if (
         msg.subtype === "success" &&
         (msg as Record<string, unknown>).structured_output
@@ -81,11 +77,15 @@ async function queryWithStructuredOutput(
   };
 }
 
-export default defineWorkflow<"claude">({
+export default defineWorkflow({
   name: "ralph",
   description:
     "Plan → orchestrate → review → debug loop with bounded iteration",
+  inputs: [
+    { name: "prompt", type: "text", required: true, description: "task prompt" },
+  ],
 })
+  .for<"claude">()
   .run(async (ctx) => {
     const prompt = ctx.inputs.prompt ?? "";
     let debuggerReport = "";
@@ -94,17 +94,14 @@ export default defineWorkflow<"claude">({
       // ── Plan ────────────────────────────────────────────────────────────
       await ctx.stage(
         { name: `planner-${iteration}` },
-        {},
+        { chatFlags: ["--agent", "planner", "--allow-dangerously-skip-permissions", "--dangerously-skip-permissions"] },
         {},
         async (s) => {
           await s.session.query(
-            asAgentCall(
-              "planner",
-              buildPlannerPrompt(prompt, {
-                iteration,
-                debuggerReport: debuggerReport || undefined,
-              }),
-            ),
+            buildPlannerPrompt(prompt, {
+              iteration,
+              debuggerReport: debuggerReport || undefined,
+            }),
           );
           s.save(s.sessionId);
         },
@@ -113,13 +110,10 @@ export default defineWorkflow<"claude">({
       // ── Orchestrate ─────────────────────────────────────────────────────
       await ctx.stage(
         { name: `orchestrator-${iteration}` },
-        {},
+        { chatFlags: ["--agent", "orchestrator", "--allow-dangerously-skip-permissions", "--dangerously-skip-permissions"] },
         {},
         async (s) => {
-          await s.session.query(
-            asAgentCall("orchestrator", buildOrchestratorPrompt(prompt)),
-            { timeoutMs: ORCHESTRATOR_TIMEOUT_MS },
-          );
+          await s.session.query(buildOrchestratorPrompt(prompt));
           s.save(s.sessionId);
         },
       );
@@ -135,10 +129,11 @@ export default defineWorkflow<"claude">({
           {},
           async (s) => {
             const result = await s.session.query(
-              asAgentCall("codebase-locator", discoveryPrompts.locator),
+              discoveryPrompts.locator,
+              { agent: "codebase-locator", permissionMode: "bypassPermissions", allowDangerouslySkipPermissions: true },
             );
             s.save(s.sessionId);
-            return String(result.output ?? "");
+            return extractAssistantText(result, 0);
           },
         ),
         ctx.stage(
@@ -147,10 +142,11 @@ export default defineWorkflow<"claude">({
           {},
           async (s) => {
             const result = await s.session.query(
-              asAgentCall("codebase-analyzer", discoveryPrompts.analyzer),
+              discoveryPrompts.analyzer,
+              { agent: "codebase-analyzer", permissionMode: "bypassPermissions", allowDangerouslySkipPermissions: true },
             );
             s.save(s.sessionId);
-            return String(result.output ?? "");
+            return extractAssistantText(result, 0);
           },
         ),
         ctx.stage(
@@ -159,10 +155,11 @@ export default defineWorkflow<"claude">({
           {},
           async (s) => {
             const result = await s.session.query(
-              asAgentCall("codebase-pattern-finder", discoveryPrompts.patternFinder),
+              discoveryPrompts.patternFinder,
+              { agent: "codebase-pattern-finder", permissionMode: "bypassPermissions", allowDangerouslySkipPermissions: true },
             );
             s.save(s.sessionId);
-            return String(result.output ?? "");
+            return extractAssistantText(result, 0);
           },
         ),
       ]);
@@ -214,20 +211,17 @@ export default defineWorkflow<"claude">({
       if (iteration < MAX_LOOPS) {
         const debugger_ = await ctx.stage(
           { name: `debugger-${iteration}` },
-          {},
+          { chatFlags: ["--agent", "debugger", "--allow-dangerously-skip-permissions", "--dangerously-skip-permissions"] },
           {},
           async (s) => {
             const result = await s.session.query(
-              asAgentCall(
-                "debugger",
-                buildDebuggerReportPrompt(parsed, reviewRaw, {
-                  iteration,
-                  changeset,
-                }),
-              ),
+              buildDebuggerReportPrompt(parsed, reviewRaw, {
+                iteration,
+                changeset,
+              }),
             );
             s.save(s.sessionId);
-            return result.output;
+            return extractAssistantText(result, 0);
           },
         );
 

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

@@ -74,11 +74,15 @@ function getAssistantText(messages: SessionEvent[]): string {
     .join("\n\n");
 }
 
-export default defineWorkflow<"copilot">({
+export default defineWorkflow({
   name: "ralph",
   description:
     "Plan → orchestrate → review → debug loop with bounded iteration",
+  inputs: [
+    { name: "prompt", type: "text", required: true, description: "task prompt" },
+  ],
 })
+  .for<"copilot">()
   .run(async (ctx) => {
     const userPromptText = ctx.inputs.prompt ?? "";
     let debuggerReport = "";

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

@@ -65,11 +65,15 @@ function extractReview(
   return { structured: null, raw };
 }
 
-export default defineWorkflow<"opencode">({
+export default defineWorkflow({
   name: "ralph",
   description:
     "Plan → orchestrate → review → debug loop with bounded iteration",
+  inputs: [
+    { name: "prompt", type: "text", required: true, description: "task prompt" },
+  ],
 })
+  .for<"opencode">()
   .run(async (ctx) => {
     const prompt = ctx.inputs.prompt ?? "";
     let debuggerReport = "";

package/src/sdk/workflows/index.ts

@@ -44,8 +44,8 @@ export type { SessionPromptResponse as OpenCodePromptResponse } from "@opencode-
 export type { SessionMessage as ClaudeSessionMessage } from "@anthropic-ai/claude-agent-sdk";
 
 // Providers
-export { createClaudeSession, claudeQuery, clearClaudeSession, validateClaudeWorkflow } from "../providers/claude.ts";
-export type { ClaudeSessionOptions, ClaudeQueryOptions, ClaudeQueryResult } from "../providers/claude.ts";
+export { createClaudeSession, claudeQuery, clearClaudeSession, extractAssistantText, validateClaudeWorkflow } from "../providers/claude.ts";
+export type { ClaudeSessionOptions, ClaudeQueryOptions } from "../providers/claude.ts";
 
 export { validateCopilotWorkflow } from "../providers/copilot.ts";