@bastani/atomic 0.8.4 → 0.8.5-0

package/dist/builtin/workflows/skills/workflow/references/sdk-authoring.md

@@ -4,12 +4,51 @@ Use this when creating or editing user-facing workflow definition files for `@ba
 
 ## Where workflow files live
 
-Pi/Atomic discovers workflows from these user-facing locations:
+Atomic/pi discovers workflows from these user-facing locations, in this override order:
 
-- Project-local: `.atomic/workflows/*.{ts,js,mjs,cjs}` inside a project. Legacy `.pi/workflows/` is also checked for compatibility.
-- User-global: `~/.atomic/agent/workflows/*.{ts,js,mjs,cjs}` for workflows shared across projects. Legacy `~/.pi/agent/workflows/` is also checked.
-- Configured directories: `.atomic/extensions/workflow/config.json` or `~/.atomic/agent/extensions/workflow/config.json` can add `workflows.<name>.path` entries; legacy `.pi/...` config paths are also considered.
-- Package-provided: a pi package can expose bundled workflow directories through `package.json` under `pi.builtin`.
+1. Configured project files from `.atomic/extensions/workflow/config.json` (`workflows.<name>.path`). Legacy `.pi/...` config paths are also considered.
+2. Project-local files in `.atomic/workflows/*.{ts,js,mjs,cjs}`. Legacy `.pi/workflows/` is also checked.
+3. Configured global files from `~/.atomic/agent/extensions/workflow/config.json`. Legacy `~/.pi/...` config paths are also considered.
+4. User-global files in `~/.atomic/agent/workflows/*.{ts,js,mjs,cjs}`. Legacy `~/.pi/agent/workflows/` is also checked.
+5. Package-provided files from installed Atomic/pi packages.
+6. Bundled workflows shipped with `@bastani/workflows`.
+
+A workflow module may export one default workflow definition and/or named workflow definitions; discovery checks the default export first, then named exports.
+
+Configured workflow paths live in extension config. Project config relative paths resolve from the project root; global config relative paths resolve under the user agent directory (`<home>/.atomic/agent`). Project entries override global entries with the same key.
+
+```json
+{
+  "workflows": {
+    "team": { "path": "./workflows/team.ts" }
+  },
+  "defaultConcurrency": 4,
+  "maxDepth": 4,
+  "persistRuns": true,
+  "statusFile": false,
+  "resumeInFlight": "ask"
+}
+```
+
+Runtime config defaults are `defaultConcurrency: 4`, `maxDepth: 4`, `persistRuns: true`, `statusFile: false`, and `resumeInFlight: "ask"`. Invalid JSON or invalid shapes produce `CONFIG_INVALID` diagnostics; missing config files are ignored. When `statusFile` is enabled, the derived status file defaults under `.atomic/workflows/status.json` for the project.
+
+Package-provided workflows can be exposed either explicitly through host package metadata or implicitly through a conventional directory:
+
+```json
+{
+  "name": "my-atomic-workflows",
+  "keywords": ["pi-package"],
+  "atomic": {
+    "extensions": ["./src/index.ts"],
+    "workflows": ["./workflows"]
+  }
+}
+```
+
+- For new Atomic package examples, prefer app-name keys such as `atomic.workflows` and `atomic.extensions` when supported by the host.
+- `pi.workflows` and `pi.extensions` remain supported for pi compatibility and existing first-party package metadata.
+- If no manifest declares workflows, conventional `workflows/` is auto-discovered. Singular `workflow/` is also accepted.
+- App-level config similarly prefers `<appName>Config` (for example `atomicConfig`) where available; legacy `piConfig` is still read as a shim.
 
 In a normal consumer project, import from the package:
 
@@ -42,7 +81,7 @@ export default defineWorkflow("my-workflow")
     const reviews = await ctx.parallel([
       { name: "quality", prompt: "Inspect quality risks using this context: {previous}", previous: scout },
       { name: "runtime", prompt: "Inspect runtime concerns using this context: {previous}", previous: scout },
-    ]);
+    ], { concurrency: 2 });
 
     const final = await ctx.task("synthesis", {
       prompt: "Synthesize findings and recommend next steps.",
@@ -65,6 +104,19 @@ export default defineWorkflow("my-workflow")
 - `.run(fn)` defines the workflow body.
 - `.compile()` returns the workflow definition for discovery.
 
+## Anti-pattern: no-stage workflows
+
+Do not create workflows whose `run` body only executes deterministic code and returns a value without creating a tracked workflow stage. That shape defeats the purpose of the workflow runtime: there is no graph node to inspect, attach to, interrupt, resume, or render.
+
+Discovery rejects no-stage workflows with an `INVALID_DEFINITION` diagnostic because the workflow graph would be empty (`cachedLayout.length === 0`). To be valid, the run body must call at least one of:
+
+- `ctx.task()`
+- `ctx.chain()`
+- `ctx.parallel()`
+- `ctx.stage()`
+
+If the entire job is deterministic TypeScript with no LLM/session interaction, use a script, custom tool, or extension command instead of a workflow. If deterministic code prepares or post-processes LLM work, keep that code in `.run()` or helpers, but pair it with a nearby tracked stage.
+
 ## Inputs
 
 Supported input schema types are:
@@ -80,21 +132,23 @@ All schemas support `description` and `required`. Prefer explicit descriptions b
 
 `ctx.inputs` contains resolved inputs.
 
-Prefer high-level primitives:
+Prefer high-level primitives for most workflows because they create tracked graph nodes, provide consistent handoff semantics, and keep definitions easier to read:
 
-- `ctx.task(name, options)` — one tracked stage + prompt, returns `WorkflowTaskResult`.
-- `ctx.parallel(steps, options?)` — run independent task steps together; keep authored fan-outs intentionally bounded.
-- `ctx.chain(steps, options?)` — run dependent task steps sequentially.
-- `ctx.ui` — human-in-the-loop primitives when a run needs user input.
+- `ctx.task(name, options)` — use for one LLM/session task with workflow tracking. This is the default choice for a single stage.
+- `ctx.chain(steps, options?)` — use for dependent sequential tasks where each step consumes previous output.
+- `ctx.parallel(steps, options?)` — use for independent branches that can run concurrently; supports shared task/session defaults plus `concurrency` and `failFast`.
+- `ctx.ui` — use for human-in-the-loop decisions during the workflow run.
 
-Use `ctx.stage(name, options?)` only when you need lower-level session control. `StageContext` supports:
+Advanced users and advanced use cases can use `ctx.stage(name, options?)` for finer-grained session control. Reach for it when `ctx.task` is too coarse and you need direct control over the underlying stage session. `StageContext` supports:
 
 - `prompt(text, options?)`, `complete(text, options?)`
-- `steer`, `followUp`, `subscribe`
+- `steer(text)`, `followUp(text)`, `subscribe(listener)`
 - session metadata: `sessionId`, `sessionFile`
 - model/thinking controls: `setModel`, `setThinkingLevel`, `cycleModel`, `cycleThinkingLevel`
 - state access: `agent`, `model`, `thinkingLevel`, `messages`, `isStreaming`
-- tree navigation, compaction, and abort
+- in-session tree navigation: `navigateTree(targetId, { summarize?, customInstructions?, replaceInstructions?, label? })`
+- compaction controls: `compact(customInstructions?)`, `abortCompaction()`
+- current operation abort: `abort()`
 
 ## Human-in-the-loop UI
 
@@ -113,10 +167,11 @@ Common task/stage options include:
 
 - `prompt` or `task`
 - `previous` for handoff context; `{previous}` placeholder inserts it, otherwise context is appended
-- `context: "fresh" | "fork"`
-- `model`, `fallbackModels`, `thinkingLevel`
-- `output`, `outputMode`, `reads`, `progress`, `worktree`, `maxOutput`, `artifacts`, `sessionDir`, `cwd`
-- `mcp: { allow?: string[], deny?: string[] }`
+- `context: "fresh" | "fork"`, `forkFromSessionFile`
+- `model`, `fallbackModels`, `thinkingLevel`, `scopedModels`, `modelRegistry`
+- `tools`, `noTools`, `customTools`, `mcp: { allow?: string[], deny?: string[] }`
+- `output`, `outputMode`, `reads`, `worktree`, `maxOutput`, `artifacts`, `sessionDir`, `cwd`, `agentDir`
+- advanced SDK seams when explicitly supplied by host code: `authStorage`, `resourceLoader`, `sessionManager`, `settingsManager`, `sessionStartEvent`
 
 `fallbackModels` retries transient provider/model failures with the primary `model` first, then each fallback, then the current pi-selected model when available. It is for rate limits, quota/auth/provider outages, unavailable models, network timeouts, and 5xx errors — not workflow-code errors, tool failures, validation failures, or cancellations. Use provider-qualified IDs when bare IDs would be ambiguous.
 
@@ -137,13 +192,18 @@ Use `createRegistry()` when code needs to group definitions explicitly:
 ```ts
 import { createRegistry, defineWorkflow } from "@bastani/workflows";
 
-const alpha = defineWorkflow("alpha").run(async () => ({})).compile();
+const alpha = defineWorkflow("alpha")
+  .run(async (ctx) => {
+    const result = await ctx.task("alpha", { prompt: "Run alpha." });
+    return { text: result.text };
+  })
+  .compile();
 const registry = createRegistry().register(alpha);
 registry.names();
 registry.get("alpha");
 ```
 
-`@bastani/workflows` is a pi package/extension. Pi loads the extension from the package manifest; the extension registers the `workflow` tool, `/workflow` command, renderers, widgets, and lifecycle hooks. Use these user-facing surfaces:
+`@bastani/workflows` is an Atomic/pi package extension. The host loads extension metadata from supported package manifest keys (new app-name keys where available plus pi-compatible metadata used by existing packages). The extension registers the `workflow` tool, `/workflow` command, renderers, widgets, and lifecycle hooks. Use these user-facing surfaces:
 
 - `/workflow <name> key=value ...` inside pi.
 - The `workflow` tool for LLM-driven orchestration and direct one-off runs.
@@ -160,10 +220,41 @@ const definition = {
   inputs: {
     prompt: "map workflow sdk",
     max_partitions: 1,
+    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: "inline",
+  maxOutput: { lines: 2000 },
+  artifacts: true,
+});
+
+await runWorkflow({
+  mode: "chain",
+  task: "Plan a safe release",
+  chainName: "release-plan",
+  chainDir: ".atomic/workflows/runs/release-plan",
+  chain: [
+    { name: "research", task: "Research release constraints for {task}" },
+    { name: "plan", task: "Create a release plan from {previous}" },
+  ],
+});
 ```
+
+The programmatic definition object mirrors the workflow tool for `mode: "workflow"` / `"named"`, `"single"`, `"parallel"`, and `"chain"` runs, including direct options and stage/session options. Direct chains support `chainName` for status/artifact grouping and `chainDir` as a shared directory for relative reads, outputs, and worktree diffs.
+
+Workflow stage sessions follow Atomic SDK directory defaults: resource discovery starts from `.atomic` locations (`~/.atomic/agent`, `<cwd>/.atomic`) and also considers legacy `.pi` locations where the SDK supports multiple config directories. Passing `agentDir` on a stage/task is an explicit user override; passing `resourceLoader` makes that loader responsible for discovery, while `cwd`/`agentDir` still affect session naming and tool path resolution.

package/dist/builtin/workflows/src/extension/discovery.ts

@@ -12,7 +12,8 @@
  *   2. project-local    — {cwd}/.atomic/workflows/*.{ts,js,mjs,cjs}
  *   3. settings-global  — paths listed in config.globalWorkflows
  *   4. user-global      — {homeDir}/.atomic/agent/workflows/*.{ts,js,mjs,cjs}
- *   5. bundled          — shipped workflows (skipped when includeBundled=false)
+ *   5. package          — workflow files supplied by Atomic/pi packages
+ *   6. bundled          — shipped workflows (skipped when includeBundled=false)
  *
  * Usage:
  *   // Full discovery (all sources):
@@ -39,13 +40,15 @@ import * as bundledManifest from "../../builtin/index.js";
  *   user-global      — found in {homeDir}/.atomic/agent/workflows/
  *   settings-project — listed in DiscoveryConfig.projectWorkflows
  *   settings-global  — listed in DiscoveryConfig.globalWorkflows
+ *   package          — supplied by Atomic/pi package workflow resources
  */
 export type DiscoveryKind =
   | "bundled"
   | "project-local"
   | "user-global"
   | "settings-project"
