feat(studio): Unit D — real backend persistence via Karrio metafields (unblocks EBE-99)

Per dan's suggestion: use metafields with a dedicated studio.* namespace as the
round-trippable per-user KV the OSS API otherwise lacked. Verified live against
:5002 — create_metafield(key, type:json, value) + metafields(filter:{key}) +
update/delete give a clean per-user CRUD round trip, no backend change needed.

- metastore.ts (new): readMeta/writeMeta/deleteMeta over metafields, + setStudioCtx
  so ctx-less stores reach the backend (SessionProvider registers the ctx).
- preferences.ts: syncToBackend -> writeMeta('studio.customization'); loadFromBackend
  now ACTUALLY hydrates (was a documented no-op) by reading the metafield.
- agents.ts: metafield-backed adapter (studio.agents / studio.mcp-servers) with
  localStorage write-through cache + offline fallback; replaces localStorage-only.
- session.tsx: on login, register ctx + hydrate UI prefs from the backend metafield.

Studio-native state (theme/accent/density/font, agent + MCP configs) now follows
the user across devices via real Karrio persistence. localStorage remains the
offline cache. tsc/build clean; tweaks/editor/build specs pass; live CRUD verified.

Author: claude

apps/studio/src/lib/karrio/agents.ts

@@ -12,6 +12,7 @@
 // a backend proxy that does not exist in OSS Karrio. The `McpServerConfig`
 // records stored here are *configuration only*. The `connectionStatus` field
 // is set to "config-only" to make this explicit.
+import { getStudioCtx, readMeta, writeMeta } from "~/lib/karrio/metastore";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -174,10 +175,80 @@ const localStorageAdapter: BackendAdapter = {
 };
 
 // ---------------------------------------------------------------------------
