Merge branch 'main' into feature/local-cloud-workflow-files

Author: willwashburn

.github/workflows/publish.yml

@@ -964,6 +964,55 @@ jobs:
           fi
           npm publish --access public --provenance --tag ${{ github.event.inputs.tag }} --ignore-scripts
 
+  # Publish @agent-relay/harnesses after the publish-packages matrix, which is
+  # where its exact-version workspace deps (@agent-relay/sdk and
+  # @agent-relay/harness-driver) land on the registry. Publishing harnesses
+  # before those exist would leave a window where
+  # `npm install @agent-relay/harnesses@<v>` cannot resolve its dependencies —
+  # the same install race the broker/sdk ordering above is built to avoid.
+  publish-harnesses:
+    name: Publish @agent-relay/harnesses
+    needs: [build, publish-packages]
+    runs-on: ubuntu-latest
+    if: github.event.inputs.package == 'all'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22.14.0'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: build-output
+          path: .
+
+      - name: Update npm for OIDC support
+        run: npm install -g npm@latest
+
+      - name: Dry run check
+        if: github.event.inputs.dry_run == 'true'
+        working-directory: packages/harnesses
+        run: npm publish --dry-run --access public --tag ${{ github.event.inputs.tag }} --ignore-scripts
+
+      - name: Publish to NPM
+        if: github.event.inputs.dry_run != 'true'
+        working-directory: packages/harnesses
+        run: |
+          set -euo pipefail
+          PKG_NAME=$(node -p "require('./package.json').name")
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          if npm view "${PKG_NAME}@${PKG_VERSION}" version >/dev/null 2>&1; then
+            echo "${PKG_NAME}@${PKG_VERSION} already exists on npm; skipping publish"
+            exit 0
+          fi
+          npm publish --access public --provenance --tag ${{ github.event.inputs.tag }} --ignore-scripts
+
   # package=main publishes only the root `agent-relay` tarball, but that
   # tarball pins several @agent-relay/* runtime dependencies to the freshly
   # bumped version. Publish those direct deps first so a main-only release
@@ -1528,13 +1577,18 @@ jobs:
   # Create git tag and release
   create-release:
     name: Create Release
-    needs: [build, build-broker, build-standalone, verify-binaries, publish-main]
+    needs: [build, build-broker, build-standalone, verify-binaries, publish-main, publish-harnesses]
     runs-on: ubuntu-latest
+    # publish-harnesses only runs for package=all; for a package=main release it
+    # is skipped, which must not block the tag. Gate on "not failed" rather than
+    # "succeeded" so a real harness publish failure stops the release but a
+    # skipped one does not.
     if: |
       always() &&
       github.event.inputs.package != 'cli-prerelease' &&
       github.event.inputs.dry_run != 'true' &&
       needs.publish-main.result == 'success' &&
+      (needs.publish-harnesses.result == 'success' || needs.publish-harnesses.result == 'skipped') &&
       needs.publish-main.outputs.published == 'true'
 
     steps:
@@ -2011,6 +2065,7 @@ jobs:
         publish-sdk-internal-deps,
         publish-broker-packages,
         publish-packages,
+        publish-harnesses,
         publish-brand-only,
         publish-sdk-py,
         publish-main,
@@ -2053,6 +2108,7 @@ jobs:
           echo "| Publish SDK Internal Deps | ${{ needs.publish-sdk-internal-deps.result == 'success' && '✅' || (needs.publish-sdk-internal-deps.result == 'skipped' && '⏭️' || '❌') }} ${{ needs.publish-sdk-internal-deps.result }} |" >> $GITHUB_STEP_SUMMARY
           echo "| Publish Broker Packages | ${{ needs.publish-broker-packages.result == 'success' && '✅' || (needs.publish-broker-packages.result == 'skipped' && '⏭️' || '❌') }} ${{ needs.publish-broker-packages.result }} |" >> $GITHUB_STEP_SUMMARY
           echo "| Publish Packages | ${{ needs.publish-packages.result == 'success' && '✅' || (needs.publish-packages.result == 'skipped' && '⏭️' || '❌') }} ${{ needs.publish-packages.result }} |" >> $GITHUB_STEP_SUMMARY
