feat(cloud): Add managed relay tunnels and APN service

[juliusmarminge]

Stack

• Extract collection performance refactors from mobile stack #2854 codex/collection-performance-refactors -> main (merged)
• T3 Code Mobile [WIP] #2013 t3code/mobile-remote-connect -> main
• This PR codex/relay-managed-tunnels-auth-infra -> t3code/mobile-remote-connect

Summary

This stacked draft PR adds the relay-managed tunnel and cloud authentication work on top of the mobile remote-runtime PR. General collection/performance rewrites from #2854 and the TypeScript/Effect tooling base are now on main.

• add the relay worker/infrastructure package, persistence, APNs delivery, managed endpoint provisioning, observability, migrations, and tests
• add standards-oriented relay authentication: DPoP proof handling, JWT/JWS signing and verification, OAuth-style token exchange/scopes, replay protections, and environment proof flows
• add shared client-runtime/contracts/shared modules for managed relay operation across web and Expo mobile clients
• add web, desktop, and mobile cloud linking and managed-environment flows, including mobile agent-awareness/live-activity registration
• route relay-specific hashing and randomness through effect/Crypto while retaining Expo-compatible implementations

Validation

• bun fmt
• bun lint (passes with 8 existing web warnings)
• bun lint:mobile
• bun typecheck
• cd infra/relay && bun run test (103 passed, 5 skipped)
• cd apps/mobile && bun run test (135 passed)
• cd apps/web && bun run test (1005 passed)
• cd apps/server && bun run test (1075 passed, 4 skipped)

Rebase Note

General collection/performance rewrites from #2854 are now merged into main; mobile command metadata, pairing-URL redaction, and shared-runtime Crypto cleanup remain in #2013. This PR retains the managed-relay changes to the mobile connection contract and runtime above those inherited lower-layer changes.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 4824cb38-dedf-4cb1-8088-cb33b59dad31

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/relay-managed-tunnels-auth-infra

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

🟡 Medium

t3code/apps/desktop/scripts/electron-launcher.mjs

Line 277 in d52d11e

