@bastani/atomic 0.6.4 → 0.6.5-0

package/src/sdk/runtime/tmux.ts

@@ -671,6 +671,23 @@ export function attachOrSwitch(sessionName: string): void {
   }
 }
 
+/**
+ * Detach every client currently attached to the given atomic-managed
+ * tmux session. The session itself stays alive — only the clients are
+ * disconnected. Mirrors {@link attachSession}: attach connects a client,
+ * detachClients disconnects them.
+ *
+ * Best-effort: returns silently when the session has no attached clients
+ * or has already been torn down.
+ */
+export function detachClients(sessionName: string): void {
+  try {
+    tmuxExec(["detach-client", "-s", sessionName]);
+  } catch {
+    // No clients attached or session already gone — nothing to do.
+  }
+}
+
 /**
  * Detach from the user's current tmux session and replace the client
  * with an attach to a session on the atomic socket.
@@ -708,6 +725,22 @@ export function selectWindow(target: string): void {
   tmuxExec(["select-window", "-t", target]);
 }
 
+/**
+ * Move the target session's current-window pointer forward by one.
+ * Equivalent to the `Ctrl+\` binding inside an attached client, but
+ * usable without a client and addressable by session name.
+ */
+export function nextWindow(sessionName: string): void {
+  tmuxExec(["next-window", "-t", sessionName]);
+}
+
+/**
+ * Move the target session's current-window pointer backward by one.
+ */
+export function previousWindow(sessionName: string): void {
+  tmuxExec(["previous-window", "-t", sessionName]);
+}
+
 // ---------------------------------------------------------------------------
 // Normalization (ported from oh-my-codex's normalizeTmuxCapture)
 // ---------------------------------------------------------------------------

package/src/sdk/types.ts

@@ -397,6 +397,22 @@ export interface WorkflowOptions<
   name: string;
   /** Human-readable description */
   description?: string;
