agent-relay 2.3.2 → 2.3.5

package/packages/sdk-ts/dist/workflows/barrier.js

@@ -0,0 +1,162 @@
+/**
+ * Barrier Manager — synchronization barriers with all/any/majority semantics.
+ *
+ * Barriers gate downstream workflow steps until a set of upstream agents
+ * or steps have resolved. Supports three resolution modes:
+ *
+ * - **all**      — every agent in `waitFor` must resolve (default)
+ * - **any**      — at least one agent resolves
+ * - **majority** — more than half of `waitFor` must resolve
+ */
+import { randomBytes } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+// ── Manager ─────────────────────────────────────────────────────────────────
+export class BarrierManager extends EventEmitter {
+    db;
+    /** In-memory mode tracking (not persisted — set once at creation). */
+    modes = new Map();
+    timeoutTimers = new Map();
+    constructor(db) {
+        super();
+        this.db = db;
+    }
+    // ── Create ──────────────────────────────────────────────────────────────
+    /**
+     * Create a barrier for a workflow run.
+     */
+    async createBarrier(runId, definition) {
+        const id = `bar_${Date.now()}_${randomBytes(4).toString('hex')}`;
+        const now = new Date().toISOString();
+        const mode = definition.mode ?? 'all';
+        const { rows } = await this.db.query(`INSERT INTO workflow_barriers (id, run_id, barrier_name, wait_for, resolved, is_satisfied, timeout_ms, created_at, updated_at)
+       VALUES ($1, $2, $3, $4, '[]'::jsonb, FALSE, $5, $6, $6)
+       RETURNING *`, [
+            id,
+            runId,
+            definition.name,
+            JSON.stringify(definition.waitFor),
+            definition.timeoutMs ?? null,
+            now,
+        ]);
+        const barrier = rows[0];
+        const key = `${runId}:${definition.name}`;
+        this.modes.set(key, mode);
+        if (definition.timeoutMs) {
+            this.scheduleTimeout(barrier, definition.timeoutMs);
+        }
+        this.emit('barrier:created', barrier);
+        return barrier;
+    }
+    /**
+     * Bulk-create barriers from a list of definitions (e.g. from coordination config).
+     */
+    async createBarriers(runId, definitions) {
+        const results = [];
+        for (const def of definitions) {
+            results.push(await this.createBarrier(runId, def));
+        }
+        return results;
+    }
+    // ── Resolve ─────────────────────────────────────────────────────────────
+    /**
+     * Mark an agent/step as resolved for a barrier. Returns whether the
+     * barrier is now fully satisfied.
+     */
+    async resolve(runId, barrierName, agent) {
+        const now = new Date().toISOString();
+        // Atomic: append agent to resolved array if not already present.
+        const { rows } = await this.db.query(`UPDATE workflow_barriers
+       SET resolved = CASE
+             WHEN resolved @> $3::jsonb THEN resolved
+             ELSE resolved || $3::jsonb
+           END,
+           updated_at = $4
+       WHERE run_id = $1 AND barrier_name = $2 AND is_satisfied = FALSE
+       RETURNING *`, [runId, barrierName, JSON.stringify(agent), now]);
+        if (rows.length === 0) {
+            // Barrier may already be satisfied or not exist.
+            const existing = await this.getBarrier(runId, barrierName);
+            if (!existing)
+                throw new Error(`Barrier ${barrierName} not found for run ${runId}`);
+            return { satisfied: existing.isSatisfied, barrier: existing };
+        }
+        const barrier = rows[0];
+        this.emit('barrier:resolved', barrierName, agent);
+        const key = `${runId}:${barrierName}`;
+        const mode = this.modes.get(key) ?? 'all';
+        if (this.checkSatisfied(barrier, mode)) {
+            return this.markSatisfied(barrier);
+        }
+        return { satisfied: false, barrier };
+    }
+    // ── Queries ─────────────────────────────────────────────────────────────
+    async getBarrier(runId, barrierName) {
+        const { rows } = await this.db.query(`SELECT * FROM workflow_barriers WHERE run_id = $1 AND barrier_name = $2`, [runId, barrierName]);
+        return rows[0] ?? null;
+    }
+    async getBarriers(runId) {
+        const { rows } = await this.db.query(`SELECT * FROM workflow_barriers WHERE run_id = $1 ORDER BY created_at ASC`, [runId]);
+        return rows;
+    }
+    async getUnsatisfiedBarriers(runId) {
+        const { rows } = await this.db.query(`SELECT * FROM workflow_barriers WHERE run_id = $1 AND is_satisfied = FALSE ORDER BY created_at ASC`, [runId]);
+        return rows;
+    }
+    /**
+     * Check if a named barrier is satisfied (useful for gating downstream work).
+     */
+    async isSatisfied(runId, barrierName) {
+        const barrier = await this.getBarrier(runId, barrierName);
+        return barrier?.isSatisfied ?? false;
+    }
+    // ── Cleanup ─────────────────────────────────────────────────────────────
+    cleanup() {
+        for (const timer of this.timeoutTimers.values())
+            clearTimeout(timer);
+        this.timeoutTimers.clear();
+        this.modes.clear();
+    }
+    // ── Private ─────────────────────────────────────────────────────────────
+    checkSatisfied(barrier, mode) {
+        const waitFor = Array.isArray(barrier.waitFor) ? barrier.waitFor : [];
+        const resolved = Array.isArray(barrier.resolved) ? barrier.resolved : [];
+        switch (mode) {
+            case 'all':
+                return waitFor.every((w) => resolved.includes(w));
+            case 'any':
+                return resolved.length > 0;
+            case 'majority':
+                return resolved.length > waitFor.length / 2;
+        }
+    }
+    async markSatisfied(barrier) {
+        const now = new Date().toISOString();
+        const { rows } = await this.db.query(`UPDATE workflow_barriers SET is_satisfied = TRUE, updated_at = $2
+       WHERE id = $1
+       RETURNING *`, [barrier.id, now]);
+        const updated = rows[0];
+        const key = `${barrier.runId}:${barrier.barrierName}`;
+        this.clearTimeout(key);
+        this.emit('barrier:satisfied', updated);
+        return { satisfied: true, barrier: updated };
+    }
+    scheduleTimeout(barrier, timeoutMs) {
+        const key = `${barrier.runId}:${barrier.barrierName}`;
+        const timer = setTimeout(async () => {
+            const current = await this.getBarrier(barrier.runId, barrier.barrierName);
+            if (current && !current.isSatisfied) {
+                this.emit('barrier:timeout', current);
+            }
+        }, timeoutMs);
+        timer.unref();
+        this.timeoutTimers.set(key, timer);
+    }
+    clearTimeout(key) {
+        const timer = this.timeoutTimers.get(key);
+        if (timer) {
+            globalThis.clearTimeout(timer);
+            this.timeoutTimers.delete(key);
+        }
+    }
+}
+//# sourceMappingURL=barrier.js.map

