@bastani/atomic 0.5.0 → 0.5.1-0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.5.0",
+  "version": "0.5.1-0",
   "description": "Configuration management CLI and SDK for coding agents",
   "type": "module",
   "license": "MIT",

package/src/sdk/define-workflow.ts

@@ -2,25 +2,25 @@
  * Workflow Builder — defines a workflow with a single `.run()` entry point.
  *
  * Usage:
- *   defineWorkflow({ name: "my-workflow", description: "..." })
+ *   defineWorkflow<"copilot">({ name: "my-workflow", description: "..." })
  *     .run(async (ctx) => {
- *       await ctx.session({ name: "research" }, async (s) => { ... });
- *       await ctx.session({ name: "plan" }, async (s) => { ... });
+ *       await ctx.stage({ name: "research" }, {}, {}, async (s) => { ... });
+ *       await ctx.stage({ name: "plan" }, {}, {}, async (s) => { ... });
  *     })
  *     .compile()
  */
 
-import type { WorkflowOptions, WorkflowContext, WorkflowDefinition } from "./types.ts";
+import type { AgentType, WorkflowOptions, WorkflowContext, WorkflowDefinition } from "./types.ts";
 
 /**
  * Chainable workflow builder. Records the run callback,
  * then .compile() seals it into a WorkflowDefinition.
  */
