agent-relay 2.3.11 → 2.3.13

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

@@ -27,12 +27,14 @@ import type {
   WorkflowStepRow,
   WorkflowStepStatus,
 } from './types.js';
+import { WorkflowTrajectory, type StepOutcome } from './trajectory.js';
 
 // ── AgentRelay SDK imports ──────────────────────────────────────────────────
 
 // Import from sub-paths to avoid pulling in the full @relaycast/sdk dependency.
 import { AgentRelay } from '../relay.js';
 import type { Agent, AgentRelayOptions } from '../relay.js';
+import { RelaycastApi } from '../relaycast.js';
 
 // ── DB adapter interface ────────────────────────────────────────────────────
 
@@ -95,6 +97,9 @@ export class WorkflowRunner {
   private readonly summaryDir: string;
 
   private relay?: AgentRelay;
+  private relaycastApi?: RelaycastApi;
+  private channel?: string;
+  private trajectory?: WorkflowTrajectory;
   private abortController?: AbortController;
   private paused = false;
   private pauseResolver?: () => void;
@@ -468,11 +473,19 @@ export class WorkflowRunner {
     this.abortController = new AbortController();
     this.paused = false;
 
+    // Initialize trajectory recording
+    this.trajectory = new WorkflowTrajectory(resolved.trajectories, runId, this.cwd);
+
     try {
       await this.updateRunStatus(runId, 'running');
       this.emit({ type: 'run:started', runId });
 
+      // Analyze DAG for trajectory context
+      const dagInfo = this.analyzeDAG(workflow.steps);
+      await this.trajectory.start(workflow.name, workflow.steps.length, dagInfo);
+
       const channel = resolved.swarm.channel ?? 'general';
+      this.channel = channel;
       await this.ensureRelaycastApiKey(channel);
 
       this.relay = new AgentRelay({
@@ -480,6 +493,14 @@ export class WorkflowRunner {
         channels: [channel],
       });
 
+      // Create the dedicated workflow channel and join it
+      this.relaycastApi = new RelaycastApi({ agentName: 'WorkflowRunner' });
+      await this.relaycastApi.createChannel(channel, workflow.description);
+      await this.relaycastApi.joinChannel(channel);
+      this.postToChannel(
+        `Workflow **${workflow.name}** started — ${workflow.steps.length} steps, pattern: ${resolved.swarm.pattern}`,
+      );
+
       const agentMap = new Map<string, AgentDefinition>();
       for (const agent of resolved.agents) {
         agentMap.set(agent.name, agent);
@@ -501,11 +522,25 @@ export class WorkflowRunner {
       if (allCompleted) {
         await this.updateRunStatus(runId, 'completed');
         this.emit({ type: 'run:completed', runId });
+        this.postToChannel(`Workflow **${workflow.name}** completed — all steps passed`);
+
+        // Complete trajectory with summary
+        const outcomes = this.collectOutcomes(stepStates, workflow.steps);
+        const summary = this.trajectory.buildRunSummary(outcomes);
+        const confidence = this.trajectory.computeConfidence(outcomes);
+        await this.trajectory.complete(summary, confidence, {
+          learnings: this.trajectory.extractLearnings(outcomes),
+          challenges: this.trajectory.extractChallenges(outcomes),
+        });
       } else {
         const failedStep = [...stepStates.values()].find((s) => s.row.status === 'failed');
         const errorMsg = failedStep?.row.error ?? 'One or more steps failed';
         await this.updateRunStatus(runId, 'failed', errorMsg);
         this.emit({ type: 'run:failed', runId, error: errorMsg });
+        this.postToChannel(`Workflow **${workflow.name}** failed: ${errorMsg}`);
+
+        // Abandon trajectory on failure
+        await this.trajectory.abandon(errorMsg);
       }
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : String(err);
@@ -514,12 +549,19 @@ export class WorkflowRunner {
 
       if (status === 'cancelled') {
         this.emit({ type: 'run:cancelled', runId });
+        this.postToChannel(`Workflow cancelled`);
+        await this.trajectory.abandon('Cancelled by user');
       } else {
         this.emit({ type: 'run:failed', runId, error: errorMsg });
+        this.postToChannel(`Workflow failed: ${errorMsg}`);
+        await this.trajectory.abandon(errorMsg);
       }
     } finally {
       await this.relay?.shutdown();
       this.relay = undefined;
+      this.relaycastApi = undefined;
+      this.channel = undefined;
+      this.trajectory = undefined;
       this.abortController = undefined;
     }
 
@@ -567,10 +609,21 @@ export class WorkflowRunner {
     this.abortController = new AbortController();
     this.paused = false;
 
+    // Initialize trajectory for resumed run
+    this.trajectory = new WorkflowTrajectory(config.trajectories, runId, this.cwd);
+
     try {
       await this.updateRunStatus(runId, 'running');
 
+      const pendingCount = [...stepStates.values()].filter((s) => s.row.status === 'pending').length;
+      await this.trajectory.start(
+        workflow.name,
+        workflow.steps.length,
+        `Resumed run: ${pendingCount} pending steps of ${workflow.steps.length} total`,
+      );
+
       const resumeChannel = config.swarm.channel ?? 'general';
+      this.channel = resumeChannel;
       await this.ensureRelaycastApiKey(resumeChannel);
 
       this.relay = new AgentRelay({
@@ -578,6 +631,14 @@ export class WorkflowRunner {
         channels: [resumeChannel],
       });
 
+      // Ensure channel exists and join it for resumed runs
+      this.relaycastApi = new RelaycastApi({ agentName: 'WorkflowRunner' });
+      await this.relaycastApi.createChannel(resumeChannel);
+      await this.relaycastApi.joinChannel(resumeChannel);
+      this.postToChannel(
+        `Workflow **${workflow.name}** resumed — ${pendingCount} pending steps`,
+      );
+
       const agentMap = new Map<string, AgentDefinition>();
       for (const agent of config.agents) {
         agentMap.set(agent.name, agent);
@@ -592,19 +653,35 @@ export class WorkflowRunner {
       if (allCompleted) {
         await this.updateRunStatus(runId, 'completed');
         this.emit({ type: 'run:completed', runId });
+        this.postToChannel(`Workflow **${workflow.name}** completed — all steps passed`);
+
+        const outcomes = this.collectOutcomes(stepStates, workflow.steps);
+        const summary = this.trajectory.buildRunSummary(outcomes);
+        const confidence = this.trajectory.computeConfidence(outcomes);
+        await this.trajectory.complete(summary, confidence, {
+          learnings: this.trajectory.extractLearnings(outcomes),
+          challenges: this.trajectory.extractChallenges(outcomes),
+        });
       } else {
         const failedStep = [...stepStates.values()].find((s) => s.row.status === 'failed');
         const errorMsg = failedStep?.row.error ?? 'One or more steps failed';
         await this.updateRunStatus(runId, 'failed', errorMsg);
         this.emit({ type: 'run:failed', runId, error: errorMsg });
+        this.postToChannel(`Workflow **${workflow.name}** failed: ${errorMsg}`);
+        await this.trajectory.abandon(errorMsg);
       }
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : String(err);
       await this.updateRunStatus(runId, 'failed', errorMsg);
       this.emit({ type: 'run:failed', runId, error: errorMsg });
+      this.postToChannel(`Workflow failed: ${errorMsg}`);
+      await this.trajectory.abandon(errorMsg);
     } finally {
       await this.relay?.shutdown();
       this.relay = undefined;
+      this.relaycastApi = undefined;
+      this.channel = undefined;
+      this.trajectory = undefined;
       this.abortController = undefined;
     }
 
@@ -660,23 +737,40 @@ export class WorkflowRunner {
         break;
       }
 
+      // Begin a track chapter if multiple parallel steps are starting
+      if (readySteps.length > 1 && this.trajectory) {
+        const trackNames = readySteps.map((s) => s.name).join(', ');
+        await this.trajectory.beginTrack(trackNames);
+      }
+
       const results = await Promise.allSettled(
         readySteps.map((step) =>
           this.executeStep(step, stepStates, agentMap, errorHandling, runId),
         ),
       );
 
+      // Collect outcomes from this batch for convergence reflection
+      const batchOutcomes: StepOutcome[] = [];
+
       for (let i = 0; i < results.length; i++) {
         const result = results[i];
         const step = readySteps[i];
+        const state = stepStates.get(step.name);
 
         if (result.status === 'rejected') {
           const error = result.reason instanceof Error ? result.reason.message : String(result.reason);
-          const state = stepStates.get(step.name);
           if (state && state.row.status !== 'failed') {
             await this.markStepFailed(state, error, runId);
           }
 
+          batchOutcomes.push({
+            name: step.name,
+            agent: step.agent,
+            status: 'failed',
+            attempts: (state?.row.retryCount ?? 0) + 1,
+            error,
+          });
+
           if (strategy === 'fail-fast') {
             // Mark all pending downstream steps as skipped
             await this.markDownstreamSkipped(step.name, workflow.steps, stepStates, runId);
@@ -686,8 +780,33 @@ export class WorkflowRunner {
           if (strategy === 'continue') {
             await this.markDownstreamSkipped(step.name, workflow.steps, stepStates, runId);
           }
+        } else {
+          batchOutcomes.push({
+            name: step.name,
+            agent: step.agent,
+            status: state?.row.status === 'completed' ? 'completed' : 'failed',
+            attempts: (state?.row.retryCount ?? 0) + 1,
+            output: state?.row.output,
+            verificationPassed: state?.row.status === 'completed' && step.verification !== undefined,
+          });
         }
       }
+
+      // Reflect at convergence when a parallel batch completes
+      if (readySteps.length > 1 && this.trajectory?.shouldReflectOnConverge()) {
+        const label = readySteps.map((s) => s.name).join(' + ');
+        // Find steps that this batch unblocks
+        const completedNames = new Set(batchOutcomes.filter((o) => o.status === 'completed').map((o) => o.name));
+        const unblocked = workflow.steps
+          .filter((s) => s.dependsOn?.some((dep) => completedNames.has(dep)))
+          .filter((s) => {
+            const st = stepStates.get(s.name);
+            return st && st.row.status === 'pending';
+          })
+          .map((s) => s.name);
+
+        await this.trajectory.synthesizeAndReflect(label, batchOutcomes, unblocked.length > 0 ? unblocked : undefined);
+      }
     }
   }
 
@@ -733,11 +852,13 @@ export class WorkflowRunner {
 
       if (attempt > 0) {
         this.emit({ type: 'step:retrying', runId, stepName: step.name, attempt });
+        this.postToChannel(`**[${step.name}]** Retrying (attempt ${attempt + 1}/${maxRetries + 1})`);
         state.row.retryCount = attempt;
         await this.db.updateStep(state.row.id, {
           retryCount: attempt,
           updatedAt: new Date().toISOString(),
         });
+        await this.trajectory?.stepRetrying(step, attempt, maxRetries);
         await this.delay(retryDelay);
       }
 
@@ -751,6 +872,8 @@ export class WorkflowRunner {
           updatedAt: new Date().toISOString(),
         });
         this.emit({ type: 'step:started', runId, stepName: step.name });
+        this.postToChannel(`**[${step.name}]** Started (agent: ${agentDef.name})`);
+        await this.trajectory?.stepStarted(step, agentDef.name);
 
         // Resolve step-output variables (e.g. {{steps.plan.output}}) at execution time
         const stepOutputContext = this.buildStepOutputContext(stepStates);
@@ -776,13 +899,24 @@ export class WorkflowRunner {
           updatedAt: new Date().toISOString(),
         });
         this.emit({ type: 'step:completed', runId, stepName: step.name, output });
+        this.postToChannel(
+          `**[${step.name}]** Completed\n${output.slice(0, 500)}${output.length > 500 ? '\n...(truncated)' : ''}`,
+        );
+        await this.trajectory?.stepCompleted(step, output, attempt + 1);
         return;
       } catch (err) {
         lastError = err instanceof Error ? err.message : String(err);
       }
     }
 
-    // All retries exhausted — mark failed and throw so callers can apply error strategy
+    // All retries exhausted — record decision and mark failed
+    await this.trajectory?.stepFailed(step, lastError ?? 'Unknown error', maxRetries + 1, maxRetries);
+    await this.trajectory?.decide(
+      `How to handle ${step.name} failure`,
+      'exhausted',
+      `All ${maxRetries + 1} attempts failed: ${lastError ?? 'Unknown error'}`,
+    );
+    this.postToChannel(`**[${step.name}]** Failed: ${lastError ?? 'Unknown error'}`);
     await this.markStepFailed(state, lastError ?? 'Unknown error', runId);
     throw new Error(`Step "${step.name}" failed after ${maxRetries} retries: ${lastError ?? 'Unknown error'}`);
   }
@@ -796,32 +930,76 @@ export class WorkflowRunner {
       throw new Error('AgentRelay not initialized');
     }
 
+    // Append self-termination instructions to the task
+    const agentName = `${step.name}-${this.generateShortId()}`;
+    const taskWithExit = step.task + '\n\n---\n' +
+      'IMPORTANT: When you have fully completed this task, you MUST self-terminate by calling ' +
+      `the MCP tool: relay_release(name="${agentName}", reason="Task completed"). ` +
+      'Do not wait for further input — release yourself immediately after finishing.';
+
+    const agentChannels = this.channel ? [this.channel] : agentDef.channels;
+
     const agent = await this.relay.spawnPty({
-      name: `${step.name}-${this.generateShortId()}`,
+      name: agentName,
       cli: agentDef.cli,
       args: agentDef.constraints?.model ? ['--model', agentDef.constraints.model] : [],
-      channels: agentDef.channels,
+      channels: agentChannels,
+      task: taskWithExit,
+      idleThresholdSecs: agentDef.constraints?.idleThresholdSecs,
     });
 
-    // Send the task as a message to the agent
-    const system = this.relay.human({ name: 'WorkflowRunner' });
-    await system.sendMessage({ to: agent.name, text: step.task });
+    // Register the spawned agent in Relaycast for observability
+    if (this.relaycastApi) {
+      await this.relaycastApi.registerExternalAgent(
+        agent.name,
+        `Workflow agent for step "${step.name}" (${agentDef.cli})`,
+      ).catch(() => {});
+    }
+
+    // Invite the spawned agent to the workflow channel
+    if (this.channel && this.relaycastApi) {
+      await this.relaycastApi.inviteToChannel(this.channel, agent.name).catch(() => {});
+    }
+
+    // Post task assignment to channel for observability
+    const taskPreview = step.task.slice(0, 500) + (step.task.length > 500 ? '...' : '');
+    this.postToChannel(`**[${step.name}]** Assigned to \`${agent.name}\`:\n${taskPreview}`);
+
+    // Task was already delivered as initial_task via spawnPty above.
 
-    // Wait for agent to exit
+    // Wait for agent to exit (self-termination via /exit)
     const exitResult = await agent.waitForExit(timeoutMs);
 
     if (exitResult === 'timeout') {
-      await agent.release();
-      throw new Error(`Step "${step.name}" timed out after ${timeoutMs}ms`);
+      // Safety net: check if the verification file exists before giving up.
+      // The agent may have completed work but failed to /exit.
+      if (step.verification?.type === 'file_exists') {
+        const verifyPath = path.resolve(this.cwd, step.verification.value);
+        if (existsSync(verifyPath)) {
+          this.postToChannel(
+            `**[${step.name}]** Agent idle after completing work — releasing`,
+          );
+          await agent.release();
+          // Fall through to read output below
+        } else {
+          await agent.release();
+          throw new Error(`Step "${step.name}" timed out after ${timeoutMs}ms`);
+        }
+      } else {
+        await agent.release();
+        throw new Error(`Step "${step.name}" timed out after ${timeoutMs}ms`);
+      }
     }
 
     // Read output from summary file if it exists
     const summaryPath = path.join(this.summaryDir, `${step.name}.md`);
-    if (existsSync(summaryPath)) {
-      return await readFile(summaryPath, 'utf-8');
-    }
+    const output = existsSync(summaryPath)
+      ? await readFile(summaryPath, 'utf-8')
+      : exitResult === 'timeout'
+        ? 'Agent completed (released after idle timeout)'
+        : `Agent exited (${exitResult})`;
 
-    return `Agent exited (${exitResult})`;
+    return output;
   }
 
   // ── Verification ────────────────────────────────────────────────────────
@@ -911,6 +1089,13 @@ export class WorkflowRunner {
               updatedAt: new Date().toISOString(),
             });
             this.emit({ type: 'step:skipped', runId, stepName: step.name });
+            this.postToChannel(`**[${step.name}]** Skipped — upstream dependency "${current}" failed`);
+            await this.trajectory?.stepSkipped(step, `Upstream dependency "${current}" failed`);
+            await this.trajectory?.decide(
+              `Whether to skip ${step.name}`,
+              'skip',
+              `Upstream dependency "${current}" failed`,
+            );
             queue.push(step.name);
           }
         }
@@ -937,6 +1122,56 @@ export class WorkflowRunner {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
 
+  // ── Channel messaging ──────────────────────────────────────────────────
+
+  /** Post a message to the workflow channel. Fire-and-forget — never throws or blocks. */
+  private postToChannel(text: string): void {
+    if (!this.relaycastApi || !this.channel) return;
+    this.relaycastApi.sendToChannel(this.channel, text).catch(() => {
+      // Non-critical — don't break workflow execution
+    });
+  }
+
+  // ── Trajectory helpers ────────────────────────────────────────────────
+
+  /** Analyze DAG structure for trajectory context. */
+  private analyzeDAG(steps: WorkflowStep[]): string {
+    const roots = steps.filter((s) => !s.dependsOn?.length);
+    const withDeps = steps.filter((s) => s.dependsOn?.length);
+
+    const parts = [`Parsed ${steps.length} steps`];
+    if (roots.length > 1) {
+      parts.push(`${roots.length} parallel tracks`);
+    }
+    if (withDeps.length > 0) {
+      parts.push(`${withDeps.length} dependent steps`);
+    }
+    parts.push('DAG validated, no cycles');
+    return parts.join(', ');
+  }
+
+  /** Collect step outcomes for trajectory synthesis. */
+  private collectOutcomes(stepStates: Map<string, StepState>, steps?: WorkflowStep[]): StepOutcome[] {
+    const stepsWithVerification = new Set(
+      steps?.filter((s) => s.verification).map((s) => s.name) ?? [],
+    );
+    const outcomes: StepOutcome[] = [];
+    for (const [name, state] of stepStates) {
+      outcomes.push({
+        name,
+        agent: state.row.agentName,
+        status: state.row.status === 'completed' ? 'completed'
+          : state.row.status === 'skipped' ? 'skipped'
+          : 'failed',
+        attempts: state.row.retryCount + 1,
+        output: state.row.output,
+        error: state.row.error,
+        verificationPassed: state.row.status === 'completed' && stepsWithVerification.has(name),
+      });
+    }
+    return outcomes;
+  }
+
   // ── ID generation ─────────────────────────────────────────────────────
 
   private generateId(): string {

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

@@ -82,7 +82,19 @@
         "cascade",
         "dag",
         "debate",
-        "hierarchical"
+        "hierarchical",
+        "map-reduce",
+        "scatter-gather",
+        "supervisor",
+        "reflection",
+        "red-team",
+        "verifier",
+        "auction",
+        "escalation",
+        "saga",
+        "circuit-breaker",
+        "blackboard",
+        "swarm"
       ]
     },
     "AgentDefinition": {