package/packages/sdk-ts/dist/workflows/barrier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"barrier.js","sourceRoot":"","sources":["../../src/workflows/barrier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAiC3C,+EAA+E;AAE/E,MAAM,OAAO,cAAe,SAAQ,YAAY;IACtC,EAAE,CAAW;IACrB,sEAAsE;IAC9D,KAAK,GAAG,IAAI,GAAG,EAAuB,CAAC;IACvC,aAAa,GAAG,IAAI,GAAG,EAAyC,CAAC;IAEzE,YAAY,EAAY;QACtB,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACf,CAAC;IAED,2EAA2E;IAE3E;;OAEG;IACH,KAAK,CAAC,aAAa,CACjB,KAAa,EACb,UAA6B;QAE7B,MAAM,EAAE,GAAG,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACjE,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,IAAI,KAAK,CAAC;QAEtC,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAClC;;mBAEa,EACb;YACE,EAAE;YACF,KAAK;YACL,UAAU,CAAC,IAAI;YACf,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC;YAClC,UAAU,CAAC,SAAS,IAAI,IAAI;YAC5B,GAAG;SACJ,CACF,CAAC;QAEF,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACxB,MAAM,GAAG,GAAG,GAAG,KAAK,IAAI,UAAU,CAAC,IAAI,EAAE,CAAC;QAC1C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAE1B,IAAI,UAAU,CAAC,SAAS,EAAE,CAAC;YACzB,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;QACtD,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;QACtC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,cAAc,CAClB,KAAa,EACb,WAAgC;QAEhC,MAAM,OAAO,GAAiB,EAAE,CAAC;QACjC,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;YAC9B,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;QACrD,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,2EAA2E;IAE3E;;;OAGG;IACH,KAAK,CAAC,OAAO,CACX,KAAa,EACb,WAAmB,EACnB,KAAa;QAEb,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAErC,iEAAiE;QACjE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAClC;;;;;;;mBAOa,EACb,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CACjD,CAAC;QAEF,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,iDAAiD;YACjD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;YAC3D,IAAI,CAAC,QAAQ;gBAAE,MAAM,IAAI,KAAK,CAAC,WAAW,WAAW,sBAAsB,KAAK,EAAE,CAAC,CAAC;YACpF,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAC,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;QAChE,CAAC;QAED,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC;QAElD,MAAM,GAAG,GAAG,GAAG,KAAK,IAAI,WAAW,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC;QAE1C,IAAI,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;YACvC,OAAO,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QACrC,CAAC;QAED,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IACvC,CAAC;IAED,2EAA2E;IAE3E,KAAK,CAAC,UAAU,CAAC,KAAa,EAAE,WAAmB;QACjD,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAClC,yEAAyE,EACzE,CAAC,KAAK,EAAE,WAAW,CAAC,CACrB,CAAC;QACF,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,WAAW,CAAC,KAAa;QAC7B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAClC,2EAA2E,EAC3E,CAAC,KAAK,CAAC,CACR,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,sBAAsB,CAAC,KAAa;QACxC,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAClC,oGAAoG,EACpG,CAAC,KAAK,CAAC,CACR,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,WAAW,CAAC,KAAa,EAAE,WAAmB;QAClD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;QAC1D,OAAO,OAAO,EAAE,WAAW,IAAI,KAAK,CAAC;IACvC,CAAC;IAED,2EAA2E;IAE3E,OAAO;QACL,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE;YAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QACrE,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAC3B,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,2EAA2E;IAEnE,cAAc,CAAC,OAAmB,EAAE,IAAiB;QAC3D,MAAM,OAAO,GAAa,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QAChF,MAAM,QAAQ,GAAa,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QAEnF,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,KAAK;gBACR,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;YACpD,KAAK,KAAK;gBACR,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;YAC7B,KAAK,UAAU;gBACb,OAAO,QAAQ,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,aAAa,CACzB,OAAmB;QAEnB,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAClC;;mBAEa,EACb,CAAC,OAAO,CAAC,EAAE,EAAE,GAAG,CAAC,CAClB,CAAC;QAEF,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACxB,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACtD,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,OAAO,CAAC,CAAC;QAExC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IAC/C,CAAC;IAEO,eAAe,CAAC,OAAmB,EAAE,SAAiB;QAC5D,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;QACtD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,IAAI,EAAE;YAClC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;YAC1E,IAAI,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;gBACpC,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;YACxC,CAAC;QACH,CAAC,EAAE,SAAS,CAAC,CAAC;QACd,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACrC,CAAC;IAEO,YAAY,CAAC,GAAW;QAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,KAAK,EAAE,CAAC;YACV,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;YAC/B,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;CACF"}

