fix(sdk-swift): align broker client with v7, rename RelayCast → AgentRelayClient

.github/workflows/e2e-tests.yml

@@ -5,6 +5,7 @@ on:
     branches: [main]
     paths:
       - 'packages/**'
+      - '!packages/sdk-swift/**'
       - 'scripts/e2e-test.sh'
       - 'scripts/e2e-sdk-lifecycle.mjs'
       - 'package.json'
@@ -13,6 +14,7 @@ on:
     branches: [main]
     paths:
       - 'packages/**'
+      - '!packages/sdk-swift/**'
       - 'scripts/e2e-test.sh'
       - 'scripts/e2e-sdk-lifecycle.mjs'
       - 'package.json'

.github/workflows/node-compat.yml

@@ -12,10 +12,11 @@ concurrency:
 
 jobs:
   changes:
-    name: Detect web-only change set
+    name: Detect change scope
     runs-on: ubuntu-latest
     outputs:
       web_only: ${{ steps.scope.outputs.web_only }}
+      sdk_swift_only: ${{ steps.scope.outputs.sdk_swift_only }}
     steps:
       - id: scope
         uses: actions/github-script@v7
@@ -42,13 +43,15 @@ jobs:
             }
 
             const webOnly = files.length > 0 && files.every((file) => file.startsWith('web/'));
+            const sdkSwiftOnly = files.length > 0 && files.every((file) => file.startsWith('packages/sdk-swift/'));
             core.info(`Changed files (${files.length}): ${files.join(', ')}`);
             core.setOutput('web_only', webOnly ? 'true' : 'false');
+            core.setOutput('sdk_swift_only', sdkSwiftOnly ? 'true' : 'false');
 
   install-test:
     name: Install Test (Node ${{ matrix.node-version }})
     needs: changes
-    if: needs.changes.outputs.web_only != 'true'
+    if: needs.changes.outputs.web_only != 'true' && needs.changes.outputs.sdk_swift_only != 'true'
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -104,7 +107,7 @@ jobs:
   fresh-install:
     name: Fresh Install (Node ${{ matrix.node-version }})
     needs: changes
-    if: needs.changes.outputs.web_only != 'true'
+    if: needs.changes.outputs.web_only != 'true' && needs.changes.outputs.sdk_swift_only != 'true'
     runs-on: ubuntu-latest
     strategy:
       matrix:

.github/workflows/package-validation.yml

@@ -15,10 +15,11 @@ env:
 
 jobs:
   changes:
-    name: Detect web-only change set
+    name: Detect change scope
     runs-on: ubuntu-latest
     outputs:
       web_only: ${{ steps.scope.outputs.web_only }}
+      sdk_swift_only: ${{ steps.scope.outputs.sdk_swift_only }}
     steps:
       - id: scope
         uses: actions/github-script@v7
@@ -45,13 +46,15 @@ jobs:
             }
 
             const webOnly = files.length > 0 && files.every((file) => file.startsWith('web/'));
+            const sdkSwiftOnly = files.length > 0 && files.every((file) => file.startsWith('packages/sdk-swift/'));
             core.info(`Changed files (${files.length}): ${files.join(', ')}`);
             core.setOutput('web_only', webOnly ? 'true' : 'false');
+            core.setOutput('sdk_swift_only', sdkSwiftOnly ? 'true' : 'false');
 
   validate:
     name: Build & Validate
     needs: changes
-    if: needs.changes.outputs.web_only != 'true'
+    if: needs.changes.outputs.web_only != 'true' && needs.changes.outputs.sdk_swift_only != 'true'
     runs-on: ubuntu-latest
     env:
       NPM_CONFIG_FUND: false
@@ -228,7 +231,7 @@ jobs:
   publish-fresh-install-build:
     name: Publish Fresh Install Build
     needs: changes
-    if: needs.changes.outputs.web_only != 'true'
+    if: needs.changes.outputs.web_only != 'true' && needs.changes.outputs.sdk_swift_only != 'true'
     runs-on: ubuntu-latest
     env:
       NPM_CONFIG_FUND: false
@@ -262,7 +265,7 @@ jobs:
   standalone-macos-smoke:
     name: Standalone macOS Smoke
     needs: changes
-    if: needs.changes.outputs.web_only != 'true'
+    if: needs.changes.outputs.web_only != 'true' && needs.changes.outputs.sdk_swift_only != 'true'
     runs-on: macos-latest
     env:
       NPM_CONFIG_FUND: false

.github/workflows/relay-cleanroom-hardening.yml

@@ -6,6 +6,7 @@ on:
     paths:
       - 'install.sh'
       - 'packages/**'
+      - '!packages/sdk-swift/**'
       - 'workflows/relay-e2e-meta-workflow.ts'
       - 'workflows/relay-clean-room-e2e-validation.ts'
       - 'scripts/run-relay-cleanroom-ci.sh'

.github/workflows/rust-ci.yml

@@ -11,10 +11,11 @@ env:
 
 jobs:
   changes:
