agent-relay 2.3.13 → 2.4.0

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

@@ -1,241 +0,0 @@
-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/broker-sdk/src/workflows/builtin-templates/bug-fix.yaml

@@ -1,75 +0,0 @@
-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/broker-sdk/src/workflows/builtin-templates/code-review.yaml

@@ -1,82 +0,0 @@
-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/broker-sdk/src/workflows/builtin-templates/documentation.yaml

@@ -1,70 +0,0 @@
-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/broker-sdk/src/workflows/builtin-templates/feature-dev.yaml

@@ -1,76 +0,0 @@
-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/broker-sdk/src/workflows/builtin-templates/refactor.yaml

@@ -1,82 +0,0 @@
-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/broker-sdk/src/workflows/builtin-templates/security-audit.yaml

@@ -1,84 +0,0 @@
-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