@bastani/atomic 0.5.0-1

package/src/sdk/errors.ts

@@ -0,0 +1,39 @@
+/**
+ * Typed error classes for the SDK.
+ *
+ * The SDK throws these instead of calling process.exit() or console.error().
+ * The CLI layer catches them and maps to user-visible output.
+ */
+
+/** Thrown when a required system dependency is not found on PATH. */
+export class MissingDependencyError extends Error {
+  constructor(public readonly dependency: "tmux" | "psmux" | "bun") {
+    super(`Required dependency not found: ${dependency}`);
+    this.name = "MissingDependencyError";
+  }
+}
+
+/** Thrown when a workflow file is defined but missing .compile(). */
+export class WorkflowNotCompiledError extends Error {
+  constructor(public readonly path: string) {
+    super(
+      `Workflow at ${path} was defined but not compiled.\n` +
+      `  Add .compile() at the end of your defineWorkflow() chain:\n\n` +
+      `    export default defineWorkflow({ ... })\n` +
+      `      .session({ ... })\n` +
+      `      .compile();`,
+    );
+    this.name = "WorkflowNotCompiledError";
+  }
+}
+
+/** Thrown when a workflow file does not export a valid WorkflowDefinition. */
+export class InvalidWorkflowError extends Error {
+  constructor(public readonly path: string) {
+    super(
+      `${path} does not export a valid WorkflowDefinition.\n` +
+      `  Make sure it exports defineWorkflow(...).compile() as the default export.`,
+    );
+    this.name = "InvalidWorkflowError";
+  }
+}

package/src/sdk/index.ts

@@ -0,0 +1,38 @@
+/**
+ * atomic SDK
+ *
+ * Public API barrel — re-exports the SDK surface.
+ * CLI-only concerns (colors, prompts, process management) are not exported here.
+ */
+
+// Typed errors
+export {
+  MissingDependencyError,
+  WorkflowNotCompiledError,
+  InvalidWorkflowError,
+} from "./errors.ts";
+
+// Shared types
+export type {
+  AgentType,
+  Transcript,
+  SavedMessage,
+  SaveTranscript,
+  SessionContext,
+  SessionOptions,
+  WorkflowOptions,
+  WorkflowDefinition,
+} from "./types.ts";
+
+// Workflow SDK (also available as atomic/workflows subpath)
+export { defineWorkflow } from "./define-workflow.ts";
+
+// Workflow discovery and execution
+export {
+  discoverWorkflows,
+  findWorkflow,
+} from "./runtime/discovery.ts";
+
+export { WorkflowLoader } from "./runtime/loader.ts";
+
+export { executeWorkflow } from "./runtime/executor.ts";

package/src/sdk/providers/claude.ts

