@bastani/atomic 0.5.0-3 → 0.5.0-4

package/src/sdk/runtime/loader.ts

@@ -297,7 +297,7 @@ export namespace WorkflowLoader {
               `Workflow at ${validated.path} was defined but not compiled.\n` +
               `  Add .compile() at the end of your defineWorkflow() chain:\n\n` +
               `    export default defineWorkflow({ ... })\n` +
-              `      .session({ ... })\n` +
+              `      .run(async (ctx) => { ... })\n` +
               `      .compile();`,
           };
         }
@@ -308,7 +308,7 @@ export namespace WorkflowLoader {
           error: new Error("Invalid workflow export"),
           message:
             `${validated.path} does not export a valid WorkflowDefinition.\n` +
-            `  Make sure it exports defineWorkflow(...).compile() as the default export.`,
+            `  Make sure it exports defineWorkflow(...).run(...).compile() as the default export.`,
         };
       }
 

package/src/sdk/runtime/tmux.ts

@@ -110,6 +110,19 @@ function tmuxExec(args: string[]): void {
 // Session and pane management
 // ---------------------------------------------------------------------------
 
+/**
+ * Build `-e KEY=VALUE` argument pairs for tmux environment flags.
+ * Supported by tmux new-session/new-window since tmux 3.2.
+ */
+function buildEnvArgs(envVars?: Record<string, string>): string[] {
+  if (!envVars) return [];
+  const args: string[] = [];
+  for (const [key, value] of Object.entries(envVars)) {
+    args.push("-e", `${key}=${value}`);
+  }
+  return args;
+}
+
 /**
  * Create a new tmux session with the given name.
  * The session starts detached with an initial command in the first pane.
@@ -118,14 +131,22 @@ function tmuxExec(args: string[]): void {
  * @param initialCommand - Shell command to run in the initial pane
  * @param windowName - Optional name for the initial window
  * @param cwd - Optional working directory for the initial pane
+ * @param envVars - Optional environment variables for the initial pane
  * @returns The pane ID of the initial pane (e.g., "%0")
  */
-export function createSession(sessionName: string, initialCommand: string, windowName?: string, cwd?: string): string {
+export function createSession(
+  sessionName: string,
+  initialCommand: string,
+  windowName?: string,
+  cwd?: string,
+  envVars?: Record<string, string>,
+): string {
   const args = [
     "new-session",
     "-d",
     "-s", sessionName,
     "-P", "-F", "#{pane_id}",
+    ...buildEnvArgs(envVars),
   ];
   if (windowName) {
     args.push("-n", windowName);
@@ -145,15 +166,23 @@ export function createSession(sessionName: string, initialCommand: string, windo
  * @param windowName - Name for the new window
  * @param command - Shell command to run in the new window
  * @param cwd - Optional working directory for the new window
+ * @param envVars - Optional environment variables for the new window
  * @returns The pane ID of the new window's pane
  */
-export function createWindow(sessionName: string, windowName: string, command: string, cwd?: string): string {
+export function createWindow(
+  sessionName: string,
+  windowName: string,
+  command: string,
+  cwd?: string,
+  envVars?: Record<string, string>,
+): string {
   const args = [
     "new-window",
     "-d",
     "-t", sessionName,
     "-n", windowName,
     "-P", "-F", "#{pane_id}",
+    ...buildEnvArgs(envVars),
   ];
   if (cwd) {
     args.push("-c", cwd);

package/src/sdk/types.ts

@@ -34,9 +34,9 @@ export type SavedMessage =
 /**
  * Save native message objects from the provider SDK.
  *
- * - **Copilot**: `ctx.save(await session.getMessages())`
- * - **OpenCode**: `ctx.save(result.data)` — the full `{ info, parts }` response
- * - **Claude**: `ctx.save(sessionId)` — auto-reads via `getSessionMessages()`
+ * - **Copilot**: `s.save(await session.getMessages())`
+ * - **OpenCode**: `s.save(result.data)` — the full `{ info, parts }` response
+ * - **Claude**: `s.save(sessionId)` — auto-reads via `getSessionMessages()`
  */
 export interface SaveTranscript {
   /** Save Copilot SessionEvent[] from session.getMessages() */
@@ -47,8 +47,54 @@ export interface SaveTranscript {
   (claudeSessionId: string): Promise<void>;
 }
 
+/** A reference to a completed session — either a handle or a session name string. */
+export type SessionRef = string | SessionHandle<unknown>;
+
+/**
+ * Handle returned by `ctx.session()`. Used for type-safe transcript references
+ * and carries the callback's return value.
+ */
+export interface SessionHandle<T = void> {
+  /** The session's unique name */
+  readonly name: string;
+  /** The session's generated UUID */
+  readonly id: string;
+  /** The value returned by the session callback */
+  readonly result: T;
+}
+
+/**
+ * Options for spawning a session via `ctx.session()`.
+ */
+export interface SessionRunOptions {
+  /** Unique name for this session (used for transcript references and graph display) */
+  name: string;
+  /** Human-readable description */
+  description?: string;
+  /**
+   * Names of sessions this one depends on. Serves two purposes:
+   *
+   * 1. **Graph rendering** — each named session becomes a parent edge in the
+   *    graph, so chains and fan-ins show up as real topology instead of
+   *    sibling-under-root.
+   * 2. **Runtime ordering** — at spawn time, the runtime waits for every
+   *    named dep to finish before starting. This makes dependency-driven
+   *    `Promise.all([...])` patterns safe: you can kick off many sessions
+   *    concurrently and let `dependsOn` serialize only the edges that matter.
+   *
+   * Each name must refer to a session that has already been spawned (either
+   * active or completed) at the time the dependent session is created.
+   * Unknown names throw a clear error.
+   *
+   * When omitted, the session falls back to the default parent (the
+   * enclosing `ctx.session()` scope, or `orchestrator` at the top level).
+   */
+  dependsOn?: string[];
+}
+
 /**
- * Session context provided to each session's run() callback at execution time.
+ * Context provided to each session's callback.
+ * Created by `ctx.session(opts, fn)` — the callback receives this as its argument.
  */
 export interface SessionContext {
   /** The agent's server URL (Copilot --ui-server / OpenCode built-in server) */
@@ -58,15 +104,15 @@ export interface SessionContext {
   /** Which agent is running */
   agent: AgentType;
   /**
-   * Get a previous session's transcript as rendered text.
-   * Returns `{ path, content }` — path for file triggers, content for embedding.
+   * Get a completed session's transcript as rendered text.
+   * Accepts a SessionHandle (recommended) or session name string.
    */
-  transcript(sessionName: string): Promise<Transcript>;
+  transcript(ref: SessionRef): Promise<Transcript>;
   /**
-   * Get a previous session's raw native messages.
-   * Returns SavedMessage[] exactly as stored by ctx.save().
+   * Get a completed session's raw native messages.
+   * Accepts a SessionHandle (recommended) or session name string.
    */
-  getMessages(sessionName: string): Promise<SavedMessage[]>;
+  getMessages(ref: SessionRef): Promise<SavedMessage[]>;
   /**
    * Save this session's output for subsequent sessions.
    * Accepts native SDK message objects only.
@@ -78,18 +124,45 @@ export interface SessionContext {
   paneId: string;
   /** Session UUID */
   sessionId: string;
+  /**
+   * Spawn a nested sub-session with its own tmux window and graph node.
+   * The sub-session is a child of this session in the graph.
+   * The callback's return value is available as `handle.result`.
+   */
+  session<T = void>(
+    options: SessionRunOptions,
+    run: (ctx: SessionContext) => Promise<T>,
+  ): Promise<SessionHandle<T>>;
 }
 
 /**
- * Options for defining a session in a workflow.
+ * Top-level context provided to the workflow's `.run()` callback.
+ * Does not have session-specific fields (serverUrl, paneId, save, etc.).
  */
-export interface SessionOptions {
-  /** Unique name for this session (used for transcript references) */
-  name: string;
-  /** Human-readable description */
-  description?: string;
-  /** The session callback. User writes raw provider-specific SDK code here. */
-  run: (ctx: SessionContext) => Promise<void>;
+export interface WorkflowContext {
+  /** The original user prompt from the CLI invocation */
+  userPrompt: string;
+  /** Which agent is running */
+  agent: AgentType;
+  /**
+   * Spawn a session with its own tmux window and graph node.
+   * The runtime manages the full lifecycle: start → run callback → complete/error.
+   * The callback's return value is available as `handle.result`.
+   */
+  session<T = void>(
+    options: SessionRunOptions,
+    run: (ctx: SessionContext) => Promise<T>,
+  ): Promise<SessionHandle<T>>;
+  /**
+   * Get a completed session's transcript as rendered text.
+   * Accepts a SessionHandle (recommended) or session name string.
+   */
+  transcript(ref: SessionRef): Promise<Transcript>;
+  /**
+   * Get a completed session's raw native messages.
+   * Accepts a SessionHandle (recommended) or session name string.
+   */
+  getMessages(ref: SessionRef): Promise<SavedMessage[]>;
 }
 
 /**
@@ -109,6 +182,6 @@ export interface WorkflowDefinition {
   readonly __brand: "WorkflowDefinition";
   readonly name: string;
   readonly description: string;
-  /** Ordered execution steps. Each step is an array of sessions — length 1 is sequential, length > 1 is parallel. */
-  readonly steps: ReadonlyArray<ReadonlyArray<SessionOptions>>;
+  /** The workflow's entry point. Called by the executor with a WorkflowContext. */
+  readonly run: (ctx: WorkflowContext) => Promise<void>;
 }

package/src/sdk/workflows.ts

@@ -1,9 +1,9 @@
 /**
  * atomic/workflows
  *
- * Workflow SDK for defining multi-session agent workflows.
- * Workflows are defined as a chain of .session() calls and compiled
- * into a WorkflowDefinition consumed by the Atomic CLI runtime.
+ * Workflow SDK for defining dynamic agent workflows.
+ * Workflows use defineWorkflow().run().compile() with ctx.session()
+ * for spawning agent sessions using native TypeScript control flow.
  */
 
 export { defineWorkflow, WorkflowBuilder } from "./define-workflow.ts";
@@ -14,7 +14,10 @@ export type {
   SavedMessage,
   SaveTranscript,
   SessionContext,
-  SessionOptions,
+  SessionRef,
+  SessionHandle,
+  SessionRunOptions,
+  WorkflowContext,
   WorkflowOptions,
   WorkflowDefinition,
 } from "./types.ts";

package/src/services/config/definitions.ts

@@ -9,6 +9,8 @@ export interface AgentConfig {
   cmd: string;
   /** Flags used when spawning the agent in interactive chat mode */
   chat_flags: string[];
+  /** Environment variables to set when spawning the agent (merged with process env) */
+  env_vars: Record<string, string>;
   /** Config folder relative to repo root */
   folder: string;
   /** URL for installation instructions */
@@ -30,7 +32,11 @@ export const AGENT_CONFIG: Record<AgentKey, AgentConfig> = {
   claude: {
     name: "Claude Code",
     cmd: "claude",
-    chat_flags: ["--allow-dangerously-skip-permissions", "--dangerously-skip-permissions"],
+    chat_flags: [
+      "--allow-dangerously-skip-permissions",
+      "--dangerously-skip-permissions",
+    ],
+    env_vars: {},
     folder: ".claude",
     install_url: "https://code.claude.com/docs/en/setup",
     exclude: [".DS_Store", "settings.json"],
@@ -51,6 +57,7 @@ export const AGENT_CONFIG: Record<AgentKey, AgentConfig> = {
     name: "OpenCode",
     cmd: "opencode",
     chat_flags: [],
+    env_vars: { OPENCODE_EXPERIMENTAL_LSP_TOOL: "true" },
     folder: ".opencode",
     install_url: "https://opencode.ai",
     exclude: [
@@ -72,7 +79,16 @@ export const AGENT_CONFIG: Record<AgentKey, AgentConfig> = {
   copilot: {
     name: "GitHub Copilot CLI",
     cmd: "copilot",
-    chat_flags: ["--add-dir", ".", "--yolo", "--experimental"],
+    chat_flags: [
+      "--add-dir",
+      ".",
+      "--yolo",
+      "--experimental",
+      "--no-auto-update",
+    ],
+    env_vars: {
+      COPILOT_ALLOW_ALL: "true",
+    },
     folder: ".github",
     install_url:
       "https://github.com/github/copilot-cli?tab=readme-ov-file#installation",
@@ -154,6 +170,27 @@ export const SCM_CONFIG: Record<SourceControlType, ScmConfig> = {
 /** Commands that have SCM-specific variants */
 export const SCM_SPECIFIC_COMMANDS = ["commit"];
 
+/**
+ * SCM-variant skill names, grouped by source control type.
+ *
+ * These are the skills that `installGlobalSkills` removes from the global
+ * scope after the initial install, and that `installLocalScmSkills`
+ * re-installs per-project based on the user's selected SCM. Passed to
+ * `npx skills add --skill <name>` as explicit names (the skills CLI does
+ * not support glob patterns like `gh-*`).
+ */
+export const SCM_SKILLS_BY_TYPE: Record<SourceControlType, readonly string[]> =
+  {
+    github: ["gh-commit", "gh-create-pr"],
+    sapling: ["sl-commit", "sl-submit-diff"],
+  };
+
+/** Flat list of every SCM-variant skill across all source control types. */
+export const ALL_SCM_SKILLS: readonly string[] = [
+  ...SCM_SKILLS_BY_TYPE.github,
+  ...SCM_SKILLS_BY_TYPE.sapling,
+];
+
 /**
  * Get all SCM keys for iteration
  */

package/src/services/config/settings.ts

@@ -35,12 +35,6 @@ function globalSettingsPath(): string {
   return join(home, ".atomic", "settings.json");
 }
 
-/** Local settings path: {cwd}/.atomic/settings.json (CWD-scoped by design) */
-function localSettingsPath(): string {
-  const cwd = process.env.ATOMIC_SETTINGS_CWD ?? process.cwd();
-  return join(cwd, ".atomic", "settings.json");
-}
-
 function loadSettingsFileSync(path: string): AtomicSettings {
   try {
     if (existsSync(path)) {

package/src/services/system/skills.ts

@@ -6,14 +6,10 @@
  * locally per-project based on the user's selected SCM + active agent.
  */
 
+import { ALL_SCM_SKILLS } from "@/services/config/index.ts";
+
 const SKILLS_REPO = "https://github.com/flora131/atomic.git";
 const SKILLS_AGENTS = ["claude-code", "opencode", "github-copilot"] as const;
-const SCM_SKILLS_TO_REMOVE_GLOBALLY = [
-  "gh-commit",
-  "gh-create-pr",
-  "sl-commit",
-  "sl-submit-diff",
-] as const;
 
 interface NpxSkillsResult {
   ok: boolean;
@@ -59,7 +55,7 @@ export async function installGlobalSkills(): Promise<void> {
     throw new Error(`npx skills add failed: ${addResult.details}`);
   }
 
-  const removeSkillFlags = SCM_SKILLS_TO_REMOVE_GLOBALLY.flatMap((skill) => [
+  const removeSkillFlags = ALL_SCM_SKILLS.flatMap((skill) => [
     "--skill",
     skill,
   ]);

package/.atomic/workflows/package-lock.json

@@ -1,31 +0,0 @@
-{
-  "name": "atomic-workflows",
-  "lockfileVersion": 3,
-  "requires": true,
-  "packages": {
-    "": {
-      "name": "atomic-workflows",
-      "dependencies": {
-        "@bastani/atomic-workflows": "^0.4.56-0"
-      }
-    },
-    "node_modules/@bastani/atomic-workflows": {
-      "version": "0.4.56-0",
-      "resolved": "https://registry.npmjs.org/@bastani/atomic-workflows/-/atomic-workflows-0.4.56-0.tgz",
-      "integrity": "sha512-6JtZTcZLI5c/DnQFHiM5i4Ymm4T+iYBAtS7J/RbOBwge3kv9EEwzxYijfLhqoBt7VHnUSkWvYlcNFjNFdDwIvw==",
-      "license": "MIT",
-      "dependencies": {
-        "zod": "^4.3.6"
-      }
-    },
-    "node_modules/zod": {
-      "version": "4.3.6",
-      "resolved": "https://registry.npmjs.org/zod/-/zod-4.3.6.tgz",
-      "integrity": "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==",
-      "license": "MIT",
-      "funding": {
-        "url": "https://github.com/sponsors/colinhacks"
-      }
-    }
-  }
-}

package/.atomic/workflows/package.json

@@ -1,8 +0,0 @@
-{
-  "name": "atomic-workflows",
-  "private": true,
-  "type": "module",
-  "dependencies": {
-    "@bastani/atomic-workflows": "^0.4.56-0"
-  }
-}