agent-relay 3.1.14 → 3.1.16

package/packages/sdk/src/workflows/schema.json

@@ -1,10 +1,17 @@
+Added workdir to AgentWorkflowStep
+Added workdir to DeterministicWorkflowStep
+Added workdir to WorktreeWorkflowStep
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "RelayYamlConfig",
   "title": "Relay YAML Configuration",
   "description": "Schema for relay.yaml workflow configuration files",
   "type": "object",
-  "required": ["version", "name", "swarm"],
+  "required": [
+    "version",
+    "name",
+    "swarm"
+  ],
   "additionalProperties": false,
   "properties": {
     "version": {
@@ -19,6 +26,13 @@
       "type": "string",
       "description": "Optional description of the configuration"
     },
+    "paths": {
+      "type": "array",
+      "description": "Named paths to external directories. The primary working directory defaults to cwd. Use this to declare additional directories so the runner can validate them in preflight and agents can reference them via workdir.",
+      "items": {
+        "$ref": "#/definitions/PathDefinition"
+      }
+    },
     "swarm": {
       "$ref": "#/definitions/SwarmConfig"
     },
@@ -51,15 +65,46 @@
         },
         {
           "type": "boolean",
-          "enum": [false]
+          "enum": [
+            false
+          ]
         }
       ]
     }
   },
   "definitions": {
+    "PathDefinition": {
+      "type": "object",
+      "required": [
+        "name",
+        "path"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Unique name used to reference this project (e.g. 'relaycast', 'relay')"
+        },
+        "path": {
+          "type": "string",
+          "description": "Path to the project root, resolved relative to the YAML file. Supports env vars: $HOME/.openclaw"
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of this project's role in the workflow"
+        },
+        "required": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether this project is required. If true (default), preflight fails if path doesn't exist."
+        }
+      }
+    },
     "SwarmConfig": {
       "type": "object",
-      "required": ["pattern"],
+      "required": [
+        "pattern"
+      ],
       "additionalProperties": false,
       "properties": {
         "pattern": {
@@ -136,7 +181,10 @@
     },
     "AgentDefinition": {
       "type": "object",
-      "required": ["name", "cli"],
+      "required": [
+        "name",
+        "cli"
+      ],
       "additionalProperties": false,
       "properties": {
         "name": {
@@ -156,7 +204,9 @@
         },
         "channels": {
           "type": "array",
-          "items": { "type": "string" },
+          "items": {
+            "type": "string"
+          },
           "description": "Relay channels the agent should join"
         },
         "constraints": {
@@ -167,16 +217,47 @@
           "default": true,
           "description": "When false, the agent runs as a non-interactive subprocess (no PTY, no relay messaging). It receives its task as a CLI prompt argument and returns stdout as output. Default: true."
         },
+        "cwd": {
+          "type": "string",
+          "description": "Working directory for this agent, resolved relative to the YAML file."
+        },
+        "workdir": {
+          "type": "string",
+          "description": "Sets this agent's working directory to a named entry from the top-level paths array. Mutually exclusive with cwd."
+        },
+        "additionalPaths": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Additional paths the agent needs read/write access to."
+        },
         "preset": {
           "type": "string",
-          "enum": ["lead", "worker", "reviewer", "analyst"],
+          "enum": [
+            "lead",
+            "worker",
+            "reviewer",
+            "analyst"
+          ],
           "description": "Role preset that automatically configures interactive mode and injects appropriate task guardrails. lead: interactive PTY, relay-aware. worker/reviewer/analyst: interactive: false, no sub-agents."
         }
       }
     },
     "AgentCli": {
       "type": "string",
-      "enum": ["claude", "codex", "gemini", "aider", "goose", "opencode", "droid", "cursor", "cursor-agent", "agent"]
+      "enum": [
+        "claude",
+        "codex",
+        "gemini",
+        "aider",
+        "goose",
+        "opencode",
+        "droid",
+        "cursor",
+        "cursor-agent",
+        "agent"
+      ]
     },
     "AgentConstraints": {
       "type": "object",
@@ -232,7 +313,10 @@
     },
     "WorkflowDefinition": {
       "type": "object",
-      "required": ["name", "steps"],
+      "required": [
+        "name",
+        "steps"
+      ],
       "additionalProperties": false,
       "properties": {
         "name": {
@@ -258,14 +342,20 @@
         },
         "onError": {
           "type": "string",
-          "enum": ["fail", "skip", "retry"],
+          "enum": [
+            "fail",
+            "skip",
+            "retry"
+          ],
           "description": "Error handling strategy for this workflow"
         }
       }
     },
     "PreflightCheck": {
       "type": "object",
-      "required": ["command"],
+      "required": [
+        "command"
+      ],
       "additionalProperties": false,
       "properties": {
         "command": {
@@ -288,20 +378,34 @@
     },
     "WorkflowStep": {
       "oneOf": [
-        { "$ref": "#/definitions/AgentWorkflowStep" },
-        { "$ref": "#/definitions/DeterministicWorkflowStep" },
-        { "$ref": "#/definitions/WorktreeWorkflowStep" },
-        { "$ref": "#/definitions/CustomWorkflowStep" }
+        {
+          "$ref": "#/definitions/AgentWorkflowStep"
+        },
+        {
+          "$ref": "#/definitions/DeterministicWorkflowStep"
+        },
+        {
+          "$ref": "#/definitions/WorktreeWorkflowStep"
+        },
+        {
+          "$ref": "#/definitions/CustomWorkflowStep"
+        }
       ]
     },
     "AgentWorkflowStep": {
       "type": "object",
-      "required": ["name", "agent", "task"],
+      "required": [
+        "name",
+        "agent",
+        "task"
+      ],
       "additionalProperties": false,
       "properties": {
         "type": {
           "type": "string",
-          "enum": ["agent"],
+          "enum": [
+            "agent"
+          ],
           "description": "Step type (optional for agent steps, defaults to 'agent')"
         },
         "name": {
@@ -318,7 +422,9 @@
         },
         "dependsOn": {
           "type": "array",
-          "items": { "type": "string" },
+          "items": {
+            "type": "string"
+          },
           "description": "Step names that must complete before this step runs"
         },
         "verification": {
@@ -336,17 +442,27 @@
           "type": "integer",
           "minimum": 1,
           "description": "Maximum iterations for steps that may need to retry"
+        },
+        "workdir": {
+          "type": "string",
+          "description": "Sets this step's working directory to a named entry from the top-level paths array."
         }
       }
     },
     "DeterministicWorkflowStep": {
       "type": "object",
-      "required": ["name", "type", "command"],
+      "required": [
+        "name",
+        "type",
+        "command"
+      ],
       "additionalProperties": false,
       "properties": {
         "type": {
           "type": "string",
-          "enum": ["deterministic"],
+          "enum": [
+            "deterministic"
+          ],
           "description": "Step type - must be 'deterministic' for shell command steps"
         },
         "name": {
@@ -359,7 +475,9 @@
         },
         "dependsOn": {
           "type": "array",
-          "items": { "type": "string" },
+          "items": {
+            "type": "string"
+          },
           "description": "Step names that must complete before this step runs"
         },
         "timeoutMs": {
@@ -375,17 +493,27 @@
           "type": "boolean",
           "default": true,
           "description": "Capture stdout as step output for downstream steps"
+        },
+        "workdir": {
+          "type": "string",
+          "description": "Sets this step's working directory to a named entry from the top-level paths array."
         }
       }
     },
     "WorktreeWorkflowStep": {
       "type": "object",
-      "required": ["name", "type", "branch"],
+      "required": [
+        "name",
+        "type",
+        "branch"
+      ],
       "additionalProperties": false,
       "properties": {
         "type": {
           "type": "string",
-          "enum": ["worktree"],
+          "enum": [
+            "worktree"
+          ],
           "description": "Step type - must be 'worktree' for git worktree setup steps"
         },
         "name": {
@@ -411,18 +539,27 @@
         },
         "dependsOn": {
           "type": "array",
-          "items": { "type": "string" },
+          "items": {
+            "type": "string"
+          },
           "description": "Step names that must complete before this step runs"
         },
         "timeoutMs": {
           "type": "integer",
           "minimum": 0
+        },
+        "workdir": {
+          "type": "string",
+          "description": "Sets this step's working directory to a named entry from the top-level paths array."
         }
       }
     },
     "CustomWorkflowStep": {
       "type": "object",
-      "required": ["name", "use"],
+      "required": [
+        "name",
+        "use"
+      ],
       "additionalProperties": true,
       "properties": {
         "name": {
@@ -435,7 +572,9 @@
         },
         "dependsOn": {
           "type": "array",
-          "items": { "type": "string" },
+          "items": {
+            "type": "string"
+          },
           "description": "Step names that must complete before this step runs"
         },
         "timeoutMs": {
@@ -446,7 +585,9 @@
     },
     "CustomStepParam": {
       "type": "object",
-      "required": ["name"],
+      "required": [
+        "name"
+      ],
       "additionalProperties": false,
       "properties": {
         "name": {
@@ -474,12 +615,17 @@
       "properties": {
         "params": {
           "type": "array",
-          "items": { "$ref": "#/definitions/CustomStepParam" },
+          "items": {
+            "$ref": "#/definitions/CustomStepParam"
+          },
           "description": "Parameters that can be passed when using this step"
         },
         "type": {
           "type": "string",
-          "enum": ["deterministic", "worktree"],
+          "enum": [
+            "deterministic",
+            "worktree"
+          ],
           "description": "Step type"
         },
         "command": {
@@ -525,24 +671,36 @@
     },
     "CustomStepsConfig": {
       "type": "object",
-      "required": ["steps"],
+      "required": [
+        "steps"
+      ],
       "additionalProperties": false,
       "properties": {
         "steps": {
           "type": "object",
-          "additionalProperties": { "$ref": "#/definitions/CustomStepDefinition" },
+          "additionalProperties": {
+            "$ref": "#/definitions/CustomStepDefinition"
+          },
           "description": "Map of step name to step definition"
         }
       }
     },
     "VerificationCheck": {
       "type": "object",
-      "required": ["type", "value"],
+      "required": [
+        "type",
+        "value"
+      ],
       "additionalProperties": false,
       "properties": {
         "type": {
           "type": "string",
-          "enum": ["output_contains", "exit_code", "file_exists", "custom"],
+          "enum": [
+            "output_contains",
+            "exit_code",
+            "file_exists",
+            "custom"
+          ],
           "description": "Type of verification to perform"
         },
         "value": {
@@ -573,14 +731,21 @@
         },
         "consensusStrategy": {
           "type": "string",
-          "enum": ["majority", "unanimous", "quorum"],
+          "enum": [
+            "majority",
+            "unanimous",
+            "quorum"
+          ],
           "description": "Strategy for reaching consensus among agents"
         }
       }
     },
     "Barrier": {
       "type": "object",
-      "required": ["name", "waitFor"],
+      "required": [
+        "name",
+        "waitFor"
+      ],
       "additionalProperties": false,
       "properties": {
         "name": {
@@ -589,7 +754,9 @@
         },
         "waitFor": {
           "type": "array",
-          "items": { "type": "string" },
+          "items": {
+            "type": "string"
+          },
           "minItems": 1,
           "description": "Agent or step names to wait for before proceeding"
         },
@@ -602,12 +769,18 @@
     },
     "StateConfig": {
       "type": "object",
-      "required": ["backend"],
+      "required": [
+        "backend"
+      ],
       "additionalProperties": false,
       "properties": {
         "backend": {
           "type": "string",
-          "enum": ["memory", "redis", "database"],
+          "enum": [
+            "memory",
+            "redis",
+            "database"
+          ],
           "description": "State storage backend"
         },
         "ttlMs": {
@@ -623,12 +796,18 @@
     },
     "ErrorHandlingConfig": {
       "type": "object",
-      "required": ["strategy"],
+      "required": [
+        "strategy"
+      ],
       "additionalProperties": false,
       "properties": {
         "strategy": {
           "type": "string",
-          "enum": ["fail-fast", "continue", "retry"],
+          "enum": [
+            "fail-fast",
+            "continue",
+            "retry"
+          ],
           "description": "Global error handling strategy"
         },
         "maxRetries": {
@@ -648,4 +827,4 @@
       }
     }
   }
-}
+}

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

@@ -12,6 +12,11 @@ export interface RelayYamlConfig {
   version: string;
   name: string;
   description?: string;
+  /** Named paths to external directories used by this workflow.
+   *  The primary working directory defaults to cwd and does not need to be declared.
+   *  Use this to declare additional directories so the runner can validate them
+   *  in preflight and agents can reference them via `workdir`. */
+  paths?: PathDefinition[];
   swarm: SwarmConfig;
   agents: AgentDefinition[];
   workflows?: WorkflowDefinition[];
@@ -21,6 +26,22 @@ export interface RelayYamlConfig {
   trajectories?: TrajectoryConfig | false;
 }
 
+// ── Path definitions ────────────────────────────────────────────────────────
+
+/** A named path to an external directory for cross-repo workflows.
+ *  Only needed for directories outside the default working directory. */
+export interface PathDefinition {
+  /** Unique name used to reference this path (e.g. "relaycast"). */
+  name: string;
+  /** Directory path, resolved relative to the YAML file.
+   *  Supports environment variables: "$HOME/.openclaw", "$RELAY_ROOT/packages/sdk". */
+  path: string;
+  /** Human-readable description of this path's role in the workflow. */
+  description?: string;
+  /** Whether this path is required. If true (default), preflight fails if it doesn't exist. */
+  required?: boolean;
+}
+
 // ── Trajectory configuration ─────────────────────────────────────────────────
 
 /** Configuration for workflow trajectory recording. */
@@ -102,6 +123,10 @@ export interface AgentDefinition {
   interactive?: boolean;
   /** Working directory for this agent, resolved relative to the YAML file. */
   cwd?: string;
+  /** Sets this agent's working directory to a named entry from the top-level `paths` array.
+   *  Mutually exclusive with `cwd`. If omitted, the agent runs in the runner's
+   *  working directory (the directory containing the workflow YAML file). */
+  workdir?: string;
   /** Additional paths the agent needs read/write access to. */
   additionalPaths?: string[];
   /**
@@ -234,6 +259,10 @@ export interface WorkflowStep {
   // ── Deterministic step fields ──────────────────────────────────────────────
   /** Shell command to execute (required for deterministic steps). */
   command?: string;
+  /** Sets this step's working directory to a named entry from the top-level `paths` array.
+   *  If omitted, the step inherits the agent's workdir, or falls back to the runner's
+   *  working directory. */
+  workdir?: string;
   /** Fail if command exit code is non-zero. Default: true. */
   failOnError?: boolean;
   /** Capture stdout as step output for downstream steps. Default: true. */

package/packages/sdk-py/pyproject.toml

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

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

@@ -59,6 +59,7 @@ from .types import (
     SwarmPattern,
     AgentDefinition,
     AgentConstraints,
+    PathDefinition,
     RelayYamlConfig,
     AgentCli,
     IdleNudgeConfig,
@@ -128,6 +129,7 @@ __all__ = [
     "SwarmPattern",
     "AgentDefinition",
     "AgentConstraints",
+    "PathDefinition",
     "RelayYamlConfig",
     "AgentCli",
     "IdleNudgeConfig",

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

@@ -123,6 +123,24 @@ class AgentConstraints:
         return result
 
 
+@dataclass
+class PathDefinition:
+    """A named path to an external directory for cross-repo workflows."""
+
+    name: str
+    path: str
+    description: str | None = None
+    required: bool | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        result: dict[str, Any] = {"name": self.name, "path": self.path}
+        if self.description is not None:
+            result["description"] = self.description
+        if self.required is not None:
+            result["required"] = self.required
+        return result
+
+
 @dataclass
 class AgentDefinition:
     name: str
@@ -132,6 +150,9 @@ class AgentDefinition:
     channels: list[str] | None = None
     constraints: AgentConstraints | None = None
     interactive: bool | None = None
+    cwd: str | None = None
+    workdir: str | None = None
+    additional_paths: list[str] | None = None
 
     def to_dict(self) -> dict[str, Any]:
         result: dict[str, Any] = {
@@ -150,6 +171,12 @@ class AgentDefinition:
                 result["constraints"] = constraints
         if self.interactive is not None:
             result["interactive"] = self.interactive
+        if self.cwd is not None:
+            result["cwd"] = self.cwd
+        if self.workdir is not None:
+            result["workdir"] = self.workdir
+        if self.additional_paths is not None:
+            result["additionalPaths"] = self.additional_paths
         return result
 
 
@@ -175,6 +202,7 @@ class WorkflowStep:
     verification: VerificationCheck | None = None
     timeout_ms: int | None = None
     retries: int | None = None
+    workdir: str | None = None
 
     def to_dict(self) -> dict[str, Any]:
         result: dict[str, Any] = {
@@ -190,6 +218,8 @@ class WorkflowStep:
             result["timeoutMs"] = self.timeout_ms
         if self.retries is not None:
             result["retries"] = self.retries
+        if self.workdir is not None:
+            result["workdir"] = self.workdir
         return result
 
 
@@ -285,6 +315,7 @@ class RelayYamlConfig:
     agents: list[AgentDefinition]
     version: str = "1.0"
     description: str | None = None
+    paths: list[PathDefinition] | None = None
     workflows: list[WorkflowDefinition] | None = None
     coordination: CoordinationConfig | None = None
     state: StateConfig | None = None
@@ -300,6 +331,8 @@ class RelayYamlConfig:
         }
         if self.description is not None:
             result["description"] = self.description
+        if self.paths is not None:
+            result["paths"] = [p.to_dict() for p in self.paths]
         if self.workflows is not None:
             result["workflows"] = [workflow.to_dict() for workflow in self.workflows]
         if self.coordination is not None:

package/packages/telemetry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/telemetry",
-  "version": "3.1.14",
+  "version": "3.1.16",
   "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.1.14",
+  "version": "3.1.16",
   "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.1.14"
+    "@agent-relay/config": "3.1.16"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",