agent-relay 2.3.4 → 2.3.6

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

@@ -0,0 +1,241 @@
+import { stringify as stringifyYaml } from 'yaml';
+
+import type { AgentRelayOptions } from '../relay.js';
+import type {
+  AgentCli,
+  AgentDefinition,
+  ErrorHandlingConfig,
+  RelayYamlConfig,
+  SwarmPattern,
+  VerificationCheck,
+  WorkflowDefinition,
+  WorkflowRunRow,
+  WorkflowStep,
+} from './types.js';
+import { WorkflowRunner, type WorkflowEventListener, type VariableContext } from './runner.js';
+
+// ── Option types for the builder API ────────────────────────────────────────
+
+export interface AgentOptions {
+  cli: AgentCli;
+  role?: string;
+  task?: string;
+  channels?: string[];
+  model?: string;
+  maxTokens?: number;
+  timeoutMs?: number;
+  retries?: number;
+}
+
+export interface StepOptions {
+  agent: string;
+  task: string;
+  dependsOn?: string[];
+  verification?: VerificationCheck;
+  timeoutMs?: number;
+  retries?: number;
+}
+
+export interface ErrorOptions {
+  maxRetries?: number;
+  retryDelayMs?: number;
+  notifyChannel?: string;
+}
+
+export interface WorkflowRunOptions {
+  /** Run a specific workflow by name (default: first). */
+  workflow?: string;
+  /** Template variable substitutions. */
+  vars?: VariableContext;
+  /** Working directory (default: process.cwd()). */
+  cwd?: string;
+  /** AgentRelay options (all optional). */
+  relay?: AgentRelayOptions;
+  /** Progress callback. */
+  onEvent?: WorkflowEventListener;
+}
+
+// ── WorkflowBuilder ─────────────────────────────────────────────────────────
+
+/**
+ * Fluent builder for constructing workflow configurations programmatically.
+ *
+ * @example
+ * ```typescript
+ * import { workflow } from "@agent-relay/broker-sdk/workflows";
+ *
+ * const result = await workflow("my-workflow")
+ *   .pattern("dag")
+ *   .agent("worker", { cli: "claude", role: "Backend engineer" })
+ *   .step("build", { agent: "worker", task: "Build the project" })
+ *   .step("test", { agent: "worker", task: "Run tests", dependsOn: ["build"] })
+ *   .run();
+ * ```
+ */
+export class WorkflowBuilder {
+  private _name: string;
+  private _description?: string;
+  private _pattern: SwarmPattern = 'dag';
+  private _maxConcurrency?: number;
+  private _timeoutMs?: number;
+  private _channel?: string;
+  private _agents: AgentDefinition[] = [];
+  private _steps: WorkflowStep[] = [];
+  private _errorHandling?: ErrorHandlingConfig;
+
+  constructor(name: string) {
+    this._name = name;
+  }
+
+  /** Set workflow description. */
+  description(desc: string): this {
+    this._description = desc;
+    return this;
+  }
+
+  /** Set swarm pattern (default: "dag"). */
+  pattern(p: SwarmPattern): this {
+    this._pattern = p;
+    return this;
+  }
+
+  /** Set maximum concurrent agents. */
+  maxConcurrency(n: number): this {
+    this._maxConcurrency = n;
+    return this;
+  }
+
+  /** Set global timeout in milliseconds. */
+  timeout(ms: number): this {
+    this._timeoutMs = ms;
+    return this;
+  }
+
+  /** Set the relay channel for agent communication. */
+  channel(ch: string): this {
+    this._channel = ch;
+    return this;
+  }
+
+  /** Add an agent definition. */
+  agent(name: string, options: AgentOptions): this {
+    const def: AgentDefinition = {
+      name,
+      cli: options.cli,
+    };
+
+    if (options.role !== undefined) def.role = options.role;
+    if (options.task !== undefined) def.task = options.task;
+    if (options.channels !== undefined) def.channels = options.channels;
+
+    if (options.model !== undefined || options.maxTokens !== undefined ||
+        options.timeoutMs !== undefined || options.retries !== undefined) {
+      def.constraints = {};
+      if (options.model !== undefined) def.constraints.model = options.model;
+      if (options.maxTokens !== undefined) def.constraints.maxTokens = options.maxTokens;
+      if (options.timeoutMs !== undefined) def.constraints.timeoutMs = options.timeoutMs;
+      if (options.retries !== undefined) def.constraints.retries = options.retries;
+    }
+
+    this._agents.push(def);
+    return this;
+  }
+
+  /** Add a workflow step. */
+  step(name: string, options: StepOptions): this {
+    const step: WorkflowStep = {
+      name,
+      agent: options.agent,
+      task: options.task,
+    };
+
+    if (options.dependsOn !== undefined) step.dependsOn = options.dependsOn;
+    if (options.verification !== undefined) step.verification = options.verification;
+    if (options.timeoutMs !== undefined) step.timeoutMs = options.timeoutMs;
+    if (options.retries !== undefined) step.retries = options.retries;
+
+    this._steps.push(step);
+    return this;
+  }
+
+  /** Set error handling strategy. */
+  onError(strategy: 'fail-fast' | 'continue' | 'retry', options?: ErrorOptions): this {
+    this._errorHandling = { strategy };
+    if (options?.maxRetries !== undefined) this._errorHandling.maxRetries = options.maxRetries;
+    if (options?.retryDelayMs !== undefined) this._errorHandling.retryDelayMs = options.retryDelayMs;
+    if (options?.notifyChannel !== undefined) this._errorHandling.notifyChannel = options.notifyChannel;
+    return this;
+  }
+
+  /** Build and return the RelayYamlConfig object. */
+  toConfig(): RelayYamlConfig {
+    if (this._agents.length === 0) {
+      throw new Error('Workflow must have at least one agent');
+    }
+    if (this._steps.length === 0) {
+      throw new Error('Workflow must have at least one step');
+    }
+
+    const wfDef: WorkflowDefinition = {
+      name: `${this._name}-workflow`,
+      steps: [...this._steps],
+    };
+
+    const config: RelayYamlConfig = {
+      version: '1.0',
+      name: this._name,
+      swarm: {
+        pattern: this._pattern,
+      },
+      agents: [...this._agents],
+      workflows: [wfDef],
+    };
+
+    if (this._description !== undefined) config.description = this._description;
+    if (this._maxConcurrency !== undefined) config.swarm.maxConcurrency = this._maxConcurrency;
+    if (this._timeoutMs !== undefined) config.swarm.timeoutMs = this._timeoutMs;
+    if (this._channel !== undefined) config.swarm.channel = this._channel;
+    if (this._errorHandling !== undefined) config.errorHandling = this._errorHandling;
+
+    return config;
+  }
+
+  /** Serialize the config to a YAML string. */
+  toYaml(): string {
+    return stringifyYaml(this.toConfig());
+  }
+
+  /** Build the config and execute it with the WorkflowRunner. */
+  async run(options: WorkflowRunOptions = {}): Promise<WorkflowRunRow> {
+    const config = this.toConfig();
+
+    const runner = new WorkflowRunner({
+      cwd: options.cwd,
+      relay: options.relay,
+    });
+
+    if (options.onEvent) {
+      runner.on(options.onEvent);
+    }
+
+    return runner.execute(config, options.workflow, options.vars);
+  }
+}
+
+// ── Entry point ─────────────────────────────────────────────────────────────
+
+/**
+ * Create a new workflow builder.
+ *
+ * @example
+ * ```typescript
+ * const result = await workflow("my-task")
+ *   .pattern("fan-out")
+ *   .agent("worker", { cli: "claude" })
+ *   .step("do-work", { agent: "worker", task: "Build the feature" })
+ *   .run();
+ * ```
+ */
+export function workflow(name: string): WorkflowBuilder {
+  return new WorkflowBuilder(name);
+}