+  /**
+   * Absolute path of the workflow source file. Pass `import.meta.path` —
+   * the SDK uses this to import the workflow module inside the
+   * orchestrator child process. Required: a workflow without `source`
+   * cannot be re-imported by the orchestrator and `defineWorkflow`
+   * throws at compile time.
+   *
+   * @example
+   * ```typescript
+   * defineWorkflow({
+   *   name: "hello",
+   *   source: import.meta.path, // ← required
+   * }).for("claude").run(...).compile();
+   * ```
+   */
+  source: string;
   /**
    * Optional declared inputs. When provided, the CLI materialises one
    * `--<name>` flag per entry and the interactive picker renders one form
@@ -446,6 +462,7 @@ export type RegistrableWorkflow = {
   readonly description: string;
   readonly inputs: readonly WorkflowInput[];
   readonly minSDKVersion: string | null;
+  readonly source: string;
   readonly run: (...args: never[]) => Promise<void>;
 };
 
@@ -487,97 +504,6 @@ export type Registry<
   resolve(name: string, agent: AgentType): WorkflowDefinition | undefined;
 };
 
-/**
- * Argv control for `WorkflowCli.run`.
- *
- * - `undefined` — parse `process.argv` (default).
- * - `string[]` — parse this explicit argv list (tests, embedding).
- * - `false` — skip parsing; use `inputs` / `name` / `agent` as provided.
- */
-export type ArgvMode = string[] | false;
-
-/** Options for constructing a WorkflowCli via `createWorkflowCli()`. */
-export interface CreateWorkflowCliOptions {
-  /** Programmatic inputs. CLI flags override these. */
-  inputs?: Record<string, string>;
-  /**
-   * Absolute path to the composition root file. The executor re-executes
-   * this path with `ATOMIC_ORCHESTRATOR_MODE=1` when detach is requested,
-   * so re-entry lands on the module that wired the dispatcher. Defaults
-   * to `process.argv[1]` — override when your composition root isn't
-   * argv[1] (test harnesses, bundled CLIs, embedded programs).
-   */
-  entry?: string;
-  /**
-   * Hook to attach sibling commands to the standalone `run()` CLI. The
-   * callback runs once against the Commander program `run()` built
-   * internally. Not used by the `toCommand` adapter — if you're embedding,
-   * add your siblings to the parent directly.
-   */
-  extend?: (program: import("@commander-js/extra-typings").Command) => void;
-  /**
-   * When `true` (the default), the generated CLI auto-registers the
-   * session + status management subcommands — `session list`,
-   * `session connect`, `session kill`, and `status` — so SDK users get
-   * the same monitoring UX as `atomic workflow …` without needing the
-   * global `atomic` binary.
-   *
-   * Every session spawned by the SDK lives on the shared `atomic` tmux
-   * socket, so these commands are pure pass-throughs to the same
-   * implementations the global CLI uses; there's no divergence. Set to
-   * `false` only when you want a minimal CLI (e.g. programmatic invocation
-   * or embedding under a parent Commander program where the parent owns
-   * session management).
-   *
-   * The `session` and `status` names are reserved — workflow inputs
-   * declared with those names will throw at `defineWorkflow` time to
-   * avoid flag collisions.
-   */
-  includeManagementCommands?: boolean;
-}
-
-/**
- * A CLI program that resolves `--name` + `--agent` from argv and runs the
- * matching workflow from a registry. Used by multi-workflow CLIs (e.g.
- * the internal `atomic workflow` command) and single-workflow entry points.
- *
- * Framework-agnostic by design. To embed under a parent CLI, use the
- * `toCommand` adapter in `@bastani/atomic/workflows/commander`.
- */
-export interface WorkflowCli<
-  T extends Record<string, WorkflowDefinition> = Record<string, WorkflowDefinition>,
-> {
-  /** Registry the CLI was constructed with. */
-  readonly registry: Registry<T>;
-  /**
-   * Absolute path the executor re-execs on `--detach`. Defaults to
-   * `process.argv[1]`; override via `createWorkflowCli(reg, { entry })`.
-   */
-  readonly entry: string;
-  /**
-   * Input defaults supplied at construction. The adapter reads these so
-   * CLI-built Commands merge them identically to `run()`.
-   */
-  readonly defaults: Record<string, string> | undefined;
-  /**
-   * Run the workflow CLI.
-   *
-   * - Default (`argv` unset): parses `process.argv` with `-n/--name`,
-   *   `-a/--agent`, and the per-input union across the registry;
-   *   `inputs`/`name`/`agent` layer in as defaults.
-   * - `argv: [...]`: parses the given argv list the same way.
-   * - `argv: false`: skip parsing; `name` and `agent` are required and
-   *   `inputs` are used as-is.
-   */
-  run(options?: {
-    name?: string;
-    agent?: AgentType;
-    inputs?: Record<string, string>;
-    argv?: ArgvMode;
-    detach?: boolean;
-  }): Promise<void>;
-}
-
 /**
  * A compiled workflow definition — the sealed output of defineWorkflow().compile().
  */
@@ -590,6 +516,15 @@ export interface WorkflowDefinition<
   /** The agent this workflow targets. Set via `.for(agent)` in the builder. */
   readonly agent: A;
   readonly description: string;
