Local agent runs hard-fail (hang, then 500/503) when Relaycast is degraded — should degrade to local-only

[khaliqgant]

Summary

A local relayflows run of an agent-bearing workflow hard-depends on the
hosted Relaycast service and fails the entire run when that service is
degraded — even for a single-agent pipeline that never needs cross-agent
coordination or the web dashboard. It also hangs ~60s before failing, and
the only escape (AGENT_RELAY_WORKFLOW_DISABLE_RELAYCAST=1) is undocumented and
undiscoverable.

This turns a transient cloud blip into "the product is broken" for a brand-new
user running their first example locally.

What we observed

Two distinct failure modes within minutes, both fatal to the run:

1. Workspace auto-create 500s and the run hangs then fails:

   [workflow 00:00] Resolving Relaycast API key...
   [workflow] FAILED: Failed to auto-create Relaycast workspace: 500
     {"ok":false,"error":{"code":"internal_error","message":"Internal server error"}}
   

   (~60s of "stuck" at "Resolving Relaycast API key..." before the failure surfaced.)

2. Workspace create succeeds, but the broker's relay connection fails:

   [workflow 00:10] API key resolved
   [workflow 00:10] Workspace created for this workflow.
   [broker] connect_relay begin ... channels=wf-triage-guest-email
   [workflow] FAILED: Service Unavailable
   

Direct probing of the endpoint shows it is intermittently healthy — the same
POST https://api.relaycast.dev/v1/workspaces returned HTTP 201 with a valid
rk_live_... key ~0.4s later. So this is server-side instability on the relay
service, on the critical path of every agent run.

Where it comes from

• packages/core/src/runner.ts ~4335: requiresBroker is true for any non-deterministic step when there's no external executor, so an agent pipeline always initializes the broker.
• ~4341–4344: unless AGENT_RELAY_WORKFLOW_DISABLE_RELAYCAST === '1', it calls ensureRelaycastApiKey, which (~2422) always POSTs to create a fresh workspace; a non-2xx throws and fails the run.
• Then the broker's connect_relay can independently fail with 503 "Service Unavailable".

Confirmed workaround: AGENT_RELAY_WORKFLOW_DISABLE_RELAYCAST=1 relayflows run <file> runs fully locally and completes 3 passed, 0 failed. RELAY_API_KEY also bypasses auto-create (but still uses Relaycast).

Expected

A local run should not be held hostage by a cloud coordination/telemetry service:

1. Degrade gracefully. If Relaycast workspace-create or broker connect fails/times out, and the workflow doesn't actually require cross-agent chat (e.g. a one-shot pipeline / single agent), fall back to the local broker and continue — the same thing the disable flag does.
2. Fail fast, don't hang. Bound the workspace-create/connect attempt (a few seconds, not ~60s) and, on failure, print a clear message that names the local-only flag.
3. Make local-only discoverable. Document AGENT_RELAY_WORKFLOW_DISABLE_RELAYCAST, and/or auto-select it when the workflow has no cross-agent coordination and no observer was requested.

Acceptance criteria

• With api.relaycast.dev unreachable or returning 5xx, a single-agent pipeline still runs to completion locally (or fails within a few seconds with a message that tells the user exactly how to run locally).
• No ~60s hang on the workspace-create step.
• The local-only path is documented in the README/CLI help.

Context

Hit while preparing a first-run example for a prospect (Altek). relayflows CLI 1.0.6.
Related: #51 (auto-created workspace not cleaned up), #9 (broker wedge / transient agent-step errors hard-fail).