package/packages/sdk-ts/src/workflows/builtin-templates/bug-fix.yaml

@@ -0,0 +1,75 @@
+version: "1.0"
+name: bug-fix
+description: "Fast bug investigation and remediation workflow with validation gates."
+swarm:
+  pattern: hub-spoke
+  maxConcurrency: 2
+  timeoutMs: 2700000
+  channel: swarm-bug-fix
+agents:
+  - name: lead
+    cli: claude
+    role: "Coordinates debugging and release decisions"
+  - name: investigator
+    cli: codex
+    role: "Reproduces and scopes the defect"
+  - name: fixer
+    cli: codex
+    role: "Implements and tests the fix"
+  - name: verifier
+    cli: claude
+    role: "Validates risk, regressions, and completion"
+workflows:
+  - name: bug-remediation
+    description: "Investigate root cause, patch safely, and verify no regressions."
+    onError: retry
+    steps:
+      - name: investigate
+        agent: investigator
+        task: |
+          Reproduce the issue, identify root cause, and provide a fix strategy:
+          {{task}}
+        verification:
+          type: output_contains
+          value: ROOT_CAUSE_IDENTIFIED
+      - name: patch
+        agent: fixer
+        dependsOn: [investigate]
+        task: |
+          Implement the fix based on the investigation report:
+          {{steps.investigate.output}}
+        retries: 2
+        verification:
+          type: output_contains
+          value: PATCH_APPLIED
+      - name: regression-check
+        agent: verifier
+        dependsOn: [patch]
+        task: |
+          Validate the patch for correctness and regression risk:
+          {{steps.patch.output}}
+        verification:
+          type: output_contains
+          value: VERIFICATION_COMPLETE
+      - name: closeout
+        agent: lead
+        dependsOn: [regression-check]
+        task: |
+          Prepare final incident summary, residual risk, and deployment notes.
+        verification:
+          type: output_contains
+          value: DONE
+coordination:
+  barriers:
+    - name: fix-ready
+      waitFor: [investigate, patch, regression-check]
+      timeoutMs: 600000
+state:
+  backend: memory
+  ttlMs: 43200000
+  namespace: bug-fix
+errorHandling:
+  strategy: retry
+  maxRetries: 3
+  retryDelayMs: 3000
+  notifyChannel: swarm-bug-fix