+  /**
+   * Absolute path of the workflow source file (the value of
+   * `import.meta.path` at the `defineWorkflow()` call site).
+   *
+   * The SDK's orchestrator entry script `import()`s this path inside
+   * the child process to recover the compiled definition without any
+   * reliance on environment variables or the parent CLI's argv.
+   */
+  readonly source: string;
   /**
    * Declared input schema — empty tuple for free-form workflows.
    * Typed as the builder-supplied `I` so consumers (e.g.

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

@@ -159,6 +159,7 @@ function logBatchRejections(
 
 export default defineWorkflow({
   name: "deep-research-codebase",
+  source: import.meta.path,
   description:
     "Deterministic deep codebase research: scout → per-partition specialist sub-agents → aggregator",
   inputs: [

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

@@ -109,6 +109,7 @@ function logBatchRejections(
 
 export default defineWorkflow({
   name: "deep-research-codebase",
+  source: import.meta.path,
   description:
     "Deterministic deep codebase research: scout → per-partition specialist sub-agents → aggregator",
   inputs: [

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

@@ -100,6 +100,7 @@ function logBatchRejections(
 
 export default defineWorkflow({
   name: "deep-research-codebase",
+  source: import.meta.path,
   description:
     "Deterministic deep codebase research: scout → per-partition specialist sub-agents → aggregator",
   inputs: [

package/src/sdk/workflows/builtin/open-claude-design/claude/index.ts

@@ -88,6 +88,7 @@ import {
 
 export default defineWorkflow({
   name: "open-claude-design",
+  source: import.meta.path,
   description:
     "AI-powered design workflow: design system onboarding → import → generate → refine → export/handoff",
   inputs: [

package/src/sdk/workflows/builtin/open-claude-design/copilot/index.ts

@@ -89,6 +89,7 @@ function getAssistantText(messages: SessionEvent[]): string {
 
 export default defineWorkflow({
   name: "open-claude-design",
+  source: import.meta.path,
   description:
     "AI-powered design workflow: design system onboarding → import → generate → refine → export/handoff",
   inputs: [

package/src/sdk/workflows/builtin/open-claude-design/opencode/index.ts

@@ -84,6 +84,7 @@ function extractResponseText(
 
 export default defineWorkflow({
   name: "open-claude-design",
+  source: import.meta.path,
   description:
     "AI-powered design workflow: design system onboarding → import → generate → refine → export/handoff",
   inputs: [

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

@@ -69,6 +69,7 @@ function extractReview(
 
 export default defineWorkflow({
   name: "ralph",
+  source: import.meta.path,
   description: "Plan → orchestrate → review loop with bounded iteration",
   inputs: [
     {

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

@@ -83,6 +83,7 @@ function getAssistantText(messages: SessionEvent[]): string {
 
 export default defineWorkflow({
   name: "ralph",
+  source: import.meta.path,
   description: "Plan → orchestrate → review loop with bounded iteration",
   inputs: [
     {

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

@@ -75,6 +75,7 @@ function extractReview(
 
 export default defineWorkflow({
   name: "ralph",
+  source: import.meta.path,
   description: "Plan → orchestrate → review loop with bounded iteration",
   inputs: [
     { name: "prompt", type: "text", required: true, description: "task prompt" },

package/src/sdk/workflows/index.ts

@@ -1,26 +1,31 @@
 /**
- * atomic/workflows
+ * @bastani/atomic/workflows — workflow SDK barrel.
  *
- * Workflow SDK for defining dynamic agent workflows.
- * Workflows use defineWorkflow().run().compile() with ctx.stage()
- * for spawning agent sessions using native TypeScript control flow.
+ * Mirrors the root barrel for the historical `/workflows` import path.
+ * Provider-specific helpers (validators, native SDK type re-exports) and
+ * the validation warning type live here so consumers don't have to drill
+ * into provider modules directly.
+ *
+ * Tmux helpers and other runtime utilities are intentionally NOT
+ * re-exported — they are private to the SDK and the atomic CLI.
  */
 
+// ─── Authoring ──────────────────────────────────────────────────────────────
 export { defineWorkflow, WorkflowBuilder } from "../define-workflow.ts";
 export { createRegistry } from "../registry.ts";
 export type { Registry } from "../registry.ts";
 
-// WorkflowCli — the single factory that drives workflow CLIs. Accepts a
-// lone workflow, an array of workflows, or a Registry for programmatic
-// composition. Ships with the interactive picker out of the box.
-export { createWorkflowCli } from "../workflow-cli.ts";
-export type { WorkflowCli, CreateWorkflowCliOptions } from "../types.ts";
-
-export type { ArgvMode } from "../types.ts";
+// ─── Errors ─────────────────────────────────────────────────────────────────
+export {
+  MissingDependencyError,
+  WorkflowNotCompiledError,
+  InvalidWorkflowError,
+  SessionNotFoundError,
+} from "../errors.ts";
 
