Harness implementation research: link daemon, agent pill, VM-as-runtime

[tlgimenes]

Summary

End-to-end implementation of harness execution via a local link daemon, with the UI shifted from Runner+Harness pills to a single Agent pill driven by the link's real capabilities.

• Link daemon — registration / heartbeat / shutdown over X-Link-Secret, capability probe for claude-code / codex / sandbox, current-link surfaced to the UI via LINK_CURRENT_GET and useCurrentLink.
• Agent pill — replaces Runner+Harness with a single eligibility-aware pill, per-agent model selector, laptop-CLI variant (Claude Code / Codex), connect-your-laptop empty-state tile.
• VM as runtime identity — vm-proxy now resolves the sandbox runner per-user via ctx.linkRegistry (with env-singleton fallback for docker / agent-sandbox).
• vmMap data fix — migrations 080/081 silently no-op'd on a dropped table; migration 082 performs the intended v1→v2 rekey and runnerKind→sandboxProviderKind rename on connections.metadata, with a tolerant normalizeVmMap on the read path.
• Auth hygiene — link daemon uses X-Link-Secret instead of Authorization: Bearer … so heartbeats don't trip Better Auth's INVALID_API_KEY logger; legacy well-known deprecation middleware pinned to its two specific paths.

Test plan

• bun test apps/mesh/src/links (heartbeat / shutdown via X-Link-Secret)
• bun test apps/mesh/migrations/082-fix-vm-map-rekey.test.ts
• bun test apps/mesh/src/storage/virtual (normalized vmMap on read)
• Manual: register a link from the CLI, confirm no INVALID_API_KEY log per heartbeat
• Manual: open chat with no GitHub repo, verify Agent pill falls back to Decopilot
• Manual: trigger /api/vm-proxy/... as a remote-user deployment, confirm 503 surfaces when no link daemon

🤖 Generated with Claude Code

---

Summary by cubic

Runs harnesses on the user’s laptop via a new deco link daemon with HMAC‑secured remote dispatch, replaces Runner+Harness pills with a capability‑aware Agent pill, and switches VM routing to a SandboxProviderKind with per‑thread pins and a 3‑level vmMap. Migrations are renumbered to 083–088 to avoid collisions and ensure the vmMap data fix lands.

• New Features

  • deco link daemon (apps/mesh/src/link-daemon): registers at /api/links, heartbeats via X-Link-Secret, serves an HMAC control plane with nonce replay protection, opens a Warp tunnel (or --no-tunnel localhost), probes capabilities (claude-code, codex, decopilot-sandbox), and exposes status via GET /api/links/me; bun run smoke:link checks link health.
  • Remote dispatch: resolves a target from the 3‑level vmMap plus per‑thread pins (threads.sandbox_provider_kind/threads.harness_id), streams to the desktop daemon over its tunnel with HMAC signing, supports cancellation, and bridges SSE back to chat; returns 409 with clear reasons when the link is offline or missing a capability.
  • Links infra: TTL’d LinkRegistry (NATS JetStream / In‑mem) backs /api/links (register/heartbeat/shutdown/status); wire protocol, HMAC, and fixtures live under apps/mesh/src/links/protocol; dev can auto‑spawn the daemon and mint a local session when MESH_ALLOW_LOCALHOST_LINKS=1; CLI adds --local-sandbox-provider and --no-tunnel.
  • Agent pill: unified, capability‑aware pill with per‑agent tier mapping and a “connect your desktop” empty state; browser‑safe model lists split into claude-code-models.ts and codex-models.ts; local‑CLI provider adapters and the cli-activate path removed; @anthropic-ai/claude-agent-sdk moved to optionalDependencies.

• Migration

  • Apply 083–088: add then drop threads.run_locally; drop host sandbox rows; rename sandbox_runner_state.runner_kind → sandbox_provider_kind; add per‑thread pins (threads.sandbox_provider_kind, threads.harness_id); re‑key connections.metadata.vmMap from 2‑level to 3‑level and finish the missed runnerKind → sandboxProviderKind rewrite with explicit casts and COALESCE; purge ai_provider_keys sentinels for claude-code/codex.

^{Written for commit 3ab12d0. Summary will update on new commits. Review in cubic}

[github-actions]

🧪 Benchmark

Should we run the Virtual MCP strategy benchmark for this PR?

React with 👍 to run the benchmark.

Reaction	Action
👍	Run quick benchmark (10 & 128 tools)

Benchmark will run on the next push after you react.

[github-actions]

Release Options

Suggested: Patch (2.339.3) — default (no conventional commit prefix detected)

React with an emoji to override the release type:

Reaction	Type	Next Version
👍	Prerelease	2.339.3-alpha.1
🎉	Patch	2.339.3
❤️	Minor	2.340.0
🚀	Major	3.0.0

Current version: 2.339.2

Note: If multiple reactions exist, the smallest bump wins. If no reactions, the suggested bump is used (default: patch).

[cubic-dev-ai]

4 issues found across 238 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/mesh/migrations/080-rename-runner-kind.ts">