package/packages/sdk-ts/src/workflows/builtin-templates/code-review.yaml

@@ -0,0 +1,82 @@
+version: "1.0"
+name: code-review
+description: "Parallel multi-reviewer code assessment with consolidated findings."
+swarm:
+  pattern: fan-out
+  maxConcurrency: 4
+  timeoutMs: 2400000
+  channel: swarm-code-review
+agents:
+  - name: lead
+    cli: claude
+    role: "Aggregates review output and final recommendations"
+  - name: reviewer-architecture
+    cli: codex
+    role: "Assesses architecture and maintainability"
+  - name: reviewer-correctness
+    cli: claude
+    role: "Assesses correctness and testing"
+  - name: reviewer-security
+    cli: gemini
+    role: "Assesses security posture and abuse resistance"
+workflows:
+  - name: parallel-review
+    description: "Run focused reviews in parallel and synthesize final guidance."
+    onError: fail
+    steps:
+      - name: prepare-context
+        agent: lead
+        task: |
+          Summarize change intent, impacted modules, and review priorities:
+          {{task}}
+        verification:
+          type: output_contains
+          value: REVIEW_CONTEXT_READY
+      - name: architecture-pass
+        agent: reviewer-architecture
+        dependsOn: [prepare-context]
+        task: |
+          Review architecture, coupling, and long-term maintainability:
+          {{steps.prepare-context.output}}
+        verification:
+          type: output_contains
+          value: ARCH_REVIEW_COMPLETE
+      - name: correctness-pass
+        agent: reviewer-correctness
+        dependsOn: [prepare-context]
+        task: |
+          Review behavior, tests, and likely regression paths:
+          {{steps.prepare-context.output}}
+        verification:
+          type: output_contains
+          value: CORRECTNESS_REVIEW_COMPLETE
+      - name: security-pass
+        agent: reviewer-security
+        dependsOn: [prepare-context]
+        task: |
+          Review attack surface, secret handling, and input validation:
+          {{steps.prepare-context.output}}
+        verification:
+          type: output_contains
+          value: SECURITY_REVIEW_COMPLETE
+      - name: consolidate
+        agent: lead
+        dependsOn: [architecture-pass, correctness-pass, security-pass]
+        task: |
+          Produce merged findings, severity levels, and final recommendation.
+        verification:
+          type: output_contains
+          value: DONE
+coordination:
+  barriers:
+    - name: reviews-complete
+      waitFor: [architecture-pass, correctness-pass, security-pass]
+      timeoutMs: 900000
+  consensusStrategy: majority
+state:
+  backend: memory
+  ttlMs: 21600000
+  namespace: code-review
+errorHandling:
+  strategy: fail-fast
+  notifyChannel: swarm-code-review

package/packages/sdk-ts/src/workflows/builtin-templates/documentation.yaml

