feat(connections): private connections + typed agent slots

[tlgimenes]

Summary

• Per-user private connections: every new mcp_connection defaults to access='user' (private to its creator); only the creator + org-shared rows are visible to other tools/UI.
• Typed slots on agents: connection_aggregations.slot_app_id lets an agent declare "I need an mcp-github" without binding to a specific connection. At runtime the slot resolves to the calling user's connection of that shape (or an org-shared one as fallback). Triggers/automations resolve via the automation's created_by.
• GitHub import bug fix: the "Import from GitHub" picker no longer leaks teammates' personal GitHub accounts. It now calls a new app-only CONNECTION_RESOLVE_FOR_USER tool that returns only the caller's own mcp-github connection.

Why

/user/installations on GitHub returns installations the authenticated user has any read access to — including teammates' personal accounts when collaborators are shared. Because Studio kept a single OAuth token per connection (migration 017 explicitly consolidated to this), opening the picker as one teammate showed installations belonging to another. This PR fixes that at the source: each user mints their own private connection and the resolver hands the picker the right one.

What landed

Phase	Commit	What
1	f97d1201e	Migration 097: connections.access + backfill, connection_aggregations.slot_app_id + XOR CHECK, R4 partial unique index. Schema-only.
2	f3bb9e6f0	Surface slots array on VirtualMCPEntity (+ fix Phase 1 RawAggregationRow drift).
2	59403a0bb	Fix VirtualMCPStorage.update preserving the untouched field across single-field updates.
2	6e65b4bb0	apps/mesh/src/core/slot-resolver.ts — resolveSlot, SlotResolutionCache, SlotUnresolvedError.
2	d12fc9059	Wire resolver into createVirtualClientFrom, emit OTel span attributes.
3	d79ddec9f	ConnectionEntity.access field + ConnectionStorage.list/findById take a viewerUserId and hide other users' private rows.
3	bf9c6ef1e	CONNECTION_RESOLVE_FOR_USER app-only tool.
4	63e5cadd1	github-repo-picker and add-storefront-modal use the resolver instead of useConnections ambiguity.

Test plan

• Unit + integration tests pass (~170 added/touched cases across migrations, storage, resolver, virtual-MCP client, connection tools).
• bun run check clean across all workspaces.
• bun run fmt:check clean.
• Manual browser test: opened "Import from GitHub" → new mcp-github connection created with access='user' in DB. Seeded a second teammate's private mcp-github connection in the same org and verified from the authenticated session that both CONNECTION_RESOLVE_FOR_USER and COLLECTION_CONNECTIONS_LIST return only the calling user's row.
• OAuth handoff to github.com → full end-to-end install (requires real GitHub login; out of scope for the automated check).

Known follow-ups (non-blocking)

• Phase 3b UI: connection list tabs (My / Org-shared), 🔒/🌐 row badges, promote/demote modal that deletes the downstream token on demote.
• Phase 5: org-admin nudge banner listing connections still on access='org'.
• Polish: OTel attribute key cardinality in createVirtualClientFrom (currently embeds app_id in the key — switch to span events or stable keys); extract a partitionAggregations helper to dedupe the partition loop between deserializeVirtualMCPEntity and update; extract a resolveSlotsForAgent helper to slim down the inlined ~70 LOC in createVirtualClientFrom.
• Latent: RawAggregationRow.child_connection_id is honest about nullability now; the local-type cast at virtual.ts:50 for the raw selectAll() results survives an extra as RawAggregationRow[] cast — safe today, worth tightening when slot-aware read paths multiply.

🤖 Generated with Claude Code

---

Update — Just-in-time connection gate for agents & subagents (commits 29b5b78d8…39c624ee7)

