@bastani/atomic 0.8.23 → 0.8.24-alpha.2

package/dist/builtin/workflows/README.md

@@ -2,7 +2,7 @@
 
 <p align="center">
   <b>Turn coding agents into reliable engineering workflows.</b><br>
-  An open-source pi extension: install it, author workflows in TypeScript, run them from chat.
+  An open-source Atomic workflow extension: install it, author workflows in TypeScript, run them from chat.
 </p>
 
 <p align="center">
@@ -507,49 +507,28 @@ Press **F2** while a workflow is running to open the DAG overlay for the active
 
 ### Execution model
 
-`@bastani/workflows` follows pi's package/extension model: pi loads `src/extension/index.ts` from the package `pi.extensions` manifest, then the extension registers the `workflow` tool, `/workflow` slash command, renderers, widget, and lifecycle hooks in-process.
+`@bastani/workflows` follows Atomic's package/extension model: Atomic loads `src/extension/index.ts` from the package `atomic.extensions` manifest, with legacy `pi.extensions` still supported, then the extension registers the `workflow` tool, `/workflow` slash command, renderers, widget, and lifecycle hooks in-process.
 
 For interactive use, run workflows through `/workflow <name> [key=value ...]` or let the LLM call the `workflow` tool. In non-interactive (`-p` / `--print` / `--mode json`) sessions, `/workflow <name> key=value` and LLM calls to the `workflow` tool remain available for deterministic workflows. The input picker and graph picker are disabled, top-level `ctx.ui.*` is unavailable, and stage child sessions exclude `ask_user_question`. Named workflow dispatch waits for the terminal run snapshot before returning.
 
 Because human input is runtime-only and workflows no longer carry a declaration-time HIL marker, headless dispatch does not reject a workflow just because its source contains `ctx.ui.*`. If you copy the HIL example above into a non-interactive session, it can pass dispatch and then fail when execution reaches the prompt with an error such as `atomic-workflows: HIL ctx.ui.confirm is unavailable because Atomic runtime did not provide a UI adapter` (the primitive name varies). Run those workflows interactively, or guard/remove runtime `ctx.ui.*` calls before using headless mode.
 
-For library or scripted use, you can also call the explicit programmatic runner:
+For library or package authoring, define reusable workflows with the builder and export the compiled definition. Hand-written objects with `__piWorkflow: true` are rejected by discovery and composition; `defineWorkflow(...).compile()` is the public authoring surface. Standalone TypeScript workflow packages can import `defineWorkflow` and `Type` from `@bastani/workflows` directly with no local `.d.ts` file or `declare module` shim. The former imperative `runWorkflow` object-form API is removed; use compiled workflow definitions with the exported `run()` / registry helpers for programmatic execution.
 
 ```ts
-import { runWorkflow, type WorkflowOptions } from "@bastani/workflows";
-
-const definition = {
-  mode: "workflow",
-  workflow: "deep-research-codebase",
-  inputs: {
-    prompt: "Investigate the auth module",
-    max_partitions: 6,
-    max_concurrency: 4,
-  },
-} as const;
-
-const options: WorkflowOptions = {};
-
-await runWorkflow(definition, options);
-
-await runWorkflow({
-  mode: "parallel",
-  task: "Audit auth changes",
-  tasks: [
-    { name: "security", task: "Review security risks" },
-    { name: "runtime", task: "Review runtime risks" },
-  ],
-  concurrency: 2,
-  reads: ["research/context.md"],
-  output: "research/auth-audit.md",
-  outputMode: "file-only",
-  worktree: false,
-  maxOutput: { lines: 2000 },
-  artifacts: true,
-});
+import { defineWorkflow, Type } from "@bastani/workflows";
+
+export default defineWorkflow("audit-auth")
+  .input("prompt", Type.String({ default: "Investigate the auth module" }))
+  .output("summary", Type.String())
+  .run(async (ctx) => {
+    const result = await ctx.task("audit", { prompt: ctx.inputs.prompt });
+    return { summary: result.text };
+  })
+  .compile();
 ```
 