@@ -0,0 +1,70 @@
+version: "1.0"
+name: documentation
+description: "Documentation production workflow from research through publication summary."
+swarm:
+  pattern: handoff
+  maxConcurrency: 1
+  timeoutMs: 3000000
+  channel: swarm-documentation
+agents:
+  - name: lead
+    cli: claude
+    role: "Owns final editorial sign-off"
+  - name: researcher
+    cli: codex
+    role: "Collects technical context and source details"
+  - name: writer
+    cli: codex
+    role: "Drafts user-facing documentation"
+  - name: editor
+    cli: claude
+    role: "Edits for accuracy, clarity, and structure"
+workflows:
+  - name: docs-production
+    description: "Gather context, draft docs, edit, and publish summary."
+    onError: skip
+    steps:
+      - name: gather-context
+        agent: researcher
+        task: |
+          Collect source context and required updates:
+          {{task}}
+        verification:
+          type: output_contains
+          value: CONTEXT_COMPLETE
+      - name: draft
+        agent: writer
+        dependsOn: [gather-context]
+        task: |
+          Draft documentation updates based on gathered context.
+        verification:
+          type: output_contains
+          value: DRAFT_COMPLETE
+      - name: edit
+        agent: editor
+        dependsOn: [draft]
+        task: |
+          Edit the draft for technical accuracy and readability.
+        verification:
+          type: output_contains
+          value: EDIT_COMPLETE
+      - name: publish-summary
+        agent: lead
+        dependsOn: [edit]
+        task: |
+          Publish a final summary of documentation changes and open items.
+        verification:
+          type: output_contains
+          value: DONE
+coordination:
+  barriers:
+    - name: docs-ready
+      waitFor: [gather-context, draft, edit]
+      timeoutMs: 600000
+state:
+  backend: memory
+  ttlMs: 259200000
+  namespace: documentation
+errorHandling:
+  strategy: continue
+  notifyChannel: swarm-documentation

package/packages/sdk-ts/src/workflows/builtin-templates/feature-dev.yaml

@@ -0,0 +1,76 @@
+version: "1.0"
+name: feature-dev
+description: "Full feature development lifecycle with planning, implementation, review, and release."
+swarm:
+  pattern: hub-spoke
+  maxConcurrency: 2
+  timeoutMs: 3600000
+  channel: swarm-feature-dev
+agents:
+  - name: lead
+    cli: claude
+    role: "Lead engineer coordinating delivery"
+  - name: planner
+    cli: codex
+    role: "Plans implementation and acceptance criteria"
+  - name: developer
+    cli: codex
+    role: "Implements planned changes"
+  - name: reviewer
+    cli: claude
+    role: "Reviews code quality and release risk"
+workflows:
+  - name: feature-delivery
+    description: "Plan, implement, review, and finalize a feature request."
+    onError: retry
+    steps:
+      - name: plan
+        agent: planner
+        task: |
+          Analyze the feature request and produce a concrete implementation plan:
+          {{task}}
+        retries: 1
+        verification:
+          type: output_contains
+          value: PLAN_COMPLETE
+      - name: implement
+        agent: developer
+        dependsOn: [plan]
+        task: |
+          Implement the approved plan:
+          {{steps.plan.output}}
+        retries: 1
+        verification:
+          type: output_contains
+          value: IMPLEMENTATION_COMPLETE
+      - name: review
+        agent: reviewer
+        dependsOn: [implement]
+        task: |
+          Review implementation quality, correctness, and test coverage:
+          {{steps.implement.output}}
+        verification:
+          type: output_contains
+          value: REVIEW_COMPLETE
+      - name: finalize
+        agent: lead
+        dependsOn: [review]
+        task: |
+          Summarize decisions and ship readiness for the feature.
+        verification:
+          type: output_contains
+          value: DONE
+coordination:
+  barriers:
+    - name: delivery-ready
+      waitFor: [plan, implement, review]
+      timeoutMs: 900000
+state:
+  backend: memory
+  ttlMs: 86400000
+  namespace: feature-dev
+errorHandling:
+  strategy: retry
+  maxRetries: 2
+  retryDelayMs: 5000
+  notifyChannel: swarm-feature-dev

package/packages/sdk-ts/src/workflows/builtin-templates/refactor.yaml

