agent-relay 3.0.1 → 3.0.2

package/README.md

@@ -1,275 +1,60 @@
 # agent-relay
 
-> Real-time messaging between AI agents. Sub-5ms latency, any CLI, any language.
+> Real-time messaging between AI agents.
 
-[![npm](https://img.shields.io/npm/v/agent-relay)](https://www.npmjs.com/package/agent-relay)
+[![npm](https://img.shields.io/npm/v/@agent-relay/sdk)](https://www.npmjs.com/package/@agent-relay/sdk)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
 ---
 
 ## Install
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/AgentWorkforce/relay/main/install.sh | bash
-```
-
-Or via npm (requires Node.js 18+):
-
-```bash
-npm install -g agent-relay
-```
-
-## Quick Start
-
-```bash
-agent-relay up --dashboard
-```
-
-Open **http://localhost:3888** to spawn agents, view real-time status, and stream logs.
-
----
-
-## CLI Reference
-
-| Command                                 | Description              |
-| --------------------------------------- | ------------------------ |
-| `agent-relay up`                        | Start broker + dashboard |
-| `agent-relay down`                      | Stop broker              |
-| `agent-relay spawn <name> <cli> "task"` | Spawn a worker agent     |
-| `agent-relay status`                    | Check broker status      |
-| `agent-relay run workflow.yaml`         | Run a YAML workflow      |
-| `agent-relay run --template feature-dev`| Run a built-in template  |
-
----
-
-## Workflows
-
-Define multi-agent workflows in YAML, TypeScript, or Python. Run locally or queue to the cloud for 24/7 execution:
-
-```bash
-# Run locally
-agent-relay run workflow.yaml --task "Add OAuth2 support"
-
-# Queue to cloud — durable, scalable, runs in sandboxes
-agent-relay run workflow.yaml --cloud --task "Add OAuth2 support"
-
-# Use built-in templates
-agent-relay run --template feature-dev --task "Add user dashboard"
-```
-
-### relay.yaml
-
-Blueprint-style workflows combine **agent steps** (LLM-powered) with **deterministic steps** (shell commands) for faster, cheaper, more reliable execution:
-
-```yaml
-version: "1.0"
-name: ship-feature
-
-agents:
-  - name: planner
-    cli: claude
-    model: opus
-  - name: developer
-    cli: codex
-
-workflows:
-  - name: default
-    preflight:
-      - command: git status --porcelain
-        failIf: non-empty
-    steps:
-      - name: plan
-        agent: planner
-        task: "Create implementation plan for: {{task}}"
-      - name: create-branch
-        type: deterministic
-        command: git checkout -b feature/{{branch-name}}
-        dependsOn: [plan]
-      - name: implement
-        agent: developer
-        task: "Implement: {{steps.plan.output}}"
-        dependsOn: [create-branch]
-      - name: test
-        type: deterministic
-        command: npm test
-        dependsOn: [implement]
-      - name: commit
-        type: deterministic
-        command: git add -A && git commit -m "feat: {{task}}"
-        dependsOn: [test]
-```
-
-**Benefits:** Deterministic steps run instantly ($0 LLM cost), catch issues early with preflight checks, and git commands can't hallucinate.
-
-Also available as fluent builders in [TypeScript SDK](https://www.npmjs.com/package/@agent-relay/sdk) and [Python SDK](https://pypi.org/project/agent-relay/).
-
-### Built-in Templates
-
-All templates use blueprint-style hybrid workflows with deterministic quality gates.
-
-| Template         | Pattern      | Description                                      |
-| ---------------- | ------------ | ------------------------------------------------ |
-| `feature-dev`    | hub-spoke    | Plan, implement, review, and finalize a feature  |
-| `bug-fix`        | hub-spoke    | Investigate, patch, validate, and document       |
-| `code-review`    | fan-out      | Parallel multi-reviewer assessment               |
-| `security-audit` | pipeline     | Scan, triage, remediate, and verify              |
-| `refactor`       | hierarchical | Analyze, plan, execute, and validate             |
-| `documentation`  | handoff      | Research, draft, review, and publish             |
-
----
-
-## SDK Usage
-
 ```bash
 npm install @agent-relay/sdk
 ```
 
-### Agent-to-Agent Messaging
+## Usage
 
 ```typescript
-import { AgentRelay, Models } from '@agent-relay/sdk';
+import { AgentRelay, Models } from "@agent-relay/sdk";
 
 const relay = new AgentRelay();
 
-// Spawn agents with different CLIs and models
-const planner = await relay.claude.spawn({
-  name: 'Planner',
-  model: Models.Claude.OPUS
-});
+relay.onMessageReceived = (msg) =>
+  console.log(`[${msg.from} → ${msg.to}]: ${msg.text}`);
+
+const channel = ["tic-tac-toe"];
 
-const coder = await relay.codex.spawn({
-  name: 'Coder',
-  model: Models.Codex.CODEX_5_3
+const x = await relay.claude.spawn({
+  name: "PlayerX",
+  model: Models.Claude.SONNET,
+  channels: channel,
+  task: "Play tic-tac-toe as X against PlayerO. You go first.",
+});
+const o = await relay.codex.spawn({
+  name: "PlayerO",
+  model: Models.Codex.GPT_5_3_CODEX_SPARK,
+  channels: channel,
+  task: "Play tic-tac-toe as O against PlayerX.",
 });
 
-// Send messages between agents
-await planner.sendMessage({ to: 'Coder', text: 'Implement the auth module' });
+console.log("Waiting for agents to be ready...");
+await Promise.all([
+  relay.waitForAgentReady("PlayerX"),
+  relay.waitForAgentReady("PlayerO"),
+]);
+console.log("Both ready. Starting game.");
 
-// Listen for messages
-relay.onMessageReceived = (msg) => {
-  console.log(`${msg.from} → ${msg.to}: ${msg.text}`);
-};
+relay.system().sendMessage({ to: "PlayerX", text: "Start." });
 
+const FIVE_MINUTES = 5 * 60 * 1000;
+await AgentRelay.waitForAny([x, o], FIVE_MINUTES);
 await relay.shutdown();
 ```
 
-### Multi-Agent Workflows
-
-Build workflows with different swarm patterns:
-
-```typescript
-import { workflow, Models, SwarmPatterns } from '@agent-relay/sdk/workflows';
-
-// Hub-spoke: Lead coordinates workers
-const result = await workflow('feature-build')
-  .pattern(SwarmPatterns.HUB_SPOKE)
-  .agent('lead', { cli: 'claude', model: Models.Claude.OPUS, role: 'Coordinator' })
-  .agent('dev1', { cli: 'codex', model: Models.Codex.CODEX_5_3, role: 'Developer' })
-  .agent('dev2', { cli: 'cursor', model: Models.Cursor.CLAUDE_SONNET, role: 'Developer' })
-  .step('plan', { agent: 'lead', task: 'Break down the feature into tasks' })
-  .step('impl1', { agent: 'dev1', task: 'Implement backend', dependsOn: ['plan'] })
-  .step('impl2', { agent: 'dev2', task: 'Implement frontend', dependsOn: ['plan'] })
-  .step('review', { agent: 'lead', task: 'Review and merge', dependsOn: ['impl1', 'impl2'] })
-  .run();
-```
-
-**Swarm Patterns:**
-
-| Category        | Patterns                                                    |
-| --------------- | ----------------------------------------------------------- |
-| **Core**        | `dag`, `fan-out`, `pipeline`, `hub-spoke`, `consensus`, `mesh` |
-| **Data**        | `map-reduce`, `scatter-gather`                              |
-| **Quality**     | `supervisor`, `reflection`, `verifier`                      |
-| **Adversarial** | `red-team`, `auction`                                       |
-| **Resilience**  | `escalation`, `saga`, `circuit-breaker`                     |
-
-Auto-pattern selection: define agents with roles like `mapper`, `reducer`, `tier-1`, `attacker`, `defender` and the pattern is auto-selected.
-
----
-
-## Cloud
-
-Scale to teams and automate with [Agent Relay Cloud](https://agent-relay.com):
-
-```bash
-agent-relay cloud link      # Link your machine
-agent-relay cloud agents    # List agents across machines
-agent-relay cloud send AgentName "Your message"
-```
-
-### Multi-Agent Orchestration
-
-Spawn agent teams in the cloud — each agent runs in its own isolated sandbox but can communicate with teammates:
-
-- **Isolated Sandboxes**: Each agent gets a secure container with full dev environment
-- **Cross-Sandbox Messaging**: Agents collaborate via relay channels despite isolation
-- **24/7 Durable Workflows**: Queue workflows to run continuously, survive restarts
-- **Auto-Scaling**: Workspaces scale up/down based on agent load
-
-```bash
-# Queue a workflow to run in the cloud
-agent-relay run workflow.yaml --cloud --task "Refactor auth module"
-
-# Workflows persist, scale, and run even when you're offline
-```
-
-### Integrations
-
-| Integration | Capabilities |
-| ----------- | ------------ |
-| **GitHub** | CI auto-fix, @mentions in PRs, issue assignment triggers |
-| **Linear** | Issue assignment spawns agents, status sync |
-| **Slack** | Chat with agents, trigger workflows from Slack commands |
-
-### CI Auto-Fix
-
-Install the [Agent Relay GitHub App](https://github.com/apps/agent-relay):
-
-```
-1. CI fails on PR #123
-2. Agent Relay: "🔴 CI Failure Detected, spawning @ci-fix agent..."
-3. Agent analyzes logs, fixes issue, pushes commit
-4. Agent Relay: "✅ CI Fix Applied — please re-run checks"
-```
-
----
-
-## Architecture
-
-Agent Relay is built from modular components that work together:
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        Your Application                         │
-├─────────────────────────────────────────────────────────────────┤
-│  agent-relay CLI    │    @agent-relay/sdk    │    relay.yaml   │
-├─────────────────────────────────────────────────────────────────┤
-│                         Relay Broker                            │
-│  • Agent lifecycle  • Message routing  • PTY management        │
-├─────────────────────────────────────────────────────────────────┤
-│                         Relaycast                               │
-│  • REST API  • WebSocket events  • Channels & threads          │
-├─────────────────────────────────────────────────────────────────┤
-│  Claude  │  Codex  │  Gemini  │  Cursor  │  Aider  │  Goose   │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Components
-
-| Component | Description |
-| --------- | ----------- |
-| **Relay Broker** | Core message router with sub-5ms latency. Manages agent lifecycle, PTY sessions, and message delivery. |
-| **Relaycast** | Communication layer with REST API and WebSocket. Provides channels, threads, reactions, and file attachments. Framework-agnostic — works with CrewAI, LangGraph, AutoGen, or raw API calls. |
-| **Relay Dashboard** | Real-time monitoring UI. View agent status, stream logs, and manage workflows from the browser. |
-| **Relay Cloud** | Multi-tenant cloud platform with auto-scaling, billing, and webhook integrations for GitHub/Linear/Slack. |
-| **Trajectories** | Decision capture system. Records the "why" behind code changes — decisions, challenges, and confidence scores — as searchable institutional memory. |
-
-### How It Works
-
-1. **Zero modification**: Agents run unmodified CLI tools (Claude Code, Codex, etc.) in PTY sessions
-2. **MCP protocol**: Agents communicate via standard MCP tools — no custom SDK required inside agents
-3. **Mix AI providers**: Combine Claude, GPT, and Gemini agents in a single workflow — each using their strengths
-4. **Workflow engine**: YAML workflows parsed and executed with dependency resolution, retries, and verification
+## Supported CLI’s
+- Claude
+- Codex
 
 ---
 
@@ -279,4 +64,4 @@ Apache-2.0 — Copyright 2026 Agent Workforce Incorporated
 
 ---
 
-**Links:** [Documentation](https://docs.agent-relay.com/) · [Issues](https://github.com/AgentWorkforce/relay/issues) · [Cloud](https://agent-relay.com) · [Discord](https://discord.gg/6E6CTxM8um)
+**Links:** [Documentation](https://docs.agent-relay.com/) · [Issues](https://github.com/AgentWorkforce/relay/issues) · [Discord](https://discord.gg/6E6CTxM8um)

package/dist/index.cjs

@@ -8989,6 +8989,8 @@ var AgentRelayClient = class _AgentRelayClient {
   eventBuffer = [];
   maxBufferSize = 1e3;
   exitPromise;
+  /** The workspace key returned by the broker in its hello_ack response. */
+  workspaceKey;
   constructor(options = {}) {
     this.options = {
       binaryPath: options.binaryPath ?? resolveDefaultBinaryPath(),
@@ -9250,8 +9252,11 @@ var AgentRelayClient = class _AgentRelayClient {
         resolve3();
       });
     });
-    await this.requestHello();
+    const helloAck = await this.requestHello();
     console.log("[broker] Broker ready (hello handshake complete)");
+    if (helloAck.workspace_key) {
+      this.workspaceKey = helloAck.workspace_key;
+    }
   }
   disposeProcessHandles() {
     this.stdoutRl?.close();
@@ -9367,12 +9372,16 @@ var AgentRelayClient = class _AgentRelayClient {
   }
 };
 var CLI_MODEL_FLAG_CLIS = /* @__PURE__ */ new Set(["claude", "codex", "gemini", "goose", "aider"]);
+var CLI_DEFAULT_ARGS = {
+  codex: ["-c", "check_for_update_on_startup=false"]
+};
 function buildPtyArgsWithModel(cli, args, model) {
-  const baseArgs = [...args];
+  const cliName = cli.split(":")[0].trim().toLowerCase();
+  const defaultArgs = CLI_DEFAULT_ARGS[cliName] ?? [];
+  const baseArgs = [...defaultArgs, ...args];
   if (!model) {
     return baseArgs;
   }
-  const cliName = cli.split(":")[0].trim().toLowerCase();
   if (!CLI_MODEL_FLAG_CLIS.has(cliName)) {
     return baseArgs;
   }
@@ -9410,7 +9419,19 @@ function resolveDefaultBinaryPath() {
   if (import_node_fs.default.existsSync(workspaceRelease)) {
     return workspaceRelease;
   }
-  const bundled = import_node_path.default.resolve(moduleDir, "..", "bin", brokerExe);
+  const binDir = import_node_path.default.resolve(moduleDir, "..", "bin");
+  const platformMap = {
+    darwin: { arm64: "darwin-arm64", x64: "darwin-x64" },
+    linux: { arm64: "linux-arm64", x64: "linux-x64" }
+  };
+  const suffix = platformMap[process.platform]?.[process.arch];
+  if (suffix) {
+    const platformBinary = import_node_path.default.join(binDir, `agent-relay-broker-${suffix}`);
+    if (import_node_fs.default.existsSync(platformBinary)) {
+      return platformBinary;
+    }
+  }
+  const bundled = import_node_path.default.join(binDir, brokerExe);
   if (import_node_fs.default.existsSync(bundled)) {
     return bundled;
   }
@@ -15176,7 +15197,7 @@ var DefaultModels = {
 };
 
 // node_modules/@relaycast/sdk/dist/version.js
-var SDK_VERSION = "0.4.0";
+var SDK_VERSION = "0.4.2";
 
 // node_modules/@relaycast/types/node_modules/zod/v4/classic/external.js
 var external_exports2 = {};
@@ -45021,12 +45042,26 @@ var AgentRelay = class {
   onDeliveryUpdate = null;
   onAgentExitRequested = null;
   onAgentIdle = null;
+  // ── Public accessors ────────────────────────────────────────────────────
+  /** The resolved Relaycast workspace API key (available after first spawn). */
+  get workspaceKey() {
+    return this.relayApiKey;
+  }
+  /** Observer URL for the auto-created workspace (available after first spawn). */
+  get observerUrl() {
+    if (!this.relayApiKey)
+      return void 0;
+    return `https://observer.relaycast.dev/?key=${this.relayApiKey}`;
+  }
   // Shorthand spawners
   codex;
   claude;
   gemini;
   clientOptions;
   defaultChannels;
+  workspaceName;
+  relaycastBaseUrl;
+  relayApiKey;
   client;
   startPromise;
   unsubEvent;
@@ -45043,6 +45078,8 @@ var AgentRelay = class {
   idleResolverSeq = 0;
   constructor(options = {}) {
     this.defaultChannels = options.channels ?? ["general"];
+    this.workspaceName = options.workspaceName;
+    this.relaycastBaseUrl = options.relaycastBaseUrl;
     this.clientOptions = {
       binaryPath: options.binaryPath,
       binaryArgs: options.binaryArgs,
@@ -45128,7 +45165,7 @@ var AgentRelay = class {
     if (waitForMessage) {
       return this.waitForAgentMessage(name, timeoutMs ?? 6e4);
     }
-    return this.waitForAgentReady(name, timeoutMs ?? 3e4);
+    return this.waitForAgentReady(name, timeoutMs ?? 6e4);
   }
   // ── Human source ────────────────────────────────────────────────────────
   human(opts) {
@@ -45318,7 +45355,7 @@ var AgentRelay = class {
    * The agent's CLI may not yet be ready to receive messages.
    * Use `waitForAgentMessage()` for full readiness.
    */
-  async waitForAgentReady(name, timeoutMs = 3e4) {
+  async waitForAgentReady(name, timeoutMs = 6e4) {
     const client = await this.ensureStarted();
     const existing = this.knownAgents.get(name);
     if (existing && this.readyAgents.has(name)) {
@@ -45492,14 +45529,42 @@ var AgentRelay = class {
       }
     }
   }
+  /**
+   * Ensure a Relaycast workspace API key is available.
+   * Resolution order:
+   *   1. Already resolved (cached from a previous call)
+   *   2. RELAY_API_KEY in options.env
+   *   3. RELAY_API_KEY in process.env
+   *   4. Auto-create a fresh workspace via the Relaycast REST API
+   */
+  async ensureRelaycastApiKey() {
+    if (this.relayApiKey)
+      return;
+    const envKey = this.clientOptions.env?.RELAY_API_KEY ?? process.env.RELAY_API_KEY;
+    if (envKey) {
+      this.relayApiKey = envKey;
+      if (!this.clientOptions.env) {
+        this.clientOptions.env = { ...process.env, RELAY_API_KEY: envKey };
+      } else if (!this.clientOptions.env.RELAY_API_KEY) {
+        this.clientOptions.env.RELAY_API_KEY = envKey;
+      }
+      return;
+    }
+    if (!this.clientOptions.env) {
+      this.clientOptions.env = { ...process.env };
+    }
+  }
   async ensureStarted() {
     if (this.client)
       return this.client;
     if (this.startPromise)
       return this.startPromise;
-    this.startPromise = AgentRelayClient.start(this.clientOptions).then((c) => {
+    this.startPromise = this.ensureRelaycastApiKey().then(() => AgentRelayClient.start(this.clientOptions)).then((c) => {
       this.client = c;
       this.startPromise = void 0;
+      if (c.workspaceKey) {
+        this.relayApiKey = c.workspaceKey;
+      }
       this.wireEvents(c);
       return c;
     }).catch((err) => {
@@ -45648,7 +45713,7 @@ var AgentRelay = class {
         const client = await relay.ensureStarted();
         await client.release(name, reason);
       },
-      async waitForReady(timeoutMs = 3e4) {
+      async waitForReady(timeoutMs = 6e4) {
         await relay.waitForAgentReady(name, timeoutMs);
       },
       waitForExit(timeoutMs) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "Real-time agent-to-agent communication system",
   "type": "module",
   "main": "dist/index.cjs",
@@ -103,6 +103,7 @@
     "postbuild": "chmod +x dist/src/cli/bootstrap.js dist/src/cli/index.js && npm run build:cjs",
     "prepack": "if [ -d node_modules ]; then npm run build; else echo '⚠ node_modules not found, skipping prepack build'; fi",
     "dev:watch": "tsc -w",
+    "docs": "cd ./docs && npx mintlify dev",
     "watch:start": "npm run build && concurrently -k \"npm run dev:watch\" \"node --watch dist/src/cli/bootstrap.js start dashboard.js claude\"",
     "watch:start:cli-tools": "npm run build && bash ./scripts/watch-cli-tools.sh",
     "watch:start:claude": "npm run watch:start:cli-tools -- --tool=claude",
@@ -173,13 +174,13 @@
   },
   "homepage": "https://github.com/AgentWorkforce/relay#readme",
   "dependencies": {
-    "@agent-relay/config": "3.0.1",
-    "@agent-relay/hooks": "3.0.1",
-    "@agent-relay/sdk": "3.0.1",
-    "@agent-relay/telemetry": "3.0.1",
-    "@agent-relay/trajectory": "3.0.1",
-    "@agent-relay/user-directory": "3.0.1",
-    "@agent-relay/utils": "3.0.1",
+    "@agent-relay/config": "3.0.2",
+    "@agent-relay/hooks": "3.0.2",
+    "@agent-relay/sdk": "3.0.2",
+    "@agent-relay/telemetry": "3.0.2",
+    "@agent-relay/trajectory": "3.0.2",
+    "@agent-relay/user-directory": "3.0.2",
+    "@agent-relay/utils": "3.0.2",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@relaycast/sdk": "^0.4.0",
     "chokidar": "^5.0.0",

package/packages/acp-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/acp-bridge",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "ACP (Agent Client Protocol) bridge for Agent Relay - expose relay agents to ACP-compatible editors like Zed",
   "type": "module",
   "main": "dist/index.js",
@@ -46,7 +46,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@agent-relay/sdk": "3.0.1",
+    "@agent-relay/sdk": "3.0.2",
     "@agentclientprotocol/sdk": "^0.12.0"
   },
   "devDependencies": {

package/packages/config/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/config",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "Shared configuration schemas and loaders for Agent Relay",
   "type": "module",
   "main": "dist/index.js",

package/packages/hooks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/hooks",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "Hook emitter, registry, and trajectory hooks for Agent Relay",
   "type": "module",
   "main": "dist/index.js",
@@ -37,9 +37,9 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/config": "3.0.1",
-    "@agent-relay/trajectory": "3.0.1",
-    "@agent-relay/sdk": "3.0.1"
+    "@agent-relay/config": "3.0.2",
+    "@agent-relay/trajectory": "3.0.2",
+    "@agent-relay/sdk": "3.0.2"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/memory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/memory",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "Semantic memory storage and retrieval system for agent-relay with multiple backend support",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/hooks": "3.0.1"
+    "@agent-relay/hooks": "3.0.2"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/policy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/policy",
-  "version": "3.0.1",
+  "version": "3.0.2",
   "description": "Agent policy management with multi-level fallback (repo, local PRPM, cloud workspace)",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/config": "3.0.1"
+    "@agent-relay/config": "3.0.2"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/sdk/dist/__tests__/facade.test.js

@@ -254,4 +254,52 @@ test("facade: listLoggedAgents returns array", async (t) => {
         await relay.shutdown();
     }
 });
+// ── workspaceKey / observerUrl from hello_ack ────────────────────────────────
+test("facade: workspaceKey is populated from broker hello_ack after startup", async (t) => {
+    const bin = requireBinary(t);
+    if (!bin)
+        return;
+    // Create relay WITHOUT passing RELAY_API_KEY in env — broker creates its own
+    // workspace and returns the key via hello_ack. This tests the fix for the
+    // "dual workspace" bug where SDK and broker used different workspace keys.
+    const envWithoutKey = { ...process.env };
+    delete envWithoutKey.RELAY_API_KEY;
+    const relay = new AgentRelay({
+        binaryPath: bin,
+        requestTimeoutMs: 15_000,
+        env: envWithoutKey,
+    });
+    try {
+        await relay.getStatus();
+        // After startup, workspaceKey MUST be set from the broker's hello_ack.
+        assert.ok(relay.workspaceKey, "workspaceKey must be set after broker startup (read from hello_ack workspace_key field)");
+        assert.match(relay.workspaceKey, /^rk_live_/, "workspaceKey must be a valid workspace key (rk_live_ prefix)");
+        // observerUrl must be correctly formatted.
+        assert.ok(relay.observerUrl, "observerUrl must be defined when workspaceKey is set");
+        assert.ok(relay.observerUrl.includes(relay.workspaceKey), "observerUrl must contain the workspace key");
+    }
+    finally {
+        await relay.shutdown();
+    }
+});
+test("facade: workspaceKey from env matches broker hello_ack when valid", async (t) => {
+    if (!requireRelaycast(t))
+        return;
+    const bin = requireBinary(t);
+    if (!bin)
+        return;
+    // When RELAY_API_KEY is valid, the broker uses it and returns the same key
+    // in hello_ack. SDK and broker must be on the same workspace.
+    const relay = makeRelay(bin);
+    try {
+        await relay.getStatus();
+        assert.ok(relay.workspaceKey, "workspaceKey must be set after startup");
+        // The workspace key returned by broker must match what we passed in.
+        assert.equal(relay.workspaceKey, process.env.RELAY_API_KEY, "broker hello_ack workspace_key must match the RELAY_API_KEY we passed — " +
+            "a mismatch means broker and SDK are on different workspaces, breaking MCP auth");
+    }
+    finally {
+        await relay.shutdown();
+    }
+});
 //# sourceMappingURL=facade.test.js.map