agent-relay 3.2.2 → 3.2.4

package/packages/sdk/src/examples/workflows/fix-dashboard-user-registration.yaml

@@ -0,0 +1,182 @@
+version: '1.0'
+name: fix-dashboard-user-registration
+description: >
+  Fixes the dashboard agent registration so the user registers as the current
+  system user (whoami / os.userInfo().username) instead of the cwd directory name.
+
+  Currently, both relaycast-provider.ts and proxy-server.ts in relay-dashboard
+  derive projectIdentity from path.basename(path.resolve(dataDir, '..')) — which
+  gives the working directory name. This workflow changes both to use
+  os.userInfo().username so the registered name reflects the actual user.
+
+swarm:
+  pattern: pipeline
+  channel: wf-fix-dashboard-user-reg
+  maxConcurrency: 3
+  timeoutMs: 1200000 # 20 min
+
+agents:
+  - name: implementer
+    cli: claude
+    preset: worker
+    role: 'Makes targeted edits to two dashboard-server files to use os.userInfo().username instead of path.basename(cwd).'
+    constraints:
+      model: sonnet
+
+  - name: reviewer
+    cli: claude
+    preset: reviewer
+    role: 'Reviews the diff to confirm correctness and no unintended side effects.'
+    constraints:
+      model: sonnet
+
+workflows:
+  - name: default
+    onError: fail-fast
+
+    steps:
+      # ── Phase 1: Capture current code for context injection ──────────────────
+
+      - name: read-relaycast-provider
+        type: deterministic
+        command: >
+          sed -n '1,15p' ../relay-dashboard/packages/dashboard-server/src/relaycast-provider.ts &&
+          echo "---" &&
+          sed -n '80,100p' ../relay-dashboard/packages/dashboard-server/src/relaycast-provider.ts
+        captureOutput: true
+        failOnError: true
+
+      - name: read-proxy-server
+        type: deterministic
+        command: >
+          grep -n "^import" ../relay-dashboard/packages/dashboard-server/src/proxy-server.ts | head -20 &&
+          echo "---" &&
+          sed -n '205,220p' ../relay-dashboard/packages/dashboard-server/src/proxy-server.ts
+        captureOutput: true
+        failOnError: true
+
+      # ── Phase 2: Implement the fix ───────────────────────────────────────────
+
+      - name: implement
+        type: agent
+        agent: implementer
+        dependsOn: [read-relaycast-provider, read-proxy-server]
+        task: |
+          Fix two files in the relay-dashboard package so the dashboard user registers
+          with the system username instead of the cwd directory name.
+
+          ── File 1: ../relay-dashboard/packages/dashboard-server/src/relaycast-provider.ts ──
+
+          Current imports and loadRelaycastConfig function:
+          {{steps.read-relaycast-provider.output}}
+
+          Changes required:
+          1. Add `import os from 'node:os';` after the existing `import path from 'path';` line.
+          2. In the `loadRelaycastConfig` function, replace:
+               const projectDir = path.basename(path.resolve(dataDir, '..'));
+             with:
+               const projectIdentity = os.userInfo().username;
+          3. Remove the line `const projectIdentity = projectDir.trim();` (it's now set above).
+          4. The return statement `return { apiKey: envApiKey, baseUrl, projectIdentity };` stays the same.
+
+          ── File 2: ../relay-dashboard/packages/dashboard-server/src/proxy-server.ts ──
+
+          Current imports and resolveRelaycastConfig function:
+          {{steps.read-proxy-server.output}}
+
+          Changes required:
+          1. Add `import os from 'node:os';` near the top of the file with the other imports.
+          2. In the `resolveRelaycastConfig` function, replace:
+               const projectDir = path.basename(path.resolve(dataDir, '..'));
+             with:
+               const projectIdentity = os.userInfo().username;
+          3. Update the `applyCachedAgentIdentity` call: change `projectIdentity: projectDir`
+             to `projectIdentity: projectIdentity` (variable is already named correctly).
+
+          IMPORTANT:
+          - Write both files to disk using your file-writing tools.
+          - Use `import os from 'node:os'` (Node.js built-in with node: prefix).
+          - Do not change anything else in either file.
+          - Preserve all existing imports, logic, and formatting.
+        verification:
+          type: exit_code
+
+      # ── Phase 3: Verify the changes look correct ─────────────────────────────
+
+      - name: verify-changes
+        type: deterministic
+        dependsOn: [implement]
+        command: |
+          echo "=== relaycast-provider.ts: os import ==="
+          grep -n "import os\|node:os" ../relay-dashboard/packages/dashboard-server/src/relaycast-provider.ts || echo "MISSING: os import"
+
+          echo ""
+          echo "=== relaycast-provider.ts: loadRelaycastConfig ==="
+          sed -n '85,96p' ../relay-dashboard/packages/dashboard-server/src/relaycast-provider.ts
+
+          echo ""
+          echo "=== proxy-server.ts: os import ==="
+          grep -n "import os\|node:os" ../relay-dashboard/packages/dashboard-server/src/proxy-server.ts || echo "MISSING: os import"
+
+          echo ""
+          echo "=== proxy-server.ts: resolveRelaycastConfig ==="
+          grep -n -A8 "const resolveRelaycastConfig" ../relay-dashboard/packages/dashboard-server/src/proxy-server.ts | head -15
+
+          echo ""
+          echo "=== Confirm no remaining path.basename(.*dataDir) calls ==="
+          grep -n "path.basename.*dataDir\|basename.*resolve.*dataDir" \
+            ../relay-dashboard/packages/dashboard-server/src/relaycast-provider.ts \
+            ../relay-dashboard/packages/dashboard-server/src/proxy-server.ts && echo "WARN: stale cwd reference found" || echo "OK: no stale cwd references"
+        captureOutput: true
+        failOnError: false
+
+      # ── Phase 4: Capture diff for review ─────────────────────────────────────
+
+      - name: capture-diff
+        type: deterministic
+        dependsOn: [verify-changes]
+        command: >
+          cd ../relay-dashboard &&
+          git diff packages/dashboard-server/src/relaycast-provider.ts
+          packages/dashboard-server/src/proxy-server.ts
+        captureOutput: true
+        failOnError: false
+
+      # ── Phase 5: Code review ──────────────────────────────────────────────────
+
+      - name: review
+        type: agent
+        agent: reviewer
+        dependsOn: [capture-diff, verify-changes]
+        task: |
+          Review this change to the relay-dashboard dashboard-server package.
+
+          The goal: dashboard user now registers with os.userInfo().username (the system user
+          running the process) instead of path.basename(cwd) (the working directory name).
+
+          Verification output:
+          {{steps.verify-changes.output}}
+
+          Diff:
+          {{steps.capture-diff.output}}
+
+          Review checklist:
+          1. Both files now import `os` from `'node:os'` — correct prefix?
+          2. `os.userInfo().username` is used in both `loadRelaycastConfig` and
+             `resolveRelaycastConfig` — no leftover `path.basename` / `projectDir` references?
+          3. The `projectIdentity` variable name is preserved in both call sites?
+          4. No unintended whitespace, import order, or formatting changes?
+          5. The `path` import in relaycast-provider.ts is still present if used elsewhere in the file?
+
+errorHandling:
+  strategy: fail-fast
+  maxRetries: 1
+  retryDelayMs: 5000
+
+state:
+  backend: memory
+  ttlMs: 3600000 # 1 hour
+
+trajectories:
+  enabled: true
+  autoDecisions: true

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

@@ -5,13 +5,18 @@ import type {
   AgentCli,
   AgentDefinition,
   AgentPreset,
+  Barrier,
+  CoordinationConfig,
   DryRunReport,
   ErrorHandlingConfig,
   IdleNudgeConfig,
   RelayYamlConfig,
+  StateConfig,
   SwarmPattern,
+  TrajectoryConfig,
   VerificationCheck,
   WorkflowDefinition,
+  WorkflowExecuteOptions,
   WorkflowRunRow,
   WorkflowStep,
 } from './types.js';
@@ -52,15 +57,27 @@ export interface AgentStepOptions {
 export interface DeterministicStepOptions {
   type: 'deterministic';
   command: string;
-  dependsOn?: string[];
-  /** Fail if command exit code is non-zero. Default: true. */
-  failOnError?: boolean;
   /** Capture stdout as step output for downstream steps. Default: true. */
   captureOutput?: boolean;
+  /** Fail if command exit code is non-zero. Default: true. */
+  failOnError?: boolean;
+  dependsOn?: string[];
+  verification?: VerificationCheck;
   timeoutMs?: number;
 }
 
-export type StepOptions = AgentStepOptions | DeterministicStepOptions;
+/** Options for worktree steps (create/checkout git worktrees). */
+export interface WorktreeStepOptions {
+  type: 'worktree';
+  branch: string;
+  baseBranch?: string;
+  path?: string;
+  createBranch?: boolean;
+  dependsOn?: string[];
+  timeoutMs?: number;
+}
+
+export type StepOptions = AgentStepOptions | DeterministicStepOptions | WorktreeStepOptions;
 
 export interface ErrorOptions {
   maxRetries?: number;
@@ -83,6 +100,10 @@ export interface WorkflowRunOptions {
   dryRun?: boolean;
   /** External step executor (e.g. Daytona sandbox backend). */
   executor?: StepExecutor;
+  /** Start from a specific step, skipping all predecessors. */
+  startFrom?: string;
+  /** Previous run ID whose cached outputs are used with startFrom. */
+  previousRunId?: string;
 }
 
 // ── WorkflowBuilder ─────────────────────────────────────────────────────────
@@ -113,6 +134,11 @@ export class WorkflowBuilder {
   private _agents: AgentDefinition[] = [];
   private _steps: WorkflowStep[] = [];
   private _errorHandling?: ErrorHandlingConfig;
+  private _coordination?: CoordinationConfig;
+  private _state?: StateConfig;
+  private _trajectories?: TrajectoryConfig | false;
+  private _startFrom?: string;
+  private _previousRunId?: string;
 
   constructor(name: string) {
     this._name = name;
@@ -154,6 +180,36 @@ export class WorkflowBuilder {
     return this;
   }
 
+  /** Set workflow coordination settings (barriers, voting threshold, consensus strategy). */
+  coordination(config: CoordinationConfig): this {
+    this._coordination = config;
+    return this;
+  }
+
+  /** Configure shared workflow state backend settings. */
+  state(config: StateConfig): this {
+    this._state = config;
+    return this;
+  }
+
+  /** Configure trajectory recording, or pass `false` to disable it. */
+  trajectories(config: TrajectoryConfig | false): this {
+    this._trajectories = config;
+    return this;
+  }
+
+  /** Start execution from a specific step, skipping all predecessor steps. */
+  startFrom(stepName: string): this {
+    this._startFrom = stepName;
+    return this;
+  }
+
+  /** Set the previous run ID whose cached step outputs should be used with startFrom. */
+  previousRunId(id: string): this {
+    this._previousRunId = id;
+    return this;
+  }
+
   /** Add an agent definition. */
   agent(name: string, options: AgentOptions): this {
     const def: AgentDefinition = {
@@ -192,21 +248,44 @@ export class WorkflowBuilder {
     const step: WorkflowStep = { name };
 
     if ('type' in options && options.type === 'deterministic') {
+      if (!options.command) {
+        throw new Error('deterministic steps must have a command');
+      }
+      if ('agent' in options || 'task' in options) {
+        throw new Error('deterministic steps must not have agent or task');
+      }
       step.type = 'deterministic';
       step.command = options.command;
-      if (options.failOnError !== undefined) step.failOnError = options.failOnError;
       if (options.captureOutput !== undefined) step.captureOutput = options.captureOutput;
+      if (options.failOnError !== undefined) step.failOnError = options.failOnError;
+      if (options.dependsOn !== undefined) step.dependsOn = options.dependsOn;
+      if (options.verification !== undefined) step.verification = options.verification;
+      if (options.timeoutMs !== undefined) step.timeoutMs = options.timeoutMs;
+    } else if ('type' in options && options.type === 'worktree') {
+      if ('agent' in options || 'task' in options) {
+        throw new Error('worktree steps must not have agent or task');
+      }
+      step.type = 'worktree';
+      step.branch = options.branch;
+      if (options.baseBranch !== undefined) step.baseBranch = options.baseBranch;
+      if (options.path !== undefined) step.path = options.path;
+      if (options.createBranch !== undefined) step.createBranch = options.createBranch;
+      if (options.dependsOn !== undefined) step.dependsOn = options.dependsOn;
+      if (options.timeoutMs !== undefined) step.timeoutMs = options.timeoutMs;
     } else {
+      // Agent step
       const agentOpts = options as AgentStepOptions;
+      if (!agentOpts.agent || !agentOpts.task) {
+        throw new Error('Agent steps must have both agent and task');
+      }
       step.agent = agentOpts.agent;
       step.task = agentOpts.task;
+      if (agentOpts.dependsOn !== undefined) step.dependsOn = agentOpts.dependsOn;
       if (agentOpts.verification !== undefined) step.verification = agentOpts.verification;
+      if (agentOpts.timeoutMs !== undefined) step.timeoutMs = agentOpts.timeoutMs;
       if (agentOpts.retries !== undefined) step.retries = agentOpts.retries;
     }
 
-    if (options.dependsOn !== undefined) step.dependsOn = options.dependsOn;
-    if (options.timeoutMs !== undefined) step.timeoutMs = options.timeoutMs;
-
     this._steps.push(step);
     return this;
   }
@@ -251,6 +330,9 @@ export class WorkflowBuilder {
     if (this._channel !== undefined) config.swarm.channel = this._channel;
     if (this._idleNudge !== undefined) config.swarm.idleNudge = this._idleNudge;
     if (this._errorHandling !== undefined) config.errorHandling = this._errorHandling;
+    if (this._coordination !== undefined) config.coordination = this._coordination;
+    if (this._state !== undefined) config.state = this._state;
+    if (this._trajectories !== undefined) config.trajectories = this._trajectories;
 
     return config;
   }
@@ -285,7 +367,13 @@ export class WorkflowBuilder {
       runner.on(options.onEvent);
     }
 
-    return runner.execute(config, options.workflow, options.vars);
+    const startFrom = this._startFrom ?? options.startFrom;
+    const previousRunId = this._previousRunId ?? options.previousRunId;
+    const executeOptions: WorkflowExecuteOptions | undefined = startFrom
+      ? { startFrom, previousRunId }
+      : undefined;
+
+    return runner.execute(config, options.workflow, options.vars, executeOptions);
   }
 }
 

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

@@ -28,6 +28,8 @@ Arguments:
 Options:
   --workflow <name>        Run a specific workflow by name (default: first)
   --resume <run-id>        Resume a failed or interrupted run by its run ID
+  --start-from <step>      Start from a specific step, skipping predecessors
+  --previous-run-id <id>   Use cached outputs from a specific prior run (with --start-from)
   --validate               Validate workflow YAML for common issues without running
   --help                   Show this help message
 
@@ -136,6 +138,18 @@ async function main(): Promise<void> {
     workflowName = args[workflowIdx + 1];
   }
 
+  let startFromStep: string | undefined;
+  const startFromIdx = args.indexOf('--start-from');
+  if (startFromIdx !== -1 && args[startFromIdx + 1]) {
+    startFromStep = args[startFromIdx + 1];
+  }
+
+  let previousRunId: string | undefined;
+  const prevRunIdx = args.indexOf('--previous-run-id');
+  if (prevRunIdx !== -1 && args[prevRunIdx + 1]) {
+    previousRunId = args[prevRunIdx + 1];
+  }
+
   const isValidate = args.includes('--validate');
 
   console.log(`Running workflow from ${yamlPath}...`);
@@ -157,7 +171,8 @@ async function main(): Promise<void> {
   }
 
   runner.on((event) => console.log(formatEvent(event)));
-  const result = await runner.execute(config, workflowName);
+  const executeOptions = startFromStep ? { startFrom: startFromStep, previousRunId } : undefined;
+  const result = await runner.execute(config, workflowName, undefined, executeOptions);
 
   if (result.status === 'completed') {
     console.log(`\nWorkflow completed successfully.`);

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

@@ -59,6 +59,7 @@ import type {
   WorkflowRunRow,
   WorkflowRunStatus,
   WorkflowStep,
+  WorkflowExecuteOptions,
   WorkflowStepCompletionReason,
   WorkflowStepRow,
   WorkflowStepStatus,
@@ -1778,7 +1779,8 @@ export class WorkflowRunner {
   async execute(
     config: RelayYamlConfig,
     workflowName?: string,
-    vars?: VariableContext
+    vars?: VariableContext,
+    executeOptions?: WorkflowExecuteOptions
   ): Promise<WorkflowRunRow> {
     // Set up abort controller early so callers can abort() even during setup
     this.abortController = new AbortController();
@@ -1861,6 +1863,49 @@ export class WorkflowRunner {
       stepStates.set(step.name, { row: stepRow });
     }
 
+    // Handle startFrom: skip all transitive dependencies of the target step
+    if (executeOptions?.startFrom) {
+      const startFromName = executeOptions.startFrom;
+      const stepNames = new Set(resolvedWorkflow.steps.map((s) => s.name));
+      if (!stepNames.has(startFromName)) {
+        throw new Error(
+          `startFrom step "${startFromName}" not found in workflow. Available steps: ${[...stepNames].join(', ')}`
+        );
+      }
+
+      const transitiveDeps = this.collectTransitiveDeps(startFromName, resolvedWorkflow.steps);
+      const skippedCount = transitiveDeps.size;
+
+      // Determine which run ID to load cached outputs from
+      const cacheRunId = executeOptions.previousRunId
+        ?? this.findMostRecentRunWithSteps(transitiveDeps);
+
+      for (const depName of transitiveDeps) {
+        const state = stepStates.get(depName);
+        if (!state) continue;
+
+        // Load cached output from a previous run if available
+        const cachedOutput = cacheRunId ? this.loadStepOutput(cacheRunId, depName) : undefined;
+        if (!cachedOutput) {
+          this.log(`[startFrom] No cached output for skipped step "${depName}" — using empty string`);
+        }
+
+        state.row.status = 'completed';
+        state.row.output = cachedOutput ?? '';
+        state.row.completedAt = now;
+        await this.db.updateStep(state.row.id, {
+          status: 'completed',
+          output: state.row.output,
+          completedAt: now,
+          updatedAt: now,
+        });
+      }
+
+      if (skippedCount > 0) {
+        this.log(`[startFrom] Skipping ${skippedCount} steps, starting from "${startFromName}"`);
+      }
+    }
+
     return this.runWorkflowCore({
       run,
       workflow: resolvedWorkflow,
@@ -5719,6 +5764,35 @@ export class WorkflowRunner {
     }
   }
 
+  // ── startFrom dependency resolution ─────────────────────────────────
+
+  /**
+   * Walk the dependsOn graph backwards from a target step to collect ALL
+   * transitive dependencies (i.e. every step that must complete before
+   * the target step can run). The target step itself is NOT included.
+   */
+  private collectTransitiveDeps(targetStep: string, steps: WorkflowStep[]): Set<string> {
+    const stepMap = new Map<string, WorkflowStep>();
+    for (const s of steps) stepMap.set(s.name, s);
+
+    const deps = new Set<string>();
+    const queue = [...(stepMap.get(targetStep)?.dependsOn ?? [])];
+
+    while (queue.length > 0) {
+      const current = queue.shift()!;
+      if (deps.has(current)) continue;
+      deps.add(current);
+      const step = stepMap.get(current);
+      if (step?.dependsOn) {
+        for (const dep of step.dependsOn) {
+          if (!deps.has(dep)) queue.push(dep);
+        }
+      }
+    }
+
+    return deps;
+  }
+
   // ── Control flow helpers ──────────────────────────────────────────────
 
   private checkAborted(): void {
@@ -6203,6 +6277,41 @@ export class WorkflowRunner {
     this.postToChannel(`**[${stepName}] Output:**\n\`\`\`\n${preview}\n\`\`\``, { stepName });
   }
 
+  /** Scan .agent-relay/step-outputs/ for the most recent run directory containing the needed steps. */
+  private findMostRecentRunWithSteps(stepNames: Set<string>): string | undefined {
+    try {
+      const baseDir = path.join(this.cwd, '.agent-relay', 'step-outputs');
+      if (!existsSync(baseDir)) return undefined;
+
+      const entries = readdirSync(baseDir);
+      let best: { name: string; mtime: number } | undefined;
+
+      for (const entry of entries) {
+        const dirPath = path.join(baseDir, entry);
+        try {
+          const stat = statSync(dirPath);
+          if (!stat.isDirectory()) continue;
+
+          // Check if this directory has at least one of the needed step files
+          const hasAny = [...stepNames].some(name =>
+            existsSync(path.join(dirPath, `${name}.md`))
+          );
+          if (!hasAny) continue;
+
+          if (!best || stat.mtimeMs > best.mtime) {
+            best = { name: entry, mtime: stat.mtimeMs };
+          }
+        } catch {
+          continue;
+        }
+      }
+
+      return best?.name;
+    } catch {
+      return undefined;
+    }
+  }
+
   /** Load persisted step output from disk. */
   private loadStepOutput(runId: string, stepName: string): string | undefined {
     try {

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

@@ -502,6 +502,20 @@ export interface DryRunReport {
   estimatedTotalAgentSteps?: number;
 }
 
+// ── Workflow execution options ───────────────────────────────────────────────
+
+/** Options that control how a workflow run executes. */
+export interface WorkflowExecuteOptions {
+  /** Start execution from a specific step, skipping all predecessor steps.
+   *  Predecessor outputs are loaded from cached step-outputs on disk when available. */
+  startFrom?: string;
+  /** Run ID of a previous execution whose cached step outputs should be used
+   *  when skipping predecessor steps via `startFrom`. If omitted, the runner
+   *  scans `.agent-relay/step-outputs/` for the most recent directory that
+   *  contains the needed step files. */
+  previousRunId?: string;
+}
+
 // ── Database row types ──────────────────────────────────────────────────────
 
 export type WorkflowRunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';

package/packages/sdk/tsconfig.build.json

@@ -14,12 +14,6 @@
   },
   "include": ["src/**/*.ts"],
   "exclude": [
-    "src/__tests__/workflow-runner.test.ts",
-    "src/__tests__/workflow-trajectory.test.ts",
-    "src/__tests__/swarm-coordinator.test.ts",
-    "src/__tests__/error-scenarios.test.ts",
-    "src/__tests__/idle-nudge.test.ts",
-    "src/__tests__/orchestration-upgrades.test.ts",
-    "src/__tests__/yaml-validation.test.ts"
+    "src/__tests__/**"
   ]
 }

package/packages/sdk/tsconfig.json

@@ -10,12 +10,6 @@
   },
   "include": ["src/**/*.ts"],
   "exclude": [
-    "src/__tests__/workflow-runner.test.ts",
-    "src/__tests__/workflow-trajectory.test.ts",
-    "src/__tests__/swarm-coordinator.test.ts",
-    "src/__tests__/error-scenarios.test.ts",
-    "src/__tests__/idle-nudge.test.ts",
-    "src/__tests__/orchestration-upgrades.test.ts",
-    "src/__tests__/yaml-validation.test.ts"
+    "src/__tests__/**"
   ]
 }