@@ -0,0 +1,316 @@
+/**
+ * Claude Code query abstraction.
+ *
+ * Sends a prompt to an interactive Claude Code session running in a tmux pane
+ * using `tmux send-keys -l --` (literal text) + `C-m` (raw carriage return).
+ * Verifies delivery by polling `capture-pane` and retries if needed.
+ *
+ * This is NOT headless — Claude runs as a full interactive TUI in the pane.
+ * We're automating keyboard input and reading pane output.
+ *
+ * Reliability hardened from oh-my-codex's sendToWorker implementation:
+ * - Pre-send readiness wait with exponential backoff
+ * - CLI-specific submit plan (Claude: 1 C-m per round)
+ * - Per-round capture verification (6 rounds)
+ * - Adaptive retry with C-u clear + retype
+ * - Post-submit active-task detection
+ * - Whitespace-collapsing normalization
+ */
+
+import {
+  sendLiteralText,
+  sendSpecialKey,
+  sendKeysAndSubmit,
+  capturePaneVisible,
+  capturePaneScrollback,
+  normalizeTmuxCapture,
+  normalizeTmuxLines,
+  paneLooksReady,
+  paneHasActiveTask,
+  waitForPaneReady,
+  attemptSubmitRounds,
+} from "../runtime/tmux.ts";
+
+// ---------------------------------------------------------------------------
+// Session tracking — ensures createClaudeSession is called before claudeQuery
+// ---------------------------------------------------------------------------
+
+const initializedPanes = new Set<string>();
+
+/**
+ * Remove a pane from the initialized set, freeing memory.
+ * Call when a Claude session is killed or no longer needed.
+ */
+export function clearClaudeSession(paneId: string): void {
+  initializedPanes.delete(paneId);
+}
+
+/** Default CLI flags passed to the `claude` command. */
+const DEFAULT_CHAT_FLAGS = [
+  "--allow-dangerously-skip-permissions",
+  "--dangerously-skip-permissions",
+];
+
+// ---------------------------------------------------------------------------
+// createClaudeSession
+// ---------------------------------------------------------------------------
+
+export interface ClaudeSessionOptions {
+  /** tmux pane ID where Claude should be started */
+  paneId: string;
+  /** CLI flags to pass to the `claude` command (default: ["--allow-dangerously-skip-permissions", "--dangerously-skip-permissions"]) */
+  chatFlags?: string[];
+  /** Timeout in ms waiting for Claude TUI to be ready (default: 30s) */
+  readyTimeoutMs?: number;
+}
+
+/**
+ * Start Claude Code in a tmux pane with configurable CLI flags.
+ *
+ * Must be called before any `claudeQuery()` calls targeting the same pane.
+ * The pane should be a bare shell — `createClaudeSession` sends the `claude`
+ * command with the given flags and waits for the TUI to become ready.
+ *
+ * @example
+ * ```typescript
+ * import { createClaudeSession, claudeQuery } from "@bastani/atomic/workflows";
+ *
+ * await createClaudeSession({ paneId: ctx.paneId });
+ * await claudeQuery({ paneId: ctx.paneId, prompt: "Describe this project" });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom flags
+ * await createClaudeSession({
+ *   paneId: ctx.paneId,
+ *   chatFlags: ["--model", "opus", "--dangerously-skip-permissions"],
+ * });
+ * ```
+ */
+export async function createClaudeSession(options: ClaudeSessionOptions): Promise<void> {
+  const {
+    paneId,
+    chatFlags = DEFAULT_CHAT_FLAGS,
+    readyTimeoutMs = 30_000,
+  } = options;
+
+  const cmd = ["claude", ...chatFlags].join(" ");
+  sendKeysAndSubmit(paneId, cmd);
+
+  // Give the shell time to exec before polling for TUI readiness
+  await Bun.sleep(1_000);
+  await waitForPaneReady(paneId, readyTimeoutMs);
+
+  // Verify Claude TUI actually rendered — a bare shell or crash won't show
+  // the expected prompt/task indicators
+  const visible = capturePaneVisible(paneId);
+  if (!paneLooksReady(visible) && !paneHasActiveTask(visible)) {
+    throw new Error(
+      "createClaudeSession() timed out waiting for the Claude TUI to start. " +
+      "Verify the `claude` command is installed and the flags are valid.",
+    );
+  }
+
+  initializedPanes.add(paneId);
+}
+
+// ---------------------------------------------------------------------------
+// claudeQuery
+// ---------------------------------------------------------------------------
+
+export interface ClaudeQueryOptions {
+  /** tmux pane ID where Claude is running */
+  paneId: string;
+  /** The prompt to send */
+  prompt: string;
+  /** 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 for Claude) */
+  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;
+}
+
+export interface ClaudeQueryResult {
+  /** The full pane content after the response completed */
+  output: string;
+  /** Whether delivery was confirmed (text disappeared from input) */
+  delivered: boolean;
+}
+
+/**
+ * Send a prompt to a Claude Code interactive session running in a tmux pane.
+ *
+ * Flow (hardened from OMX's sendToWorker):
+ * 1. Wait for pane readiness with exponential backoff
+ * 2. Capture pane content before sending
+ * 3. Send literal text via `send-keys -l --`
+ * 4. Submit with C-m rounds and per-round capture verification
+ * 5. Adaptive retry: clear line (C-u), re-type, re-submit
+ * 6. Post-submit verification via active-task detection
+ * 7. Wait for response by polling for output stabilization + prompt return
+ *
+ * @example
+ * ```typescript
+ * import { claudeQuery } from "@bastani/atomic/workflows";
+ *
+ * const result = await claudeQuery({
+ *   paneId: ctx.paneId,
+ *   prompt: "Describe this project",
+ * });
+ * ctx.log(result.output);
+ * ```
+ */
+export async function claudeQuery(options: ClaudeQueryOptions): Promise<ClaudeQueryResult> {
+  const {
+    paneId,
+    prompt,
+    timeoutMs = 300_000,
+    pollIntervalMs = 2_000,
+    submitPresses = 1,
+    maxSubmitRounds = 6,
+    readyTimeoutMs = 30_000,
+  } = options;
+
+  if (!initializedPanes.has(paneId)) {
+    throw new Error(
+      "claudeQuery() called without a prior createClaudeSession() for this pane. " +
+      "Call createClaudeSession({ paneId }) first to start the Claude CLI.",
+    );
+  }
+
+  const normalizedPrompt = normalizeTmuxCapture(prompt).slice(0, 100);
+
+  // Step 1: Wait for pane readiness before sending (deducted from response timeout)
+  const waitElapsed = await waitForPaneReady(paneId, readyTimeoutMs);
+  const responseTimeoutMs = Math.max(0, timeoutMs - waitElapsed);
+
+  if (waitElapsed > timeoutMs * 0.5) {
+    console.warn(
+      `claudeQuery: readiness wait consumed ${Math.round(waitElapsed / 1000)}s ` +
+      `of ${Math.round(timeoutMs / 1000)}s total timeout budget`,
+    );
+  }
+
+  const beforeContent = normalizeTmuxLines(capturePaneScrollback(paneId));
+
+  // Step 2: Send literal text
+  sendLiteralText(paneId, prompt);
+  await Bun.sleep(150);
+
+  // Step 3: Submit with per-round capture verification
+  let delivered = await attemptSubmitRounds(paneId, normalizedPrompt, maxSubmitRounds, submitPresses);
+
+  // Step 4: Adaptive retry — clear line, re-type, re-submit
+  if (!delivered) {
+    const visibleCapture = capturePaneVisible(paneId);
+    const visibleNorm = normalizeTmuxCapture(visibleCapture);
+
+    // Only retry if text is still visible and pane is idle (not mid-task)
+    if (visibleNorm.includes(normalizedPrompt) && !paneHasActiveTask(visibleCapture) && paneLooksReady(visibleCapture)) {
+      sendSpecialKey(paneId, "C-u");
+      await Bun.sleep(80);
+      sendLiteralText(paneId, prompt);
+      await Bun.sleep(120);
+      delivered = await attemptSubmitRounds(paneId, normalizedPrompt, 4, submitPresses);
+    }
+  }
+
+  // Step 5: Final fallback — double C-m nudge + post-submit verification
+  if (!delivered) {
+    sendSpecialKey(paneId, "C-m");
+    await Bun.sleep(120);
+    sendSpecialKey(paneId, "C-m");
+    await Bun.sleep(300);
+
+    const verifyCapture = capturePaneVisible(paneId);
+    if (paneHasActiveTask(verifyCapture)) {
+      delivered = true;
+    } else {
+      delivered = !normalizeTmuxCapture(verifyCapture).includes(normalizedPrompt);
+    }
+
+    // One more attempt if text is still stuck
+    if (!delivered) {
+      sendSpecialKey(paneId, "C-m");
+      await Bun.sleep(150);
+      sendSpecialKey(paneId, "C-m");
+    }
+  }
+
+  // Step 6: Wait for response by detecting output stabilization or prompt return
+  const deadline = Date.now() + responseTimeoutMs;
+  let lastContent = "";
+  let stableCount = 0;
+
+  // Give Claude time to start processing
+  await Bun.sleep(3_000);
+
+  while (Date.now() < deadline) {
+    const currentContent = normalizeTmuxLines(capturePaneScrollback(paneId));
+
+    // Must have new content compared to before we sent
+    if (currentContent === beforeContent) {
+      await Bun.sleep(pollIntervalMs);
+      continue;
+    }
+
+    // Use visible capture for state detection to avoid stale scrollback matches
+    const visible = capturePaneVisible(paneId);
+    if (paneLooksReady(visible) && !paneHasActiveTask(visible)) {
+      return { output: currentContent, delivered };
+    }
+
+    if (currentContent === lastContent) {
+      stableCount++;
+      if (stableCount >= 3) {
+        return { output: currentContent, delivered };
+      }
+    } else {
+      stableCount = 0;
+    }
+
+    lastContent = currentContent;
+    await Bun.sleep(pollIntervalMs);
+  }
+
+  // Timeout — return whatever we have
+  return { output: lastContent || capturePaneScrollback(paneId), delivered };
+}
+
+// ---------------------------------------------------------------------------
+// Static source validation
+// ---------------------------------------------------------------------------
+
+export interface ClaudeValidationWarning {
+  rule: string;
+  message: string;
+}
+
+/**
+ * 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.
+ */
+export function validateClaudeWorkflow(source: string): ClaudeValidationWarning[] {
+  const warnings: ClaudeValidationWarning[] = [];
+
+  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: ctx.paneId }) to start the Claude CLI before sending queries.",
+      });
+    }
+  }
+
+  return warnings;
+}