@@ -0,0 +1,82 @@
+version: "1.0"
+name: refactor
+description: "Hierarchical refactor workflow for safe structural improvement."
+swarm:
+  pattern: hierarchical
+  maxConcurrency: 2
+  timeoutMs: 4500000
+  channel: swarm-refactor
+agents:
+  - name: lead
+    cli: claude
+    role: "Owns scope, sequencing, and acceptance"
+  - name: architect
+    cli: codex
+    role: "Designs target architecture and migration plan"
+  - name: refactorer
+    cli: codex
+    role: "Executes scoped refactor changes"
+  - name: tester
+    cli: claude
+    role: "Validates behavior parity and risk"
+workflows:
+  - name: refactor-execution
+    description: "Analyze current system, design approach, refactor, and validate."
+    onError: retry
+    steps:
+      - name: analyze
+        agent: architect
+        task: |
+          Analyze current design and identify refactor opportunities:
+          {{task}}
+        verification:
+          type: output_contains
+          value: ANALYSIS_COMPLETE
+      - name: design
+        agent: architect
+        dependsOn: [analyze]
+        task: |
+          Provide incremental refactor plan with rollback notes:
+          {{steps.analyze.output}}
+        verification:
+          type: output_contains
+          value: PLAN_COMPLETE
+      - name: refactor-code
+        agent: refactorer
+        dependsOn: [design]
+        task: |
+          Execute the refactor plan while preserving behavior.
+        retries: 2
+        verification:
+          type: output_contains
+          value: REFACTOR_COMPLETE
+      - name: validate
+        agent: tester
+        dependsOn: [refactor-code]
+        task: |
+          Validate no regressions and ensure tests/quality checks pass.
+        verification:
+          type: output_contains
+          value: VALIDATION_COMPLETE
+      - name: handoff
+        agent: lead
+        dependsOn: [validate]
+        task: |
+          Produce final refactor summary and open follow-up items.
+        verification:
+          type: output_contains
+          value: DONE
+coordination:
+  barriers:
+    - name: refactor-ready
+      waitFor: [analyze, design, refactor-code, validate]
+      timeoutMs: 900000
+state:
+  backend: memory
+  ttlMs: 604800000
+  namespace: refactor
+errorHandling:
+  strategy: retry
+  maxRetries: 2
+  retryDelayMs: 5000
+  notifyChannel: swarm-refactor

package/packages/sdk-ts/src/workflows/builtin-templates/security-audit.yaml

@@ -0,0 +1,84 @@
+version: "1.0"
+name: security-audit
+description: "Structured security assessment pipeline from scan through verification."
+swarm:
+  pattern: pipeline
+  maxConcurrency: 1
+  timeoutMs: 5400000
+  channel: swarm-security-audit
+agents:
+  - name: lead
+    cli: claude
+    role: "Owns final risk sign-off and recommendations"
+  - name: scanner
+    cli: codex
+    role: "Performs static and dependency security scanning"
+  - name: analyst
+    cli: claude
+    role: "Prioritizes findings and recommends mitigations"
+  - name: remediator
+    cli: codex
+    role: "Implements approved remediations"
+  - name: verifier
+    cli: gemini
+    role: "Verifies fixes and residual exposure"
+workflows:
+  - name: audit-pipeline
+    description: "Scan, triage, remediate, verify, and report security posture."
+    onError: fail
+    steps:
+      - name: scan
+        agent: scanner
+        task: |
+          Execute security scan and summarize high-confidence findings:
+          {{task}}
+        verification:
+          type: output_contains
+          value: SCAN_COMPLETE
+      - name: triage
+        agent: analyst
+        dependsOn: [scan]
+        task: |
+          Prioritize findings by severity and exploitability:
+          {{steps.scan.output}}
+        verification:
+          type: output_contains
+          value: TRIAGE_COMPLETE
+      - name: remediate
+        agent: remediator
+        dependsOn: [triage]
+        task: |
+          Implement mitigations for approved findings:
+          {{steps.triage.output}}
+        retries: 1
+        verification:
+          type: output_contains
+          value: REMEDIATION_COMPLETE
+      - name: verify
+        agent: verifier
+        dependsOn: [remediate]
+        task: |
+          Re-test security posture and confirm mitigations hold.
+        verification:
+          type: output_contains
+          value: VERIFICATION_COMPLETE
+      - name: report
+        agent: lead
+        dependsOn: [verify]
+        task: |
+          Produce final audit report with residual risk and next actions.
+        verification:
+          type: output_contains
+          value: DONE
+coordination:
+  barriers:
+    - name: audit-complete
+      waitFor: [scan, triage, remediate, verify]
+      timeoutMs: 1200000
+state:
+  backend: memory
+  ttlMs: 86400000
+  namespace: security-audit
+errorHandling:
+  strategy: fail-fast
+  notifyChannel: swarm-security-audit