-The programmatic definition object mirrors the workflow tool: named workflow runs, single-task runs, parallel `tasks`, and mixed `chain` runs accept the same direct options (`reads`, `output`, `outputMode`, `worktree`, `gitWorktreeDir`, `baseBranch`, `maxOutput`, `artifacts`, `concurrency`, `failFast`, and stage/session options such as `cwd`, `agentDir`, `model`, `tools`, `context`, and `sessionDir`). `chainDir` is chain-only: it provides the shared artifact directory for chain reads, outputs, and worktree diffs.
+The `workflow` tool still supports direct one-off `task`, `tasks`, and `chain` modes for agent-initiated orchestration. Those direct modes are runtime tool inputs, not workflow definition files.
 
 For large handoffs, prefer artifact paths over prompt injection: write stage output to `output`, set `outputMode: "file-only"` when the parent only needs the path, pass paths with `reads`, and instruct downstream agents explicitly with wording like `Read the file at <path>...`. Reserve `previous`/`{previous}` for compact summaries; avoid passing full session histories, all prior stage outputs, or every review round directly into the next model prompt. In review loops, save JSON review artifacts and pass only the latest review-round artifact, with a ledger or index file linking older rounds when needed.
 
@@ -636,13 +615,15 @@ Child workflow outputs: `output_type`, `design_system`, `artifact`, `handoff`, `
 
 ## Custom workflow discovery
 
-`@bastani/workflows` automatically discovers workflow files from three locations:
+`@bastani/workflows` discovers workflow files from project-local paths, user-global paths, configured workflow paths, installed Atomic package resources, and bundled workflows:
 
-| Location                          | Scope      | Example path                               |
-| --------------------------------- | ---------- | ------------------------------------------ |
-| `.atomic/workflows/*.ts`          | Project    | `.atomic/workflows/my-workflow.ts`         |
-| `~/.atomic/agent/workflows/*.ts`  | User       | `~/.atomic/agent/workflows/my-workflow.ts` |
-| `workflows.<name>.path` in config | Configured | see config example below                   |
+| Location                           | Scope      | Example path                                                                           |
+| ---------------------------------- | ---------- | -------------------------------------------------------------------------------------- |
+| `.atomic/workflows/*.ts`           | Project    | `.atomic/workflows/my-workflow.ts`                                                     |
+| `~/.atomic/agent/workflows/*.ts`   | User       | `~/.atomic/agent/workflows/my-workflow.ts`                                             |
+| `workflows.<name>.path` in config  | Configured | see config example below                                                               |
+| Installed Atomic package workflows | Package    | `atomic.workflows`, legacy `pi.workflows`, or `workflows/` / `workflow/` directories   |
+| Bundled workflows                  | Built-in   | shipped with `@bastani/workflows`                                                      |
 
 Config-based discovery (`~/.atomic/agent/extensions/workflow/config.json` or `.atomic/extensions/workflow/config.json`):
 
@@ -667,3 +648,19 @@ MIT — see [LICENSE](LICENSE).
 ---
 
 **Development:** see [DEV_SETUP.md](../../DEV_SETUP.md) for setup, testing, layout, and the local-extension dev loop.
+
+## Model reasoning levels
+
+Workflow stage `model` and `fallbackModels` strings support suffix-first reasoning levels using the `model_name:thinking_effort` syntax: append `:off`, `:minimal`, `:low`, `:medium`, `:high`, or `:xhigh` to the model id (for example `openai/gpt-5:high` or `anthropic/claude-haiku-4-5:off`). A suffix on a fallback candidate controls only that retry attempt, so fallback chains can mix reasoning levels.
+
+The older `thinkingLevel` stage option remains accepted as a deprecated default for candidates without a suffix. If both are present, the model suffix wins. Migrate legacy `thinkingLevel` stages by folding the effort into the model strings:
+
+```diff
+-  model: "openai/gpt-5.5",
+-  fallbackModels: ["anthropic/claude-opus-4-8"],
+-  thinkingLevel: "high",
++  model: "openai/gpt-5.5:high",
++  fallbackModels: ["anthropic/claude-opus-4-8:high"],
+```
+
+`fallbackThinkingLevels` is an optional compatibility helper aligned by index to `fallbackModels`; it is used only for fallback entries that do not already include a suffix.

package/dist/builtin/workflows/ambient.d.ts

@@ -0,0 +1,36 @@
+// AUTO-GENERATED by scripts/copy-builtin-packages.ts (issue #1208). Do not edit by hand.
+//
+// Ambient bridge so the documented bare specifier `@bastani/workflows` (and its
+// `builtin/*` submodules) type-check in installed packages that depend only on
+// @bastani/atomic. Runtime resolution is unchanged: Atomic's jiti virtual-module
+// loader still supplies the real SDK when workflow files load; these declarations
+// only affect `tsc`. Each module is declared in exactly one file to avoid
+// TS2666 / duplicate-identifier errors.
+
+declare module "@bastani/workflows" {
+	export * from "@bastani/atomic/workflows";
+}
+
+declare module "@bastani/workflows/builtin" {
+	export * from "@bastani/atomic/workflows/builtin";
+}
+
+declare module "@bastani/workflows/builtin/deep-research-codebase" {
+	export * from "@bastani/atomic/workflows/builtin/deep-research-codebase";
+	export { default } from "@bastani/atomic/workflows/builtin/deep-research-codebase";
+}
+
+declare module "@bastani/workflows/builtin/goal" {
+	export * from "@bastani/atomic/workflows/builtin/goal";
+	export { default } from "@bastani/atomic/workflows/builtin/goal";
+}
+
+declare module "@bastani/workflows/builtin/open-claude-design" {
+	export * from "@bastani/atomic/workflows/builtin/open-claude-design";
+	export { default } from "@bastani/atomic/workflows/builtin/open-claude-design";
+}
+
+declare module "@bastani/workflows/builtin/ralph" {
+	export * from "@bastani/atomic/workflows/builtin/ralph";
+	export { default } from "@bastani/atomic/workflows/builtin/ralph";
+}

package/dist/builtin/workflows/builtin/deep-research-codebase.d.ts

@@ -0,0 +1,35 @@
+import type { WorkflowDefinition, WorkflowInputValues, WorkflowOutputValues } from "../src/authoring.js";
+
+export type DeepResearchCodebaseWorkflowInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly max_partitions: number;
+  readonly max_concurrency: number;
+};
+
+export type DeepResearchCodebaseWorkflowRunInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly max_partitions?: number;
+  readonly max_concurrency?: number;
+};
+
+export type DeepResearchCodebaseWorkflowOutputs = WorkflowOutputValues & {
+  readonly result?: string;
+  readonly findings?: string;
+  readonly research_doc_path?: string;
+  readonly artifact_dir?: string;
+  readonly manifest_path?: string;
+  readonly partitions?: string[];
+  readonly explorer_count?: number;
+  readonly specialist_count?: number;
+  readonly max_concurrency?: number;
+  readonly history?: string;
+};
+
+export type DeepResearchCodebaseWorkflowDefinition = WorkflowDefinition<
+  DeepResearchCodebaseWorkflowInputs,
+  DeepResearchCodebaseWorkflowOutputs,
+  DeepResearchCodebaseWorkflowRunInputs
+>;
+
+declare const workflow: DeepResearchCodebaseWorkflowDefinition;
+export default workflow;

package/dist/builtin/workflows/builtin/deep-research-codebase.ts

@@ -15,7 +15,6 @@ import { defineWorkflow } from "../src/workflows/define-workflow.js";
 import { Type } from "typebox";
 import type {
   WorkflowOutputMode,
-  WorkflowOutputValues,
   WorkflowTaskResult,
   WorkflowTaskStep,
 } from "../src/shared/types.js";
@@ -30,7 +29,7 @@ const GIT_LS_FILES_TIMEOUT_MS = 2_000;
 
 type PromptSection = readonly [tag: string, content: string];
 
-interface DeepResearchCodebaseResult extends WorkflowOutputValues {
+interface DeepResearchCodebaseResult {
   readonly result: string;
   readonly findings: string;
   readonly research_doc_path: string;
@@ -413,26 +412,24 @@ export default defineWorkflow("deep-research-codebase")
     );
 
     const plannerModelConfig = {
-      model: "openai/gpt-5.5",
+      model: "openai/gpt-5.5:xhigh",
       fallbackModels: [
-        "openai-codex/gpt-5.5",
-        "github-copilot/gpt-5.5",
-        "anthropic/claude-opus-4-8",
-        "github-copilot/claude-opus-4.7",
+        "openai-codex/gpt-5.5:xhigh",
+        "github-copilot/gpt-5.5:xhigh",
+        "anthropic/claude-opus-4-8:xhigh",
+        "github-copilot/claude-opus-4.8:medium",
       ],
-      thinkingLevel: "high" as const,
       excludedTools: ["ask_user_question"],
     };
 
     const explorerModelConfig = {
-      model: "openai/gpt-5.4-mini",
+      model: "openai/gpt-5.4-mini:low",
       fallbackModels: [
-        "openai-codex/gpt-5.4-mini",
-        "github-copilot/gpt-5.4-mini",
-        "anthropic/claude-haiku-4-5",
-        "github-copilot/claude-haiku-4.5",
+        "openai-codex/gpt-5.4-mini:low",
+        "github-copilot/gpt-5.4-mini:low",
+        "anthropic/claude-haiku-4-5:low",
+        "github-copilot/claude-haiku-4.5:low",
       ],
-      thinkingLevel: "low" as const,
       excludedTools: ["ask_user_question"],
     };
 

package/dist/builtin/workflows/builtin/goal.d.ts

@@ -0,0 +1,46 @@
+import type { WorkflowDefinition, WorkflowInputValues, WorkflowOutputValues } from "../src/authoring.js";
+
+export type GoalWorkflowStatus = "active" | "complete" | "blocked" | "needs_human";
+
+export type GoalWorkflowReceipt = {
+  readonly turn: number;
+  readonly stage: string;
+  readonly artifact_path: string;
+  readonly summary: string;
+};
+
+export type GoalWorkflowInputs = WorkflowInputValues & {
+  readonly objective: string;
+  readonly max_turns: number;
+  readonly base_branch: string;
+};
+
+export type GoalWorkflowRunInputs = WorkflowInputValues & {
+  readonly objective: string;
+  readonly max_turns?: number;
+  readonly base_branch?: string;
+};
+
+export type GoalWorkflowOutputs = WorkflowOutputValues & {
+  readonly result?: string;
+  readonly status?: GoalWorkflowStatus;
+  readonly approved?: boolean;
+  readonly goal_id?: string;
+  readonly objective?: string;
+  readonly ledger_path?: string;
+  readonly turns_completed?: number;
+  readonly iterations_completed?: number;
+  readonly receipts?: GoalWorkflowReceipt[];
+  readonly remaining_work?: string;
+  readonly review_report?: string;
+  readonly review_report_path?: string;
+};
+
+export type GoalWorkflowDefinition = WorkflowDefinition<
+  GoalWorkflowInputs,
+  GoalWorkflowOutputs,
+  GoalWorkflowRunInputs
+>;
+
+declare const workflow: GoalWorkflowDefinition;
+export default workflow;

package/dist/builtin/workflows/builtin/goal.ts

@@ -1026,26 +1026,24 @@ export default defineWorkflow("goal")
     const { ledger, ledgerPath, artifactDir } = await createGoalLedger(objective);
 
     const workerModelConfig = {
-      model: "openai/gpt-5.5",
+      model: "openai/gpt-5.5:medium",
       fallbackModels: [
-        "openai-codex/gpt-5.5",
-        "github-copilot/gpt-5.5",
-        "anthropic/claude-sonnet-4-7",
-        "github-copilot/claude-sonnet-4.7",
+        "openai-codex/gpt-5.5:medium",
+        "github-copilot/gpt-5.5:medium",
+        "anthropic/claude-sonnet-4-8:medium",
+        "github-copilot/claude-sonnet-4.8:medium",
       ],
-      thinkingLevel: "low" as const,
       tools: goalRunnerTools,
     };
 
     const reviewerModelConfig = {
-      model: "openai/gpt-5.5",
+      model: "openai/gpt-5.5:xhigh",
       fallbackModels: [
-        "openai-codex/gpt-5.5",
-        "github-copilot/gpt-5.5",
-        "anthropic/claude-sonnet-4-7",
-        "github-copilot/claude-sonnet-4.7",
+        "openai-codex/gpt-5.5:xhigh",
+        "github-copilot/gpt-5.5:xhigh",
+        "anthropic/claude-sonnet-4-8:xhigh",
+        "github-copilot/claude-sonnet-4.8:medium",
       ],
-      thinkingLevel: "high" as const,
       tools: [...goalRunnerTools, reviewDecisionTool.name],
       customTools: [reviewDecisionTool],
     };

package/dist/builtin/workflows/builtin/index.d.ts

@@ -0,0 +1,136 @@
+import type { WorkflowDefinition, WorkflowInputValues, WorkflowOutputValues } from "../src/authoring.js";
+
+export type DeepResearchCodebaseWorkflowInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly max_partitions: number;
+  readonly max_concurrency: number;
+};
+export type DeepResearchCodebaseWorkflowRunInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly max_partitions?: number;
+  readonly max_concurrency?: number;
+};
+export type DeepResearchCodebaseWorkflowOutputs = WorkflowOutputValues & {
+  readonly result?: string;
+  readonly findings?: string;
+  readonly research_doc_path?: string;
+  readonly artifact_dir?: string;
+  readonly manifest_path?: string;
+  readonly partitions?: string[];
+  readonly explorer_count?: number;
+  readonly specialist_count?: number;
+  readonly max_concurrency?: number;
+  readonly history?: string;
+};
+export type DeepResearchCodebaseWorkflowDefinition = WorkflowDefinition<
+  DeepResearchCodebaseWorkflowInputs,
+  DeepResearchCodebaseWorkflowOutputs,
+  DeepResearchCodebaseWorkflowRunInputs
+>;
+
+export type GoalWorkflowStatus = "active" | "complete" | "blocked" | "needs_human";
+export type GoalWorkflowReceipt = {
+  readonly turn: number;
+  readonly stage: string;
+  readonly artifact_path: string;
+  readonly summary: string;
+};
+export type GoalWorkflowInputs = WorkflowInputValues & {
+  readonly objective: string;
+  readonly max_turns: number;
+  readonly base_branch: string;
+};
+export type GoalWorkflowRunInputs = WorkflowInputValues & {
+  readonly objective: string;
+  readonly max_turns?: number;
+  readonly base_branch?: string;
+};
+export type GoalWorkflowOutputs = WorkflowOutputValues & {
+  readonly result?: string;
+  readonly status?: GoalWorkflowStatus;
+  readonly approved?: boolean;
+  readonly goal_id?: string;
+  readonly objective?: string;
+  readonly ledger_path?: string;
+  readonly turns_completed?: number;
+  readonly iterations_completed?: number;
+  readonly receipts?: GoalWorkflowReceipt[];
+  readonly remaining_work?: string;
+  readonly review_report?: string;
+  readonly review_report_path?: string;
+};
+export type GoalWorkflowDefinition = WorkflowDefinition<
+  GoalWorkflowInputs,
+  GoalWorkflowOutputs,
+  GoalWorkflowRunInputs
+>;
+
+export type RalphWorkflowInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly max_loops: number;
+  readonly base_branch: string;
+  readonly git_worktree_dir: string;
+};
+export type RalphWorkflowRunInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly max_loops?: number;
+  readonly base_branch?: string;
+  readonly git_worktree_dir?: string;
+};
+export type RalphWorkflowOutputs = WorkflowOutputValues & {
+  readonly result?: string;
+  readonly plan?: string;
+  readonly plan_path?: string;
+  readonly implementation_notes_path?: string;
+  readonly pr_report?: string;
+  readonly approved?: boolean;
+  readonly iterations_completed?: number;
+  readonly review_report?: string;
+  readonly review_report_path?: string;
+};
+export type RalphWorkflowDefinition = WorkflowDefinition<
+  RalphWorkflowInputs,
+  RalphWorkflowOutputs,
+  RalphWorkflowRunInputs
+>;
+
+export type OpenClaudeDesignOutputType = "prototype" | "wireframe" | "page" | "component" | "theme" | "tokens";
+export type OpenClaudeDesignWorkflowInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly reference?: string;
+  readonly output_type: OpenClaudeDesignOutputType;
+  readonly design_system?: string;
+  readonly max_refinements: number;
+};
+export type OpenClaudeDesignWorkflowRunInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly reference?: string;
+  readonly output_type?: OpenClaudeDesignOutputType;
+  readonly design_system?: string;
+  readonly max_refinements?: number;
+};
+export type OpenClaudeDesignWorkflowOutputs = WorkflowOutputValues & {
+  readonly output_type?: string;
+  readonly design_system?: string;
+  readonly artifact?: string;
+  readonly handoff?: string;
+  readonly approved_for_export?: boolean;
+  readonly refinements_completed?: number;
+  readonly import_context?: string;
+  readonly run_id?: string;
+  readonly artifact_dir?: string;
+  readonly preview_path?: string;
+  readonly preview_file_url?: string;
+  readonly spec_path?: string;
+  readonly spec_file_url?: string;
+};
+export type OpenClaudeDesignWorkflowDefinition = WorkflowDefinition<
+  OpenClaudeDesignWorkflowInputs,
+  OpenClaudeDesignWorkflowOutputs,
+  OpenClaudeDesignWorkflowRunInputs
+>;
+
+export declare const deepResearchCodebase: DeepResearchCodebaseWorkflowDefinition;
+export declare const goal: GoalWorkflowDefinition;
+export declare const ralph: RalphWorkflowDefinition;
+export declare const openClaudeDesign: OpenClaudeDesignWorkflowDefinition;

package/dist/builtin/workflows/builtin/open-claude-design.d.ts

@@ -0,0 +1,44 @@
+import type { WorkflowDefinition, WorkflowInputValues, WorkflowOutputValues } from "../src/authoring.js";
+
+export type OpenClaudeDesignOutputType = "prototype" | "wireframe" | "page" | "component" | "theme" | "tokens";
+
+export type OpenClaudeDesignWorkflowInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly reference?: string;
+  readonly output_type: OpenClaudeDesignOutputType;
+  readonly design_system?: string;
+  readonly max_refinements: number;
+};
+
+export type OpenClaudeDesignWorkflowRunInputs = WorkflowInputValues & {
+  readonly prompt: string;
+  readonly reference?: string;
+  readonly output_type?: OpenClaudeDesignOutputType;
+  readonly design_system?: string;
+  readonly max_refinements?: number;
+};
+
+export type OpenClaudeDesignWorkflowOutputs = WorkflowOutputValues & {
+  readonly output_type?: string;
+  readonly design_system?: string;
+  readonly artifact?: string;
+  readonly handoff?: string;
+  readonly approved_for_export?: boolean;
+  readonly refinements_completed?: number;
+  readonly import_context?: string;
+  readonly run_id?: string;
+  readonly artifact_dir?: string;
+  readonly preview_path?: string;
+  readonly preview_file_url?: string;
+  readonly spec_path?: string;
+  readonly spec_file_url?: string;
+};
+
+export type OpenClaudeDesignWorkflowDefinition = WorkflowDefinition<
+  OpenClaudeDesignWorkflowInputs,
+  OpenClaudeDesignWorkflowOutputs,
+  OpenClaudeDesignWorkflowRunInputs
+>;
+
+declare const workflow: OpenClaudeDesignWorkflowDefinition;
+export default workflow;