package/src/sdk/providers/copilot.ts

@@ -0,0 +1,43 @@
+/**
+ * Copilot workflow source validation.
+ *
+ * Checks that Copilot workflow source files follow required patterns:
+ * - `cliUrl` is wired to `ctx.serverUrl` (or destructured `serverUrl`)
+ * - `setForegroundSessionId` is called after creating a session
+ */
+
+export interface CopilotValidationWarning {
+  rule: string;
+  message: string;
+}
+
+/**
+ * Validate a Copilot workflow source file for common mistakes.
+ */
+export function validateCopilotWorkflow(source: string): CopilotValidationWarning[] {
+  const warnings: CopilotValidationWarning[] = [];
+
+  if (/\bCopilotClient\b/.test(source)) {
+    if (!/cliUrl\s*:\s*(?:ctx\.serverUrl|serverUrl)/.test(source)) {
+      warnings.push({
+        rule: "copilot/cli-url",
+        message:
+          "Could not verify that CopilotClient is created with { cliUrl: ctx.serverUrl }. " +
+          "This is required to connect to the workflow's agent pane.",
+      });
+    }
+  }
+
+  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.",
+      });
+    }
+  }
+
+  return warnings;
+}

package/src/sdk/providers/opencode.ts

@@ -0,0 +1,43 @@
+/**
+ * OpenCode workflow source validation.
+ *
+ * Checks that OpenCode workflow source files follow required patterns:
+ * - `baseUrl` is wired to `ctx.serverUrl` (or destructured `serverUrl`)
+ * - `tui.selectSession` is called after creating a session
+ */
+
+export interface OpenCodeValidationWarning {
+  rule: string;
+  message: string;
+}
+
+/**
+ * Validate an OpenCode workflow source file for common mistakes.
+ */
+export function validateOpenCodeWorkflow(source: string): OpenCodeValidationWarning[] {
+  const warnings: OpenCodeValidationWarning[] = [];
+
+  if (/\bcreateOpencodeClient\b/.test(source)) {
+    if (!/baseUrl\s*:\s*(?:ctx\.serverUrl|serverUrl)/.test(source)) {
+      warnings.push({
+        rule: "opencode/base-url",
+        message:
+          "Could not verify that createOpencodeClient is called with { baseUrl: ctx.serverUrl }. " +
+          "This is required to connect to the workflow's agent pane.",
+      });
+    }
+  }
+
+  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.",
+      });
+    }
+  }
+
+  return warnings;
+}