-    name: Detect web-only change set
+    name: Detect change scope
     runs-on: ubuntu-latest
     outputs:
       web_only: ${{ steps.scope.outputs.web_only }}
+      sdk_swift_only: ${{ steps.scope.outputs.sdk_swift_only }}
     steps:
       - id: scope
         uses: actions/github-script@v7
@@ -41,13 +42,15 @@ jobs:
             }
 
             const webOnly = files.length > 0 && files.every((file) => file.startsWith('web/'));
+            const sdkSwiftOnly = files.length > 0 && files.every((file) => file.startsWith('packages/sdk-swift/'));
             core.info(`Changed files (${files.length}): ${files.join(', ')}`);
             core.setOutput('web_only', webOnly ? 'true' : 'false');
+            core.setOutput('sdk_swift_only', sdkSwiftOnly ? 'true' : 'false');
 
   rust-test:
     name: Rust Tests (${{ matrix.os }})
     needs: changes
-    if: needs.changes.outputs.web_only != 'true'
+    if: needs.changes.outputs.web_only != 'true' && needs.changes.outputs.sdk_swift_only != 'true'
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -64,7 +67,7 @@ jobs:
   rust-cross-compile:
     name: Cross-compile check (${{ matrix.target }})
     needs: changes
-    if: needs.changes.outputs.web_only != 'true'
+    if: needs.changes.outputs.web_only != 'true' && needs.changes.outputs.sdk_swift_only != 'true'
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -98,7 +101,7 @@ jobs:
   rust-clippy:
     name: Clippy
     needs: changes
-    if: needs.changes.outputs.web_only != 'true'
+    if: needs.changes.outputs.web_only != 'true' && needs.changes.outputs.sdk_swift_only != 'true'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -113,7 +116,7 @@ jobs:
   rust-fmt:
     name: Format
     needs: changes
-    if: needs.changes.outputs.web_only != 'true'
+    if: needs.changes.outputs.web_only != 'true' && needs.changes.outputs.sdk_swift_only != 'true'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -125,7 +128,7 @@ jobs:
   sdk-check:
     name: SDK TypeScript Check
     needs: changes
-    if: needs.changes.outputs.web_only != 'true'
+    if: needs.changes.outputs.web_only != 'true' && needs.changes.outputs.sdk_swift_only != 'true'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4

.github/workflows/test.yml

@@ -15,10 +15,12 @@ env:
 
 jobs:
   changes:
-    name: Detect web-only change set
+    name: Detect change scope
     runs-on: ubuntu-latest
     outputs:
       web_only: ${{ steps.scope.outputs.web_only }}
+      sdk_swift_only: ${{ steps.scope.outputs.sdk_swift_only }}
+      sdk_swift_changed: ${{ steps.scope.outputs.sdk_swift_changed }}
     steps:
       - id: scope
         uses: actions/github-script@v7
@@ -45,12 +47,16 @@ jobs:
             }
 
             const webOnly = files.length > 0 && files.every((file) => file.startsWith('web/'));
+            const sdkSwiftOnly = files.length > 0 && files.every((file) => file.startsWith('packages/sdk-swift/'));
+            const sdkSwiftChanged = files.some((file) => file.startsWith('packages/sdk-swift/'));
             core.info(`Changed files (${files.length}): ${files.join(', ')}`);
             core.setOutput('web_only', webOnly ? 'true' : 'false');
+            core.setOutput('sdk_swift_only', sdkSwiftOnly ? 'true' : 'false');
+            core.setOutput('sdk_swift_changed', sdkSwiftChanged ? 'true' : 'false');
 
   test:
     needs: changes
-    if: needs.changes.outputs.web_only != 'true'
+    if: needs.changes.outputs.web_only != 'true' && needs.changes.outputs.sdk_swift_only != 'true'
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
@@ -80,7 +86,7 @@ jobs:
   coverage:
     name: Coverage (upload)
     needs: changes
-    if: needs.changes.outputs.web_only != 'true'
+    if: needs.changes.outputs.web_only != 'true' && needs.changes.outputs.sdk_swift_only != 'true'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -108,7 +114,7 @@ jobs:
 
   lint:
     needs: changes
-    if: needs.changes.outputs.web_only != 'true'
+    if: needs.changes.outputs.web_only != 'true' && needs.changes.outputs.sdk_swift_only != 'true'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
@@ -135,7 +141,7 @@ jobs:
   rust-test:
     name: Rust Tests (agent-relay-broker)
     needs: changes
-    if: needs.changes.outputs.web_only != 'true'
+    if: needs.changes.outputs.web_only != 'true' && needs.changes.outputs.sdk_swift_only != 'true'
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
@@ -162,3 +168,24 @@ jobs:
 
       - name: Run Clippy lints
         run: cargo clippy -- -D warnings
+
+  swift-test:
+    name: Swift SDK Tests
+    needs: changes
+    if: needs.changes.outputs.sdk_swift_changed == 'true'
+    runs-on: macos-latest
+    defaults:
+      run:
+        working-directory: packages/sdk-swift
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Show Swift version
+        run: swift --version
+
+      - name: Build
+        run: swift build
+
+      - name: Test
+        run: swift test

