feat(workflow): add subworkflow steps

Enable composing workflows via workflow: steps with isolated child context, recursion/depth guards, and artifact exports; add CLI E2E coverage across direct/supervised transports and scope CI tests to repo suites.

Author: reoring

CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog, and this project follows SemVer where practical.
+
+## [0.1.3] - 2026-02-22
+
+### Added
+
+- Subworkflow steps via `workflow:`: parent workflows can invoke child workflows, with isolated child context under `_subworkflows/` and optional `exports` to copy child artifacts into the parent context.
+- Recursion protection for subworkflow invocations (cycle detection + max nesting depth).
+- CLI E2E coverage for subworkflow execution in three modes: direct, supervised (stdio transport), supervised (socket transport).
+
+### Changed
+
+- Agent catalog loading is consolidated in `src/workflow/workflow-loader.ts` and reused by CLI and daemon; child workflows inherit the parent's resolved catalog.
+- `make test` / `bun run test` are scoped to this repo's test suites (`test/unit`, `test/integration`, `tests/at`) to avoid running vendored/reference tests.
+
+### Fixed
+
+- Harden workflow parsing and context path handling against path traversal and reserved-name collisions (step IDs and artifact names).
+
+## [0.1.2] - 2026-02-20
+
+- See GitHub release notes.

Makefile

@@ -26,8 +26,8 @@ all: build ## Build the binary (default)
 build: ## Build a single binary (roboppi)
 	$(BUN) $(BUN_FLAGS) build $(BUN_BUILD_FLAGS) --compile $(SRC) --outfile $(BIN)
 
