agent-relay 4.0.0 → 4.0.2

package/packages/sdk/src/workflows/__tests__/template-resolver.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it } from 'vitest';
+
+// Import from the module that will be extracted from runner.ts
+import { resolveStepOutputRef, resolveTemplate, TemplateResolver } from '../template-resolver.js';
+
+describe('TemplateResolver', () => {
+  const resolver = new TemplateResolver();
+
+  describe('resolveTemplate', () => {
+    it('replaces non-step placeholders and preserves deferred step outputs', () => {
+      const result = resolveTemplate('Deploy {{env}} after {{steps.plan.output}}', { env: 'prod' });
+      expect(result).toBe('Deploy prod after {{steps.plan.output}}');
+    });
+
+    it('throws on unresolved placeholders', () => {
+      expect(() => resolveTemplate('Deploy {{missing}}', {})).toThrow('Unresolved variable: {{missing}}');
+    });
+  });
+
+  describe('resolveStepOutputRef', () => {
+    it('resolves a completed step output by reference', () => {
+      const stepOutputs = new Map([['plan', 'Build a REST API']]);
+      expect(resolveStepOutputRef('steps.plan.output', stepOutputs)).toBe('Build a REST API');
+    });
+
+    it('accepts references wrapped in template braces', () => {
+      const stepOutputs = new Map([['code', 'Created 3 files']]);
+      expect(resolveStepOutputRef('{{steps.code.output}}', stepOutputs)).toBe('Created 3 files');
+    });
+  });
+
+  describe('resolveVariables', () => {
+    it('replaces simple {{var}} placeholders in agent tasks', () => {
+      const config = {
+        version: '1',
+        name: 'test',
+        swarm: { mode: 'coordinate' as const },
+        agents: [{ name: 'a1', cli: 'claude', task: 'Deploy {{env}} to {{region}}' }],
+      };
+      const result = resolver.resolveVariables(config as any, { env: 'staging', region: 'us-east-1' });
+      expect(result.agents[0].task).toBe('Deploy staging to us-east-1');
+    });
+
+    it('replaces variables in workflow step tasks and commands', () => {
+      const config = {
+        version: '1',
+        name: 'test',
+        swarm: { mode: 'coordinate' as const },
+        agents: [],
+        workflows: [
+          {
+            name: 'wf1',
+            steps: [
+              { name: 's1', task: 'Build {{project}}', agent: 'a1' },
+              { name: 's2', command: 'deploy --env={{env}}' },
+            ],
+          },
+        ],
+      };
+      const result = resolver.resolveVariables(config as any, { project: 'relay', env: 'prod' });
+      expect(result.workflows![0].steps[0].task).toBe('Build relay');
+      expect(result.workflows![0].steps[1].command).toBe('deploy --env=prod');
+    });
+
+    it('replaces variables in step params', () => {
+      const config = {
+        version: '1',
+        name: 'test',
+        swarm: { mode: 'coordinate' as const },
+        agents: [],
+        workflows: [
+          {
+            name: 'wf1',
+            steps: [{ name: 's1', agent: 'a1', params: { url: '{{base_url}}/api', count: 42 } }],
+          },
+        ],
+      };
+      const result = resolver.resolveVariables(config as any, { base_url: 'https://example.com' });
+      expect((result.workflows![0].steps[0].params as any).url).toBe('https://example.com/api');
+      // Non-string params are left untouched
+      expect((result.workflows![0].steps[0].params as any).count).toBe(42);
+    });
+
+    it('preserves {{steps.X.output}} placeholders for later resolution', () => {
+      const config = {
+        version: '1',
+        name: 'test',
+        swarm: { mode: 'coordinate' as const },
+        agents: [{ name: 'a1', cli: 'claude', task: 'Use {{steps.plan.output}} for {{env}}' }],
+      };
+      const result = resolver.resolveVariables(config as any, { env: 'prod' });
+      expect(result.agents[0].task).toBe('Use {{steps.plan.output}} for prod');
+    });
+
+    it('throws on unresolved non-step variables', () => {
+      const config = {
+        version: '1',
+        name: 'test',
+        swarm: { mode: 'coordinate' as const },
+        agents: [{ name: 'a1', cli: 'claude', task: 'Deploy to {{missing_var}}' }],
+      };
+      expect(() => resolver.resolveVariables(config as any, {})).toThrow('Unresolved variable: {{missing_var}}');
+    });
+
+    it('does not mutate the original config', () => {
+      const config = {
+        version: '1',
+        name: 'test',
+        swarm: { mode: 'coordinate' as const },
+        agents: [{ name: 'a1', cli: 'claude', task: 'Deploy {{env}}' }],
+      };
+      resolver.resolveVariables(config as any, { env: 'staging' });
+      expect(config.agents[0].task).toBe('Deploy {{env}}');
+    });
+  });
+
+  describe('resolveDotPath', () => {
+    it('resolves nested dot-path variables', () => {
+      const config = {
+        version: '1',
+        name: 'test',
+        swarm: { mode: 'coordinate' as const },
+        agents: [{ name: 'a1', cli: 'claude', task: 'Region: {{aws.region}}' }],
+      };
+      const vars = { aws: { region: 'us-west-2' } } as any;
+      const result = resolver.resolveVariables(config as any, vars);
+      expect(result.agents[0].task).toBe('Region: us-west-2');
+    });
+
+    it('throws for undefined nested paths', () => {
+      const config = {
+        version: '1',
+        name: 'test',
+        swarm: { mode: 'coordinate' as const },
+        agents: [{ name: 'a1', cli: 'claude', task: '{{a.b.c}}' }],
+      };
+      expect(() => resolver.resolveVariables(config as any, { a: { b: {} } } as any)).toThrow(
+        'Unresolved variable: {{a.b.c}}'
+      );
+    });
+  });
+
+  describe('interpolateStepTask', () => {
+    it('resolves step output references from completed steps', () => {
+      const template = 'Review: {{steps.plan.output}} and {{steps.code.output}}';
+      const context = {
+        steps: {
+          plan: { output: 'Build a REST API' },
+          code: { output: 'Created 3 files' },
+        },
+      } as any;
+      const result = resolver.interpolateStepTask(template, context);
+      expect(result).toBe('Review: Build a REST API and Created 3 files');
+    });
+
+    it('leaves unresolved step references intact', () => {
+      const template = 'Use {{steps.future.output}} later';
+      const result = resolver.interpolateStepTask(template, { steps: {} } as any);
+      expect(result).toBe('Use {{steps.future.output}} later');
+    });
+  });
+});

