agent-relay 3.1.15 → 3.1.16

package/packages/sdk/dist/workflows/runner.js

@@ -86,6 +86,8 @@ export class WorkflowRunner {
     lastIdleLog = new Map();
     /** Tracks last logged activity type per agent to avoid duplicate status lines. */
     lastActivity = new Map();
+    /** Resolved named paths from the top-level `paths` config, keyed by name → absolute directory. */
+    resolvedPaths = new Map();
     constructor(options = {}) {
         this.db = options.db ?? new InMemoryWorkflowDb();
         this.workspaceId = options.workspaceId ?? 'local';
@@ -95,6 +97,76 @@ export class WorkflowRunner {
         this.workersPath = path.join(this.cwd, '.agent-relay', 'team', 'workers.json');
         this.executor = options.executor;
     }
+    // ── Path resolution ─────────────────────────────────────────────────────
+    /** Expand environment variables like $HOME or $VAR in a path string. */
+    static resolveEnvVars(p) {
+        return p.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, varName) => {
+            return process.env[varName] ?? _match;
+        });
+    }
+    /**
+     * Resolve and validate the top-level `paths` definitions from the config.
+     * Returns a map of name → absolute directory path.
+     * Throws if a required path does not exist.
+     */
+    resolvePathDefinitions(pathDefs, baseCwd) {
+        const resolved = new Map();
+        const errors = [];
+        const warnings = [];
+        if (!pathDefs || pathDefs.length === 0)
+            return { resolved, errors, warnings };
+        const seenNames = new Set();
+        for (const pd of pathDefs) {
+            if (seenNames.has(pd.name)) {
+                errors.push(`Duplicate path name "${pd.name}"`);
+                continue;
+            }
+            seenNames.add(pd.name);
+            const expanded = WorkflowRunner.resolveEnvVars(pd.path);
+            const abs = path.resolve(baseCwd, expanded);
+            resolved.set(pd.name, abs);
+            const isRequired = pd.required !== false; // default true
+            if (!existsSync(abs)) {
+                if (isRequired) {
+                    errors.push(`Path "${pd.name}" resolves to "${abs}" which does not exist (required)`);
+                }
+                else {
+                    warnings.push(`Path "${pd.name}" resolves to "${abs}" which does not exist (optional)`);
+                }
+            }
+        }
+        return { resolved, errors, warnings };
+    }
+    /**
+     * Resolve an agent's effective working directory, considering `workdir` (named path reference)
+     * and `cwd` (explicit path). `workdir` takes precedence when both are set.
+     */
+    resolveAgentCwd(agent) {
+        if (agent.workdir) {
+            const resolved = this.resolvedPaths.get(agent.workdir);
+            if (!resolved) {
+                throw new Error(`Agent "${agent.name}" references workdir "${agent.workdir}" which is not defined in paths`);
+            }
+            return resolved;
+        }
+        if (agent.cwd) {
+            return path.resolve(this.cwd, agent.cwd);
+        }
+        return this.cwd;
+    }
+    /**
+     * Resolve a step's working directory from its `workdir` field (named path reference).
+     * Returns undefined if no workdir is set.
+     */
+    resolveStepWorkdir(step) {
+        if (!step.workdir)
+            return undefined;
+        const resolved = this.resolvedPaths.get(step.workdir);
+        if (!resolved) {
+            throw new Error(`Step "${step.name}" references workdir "${step.workdir}" which is not defined in paths`);
+        }
+        return resolved;
+    }
     // ── Progress logging ────────────────────────────────────────────────────
     /** Log a progress message with elapsed time since run start. */
     log(msg) {
@@ -346,6 +418,17 @@ export class WorkflowRunner {
                 estimatedWaves: 0,
             };
         }
+        // 1b. Resolve and validate named paths
+        const pathResult = this.resolvePathDefinitions(resolved.paths, this.cwd);
+        errors.push(...pathResult.errors);
+        warnings.push(...pathResult.warnings);
+        const dryRunPaths = pathResult.resolved;
+        // Validate workdir references on agents
+        for (const agent of resolved.agents) {
+            if (agent.workdir && !dryRunPaths.has(agent.workdir)) {
+                errors.push(`Agent "${agent.name}" references workdir "${agent.workdir}" which is not defined in paths`);
+            }
+        }
         // 2. Find target workflow
         const workflows = resolved.workflows ?? [];
         const workflow = workflowName ? workflows.find((w) => w.name === workflowName) : workflows[0];