+// ─── Shared types ───────────────────────────────────────────────────────────
 export type {
   AgentType,
-  ValidationWarning,
   Transcript,
   SavedMessage,
   SaveTranscript,
@@ -28,6 +33,7 @@ export type {
   SessionRef,
   SessionHandle,
   SessionRunOptions,
+  ValidationWarning,
   WorkflowContext,
   WorkflowOptions,
   WorkflowDefinition,
@@ -47,53 +53,64 @@ export type {
   ClaudeSessionWrapper,
 } from "../types.ts";
 
-// Re-export native SDK types for convenience
+// ─── Native SDK message types ──────────────────────────────────────────────
 export type { SessionEvent as CopilotSessionEvent } from "@github/copilot-sdk";
 export type { SessionPromptResponse as OpenCodePromptResponse } from "@opencode-ai/sdk/v2";
 export type { SessionMessage as ClaudeSessionMessage } from "@anthropic-ai/claude-agent-sdk";
 
-// Providers
-export { createClaudeSession, claudeQuery, clearClaudeSession, extractAssistantText, validateClaudeWorkflow } from "../providers/claude.ts";
-export type { ClaudeSessionOptions, ClaudeQueryOptions } from "../providers/claude.ts";
+// ─── Provider helpers ──────────────────────────────────────────────────────
+export {
+  createClaudeSession,
+  claudeQuery,
+  clearClaudeSession,
+  extractAssistantText,
+  validateClaudeWorkflow,
+} from "../providers/claude.ts";
+export type {
+  ClaudeSessionOptions,
+  ClaudeQueryOptions,
+} from "../providers/claude.ts";
 
 export { validateCopilotWorkflow } from "../providers/copilot.ts";
-
 export { validateOpenCodeWorkflow } from "../providers/opencode.ts";
 
-// Runtime — tmux utilities
-export type { TmuxResult, TmuxSession, SessionType } from "../runtime/tmux.ts";
+// ─── Metadata accessors ────────────────────────────────────────────────────
+export {
+  getName,
+  getDescription,
+  getAgent,
+  getInputSchema,
+  getSource,
+  getMinSDKVersion,
+} from "../primitives/metadata.ts";
+
+// ─── Registry iteration ────────────────────────────────────────────────────
+export { listWorkflows, getWorkflow } from "../index.ts";
+
+// ─── Input validation ──────────────────────────────────────────────────────
+export { validateInputs } from "../primitives/inputs.ts";
+export type { ResolvedInputs } from "../primitives/inputs.ts";
+
+// ─── Run a workflow ────────────────────────────────────────────────────────
+export { runWorkflow } from "../primitives/run.ts";
+export type {
+  RunWorkflowOptions,
+  RunWorkflowResult,
+} from "../primitives/run.ts";
+
+// ─── Session management ────────────────────────────────────────────────────
 export {
-  SOCKET_NAME,
-  isTmuxInstalled,
-  getMuxBinary,
-  resetMuxBinaryCache,
-  isInsideTmux,
-  isInsideAtomicSocket,
-  createSession,
-  createWindow,
-  createPane,
-  sendLiteralText,
-  sendSpecialKey,
-  capturePane,
-  capturePaneVisible,
-  capturePaneScrollback,
-  killSession,
-  killSessionOnPaneExit,
-  killWindow,
-  sessionExists,
   listSessions,
+  getSession,
+  stopSession,
   attachSession,
-  spawnMuxAttach,
-  switchClient,
-  getCurrentSession,
-  attachOrSwitch,
-  detachAndAttachAtomic,
-  selectWindow,
-  setSessionEnv,
-  getSessionEnv,
-  parseSessionName,
-  tmuxRun,
-  normalizeTmuxCapture,
-  normalizeTmuxLines,
-} from "../runtime/tmux.ts";
-
+  getSessionStatus,
+  getSessionTranscript,
+} from "../primitives/sessions.ts";
+export type {
+  SessionInfo,
+  SessionScope,
+  StatusSnapshot,
+  ListSessionsOptions,
+  SessionPrimitiveDeps,
+} from "../primitives/sessions.ts";

package/src/services/config/additional-instructions.ts

@@ -46,7 +46,7 @@ Use playwright-cli (refer to playwright-cli skill) for ALL browser automation ta
 
 You are operating in an environment where ast-grep is installed. For any code search that requires understanding of syntax or code structure, you should default to using \`ast-grep --lang [language] -p '<pattern>'\`. Rely on your ast-grep skill for best practices. Adjust the --lang flag as needed for the specific programming language. Avoid using text-only search tools unless a plain-text search is explicitly requested.
 
-3. **Testing**: ALWAYS invoke your test-driven-development skill BEFORE creating or modifying any tests.
+3. **Testing**: ALWAYS invoke your tdd skill BEFORE creating or modifying any tests.
 
 4. **Sub-agent Orchestration**: You have a large number of tools available to you. The most important one is the one that allows you to dispatch sub-agents: either \`Agent\` or \`Task\`.