+          echo "| Publish Harnesses | ${{ needs.publish-harnesses.result == 'success' && '✅' || (needs.publish-harnesses.result == 'skipped' && '⏭️' || '❌') }} ${{ needs.publish-harnesses.result }} |" >> $GITHUB_STEP_SUMMARY
           echo "| Publish Brand | ${{ needs.publish-brand-only.result == 'success' && '✅' || (needs.publish-brand-only.result == 'skipped' && '⏭️' || '❌') }} ${{ needs.publish-brand-only.result }} |" >> $GITHUB_STEP_SUMMARY
           echo "| Publish Python SDK | ${{ needs.publish-sdk-py.result == 'success' && '✅' || (needs.publish-sdk-py.result == 'skipped' && '⏭️' || '❌') }} ${{ needs.publish-sdk-py.result }} |" >> $GITHUB_STEP_SUMMARY
           echo "| Publish Main | ${{ needs.publish-main.result == 'success' && '✅' || (needs.publish-main.result == 'skipped' && '⏭️' || '❌') }} ${{ needs.publish-main.result }} |" >> $GITHUB_STEP_SUMMARY

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `@agent-relay/harnesses` adds a `grok` PTY harness for the Grok CLI, including Relaycast MCP support for spawned agents.
+- `@agent-relay/harnesses` is now published to npm, so SDK consumers can install the prebuilt PTY harnesses and harness-authoring helpers.
 - `agent-relay drive` and `agent-relay passthrough` add adaptive predictive echo so typing stays responsive when driving a high-latency or remote agent, and stays invisible on fast local links.
 - `@agent-relay/harness-driver` exports a reusable `PredictiveEchoEngine` so other attach UIs (CLI, Electron, browser) can share one predictive-echo implementation.
 - `@agent-relay/sdk` `relay.addListener(...)` on a workspace client now receives all workspace-visible events: `events.connect()` opens the relaycast 2.5 workspace stream when no agent client is present, so the documented `relay.addListener('message.created', ...)` quickstart path streams without registering an agent.
@@ -135,6 +137,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `agent-relay-sdk` refreshes `packages/sdk-py/uv.lock` to clear 20 transitive CVEs across `urllib3` (2.6.3→2.7.0), `gitpython` (3.1.46→3.1.50), `pillow` (12.1.1→12.2.0), `python-multipart` (0.0.22→0.0.29), `cryptography` (46.0.6→48.0.0), `authlib` (1.6.9→1.7.2), `idna` (3.11→3.16), `python-dotenv` (1.1.1→1.2.2), `pytest` (9.0.2→9.0.3), and `uv` (0.9.30→0.11.16). Only `starlette` PYSEC-2026-161 remains pending an upstream `google-adk` upper-bound bump.
 - `gemini-relay-extension` refreshes its `package-lock.json` to clear `fast-uri` (GHSA path-traversal via percent-encoded dots) and `path-to-regexp` (GHSA sequential-optional-groups DoS), plus moderate alerts on `hono`, `qs`, `ip-address`, `express-rate-limit`, and `@hono/node-server`.
 
+## [8.2.0] - 2026-06-04
+
+### Added
+
+- Add lifecycle-aware SpawnedAgentHandle
+
+### Changed
+
+- Publish @agent-relay/harnesses on release
+
+## [8.1.2] - 2026-06-04
+
+### Fixed
+
+- Export ./predictive-echo subpath
+
+## [8.1.1] - 2026-06-04
+
+### Changed
+
+- Predictive echo for remote attach + interactive latency fixes
+
 ## [8.1.0] - 2026-06-03
 
 ### Changed

crates/broker/src/snippets.rs

@@ -687,7 +687,7 @@ pub fn ensure_cursor_mcp_config(
     Ok(changed)
 }
 
-/// - `cli`: CLI tool name (e.g. "claude", "codex", "gemini", "droid", "opencode", "cursor")
+/// - `cli`: CLI tool name (e.g. "claude", "codex", "gemini", "droid", "grok", "opencode", "cursor")
 /// - `agent_name`: the name of the agent being spawned
 /// - `api_key`: optional relay API key (empty or `None` means omit)
 /// - `base_url`: optional relay base URL (empty or `None` means omit)
