agent-relay 3.2.16 → 3.2.18

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/sdk",
-  "version": "3.2.16",
+  "version": "3.2.18",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -112,7 +112,7 @@
     "typescript": "^5.7.3"
   },
   "dependencies": {
-    "@agent-relay/config": "3.2.16",
+    "@agent-relay/config": "3.2.18",
     "@relaycast/sdk": "^1.1.0",
     "@sinclair/typebox": "^0.34.48",
     "chalk": "^4.1.2",

package/packages/sdk/src/workflows/runner.ts

@@ -6223,26 +6223,23 @@ export class WorkflowRunner {
     );
     console.log(chalk.dim('━'.repeat(70)));
 
-    if (this.agentReports.size > 0) {
-      console.log(formatRunSummaryTable(outcomes, this.agentReports));
-    } else {
-      for (const outcome of outcomes) {
-        const icon =
-          outcome.status === 'completed' ? chalk.green('✓') : outcome.status === 'failed' ? chalk.red('✗') : chalk.dim('⊘');
-        const retryNote = outcome.attempts > 1 ? ` (${outcome.attempts} attempts)` : '';
-        console.log(`  ${icon} ${outcome.name} [${outcome.agent}]${retryNote}`);
-
-        if (outcome.error) {
-          console.log(`    Error: ${outcome.error}`);
-        }
+    // Always show the summary table — with agent reports when available,
+    // with just step/status/duration when not (non-interactive agents).
+    console.log(formatRunSummaryTable(outcomes, this.agentReports));
 
-        // Extract last meaningful lines from raw PTY output
-        if (outcome.output) {
-          const excerpt = this.extractOutputExcerpt(outcome.output);
-          if (excerpt) {
-            for (const line of excerpt.split('\n')) {
-              console.log(`    ${line}`);
-            }
+    // Show errors and output excerpts for failed steps below the table
+    for (const outcome of outcomes) {
+      if (outcome.status !== 'failed') continue;
+
+      if (outcome.error) {
+        console.log(chalk.red(`  ${outcome.name}: ${outcome.error}`));
+      }
+
+      if (outcome.output) {
+        const excerpt = this.extractOutputExcerpt(outcome.output);
+        if (excerpt) {
+          for (const line of excerpt.split('\n')) {
+            console.log(`    ${line}`);
           }
         }
       }

package/packages/sdk-py/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-relay-sdk"
-version = "3.2.16"
+version = "3.2.18"
 description = "Python SDK for Agent Relay workflows"
 readme = "README.md"
 license = "Apache-2.0"

package/packages/sdk-py/src/agent_relay/builder.py

@@ -18,9 +18,11 @@ Example::
 from __future__ import annotations
 
 import copy
+import os
 import re
 import shutil
 import subprocess
+import sys
 import tempfile
 from pathlib import Path
 from typing import Any
@@ -388,9 +390,36 @@ class WorkflowBuilder:
         """Serialize the config to a YAML string."""
         return yaml.dump(self.to_config(), default_flow_style=False, sort_keys=False)
 
+    def dry_run(self, options: RunOptions | None = None) -> WorkflowResult:
+        """Validate the workflow and show execution plan without running."""
+        opts = RunOptions(
+            workflow=(options.workflow if options else None),
+            cwd=(options.cwd if options else None),
+            vars=(options.vars if options else None),
+            trajectories=(options.trajectories if options else None),
+            on_event=(options.on_event if options else None),
+            dry_run=True,
+        )
+        return self.run(opts)
+
     def run(self, options: RunOptions | None = None) -> WorkflowResult:
-        """Build the config and execute it via ``agent-relay run <tempfile>``."""
-        opts = options or RunOptions()
+        """Build the config and execute it via ``agent-relay run <tempfile>``.
+
+        Dry-run is enabled when:
+        - ``options.dry_run`` is ``True``, or
+        - the ``DRY_RUN`` environment variable is set to ``"true"``
+          (set automatically by ``agent-relay run script.py --dry-run``).
+        """
+        opts = RunOptions(
+            workflow=(options.workflow if options else None),
+            cwd=(options.cwd if options else None),
+            vars=(options.vars if options else None),
+            trajectories=(options.trajectories if options else None),
+            on_event=(options.on_event if options else None),
+            dry_run=(options.dry_run if options else None),
+        )
+        if opts.dry_run is None and os.environ.get("DRY_RUN") == "true":
+            opts.dry_run = True
         config = _apply_runtime_overrides(self.to_config(), opts)
         return _run_config(config, opts)
 
@@ -402,7 +431,16 @@ def workflow(name: str) -> WorkflowBuilder:
 
 def run_yaml(yaml_path: str, options: RunOptions | None = None) -> WorkflowResult:
     """Run an existing relay YAML workflow file."""
-    opts = options or RunOptions()
+    opts = RunOptions(
+        workflow=(options.workflow if options else None),
+        cwd=(options.cwd if options else None),
+        vars=(options.vars if options else None),
+        trajectories=(options.trajectories if options else None),
+        on_event=(options.on_event if options else None),
+        dry_run=(options.dry_run if options else None),
+    )
+    if opts.dry_run is None and os.environ.get("DRY_RUN") == "true":
+        opts.dry_run = True
 
     if opts.trajectories is None and not opts.vars:
         return _run_yaml_path(yaml_path, opts)
@@ -436,6 +474,8 @@ def _run_yaml_path(yaml_path: str, options: RunOptions) -> WorkflowResult:
         )
 
     cmd = [*cmd_prefix, "run", yaml_path]
+    if options.dry_run:
+        cmd.append("--dry-run")
     if options.workflow:
         cmd.extend(["--workflow", options.workflow])
 
@@ -462,7 +502,26 @@ def _execute_cli(
     cwd: str | None,
     on_event: WorkflowEventCallback | None,
 ) -> WorkflowResult:
-    """Execute CLI command and parse emitted workflow events."""
+    """Execute CLI command and parse emitted workflow events.
+
+    When no event callback is registered, stdio is passed straight through so
+    the TypeScript runner's listr progress and summary table render directly
+    to the terminal — identical output to YAML and TypeScript workflows.
+    """
+    # Passthrough mode: no callback → let the TS runner render directly
+    if on_event is None:
+        process = subprocess.Popen(cmd, cwd=cwd)
+        process.wait()
+
+        return WorkflowResult(
+            status="completed" if process.returncode == 0 else "failed",
+            run_id="",
+            error=None if process.returncode == 0 else "Workflow failed",
+            steps=[],
+            events=[],
+        )
+
+    # Capture mode: callback registered → parse events line by line
     process = subprocess.Popen(
         cmd,
         cwd=cwd,
@@ -487,9 +546,7 @@ def _execute_cli(
 
             events.append(event)
             _sync_step_result(steps, event)
-
-            if on_event is not None:
-                on_event(event)
+            on_event(event)
 
     return_code = process.wait()
     output = "\n".join(lines).strip()

package/packages/sdk-py/src/agent_relay/types.py

@@ -562,6 +562,7 @@ class RunOptions:
     vars: dict[str, str | int | bool] | None = None
     trajectories: TrajectoryConfig | Literal[False] | dict[str, Any] | bool | None = None
     on_event: WorkflowEventCallback | None = None
+    dry_run: bool | None = None
 
 
 @dataclass

package/packages/sdk-py/tests/test_builder.py

@@ -213,3 +213,61 @@ def test_dag_empty_agents_raises():
 def test_dag_empty_steps_raises():
     with pytest.raises(ValueError, match="at least one step"):
         dag("empty", agents=[TemplateAgent(name="a")], steps=[])
+
+
+def test_run_options_dry_run_flag():
+    """dry_run option should be passed through to CLI as --dry-run."""
+    from agent_relay.types import RunOptions
+
+    opts = RunOptions(dry_run=True)
+    assert opts.dry_run is True
+
+    opts_default = RunOptions()
+    assert opts_default.dry_run is None
+
+
+def test_dry_run_env_var(monkeypatch):
+    """DRY_RUN=true env var should enable dry_run on .run()."""
+    monkeypatch.setenv("DRY_RUN", "true")
+
+    builder = (
+        workflow("test-dry")
+        .pattern("dag")
+        .agent("worker", cli="claude")
+        .step("s1", agent="worker", task="Do something")
+    )
+
+    # Calling .run() should resolve dry_run from env — we test via RunOptions
+    from agent_relay.types import RunOptions
+    import os
+
+    opts = RunOptions()
+    if opts.dry_run is None and os.environ.get("DRY_RUN") == "true":
+        opts.dry_run = True
+    assert opts.dry_run is True
+
+
+def test_dry_run_env_var_not_set():
+    """Without DRY_RUN env var, dry_run should remain None."""
+    from agent_relay.types import RunOptions
+    import os
+
+    # Ensure env var is not set
+    os.environ.pop("DRY_RUN", None)
+    opts = RunOptions()
+    assert opts.dry_run is None
+
+
+def test_dry_run_method():
+    """WorkflowBuilder.dry_run() should set dry_run=True."""
+    builder = (
+        workflow("test-dry-method")
+        .pattern("dag")
+        .agent("worker", cli="claude")
+        .step("s1", agent="worker", task="Do something")
+    )
+
+    # We can't actually call dry_run() without the CLI, but we can verify
+    # the method exists and the config is still valid
+    config = builder.to_config()
+    assert config["name"] == "test-dry-method"

package/packages/sdk-py/tests/test_dry_run.py

@@ -0,0 +1,215 @@
+"""Tests for dry-run support in the Python workflow builder."""
+
+import os
+import subprocess
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from agent_relay import workflow, fan_out, pipeline, PipelineStage, run_yaml
+from agent_relay.types import RunOptions
+
+
+class TestDryRunOption:
+    """RunOptions.dry_run field."""
+
+    def test_default_is_none(self):
+        opts = RunOptions()
+        assert opts.dry_run is None
+
+    def test_explicit_true(self):
+        opts = RunOptions(dry_run=True)
+        assert opts.dry_run is True
+
+    def test_explicit_false(self):
+        opts = RunOptions(dry_run=False)
+        assert opts.dry_run is False
+
+
+class TestDryRunEnvVar:
+    """DRY_RUN environment variable auto-detection."""
+
+    def test_env_var_enables_dry_run(self, monkeypatch):
+        monkeypatch.setenv("DRY_RUN", "true")
+        builder = (
+            workflow("test")
+            .agent("w", cli="claude")
+            .step("s", agent="w", task="t")
+        )
+        with patch("agent_relay.builder._run_config") as mock_run:
+            mock_run.return_value = MagicMock(status="completed")
+            builder.run()
+            # The opts passed to _run_config should have dry_run=True
+            call_opts = mock_run.call_args[0][1]
+            assert call_opts.dry_run is True
+
+    def test_env_var_not_set_leaves_none(self, monkeypatch):
+        monkeypatch.delenv("DRY_RUN", raising=False)
+        builder = (
+            workflow("test")
+            .agent("w", cli="claude")
+            .step("s", agent="w", task="t")
+        )
+        with patch("agent_relay.builder._run_config") as mock_run:
+            mock_run.return_value = MagicMock(status="completed")
+            builder.run()
+            call_opts = mock_run.call_args[0][1]
+            assert call_opts.dry_run is None
+
+    def test_explicit_false_overrides_env(self, monkeypatch):
+        monkeypatch.setenv("DRY_RUN", "true")
+        builder = (
+            workflow("test")
+            .agent("w", cli="claude")
+            .step("s", agent="w", task="t")
+        )
+        with patch("agent_relay.builder._run_config") as mock_run:
+            mock_run.return_value = MagicMock(status="completed")
+            builder.run(RunOptions(dry_run=False))
+            call_opts = mock_run.call_args[0][1]
+            assert call_opts.dry_run is False
+
+
+class TestDryRunCLIFlag:
+    """--dry-run flag is passed to the agent-relay CLI."""
+
+    def test_dry_run_adds_flag(self):
+        """When dry_run=True, the CLI command should include --dry-run."""
+        from agent_relay.builder import _find_agent_relay
+
+        cmd_prefix = _find_agent_relay()
+        if cmd_prefix is None:
+            pytest.skip("agent-relay CLI not installed")
+
+        builder = (
+            workflow("test-flag")
+            .agent("w", cli="claude")
+            .step("s", agent="w", task="t")
+        )
+
+        with patch("agent_relay.builder._execute_cli") as mock_exec:
+            mock_run_result = MagicMock(status="completed")
+            mock_exec.return_value = mock_run_result
+
+            builder.run(RunOptions(dry_run=True))
+
+            cmd = mock_exec.call_args[0][0]
+            assert "--dry-run" in cmd
+
+    def test_no_dry_run_omits_flag(self):
+        """When dry_run is not set, --dry-run should not be in the command."""
+        from agent_relay.builder import _find_agent_relay
+
+        cmd_prefix = _find_agent_relay()
+        if cmd_prefix is None:
+            pytest.skip("agent-relay CLI not installed")
+
+        builder = (
+            workflow("test-no-flag")
+            .agent("w", cli="claude")
+            .step("s", agent="w", task="t")
+        )
+
+        with patch("agent_relay.builder._execute_cli") as mock_exec:
+            mock_run_result = MagicMock(status="completed")
+            mock_exec.return_value = mock_run_result
+
+            builder.run()
+
+            cmd = mock_exec.call_args[0][0]
+            assert "--dry-run" not in cmd
+
+
+class TestDryRunMethod:
+    """.dry_run() convenience method."""
+
+    def test_dry_run_method_sets_flag(self):
+        builder = (
+            workflow("test-method")
+            .agent("w", cli="claude")
+            .step("s", agent="w", task="t")
+        )
+
+        with patch("agent_relay.builder._run_config") as mock_run:
+            mock_run.return_value = MagicMock(status="completed")
+            builder.dry_run()
+            call_opts = mock_run.call_args[0][1]
+            assert call_opts.dry_run is True
+
+
+class TestDryRunE2E:
+    """End-to-end dry-run through agent-relay CLI (requires CLI installed)."""
+
+    def test_builder_dry_run_e2e(self):
+        from agent_relay.builder import _find_agent_relay
+
+        if _find_agent_relay() is None:
+            pytest.skip("agent-relay CLI not installed")
+
+        result = (
+            workflow("e2e-dry")
+            .agent("w", cli="claude")
+            .step("s", agent="w", task="Do something")
+            .dry_run()
+        )
+
+        assert result.status == "completed"
+
+    def test_fan_out_dry_run_e2e(self):
+        from agent_relay.builder import _find_agent_relay
+
+        if _find_agent_relay() is None:
+            pytest.skip("agent-relay CLI not installed")
+
+        result = (
+            fan_out("e2e-fan", tasks=["task A", "task B"], worker_cli="claude")
+            .dry_run()
+        )
+
+        assert result.status == "completed"
+
+    def test_pipeline_dry_run_e2e(self):
+        from agent_relay.builder import _find_agent_relay
+
+        if _find_agent_relay() is None:
+            pytest.skip("agent-relay CLI not installed")
+
+        result = pipeline(
+            "e2e-pipe",
+            stages=[
+                PipelineStage(name="s1", task="First"),
+                PipelineStage(name="s2", task="Second"),
+            ],
+        ).dry_run()
+
+        assert result.status == "completed"
+
+
+class TestRunYamlDryRun:
+    """run_yaml() respects dry_run and DRY_RUN env var."""
+
+    def test_run_yaml_env_var(self, monkeypatch, tmp_path):
+        monkeypatch.setenv("DRY_RUN", "true")
+
+        yaml_file = tmp_path / "test.yaml"
+        yaml_file.write_text("""
+version: "1.0"
+name: yaml-dry-test
+swarm:
+  pattern: dag
+agents:
+  - name: w
+    cli: claude
+workflows:
+  - name: wf
+    steps:
+      - name: s
+        agent: w
+        task: do something
+""")
+
+        with patch("agent_relay.builder._run_yaml_path") as mock_run:
+            mock_run.return_value = MagicMock(status="completed")
+            run_yaml(str(yaml_file))
+            call_opts = mock_run.call_args[0][1]
+            assert call_opts.dry_run is True

package/packages/telemetry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/telemetry",
-  "version": "3.2.16",
+  "version": "3.2.18",
   "description": "Anonymous telemetry for Agent Relay usage analytics",
   "type": "module",
   "main": "dist/index.js",

package/packages/trajectory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/trajectory",
-  "version": "3.2.16",
+  "version": "3.2.18",
   "description": "Trajectory integration utilities (trail/PDERO) for Relay",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/config": "3.2.16"
+    "@agent-relay/config": "3.2.18"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/user-directory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/user-directory",
-  "version": "3.2.16",
+  "version": "3.2.18",
   "description": "User directory service for agent-relay (per-user credential storage)",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/utils": "3.2.16"
+    "@agent-relay/utils": "3.2.18"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/utils/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/utils",
-  "version": "3.2.16",
+  "version": "3.2.18",
   "description": "Shared utilities for agent-relay: logging, name generation, command resolution, update checking",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -112,7 +112,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@agent-relay/config": "3.2.16",
+    "@agent-relay/config": "3.2.18",
     "compare-versions": "^6.1.1"
   },
   "publishConfig": {