agent-relay 2.3.13 → 2.4.0

package/packages/sdk/dist/workflows/builder.js

@@ -0,0 +1,201 @@
+import { stringify as stringifyYaml } from 'yaml';
+import { WorkflowRunner } from './runner.js';
+import { formatDryRunReport } from './dry-run-format.js';
+// ── WorkflowBuilder ─────────────────────────────────────────────────────────
+/**
+ * Fluent builder for constructing workflow configurations programmatically.
+ *
+ * @example
+ * ```typescript
+ * import { workflow } from "@agent-relay/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 {
+    _name;
+    _description;
+    _pattern = 'dag';
+    _maxConcurrency;
+    _timeoutMs;
+    _channel;
+    _idleNudge;
+    _agents = [];
+    _steps = [];
+    _errorHandling;
+    constructor(name) {
+        this._name = name;
+    }
+    /** Set workflow description. */
+    description(desc) {
+        this._description = desc;
+        return this;
+    }
+    /** Set swarm pattern (default: "dag"). */
+    pattern(p) {
+        this._pattern = p;
+        return this;
+    }
+    /** Set maximum concurrent agents. */
+    maxConcurrency(n) {
+        this._maxConcurrency = n;
+        return this;
+    }
+    /** Set global timeout in milliseconds. */
+    timeout(ms) {
+        this._timeoutMs = ms;
+        return this;
+    }
+    /** Set the relay channel for agent communication. */
+    channel(ch) {
+        this._channel = ch;
+        return this;
+    }
+    /** Configure idle agent detection and nudging for interactive agents. */
+    idleNudge(config) {
+        this._idleNudge = config;
+        return this;
+    }
+    /** Add an agent definition. */
+    agent(name, options) {
+        const def = {
+            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.interactive !== undefined)
+            def.interactive = options.interactive;
+        if (options.model !== undefined ||
+            options.maxTokens !== undefined ||
+            options.timeoutMs !== undefined ||
+            options.retries !== undefined ||
+            options.idleThresholdSecs !== 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;
+            if (options.idleThresholdSecs !== undefined)
+                def.constraints.idleThresholdSecs = options.idleThresholdSecs;
+        }
+        this._agents.push(def);
+        return this;
+    }
+    /** Add a workflow step. */
+    step(name, options) {
+        const step = {
+            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, options) {
+        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() {
+        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 = {
+            name: `${this._name}-workflow`,
+            steps: [...this._steps],
+        };
+        const config = {
+            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._idleNudge !== undefined)
+            config.swarm.idleNudge = this._idleNudge;
+        if (this._errorHandling !== undefined)
+            config.errorHandling = this._errorHandling;
+        return config;
+    }
+    /** Serialize the config to a YAML string. */
+    toYaml() {
+        return stringifyYaml(this.toConfig());
+    }
+    async run(options = {}) {
+        const config = this.toConfig();
+        const runner = new WorkflowRunner({
+            cwd: options.cwd,
+            relay: options.relay,
+        });
+        // Auto-detect DRY_RUN env var so existing scripts get dry-run for free
+        const isDryRun = options.dryRun ?? !!process.env.DRY_RUN;
+        if (isDryRun) {
+            const report = runner.dryRun(config, options.workflow, options.vars);
+            console.log(formatDryRunReport(report));
+            return report;
+        }
+        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) {
+    return new WorkflowBuilder(name);
+}
+//# sourceMappingURL=builder.js.map

package/packages/sdk/dist/workflows/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../../src/workflows/builder.ts"],"names":[],"mappings":"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"}

package/packages/sdk/dist/workflows/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for running relay.yaml workflows.
+ *
+ * Usage:
+ *   relay-workflow <yaml-path> [--workflow <name>]
+ *   relay-workflow --resume <run-id>
+ *   npx @agent-relay/sdk run <yaml-path> [--workflow <name>]
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/packages/sdk/dist/workflows/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/workflows/cli.ts"],"names":[],"mappings":";AAEA;;;;;;;GAOG"}

package/packages/sdk/dist/workflows/cli.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for running relay.yaml workflows.
+ *
+ * Usage:
+ *   relay-workflow <yaml-path> [--workflow <name>]
+ *   relay-workflow --resume <run-id>
+ *   npx @agent-relay/sdk run <yaml-path> [--workflow <name>]
+ */
+import path from 'node:path';
+import { WorkflowRunner } from './runner.js';
+import { JsonFileWorkflowDb } from './file-db.js';
+function printUsage() {
+    console.log(`
+Usage: relay-workflow <yaml-path> [options]
+       relay-workflow --resume <run-id>
+
+Run a relay.yaml workflow file.
+
+Arguments:
+  <yaml-path>              Path to the relay.yaml workflow file
+
+Options:
+  --workflow <name>        Run a specific workflow by name (default: first)
+  --resume <run-id>        Resume a failed or interrupted run by its run ID
+  --validate               Validate workflow YAML for common issues without running
+  --help                   Show this help message
+
+Examples:
+  relay-workflow workflows/daytona-migration.yaml
+  relay-workflow workflows/feature-dev.yaml --workflow build-and-test
+  relay-workflow --resume f409ce1d1788710bcc6abb55
+`.trim());
+}
+function formatEvent(event) {
+    switch (event.type) {
+        case 'run:started':
+            return `[run] started (${event.runId})`;
+        case 'run:completed':
+            return `[run] completed`;
+        case 'run:failed':
+            return `[run] failed: ${event.error}`;
+        case 'run:cancelled':
+            return `[run] cancelled`;
+        case 'step:started':
+            return `[step] ${event.stepName} started`;
+        case 'step:completed':
+            return `[step] ${event.stepName} completed`;
+        case 'step:failed':
+            return `[step] ${event.stepName} failed: ${event.error}`;
+        case 'step:skipped':
+            return `[step] ${event.stepName} skipped`;
+        case 'step:retrying':
+            return `[step] ${event.stepName} retrying (attempt ${event.attempt})`;
+        case 'step:nudged':
+            return `[step] ${event.stepName} nudged (nudge #${event.nudgeCount})`;
+        case 'step:force-released':
+            return `[step] ${event.stepName} force-released`;
+    }
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args.includes('--help')) {
+        printUsage();
+        process.exit(args.includes('--help') ? 0 : 1);
+    }
+    // Use a file-backed DB so runs survive process restarts and --resume works.
+    const dbPath = path.join(process.cwd(), '.agent-relay', 'workflow-runs.jsonl');
+    const fileDb = new JsonFileWorkflowDb(dbPath);
+    if (!fileDb.isWritable()) {
+        console.warn(`[workflow] warning: cannot write to ${dbPath} — run state will not be persisted (--resume unavailable)`);
+    }
+    const runner = new WorkflowRunner({ db: fileDb });
+    let shuttingDown = false;
+    const shutdown = async (signal) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        console.log(`\n[workflow] ${signal} received — shutting down broker...`);
+        await runner.relay?.shutdown().catch(() => undefined);
+        process.exit(130);
+    };
+    process.on('SIGINT', () => void shutdown('SIGINT'));
+    process.on('SIGTERM', () => void shutdown('SIGTERM'));
+    // ── Resume mode ────────────────────────────────────────────────────────────
+    const resumeIdx = args.indexOf('--resume');
+    if (resumeIdx !== -1) {
+        const runId = args[resumeIdx + 1];
+        if (!runId) {
+            console.error('Error: --resume requires a run ID');
+            process.exit(1);
+        }
+        console.log(`Resuming run ${runId}...`);
+        runner.on((event) => console.log(formatEvent(event)));
+        const result = await runner.resume(runId);
+        if (result.status === 'completed') {
+            console.log(`\nWorkflow completed successfully.`);
+            process.exit(0);
+        }
+        else {
+            console.error(`\nWorkflow ${result.status}${result.error ? `: ${result.error}` : ''}`);
+            process.exit(1);
+        }
+        return;
+    }
+    // ── Normal / validate / dry-run mode ──────────────────────────────────────
+    const yamlPath = args[0];
+    let workflowName;
+    const workflowIdx = args.indexOf('--workflow');
+    if (workflowIdx !== -1 && args[workflowIdx + 1]) {
+        workflowName = args[workflowIdx + 1];
+    }
+    const isValidate = args.includes('--validate');
+    console.log(`Running workflow from ${yamlPath}...`);
+    const isDryRun = !!process.env.DRY_RUN;
+    const config = await runner.parseYamlFile(yamlPath);
+    if (isValidate) {
+        const { validateWorkflow, formatValidationReport } = await import('./validator.js');
+        const issues = validateWorkflow(config);
+        console.log(formatValidationReport(issues, yamlPath));
+        process.exit(issues.some((i) => i.severity === 'error') ? 1 : 0);
+    }
+    if (isDryRun) {
+        const { formatDryRunReport } = await import('./dry-run-format.js');
+        const report = runner.dryRun(config, workflowName);
+        console.log(formatDryRunReport(report));
+        process.exit(report.valid ? 0 : 1);
+    }
+    runner.on((event) => console.log(formatEvent(event)));
+    const result = await runner.execute(config, workflowName);
+    if (result.status === 'completed') {
+        console.log(`\nWorkflow completed successfully.`);
+        process.exit(0);
+    }
+    else {
+        console.error(`\nWorkflow ${result.status}${result.error ? `: ${result.error}` : ''}`);
+        process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/packages/sdk/dist/workflows/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/workflows/cli.ts"],"names":[],"mappings":"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"}

package/packages/sdk/dist/workflows/coordinator.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Swarm Coordinator — pattern selection, agent topology, and workflow lifecycle.
+ *
+ * Orchestrates workflow runs: picks the right swarm pattern (or auto-selects),
+ * resolves agent topology from the config, and drives the run through its
+ * lifecycle states (pending → running → completed / failed / cancelled).
+ */
+import { EventEmitter } from 'node:events';
+import type { AgentDefinition, RelayYamlConfig, SwarmPattern, WorkflowRunRow, WorkflowRunStatus, WorkflowStepRow } from './types.js';
+/** Minimal database client contract accepted by all services. */
+export interface DbClient {
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+}
+/** Describes the communication graph for a set of agents. */
+export interface AgentTopology {
+    pattern: SwarmPattern;
+    agents: AgentDefinition[];
+    /** Agent name → names it can send messages to. */
+    edges: Map<string, string[]>;
+    /** Optional hub agent for hub-spoke / hierarchical. */
+    hub?: string;
+    /** Ordered pipeline stages (pipeline pattern only). */
+    pipelineOrder?: string[];
+}
+export interface SwarmCoordinatorEvents {
+    'run:created': (run: WorkflowRunRow) => void;
+    'run:started': (run: WorkflowRunRow) => void;
+    'run:completed': (run: WorkflowRunRow) => void;
+    'run:failed': (run: WorkflowRunRow) => void;
+    'run:cancelled': (run: WorkflowRunRow) => void;
+    'step:started': (step: WorkflowStepRow) => void;
+    'step:completed': (step: WorkflowStepRow) => void;
+    'step:failed': (step: WorkflowStepRow) => void;
+}
+export declare class SwarmCoordinator extends EventEmitter {
+    private db;
+    constructor(db: DbClient);
+    /**
+     * Select the swarm pattern to use for a config. If the config already
+     * specifies a pattern, it is returned as-is. Otherwise heuristics apply.
+     */
+    selectPattern(config: RelayYamlConfig): SwarmPattern;
+    /**
+     * Build the agent communication topology for a given config and pattern.
+     * Non-interactive agents are excluded from message edges — they only communicate
+     * through step output chaining ({{steps.X.output}}).
+     */
+    resolveTopology(config: RelayYamlConfig, pattern?: SwarmPattern): AgentTopology;
+    /** Internal: resolve topology edges for interactive agents only. */
+    private resolveInteractiveTopology;
+    createRun(workspaceId: string, config: RelayYamlConfig): Promise<WorkflowRunRow>;
+    startRun(runId: string): Promise<WorkflowRunRow>;
+    completeRun(runId: string, stateSnapshot?: Record<string, unknown>): Promise<WorkflowRunRow>;
+    failRun(runId: string, error: string): Promise<WorkflowRunRow>;
+    cancelRun(runId: string): Promise<WorkflowRunRow>;
+    createSteps(runId: string, config: RelayYamlConfig): Promise<WorkflowStepRow[]>;
+    startStep(stepId: string): Promise<WorkflowStepRow>;
+    completeStep(stepId: string, output?: string): Promise<WorkflowStepRow>;
+    failStep(stepId: string, error: string): Promise<WorkflowStepRow>;
+    skipStep(stepId: string): Promise<WorkflowStepRow>;
+    getRun(runId: string): Promise<WorkflowRunRow | null>;
+    getSteps(runId: string): Promise<WorkflowStepRow[]>;
+    getReadySteps(runId: string): Promise<WorkflowStepRow[]>;
+    getRunsByWorkspace(workspaceId: string, status?: WorkflowRunStatus): Promise<WorkflowRunRow[]>;
+    private transitionRun;
+    private pickHub;
+    private resolvePipelineOrder;
+    private resolveEscalationOrder;
+    private resolveDAGEdges;
+}
+//# sourceMappingURL=coordinator.d.ts.map

package/packages/sdk/dist/workflows/coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator.d.ts","sourceRoot":"","sources":["../../src/workflows/coordinator.ts"],"names":[],"mappings":"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"}