@agent-native/core 0.127.3 → 0.128.0

package/src/client/DefaultSpinner.tsx

@@ -2,14 +2,23 @@
  * Full-screen loading spinner rendered during SSR and initial hydration.
  * Uses inline SVG + styles because Tailwind may not be loaded yet on the server.
  * Respects the user's OS color scheme so dark-mode users don't get a white flash.
+ *
+ * The stall hint is revealed by a pure-CSS `animation-delay`, never a timer:
+ * the states that strand a user here (hydration never runs, the route module
+ * 404s, a cold dev-server compile) are exactly the states where no JS of ours
+ * executes, so a `setTimeout` fallback would never fire. A featureless spinner
+ * is indistinguishable from a blank screen, and reads as "the app is broken"
+ * rather than "look at the terminal" — that mis-read is what this text buys.
  */
 export function DefaultSpinner() {
   return (
     <div
       style={{
         display: "flex",
+        flexDirection: "column",
         alignItems: "center",
         justifyContent: "center",
+        gap: 16,
         height: "100vh",
         width: "100%",
       }}
@@ -29,8 +38,28 @@ export function DefaultSpinner() {
       >
         <path d="M21 12a9 9 0 1 1-6.219-8.56" />
       </svg>
+      <p className="an-stall-hint">
+        Still loading. A first run compiles dependencies and can take a minute —
+        if it does not finish, check the terminal running the dev server for
+        errors.
+      </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 }
+        }
         html {
           background: hsl(var(--background, 0 0% 100%));
           color: hsl(var(--foreground, 240 10% 3.9%));

package/src/client/org/TeamPage.tsx

@@ -56,6 +56,9 @@ import {
   type ReactNode,
 } from "react";
 
+// Type-only: erased at build time, so declaring app roles pulls no server or
+// database code into the browser bundle.
+import type { AppRolesDescriptor } from "../../org/app-roles.js";
 import type { DomainMatchOrg } from "../../org/types.js";
 import {
   Tooltip,
@@ -82,6 +85,8 @@ import {
   useSetA2ASecret,
   useSyncA2ASecret,
   useJoinByDomain,
+  useAppRoles,
+  useSetAppMemberRole,
   type InviteRole,
   type SyncA2ASecretResult,
 } from "./hooks.js";
@@ -127,6 +132,17 @@ export interface TeamPageProps {
    * tweak page width.
    */
   className?: string;
+  /**
+   * Opt in to an app-role column on the members table, using the same
+   * descriptor the app passes to `defineAppRoles`. Pass it explicitly rather
+   * than letting the page discover registered apps: a workspace can host
+   * several, and a members table that silently grows a column when some
+   * unrelated module registers itself is a surprise, not a feature.
+   *
+   * Only org owners/admins can change assignments; everyone else sees the
+   * column read-only.
+   */
+  appRoles?: AppRolesDescriptor;
 }
 
 function RoleIcon({ role }: { role: string }) {
@@ -383,7 +399,7 @@ interface PendingInviteListItem {
   role: string;
 }
 
-function MembersCard() {
+function MembersCard({ appRoles }: { appRoles?: AppRolesDescriptor }) {
   const t = useT();
   const { data: org } = useOrg();
   const { data: membersData, isLoading: isLoadingMembers } = useOrgMembers();
@@ -457,6 +473,7 @@ function MembersCard() {
         isLoadingMembers={isLoadingMembers}
         currentUserEmail={org.email}
         currentUserRole={org.role ?? null}
+        appRoles={appRoles}
       />
 
       {isOwner && <DangerZoneCard orgName={org.orgName ?? ""} />}
@@ -470,16 +487,26 @@ function MembersTableCard({
   isLoadingMembers,
   currentUserEmail,
   currentUserRole,
+  appRoles,
 }: {
   members: MemberListItem[];
   pendingInvites: PendingInviteListItem[];
   isLoadingMembers: boolean;
   currentUserEmail: string;
   currentUserRole: string | null;
+  appRoles?: AppRolesDescriptor;
 }) {
   const t = useT();
   const [showInviteForm, setShowInviteForm] = useState(false);
   const canInvite = currentUserRole === "owner" || currentUserRole === "admin";
+  const { data: appRoleData } = useAppRoles(appRoles?.appId);
+  const appRoleByEmail = new Map(
+    (appRoleData?.assignments ?? []).map((a) => [
+      a.email.toLowerCase(),
+      a.role,
+    ]),
+  );
+  const columnCount = appRoles ? 5 : 4;
 
   return (
     <section className="rounded-lg border border-border bg-card">
@@ -516,6 +543,9 @@ function MembersTableCard({
           <TableRow>
             <TableHead>{t("org.member")}</TableHead>
             <TableHead>{t("org.role")}</TableHead>
+            {appRoles && (
+              <TableHead>{appRoles.label ?? appRoles.appId}</TableHead>
+            )}
             <TableHead>{t("org.status")}</TableHead>
             <TableHead className="text-end">{t("org.actions")}</TableHead>
           </TableRow>
@@ -524,7 +554,7 @@ function MembersTableCard({
           {isLoadingMembers && members.length === 0 ? (
             [0, 1, 2].map((i) => (
               <TableRow key={i}>
-                <TableCell colSpan={4}>
+                <TableCell colSpan={columnCount}>
                   <div
                     className="h-3.5 rounded bg-muted animate-pulse"
                     style={{ width: `${180 + i * 48}px` }}
@@ -535,7 +565,7 @@ function MembersTableCard({
           ) : members.length === 0 && pendingInvites.length === 0 ? (
             <TableRow>
               <TableCell
-                colSpan={4}
+                colSpan={columnCount}
                 className="py-8 text-center text-sm text-muted-foreground"
               >
                 {t("org.noMembers")}
@@ -550,10 +580,17 @@ function MembersTableCard({
                   role={m.role}
                   isCurrentUser={m.email === currentUserEmail}
                   currentUserRole={currentUserRole}
+                  appRoles={appRoles}
+                  appRole={appRoleByEmail.get(m.email.toLowerCase()) ?? null}
+                  canManageAppRoles={Boolean(appRoleData?.canManage)}
                 />
               ))}
               {pendingInvites.map((inv) => (
-                <PendingInviteRow key={inv.id} invite={inv} />
+                <PendingInviteRow
+                  key={inv.id}
+                  invite={inv}
+                  hasAppRoleColumn={Boolean(appRoles)}
+                />
               ))}
             </>
           )}
@@ -665,7 +702,13 @@ function RoleBadge({ role }: { role: string }) {
   );
 }
 
-function PendingInviteRow({ invite }: { invite: PendingInviteListItem }) {
+function PendingInviteRow({
+  invite,
+  hasAppRoleColumn,
+}: {
+  invite: PendingInviteListItem;
+  hasAppRoleColumn?: boolean;
+}) {
   const t = useT();
   return (
     <TableRow className="opacity-70">
@@ -675,6 +718,13 @@ function PendingInviteRow({ invite }: { invite: PendingInviteListItem }) {
       <TableCell>
         <RoleBadge role={invite.role} />
       </TableCell>
+      {/* App roles hang off membership, so there is nothing to assign until the
+          invitation is accepted. */}
+      {hasAppRoleColumn && (
+        <TableCell>
+          <span className="text-muted-foreground">-</span>
+        </TableCell>
+      )}
       <TableCell>
         <span className="rounded border border-border px-1.5 py-0.5 text-[10px] text-muted-foreground">
           {t("org.invited")}
@@ -685,16 +735,112 @@ function PendingInviteRow({ invite }: { invite: PendingInviteListItem }) {
   );
 }
 
+/** Sentinel for "clear the assignment" — Select cannot carry an empty value. */
+const UNASSIGNED = "__unassigned__";
+
+function AppRoleCell({
+  email,
+  appRoles,
+  appRole,
+  canManage,
+}: {
+  email: string;
+  appRoles: AppRolesDescriptor;
+  appRole: string | null;
+  canManage: boolean;
+}) {
+  const [editing, setEditing] = useState(false);
+  const setAppRole = useSetAppMemberRole(appRoles.appId);
+  const labelFor = (r: string) => appRoles.roleLabels?.[r] ?? r;
+
+  if (editing) {
+    return (
+      <TableCell>
+        <Select
+          defaultOpen
+          value={appRole ?? UNASSIGNED}
+          onOpenChange={(open) => {
+            if (!open) setEditing(false);
+          }}
+          onValueChange={(value) => {
+            const next = value === UNASSIGNED ? null : value;
+            if (next === appRole) {
+              setEditing(false);
+              return;
+            }
+            setAppRole.mutate(
+              { email, role: next },
+              { onSuccess: () => setEditing(false) },
+            );
+          }}
+          disabled={setAppRole.isPending}
+        >
+          <SelectTrigger
+            autoFocus
+            className="h-auto w-auto rounded-md border border-border bg-background px-1.5 py-0.5 text-[11px]"
+          >
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value={UNASSIGNED}>
+              {appRoles.defaultRole ? labelFor(appRoles.defaultRole) : "—"}
+            </SelectItem>
+            {appRoles.roles.map((r) => (
+              <SelectItem key={r} value={r}>
+                {labelFor(r)}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </TableCell>
+    );
+  }
+
+  // An unassigned member shows the app's default only as a hint. The default
+  // never satisfies a server guard, so it must not read as a granted role.
+  const display = appRole ? (
+    <span className="inline-flex items-center rounded border border-border px-2 py-1 text-xs text-muted-foreground">
+      {labelFor(appRole)}
+    </span>
+  ) : (
+    <span className="text-xs text-muted-foreground/70">
+      {appRoles.defaultRole ? labelFor(appRoles.defaultRole) : "—"}
+    </span>
+  );
+
+  return (
+    <TableCell>
+      {canManage ? (
+        <Button
+          type="button"
+          onClick={() => setEditing(true)}
+          className="cursor-pointer rounded hover:opacity-80"
+        >
+          {display}
+        </Button>
+      ) : (
+        display
+      )}
+    </TableCell>
+  );
+}
+
 function MemberRow({
   email,
   role,
   isCurrentUser,
   currentUserRole,
+  appRoles,
+  appRole,
+  canManageAppRoles,
 }: {
   email: string;
   role: string;
   isCurrentUser: boolean;
   currentUserRole: string | null;
+  appRoles?: AppRolesDescriptor;
+  appRole?: string | null;
+  canManageAppRoles?: boolean;
 }) {
   const t = useT();
   const removeMember = useRemoveMember();
@@ -719,6 +865,14 @@ function MemberRow({
       <TableCell>
         <RoleBadge role={role} />
       </TableCell>
+      {appRoles && (
+        <AppRoleCell
+          email={email}
+          appRoles={appRoles}
+          appRole={appRole ?? null}
+          canManage={Boolean(canManageAppRoles)}
+        />
+      )}
       <TableCell>
         {isCurrentUser ? (
           <span className="rounded border border-border px-1.5 py-0.5 text-[10px] text-muted-foreground">
@@ -1620,6 +1774,7 @@ export function TeamPage({
   showTitle = true,
   createOrgDescription,
   className,
+  appRoles,
 }: TeamPageProps) {
   const t = useT();
   const { data: org, isLoading } = useOrg();
@@ -1652,7 +1807,7 @@ export function TeamPage({
           {!org?.orgId ? (
             <CreateOrgCard description={createOrgDescription} />
           ) : (
-            <MembersCard />
+            <MembersCard appRoles={appRoles} />
           )}
         </>
       )}

package/src/client/org/hooks.ts

@@ -318,6 +318,73 @@ export function useSetOrgDomain() {
   });
 }
 
+export interface AppRoleAssignment {
+  email: string;
+  role: string;
+}
+
+export interface AppRolesInfo {
+  appId: string;
+  roles: string[];
+  /** Shown for members with no assignment. Never satisfies a server guard. */
+  defaultRole: string | null;
+  roleLabels: Record<string, string>;
+  /** Whether the current user may change assignments (org owner/admin). */
+  canManage: boolean;
+  assignments: AppRoleAssignment[];
+  myRole: string | null;
+}
+
+/**
+ * App-role vocabulary and assignments for the active org.
+ *
+ * `myRole` and `canManage` are progressive disclosure only — every guarded
+ * operation re-resolves both server-side, so a client that shows the wrong
+ * affordance still cannot perform the operation.
+ */
+export function useAppRoles(appId: string | undefined) {
+  const { data: org } = useOrg();
+  return useQuery<AppRolesInfo>({
+    queryKey: ["org-app-roles", appId ?? null, org?.orgId ?? null],
+    queryFn: () =>
+      apiFetch(`${ORG_BASE}/app-roles?appId=${encodeURIComponent(appId!)}`),
+    enabled: Boolean(appId),
+    staleTime: 30_000,
+  });
+}
+
+/** The current user's role in one app, or `null` when unassigned. */
+export function useAppRole(appId: string | undefined): {
+  role: string | null;
+  isLoading: boolean;
+  error: Error | null;
+} {
+  const query = useAppRoles(appId);
+  return {
+    role: query.data?.myRole ?? null,
+    isLoading: query.isLoading,
+    error: query.error,
+  };
+}
+
+export function useSetAppMemberRole(appId: string) {
+  const qc = useQueryClient();
+  return useMutation<
+    { appId: string; email: string; role: string | null },
+    Error,
+    { email: string; role: string | null }
+  >({
+    mutationFn: ({ email, role }) =>
+      apiFetch(`${ORG_BASE}/app-roles/${encodeURIComponent(email)}`, {
+        method: "PUT",
+        body: JSON.stringify({ appId, role }),
+      }),
+    onSuccess: async () => {
+      await qc.invalidateQueries({ queryKey: ["org-app-roles"] });
+    },
+  });
+}
+
 /**
  * Fetch the org's A2A secret on demand (owner/admin). Deliberately a separate
  * request from `useOrg()` so the secret only reaches the browser when the

package/src/client/org/index.ts

@@ -19,6 +19,9 @@ export {
   useSetA2ASecret,
   useSyncA2ASecret,
   useOrgRole,
+  useAppRoles,
+  useAppRole,
+  useSetAppMemberRole,
 } from "./hooks.js";
 
 export type {
@@ -27,8 +30,14 @@ export type {
   BulkInviteResult,
   SyncA2ASecretResult,
   UseOrgRoleResult,
+  AppRoleAssignment,
+  AppRolesInfo,
 } from "./hooks.js";
 
+// Type-only re-export so templates can annotate the `appRoles` prop without
+// importing the server module.
+export type { AppRolesDescriptor } from "../../org/app-roles.js";
+
 export { OrgSwitcher, type OrgSwitcherProps } from "./OrgSwitcher.js";
 export {
   InvitationBanner,

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)))