package/packages/sdk-ts/dist/workflows/builder.d.ts

@@ -0,0 +1,101 @@
+import type { AgentRelayOptions } from '../relay.js';
+import type { AgentCli, RelayYamlConfig, SwarmPattern, VerificationCheck, WorkflowRunRow } from './types.js';
+import { type WorkflowEventListener, type VariableContext } from './runner.js';
+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;
+}
+/**
+ * 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 declare class WorkflowBuilder {
+    private _name;
+    private _description?;
+    private _pattern;
+    private _maxConcurrency?;
+    private _timeoutMs?;
+    private _channel?;
+    private _agents;
+    private _steps;
+    private _errorHandling?;
+    constructor(name: string);
+    /** Set workflow description. */
+    description(desc: string): this;
+    /** Set swarm pattern (default: "dag"). */
+    pattern(p: SwarmPattern): this;
+    /** Set maximum concurrent agents. */
+    maxConcurrency(n: number): this;
+    /** Set global timeout in milliseconds. */
+    timeout(ms: number): this;
+    /** Set the relay channel for agent communication. */
+    channel(ch: string): this;
+    /** Add an agent definition. */
+    agent(name: string, options: AgentOptions): this;
+    /** Add a workflow step. */
+    step(name: string, options: StepOptions): this;
+    /** Set error handling strategy. */
+    onError(strategy: 'fail-fast' | 'continue' | 'retry', options?: ErrorOptions): this;
+    /** Build and return the RelayYamlConfig object. */
+    toConfig(): RelayYamlConfig;
+    /** Serialize the config to a YAML string. */
+    toYaml(): string;
+    /** Build the config and execute it with the WorkflowRunner. */
+    run(options?: WorkflowRunOptions): Promise<WorkflowRunRow>;
+}
+/**
+ * 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 declare function workflow(name: string): WorkflowBuilder;
+//# sourceMappingURL=builder.d.ts.map

package/packages/sdk-ts/dist/workflows/builder.d.ts.map

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

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

@@ -0,0 +1,179 @@
+import { stringify as stringifyYaml } from 'yaml';
+import { WorkflowRunner } from './runner.js';
+// ── 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 {
+    _name;
+    _description;
+    _pattern = 'dag';
+    _maxConcurrency;
+    _timeoutMs;
+    _channel;
+    _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;
+    }
+    /** 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.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, 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._errorHandling !== undefined)
+            config.errorHandling = this._errorHandling;
+        return config;
+    }
+    /** Serialize the config to a YAML string. */
+    toYaml() {
+        return stringifyYaml(this.toConfig());
+    }
+    /** Build the config and execute it with the WorkflowRunner. */
+    async run(options = {}) {
+        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) {
+    return new WorkflowBuilder(name);
+}
+//# sourceMappingURL=builder.js.map