-// Active adapter (swap this to a REST adapter when the backend ships)
+// Backend (metafield) adapter — real per-user persistence with localStorage cache
+// ---------------------------------------------------------------------------
+// Agent + MCP configs persist as per-user JSON metafields under the `studio.*`
+// namespace (see metastore.ts), with localStorage as an immediate write-through
+// cache and offline fallback. The ctx comes from SessionProvider via setStudioCtx.
+
+const META_AGENTS_KEY = "studio.agents";
+const META_MCP_KEY = "studio.mcp-servers";
+
+async function loadList<T>(metaKey: string, lsKey: string): Promise<T[]> {
+  const ctx = getStudioCtx();
+  if (ctx?.token) {
+    try {
+      const remote = await readMeta<T[]>(ctx, metaKey);
+      if (remote) {
+        writeJson(lsKey, remote); // refresh the local cache
+        return remote;
+      }
+    } catch {
+      /* network/permission error — fall back to cache */
+    }
+  }
+  return readJson<T[]>(lsKey, []);
+}
+
+async function persistList<T>(metaKey: string, lsKey: string, next: T[]): Promise<void> {
+  writeJson(lsKey, next); // immediate cache
+  const ctx = getStudioCtx();
+  if (ctx?.token) {
+    try {
+      await writeMeta(ctx, metaKey, next);
+    } catch {
+      /* sync failure is non-fatal; cache holds and re-syncs on next write */
+    }
+  }
+}
+
+const backendAdapter: BackendAdapter = {
+  listAgents: () => loadList<AgentDef>(META_AGENTS_KEY, LS_AGENTS_KEY),
+
+  saveAgent: async (agent) => {
+    const existing = await loadList<AgentDef>(META_AGENTS_KEY, LS_AGENTS_KEY);
+    const idx = existing.findIndex((a) => a.id === agent.id);
+    const next = idx >= 0 ? existing.map((a) => (a.id === agent.id ? agent : a)) : [...existing, agent];
+    await persistList(META_AGENTS_KEY, LS_AGENTS_KEY, next);
+    return agent;
+  },
+
+  deleteAgent: async (id) => {
+    const next = (await loadList<AgentDef>(META_AGENTS_KEY, LS_AGENTS_KEY)).filter((a) => a.id !== id);
+    await persistList(META_AGENTS_KEY, LS_AGENTS_KEY, next);
+  },
+
+  listMcpServers: () => loadList<McpServerConfig>(META_MCP_KEY, LS_MCP_KEY),
+
+  saveMcpServer: async (server) => {
+    const existing = await loadList<McpServerConfig>(META_MCP_KEY, LS_MCP_KEY);
+    const idx = existing.findIndex((s) => s.id === server.id);
+    const next = idx >= 0 ? existing.map((s) => (s.id === server.id ? server : s)) : [...existing, server];
+    await persistList(META_MCP_KEY, LS_MCP_KEY, next);
+    return server;
+  },
+
+  deleteMcpServer: async (id) => {
+    const next = (await loadList<McpServerConfig>(META_MCP_KEY, LS_MCP_KEY)).filter((s) => s.id !== id);
+    await persistList(META_MCP_KEY, LS_MCP_KEY, next);
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Active adapter — metafield-backed with localStorage cache/fallback.
 // ---------------------------------------------------------------------------
 
-const defaultAdapter: BackendAdapter = localStorageAdapter;
+const defaultAdapter: BackendAdapter = backendAdapter;
 
 // ---------------------------------------------------------------------------
 // Helpers

apps/studio/src/lib/karrio/metastore.ts

@@ -0,0 +1,65 @@
+// metastore.ts — round-trippable per-user backend KV via Karrio metafields.
+// Studio-native app state (UI preferences, agent + MCP configs) is stored as
+// JSON metafields under a `studio.*` key namespace, scoped to the authenticated
+// user by Karrio's ownership model. This is the real backend behind the
+// localStorage caches in preferences.ts / agents.ts (unblocks EBE-99).
+//
+// Verified live: a free-standing `create_metafield(key, type:json, value)` plus
+// `metafields(filter:{ key })` gives a clean per-user create/read/update/delete
+// round trip — no backend change required.
+import { graphql, type KarrioCtx } from "~/lib/karrio/client";
+
+// The SessionProvider registers the current authenticated ctx here (client-side)
+// so ctx-less stores (agents.ts) can reach the backend without threading ctx
+// through every call. Null on the server / when unauthenticated.
+let studioCtx: KarrioCtx | null = null;
+export function setStudioCtx(ctx: KarrioCtx | null): void {
+  studioCtx = ctx;
+}
+export function getStudioCtx(): KarrioCtx | null {
+  return studioCtx;
+}
+
+const READ = `query($key: String!) {
+  metafields(filter: { key: $key }) { edges { node { id value } } }
+}`;
+const CREATE = `mutation($input: CreateMetafieldInput!) {
+  create_metafield(input: $input) { metafield { id } errors { field messages } }
+}`;
+const UPDATE = `mutation($input: UpdateMetafieldInput!) {
+  update_metafield(input: $input) { metafield { id } errors { field messages } }
+}`;
+const DELETE = `mutation($input: DeleteMutationInput!) {
+  delete_metafield(input: $input) { id }
+}`;
+
+type ReadResult<T> = { metafields: { edges: Array<{ node: { id: string; value: T } }> } };
+
+async function find<T>(ctx: KarrioCtx, key: string): Promise<{ id: string; value: T } | null> {
+  const data = await graphql<Partial<ReadResult<T>>>(ctx, READ, { key });
+  return data?.metafields?.edges?.[0]?.node ?? null;
+}
+
+/** Read a JSON metafield value by key, or null when absent/unauthenticated. */
+export async function readMeta<T>(ctx: KarrioCtx, key: string): Promise<T | null> {
+  if (!ctx.token) return null;
+  return (await find<T>(ctx, key))?.value ?? null;
+}
+
+/** Upsert a JSON metafield by key (create or update). No-op when unauthenticated. */
+export async function writeMeta(ctx: KarrioCtx, key: string, value: unknown): Promise<void> {
+  if (!ctx.token) return;
+  const existing = await find(ctx, key);
+  if (existing) {
+    await graphql(ctx, UPDATE, { input: { id: existing.id, value } });
+  } else {
+    await graphql(ctx, CREATE, { input: { key, type: "json", value } });
+  }
+}
+
+/** Delete the metafield for a key, if present. */
+export async function deleteMeta(ctx: KarrioCtx, key: string): Promise<void> {
+  if (!ctx.token) return;
+  const existing = await find(ctx, key);
+  if (existing) await graphql(ctx, DELETE, { input: { id: existing.id } });
+}

apps/studio/src/lib/karrio/preferences.ts

@@ -21,7 +21,8 @@
 //   savePrefs({ accent: "#10B981" });    // synchronous + kicks off async sync
 //   await syncToBackend(ctx, prefs);     // explicit flush (e.g. on unload)
 
-import { graphql, type KarrioCtx } from "~/lib/karrio/client";
+import type { KarrioCtx } from "~/lib/karrio/client";
+import { readMeta, writeMeta } from "~/lib/karrio/metastore";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -154,78 +155,47 @@ export function applyFont(font: FontStack): void {
 }
 
 // ---------------------------------------------------------------------------
-// Backend adapter — async sync layer (Karrio User.metadata)
+// Backend adapter — async sync layer (Karrio metafields, key-namespaced)
 // ---------------------------------------------------------------------------
-
-// GraphQL mutation — writes the full preferences blob into User.metadata under
-// the BACKEND_META_KEY namespace. Karrio's process_dictionaries_mutations helper
-// merges dict keys, so other metadata keys are preserved.
-const UPDATE_USER_PREFS_MUTATION = `
-  mutation UpdateUserPreferences($data: UpdateUserInput!) {
-    update_user(input: $data) {
-      user {
-        email
-      }
-      errors {
-        field
-        messages
-      }
-    }
-  }
-`;
-
-type UpdateUserResponse = {
-  update_user: {
-    user: { email: string } | null;
-    errors: Array<{ field: string; messages: string[] }> | null;
-  };
-};
+// Studio prefs persist as a per-user JSON metafield under BACKEND_META_KEY
+// ("studio.customization"). Unlike User.metadata (write-only on the OSS
+// GraphQL), metafields round-trip cleanly — so loadFromBackend() actually
+// hydrates. See metastore.ts.
 
 /**
- * Flush the given preferences to the Karrio backend (User.metadata).
- *
- * Writes to `User.metadata["studio.customization"]`. Fails silently if the
- * user is not authenticated (ctx.token absent) — localStorage remains the
- * source of truth in that case.
+ * Flush the given preferences to the Karrio backend (metafield
+ * `studio.customization`). No-op + silent when unauthenticated or on error —
+ * localStorage remains the applied source of truth in that case.
  */
 export async function syncToBackend(
   ctx: KarrioCtx,
   prefs: Preferences,
 ): Promise<void> {
-  if (!ctx.token) return; // unauthenticated — localStorage only
-
   try {
-    await graphql<UpdateUserResponse>(ctx, UPDATE_USER_PREFS_MUTATION, {
-      data: {
-        metadata: { [BACKEND_META_KEY]: prefs },
-      },
-    });
+    await writeMeta(ctx, BACKEND_META_KEY, prefs);
   } catch {
-    // Sync failure is non-fatal. The user's local settings remain applied;
-    // they will re-sync on next successful write.
+    // Sync failure is non-fatal; local settings stay applied and re-sync later.
   }
 }
 
 /**
- * Load preferences from the Karrio backend into localStorage.
- *
- * LIMITATION: The OSS `UserType` GraphQL selection does not expose the
- * `metadata` field. Until `metadata: JSON` is added to the `user` query
- * response in `karrio/server/graph/schemas/base/types.py` (UserType class),
- * this function is a no-op and localStorage remains the primary read source.
- *
- * TODO(backend): Expose `metadata` on UserType, then implement:
- *   const data = await graphql<{ user: { metadata: Record<string, unknown> } }>(
- *     ctx, `query { user { metadata } }`,
- *   );
- *   const remote = data.user?.metadata?.[BACKEND_META_KEY] as Partial<Preferences> | undefined;
- *   if (remote) savePrefs(remote);
+ * Load preferences from the Karrio backend (metafield `studio.customization`)
+ * into localStorage, and return the merged preferences. Falls back to the
+ * localStorage cache when unauthenticated or on any error.
  */
 export async function loadFromBackend(
-  _ctx: KarrioCtx,
+  ctx: KarrioCtx,
 ): Promise<Preferences> {
-  // No-op: returns the current localStorage-cached prefs.
-  // When the TODO above is resolved, replace this body with the remote fetch.
+  try {
+    const remote = await readMeta<Partial<Preferences>>(ctx, BACKEND_META_KEY);
+    if (remote) {
+      const merged = { ...loadPrefs(), ...remote };
+      savePrefs(merged);
+      return merged;
+    }
+  } catch {
+    // Ignore — fall through to the localStorage cache.
+  }
   return loadPrefs();
 }
 

apps/studio/src/lib/karrio/session.tsx

@@ -14,6 +14,8 @@ import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { getSession, refreshSession } from "~/server/auth";
 import { karrioBaseUrl } from "~/lib/karrio/env";
 import { setRefreshHandler, type KarrioCtx } from "~/lib/karrio/client";
+import { applyPrefsToDOM, loadFromBackend } from "~/lib/karrio/preferences";
+import { setStudioCtx } from "~/lib/karrio/metastore";
 
 type SessionContextValue = {
   ctx: KarrioCtx;
@@ -51,8 +53,19 @@ export function SessionProvider({ children }: { children: ReactNode }) {
     return () => setRefreshHandler(null);
   }, [queryClient]);
 
+  // Hydrate Studio UI preferences from the backend (metafield `studio.customization`)
+  // once authenticated, so settings follow the user across devices.
+  const token = sessionQuery.data?.access;
+  useEffect(() => {
+    // Register the current ctx so ctx-less stores (agents/MCP configs) can reach
+    // the backend, then hydrate UI preferences from the backend metafield.
+    setStudioCtx(token ? { baseUrl, token, orgId, testMode } : null);
+    if (!token) return;
+    void loadFromBackend({ baseUrl, token, orgId, testMode }).then(applyPrefsToDOM);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [token, baseUrl, orgId, testMode]);
+
   const value = useMemo<SessionContextValue>(() => {
-    const token = sessionQuery.data?.access;
     return {
       ctx: { baseUrl, token, orgId, testMode },
       isAuthenticated: Boolean(token),