The earlier slot work gated the parent agent up front (block the composer until the user's slots resolve). But a parent can delegate to any agent via the subtask tool, and those subagents' slots were never gated — so they blew up mid-conversation with a generic "Subtask failed". This follow-up replaces the up-front gate with one runtime mechanism shared by both flows.

Design/Plan: docs/superpowers/specs/2026-05-31-just-in-time-connection-gate-design.md, docs/superpowers/plans/2026-05-31-just-in-time-connection-gate.md.

What changed

• SlotUnresolvedError now collects all missing app_ids + agent identity; createVirtualClientFrom resolves every slot and throws once.
• Both boundaries catch it and emit a single data-connect-required stream chunk: the subagent boundary (subtask.ts, keyed by toolCallId) and the parent boundary (decopilot harness index.ts). The model also gets plain-text so it doesn't blindly retry.
• Frontend: new ConnectCard (reuses ConnectSlotRow + useSlotAppDisplays; Retry re-runs the last turn) rendered inline as a visible part; the up-front ConnectAgentGate + useUnresolvedSlots are removed.
• Critical fix (found in adversarial review): the parent path's bare return emitted no finish chunk → the client hung in "streaming" forever and the run logged as failed. It now emits a well-formed start → text → data-connect-required → finish envelope, and resolveThreadStatus maps a connect-required part to requires_action (no false failure / failure sound). Also fixed a ConnectCard crash in the read-only monitoring route (useOptionalChatStream).

Test plan

• Unit: SlotUnresolvedError collect-all + agent identity; subtask SlotUnresolvedError catch path; resolveThreadStatus connect-required → requires_action. bun test green (44 cases across the touched files).
• bun run check clean (all workspaces); bun run fmt:check clean; lint 0 errors; knip clean.
• Whole-branch adversarial review (multi-agent) + independent re-verification of the critical finish-envelope path against the AI SDK internals.
• E2E (apps/mesh/e2e/tests/connect-card.spec.ts): deterministic parent-gate path (slot unresolved → data-connect-required part + finish chunk + clean requires_action status) — passes. The subagent path depends on the real LLM choosing subtask (non-deterministic) and is covered by the subtask.ts unit test instead.

🤖 Generated with Claude Code

---

Summary by cubic

Adds per-user private connections and typed agent slots with runtime resolution and an inline Connect card for agents and subagents. Fixes the GitHub import privacy leak and stuck installs by resolving the caller’s own GitHub connection by app_id; also merges latest main and links @decocms/std.

• New Features

  • Runtime slot resolution for Virtual MCPs via resolveSlot with SlotResolutionCache; SlotUnresolvedError now collects all missing app_ids and agent identity.
  • Just‑in‑time connect: unresolved slots emit a data-connect-required part rendered as a chat ConnectCard with registry icon/name and inline OAuth (connectApp + useConnectApp + useSlotAppDisplays); thread status is requires_action. Subagents (via subtask) use the same flow.
  • Connections UI: settings and AddConnectionDialog split into All/Shared/Personal tabs; lightweight per‑item enable/disable toggle replaces the dependency dialog; “Import from GitHub” always shown.
  • Private-by-default connections (connections.access); ConnectionStorage.findById/list require a viewer and support INTERNAL_VIEWER. Centralized token save (persistDownstreamToken) and OAuth identity decoration (oauth-identity) update titles like “Gmail (alice@acme.com)”.
  • Agents/data/infra: Virtual MCPs are org‑scoped; private connections can’t attach as concrete children; connectionAttachTarget auto‑picks slot vs child. Migrations 097–098 add connections.access, connection_aggregations.slot_app_id, flip existing rows to org access, and backfill/stabilize app_ids via deriveAppId. New tool CONNECTION_RESOLVE_FOR_USER; hooks useResolveConnectionForUser; constant GITHUB_APP_ID.

• Bug Fixes

  • GitHub import resolves by app_id (GITHUB_APP_ID) through CONNECTION_RESOLVE_FOR_USER and attaches as a typed slot, fixing cross‑user leaks and the stuck picker.
  • Parent/subagent connect-required paths emit a well‑formed start/text/data-connect-required/finish envelope; resolveThreadStatus maps to requires_action. Standardized @/ imports keep instanceof checks stable under hot reload.
  • Cross-user safety: all routes/tools pass a viewer to connections.findById/list; trusted infra uses INTERNAL_VIEWER.

^{Written for commit 649c4f8. Summary will update on new commits.}

[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: Minor (2.376.0) — based on feat: prefix

React with an emoji to override the release type:

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

Current version: 2.375.2

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

[cubic-dev-ai]

8 issues found

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/src/web/components/add-storefront-modal.tsx">

<violation number="1" location="apps/mesh/src/web/components/add-storefront-modal.tsx:246">
P2: Duplicate connection resolver query logic in BrowseFlow and UrlEntry; extract a shared hook to reduce drift risk in this privacy-sensitive path.</violation>

<violation number="2" location="apps/mesh/src/web/components/add-storefront-modal.tsx:302">
P1: BrowseFlow can get stuck in a perpetual "installing" UI when CONNECTION_RESOLVE_FOR_USER fails because resolver error states are not handled.</violation>
</file>

<sub>Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: BrowseFlow can get stuck in a perpetual "installing" UI when CONNECTION_RESOLVE_FOR_USER fails because resolver error states are not handled.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/src/web/components/add-storefront-modal.tsx, line 302:

<comment>BrowseFlow can get stuck in a perpetual "installing" UI when CONNECTION_RESOLVE_FOR_USER fails because resolver error states are not handled.</comment>

<file context>
@@ -279,7 +299,7 @@ function BrowseFlow({
   }
 
-  if (githubConnections.length === 0 && autoInstall.status === "idle") {
+  if (resolvedConnectionId === null) {
     return (
       <AutoInstallGitHubUI
</file context>

[tlgimenes]

Not a real issue (and cubic mislabeled the file — the diff_hunk actually targets apps/mesh/src/web/components/github-repo-picker.tsx, not add-storefront-modal.tsx which does not exist in this repo).

In PickerContent the resolver error state is handled explicitly before the "installing" fallback:

if (resolveQuery.isError) {
  return (
    <AutoInstallGitHubUI
      status="error"
      error={resolveQuery.error instanceof Error ? resolveQuery.error.message : "Failed to resolve GitHub connection."}
      retry={() => { resolveQuery.refetch(); }}
    />
  );
}

if (resolveQuery.isLoading || resolvedConnectionId === null) {
  return <AutoInstallGitHubUI status="installing" ... />;
}

InstallationPicker does the same (lines 529-543). On resolver failure the user sees the "Connection failed" UI with a Try again button — no perpetual "installing" state. Additionally, useAutoInstallGitHub is gated on resolveQuery.isSuccess && resolvedConnectionId === null, so it never fires on resolver error.

[cubic-dev-ai]

Thanks for the feedback.

[cubic-dev-ai]

P2: Duplicate connection resolver query logic in BrowseFlow and UrlEntry; extract a shared hook to reduce drift risk in this privacy-sensitive path.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/src/web/components/add-storefront-modal.tsx, line 246:

<comment>Duplicate connection resolver query logic in BrowseFlow and UrlEntry; extract a shared hook to reduce drift risk in this privacy-sensitive path.</comment>

<file context>
@@ -239,17 +234,42 @@ function BrowseFlow({
+  // Resolve the caller's own mcp-github connection (user-private preferred,
+  // org-shared fallback). Avoids the cross-user leak in
+  // useConnections({ slug: 'mcp-github' }).
+  const resolveQuery = useQuery({
+    queryKey: KEYS.connectionResolveForUser(org.id, "mcp-github"),
+    queryFn: async () => {
</file context>

[tlgimenes]

No-op here: apps/mesh/src/web/components/add-storefront-modal.tsx doesn't exist in this PR or the codebase. The two CONNECTION_RESOLVE_FOR_USER useQuery blocks live in github-repo-picker.tsx (lines 189 and 483), which is being handled by the sibling comment 3314944426.

[cubic-dev-ai]

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

[cubic-dev-ai]

9 issues found across 110 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/src/web/components/chat/connect-slot-row.tsx">

<violation number="1" location="apps/mesh/src/web/components/chat/connect-slot-row.tsx:50">
P3: `ready` is rendered as "Connecting…" with a spinner, which shows a false in-progress state after a successful connect. Render a completed label for `ready` instead.</violation>
</file>

<file name="apps/mesh/src/storage/derive-app-id.ts">

<violation number="1" location="apps/mesh/src/storage/derive-app-id.ts:80">
P1: `canonicalizeUrl` drops the URL scheme, so `http` and `https` endpoints can collapse to the same derived `app_id`. Include protocol in the canonical form to avoid false service collisions.</violation>

<violation number="2" location="apps/mesh/src/storage/derive-app-id.ts:88">
P2: `npx` package detection is fragile: it can pick flag values instead of the executed positional package.</violation>
</file>

<file name="apps/mesh/src/tools/virtual/assert-concrete-children-org-scoped.ts">

<violation number="1" location="apps/mesh/src/tools/virtual/assert-concrete-children-org-scoped.ts:17">
P3: Connection privacy checks are executed sequentially; run the lookups in parallel to avoid linear DB round-trip latency on create/update.</violation>
</file>

<file name="apps/mesh/migrations/097-connection-access-and-slots.ts">

<violation number="1" location="apps/mesh/migrations/097-connection-access-and-slots.ts:79">
P2: Rollback can fail after slot-based rows are created because `down()` sets `child_connection_id` back to NOT NULL before cleaning up rows where that column is intentionally NULL.</violation>
</file>

<file name="apps/mesh/src/storage/ports.ts">

<violation number="1" location="apps/mesh/src/storage/ports.ts:259">
P1: `findById` allows `organizationId` to be `undefined`, which enables unscoped cross-organization lookups when callers pass optional org context.</violation>
</file>

<file name="apps/mesh/src/api/app.ts">

<violation number="1" location="apps/mesh/src/api/app.ts:256">
P2: Avoid INTERNAL_VIEWER in this request-path lookup; it can pull another user’s private registry connection and use its `project_locator`.

(Based on your team's feedback about restricting INTERNAL_VIEWER to trusted infra and using user/null viewers in user-facing flows.) [FEEDBACK_USED]</violation>
</file>

<file name="apps/mesh/migrations/098-org-scope-connections-and-derive-app-id.ts">

<violation number="1" location="apps/mesh/migrations/098-org-scope-connections-and-derive-app-id.ts:21">
P2: This migration depends on mutable runtime code (`src/storage/derive-app-id`), which makes historical migration results non-deterministic across environments. Snapshot the derivation logic inside the migration (or a versioned migration-local helper) instead.</violation>

<violation number="2" location="apps/mesh/migrations/098-org-scope-connections-and-derive-app-id.ts:56">
P2: Guard the UPDATE with `app_id IS NULL` to avoid clobbering concurrent writes between the read and write steps.</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: canonicalizeUrl drops the URL scheme, so http and https endpoints can collapse to the same derived app_id. Include protocol in the canonical form to avoid false service collisions.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/src/storage/derive-app-id.ts, line 80:

<comment>`canonicalizeUrl` drops the URL scheme, so `http` and `https` endpoints can collapse to the same derived `app_id`. Include protocol in the canonical form to avoid false service collisions.</comment>

<file context>
@@ -0,0 +1,99 @@
+    scheme === "https" ? "443" : scheme === "http" ? "80" : "";
+  const port = u.port && u.port !== defaultPort ? `:${u.port}` : "";
+  const path = u.pathname.replace(/\/+$/, "");
+  return `${host}${port}${path}`;
+}
+
</file context>

[cubic-dev-ai]

P1: findById allows organizationId to be undefined, which enables unscoped cross-organization lookups when callers pass optional org context.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/src/storage/ports.ts, line 259:

<comment>`findById` allows `organizationId` to be `undefined`, which enables unscoped cross-organization lookups when callers pass optional org context.</comment>

<file context>
@@ -228,18 +228,47 @@ export interface AsyncResearchJobStoragePort {
-  findById(id: string): Promise<ConnectionEntity | null>;
+  findById(
+    id: string,
+    organizationId: string | undefined,
+    viewer: ConnectionViewer,
+  ): Promise<ConnectionEntity | null>;
</file context>

[cubic-dev-ai]

P2: Rollback can fail after slot-based rows are created because down() sets child_connection_id back to NOT NULL before cleaning up rows where that column is intentionally NULL.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/migrations/097-connection-access-and-slots.ts, line 79:

<comment>Rollback can fail after slot-based rows are created because `down()` sets `child_connection_id` back to NOT NULL before cleaning up rows where that column is intentionally NULL.</comment>

<file context>
@@ -0,0 +1,95 @@
+  `.execute(db);
+  await sql`
+    ALTER TABLE connection_aggregations
+      ALTER COLUMN child_connection_id SET NOT NULL
+  `.execute(db);
+  await sql`
</file context>

[cubic-dev-ai]

P2: Avoid INTERNAL_VIEWER in this request-path lookup; it can pull another user’s private registry connection and use its project_locator.

(Based on your team's feedback about restricting INTERNAL_VIEWER to trusted infra and using user/null viewers in user-facing flows.)

View Feedback

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/src/api/app.ts, line 256:

<comment>Avoid INTERNAL_VIEWER in this request-path lookup; it can pull another user’s private registry connection and use its `project_locator`.

(Based on your team's feedback about restricting INTERNAL_VIEWER to trusted infra and using user/null viewers in user-facing flows.) </comment>

<file context>
@@ -248,6 +253,7 @@ async function getDecoStoreProjectLocator(
         value: `${DECO_STORE_URL}%`,
       },
       limit: 1,
+      viewer: INTERNAL_VIEWER,
     },
   );
</file context>

Suggested change

	viewer: INTERNAL_VIEWER,
	viewer: null,

[cubic-dev-ai]

P2: Guard the UPDATE with app_id IS NULL to avoid clobbering concurrent writes between the read and write steps.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/migrations/098-org-scope-connections-and-derive-app-id.ts, line 56:

<comment>Guard the UPDATE with `app_id IS NULL` to avoid clobbering concurrent writes between the read and write steps.</comment>

<file context>
@@ -0,0 +1,71 @@
+      app_id: row.app_id,
+    });
+    if (appId) {
+      await sql`UPDATE connections SET app_id = ${appId} WHERE id = ${row.id}`.execute(
+        db,
+      );
</file context>

[cubic-dev-ai]

P2: This migration depends on mutable runtime code (src/storage/derive-app-id), which makes historical migration results non-deterministic across environments. Snapshot the derivation logic inside the migration (or a versioned migration-local helper) instead.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/migrations/098-org-scope-connections-and-derive-app-id.ts, line 21:

<comment>This migration depends on mutable runtime code (`src/storage/derive-app-id`), which makes historical migration results non-deterministic across environments. Snapshot the derivation logic inside the migration (or a versioned migration-local helper) instead.</comment>

<file context>
@@ -0,0 +1,71 @@
+ */
+
+import { sql, type Kysely } from "kysely";
+import { deriveAppId } from "../src/storage/derive-app-id";
+
+interface ConnRow {
</file context>

[cubic-dev-ai]

P2: npx package detection is fragile: it can pick flag values instead of the executed positional package.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/src/storage/derive-app-id.ts, line 88:

<comment>`npx` package detection is fragile: it can pick flag values instead of the executed positional package.</comment>

<file context>
@@ -0,0 +1,99 @@
+  const command = (stdio.command ?? "").trim();
+  const args = (stdio.args ?? []).map((a) => a.trim());
+  if (command === "npx" || command === "bunx") {
+    const pkg = args.find((a) => a.length > 0 && !a.startsWith("-"));
+    if (pkg) return `npx:${pkg}`;
+  }
</file context>

[cubic-dev-ai]

P3: ready is rendered as "Connecting…" with a spinner, which shows a false in-progress state after a successful connect. Render a completed label for ready instead.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/src/web/components/chat/connect-slot-row.tsx, line 50:

<comment>`ready` is rendered as "Connecting…" with a spinner, which shows a false in-progress state after a successful connect. Render a completed label for `ready` instead.</comment>

<file context>
@@ -0,0 +1,80 @@
+          disabled={busy}
+          onClick={() => connect(registryItem)}
+        >
+          {status === "connecting" || status === "ready" ? (
+            <>
+              <Loading01 size={12} className="animate-spin" />
</file context>

[cubic-dev-ai]

P3: Connection privacy checks are executed sequentially; run the lookups in parallel to avoid linear DB round-trip latency on create/update.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At apps/mesh/src/tools/virtual/assert-concrete-children-org-scoped.ts, line 17:

<comment>Connection privacy checks are executed sequentially; run the lookups in parallel to avoid linear DB round-trip latency on create/update.</comment>

<file context>
@@ -0,0 +1,29 @@
+  connectionStorage: ConnectionStoragePort,
+  organizationId: string,
+): Promise<void> {
+  for (const conn of connections) {
+    const c = await connectionStorage.findById(
+      conn.connection_id,
</file context>