package/packages/sdk/src/workflows/__tests__/verification.test.ts

@@ -0,0 +1,229 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+// The module under test — does not exist yet (red phase).
+import {
+  runVerification,
+  stripInjectedTaskEcho,
+  checkOutputContains,
+  checkFileExists,
+  type VerificationCheck,
+  type VerificationResult,
+  type VerificationOptions,
+  WorkflowCompletionError,
+} from '../verification.js';
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+const noopSideEffects = {
+  recordStepToolSideEffect: vi.fn(),
+  getOrCreateStepEvidenceRecord: vi.fn(() => ({
+    evidence: { coordinationSignals: [] },
+  })),
+  log: vi.fn(),
+};
+
+function run(
+  check: VerificationCheck,
+  output: string,
+  stepName = 'test-step',
+  options?: VerificationOptions
+): VerificationResult {
+  return runVerification(check, output, stepName, undefined, options, noopSideEffects);
+}
+
+// ── tests ─────────────────────────────────────────────────────────────────────
+
+describe('verification logic', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  // 1. exit_code — pass on exit 0 (implicit success)
+  describe('exit_code', () => {
+    it('should pass when agent exited successfully (exit 0 implicit)', () => {
+      const result = run({ type: 'exit_code', value: '0' }, 'some output');
+      expect(result.passed).toBe(true);
+      expect(result.completionReason).toBe('completed_verified');
+    });
+
+    it('should still pass for non-zero value (exit_code is implicitly satisfied)', () => {
+      // per existing logic, exit_code case is a no-op — always passes if we reach it
+      const result = run({ type: 'exit_code', value: '1' }, 'output');
+      expect(result.passed).toBe(true);
+    });
+  });
+
+  // 2. output_contains — case-sensitive substring match
+  describe('output_contains', () => {
+    it('should pass when output contains the token', () => {
+      const result = run(
+        { type: 'output_contains', value: 'BUILD_SUCCESS' },
+        'Starting build...\nBUILD_SUCCESS\nDone.'
+      );
+      expect(result.passed).toBe(true);
+      expect(result.completionReason).toBe('completed_verified');
+    });
+
+    it('should fail when output does not contain the token', () => {
+      expect(() => run({ type: 'output_contains', value: 'BUILD_SUCCESS' }, 'build failed')).toThrow(
+        WorkflowCompletionError
+      );
+    });
+
+    it('should be case-sensitive', () => {
+      expect(() => run({ type: 'output_contains', value: 'BUILD_SUCCESS' }, 'build_success')).toThrow(
+        WorkflowCompletionError
+      );
+    });
+
+    it('should return failure result instead of throwing when allowFailure is set', () => {
+      const result = run({ type: 'output_contains', value: 'MISSING' }, 'no match here', 'test-step', {
+        allowFailure: true,
+      });
+      expect(result.passed).toBe(false);
+      expect(result.completionReason).toBe('failed_verification');
+      expect(result.error).toContain('MISSING');
+    });
+  });
+
+  // 3. file_exists — checks file presence at path
+  describe('file_exists', () => {
+    let tmpDir: string;
+    let tmpFile: string;
+
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'verify-test-'));
+      tmpFile = path.join(tmpDir, 'artifact.txt');
+    });
+
+    afterEach(() => {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('should pass when the file exists', () => {
+      fs.writeFileSync(tmpFile, 'content');
+      // file_exists resolves relative to cwd; pass absolute path as value
+      const result = run({ type: 'file_exists', value: tmpFile }, '');
+      expect(result.passed).toBe(true);
+    });
+
+    it('should fail when the file does not exist', () => {
+      expect(() => run({ type: 'file_exists', value: path.join(tmpDir, 'nope.txt') }, '')).toThrow(
+        WorkflowCompletionError
+      );
+    });
+  });
+
+  // 4. custom verification — returns { passed: false } (no-op in runner)
+  describe('custom', () => {
+    it('should return passed: false (delegated to caller)', () => {
+      const result = run({ type: 'custom', value: 'anything' }, 'output');
+      expect(result.passed).toBe(false);
+    });
+  });
+
+  // 5. Invalid/unknown verification type — falls through gracefully
+  describe('unknown type', () => {
+    it('should fall through and pass for unknown verification types', () => {
+      const result = run({ type: 'nonexistent' as VerificationCheck['type'], value: 'x' }, 'output');
+      // falls through the switch with no match, reaches success path
+      expect(result.passed).toBe(true);
+    });
+  });
+
+  // 6. completionMarkerFound option
+  describe('completionMarkerFound option', () => {
+    it('should log legacy marker message when completionMarkerFound is false', () => {
+      const result = run({ type: 'exit_code', value: '0' }, 'output', 'my-step', {
+        completionMarkerFound: false,
+      });
+      expect(result.passed).toBe(true);
+      expect(noopSideEffects.log).toHaveBeenCalledWith(
+        expect.stringContaining('without legacy STEP_COMPLETE marker')
+      );
+    });
+  });
+
+  // 7. stripInjectedTaskEcho
+  describe('stripInjectedTaskEcho', () => {
+    it('should return output unchanged when no injectedTaskText', () => {
+      expect(stripInjectedTaskEcho('hello world')).toBe('hello world');
+      expect(stripInjectedTaskEcho('hello world', undefined)).toBe('hello world');
+    });
+
+    it('should strip the injected task text from output', () => {
+      const task = 'Please run the build';
+      const output = 'Starting...\nPlease run the build\nBUILD_SUCCESS';
+      expect(stripInjectedTaskEcho(output, task)).toBe('Starting...\n\nBUILD_SUCCESS');
+    });
+
+    it('should handle CRLF normalization', () => {
+      const task = 'Run task\r\nwith newlines';
+      const output = 'prefix Run task\nwith newlines suffix';
+      expect(stripInjectedTaskEcho(output, task)).toBe('prefix  suffix');
+    });
+
+    it('should handle LF to CRLF normalization', () => {
+      const task = 'Run task\nwith newlines';
+      const output = 'prefix Run task\r\nwith newlines suffix';
+      expect(stripInjectedTaskEcho(output, task)).toBe('prefix  suffix');
+    });
+
+    it('should return output unchanged when task text is not found', () => {
+      expect(stripInjectedTaskEcho('output text', 'not present')).toBe('output text');
+    });
+
+    it('should handle empty injected task text', () => {
+      expect(stripInjectedTaskEcho('output', '')).toBe('output');
+    });
+  });
+
+  // 8. checkOutputContains with injectedTaskText
+  describe('checkOutputContains with injectedTaskText', () => {
+    it('should not match token that only appears in injected task echo', () => {
+      const task = 'Verify BUILD_SUCCESS appears';
+      const output = 'Verify BUILD_SUCCESS appears\nDone.';
+      expect(checkOutputContains(output, 'BUILD_SUCCESS', task)).toBe(false);
+    });
+
+    it('should match token that appears outside injected task echo', () => {
+      const task = 'Run the build';
+      const output = 'Run the build\nBUILD_SUCCESS';
+      expect(checkOutputContains(output, 'BUILD_SUCCESS', task)).toBe(true);
+    });
+
+    it('should return false for empty token', () => {
+      expect(checkOutputContains('anything', '', undefined)).toBe(false);
+    });
+  });
+
+  // 9. checkFileExists path traversal protection
+  describe('checkFileExists path traversal', () => {
+    let tmpDir: string;
+
+    beforeEach(() => {
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'verify-traversal-'));
+    });
+
+    afterEach(() => {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it('should reject path traversal with ../', () => {
+      expect(checkFileExists('../../etc/passwd', tmpDir)).toBe(false);
+    });
+
+    it('should reject relative path with .. that resolves outside cwd', () => {
+      expect(checkFileExists('../../../etc/passwd', tmpDir)).toBe(false);
+    });
+
+    it('should allow files within cwd', () => {
+      const file = path.join(tmpDir, 'ok.txt');
+      fs.writeFileSync(file, 'ok');
+      expect(checkFileExists('ok.txt', tmpDir)).toBe(true);
+    });
+  });
+});

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

