agent-relay 2.3.13 → 2.4.0

package/packages/sdk/dist/workflows/file-db.js

@@ -0,0 +1,108 @@
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * JSONL-backed WorkflowDb for the CLI.
+ *
+ * Each insert/update appends a line to the file. On read, we scan from the
+ * bottom and take the last record for each ID — so updates naturally shadow
+ * earlier inserts without rewriting the file.
+ *
+ * This makes writes O(1) and reads O(n) where n = number of lines (small for
+ * typical workflows). Resume only reads once at startup, so the read cost is
+ * paid once per CLI invocation.
+ *
+ * File: .agent-relay/workflow-runs.jsonl in the workflow cwd.
+ */
+export class JsonFileWorkflowDb {
+    filePath;
+    /** Whether the storage directory is writable. False = silent no-op mode. */
+    writable;
+    constructor(filePath) {
+        this.filePath = filePath;
+        let writable = false;
+        try {
+            mkdirSync(path.dirname(filePath), { recursive: true });
+            writable = true;
+        }
+        catch {
+            // Permission denied or read-only fs — run in memory-only mode.
+            // The workflow executes normally; resume won't be available for this run.
+        }
+        this.writable = writable;
+    }
+    /** Returns false if the storage directory could not be created (permission error). */
+    isWritable() {
+        return this.writable;
+    }
+    // ── Private helpers ─────────────────────────────────────────────────────
+    append(entry) {
+        if (!this.writable)
+            return;
+        try {
+            appendFileSync(this.filePath, JSON.stringify(entry) + '\n', 'utf8');
+        }
+        catch {
+            // Non-critical — workflow execution continues; resume won't be available.
+        }
+    }
+    /** Read all lines and build the latest snapshot for each ID. */
+    snapshot() {
+        const runs = new Map();
+        const steps = new Map();
+        let raw = '';
+        try {
+            raw = readFileSync(this.filePath, 'utf8');
+        }
+        catch {
+            return { runs, steps };
+        }
+        for (const line of raw.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const entry = JSON.parse(trimmed);
+                if (entry.kind === 'run') {
+                    runs.set(entry.row.id, entry.row);
+                }
+                else {
+                    steps.set(entry.row.id, entry.row);
+                }
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+        return { runs, steps };
+    }
+    // ── WorkflowDb interface ─────────────────────────────────────────────────
+    async insertRun(run) {
+        this.append({ kind: 'run', row: run });
+    }
+    async updateRun(id, patch) {
+        const { runs } = this.snapshot();
+        const existing = runs.get(id);
+        if (!existing)
+            return;
+        this.append({ kind: 'run', row: { ...existing, ...patch, updatedAt: new Date().toISOString() } });
+    }
+    async getRun(id) {
+        const { runs } = this.snapshot();
+        return runs.get(id) ?? null;
+    }
+    async insertStep(step) {
+        this.append({ kind: 'step', row: step });
+    }
+    async updateStep(id, patch) {
+        const { steps } = this.snapshot();
+        const existing = steps.get(id);
+        if (!existing)
+            return;
+        this.append({ kind: 'step', row: { ...existing, ...patch, updatedAt: new Date().toISOString() } });
+    }
+    async getStepsByRunId(runId) {
+        const { steps } = this.snapshot();
+        return Array.from(steps.values()).filter((s) => s.runId === runId);
+    }
+}
+//# sourceMappingURL=file-db.js.map

package/packages/sdk/dist/workflows/file-db.js.map

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

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

@@ -0,0 +1,15 @@
+export * from './types.js';
+export * from './runner.js';
+export * from './custom-steps.js';
+export { Models, ClaudeModels, CodexModels, GeminiModels, CursorModels, CLIs, CLIVersions, CLIRegistry, SwarmPatterns, } from '../models.js';
+export * from './memory-db.js';
+export * from './file-db.js';
+export * from './run.js';
+export * from './builder.js';
+export * from './coordinator.js';
+export * from './barrier.js';
+export * from './state.js';
+export * from './templates.js';
+export { WorkflowTrajectory, type StepOutcome } from './trajectory.js';
+export { formatDryRunReport } from './dry-run-format.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/workflows/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,OAAO,EACL,MAAM,EACN,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,IAAI,EACJ,WAAW,EACX,WAAW,EACX,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC"}

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

@@ -0,0 +1,15 @@
+export * from './types.js';
+export * from './runner.js';
+export * from './custom-steps.js';
+export { Models, ClaudeModels, CodexModels, GeminiModels, CursorModels, CLIs, CLIVersions, CLIRegistry, SwarmPatterns, } from '../models.js';
+export * from './memory-db.js';
+export * from './file-db.js';
+export * from './run.js';
+export * from './builder.js';
+export * from './coordinator.js';
+export * from './barrier.js';
+export * from './state.js';
+export * from './templates.js';
+export { WorkflowTrajectory } from './trajectory.js';
+export { formatDryRunReport } from './dry-run-format.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/workflows/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,OAAO,EACL,MAAM,EACN,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,IAAI,EACJ,WAAW,EACX,WAAW,EACX,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAoB,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC"}

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

@@ -0,0 +1,38 @@
+import type { AgentRelayOptions } from '../relay.js';
+import type { DryRunReport, TrajectoryConfig, WorkflowRunRow } from './types.js';
+import { type WorkflowEventListener, type VariableContext } from './runner.js';
+/**
+ * Options for the `runWorkflow` convenience function.
+ */
+export interface RunWorkflowOptions {
+    /** Workflow name within the YAML file. Defaults to the first workflow. */
+    workflow?: string;
+    /** Template variable substitutions for {{variable}} placeholders. */
+    vars?: VariableContext;
+    /** Working directory. Defaults to process.cwd(). */
+    cwd?: string;
+    /** AgentRelay options (all optional — broker starts automatically). */
+    relay?: AgentRelayOptions;
+    /** Progress callback for workflow events. */
+    onEvent?: WorkflowEventListener;
+    /** Override trajectory config. Set to false to disable trajectory recording. */
+    trajectories?: TrajectoryConfig | false;
+    /** Validate and show execution plan without running. */
+    dryRun?: boolean;
+}
+/**
+ * Run a workflow from a relay.yaml file with zero configuration.
+ *
+ * @example
+ * ```typescript
+ * import { runWorkflow } from "@agent-relay/sdk/workflows";
+ *
+ * const result = await runWorkflow("workflows/daytona-migration.yaml");
+ * console.log(result.status); // "completed" | "failed"
+ * ```
+ */
+export declare function runWorkflow(yamlPath: string, options: RunWorkflowOptions & {
+    dryRun: true;
+}): Promise<DryRunReport>;
+export declare function runWorkflow(yamlPath: string, options?: RunWorkflowOptions): Promise<WorkflowRunRow>;
+//# sourceMappingURL=run.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/workflows/run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjF,OAAO,EAAkB,KAAK,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAG/F;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,6CAA6C;IAC7C,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAChC,gFAAgF;IAChF,YAAY,CAAC,EAAE,gBAAgB,GAAG,KAAK,CAAC;IACxC,wDAAwD;IACxD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,kBAAkB,GAAG;IAAE,MAAM,EAAE,IAAI,CAAA;CAAE,GAC7C,OAAO,CAAC,YAAY,CAAC,CAAC;AACzB,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC"}

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

@@ -0,0 +1,25 @@
+import { WorkflowRunner } from './runner.js';
+import { formatDryRunReport } from './dry-run-format.js';
+export async function runWorkflow(yamlPath, options = {}) {
+    const runner = new WorkflowRunner({
+        cwd: options.cwd,
+        relay: options.relay,
+    });
+    const config = await runner.parseYamlFile(yamlPath);
+    // Allow programmatic trajectory override
+    if (options.trajectories !== undefined) {
+        config.trajectories = options.trajectories;
+    }
+    // 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);
+}
+//# sourceMappingURL=run.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/workflows/run.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAoD,MAAM,aAAa,CAAC;AAC/F,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAsCzD,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,QAAgB,EAChB,UAA8B,EAAE;IAEhC,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC;QAChC,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,KAAK,EAAE,OAAO,CAAC,KAAK;KACrB,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IAEpD,yCAAyC;IACzC,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACvC,MAAM,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAC7C,CAAC;IAED,uEAAuE;IACvE,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;IAEzD,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;QACrE,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC;QACxC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IAED,OAAO,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;AAChE,CAAC"}

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

@@ -0,0 +1,320 @@
+/**
+ * WorkflowRunner — parses relay.yaml, validates config, resolves templates,
+ * executes steps (sequential/parallel/DAG), runs verification checks,
+ * persists state to DB, and supports pause/resume/abort with retries.
+ */
+import type { AgentCli, DryRunReport, RelayYamlConfig, WorkflowRunRow, WorkflowStepRow } from './types.js';
+import { AgentRelay } from '../relay.js';
+import type { AgentRelayOptions } from '../relay.js';
+/** Minimal DB adapter so the runner is not coupled to a specific driver. */
+export interface WorkflowDb {
+    insertRun(run: WorkflowRunRow): Promise<void>;
+    updateRun(id: string, patch: Partial<WorkflowRunRow>): Promise<void>;
+    getRun(id: string): Promise<WorkflowRunRow | null>;
+    insertStep(step: WorkflowStepRow): Promise<void>;
+    updateStep(id: string, patch: Partial<WorkflowStepRow>): Promise<void>;
+    getStepsByRunId(runId: string): Promise<WorkflowStepRow[]>;
+}
+export type WorkflowEvent = {
+    type: 'run:started';
+    runId: string;
+} | {
+    type: 'run:completed';
+    runId: string;
+} | {
+    type: 'run:failed';
+    runId: string;
+    error: string;
+} | {
+    type: 'run:cancelled';
+    runId: string;
+} | {
+    type: 'step:started';
+    runId: string;
+    stepName: string;
+} | {
+    type: 'step:completed';
+    runId: string;
+    stepName: string;
+    output?: string;
+} | {
+    type: 'step:failed';
+    runId: string;
+    stepName: string;
+    error: string;
+} | {
+    type: 'step:skipped';
+    runId: string;
+    stepName: string;
+} | {
+    type: 'step:retrying';
+    runId: string;
+    stepName: string;
+    attempt: number;
+} | {
+    type: 'step:nudged';
+    runId: string;
+    stepName: string;
+    nudgeCount: number;
+} | {
+    type: 'step:force-released';
+    runId: string;
+    stepName: string;
+};
+export type WorkflowEventListener = (event: WorkflowEvent) => void;
+export interface WorkflowRunnerOptions {
+    db?: WorkflowDb;
+    workspaceId?: string;
+    relay?: AgentRelayOptions;
+    cwd?: string;
+    summaryDir?: string;
+}
+export interface VariableContext {
+    [key: string]: string | number | boolean | undefined;
+}
+export declare class WorkflowRunner {
+    private readonly db;
+    private readonly workspaceId;
+    private readonly relayOptions;
+    private readonly cwd;
+    private readonly summaryDir;
+    /** @internal exposed for CLI signal-handler shutdown only */
+    relay?: AgentRelay;
+    private relaycast?;
+    private relaycastAgent?;
+    private relayApiKey?;
+    private relayApiKeyAutoCreated;
+    private channel?;
+    private trajectory?;
+    private abortController?;
+    private paused;
+    private pauseResolver?;
+    private listeners;
+    /** Current config for the active run, so spawnAndWait can access swarm config. */
+    private currentConfig?;
+    /** Current run ID for event emission from spawnAndWait context. */
+    private currentRunId?;
+    /** Live Agent handles keyed by name, for hub-mediated nudging. */
+    private readonly activeAgentHandles;
+    private readonly ptyOutputBuffers;
+    private readonly ptyListeners;
+    private readonly ptyLogStreams;
+    /** Path to workers.json so `agents:kill` can find workflow-spawned agents */
+    private readonly workersPath;
+    /** In-memory tracking of active workers to avoid race conditions on workers.json */
+    private readonly activeWorkers;
+    /** Mutex for serializing workers.json file access */
+    private workersFileLock;
+    /** Timestamp when the current workflow run started, for elapsed-time logging. */
+    private runStartTime?;
+    /** Unsubscribe handle for broker stderr listener wired during a run. */
+    private unsubBrokerStderr?;
+    /** Tracks last idle log time per agent to debounce idle warnings (30s multiples). */
+    private readonly lastIdleLog;
+    /** Tracks last logged activity type per agent to avoid duplicate status lines. */
+    private readonly lastActivity;
+    constructor(options?: WorkflowRunnerOptions);
+    /** Log a progress message with elapsed time since run start. */
+    private log;
+    /**
+     * Ensure a Relaycast workspace API key is available for the broker.
+     * Resolution order:
+     *   1. RELAY_API_KEY environment variable (explicit override)
+     *   2. Auto-create a fresh workspace via the Relaycast API
+     *
+     * Each workflow run gets its own isolated workspace — no caching, no sharing.
+     */
+    private ensureRelaycastApiKey;
+    private getRelayEnv;
+    private getRelaycastBaseUrl;
+    private getRelaycastClient;
+    private ensureRelaycastRunnerAgent;
+    private createAndJoinRelaycastChannel;
+    private registerRelaycastExternalAgent;
+    private startRelaycastHeartbeat;
+    on(listener: WorkflowEventListener): () => void;
+    private emit;
+    /** Parse a relay.yaml file from disk. */
+    parseYamlFile(filePath: string): Promise<RelayYamlConfig>;
+    /** Parse a relay.yaml string. */
+    parseYamlString(raw: string, source?: string): RelayYamlConfig;
+    /** Validate a config object against the RelayYamlConfig shape. */
+    validateConfig(config: unknown, source?: string): asserts config is RelayYamlConfig;
+    /**
+     * Validate a workflow config and simulate execution waves without spawning agents.
+     * Returns a DryRunReport with DAG analysis, agent summary, and wave breakdown.
+     */
+    dryRun(config: RelayYamlConfig, workflowName?: string, vars?: VariableContext): DryRunReport;
+    private validateWorkflow;
+    private detectCycles;
+    private detectLeadWorkerDeadlock;
+    /** Resolve {{variable}} placeholders in all task strings. */
+    resolveVariables(config: RelayYamlConfig, vars: VariableContext): RelayYamlConfig;
+    private interpolate;
+    private resolveDotPath;
+    /** Build a nested context from completed step outputs for {{steps.X.output}} resolution. */
+    private buildStepOutputContext;
+    /** Interpolate step-output variables, silently skipping unresolved ones (they may be user vars). */
+    private interpolateStepTask;
+    /** Execute a named workflow from a validated config. */
+    execute(config: RelayYamlConfig, workflowName?: string, vars?: VariableContext): Promise<WorkflowRunRow>;
+    /** Resume a previously paused or partially completed run. */
+    resume(runId: string, vars?: VariableContext): Promise<WorkflowRunRow>;
+    private runWorkflowCore;
+    /** Pause execution. Currently-running steps will finish but no new steps start. */
+    pause(): void;
+    /** Resume after a pause(). */
+    unpause(): void;
+    /** Abort the current run. Running agents are released. */
+    abort(): void;
+    private executeSteps;
+    private findReadySteps;
+    /**
+     * Execute preflight checks before any workflow steps.
+     * All checks must pass or the workflow fails immediately.
+     */
+    private runPreflightChecks;
+    /** Check if a step is deterministic (shell command) vs agent (LLM-powered). */
+    private isDeterministicStep;
+    /** Check if a step is a worktree (git worktree setup) step. */
+    private isWorktreeStep;
+    private executeStep;
+    /**
+     * Execute a deterministic step (shell command).
+     * Fast, reliable, $0 LLM cost.
+     */
+    private executeDeterministicStep;
+    /**
+     * Execute a worktree step (git worktree setup).
+     * Fast, reliable, $0 LLM cost.
+     * Outputs the worktree path for downstream steps to use.
+     */
+    private executeWorktreeStep;
+    /**
+     * Execute an agent step (LLM-powered).
+     */
+    private executeAgentStep;
+    /**
+     * Build the CLI command and arguments for a non-interactive agent execution.
+     * Each CLI has a specific flag for one-shot prompt mode.
+     */
+    static buildNonInteractiveCommand(cli: AgentCli, task: string, extraArgs?: string[]): {
+        cmd: string;
+        args: string[];
+    };
+    /**
+     * Apply preset defaults to an agent definition.
+     * Explicit fields on the definition always win over preset-inferred defaults.
+     */
+    private static resolveAgentDef;
+    /**
+     * Returns a preset-specific prefix that is prepended to the non-interactive
+     * enforcement block in execNonInteractive.
+     */
+    /**
+     * Returns a prefix injected into the task prompt for non-interactive agents.
+     * Lead agents are always interactive (PTY), so they never reach execNonInteractive
+     * and there is no 'lead' case here.
+     */
+    private buildPresetInjection;
+    /**
+     * Execute an agent as a non-interactive subprocess.
+     * No PTY, no relay messaging, no /exit injection. The process receives its task
+     * as a CLI argument and stdout is captured as the step output.
+     */
+    private execNonInteractive;
+    private spawnAndWait;
+    /** Patterns where a hub agent coordinates spoke agents. */
+    private static readonly HUB_PATTERNS;
+    /** Roles that indicate a coordinator/lead agent (eligible for delegation guidance). */
+    private static readonly HUB_ROLES;
+    /**
+     * Wait for agent exit with idle detection and nudging.
+     * If no idle nudge config is set, falls through to simple waitForExit.
+     */
+    private waitForExitWithIdleNudging;
+    /**
+     * Send a nudge to an idle agent. Uses hub-mediated nudge for hub patterns,
+     * or direct system injection otherwise.
+     */
+    private nudgeIdleAgent;
+    /**
+     * Find the hub agent for hub-mediated nudging.
+     * Returns the hub's live Agent handle if this is a hub pattern and the idle agent is not the hub.
+     */
+    private resolveHubForNudge;
+    private runVerification;
+    private updateRunStatus;
+    private markStepFailed;
+    private markDownstreamSkipped;
+    private checkAborted;
+    private waitIfPaused;
+    private delay;
+    /**
+     * Build a metadata note about non-interactive workers for inclusion in interactive agent tasks.
+     * Returns undefined if there are no non-interactive agents.
+     */
+    private buildNonInteractiveAwareness;
+    /**
+     * Build guidance that encourages agents to autonomously delegate subtasks
+     * to helper agents when work is too complex for a single pass.
+     */
+    /**
+     * Returns a relay registration preamble for CLIs that don't auto-call
+     * `register` via the MCP system prompt (everyone except claude).
+     *
+     * Claude reads the Relaycast system prompt and registers on its own.
+     * Codex, gemini, etc. have the MCP server configured with the workspace
+     * key, but they won't call `register` unless explicitly told to.
+     */
+    private buildRelayRegistrationNote;
+    private buildDelegationGuidance;
+    /** Post a message to the workflow channel. Fire-and-forget — never throws or blocks. */
+    private postToChannel;
+    /** Post a rich completion report to the channel. */
+    private postCompletionReport;
+    /** Post a failure report to the channel. */
+    private postFailureReport;
+    /**
+     * Log a human-readable run summary to the console after completion or failure.
+     * Extracts the last meaningful lines from each step's raw PTY output.
+     */
+    private logRunSummary;
+    /**
+     * Extract a useful excerpt from raw PTY output.
+     * Looks for the agent's final text output (ignoring ANSI, system prompts, tool calls).
+     */
+    private extractOutputExcerpt;
+    /** Analyze DAG structure for trajectory context. */
+    private analyzeDAG;
+    /** Collect step outcomes for trajectory synthesis. */
+    private collectOutcomes;
+    private generateId;
+    private generateShortId;
+    /** Strip ANSI escape codes from terminal output — delegates to pty.ts canonical regex. */
+    private static stripAnsi;
+    /**
+     * Strip TUI chrome from PTY-captured output before posting to a channel.
+     * Removes: ANSI codes, unicode spinner/thinking characters, cursor-movement
+     * artifacts, and collapses runs of blank lines to a single blank line.
+     * The raw (ANSI-stripped) output is still written to disk for step chaining.
+     */
+    private static scrubForChannel;
+    /** Sanitize a workflow name into a valid channel name. */
+    private sanitizeChannelName;
+    /** Directory for persisted step outputs: .agent-relay/step-outputs/{runId}/ */
+    private getStepOutputDir;
+    /** Persist step output to disk and post full output as a channel message. */
+    private persistStepOutput;
+    /** Load persisted step output from disk. */
+    private loadStepOutput;
+    /** Get or create the worker logs directory (.agent-relay/team/worker-logs) */
+    private getWorkerLogsDir;
+    /** Register a spawned agent in workers.json so `agents:kill` can find it. */
+    private registerWorker;
+    /** Remove a spawned agent from workers.json after it exits. */
+    private unregisterWorker;
+    private readWorkers;
+    private writeWorkers;
+}
+//# sourceMappingURL=runner.d.ts.map

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

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