package/packages/sdk-ts/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-ts/dist/workflows/cli.d.ts

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

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

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

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

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for running relay.yaml workflows.
+ *
+ * Usage:
+ *   relay-workflow <yaml-path> [--workflow <name>]
+ *   npx @agent-relay/broker-sdk run <yaml-path> [--workflow <name>]
+ */
+import { runWorkflow } from './run.js';
+function printUsage() {
+    console.log(`
+Usage: relay-workflow <yaml-path> [options]
+
+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)
+  --help                   Show this help message
+
+Examples:
+  relay-workflow workflows/daytona-migration.yaml
+  relay-workflow workflows/feature-dev.yaml --workflow build-and-test
+`.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})`;
+    }
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args.includes('--help')) {
+        printUsage();
+        process.exit(args.includes('--help') ? 0 : 1);
+    }
+    const yamlPath = args[0];
+    let workflowName;
+    const workflowIdx = args.indexOf('--workflow');
+    if (workflowIdx !== -1 && args[workflowIdx + 1]) {
+        workflowName = args[workflowIdx + 1];
+    }
+    console.log(`Running workflow from ${yamlPath}...`);
+    const result = await runWorkflow(yamlPath, {
+        workflow: workflowName,
+        onEvent(event) {
+            console.log(formatEvent(event));
+        },
+    });
+    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-ts/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-ts/dist/workflows/coordinator.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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.
+     */
+    resolveTopology(config: RelayYamlConfig, pattern?: SwarmPattern): AgentTopology;
+    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 resolveDAGEdges;
+}
+//# sourceMappingURL=coordinator.d.ts.map

package/packages/sdk-ts/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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"}