<violation number="1" location="apps/mesh/migrations/080-rename-runner-kind.ts:37">
P1: Guard the vmMap aggregate with `COALESCE(..., '{}'::jsonb)`; otherwise rows with an empty `vmMap` can end up with `metadata = NULL` during migration.</violation>
</file>

<file name="apps/link/src/tunnel.ts">

<violation number="1" location="apps/link/src/tunnel.ts:51">
P1: Do not fall back to a hardcoded tunnel API key; require explicit configuration (input or env) instead.</violation>
</file>

<file name="apps/link/src/control-plane.ts">

<violation number="1" location="apps/link/src/control-plane.ts:77">
P2: Validate `handle` as a non-empty string (not just truthy) before calling `ensureSandbox`.</violation>
</file>

<sub>Note: This PR contains a large number of files. cubic only reviews up to 100 files per PR, so some files may not have been reviewed. cubic prioritizes the most important files to review.
On a pro plan you can use ultrareview for larger PRs.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: Do not fall back to a hardcoded tunnel API key; require explicit configuration (input or env) instead.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/link/src/tunnel.ts, line 51:

<comment>Do not fall back to a hardcoded tunnel API key; require explicit configuration (input or env) instead.</comment>

<file context>
@@ -0,0 +1,85 @@
+    apiKey:
+      input.apiKey ??
+      process.env.DECO_TUNNEL_SERVER_TOKEN ??
+      LEGACY_TUNNEL_TOKEN,
+  });
+  await Promise.race([
</file context>

[tlgimenes]

Pre-existing shared key, not per-user. The file's header documents this explicitly ("The Warp server still uses a legacy shared key... Once Warp accepts OAuth tokens we can swap the source in one place"). The fallback was introduced in #3283 to fix a silent registration hang — this PR just extracts it into apps/mesh/src/link-daemon/tunnel.ts without changing the auth model. Removing it would break every laptop CLI client that hasn't manually set DECO_TUNNEL_SERVER_TOKEN. Tracked for replacement when Warp accepts OAuth bearers.

[cubic-dev-ai]

Thanks for the feedback! I've saved this as a new learning to improve future reviews.

[cubic-dev-ai]

P1: Guard the vmMap aggregate with COALESCE(..., '{}'::jsonb); otherwise rows with an empty vmMap can end up with metadata = NULL during migration.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/migrations/080-rename-runner-kind.ts, line 37:

<comment>Guard the vmMap aggregate with `COALESCE(..., '{}'::jsonb)`; otherwise rows with an empty `vmMap` can end up with `metadata = NULL` during migration.</comment>

<file context>
@@ -0,0 +1,107 @@
+        v.metadata,
+        '{vmMap}',
+        (
+          SELECT jsonb_object_agg(
+            user_key,
+            (
</file context>

[tlgimenes]

Fixed in c8a0e5435. Wrapped both jsonb_object_agg calls (outer over vmMap and inner over user_map) in COALESCE(..., '{}'::jsonb) so rows whose vmMap is {} — or whose nested user_map is {} — keep an empty object instead of getting metadata = NULL via jsonb_set. Also tightened the WHERE to require jsonb_typeof(metadata->'vmMap') = 'object' so non-object vmMap values are skipped. Same guard applied to the down migration.

[cubic-dev-ai]

Thanks for the feedback! I've saved this as a new learning to improve future reviews.

[cubic-dev-ai]

P2: Validate handle as a non-empty string (not just truthy) before calling ensureSandbox.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/link/src/control-plane.ts, line 77:

<comment>Validate `handle` as a non-empty string (not just truthy) before calling `ensureSandbox`.</comment>

<file context>
@@ -0,0 +1,104 @@
+          headers: { "content-type": "application/json" },
+        });
+      }
+      if (!parsed.handle) {
+        return new Response(JSON.stringify({ error: "missing_handle" }), {
+          status: 400,
</file context>

[tlgimenes]

Fixed. Changed the check to typeof handle === "string" && handle.length > 0 so non-string truthy bodies (e.g. arrays, objects) are also rejected with 400.

[cubic-dev-ai]

Thanks for the feedback! I've saved this as a new learning to improve future reviews.

[cubic-dev-ai]

1 issue found across 111 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="apps/mesh/migrations/080-rename-runner-kind.ts">

<violation number="1" location="apps/mesh/migrations/080-rename-runner-kind.ts:37">
P1: Guard the vmMap aggregate with `COALESCE(..., '{}'::jsonb)`; otherwise rows with an empty `vmMap` can end up with `metadata = NULL` during migration.</violation>
</file>

<file name="apps/link/src/tunnel.ts">

<violation number="1" location="apps/link/src/tunnel.ts:51">
P1: Do not fall back to a hardcoded tunnel API key; require explicit configuration (input or env) instead.</violation>
</file>

<file name="apps/link/src/control-plane.ts">

<violation number="1" location="apps/link/src/control-plane.ts:77">
P2: Validate `handle` as a non-empty string (not just truthy) before calling `ensureSandbox`.</violation>
</file>

<sub>Note: This PR contains a large number of files. cubic only reviews up to 100 files per PR, so some files may not have been reviewed. cubic prioritizes the most important files to review.
On a pro plan you can use ultrareview for larger PRs.
Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>