@bastani/atomic-workflows 0.4.27-3

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@bastani/atomic-workflows",
+  "version": "0.4.27-3",
+  "description": "Workflow SDK for defining multi-agent workflows in Atomic CLI",
+  "type": "module",
+  "license": "BUSL-1.1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flora131/atomic.git",
+    "directory": "packages/workflow-sdk"
+  },
+  "keywords": [
+    "workflow",
+    "dsl",
+    "coding-agents",
+    "atomic",
+    "bun"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint --config=../../oxlint.json src",
+    "lint:fix": "oxlint --config=../../oxlint.json --fix src",
+    "test": "bun test ./tests/**/*.test.ts"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.11",
+    "lefthook": "^2.1.4",
+    "oxlint": "^1.56.0",
+    "typescript": "^5.9.3",
+    "typescript-language-server": "^5.1.3"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  }
+}

package/src/define-workflow.ts

@@ -0,0 +1,251 @@
+/**
+ * Chainable Workflow Builder (SDK)
+ *
+ * Lightweight version of the workflow builder for end-user workflow files.
+ * Records an ordered instruction list and returns a branded "blueprint"
+ * from `.compile()` that the Atomic CLI binary compiles at load time.
+ *
+ * Usage:
+ * ```ts
+ * import { defineWorkflow } from "@bastani/atomic-workflows";
+ *
+ * export default defineWorkflow({
+ *     name: "my-workflow",
+ *     description: "A workflow that does X",
+ *     globalState: {
+ *       count: { default: 0, reducer: "sum" },
+ *       items: { default: () => [], reducer: "concat" },
+ *     },
+ *   })
+ *   .version("1.0.0")
+ *   .argumentHint("<file-path>")
+ *   .stage({ name: "planner", agent: "planner", ... })
+ *   .if(ctx => ctx.stageOutputs.has("planner"))
+ *     .stage({ name: "executor", agent: "executor", ... })
+ *   .else()
+ *     .stage({ name: "fallback", agent: "fallback", ... })
+ *   .endIf()
+ *   .compile();
+ * ```
+ */
+
+import type {
+  BaseState,
+  StageContext,
+  StageOptions,
+  ToolOptions,
+  AskUserQuestionOptions,
+  LoopOptions,
+  StateFieldOptions,
+  WorkflowOptions,
+  CompiledWorkflow,
+} from "./types.ts";
+
+// ---------------------------------------------------------------------------
+// Instruction — internal discriminated union recorded by the builder
+// ---------------------------------------------------------------------------
+
+type Instruction =
+  | { readonly type: "stage"; readonly id: string; readonly config: StageOptions }
+  | { readonly type: "tool"; readonly id: string; readonly config: ToolOptions }
+  | { readonly type: "askUserQuestion"; readonly id: string; readonly config: AskUserQuestionOptions }
+  | { readonly type: "if"; readonly condition: (ctx: StageContext) => boolean }
+  | { readonly type: "elseIf"; readonly condition: (ctx: StageContext) => boolean }
+  | { readonly type: "else" }
+  | { readonly type: "endIf" }
+  | { readonly type: "loop"; readonly config: LoopOptions }
+  | { readonly type: "endLoop" }
+  | { readonly type: "break"; readonly condition?: () => (state: BaseState) => boolean };
+
+// ---------------------------------------------------------------------------
+// Blueprint — the data structure carried by the branded CompiledWorkflow
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal blueprint data attached to the branded CompiledWorkflow.
+ * The Atomic CLI binary extracts this to compile the workflow at load time.
+ */
+export interface WorkflowBlueprint {
+  readonly name: string;
+  readonly description: string;
+  readonly instructions: readonly Instruction[];
+  readonly version?: string;
+  readonly argumentHint?: string;
+  readonly stateSchema?: Record<string, StateFieldOptions>;
+}
+
+// ---------------------------------------------------------------------------
+// Entry Point
+// ---------------------------------------------------------------------------
+
+export function defineWorkflow(options: WorkflowOptions): WorkflowBuilder {
+  return new WorkflowBuilder(options);
+}
+
+// ---------------------------------------------------------------------------
+// WorkflowBuilder
+// ---------------------------------------------------------------------------
+
+export class WorkflowBuilder {
+  readonly name: string;
+  readonly description: string;
+  readonly instructions: Instruction[] = [];
+
+  private _version: string | undefined;
+  private _argumentHint: string | undefined;
+  private readonly _globalState: Record<string, StateFieldOptions> | undefined;
+  private loopDepth: number = 0;
+  private nodeNames: Set<string> = new Set();
+
+  constructor(options: WorkflowOptions) {
+    this.name = options.name;
+    this.description = options.description;
+    this._globalState = options.globalState;
+  }
+
+  // -- Metadata -------------------------------------------------------------
+
+  version(v: string): this {
+    this._version = v;
+    return this;
+  }
+
+  argumentHint(hint: string): this {
+    this._argumentHint = hint;
+    return this;
+  }
+
+  // -- Linear flow ----------------------------------------------------------
+
+  stage(options: StageOptions): this {
+    if (this.nodeNames.has(options.name)) {
+      throw new Error(
+        `Duplicate node name: "${options.name}". Each node must have a unique name within the workflow.`,
+      );
+    }
+    this.nodeNames.add(options.name);
+    this.instructions.push({ type: "stage", id: options.name, config: options });
+    return this;
+  }
+
+  tool(options: ToolOptions): this {
+    if (this.nodeNames.has(options.name)) {
+      throw new Error(
+        `Duplicate node name: "${options.name}". Each node must have a unique name within the workflow.`,
+      );
+    }
+    this.nodeNames.add(options.name);
+    this.instructions.push({ type: "tool", id: options.name, config: options });
+    return this;
+  }
+
+  askUserQuestion(options: AskUserQuestionOptions): this {
+    if (this.nodeNames.has(options.name)) {
+      throw new Error(
+        `Duplicate node name: "${options.name}". Each node must have a unique name within the workflow.`,
+      );
+    }
+    this.nodeNames.add(options.name);
+    this.instructions.push({ type: "askUserQuestion", id: options.name, config: options });
+    return this;
+  }
+
+  // -- Conditional branching ------------------------------------------------
+
+  if(condition: (ctx: StageContext) => boolean): this {
+    this.instructions.push({ type: "if", condition });
+    return this;
+  }
+
+  elseIf(condition: (ctx: StageContext) => boolean): this {
+    this.instructions.push({ type: "elseIf", condition });
+    return this;
+  }
+
+  else(): this {
+    this.instructions.push({ type: "else" });
+    return this;
+  }
+
+  endIf(): this {
+    this.instructions.push({ type: "endIf" });
+    return this;
+  }
+
+  // -- Bounded loops --------------------------------------------------------
+
+  loop(options?: LoopOptions): this {
+    this.loopDepth++;
+    this.instructions.push({ type: "loop", config: options ?? {} });
+    return this;
+  }
+
+  endLoop(): this {
+    if (this.loopDepth === 0) {
+      throw new Error("endLoop() called without a matching loop()");
+    }
+    this.loopDepth--;
+    this.instructions.push({ type: "endLoop" });
+    return this;
+  }
+
+  break(condition?: () => (state: BaseState) => boolean): this {
+    if (this.loopDepth === 0) {
+      throw new Error("break() can only be used inside a loop() block");
+    }
+    this.instructions.push({ type: "break", condition });
+    return this;
+  }
+
+  // -- Terminal -------------------------------------------------------------
+
+  /**
+   * Compile the recorded instructions into a `CompiledWorkflow`.
+   *
+   * Returns a branded "blueprint" object that the Atomic CLI binary
+   * detects and compiles at load time. The blueprint carries the
+   * recorded instructions and metadata — no heavy compilation runs
+   * in the SDK.
+   */
+  compile(): CompiledWorkflow {
+    return {
+      __compiledWorkflow: true,
+      name: this.name,
+      description: this.description,
+      __blueprint: {
+        name: this.name,
+        description: this.description,
+        instructions: this.instructions,
+        version: this._version,
+        argumentHint: this._argumentHint,
+        stateSchema: this.getStateSchema(),
+      },
+    } as CompiledWorkflow;
+  }
+
+  // -- Accessors (used by the binary's compiler via blueprint) ---------------
+
+  getVersion(): string | undefined {
+    return this._version;
+  }
+
+  getArgumentHint(): string | undefined {
+    return this._argumentHint;
+  }
+
+  getStateSchema(): Record<string, StateFieldOptions> | undefined {
+    const loopStates = this.instructions
+      .filter((i): i is Extract<Instruction, { type: "loop" }> => i.type === "loop")
+      .map((i) => i.config.loopState)
+      .filter((s): s is Record<string, StateFieldOptions> => s !== undefined);
+
+    if (!this._globalState && loopStates.length === 0) {
+      return undefined;
+    }
+
+    return {
+      ...this._globalState,
+      ...Object.assign({}, ...loopStates),
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+/**
+ * @bastani/atomic-workflows — Workflow SDK
+ *
+ * Lightweight SDK for defining multi-agent workflows that run in the
+ * Atomic CLI. Install this package in your project and create workflow
+ * files in `.atomic/workflows/`.
+ *
+ * @example
+ * ```ts
+ * import { defineWorkflow } from "@bastani/atomic-workflows";
+ *
+ * export default defineWorkflow({
+ *     name: "my-workflow",
+ *     description: "A workflow that does X",
+ *   })
+ *   .stage({
+ *     name: "planner",
+ *     agent: "planner",
+ *     description: "Plans the work",
+ *     prompt: (ctx) => `Plan this: ${ctx.userPrompt}`,
+ *     outputMapper: (response) => ({ plan: response }),
+ *   })
+ *   .compile();
+ * ```
+ */
+
+export { defineWorkflow, WorkflowBuilder } from "./define-workflow.ts";
+export type { WorkflowBlueprint } from "./define-workflow.ts";
+export type {
+  BaseState,
+  ExecutionContext,
+  ExecutionError,
+  ErrorAction,
+  GraphConfig,
+  ModelSpec,
+  NodeExecuteFn,
+  NodeId,
+  NodeResult,
+  RetryConfig,
+  Signal,
+  SignalData,
+  StageContext,
+  StageOutput,
+  StageOutputStatus,
+  TaskItem,
+  ContextPressureSnapshot,
+  ContextPressureLevel,
+  ContinuationRecord,
+  AccumulatedContextPressure,
+  SessionConfig,
+  StageOptions,
+  ToolOptions,
+  AskUserQuestionConfig,
+  AskUserQuestionOptions,
+  LoopOptions,
+  StateFieldOptions,
+  WorkflowOptions,
+  CompiledWorkflow,
+} from "./types.ts";

package/src/types.ts

@@ -0,0 +1,317 @@
+/**
+ * Workflow SDK Type Definitions
+ *
+ * All user-facing types for defining workflows with the chainable DSL.
+ * These types mirror the Atomic CLI runtime types so that user workflow
+ * files get full IDE support (autocomplete, type checking) without
+ * depending on the full CLI codebase.
+ */
+
+import type { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Graph Core
+// ---------------------------------------------------------------------------
+
+export type NodeId = string;
+
+export type ModelSpec = string | "inherit";
+
+export type Signal =
+  | "context_window_warning"
+  | "checkpoint"
+  | "human_input_required"
+  | "debug_report_generated";
+
+export interface SignalData {
+  type: Signal;
+  message?: string;
+  data?: Record<string, unknown>;
+}
+
+/**
+ * Base workflow state. All workflow state extends this shape.
+ * The `outputs` record is keyed by node ID and holds each node's output.
+ */
+export interface BaseState {
+  executionId: string;
+  lastUpdated: string;
+  outputs: Record<NodeId, unknown>;
+}
+
+export interface ExecutionError {
+  nodeId: NodeId;
+  error: Error | string;
+  timestamp: string;
+  attempt: number;
+}
+
+export interface RetryConfig {
+  maxAttempts: number;
+  backoffMs: number;
+  backoffMultiplier: number;
+  retryOn?: (error: Error) => boolean;
+}
+
+export type ErrorAction<TState extends BaseState = BaseState> =
+  | { action: "retry"; delay?: number }
+  | { action: "skip"; fallbackState?: Partial<TState> }
+  | { action: "abort"; error?: Error }
+  | { action: "goto"; nodeId: NodeId };
+
+// ---------------------------------------------------------------------------
+// Graph Runtime
+// ---------------------------------------------------------------------------
+
+/**
+ * Result returned from a graph node execution.
+ */
+export interface NodeResult<TState extends BaseState = BaseState> {
+  stateUpdate?: Partial<TState>;
+  goto?: NodeId | NodeId[];
+  signals?: SignalData[];
+}
+
+/**
+ * Graph configuration for workflow execution.
+ */
+export interface GraphConfig<TState extends BaseState = BaseState> {
+  maxConcurrency?: number;
+  timeout?: number;
+  contextWindowThreshold?: number;
+  autoCheckpoint?: boolean;
+  metadata?: Record<string, unknown>;
+  defaultModel?: ModelSpec;
+  outputSchema?: z.ZodType<TState>;
+}
+
+/**
+ * Execute function signature for graph nodes.
+ */
+export type NodeExecuteFn<TState extends BaseState = BaseState> = (
+  context: ExecutionContext<TState>,
+) => Promise<NodeResult<TState>>;
+
+// ---------------------------------------------------------------------------
+// Execution Context (passed to tool execute functions)
+// ---------------------------------------------------------------------------
+
+/**
+ * Context provided to tool node `execute` functions.
+ *
+ * The most commonly used field is `state`, which gives access to the
+ * current workflow state including outputs from prior nodes.
+ */
+export interface ExecutionContext<TState extends BaseState = BaseState> {
+  state: TState;
+  config: GraphConfig<TState>;
+  errors: ExecutionError[];
+  abortSignal?: AbortSignal;
+  emit?: (type: string, data?: Record<string, unknown>) => void;
+  getNodeOutput?: (nodeId: NodeId) => unknown;
+  model?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Conductor Types (passed to stage prompt/condition callbacks)
+// ---------------------------------------------------------------------------
+
+export type StageOutputStatus = "completed" | "interrupted" | "error";
+
+export type ContextPressureLevel = "normal" | "elevated" | "critical";
+
+export interface ContextPressureSnapshot {
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly maxTokens: number;
+  readonly usagePercentage: number;
+  readonly level: ContextPressureLevel;
+  readonly timestamp: string;
+}
+
+export interface ContinuationRecord {
+  readonly stageId: string;
+  readonly continuationIndex: number;
+  readonly triggerSnapshot: ContextPressureSnapshot;
+  readonly partialResponse: string;
+  readonly timestamp: string;
+}
+
+export interface StageOutput {
+  readonly stageId: string;
+  readonly rawResponse: string;
+  readonly parsedOutput?: unknown;
+  readonly status: StageOutputStatus;
+  readonly error?: string;
+  readonly contextUsage?: ContextPressureSnapshot;
+  readonly continuations?: readonly ContinuationRecord[];
+  readonly originalByteLength?: number;
+}
+
+export interface AccumulatedContextPressure {
+  readonly totalInputTokens: number;
+  readonly totalOutputTokens: number;
+  readonly totalContinuations: number;
+  readonly stageSnapshots: ReadonlyMap<string, ContextPressureSnapshot>;
+  readonly continuations: readonly ContinuationRecord[];
+}
+
+/**
+ * Task item in the workflow task list.
+ * Populated after the planner stage and updated throughout execution.
+ */
+export interface TaskItem {
+  id?: string;
+  description: string;
+  status: string;
+  summary: string;
+  blockedBy?: string[];
+}
+
+/**
+ * Read-only context provided to stage prompt builders and conditional
+ * callbacks (`.if()`, `.elseIf()`).
+ */
+export interface StageContext {
+  readonly userPrompt: string;
+  readonly stageOutputs: ReadonlyMap<string, StageOutput>;
+  readonly tasks: readonly TaskItem[];
+  readonly abortSignal: AbortSignal;
+  readonly contextPressure?: AccumulatedContextPressure;
+}
+
+// ---------------------------------------------------------------------------
+// Session Configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * Agent session configuration overrides.
+ * Used in `StageOptions.sessionConfig` to customize per-stage sessions.
+ */
+export interface SessionConfig {
+  model?: string;
+  sessionId?: string;
+  systemPrompt?: string;
+  additionalInstructions?: string;
+  tools?: string[];
+  permissionMode?: "auto" | "prompt" | "deny" | "bypass";
+  maxBudgetUsd?: number;
+  maxTurns?: number;
+  reasoningEffort?: string;
+  maxThinkingTokens?: number;
+}
+
+// ---------------------------------------------------------------------------
+// DSL Stage Options
+// ---------------------------------------------------------------------------
+
+export interface StageOptions {
+  readonly name: string;
+  readonly agent?: string | null;
+  readonly description: string;
+  readonly prompt: (context: StageContext) => string;
+  readonly outputMapper: (response: string) => Record<string, unknown>;
+  readonly sessionConfig?: Partial<SessionConfig>;
+  readonly maxOutputBytes?: number;
+  readonly reads?: string[];
+  readonly outputs?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// DSL Tool Options
+// ---------------------------------------------------------------------------
+
+export interface ToolOptions {
+  readonly name: string;
+  readonly execute: (
+    context: ExecutionContext<BaseState>,
+  ) => Promise<Record<string, unknown>>;
+  readonly description?: string;
+  readonly reads?: string[];
+  readonly outputs?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// DSL Ask User Question Options
+// ---------------------------------------------------------------------------
+
+export interface AskUserQuestionConfig {
+  readonly question: string;
+  readonly header?: string;
+  readonly options?: ReadonlyArray<{
+    readonly label: string;
+    readonly description?: string;
+  }>;
+  readonly multiSelect?: boolean;
+}
+
+export interface AskUserQuestionOptions {
+  readonly name: string;
+  readonly question:
+    | AskUserQuestionConfig
+    | ((state: BaseState) => AskUserQuestionConfig);
+  readonly description?: string;
+  readonly onAnswer?: (answer: string | string[]) => Record<string, unknown>;
+  readonly reads?: string[];
+  readonly outputs?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// DSL Loop Options
+// ---------------------------------------------------------------------------
+
+export interface LoopOptions {
+  readonly maxCycles?: number;
+  readonly loopState?: Record<string, StateFieldOptions>;
+}
+
+// ---------------------------------------------------------------------------
+// State Field Options
+// ---------------------------------------------------------------------------
+
+export interface StateFieldOptions<T = unknown> {
+  readonly default: T | (() => T);
+  readonly reducer?:
+    | "replace"
+    | "concat"
+    | "merge"
+    | "mergeById"
+    | "max"
+    | "min"
+    | "sum"
+    | "or"
+    | "and"
+    | ((current: T, update: T) => T);
+  readonly key?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Workflow Options (passed to defineWorkflow)
+// ---------------------------------------------------------------------------
+
+export interface WorkflowOptions {
+  readonly name: string;
+  readonly description: string;
+  readonly globalState?: Record<string, StateFieldOptions>;
+}
+
+// ---------------------------------------------------------------------------
+// Compiled Workflow (opaque return type of .compile())
+// ---------------------------------------------------------------------------
+
+/**
+ * Opaque branded type returned by `.compile()`.
+ *
+ * Export this value as the default export (or a named export) from your
+ * workflow file. The Atomic CLI binary detects the brand and compiles
+ * the workflow at load time.
+ *
+ * ```ts
+ * export default defineWorkflow({ ... }).stage({ ... }).compile();
+ * ```
+ */
+export interface CompiledWorkflow {
+  readonly __compiledWorkflow: true;
+  readonly name: string;
+  readonly description: string;
+}