@@ -411,6 +494,12 @@ export class WorkflowRunner {
                 stepAgentCounts.set(step.agent, (stepAgentCounts.get(step.agent) ?? 0) + 1);
             }
         }
+        // Validate workdir references on steps
+        for (const step of resolvedSteps) {
+            if (step.workdir && !dryRunPaths.has(step.workdir)) {
+                errors.push(`Step "${step.name}" references workdir "${step.workdir}" which is not defined in paths`);
+            }
+        }
         // Validate cwd paths
         for (const agent of resolved.agents) {
             if (agent.cwd) {
@@ -499,7 +588,7 @@ export class WorkflowRunner {
             name: a.name,
             cli: a.cli,
             role: a.role,
-            cwd: a.cwd,
+            cwd: a.workdir ? dryRunPaths.get(a.workdir) : a.cwd,
             stepCount: stepAgentCounts.get(a.name) ?? 0,
         }));
         // 5. Simulate execution waves
@@ -775,6 +864,17 @@ export class WorkflowRunner {
     /** Execute a named workflow from a validated config. */
     async execute(config, workflowName, vars) {
         const resolved = vars ? this.resolveVariables(config, vars) : config;
+        // Resolve and validate named paths from the top-level `paths` config
+        const pathResult = this.resolvePathDefinitions(resolved.paths, this.cwd);
+        if (pathResult.errors.length > 0) {
+            throw new Error(`Path validation failed:\n  ${pathResult.errors.join('\n  ')}`);
+        }
+        this.resolvedPaths = pathResult.resolved;
+        if (this.resolvedPaths.size > 0) {
+            for (const [name, abs] of this.resolvedPaths) {
+                console.log(`[workflow] path "${name}" → ${abs}`);
+            }
+        }
         const workflows = resolved.workflows ?? [];
         const workflow = workflowName ? workflows.find((w) => w.name === workflowName) : workflows[0];
         if (!workflow) {
@@ -841,6 +941,12 @@ export class WorkflowRunner {
             throw new Error(`Run "${runId}" is in status "${run.status}" and cannot be resumed`);
         }
         const config = vars ? this.resolveVariables(run.config, vars) : run.config;
+        // Resolve path definitions (same as execute()) so workdir lookups work on resume
+        const pathResult = this.resolvePathDefinitions(config.paths, this.cwd);
+        if (pathResult.errors.length > 0) {
+            throw new Error(`Path validation failed:\n  ${pathResult.errors.join('\n  ')}`);
+        }
+        this.resolvedPaths = pathResult.resolved;
         const workflows = config.workflows ?? [];
         const workflow = workflows.find((w) => w.name === run.workflowName);
         if (!workflow) {
@@ -1386,10 +1492,12 @@ export class WorkflowRunner {
             const value = this.resolveDotPath(key, stepOutputContext);
             return value !== undefined ? String(value) : _match;
         });
+        // Resolve step workdir (named path reference) for deterministic steps
+        const stepCwd = this.resolveStepWorkdir(step) ?? this.cwd;
         try {
             // Delegate to executor if present
             if (this.executor?.executeDeterministicStep) {
-                const result = await this.executor.executeDeterministicStep(step, resolvedCommand, this.cwd);
+                const result = await this.executor.executeDeterministicStep(step, resolvedCommand, stepCwd);
                 const failOnError = step.failOnError !== false;
                 if (failOnError && result.exitCode !== 0) {
                     throw new Error(`Command failed with exit code ${result.exitCode}: ${result.output.slice(0, 500)}`);
@@ -1412,7 +1520,7 @@ export class WorkflowRunner {
             const output = await new Promise((resolve, reject) => {
                 const child = cpSpawn('sh', ['-c', resolvedCommand], {
                     stdio: 'pipe',
-                    cwd: this.cwd,
+                    cwd: stepCwd,
                     env: { ...process.env },
                 });
                 const stdoutChunks = [];
@@ -1527,6 +1635,8 @@ export class WorkflowRunner {
             ? this.interpolateStepTask(step.path, stepOutputContext)
             : path.join('.worktrees', step.name);
         const createBranch = step.createBranch !== false;
+        // Resolve workdir for worktree steps (same as deterministic/agent steps)
+        const stepCwd = this.resolveStepWorkdir(step) ?? this.cwd;
         if (!branch) {
             const errorMsg = 'Worktree step missing required "branch" field';
             await this.markStepFailed(state, errorMsg, runId);
@@ -1535,14 +1645,14 @@ export class WorkflowRunner {
         try {
             // Build the git worktree command
             // If createBranch is true and branch doesn't exist, use -b flag
-            const absoluteWorktreePath = path.resolve(this.cwd, worktreePath);
+            const absoluteWorktreePath = path.resolve(stepCwd, worktreePath);
             // First, check if the branch already exists
             const checkBranchCmd = `git rev-parse --verify --quiet ${branch} 2>/dev/null`;
             let branchExists = false;
             await new Promise((resolve) => {
                 const checkChild = cpSpawn('sh', ['-c', checkBranchCmd], {
                     stdio: 'pipe',
-                    cwd: this.cwd,
+                    cwd: stepCwd,
                     env: { ...process.env },
                 });
                 checkChild.on('close', (code) => {
@@ -1570,7 +1680,7 @@ export class WorkflowRunner {
             const output = await new Promise((resolve, reject) => {
                 const child = cpSpawn('sh', ['-c', worktreeCmd], {
                     stdio: 'pipe',
-                    cwd: this.cwd,
+                    cwd: stepCwd,
                     env: { ...process.env },
                 });
                 const stdoutChunks = [];
@@ -1710,12 +1820,20 @@ export class WorkflowRunner {
                         resolvedTask += nonInteractiveInfo;
                     }
                 }
+                // Apply step-level workdir override to agent definition if present
+                let effectiveAgentDef = agentDef;
+                if (step.workdir) {
+                    const stepWorkdir = this.resolveStepWorkdir(step);
+                    if (stepWorkdir) {
+                        effectiveAgentDef = { ...agentDef, cwd: stepWorkdir, workdir: undefined };
+                    }
+                }
                 // Spawn agent via AgentRelay
-                this.log(`[${step.name}] Spawning agent "${agentDef.name}" (cli: ${agentDef.cli})`);
+                this.log(`[${step.name}] Spawning agent "${effectiveAgentDef.name}" (cli: ${effectiveAgentDef.cli})${step.workdir ? ` [workdir: ${step.workdir}]` : ''}`);
                 const resolvedStep = { ...step, task: resolvedTask };
                 const output = this.executor
-                    ? await this.executor.executeAgentStep(resolvedStep, agentDef, resolvedTask, timeoutMs)
-                    : await this.spawnAndWait(agentDef, resolvedStep, timeoutMs);
+                    ? await this.executor.executeAgentStep(resolvedStep, effectiveAgentDef, resolvedTask, timeoutMs)
+                    : await this.spawnAndWait(effectiveAgentDef, resolvedStep, timeoutMs);
                 this.log(`[${step.name}] Agent "${agentDef.name}" exited`);
                 // Run verification if configured
                 if (step.verification) {
@@ -1882,7 +2000,7 @@ export class WorkflowRunner {
             const output = await new Promise((resolve, reject) => {
                 const child = cpSpawn(cmd, args, {
                     stdio: ['ignore', 'pipe', 'pipe'],
-                    cwd: agentDef.cwd ? path.resolve(this.cwd, agentDef.cwd) : this.cwd,
+                    cwd: this.resolveAgentCwd(agentDef),
                     env: this.getRelayEnv() ?? { ...process.env },
                 });
                 // Update workers.json with PID now that we have it
@@ -2028,6 +2146,7 @@ export class WorkflowRunner {
         let stopHeartbeat;
         let ptyChunks = [];
         try {
+            const agentCwd = this.resolveAgentCwd(agentDef);
             agent = await this.relay.spawnPty({
                 name: agentName,
                 cli: agentDef.cli,
@@ -2036,7 +2155,7 @@ export class WorkflowRunner {
                 channels: agentChannels,
                 task: taskWithExit,
                 idleThresholdSecs: agentDef.constraints?.idleThresholdSecs,
-                cwd: agentDef.cwd ? path.resolve(this.cwd, agentDef.cwd) : undefined,
+                cwd: agentCwd !== this.cwd ? agentCwd : undefined,
             });
             // Re-key PTY maps if broker assigned a different name than requested
             if (agent.name !== agentName) {