const expectedMetadata = {

The cache invalidation logic at line 290 only checks expectedMetadata, which omits the environment variables embedded by writeDevelopmentLauncherScript. When the metadata matches, the function returns early at line 293 without regenerating the launcher script, even if VITE_DEV_SERVER_URL or T3CODE_PORT has changed. This causes the app to use stale environment variables from a previous run — for example, attempting to connect to a Vite dev server port that is no longer running.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file apps/desktop/scripts/electron-launcher.mjs around line 277:

The cache invalidation logic at line 290 only checks `expectedMetadata`, which omits the environment variables embedded by `writeDevelopmentLauncherScript`. When the metadata matches, the function returns early at line 293 without regenerating the launcher script, even if `VITE_DEV_SERVER_URL` or `T3CODE_PORT` has changed. This causes the app to use stale environment variables from a previous run — for example, attempting to connect to a Vite dev server port that is no longer running.

Evidence trail:
apps/desktop/scripts/electron-launcher.mjs lines 277-294 (expectedMetadata definition and early return), lines 97-130 (writeDevelopmentLauncherScript embedding env vars into the launcher script), lines 300-302 (writeDevelopmentLauncherScript only called when cache is invalidated)

[macroscopeapp]

🟡 Medium src/worker.ts:249

The queue message handler and cron handler create spans using Stream.withSpan and Effect.withSpan, but they only provide runtimeLayer which does not include the tracer. This means spans from background jobs are silently dropped instead of being exported to Axiom, despite the explicit instrumentation. Consider providing relayTraceLayer to these handlers, similar to the HTTP fetch handler at line 270.

        Effect.provide(runtimeLayer),
+        Effect.provide(relayTraceLayer),

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file infra/relay/src/worker.ts around lines 249-250:

The queue message handler and cron handler create spans using `Stream.withSpan` and `Effect.withSpan`, but they only provide `runtimeLayer` which does not include the tracer. This means spans from background jobs are silently dropped instead of being exported to Axiom, despite the explicit instrumentation. Consider providing `relayTraceLayer` to these handlers, similar to the HTTP fetch handler at line 270.

Evidence trail:
infra/relay/src/worker.ts lines 170-176 (relayTraceLayer definition with OtlpTracer), lines 178-213 (runtimeLayer definition without tracer), line 242 (Stream.withSpan in queue handler), line 246 (Effect.withSpan in queue handler), line 249 (Effect.provide(runtimeLayer) - no tracer), line 256 (Effect.withSpan in cron handler), line 257 (Effect.provide(runtimeLayer) - no tracer), line 270 (HTTP handler uses relayTraceLayer). infra/relay/src/observability.ts lines 53-72 (makeRelayTraceLayer creates OtlpTracer.layer for Axiom export).

[macroscopeapp]

🟢 Low environments/ManagedEndpointProvider.ts:232

The Effect.filterMapOrFail at line 232 uses the single-argument form, so when Result.fail(new ManagedEndpointProvisioningFailed({ cause: tunnel })) is returned, the error inside is discarded and the effect fails with Cause.NoSuchElementError instead. The subsequent mapError at line 237 then wraps that NoSuchElementError into ManagedEndpointProvisioningFailed, losing the original tunnel object that was intended for debugging. Use the two-argument overload of filterMapOrFail to preserve the tunnel as the error cause.

-      Effect.filterMapOrFail((tunnel) =>
-        tunnel.id && tunnel.name
-          ? Result.succeed({ id: tunnel.id, name: tunnel.name })
-          : Result.fail(new ManagedEndpointProvisioningFailed({ cause: tunnel })),
-      ),
-      Effect.mapError((cause) => new ManagedEndpointProvisioningFailed({ cause })),
+      Effect.filterMapOrFail(
+        (tunnel) =>
+          tunnel.id && tunnel.name
+            ? Result.succeed({ id: tunnel.id, name: tunnel.name })
+            : Result.fail(tunnel),
+        (failedTunnel) => new ManagedEndpointProvisioningFailed({ cause: failedTunnel }),
+      ),

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file infra/relay/src/environments/ManagedEndpointProvider.ts around lines 232-237:

The `Effect.filterMapOrFail` at line 232 uses the single-argument form, so when `Result.fail(new ManagedEndpointProvisioningFailed({ cause: tunnel }))` is returned, the error inside is discarded and the effect fails with `Cause.NoSuchElementError` instead. The subsequent `mapError` at line 237 then wraps that `NoSuchElementError` into `ManagedEndpointProvisioningFailed`, losing the original `tunnel` object that was intended for debugging. Use the two-argument overload of `filterMapOrFail` to preserve the `tunnel` as the error cause.

Evidence trail:
1. Effect.filterMapOrFail type signature and implementation: packages/effect/src/Effect.ts lines 5210-5227 and packages/effect/src/internal/effect.ts lines 4789-4810 in https://github.com/Effect-TS/effect-smol (the source for effect@4.0.0-beta.73)
2. Single-argument overload fails with NoSuchElementError: `() => fail(new NoSuchElementError() as E2)` at packages/effect/src/internal/effect.ts ~line 4810
3. Code under review: infra/relay/src/environments/ManagedEndpointProvider.ts lines 232-237 in https://github.com/pingdotgg/t3code at REVIEWED_COMMIT
4. Correct two-argument usage in same codebase: apps/server/src/provider/opencodeRuntime.ts lines 513-524 in https://github.com/pingdotgg/t3code at REVIEWED_COMMIT
5. effect version: package.json line 80 shows effect@4.0.0-beta.73

[macroscopeapp]

🟡 Medium cloud/linkEnvironment.ts:408

updatePrimaryCloudPreferences calls resolvePrimaryEnvironmentHttpUrl without checking if a primary environment exists. When none is configured, resolvePrimaryEnvironmentHttpUrl throws a raw Error("Unable to resolve the primary environment HTTP base URL.") instead of the declared CloudEnvironmentLinkError. Callers in CloudSettings.tsx catch and handle CloudEnvironmentLinkError, so raw Error throws produce unhandled exception messages instead of proper user-facing errors.

-  return Effect.gen(function* () {
-    const client = yield* makeEnvironmentHttpApiClient(resolvePrimaryEnvironmentHttpUrl("/"));
+  return Effect.gen(function* () {
+    if (!readPrimaryCloudLinkTarget()) {
+      return yield* new CloudEnvironmentLinkError({
+        message: "Local environment is not ready yet.",
+      });
+    }
+    const client = yield* makeEnvironmentHttpApiClient(resolvePrimaryEnvironmentHttpUrl("/"));

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file apps/web/src/cloud/linkEnvironment.ts around lines 408-412:

`updatePrimaryCloudPreferences` calls `resolvePrimaryEnvironmentHttpUrl` without checking if a primary environment exists. When none is configured, `resolvePrimaryEnvironmentHttpUrl` throws a raw `Error("Unable to resolve the primary environment HTTP base URL.")` instead of the declared `CloudEnvironmentLinkError`. Callers in `CloudSettings.tsx` catch and handle `CloudEnvironmentLinkError`, so raw `Error` throws produce unhandled exception messages instead of proper user-facing errors.

Evidence trail:
apps/web/src/cloud/linkEnvironment.ts lines 408-423 (updatePrimaryCloudPreferences — no guard before calling resolvePrimaryEnvironmentHttpUrl); apps/web/src/cloud/linkEnvironment.ts lines 394-397 (readPrimaryCloudLinkState — has the guard); apps/web/src/cloud/linkEnvironment.ts lines 429-433 (unlinkPrimaryEnvironmentFromCloud — has the guard yielding CloudEnvironmentLinkError); apps/web/src/environments/primary/target.ts lines 135-150 (resolvePrimaryEnvironmentHttpUrl — throws raw Error at line 141); apps/web/src/components/settings/CloudSettings.tsx lines 158-181 (caller using runPromise with generic catch); apps/web/src/components/settings/CloudSettings.tsx lines 49-58 (cloudErrorMessage — checks CloudSettingsOperationError then Error)

[macroscopeapp]

🟡 Medium cloud/desktopClerk.tsx:128

If existingScript is found in the DOM but has already finished loading (its load event already fired), the event listeners added on lines 167-176 will never fire. Since window.__internal_ClerkUICtor check at line 150 already returned false, the promise will hang until the 15-second timeout rejects it, even though the script element exists and has completed loading.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file apps/web/src/cloud/desktopClerk.tsx around line 128:

If `existingScript` is found in the DOM but has already finished loading (its `load` event already fired), the event listeners added on lines 167-176 will never fire. Since `window.__internal_ClerkUICtor` check at line 150 already returned false, the promise will hang until the 15-second timeout rejects it, even though the script element exists and has completed loading.

Evidence trail:
apps/web/src/cloud/desktopClerk.tsx lines 128-187 (REVIEWED_COMMIT): loadDesktopClerkUi function. Line 129/150: checks window.__internal_ClerkUICtor. Line 138-140: queries for existing script. Line 154: reuses existing script if found. Lines 155-158: sets attributes on script (won't retrigger load per HTML spec for already-started scripts). Lines 167-176: adds load/error event listeners that won't fire on already-loaded scripts. Lines 164-166: 15-second timeout is the only fallback. Line 177: existing script is not re-appended. HTML spec: setting src on an already-inserted script element does not cause re-fetch or re-execution due to the 'already started' flag.

[macroscopeapp]

🟡 Medium agent-awareness/liveActivityController.ts:217

When activeActivity.missingSince is set at line 233, the function returns Effect.void without scheduling a timer to re-check after MISSING_STATE_GRACE_MS (30s). The timeout condition at line 239 only evaluates when syncAgentLiveActivities is invoked again by an external event. If no new snapshots arrive, the live activity remains visible indefinitely despite the grace period having elapsed.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file apps/mobile/src/features/agent-awareness/liveActivityController.ts around line 217:

When `activeActivity.missingSince` is set at line 233, the function returns `Effect.void` without scheduling a timer to re-check after `MISSING_STATE_GRACE_MS` (30s). The timeout condition at line 239 only evaluates when `syncAgentLiveActivities` is invoked again by an external event. If no new snapshots arrive, the live activity remains visible indefinitely despite the grace period having elapsed.

Evidence trail:
apps/mobile/src/features/agent-awareness/liveActivityController.ts lines 217-246 (syncAgentLiveActivities function with missing timer), line 28 (MISSING_STATE_GRACE_MS = 30_000), lines 434-465 (scheduleRemoteTokenRegistrationRetry showing the correct pattern with Effect.sleep), lines 161-182 (syncAgentLiveActivitiesForSnapshot - the only external caller that triggers re-sync), apps/mobile/src/features/agent-awareness/shellLiveActivitySync.ts lines 28-42 (showing sync only happens on atom subscription changes, no polling).