package/src/sdk/runtime/discovery.ts

@@ -0,0 +1,172 @@
+/**
+ * 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)
+ *
+ * Project-local workflows take precedence over global ones with the same name.
+ */
+
+import { join } from "path";
+import { readdir, writeFile } from "fs/promises";
+import { homedir } from "os";
+import ignore from "ignore";
+import type { AgentType } from "../types.ts";
+
+export interface DiscoveredWorkflow {
+  name: string;
+  agent: AgentType;
+  path: string;
+  source: "local" | "global";
+}
+
+function getLocalWorkflowsDir(projectRoot: string): string {
+  return join(projectRoot, ".atomic", "workflows");
+}
+
+function getGlobalWorkflowsDir(): string {
+  return join(homedir(), ".atomic", "workflows");
+}
+
+export const AGENTS: AgentType[] = ["copilot", "opencode", "claude"];
+const AGENT_SET = new Set<string>(AGENTS);
+
+/**
+ * Default `.gitignore` content for a workflows directory.
+ * Auto-generated during install; regenerated by discovery if missing.
+ */
+export const WORKFLOWS_GITIGNORE = [
+  "node_modules/",
+  "dist/",
+  "build/",
+  "coverage/",
+  ".cache/",
+  "*.log",
+  "*.tsbuildinfo",
+  "",
+].join("\n");
+
+/**
+ * Load the `.gitignore` from a workflows directory, regenerating it if absent.
+ * The workflows `.gitignore` is always auto-generated so a missing file
+ * indicates an incomplete setup rather than an intentional absence.
+ */
+async function loadWorkflowsGitignore(workflowsDir: string): Promise<ignore.Ignore> {
+  const gitignorePath = join(workflowsDir, ".gitignore");
+  let content: string;
+  try {
+    content = await Bun.file(gitignorePath).text();
+  } catch {
+    // Missing — regenerate from the canonical template
+    await writeFile(gitignorePath, WORKFLOWS_GITIGNORE);
+    content = WORKFLOWS_GITIGNORE;
+  }
+  return ignore().add(content);
+}
+
+/**
+ * Discover workflows from a base directory by scanning workflow-name
+ * directories first, then agent subdirectories within each.
+ *
+ * Layout: baseDir/<workflow_name>/<agent>/index.ts
+ *
+ * Entries are filtered against the `.gitignore` that lives inside the
+ * workflows directory itself (auto-generated, regenerated if missing).
+ */
+async function discoverFromBaseDir(
+  baseDir: string,
+  source: "local" | "global",
+  agentFilter?: AgentType,
+): Promise<DiscoveredWorkflow[]> {
+  const workflows: DiscoveredWorkflow[] = [];
+  const agents = agentFilter ? [agentFilter] : AGENTS;
+  const agentNames = new Set<string>(agents);
+
+  let workflowEntries;
+  try {
+    workflowEntries = await readdir(baseDir, { withFileTypes: true });
+  } catch {
+    return workflows;
+  }
+
+  const ig = await loadWorkflowsGitignore(baseDir);
+
+  for (const wfEntry of workflowEntries) {
+    if (!wfEntry.isDirectory()) continue;
+    if (wfEntry.name.startsWith(".")) continue;
+    // Skip agent-named directories at root (they are not workflow names)
+    if (AGENT_SET.has(wfEntry.name)) continue;
+    // Skip directories matched by the workflows .gitignore.
+    // Append "/" so directory-only patterns (e.g. "build/") match correctly.
+    if (ig.ignores(wfEntry.name + "/")) continue;
+
+    const workflowDir = join(baseDir, wfEntry.name);
+
+    let agentEntries;
+    try {
+      agentEntries = await readdir(workflowDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const agentEntry of agentEntries) {
+      if (!agentEntry.isDirectory()) continue;
+      if (!agentNames.has(agentEntry.name)) continue;
+
+      const indexPath = join(workflowDir, agentEntry.name, "index.ts");
+      const file = Bun.file(indexPath);
+      if (await file.exists()) {
+        workflows.push({
+          name: wfEntry.name,
+          agent: agentEntry.name as AgentType,
+          path: indexPath,
+          source,
+        });
+      }
+    }
+  }
+
+  return workflows;
+}
+
+/**
+ * Discover all available workflows from local and global directories.
+ * Optionally filter by agent. Local workflows take precedence over global.
+ */
+export async function discoverWorkflows(
+  projectRoot: string = process.cwd(),
+  agentFilter?: AgentType
+): Promise<DiscoveredWorkflow[]> {
+  const localDir = getLocalWorkflowsDir(projectRoot);
+  const globalDir = getGlobalWorkflowsDir();
+
+  const [globalResults, localResults] = await Promise.all([
+    discoverFromBaseDir(globalDir, "global", agentFilter),
+    discoverFromBaseDir(localDir, "local", agentFilter),
+  ]);
+
+  const byKey = new Map<string, DiscoveredWorkflow>();
+  for (const wf of globalResults) {
+    byKey.set(`${wf.agent}/${wf.name}`, wf);
+  }
+  for (const wf of localResults) {
+    byKey.set(`${wf.agent}/${wf.name}`, wf);
+  }
+
+  return Array.from(byKey.values());
+}
+
+/**
+ * Find a specific workflow by name and agent.
+ */
+export async function findWorkflow(
+  name: string,
+  agent: AgentType,
+  projectRoot: string = process.cwd()
+): Promise<DiscoveredWorkflow | null> {
+  const all = await discoverWorkflows(projectRoot, agent);
+  return all.find((w) => w.name === name) ?? null;
+}
+
+