@@ -20,10 +20,11 @@ import type {
   WorkflowRunRow,
   WorkflowStep,
 } from './types.js';
-import { WorkflowRunner, type WorkflowEventListener, type VariableContext, type StepExecutor } from './runner.js';
+import { WorkflowRunner, type WorkflowEventListener, type RunnerStepExecutor } from './runner.js';
 import { formatDryRunReport } from './dry-run-format.js';
 import { createDefaultEventLogger, type LogLevel } from './default-logger.js';
 import { runInCloud, type CloudRunOptions } from './cloud-runner.js';
+import type { VariableContext } from './template-resolver.js';
 
 // ── Option types for the builder API ────────────────────────────────────────
 
@@ -105,7 +106,7 @@ export interface WorkflowRunOptions {
   /** Validate and print execution plan without spawning agents. */
   dryRun?: boolean;
   /** External step executor (e.g. Daytona sandbox backend). */
-  executor?: StepExecutor;
+  executor?: RunnerStepExecutor;
   /** Start from a specific step, skipping all predecessors. */
   startFrom?: string;
   /** Previous run ID whose cached outputs are used with startFrom. */
@@ -196,7 +197,7 @@ export class WorkflowBuilder {
     if (!CHANNEL_RE.test(ch)) {
       throw new Error(
         `Invalid channel name "${ch}". Channel names must be lowercase alphanumeric and hyphens, starting with a letter or number. ` +
-        `Fix: use .toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '')`
+          `Fix: use .toLowerCase().replace(/[^a-z0-9-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '')`
       );
     }
     this._channel = ch;
@@ -419,9 +420,8 @@ export class WorkflowBuilder {
     // Wire up default console logger unless explicitly disabled
     // renderer: "listr" owns the terminal — skip console logger to avoid garbled output
     // renderer: false implies no output at all
-    const logLevel = options.renderer === 'listr' || options.renderer === false
-      ? false
-      : (options.logLevel ?? 'normal');
+    const logLevel =
+      options.renderer === 'listr' || options.renderer === false ? false : (options.logLevel ?? 'normal');
     if (logLevel !== false) {
       runner.on(createDefaultEventLogger(logLevel));
     }