-test: ## Run all tests
-	$(BUN) $(BUN_FLAGS) test
+test: ## Run all tests (repo scope)
+	$(BUN) $(BUN_FLAGS) test test/unit test/integration tests/at
 
 tests: test ## Alias for `make test`
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "roboppi",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "bin": {
     "roboppi": "src/cli.ts"
@@ -9,7 +9,7 @@
     "start": "bun run src/cli.ts",
     "dev": "bun run src/index.ts",
     "dev:scheduler": "bun run src/scheduler/index.ts",
-    "test": "bun test",
+    "test": "bun test test/unit test/integration tests/at",
     "test:unit": "bun test test/unit",
     "test:integration": "bun test test/integration",
     "test:at": "bun test tests/at",

src/daemon/daemon.ts

@@ -17,7 +17,7 @@ import { CommandSource } from "./events/command-source.js";
 import { mergeEventSources } from "./events/event-source.js";
 import type { EventSource } from "./events/event-source.js";
 import { parseWorkflow } from "../workflow/parser.js";
-import { parseAgentCatalog, type AgentCatalog } from "../workflow/agent-catalog.js";
+import { loadAgentCatalog } from "../workflow/workflow-loader.js";
 import type { StepRunner } from "../workflow/executor.js";
 import { WorkflowExecutor } from "../workflow/executor.js";
 import { MultiWorkerStepRunner } from "../workflow/multi-worker-step-runner.js";
@@ -512,6 +512,12 @@ export class Daemon {
         this.shutdownAbortController.signal,
         branchContext,
         this.supervised,
+        undefined,
+        {
+          definitionPath: workflowPath,
+          workflowCallStack: [workflowPath],
+          agentCatalog,
+        },
       );
       const result = await executor.execute();
 
@@ -550,52 +556,21 @@ export class Daemon {
   private async loadAgentCatalogForWorkflow(
     workflowPath: string,
     workflowEnv: Record<string, string>,
-  ): Promise<AgentCatalog | undefined> {
-    const fromProcessEnv = splitPathList(
-      process.env.ROBOPPI_AGENTS_FILE,
-    );
+  ): Promise<import("../workflow/agent-catalog.js").AgentCatalog | undefined> {
+    const fromProcessEnv = splitPathList(process.env.ROBOPPI_AGENTS_FILE);
     const fromConfig = this.config.agents_file ? [this.config.agents_file] : [];
-    const fromWorkflowEnv = splitPathList(
-      workflowEnv.ROBOPPI_AGENTS_FILE,
-    );
-
-    // Precedence: process env (lowest) -> daemon config -> trigger env (highest).
-    const explicit = [...fromProcessEnv, ...fromConfig, ...fromWorkflowEnv];
+    const fromWorkflowEnv = splitPathList(workflowEnv.ROBOPPI_AGENTS_FILE);
 
     const resolveFromWorkspace = (p: string): string =>
       path.isAbsolute(p) ? p : path.resolve(this.workspaceDir, p);
 
-    const candidates: string[] = [];
-    if (explicit.length > 0) {
-      candidates.push(...explicit.map(resolveFromWorkspace));
-    } else {
-      const dir = path.dirname(workflowPath);
-      candidates.push(path.join(dir, "agents.yaml"));
-      candidates.push(path.join(dir, "agents.yml"));
-    }
-
-    let catalog: AgentCatalog | undefined;
-    for (const p of candidates) {
-      try {
-        const content = await readFile(p, "utf-8");
-        const parsed = parseAgentCatalog(content);
-        catalog = { ...(catalog ?? {}), ...parsed };
-      } catch (err: unknown) {
-        const code = (err as any)?.code;
-
-        // In implicit mode, missing default files are ignored.
-        if (explicit.length === 0 && code === "ENOENT") {
-          continue;
-        }
+    const envAgentsPaths = fromProcessEnv.map(resolveFromWorkspace);
+    const explicitAgentsPaths = [...fromConfig, ...fromWorkflowEnv].map(resolveFromWorkspace);
 
-        if (code === "ENOENT") {
-          throw new Error(`Agent catalog not found: ${p}`);
-        }
-        throw err;
-      }
-    }
-
-    return catalog;
+    return loadAgentCatalog(workflowPath, {
+      envAgentsPaths,
+      explicitAgentsPaths: explicitAgentsPaths.length > 0 ? explicitAgentsPaths : undefined,
+    });
   }
 
   private logBranchContext(triggerId: string, context: BranchRuntimeContext): void {

src/workflow/agent-catalog.ts

@@ -2,8 +2,8 @@ import YAML from "yaml";
 
 import type { StepDefinition, DurationString } from "./types.js";
 
-export type AgentWorkerKind = StepDefinition["worker"];
-export type AgentCapability = StepDefinition["capabilities"][number];
+export type AgentWorkerKind = NonNullable<StepDefinition["worker"]>;
+export type AgentCapability = NonNullable<StepDefinition["capabilities"]>[number];
 
 export interface AgentProfile {
   description?: string;

src/workflow/context-manager.ts

@@ -11,9 +11,18 @@ export interface StepMeta {
   attempts: number;
   iterations?: number;
   maxIterations?: number;
-  workerKind: string;
+  workerKind?: string;
   artifacts: Array<{ name: string; path: string; type?: string }>;
   workerResult?: unknown;
+  subworkflow?: {
+    path: string;
+    name: string;
+    workflowId: string;
+    status: string;
+    contextDir: string;
+    startedAt: number;
+    completedAt?: number;
+  };
 }
 
 /**
@@ -31,9 +40,15 @@ export interface StepResolvedMeta {
   attempts: number;
   iterations?: number;
   maxIterations?: number;
-  workerKind: string;
+  workerKind?: string;
   artifacts: Array<{ name: string; path: string; type?: string }>;
   workerResult?: unknown;
+  subworkflowCall?: {
+    requestedPath: string;
+    definitionPath?: string;
+    effectiveTimeoutMs?: number;
+    maxNestingDepth?: number;
+  };
   resolved: {
     timeoutMs?: number;
     workspaceRef?: string;
@@ -46,7 +61,12 @@ export interface StepResolvedMeta {
 }
 
 function validatePathSegment(name: string): void {
-  if (name.includes("..") || name.includes(path.sep) || name.includes("/")) {
+  if (
+    name.includes("..") ||
+    name.includes(path.sep) ||
+    name.includes("/") ||
+    name.includes("\\")
+  ) {
     throw new Error(`Invalid path segment: ${name}`);
   }
 }
@@ -66,7 +86,7 @@ function ensureWithinBase(basePath: string, targetPath: string): string {
 }
 
 export class ContextManager {
-  constructor(private readonly contextDir: string) {}
+  constructor(public readonly contextDir: string) {}
 
   async initWorkflow(
     workflowId: string,

src/workflow/dag-validator.ts

@@ -1,4 +1,5 @@
 import type { WorkflowDefinition } from "./types.js";
+import { isSubworkflowStep } from "./types.js";
 
 export interface ValidationError {
   stepId?: string;
@@ -77,6 +78,22 @@ export function validateDag(workflow: WorkflowDefinition): ValidationError[] {
         });
       }
     }
+
+    // Subworkflow: exports `as` name uniqueness
+    if (isSubworkflowStep(step) && step.exports) {
+      const seen = new Set<string>();
+      for (const exp of step.exports) {
+        const name = exp.as ?? exp.artifact;
+        if (seen.has(name)) {
+          errors.push({
+            stepId,
+            field: "exports",
+            message: `Step "${stepId}" has duplicate export name "${name}"`,
+          });
+        }
+        seen.add(name);
+      }
+    }
   }
 
   // Cycle detection via topological sort (Kahn's algorithm)