CHANGELOG.md

@@ -22,17 +22,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `@agent-relay/sdk` swaps `@agentworkforce/harness-kit` + `@agentworkforce/workload-router` for `@agentworkforce/persona-kit@^3`. The persona tier system, the `tier` option on `spawnPersona`, the legacy relay-side `PersonaFile` / `PersonaTier` / `PersonaTierSpec` / `ResolvedPersona` / `PersonaSpawnSpec` / `MaterializedConfigFile` types, and the `buildPersonaSpawnSpec` / `materializePersonaConfigFiles` / `restorePersonaConfigFiles` helpers are removed. `loadPersona` now returns the canonical `PersonaSpec`, and `spawnPersona({ persona })` takes a `PersonaSpec` instead of a resolved persona.
 - `agent-relay-broker`'s public Rust protocol types now require typed ID newtypes (`WorkerName`, `DeliveryId`, `EventId`, `WorkspaceId`, `WorkspaceAlias`, `ThreadId`, `AgentId`, `RequestId`, `ChannelName`, `MessageTarget`) on every protocol struct and enum variant in `protocol.rs`, `types.rs`, and `listen_api.rs::ListenApiRequest`. The new wrappers live in `crates/broker/src/lib.rs` under `pub mod ids`. JSON wire format is unchanged because every wrapper is `#[serde(transparent)]`, so the broker ↔ SDK channel and on-disk persisted state remain byte-compatible.
 - `agent-relay spawn` and SDK spawn calls now return harness `sessionId` metadata for resumable Claude and Codex PTY sessions.
+- `sdk-swift`: renamed the broker client class `RelayCast` → `AgentRelayClient`.
 
 ### Migration Guidance
 
 - Personas relying on `tiers.*` need to be flattened to a single top-level `harness` / `model` / `systemPrompt`. The shape that persona-kit (and the `agentworkforce` CLI) consumes is now the only supported shape.
 - Callers that previously used `spawnPersona` to "just launch the harness" — without persona-kit's skill / mount / sidecar side effects — should use `AgentRelay.getPersonaSpawnPlan(id)` to inspect the plan and call `spawnPty` with the plan's `cli` + `args` themselves.
 - Downstream Rust callers must construct identifiers via `relay_broker::ids::{WorkerName, DeliveryId, EventId, MessageTarget, …}` instead of `String`. Each newtype impls `From<String>` / `From<&str>` and `Deref<Target = str>`, so most string-handling code keeps compiling; only construction sites (`HashMap` keys, struct literals, channel sends) need updates.
 - Replace ad-hoc target discrimination (`target.starts_with('#')`, `target == "thread"`) with `MessageTarget::kind()` and match on `MessageTargetKind::{Channel, Thread, DirectMessage, Conversation, Worker}`.
+- `sdk-swift`: replace `RelayCast(apiKey:baseURL:)` with `AgentRelayClient(apiKey:baseURL:)`. The public API surface is otherwise unchanged.
 
 ### Fixed
 
 - `web`: PR preview SST deploys use and comment the generated CloudFront URL and AWS's managed disabled cache policy instead of creating per-preview Cloudflare DNS records, ACM certificates, and custom CloudFront cache policies.
+- `sdk-swift`: broker client now connects to the v7 broker's `/ws` event stream without a legacy `hello`/`hello_ack` handshake and routes `spawnAgent`, `releaseAgent`, channel `post`, and agent `dm` through the broker's HTTP API (`/api/spawn`, `/api/spawned/{name}`, `/api/send`).
 
 ### Security
 

packages/sdk-swift/README.md

@@ -1,6 +1,7 @@
 # AgentRelaySDK
 
-Native Swift SDK for the Agent Relay broker.
+Native Swift SDK for `agent-relay-broker`. Talks to the broker over its `/ws`
+event stream and `/api/*` HTTP endpoints.
 
 ## Installation
 
@@ -19,8 +20,10 @@ Then depend on `AgentRelaySDK`.
 ```swift
 import AgentRelaySDK
 
-let relay = RelayCast(apiKey: "rk_live_...")
-let channel = relay.channel("wf-my-workflow")
+// Point at a local broker started with `agent-relay up` (defaults to
+// http://localhost:3889) or pass `baseURL:` for a remote broker.
+let client = AgentRelayClient(apiKey: "rk_live_...")
+let channel = client.channel("wf-my-workflow")
 try await channel.subscribe()
 try await channel.post("Hello from Swift")
 
@@ -31,8 +34,10 @@ for await event in channel.events {
 
 ## API
 
-- `RelayCast(apiKey:baseURL:)`
+- `AgentRelayClient(apiKey:baseURL:)` — broker client
 - `channel(_:) -> Channel`
+- `spawnAgent(_:initialTask:skipRelayPrompt:)`
+- `releaseAgent(name:reason:)`
 - `registerOrRotate(name:)`
 - `AgentRegistration.asClient()`
 - `AgentClient.post(to:message:)`