@agent-native/core 0.127.3 → 0.128.1

package/src/client/transcription/use-live-transcription.ts

@@ -15,6 +15,8 @@ import { useCallback, useEffect, useRef, useState } from "react";
 
 const NETWORK_RESTART_BASE_MS = 1_000;
 const NETWORK_RESTART_MAX_MS = 30_000;
+const RESTART_RETRY_BASE_MS = 400;
+const MAX_RESTART_ATTEMPTS = 8;
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 function getSpeechRecognitionCtor(): any {
@@ -42,6 +44,14 @@ export interface LiveTranscriptionApi {
   stopAndWait: (timeoutMs?: number) => Promise<string>;
   pause: () => void;
   resume: () => void;
+  /**
+   * Non-null when recognition died before the caller asked it to stop, so the
+   * returned transcript covers only part of the session. Callers must pass it
+   * along rather than storing a partial transcript as a finished one. Read
+   * through a getter (not state) so a stop handler can never observe a stale
+   * "everything was fine" value from an earlier render.
+   */
+  getIncompleteReason: () => string | null;
 }
 
 export function useLiveTranscription(
@@ -64,6 +74,20 @@ export function useLiveTranscription(
   const restartTimerRef = useRef<number | null>(null);
   const networkErrorCountRef = useRef(0);
   const restartDelayRef = useRef(0);
+  const restartFailureCountRef = useRef(0);
+  const incompleteReasonRef = useRef<string | null>(null);
+
+  // First reason wins: it names what actually broke the capture, and later
+  // teardown noise must not overwrite it.
+  const markIncomplete = useCallback((reason: string) => {
+    if (incompleteReasonRef.current) return;
+    incompleteReasonRef.current = reason;
+  }, []);
+
+  const getIncompleteReason = useCallback(
+    () => incompleteReasonRef.current,
+    [],
+  );
 
   const currentTranscript = useCallback(
     () =>
@@ -102,6 +126,8 @@ export function useLiveTranscription(
     stoppedManuallyRef.current = false;
     networkErrorCountRef.current = 0;
     restartDelayRef.current = 0;
+    restartFailureCountRef.current = 0;
+    incompleteReasonRef.current = null;
     setTranscript("");
     setInterimText("");
 
@@ -122,6 +148,7 @@ export function useLiveTranscription(
       if (event.results.length > 0) {
         networkErrorCountRef.current = 0;
         restartDelayRef.current = 0;
+        restartFailureCountRef.current = 0;
       }
     };
 
@@ -133,6 +160,9 @@ export function useLiveTranscription(
         event.error === "audio-capture"
       ) {
         stoppedManuallyRef.current = true;
+        markIncomplete(
+          `Browser speech recognition stopped mid-recording (${event.error}).`,
+        );
         setIsActive(false);
         return;
       }
@@ -163,17 +193,34 @@ export function useLiveTranscription(
           }
           try {
             recognition.start();
+            restartFailureCountRef.current = 0;
           } catch {
-            setIsActive(false);
+            // Chrome throws InvalidStateError while the previous session is
+            // still releasing. `onend` has already fired and will not fire
+            // again, so this timer is the only thing left that can revive
+            // recognition — giving up here freezes the transcript mid-recording
+            // and the partial text then looks like the whole recording.
+            const attempt = ++restartFailureCountRef.current;
+            if (attempt >= MAX_RESTART_ATTEMPTS) {
+              markIncomplete(
+                "Browser speech recognition stopped mid-recording and could not be restarted.",
+              );
+              setIsActive(false);
+              return;
+            }
+            restartTimerRef.current = window.setTimeout(
+              restart,
+              RESTART_RETRY_BASE_MS * attempt,
+            );
           }
         };
-        const delayMs = restartDelayRef.current;
+        // Never call start() synchronously from inside onend — Chrome still
+        // has the session marked as running during dispatch and throws.
+        restartTimerRef.current = window.setTimeout(
+          restart,
+          restartDelayRef.current,
+        );
         restartDelayRef.current = 0;
-        if (delayMs > 0) {
-          restartTimerRef.current = window.setTimeout(restart, delayMs);
-        } else {
-          restart();
-        }
         return;
       }
       setIsActive(false);
@@ -185,10 +232,14 @@ export function useLiveTranscription(
     try {
       recognition.start();
       setIsActive(true);
-    } catch {
-      /* browser may block without user gesture */
+    } catch (err) {
+      // Browser may block without user gesture. Nothing was captured, and the
+      // caller must not treat the resulting empty text as "no speech".
+      markIncomplete(
+        `Browser speech recognition could not start (${(err as Error)?.message || "unknown error"}).`,
+      );
     }
-  }, [currentTranscript, lang]);
+  }, [currentTranscript, lang, markIncomplete]);
 
   const stop = useCallback((): string => {
     const text = currentTranscript();
@@ -307,5 +358,6 @@ export function useLiveTranscription(
     stopAndWait,
     pause,
     resume,
+    getIncompleteReason,
   };
 }

package/src/db/client.ts

@@ -1595,6 +1595,35 @@ async function initClient(): Promise<void> {
  * Get the singleton database client. Returns a `DbExec` whose first
  * `execute()` call lazily initializes the underlying driver.
  */
+/**
+ * Point a missing-table failure at the cause instead of the symptom.
+ *
+ * The driver reports `no such table: x` / `relation "x" does not exist` from
+ * whichever query happened to touch it first, so the stack lands in an action
+ * and reads as a bug in that action. The actual cause is almost always that no
+ * migration ever created the table — a template with no `server/plugins/db.ts`
+ * creates none, and core's own tables self-heal, so app tables are the only
+ * ones that fail this way. Appends rather than replaces: `isDuplicateColumnError`
+ * and friends match substrings of the driver's original text.
+ */
+export function annotateMissingTable(err: unknown, sql: unknown): unknown {
+  if (!(err instanceof Error)) return err;
+  const match =
+    /no such table:?\s*["'`]?([\w.]+)/i.exec(err.message) ??
+    /relation\s+["'`]?([\w.]+)["'`]?\s+does not exist/i.exec(err.message);
+  if (!match) return err;
+  if (err.message.includes("server/plugins/db.ts")) return err;
+  const statement =
+    typeof sql === "string" ? sql : (sql as { sql?: string })?.sql;
+  err.message =
+    `${err.message}\n` +
+    `  [agent-native] Table "${match[1]}" does not exist. App tables are created by migrations in ` +
+    `server/plugins/db.ts — check that the plugin exists and declares a migration for this table, ` +
+    `then restart the dev server so it runs.` +
+    (statement ? `\n  Statement: ${statement.slice(0, 200)}` : "");
+  return err;
+}
+
 export function getDbExec(): DbExec {
   if (_exec) return _exec;
 
@@ -1608,6 +1637,16 @@ export function getDbExec(): DbExec {
     return sql;
   }
 
+  async function execAnnotated(
+    s: string | { sql: string; args?: unknown[] },
+  ): ReturnType<DbExec["execute"]> {
+    try {
+      return await _exec!.execute(sanitize(s));
+    } catch (err) {
+      throw annotateMissingTable(err, s);
+    }
+  }
+
   // Return a proxy that lazy-inits on first call
   const proxy: DbExec = {
     async execute(sql) {
@@ -1624,7 +1663,7 @@ export function getDbExec(): DbExec {
       }
       // After init, swap to a sanitizing wrapper around the real client
       const wrapper: DbExec = {
-        execute: (s) => _exec!.execute(sanitize(s)),
+        execute: (s) => execAnnotated(s),
         atomicBatch: _exec!.atomicBatch
           ? (statements) =>
               _exec!.atomicBatch!(statements.map((s) => sanitize(s)))
@@ -1640,7 +1679,7 @@ export function getDbExec(): DbExec {
           : undefined,
       };
       Object.assign(proxy, wrapper);
-      return _exec!.execute(sanitize(sql));
+      return execAnnotated(sql);
     },
     async transaction(fn) {
       if (!_initPromise) _initPromise = initClient();
@@ -1652,7 +1691,7 @@ export function getDbExec(): DbExec {
         throw err;
       }
       const wrapper: DbExec = {
-        execute: (s) => _exec!.execute(sanitize(s)),
+        execute: (s) => execAnnotated(s),
         atomicBatch: _exec!.atomicBatch
           ? (statements) =>
               _exec!.atomicBatch!(statements.map((s) => sanitize(s)))

package/src/db/ensure-additive-columns.ts

@@ -132,38 +132,56 @@ async function loadGetTableConfig(): Promise<
 }
 
 /**
- * Live columns already present on `table`, keyed by column name.
- * Postgres: `information_schema.columns` scoped to the table's schema
- * (default `public`). SQLite: `PRAGMA table_info(table)`.
- *
- * Returns `null` when the table itself does not exist (caller no-ops —
- * table creation owns that path) or when introspection fails outright.
+ * Load every requested Postgres table's live columns in one round trip.
+ * Calling information_schema separately for each table adds dozens of
+ * serialized network requests to every serverless cold start.
  */
-async function introspectLiveColumns(
+async function introspectPostgresColumns(
   db: DbExec,
-  table: string,
-  schema: string | undefined,
-): Promise<Set<string> | null> {
-  if (isPostgres()) {
-    try {
-      const tableSchema = schema || "public";
-      const { rows: existsRows } = await db.execute({
-        sql: `SELECT 1 FROM information_schema.tables
-              WHERE table_schema = ? AND table_name = ? LIMIT 1`,
-        args: [tableSchema, table],
-      });
-      if (existsRows.length === 0) return null;
-      const { rows } = await db.execute({
-        sql: `SELECT column_name FROM information_schema.columns
-              WHERE table_schema = ? AND table_name = ?`,
-        args: [tableSchema, table],
-      });
-      return new Set(rows.map((r) => String(r.column_name)));
-    } catch {
-      return null;
+  tables: DeclaredTableLike[],
+): Promise<Map<string, Set<string>> | null> {
+  if (tables.length === 0) return new Map();
+  const pairs = [
+    ...new Map(
+      tables.map((table) => {
+        const schema = table.schema || "public";
+        return [`${schema}.${table.name}`, { schema, table: table.name }];
+      }),
+    ).values(),
+  ];
+  const args: unknown[] = [];
+  const predicates = pairs.map(({ schema, table }) => {
+    args.push(schema, table);
+    return `(table_schema = ? AND table_name = ?)`;
+  });
+  try {
+    const { rows } = await db.execute({
+      sql: `SELECT table_schema, table_name, column_name
+            FROM information_schema.columns
+            WHERE ${predicates.join(" OR ")}`,
+      args,
+    });
+    const columns = new Map<string, Set<string>>();
+    for (const row of rows) {
+      const key = `${String(row.table_schema)}.${String(row.table_name)}`;
+      const tableColumns = columns.get(key) ?? new Set<string>();
+      tableColumns.add(String(row.column_name));
+      columns.set(key, tableColumns);
     }
+    return columns;
+  } catch {
+    return null;
   }
+}
 
+/**
+ * Live SQLite columns already present on `table`, keyed by column name.
+ * Returns `null` when the table does not exist or introspection fails.
+ */
+async function introspectSqliteLiveColumns(
+  db: DbExec,
+  table: string,
+): Promise<Set<string> | null> {
   // SQLite: PRAGMA table_info returns zero rows for a non-existent table
   // (no error), so we can't distinguish "missing table" from "no columns"
   // that way — probe sqlite_master first.
@@ -308,10 +326,13 @@ export async function ensureAdditiveColumns(
     return result;
   }
 
+  const declaredTables: DeclaredTableLike[] = [];
   for (const tableObj of tables) {
-    let config: DeclaredTableLike;
     try {
-      config = getTableConfig(tableObj);
+      const config = getTableConfig(tableObj);
+      if (config.name && PLAIN_IDENTIFIER.test(config.name)) {
+        declaredTables.push(config);
+      }
     } catch (err) {
       // Not a table this dialect's getTableConfig understands (e.g. a stray
       // export that isn't a Drizzle table) — skip quietly rather than
@@ -319,15 +340,21 @@ export async function ensureAdditiveColumns(
       logger.warn(
         `[ensure-additive-columns] skipping non-table export: ${err instanceof Error ? err.message : String(err)}`,
       );
-      continue;
     }
+  }
 
-    const tableName = config.name;
-    if (!tableName || !PLAIN_IDENTIFIER.test(tableName)) continue;
+  const postgresColumns = isPostgres()
+    ? await introspectPostgresColumns(db, declaredTables)
+    : null;
 
+  for (const config of declaredTables) {
+    const tableName = config.name;
     let liveColumns: Set<string> | null;
     try {
-      liveColumns = await introspectLiveColumns(db, tableName, config.schema);
+      liveColumns = isPostgres()
+        ? (postgresColumns?.get(`${config.schema || "public"}.${tableName}`) ??
+          null)
+        : await introspectSqliteLiveColumns(db, tableName);
     } catch (err) {
       result.errors.push({
         column: `${tableName}.*`,

package/src/deploy/build.ts

@@ -1688,7 +1688,7 @@ export function generateCloudflarePagesStaticShellFromManifest(
     ? DEFAULT_ROOT_LOADER_REACT_ROUTER_TURBO_STREAM
     : EMPTY_REACT_ROUTER_TURBO_STREAM;
 
-  return `<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"/><link rel="manifest" href="/manifest.json"/><link rel="icon" type="image/svg+xml" href="/favicon.svg"/>${modulePreloads}${stylesheets}</head><body><div style="display:flex;align-items:center;justify-content:center;height:100vh;width:100%"><svg role="status" aria-label="Loading" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="animation:an-spin 1s linear infinite;opacity:0.7"><path d="M21 12a9 9 0 1 1-6.219-8.56"></path></svg><style>@keyframes an-spin { to { transform: rotate(360deg) } } @media (prefers-color-scheme: dark) { html { background: #09090b; color: #fafafa } }</style></div><script>window.__reactRouterContext = ${JSON.stringify(context)};window.__reactRouterContext.stream = new ReadableStream({start(controller){window.__reactRouterContext.streamController = controller;}}).pipeThrough(new TextEncoderStream());</script><script type="module" async="">${routeModuleScript}</script><!--$--><script>window.__reactRouterContext.streamController.enqueue(${JSON.stringify(encodedInitialState)});</script><!--$--><script>window.__reactRouterContext.streamController.close();</script><!--/$--><!--/$--></body></html>`;
+  return `<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"/><link rel="manifest" href="/manifest.json"/><link rel="icon" type="image/svg+xml" href="/favicon.svg"/>${modulePreloads}${stylesheets}</head><body><div style="display:flex;flex-direction:column;align-items:center;justify-content:center;gap:16px;height:100vh;width:100%"><svg role="status" aria-label="Loading" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="animation:an-spin 1s linear infinite;opacity:0.7"><path d="M21 12a9 9 0 1 1-6.219-8.56"></path></svg><p class="an-stall-hint">Still loading. If this does not finish, reload the page — the browser console may show what failed.</p><style>@keyframes an-spin { to { transform: rotate(360deg) } } @keyframes an-stall-in { to { opacity: 0.6 } } .an-stall-hint { opacity: 0; margin: 0; max-width: 32rem; padding: 0 1.5rem; text-align: center; font-size: 0.875rem; line-height: 1.5; font-family: ui-sans-serif, system-ui, sans-serif; animation: an-stall-in 0.4s ease-out 10s forwards } @media (prefers-reduced-motion: reduce) { .an-stall-hint { animation-duration: 0s } } @media (prefers-color-scheme: dark) { html { background: #09090b; color: #fafafa } }</style></div><script>window.__reactRouterContext = ${JSON.stringify(context)};window.__reactRouterContext.stream = new ReadableStream({start(controller){window.__reactRouterContext.streamController = controller;}}).pipeThrough(new TextEncoderStream());</script><script type="module" async="">${routeModuleScript}</script><!--$--><script>window.__reactRouterContext.streamController.enqueue(${JSON.stringify(encodedInitialState)});</script><!--$--><script>window.__reactRouterContext.streamController.close();</script><!--/$--><!--/$--></body></html>`;
 }
 
 function writeCloudflarePagesStaticShell({
@@ -2343,6 +2343,28 @@ const LIBSQL_NATIVE_PACKAGE_NAMES = [
 const FFMPEG_STATIC_PACKAGE_NAME = "ffmpeg-static";
 const RESVG_SCOPE = "@resvg";
 const RESVG_PACKAGE_PREFIX = "resvg-js";
+
+// Serverless functions only ever run on 64-bit Linux. The darwin/win32/android
+// and 32-bit-arm prebuilds of these native packages are ~100MB that can never
+// execute there, and Netlify copies the whole server dir again for every extra
+// emitted function — so the dead weight is paid once per function. Cold start
+// scales with bundle size, and a page that opens several requests at once
+// scales out to that many cold containers, which is how this surfaces: 502/504
+// on the first burst rather than as an obviously slow deploy.
+const SERVERLESS_NATIVE_PACKAGE_SUFFIXES = [
+  "linux-x64-gnu",
+  "linux-x64-musl",
+  "linux-arm64-gnu",
+  "linux-arm64-musl",
+];
+
+export function isServerlessNativePlatformPackage(
+  packageName: string,
+): boolean {
+  return SERVERLESS_NATIVE_PACKAGE_SUFFIXES.some((suffix) =>
+    packageName.endsWith(suffix),
+  );
+}
 const FFMPEG_STATIC_BINARY_NAMES =
   process.platform === "win32" ? ["ffmpeg.exe", "ffmpeg"] : ["ffmpeg"];
 const SERVERLESS_FFMPEG_STATIC_PLATFORM = "linux";
@@ -3441,6 +3463,7 @@ function copyInstalledLibsqlNativePackages(serverDir: string | undefined) {
   let copied = 0;
 
   for (const packageName of LIBSQL_NATIVE_PACKAGE_NAMES) {
+    if (!isServerlessNativePlatformPackage(packageName)) continue;
     const src = findInstalledLibsqlNativePackage(nodeModulesRoots, packageName);
     if (!src) continue;
 
@@ -3457,7 +3480,13 @@ function copyInstalledLibsqlNativePackages(serverDir: string | undefined) {
 
 function copyInstalledResvgPackages(serverDir: string | undefined) {
   if (!serverDir || !fs.existsSync(serverDir)) return;
-  const packages = findInstalledResvgPackages(nodeModulesAncestors(cwd));
+  // `resvg-js` itself is the JS wrapper that gets imported; everything else in
+  // the scope is a per-platform prebuild.
+  const packages = findInstalledResvgPackages(nodeModulesAncestors(cwd)).filter(
+    ({ packageName }) =>
+      packageName === RESVG_PACKAGE_PREFIX ||
+      isServerlessNativePlatformPackage(packageName),
+  );
   if (packages.length === 0) return;
 
   const destScopeDir = path.join(serverDir, "node_modules", RESVG_SCOPE);

package/src/mcp-client/routes.ts

@@ -367,6 +367,9 @@ async function reconfigureManager(manager: McpClientManager): Promise<void> {
 export function mountMcpServersRoutes(
   nitroApp: any,
   manager: McpClientManager,
+  options: {
+    waitUntilReady?: () => Promise<void>;
+  } = {},
 ): void {
   const mountedApps: WeakSet<object> = ((
     globalThis as any
@@ -375,13 +378,17 @@ export function mountMcpServersRoutes(
   mountedApps.add(nitroApp);
 
   mountMcpOAuthRoutes(nitroApp, {
-    reconfigure: () => reconfigureManager(manager),
+    reconfigure: async () => {
+      await options.waitUntilReady?.();
+      await reconfigureManager(manager);
+    },
   });
 
   try {
     getH3App(nitroApp).use(
       "/_agent-native/mcp/servers",
       defineEventHandler(async (event: H3Event) => {
+        await options.waitUntilReady?.();
         const method = getMethod(event);
         const pathname = (event.url?.pathname || "")
           .replace(/^\/+/, "")
@@ -421,6 +428,7 @@ export function mountMcpServersRoutes(
     getH3App(nitroApp).use(
       "/_agent-native/mcp/builtin",
       defineEventHandler(async (event: H3Event) => {
+        await options.waitUntilReady?.();
         const method = getMethod(event);
         const pathname = (event.url?.pathname || "")
           .replace(/^\/+/, "")
@@ -442,6 +450,7 @@ export function mountMcpServersRoutes(
     getH3App(nitroApp).use(
       "/_agent-native/mcp/apps",
       defineEventHandler(async (event: H3Event) => {
+        await options.waitUntilReady?.();
         const method = getMethod(event);
         const pathname = (event.url?.pathname || "")
           .replace(/^\/+/, "")

package/src/org/app-roles-handlers.ts

@@ -0,0 +1,152 @@
+import {
+  defineEventHandler,
+  getRequestURL,
+  createError,
+  type H3Event,
+} from "h3";
+
+import { getDbExec } from "../db/client.js";
+import { readBody } from "../server/h3-helpers.js";
+import {
+  getRegisteredAppRoles,
+  listAppMemberRoles,
+  setAppMemberRole,
+  type AppRolesDescriptor,
+} from "./app-roles.js";
+import { getOrgContext } from "./context.js";
+import { canManageOrg } from "./permissions.js";
+
+/**
+ * Resolve the descriptor a request is talking about.
+ *
+ * The `appId` arrives from the client but can only ever select among
+ * descriptors the server already declared through `defineAppRoles`; an
+ * unregistered id is a 404, never an implicit new app. That keeps the trusted
+ * vocabulary in app source while still letting one workspace host several apps.
+ */
+function requireDescriptor(appId: string | null): AppRolesDescriptor<string> {
+  if (!appId?.trim()) {
+    throw createError({ statusCode: 400, message: "appId is required" });
+  }
+  const descriptor = getRegisteredAppRoles(appId.trim());
+  if (!descriptor) {
+    throw createError({
+      statusCode: 404,
+      message: `No app roles registered for "${appId}"`,
+    });
+  }
+  return descriptor;
+}
+
+/** Extract the :email tail. The mount prefix is stripped before we see it. */
+function extractMemberEmail(event: H3Event): string | undefined {
+  const path = getRequestURL(event).pathname;
+  const match =
+    path.match(/^\/([^/]+)\/?$/) ?? path.match(/\/app-roles\/([^/]+)\/?$/);
+  return match?.[1] ? decodeURIComponent(match[1]) : undefined;
+}
+
+async function isOrgMember(orgId: string, email: string): Promise<boolean> {
+  const { rows } = await getDbExec().execute({
+    sql: `SELECT 1 FROM org_members WHERE org_id = ? AND LOWER(email) = ? LIMIT 1`,
+    args: [orgId, email.trim().toLowerCase()],
+  });
+  return rows.length > 0;
+}
+
+/**
+ * GET /_agent-native/org/app-roles?appId=X — the app's vocabulary plus every
+ * assignment in the active org, and the caller's own resolved role.
+ */
+export const listAppRolesHandler = defineEventHandler(
+  async (event: H3Event) => {
+    const url = getRequestURL(event);
+    const descriptor = requireDescriptor(url.searchParams.get("appId"));
+    const ctx = await getOrgContext(event);
+
+    const base = {
+      appId: descriptor.appId,
+      roles: descriptor.roles,
+      defaultRole: descriptor.defaultRole ?? null,
+      roleLabels: descriptor.roleLabels ?? {},
+      canManage: canManageOrg(ctx.role),
+    };
+    if (!ctx.orgId) return { ...base, assignments: [], myRole: null };
+
+    const assignments = await listAppMemberRoles(descriptor.appId, ctx.orgId);
+    const mine = assignments.find(
+      (a) => a.email.toLowerCase() === ctx.email.toLowerCase(),
+    );
+    return {
+      ...base,
+      assignments,
+      // The caller's own role, for progressive disclosure only. Every guarded
+      // operation re-resolves this server-side; a client that lies about it gains
+      // nothing but a differently-shaped UI.
+      myRole: mine && descriptor.roles.includes(mine.role) ? mine.role : null,
+    };
+  },
+);
+
+/**
+ * PUT /_agent-native/org/app-roles/:email — assign or clear an app role.
+ * Body: `{ appId, role }`, where `role: null` clears the assignment.
+ *
+ * Org owner/admin only. App roles never confer the right to manage app roles:
+ * that would let an app admin escalate inside a team they cannot otherwise
+ * administer, and it is the org roster this overlay hangs off.
+ */
+export const setAppRoleHandler = defineEventHandler(async (event: H3Event) => {
+  const ctx = await getOrgContext(event);
+  if (!ctx.email) {
+    throw createError({ statusCode: 401, message: "Authentication required" });
+  }
+  if (!ctx.orgId) {
+    throw createError({ statusCode: 400, message: "No active organization" });
+  }
+  if (!canManageOrg(ctx.role)) {
+    throw createError({
+      statusCode: 403,
+      message: "Organization admin role required",
+    });
+  }
+
+  const body = await readBody(event);
+  const descriptor = requireDescriptor(body?.appId ?? null);
+
+  const email = extractMemberEmail(event);
+  if (!email) {
+    throw createError({ statusCode: 400, message: "Member email is required" });
+  }
+
+  const role = body?.role ?? null;
+  if (role !== null && !descriptor.roles.includes(String(role))) {
+    throw createError({
+      statusCode: 400,
+      message: `Unknown ${descriptor.appId} role "${role}"`,
+    });
+  }
+
+  // Assignments hang off membership. Writing one for a non-member would leave a
+  // row that resolves to nothing and reappears if that person is ever invited.
+  if (!(await isOrgMember(ctx.orgId, email))) {
+    throw createError({
+      statusCode: 404,
+      message: "Not a member of this organization",
+    });
+  }
+
+  await setAppMemberRole({
+    appId: descriptor.appId,
+    orgId: ctx.orgId,
+    email,
+    role: role === null ? null : String(role),
+    updatedBy: ctx.email,
+  });
+
+  return {
+    appId: descriptor.appId,
+    email,
+    role: role === null ? null : String(role),
+  };
+});