@@ -765,6 +765,7 @@ pub async fn configure_agent_relay_mcp_with_result(
     let is_gemini = cli_lower == "gemini";
     let is_droid = cli_lower == "droid";
     let is_opencode = cli_lower == "opencode";
+    let is_grok = cli_lower == "grok";
     let is_cursor = cli_lower == "cursor" || cli_lower == "cursor-agent" || cli_lower == "agent"; // "agent" is cursor-agent's binary name
 
     let api_key = api_key.map(str::trim).filter(|s| !s.is_empty());
@@ -920,6 +921,17 @@ pub async fn configure_agent_relay_mcp_with_result(
             None,
         )
         .await?;
+    } else if is_grok {
+        configure_grok_mcp(
+            cli,
+            api_key,
+            base_url,
+            Some(agent_name),
+            agent_token,
+            workspaces_json,
+            default_workspace,
+        )
+        .await?;
     } else if is_opencode && !existing_args.iter().any(|a| a == "--agent") {
         ensure_opencode_config_with_result(
             cwd,
@@ -1110,6 +1122,150 @@ fn gemini_droid_mcp_add_args_with_result(
     args
 }
 
+fn grok_mcp_add_args(
+    api_key: Option<&str>,
+    base_url: Option<&str>,
+    agent_name: Option<&str>,
+    agent_token: Option<&str>,
+    workspaces_json: Option<&str>,
+    default_workspace: Option<&str>,
+) -> Vec<String> {
+    let mut args = vec!["mcp".to_string(), "add".to_string()];
+    if let Some(key) = api_key {
+        args.push("--env".to_string());
+        args.push(format!("RELAY_API_KEY={key}"));
+    }
+    if let Some(url) = base_url {
+        args.push("--env".to_string());
+        args.push(format!("RELAY_BASE_URL={url}"));
+    }
+    if let Some(name) = agent_name.map(str::trim).filter(|s| !s.is_empty()) {
+        args.push("--env".to_string());
+        args.push(format!("RELAY_AGENT_NAME={name}"));
+        args.push("--env".to_string());
+        args.push("RELAY_AGENT_TYPE=agent".to_string());
+        args.push("--env".to_string());
+        args.push("RELAY_STRICT_AGENT_NAME=1".to_string());
+    }
+    if let Some(token) = agent_token.map(str::trim).filter(|s| !s.is_empty()) {
+        args.push("--env".to_string());
+        args.push(format!("RELAY_AGENT_TOKEN={token}"));
+        args.push("--env".to_string());
+        args.push("RELAY_SKIP_BOOTSTRAP=1".to_string());
+    }
+    if let Some(wj) = workspaces_json.map(str::trim).filter(|s| !s.is_empty()) {
+        args.push("--env".to_string());
+        args.push(format!("RELAY_WORKSPACES_JSON={wj}"));
+    }
+    if let Some(dw) = default_workspace.map(str::trim).filter(|s| !s.is_empty()) {
+        args.push("--env".to_string());
+        args.push(format!("RELAY_DEFAULT_WORKSPACE={dw}"));
+    }
+    args.push(AGENT_RELAY_MCP_SERVER.to_string());
+    let mcp_command = agent_relay_mcp_command();
+    args.push("--command".to_string());
+    args.push(mcp_command.command);
+    for arg in mcp_command.args {
+        args.push("--args".to_string());
+        args.push(arg);
+    }
+    args
+}
+
+fn grok_manual_mcp_add_cmd(cli: &str) -> String {
+    let mcp_command = agent_relay_mcp_command();
+    let rendered_args = mcp_command
+        .args
+        .iter()
+        .map(|arg| format!("--args {arg}"))
+        .collect::<Vec<_>>()
+        .join(" ");
+    format!(
+        "{cli} mcp add --env RELAY_API_KEY=<key> --env RELAY_BASE_URL=<url> {AGENT_RELAY_MCP_SERVER} --command {} {rendered_args}",
+        mcp_command.command
+    )
+}
+
+async fn remove_grok_mcp_servers(exe: &str) {
+    for server_name in [AGENT_RELAY_MCP_SERVER, LEGACY_RELAYCAST_SERVER] {
+        let mut cmd = Command::new(exe);
+        cmd.args(["mcp", "remove", server_name])
+            .stdin(Stdio::null())
+            .stdout(Stdio::null())
+            .stderr(Stdio::null());
+        if let Ok(mut child) = cmd.spawn() {
+            let _ = tokio::time::timeout(Duration::from_secs(5), child.wait()).await;
+        }
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+async fn configure_grok_mcp(
+    cli: &str,
+    api_key: Option<&str>,
+    base_url: Option<&str>,
+    agent_name: Option<&str>,
+    agent_token: Option<&str>,
+    workspaces_json: Option<&str>,
+    default_workspace: Option<&str>,
+) -> Result<()> {
+    let exe = shlex::split(cli)
+        .and_then(|parts| parts.first().cloned())
+        .unwrap_or_else(|| cli.trim().to_string());
+    let manual_cmd = grok_manual_mcp_add_cmd(&exe);
+
+    remove_grok_mcp_servers(&exe).await;
+
+    let mut mcp_cmd = Command::new(&exe);
+    mcp_cmd.args(grok_mcp_add_args(
+        api_key,
+        base_url,
+        agent_name,
+        agent_token,
+        workspaces_json,
+        default_workspace,
+    ));
+    mcp_cmd
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(Stdio::null());
+
+    match mcp_cmd.spawn() {
+        Ok(mut child) => match tokio::time::timeout(Duration::from_secs(15), child.wait()).await {
+            Ok(Ok(status)) if !status.success() => {
+                anyhow::bail!(
+                    "failed to configure Agent Relay MCP for {cli}: `{cli} mcp add` exited with code {:?}. \
+                     Please configure the Agent Relay MCP server manually:\n  {manual_cmd}",
+                    status.code()
+                );
+            }
+            Ok(Err(error)) => {
+                anyhow::bail!(
+                    "failed to configure Agent Relay MCP for {cli}: {error}. \
+                     Please configure the Agent Relay MCP server manually:\n  {manual_cmd}"
+                );
+            }
+            Err(_) => {
+                let _ = child.kill().await;
+                let _ = child.wait().await;
+                anyhow::bail!(
+                    "failed to configure Agent Relay MCP for {cli}: `{cli} mcp add` timed out after 15s. \
+                     Please configure the Agent Relay MCP server manually:\n  {manual_cmd}"
+                );
+            }
+            _ => {}
+        },
+        Err(error) => {
+            anyhow::bail!(
+                "failed to configure Agent Relay MCP for {cli}: {error}. \
+                 Please configure the Agent Relay MCP server manually:\n  {manual_cmd}"
+            );
+        }
+    }
+
+    Ok(())
+}
+
 #[allow(clippy::too_many_arguments)]
 async fn configure_gemini_droid_mcp(
     cli: &str,
@@ -1584,6 +1740,36 @@ mod tests {
         assert_eq!(args[0], "--mcp-config");
     }
 
+    #[test]
+    fn grok_mcp_add_args_use_command_and_args_flags() {
+        let args = super::grok_mcp_add_args(
+            Some("rk_live_xyz"),
+            Some("https://api.relaycast.dev"),
+            Some("GrokWorker"),
+            Some("tok_grok_123"),
+            None,
+            None,
+        );
+
+        assert!(args.starts_with(&["mcp".to_string(), "add".to_string()]));
+        assert!(args.contains(&"--env".to_string()));
+        assert!(args.contains(&"RELAY_API_KEY=rk_live_xyz".to_string()));
+        assert!(args.contains(&"RELAY_AGENT_NAME=GrokWorker".to_string()));
+        assert!(args.contains(&"RELAY_AGENT_TOKEN=tok_grok_123".to_string()));
+        let server_idx = args
+            .iter()
+            .position(|arg| arg == "agent-relay")
+            .expect("agent-relay arg");
+        assert_eq!(args[server_idx + 1], "--command");
+        assert_eq!(args[server_idx + 2], "npx");
+        assert_eq!(args[server_idx + 3], "--args");
+        assert_eq!(args[server_idx + 4], "-y");
+        assert_eq!(args[server_idx + 5], "--args");
+        assert_eq!(args[server_idx + 6], "agent-relay");
+        assert_eq!(args[server_idx + 7], "--args");
+        assert_eq!(args[server_idx + 8], "mcp");
+    }
+
     #[test]
     fn droid_mcp_add_args_include_option_separator() {
         let args = super::gemini_droid_mcp_add_args(

crates/broker/src/worker.rs

@@ -280,6 +280,7 @@ impl WorkerRegistry {
                 let is_claude = cli_lower == "claude" || cli_lower.starts_with("claude:");
                 let is_codex = cli_lower == "codex";
                 let is_gemini = cli_lower == "gemini";
+                let is_grok = cli_lower == "grok";
                 if let Some(model) = apply_codex_model_arg_fallback(
                     &resolved_cli,
                     &cli_lower,
@@ -356,6 +357,8 @@ impl WorkerRegistry {
                     Some("--dangerously-bypass-approvals-and-sandbox")
                 } else if is_gemini && !effective_args.iter().any(|a| a == "--yolo" || a == "-y") {
                     Some("--yolo")
+                } else if is_grok && !effective_args.iter().any(|a| a == "--always-approve") {
+                    Some("--always-approve")
                 } else {
                     None
                 };
@@ -481,6 +484,7 @@ impl WorkerRegistry {
                     let is_claude = cli_lower == "claude" || cli_lower.starts_with("claude:");
                     let is_codex = cli_lower == "codex";
                     let is_gemini = cli_lower == "gemini";
+                    let is_grok = cli_lower == "grok";
                     if let Some(model) = apply_codex_model_arg_fallback(
                         &resolved_cli,
                         &cli_lower,
@@ -559,6 +563,8 @@ impl WorkerRegistry {
                         && !effective_args.iter().any(|a| a == "--yolo" || a == "-y")
                     {
                         Some("--yolo")
+                    } else if is_grok && !effective_args.iter().any(|a| a == "--always-approve") {
+                        Some("--always-approve")
                     } else {
                         None
                     };

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/monorepo",
-  "version": "8.1.0",
+  "version": "8.2.0",
   "private": true,
   "description": "Agent Relay monorepo",
   "type": "module",