-  | "settings-global";
+  | "settings-global"
+  | "package";
 
 /** Identifies the origin of a discovered workflow definition. */
 export interface DiscoverySource {
@@ -121,6 +124,8 @@ export interface DiscoveryOptions {
   homeDir: string;
   /** Optional extra paths from project/global config. */
   config?: DiscoveryConfig;
+  /** Workflow files supplied by installed Atomic/pi packages. */
+  packageWorkflowPaths?: string[] | Record<string, string>;
   /** When false, bundled workflows are excluded. Default: true */
   includeBundled?: boolean;
 }
@@ -143,6 +148,15 @@ export interface DiscoveryResult {
  * Validate a candidate value as a WorkflowDefinition.
  * Returns null when valid, or a human-readable rejection reason string.
  */
+function workflowRunCreatesStage(run: WorkflowDefinition["run"]): boolean {
+  // Discovery must not execute workflow bodies: run functions are arbitrary
+  // user code and may perform I/O before the first stage. Use a conservative
+  // static guard instead so obvious no-stage definitions are rejected before
+  // they can register and render an empty graph.
+  const source = Function.prototype.toString.call(run);
+  return /\.\s*(?:stage|task|chain|parallel)\s*\(/.test(source);
+}
+
 function validateDefinition(value: unknown): string | null {
   if (value === null || typeof value !== "object") {
     return "export is not an object";
@@ -161,6 +175,9 @@ function validateDefinition(value: unknown): string | null {
   if (typeof d["run"] !== "function") {
     return "run must be a function";
   }
+  if (!workflowRunCreatesStage(d["run"] as WorkflowDefinition["run"])) {
+    return "run must create at least one workflow stage via ctx.stage(), ctx.task(), ctx.chain(), or ctx.parallel(); otherwise the workflow graph is empty (cachedLayout.length === 0)";
+  }
   return null;
 }
 
@@ -367,7 +384,8 @@ async function loadFromPaths(
  *   2. project-local    — {cwd}/.atomic/workflows/*.{ts,js,mjs,cjs}
  *   3. settings-global  — config.globalWorkflows paths
  *   4. user-global      — {homeDir}/.atomic/agent/workflows/*.{ts,js,mjs,cjs}
- *   5. bundled          — shipped workflows (omitted when includeBundled=false)
+ *   5. package          — package-supplied workflow files
+ *   6. bundled          — shipped workflows (omitted when includeBundled=false)
  */
 export async function discoverWorkflows(
   options?: Partial<DiscoveryOptions>,
@@ -375,6 +393,7 @@ export async function discoverWorkflows(
   const cwd = options?.cwd ?? process.cwd();
   const homeDir = options?.homeDir ?? (await defaultHomeDir());
   const config = options?.config;
+  const packageWorkflowPaths = options?.packageWorkflowPaths;
   const includeBundled = options?.includeBundled !== false;
 
   const diagnostics: DiscoveryDiagnostic[] = [];
@@ -429,7 +448,16 @@ export async function discoverWorkflows(
     registry = applyBatch(candidates, registry, sources, diagnostics);
   }
 
-  // 5. bundled
+  // 5. package workflows
+  if (packageWorkflowPaths !== undefined) {
+    const hasEntries = Array.isArray(packageWorkflowPaths) ? packageWorkflowPaths.length > 0 : Object.keys(packageWorkflowPaths).length > 0;
+    if (hasEntries) {
+      const candidates = await loadFromPaths(packageWorkflowPaths, "package", cwd, diagnostics);
+      registry = applyBatch(candidates, registry, sources, diagnostics);
+    }
+  }
+
+  // 6. bundled
   if (includeBundled) {
     const bundledResult = discoverBundledManifest();
     // Merge bundled: only register names not already present (lower precedence)