-export class WorkflowBuilder {
+export class WorkflowBuilder<A extends AgentType = AgentType> {
   /** @internal Brand for detection across package boundaries */
   readonly __brand = "WorkflowBuilder" as const;
   private readonly options: WorkflowOptions;
-  private runFn: ((ctx: WorkflowContext) => Promise<void>) | null = null;
+  private runFn: ((ctx: WorkflowContext<A>) => Promise<void>) | null = null;
 
   constructor(options: WorkflowOptions) {
     this.options = options;
@@ -29,12 +29,12 @@ export class WorkflowBuilder {
   /**
    * Set the workflow's entry point.
    *
-   * The callback receives a {@link WorkflowContext} with `session()` for
+   * The callback receives a {@link WorkflowContext} with `stage()` for
    * spawning agent sessions, and `transcript()` / `getMessages()` for
    * reading completed session outputs. Use native TypeScript control flow
    * (loops, conditionals, `Promise.all()`) for orchestration.
    */
-  run(fn: (ctx: WorkflowContext) => Promise<void>): this {
+  run(fn: (ctx: WorkflowContext<A>) => Promise<void>): this {
     if (this.runFn) {
       throw new Error("run() can only be called once per workflow.");
     }
@@ -51,7 +51,7 @@ export class WorkflowBuilder {
    * After calling compile(), the returned object is consumed by the
    * Atomic CLI runtime.
    */
-  compile(): WorkflowDefinition {
+  compile(): WorkflowDefinition<A> {
     if (!this.runFn) {
       throw new Error(
         `Workflow "${this.options.name}" has no run callback. ` +
@@ -73,29 +73,45 @@ export class WorkflowBuilder {
 /**
  * Entry point for defining a workflow.
  *
+ * Pass a type parameter to narrow all context types to a specific agent:
+ *
  * @example
  * ```typescript
  * import { defineWorkflow } from "@bastani/atomic/workflows";
  *
- * export default defineWorkflow({
+ * export default defineWorkflow<"copilot">({
  *   name: "hello",
  *   description: "Two-session demo",
  * })
  *   .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);
- *       // ...
- *     });
+ *     const describe = await ctx.stage(
+ *       { name: "describe" },
+ *       {},
+ *       {},
+ *       async (s) => {
+ *         // s.client: CopilotClient, s.session: CopilotSession
+ *         await s.session.sendAndWait({ prompt: s.userPrompt });
+ *         s.save(await s.session.getMessages());
+ *       },
+ *     );
+ *     await ctx.stage(
+ *       { name: "summarize" },
+ *       {},
+ *       {},
+ *       async (s) => {
+ *         const research = await s.transcript(describe);
+ *         // ...
+ *       },
+ *     );
  *   })
  *   .compile();
  * ```
  */
-export function defineWorkflow(options: WorkflowOptions): WorkflowBuilder {
+export function defineWorkflow<A extends AgentType = AgentType>(
+  options: WorkflowOptions,
+): WorkflowBuilder<A> {
   if (!options.name || options.name.trim() === "") {
     throw new Error("Workflow name is required.");
   }
-  return new WorkflowBuilder(options);
+  return new WorkflowBuilder<A>(options);
 }

package/src/sdk/index.ts

@@ -25,6 +25,10 @@ export type {
   WorkflowContext,
   WorkflowOptions,
   WorkflowDefinition,
+  StageClientOptions,
+  StageSessionOptions,
+  ProviderClient,
+  ProviderSession,
 } from "./types.ts";
 
 // Workflow SDK (also available as atomic/workflows subpath)

package/src/sdk/providers/claude.ts

@@ -283,6 +283,92 @@ export async function claudeQuery(options: ClaudeQueryOptions): Promise<ClaudeQu
   return { output: lastContent || capturePaneScrollback(paneId), delivered };
 }
 
+// ---------------------------------------------------------------------------
+// Synthetic wrappers — uniform s.client / s.session API for Claude stages
+// ---------------------------------------------------------------------------
+
+/**
+ * Default query options the user can set per-stage via the `sessionOpts` arg.
+ * These become defaults for every `s.session.query()` call within that stage.
+ */
+export interface ClaudeQueryDefaults {
+  /** Timeout in ms waiting for Claude to finish responding (default: 300s) */
+  timeoutMs?: number;
+  /** Polling interval in ms (default: 2000) */
+  pollIntervalMs?: number;
+  /** Number of C-m presses per submit round (default: 1) */
+  submitPresses?: number;
+  /** Max submit rounds if text isn't consumed (default: 6) */
+  maxSubmitRounds?: number;
+  /** Timeout in ms waiting for pane to be ready before sending (default: 30s) */
+  readyTimeoutMs?: number;
+}
+
+/**
+ * Synthetic client wrapper for Claude stages.
+ * Auto-starts the Claude CLI in the tmux pane during `start()`.
+ */
+export class ClaudeClientWrapper {
+  readonly paneId: string;
+  private readonly opts: { chatFlags?: string[]; readyTimeoutMs?: number };
+
+  constructor(
+    paneId: string,
+    opts: { chatFlags?: string[]; readyTimeoutMs?: number } = {},
+  ) {
+    this.paneId = paneId;
+    this.opts = opts;
+  }
+
+  /** Start the Claude CLI in the tmux pane. Called by the runtime during init. */
+  async start(): Promise<void> {
+    await createClaudeSession({
+      paneId: this.paneId,
+      chatFlags: this.opts.chatFlags,
+      readyTimeoutMs: this.opts.readyTimeoutMs,
+    });
+  }
+
+  /** Noop — cleanup is handled by the runtime via `clearClaudeSession`. */
+  async stop(): Promise<void> {}
+}
+
+/**
+ * Synthetic session wrapper for Claude stages.
+ * Wraps `claudeQuery()` so users call `s.session.query(prompt)`.
+ */
+export class ClaudeSessionWrapper {
+  readonly paneId: string;
+  readonly sessionId: string;
+  private readonly defaults: ClaudeQueryDefaults;
+
+  constructor(
+    paneId: string,
+    sessionId: string,
+    defaults: ClaudeQueryDefaults = {},
+  ) {
+    this.paneId = paneId;
+    this.sessionId = sessionId;
+    this.defaults = defaults;
+  }
+
+  /** Send a prompt to Claude and wait for the response. */
+  async query(
+    prompt: string,
+    opts?: Partial<ClaudeQueryDefaults>,
+  ): Promise<ClaudeQueryResult> {
+    return claudeQuery({
+      paneId: this.paneId,
+      prompt,
+      ...this.defaults,
+      ...opts,
+    });
+  }
+
+  /** Noop — for API symmetry with CopilotSession.disconnect(). */
+  async disconnect(): Promise<void> {}
+}
+
 // ---------------------------------------------------------------------------
 // Static source validation
 // ---------------------------------------------------------------------------
@@ -295,21 +381,28 @@ export interface ClaudeValidationWarning {
 /**
  * Validate a Claude workflow source file for common mistakes.
  *
- * Checks that `createClaudeSession` is called when `claudeQuery` is used,
- * paralleling the validation patterns for Copilot and OpenCode workflows.
+ * Warns on direct usage of createClaudeSession/claudeQuery — the runtime
+ * now handles init/cleanup automatically via s.client and s.session.
  */
 export function validateClaudeWorkflow(source: string): ClaudeValidationWarning[] {
   const warnings: ClaudeValidationWarning[] = [];
 
+  if (/\bcreateClaudeSession\b/.test(source)) {
+    warnings.push({
+      rule: "claude/manual-session",
+      message:
+        "Manual createClaudeSession() call detected. The runtime auto-starts the Claude CLI — " +
+        "use s.session.query() instead of claudeQuery(). Pass chatFlags via the second arg to ctx.stage().",
+    });
+  }
+
   if (/\bclaudeQuery\b/.test(source)) {
-    if (!/\bcreateClaudeSession\b/.test(source)) {
-      warnings.push({
-        rule: "claude/create-session",
-        message:
-          "Could not verify that createClaudeSession is called before claudeQuery(). " +
-          "Call createClaudeSession({ paneId: s.paneId }) to start the Claude CLI before sending queries.",
-      });
-    }
+    warnings.push({
+      rule: "claude/manual-query",
+      message:
+        "Direct claudeQuery() call detected. Use s.session.query(prompt) instead — " +
+        "it wraps claudeQuery with the correct paneId.",
+    });
   }
 
   return warnings;

package/src/sdk/providers/copilot.ts

@@ -1,9 +1,8 @@
 /**
  * Copilot workflow source validation.
  *
- * Checks that Copilot workflow source files follow required patterns:
- * - `cliUrl` is wired to the session context's `serverUrl`
- * - `setForegroundSessionId` is called after creating a session
+ * Checks that Copilot workflow source files use the runtime-managed
+ * `s.client` and `s.session` instead of manual SDK client creation.
  */
 
 export interface CopilotValidationWarning {
@@ -17,28 +16,22 @@ export interface CopilotValidationWarning {
 export function validateCopilotWorkflow(source: string): CopilotValidationWarning[] {
   const warnings: CopilotValidationWarning[] = [];
 
-  if (/\bCopilotClient\b/.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: s.serverUrl }. " +
-          "This is required to connect to the workflow's agent pane.",
-      });
-    }
+  if (/\bnew\s+CopilotClient\b/.test(source)) {
+    warnings.push({
+      rule: "copilot/manual-client",
+      message:
+        "Manual CopilotClient creation detected. Use s.client instead — " +
+        "the runtime auto-creates and cleans up the client.",
+    });
   }
 
-  if (/\bcreateSession\b/.test(source)) {
-    if (!/\bsetForegroundSessionId\b/.test(source)) {
-      warnings.push({
-        rule: "copilot/foreground-session",
-        message:
-          "Could not verify that setForegroundSessionId is called after createSession(). " +
-          "Call client.setForegroundSessionId(session.sessionId) so the TUI displays the workflow session.",
-      });
-    }
+  if (/\bclient\.createSession\b/.test(source)) {
+    warnings.push({
+      rule: "copilot/manual-session",
+      message:
+        "Manual createSession() call detected. Use s.session instead — " +
+        "the runtime auto-creates the session. Pass session config as the third arg to ctx.stage().",
+    });
   }
 
   return warnings;

package/src/sdk/providers/opencode.ts

@@ -1,9 +1,8 @@
 /**
  * OpenCode workflow source validation.
  *
- * Checks that OpenCode workflow source files follow required patterns:
- * - `baseUrl` is wired to the session context's `serverUrl`
- * - `tui.selectSession` is called after creating a session
+ * Checks that OpenCode workflow source files use the runtime-managed
+ * `s.client` and `s.session` instead of manual SDK client creation.
  */
 
 export interface OpenCodeValidationWarning {
@@ -18,27 +17,21 @@ export function validateOpenCodeWorkflow(source: string): OpenCodeValidationWarn
   const warnings: OpenCodeValidationWarning[] = [];
 
   if (/\bcreateOpencodeClient\b/.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: s.serverUrl }. " +
-          "This is required to connect to the workflow's agent pane.",
-      });
-    }
+    warnings.push({
+      rule: "opencode/manual-client",
+      message:
+        "Manual createOpencodeClient() call detected. Use s.client instead — " +
+        "the runtime auto-creates the client. Pass client config as the second arg to ctx.stage().",
+    });
   }
 
-  if (/\bsession\.create\b/.test(source)) {
-    if (!/\btui\.selectSession\b/.test(source)) {
-      warnings.push({
-        rule: "opencode/select-session",
-        message:
-          "Could not verify that tui.selectSession is called after session.create(). " +
-          "Call client.tui.selectSession({ sessionID }) so the TUI displays the workflow session.",
-      });
-    }
+  if (/\bclient\.session\.create\b/.test(source)) {
+    warnings.push({
+      rule: "opencode/manual-session",
+      message:
+        "Manual client.session.create() call detected. Use s.session instead — " +
+        "the runtime auto-creates the session. Pass session config as the third arg to ctx.stage().",
+    });
   }
 
   return warnings;