@kortix/sdk 0.12.7 → 0.13.0

package/dist/react/use-can.js

@@ -0,0 +1,190 @@
+'use client';
+/**
+ * `useCan` / `useCans` — the ONLY client-side authorization read.
+ *
+ * Relocated from `apps/web/src/lib/use-permission.ts` + `use-project-can.ts`.
+ * They were host-local, so every other host (the whitelabel demo, mobile) had
+ * no probe at all and fell back to reading a role literal off a row — which is
+ * exactly the bug the canonical model deletes: a member holding a custom role
+ * that grants `project.members.manage` is invisible to `role === 'manager'`.
+ *
+ * Ask for the LEAF the route asserts (`project.gitops.push`), never for a role.
+ * The engine answers; the client renders the answer.
+ *
+ * NOT a security boundary — the API re-checks every mutating route. This only
+ * decides what to show and enable.
+ *
+ * ### Cache contract
+ *
+ * A verdict is cached for 5 minutes. That is only safe because every
+ * assignment write calls `invalidatePermissionProbes`, so a revoke is visible
+ * on the next render rather than up to five minutes later. If you add a write
+ * path that changes an assignment, it calls that function. No exceptions.
+ */
+import { useQuery } from '@tanstack/react-query';
+import { getProject, probeEffectivePermission, probeEffectivePermissions, validateToken, } from '../core/rest/projects-client/index.js';
+import { contract } from './query-contracts.js';
+import { qk } from './query-keys.js';
+const PROBE_STALE_MS = 5 * 60_000;
+/** The single-probe cache key. Kept as a flat literal (not under `qk`) because
+ *  it predates that factory and both `apps/web` and its tests address it. */
+export const permissionProbeKey = (accountId, userId, action, target) => [
+    'iam-permission',
+    accountId,
+    userId,
+    action,
+    target?.resourceType ?? null,
+    target?.resourceId ?? null,
+];
+/** The batch cache key. Keyed on the probe LIST so adding or removing a probe
+ *  refetches; the signature is action+target per probe, never object identity,
+ *  which React swaps every render. */
+export const permissionProbeBatchKey = (accountId, userId, probes) => [
+    'iam-permission-batch',
+    accountId,
+    userId,
+    probes.map((p) => `${p.action}|${p.resourceType ?? ''}|${p.resourceId ?? ''}`).join(','),
+];
+/** Identity of the calling principal, for hosts that do not inject one. */
+const identityKey = ['iam-identity', 'me'];
+function useProbeUserId(explicit) {
+    const query = useQuery({
+        queryKey: identityKey,
+        queryFn: async () => (await validateToken()).identity ?? null,
+        enabled: !explicit,
+        staleTime: Infinity,
+    });
+    return explicit ?? query.data?.user_id;
+}
+/**
+ * Resolve the account that owns a project. A DISABLED react-query query reports
+ * `isLoading === false` in v5, so callers must not read the unresolved window
+ * as a denial — `pending()` below converts it to "still loading".
+ */
+function useOwningAccountId(projectId, accountIdHint) {
+    const { data } = useQuery({
+        queryKey: qk.project.summary(projectId ?? ''),
+        queryFn: () => getProject(projectId),
+        enabled: !!projectId && !accountIdHint,
+        ...contract('config'),
+    });
+    return projectId ? (accountIdHint ?? data?.account_id) : undefined;
+}
+const pending = () => ({
+    allowed: false,
+    reason: null,
+    isLoading: true,
+    isError: false,
+});
+/** Everything a target resolves to: the account to ask, and the probe target. */
+function useResolvedTarget(target) {
+    const isProject = 'projectId' in target && target.projectId !== undefined;
+    const projectId = 'projectId' in target ? target.projectId : undefined;
+    const owningAccountId = useOwningAccountId(projectId, target.accountId);
+    const accountId = isProject ? owningAccountId : target.accountId;
+    const probeTarget = isProject
+        ? { resourceType: 'project', resourceId: projectId }
+        : target.resource
+            ? { resourceType: target.resource.type, resourceId: target.resource.id }
+            : undefined;
+    return { accountId, probeTarget, resolved: !!accountId && (!isProject || !!projectId) };
+}
+/** Can this principal perform `action` on this target? */
+export function useCan(target, action, options) {
+    const userId = useProbeUserId(options?.userId);
+    const { accountId, probeTarget, resolved } = useResolvedTarget(target);
+    const enabled = resolved && !!userId;
+    const query = useQuery({
+        queryKey: permissionProbeKey(accountId, userId, action, probeTarget),
+        queryFn: () => probeEffectivePermission(accountId, userId, (probeTarget ? { action, ...probeTarget } : { action })),
+        enabled,
+        staleTime: PROBE_STALE_MS,
+    });
+    if (!enabled)
+        return pending();
+    return {
+        allowed: query.data?.allowed === true,
+        reason: query.data?.reason ?? null,
+        isLoading: query.isLoading,
+        isError: query.isError,
+    };
+}
+/**
+ * Batch variant — ONE roundtrip for N actions on the same target. Returns a map
+ * keyed by action, so a caller reads `caps[ACTION].allowed`.
+ *
+ * `actions` must be stable across renders (module-level or memoized): the query
+ * key is derived from the list.
+ */
+export function useCans(target, actions, options) {
+    const userId = useProbeUserId(options?.userId);
+    const { accountId, probeTarget, resolved } = useResolvedTarget(target);
+    const probes = actions.map((action) => (probeTarget ? { action, ...probeTarget } : { action }));
+    const enabled = resolved && !!userId && probes.length > 0;
+    const query = useQuery({
+        queryKey: permissionProbeBatchKey(accountId, userId, probes),
+        queryFn: () => probeEffectivePermissions(accountId, userId, probes),
+        enabled,
+        staleTime: PROBE_STALE_MS,
+    });
+    const map = {};
+    actions.forEach((action, i) => {
+        if (!enabled) {
+            map[action] = pending();
+            return;
+        }
+        const hit = query.data?.[i];
+        map[action] = {
+            allowed: hit?.allowed === true,
+            reason: hit?.reason ?? null,
+            isLoading: query.isLoading,
+            isError: query.isError,
+        };
+    });
+    return map;
+}
+/**
+ * Probe on behalf of ANOTHER member — the "what can this person actually do"
+ * admin panels. Returns one result per input, in order. The caller needs
+ * `member.read` on the account; the server enforces it.
+ *
+ * Kept probe-shaped (not action-shaped like `useCans`) because these panels mix
+ * account and project targets in one request.
+ */
+export function usePermissionsFor(accountId, memberUserId, probes) {
+    const enabled = !!accountId && !!memberUserId && probes.length > 0;
+    const query = useQuery({
+        queryKey: permissionProbeBatchKey(accountId, memberUserId, probes),
+        queryFn: () => probeEffectivePermissions(accountId, memberUserId, probes),
+        enabled,
+        staleTime: PROBE_STALE_MS,
+    });
+    return probes.map((_, i) => {
+        if (!enabled)
+            return pending();
+        const hit = query.data?.[i];
+        return {
+            allowed: hit?.allowed === true,
+            reason: hit?.reason ?? null,
+            isLoading: query.isLoading,
+            isError: query.isError,
+        };
+    });
+}
+/**
+ * Bust the probe cache after an assignment write. **Every** write that creates,
+ * changes or revokes an assignment calls this — a 5-minute stale window on an
+ * authorization verdict is a revoke that has not happened yet.
+ *
+ * Scope it as tightly as you honestly can: an account+user pair when you know
+ * whose access changed, the account when a group or a role definition changed
+ * (that moves verdicts for principals you cannot enumerate client-side), and
+ * everything only when you know nothing.
+ */
+export function invalidatePermissionProbes(queryClient, scope) {
+    const suffix = [scope.accountId, scope.userId].filter((s) => !!s);
+    queryClient.invalidateQueries({ queryKey: ['iam-permission', ...suffix] });
+    queryClient.invalidateQueries({ queryKey: ['iam-permission-batch', ...suffix] });
+    return Promise.resolve();
+}
+//# sourceMappingURL=use-can.js.map

package/dist/react/use-can.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-can.js","sourceRoot":"","sources":["../../src/react/use-can.ts"],"names":[],"mappings":"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"}

package/dist/react/use-canonical-opencode-session.d.ts

@@ -8,7 +8,12 @@ import { type Session } from './use-opencode-sessions/index.js';
  * the client (the old client-side `ensure-opencode` mutation caused the
  * "session replaced / data lost" drift). It just surfaces the pin:
  *   1. the value /start handed us this render (`pinFromStart`), else
- *   2. the persisted pin on the Kortix session row (`getProjectSession`).
+ *   2. the host's own warm-list pin (`initialPin`), else
+ *   3. the persisted row (`getProjectSession`) once its REST read resolves,
+ *      or — before it does — this browser's own synchronous local mirror of
+ *      the last canonical id seen for this session (T6). The local
+ *      mirror exists ONLY to cover the gap before (3)'s network read lands;
+ *      it never outranks it once loaded, and neither ever outranks (1).
  *
  * The OpenCode session list is still read (read-only) for ?oc deep-links and
  * sidebar sub-session rendering.

package/dist/react/use-canonical-opencode-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-canonical-opencode-session.d.ts","sourceRoot":"","sources":["../../src/react/use-canonical-opencode-session.ts"],"names":[],"mappings":"AAGA,OAAO,EAAuB,KAAK,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAG5E;;;;;;;;;;;;;GAaG;AAEH;gFACgF;AAChF,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED,MAAM,WAAW,wBAAwB;IACvC,kFAAkF;IAClF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,yEAAyE;IACzE,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B,GAAG,wBAAwB,CAuC3B"}
+{"version":3,"file":"use-canonical-opencode-session.d.ts","sourceRoot":"","sources":["../../src/react/use-canonical-opencode-session.ts"],"names":[],"mappings":"AAUA,OAAO,EAAuB,KAAK,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAa5E;;;;;;;;;;;;;;;;;;GAkBG;AAEH;gFACgF;AAChF,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED,MAAM,WAAW,wBAAwB;IACvC,kFAAkF;IAClF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,yEAAyE;IACzE,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B,GAAG,wBAAwB,CAqE3B"}

package/dist/react/use-canonical-opencode-session.js

@@ -1,7 +1,17 @@
 'use client';
-import { resolveSessionPin } from './initial-session-pin.js';
+import { useEffect, useLayoutEffect, useState } from 'react';
+import { readPersistedSessionPin, resolvePersistedPin, resolveSessionPin, writePersistedSessionPin, } from './initial-session-pin.js';
 import { useOpenCodeSessions } from './use-opencode-sessions/index.js';
 import { useProjectSession } from './use-project-session.js';
+// SSR-safe: `localStorage` does not exist on the server, and reading it
+// during render (rather than an effect) would make the client's FIRST
+// hydration render disagree with the server-rendered HTML. Mirrors
+// `useSession`'s own `useIsomorphicLayoutEffect` (T5) for the exact
+// same reason — a `useLayoutEffect` commits its state update before the
+// browser paints, so the corrected value is on screen for the user's very
+// first frame instead of trailing one visible "empty" frame behind a plain
+// `useEffect`.
+const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
 /**
  * OpenCode ↔ Kortix session mapping — READ side.
  *
@@ -11,7 +21,12 @@ import { useProjectSession } from './use-project-session.js';
  * the client (the old client-side `ensure-opencode` mutation caused the
  * "session replaced / data lost" drift). It just surfaces the pin:
  *   1. the value /start handed us this render (`pinFromStart`), else
- *   2. the persisted pin on the Kortix session row (`getProjectSession`).
+ *   2. the host's own warm-list pin (`initialPin`), else
+ *   3. the persisted row (`getProjectSession`) once its REST read resolves,
+ *      or — before it does — this browser's own synchronous local mirror of
+ *      the last canonical id seen for this session (T6). The local
+ *      mirror exists ONLY to cover the gap before (3)'s network read lands;
+ *      it never outranks it once loaded, and neither ever outranks (1).
  *
  * The OpenCode session list is still read (read-only) for ?oc deep-links and
  * sidebar sub-session rendering.
@@ -44,12 +59,40 @@ export function useCanonicalOpenCodeSession(params) {
     const projectSessionQuery = useProjectSession(projectId, sessionId, {
         enabled: !pinFromStart && !initialPin,
     });
-    const pin = projectSessionQuery.data?.opencode_session_id ?? null;
+    const networkPin = projectSessionQuery.data?.opencode_session_id ?? null;
+    // T6 — a synchronous local mirror of the persisted pin, so a cold
+    // mount (no /start response yet, no host-warm `initialPin`) can still
+    // resolve `rootSessionId` on frame one instead of waiting out a network
+    // round trip. `useState(null)` matches what a server render sees (no
+    // `localStorage`), so hydration never disagrees with the server-rendered
+    // HTML; the layout effect below then corrects it to the real cached value
+    // before the browser paints — see the module-level comment on
+    // `useIsomorphicLayoutEffect`.
+    const [cachedPin, setCachedPin] = useState(null);
+    useIsomorphicLayoutEffect(() => {
+        setCachedPin(readPersistedSessionPin(projectId, sessionId));
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [projectId, sessionId]);
+    const pin = resolvePersistedPin({ networkPin, cachedPin });
     const rootSessionId = resolveSessionPin({
         startPin: pinFromStart,
         initialPin,
         persistedPin: pin,
     });
+    // Mirror a freshly-resolved canonical id back to disk so the NEXT mount of
+    // this (projectId, sessionId) can paint synchronously via `cachedPin`
+    // above. Scoped to the two AUTHORITATIVE, resolved-this-render sources —
+    // /start and the host's warm session-list pin — never to `pin` itself,
+    // which would just echo `cachedPin` back to its own key on every render
+    // this session is cold. This is also the write half of stale-pin
+    // convergence: a re-pinned session's fresh /start id overwrites whatever
+    // stale id a previous visit left behind, so the session AFTER this one
+    // reads the corrected value instead of the one that just got replaced.
+    const freshPin = pinFromStart ?? initialPin ?? null;
+    useEffect(() => {
+        if (freshPin)
+            writePersistedSessionPin(projectId, sessionId, freshPin);
+    }, [projectId, sessionId, freshPin]);
     return {
         rootSessionId,
         sessions: sessionsQuery.data ?? [],

package/dist/react/use-canonical-opencode-session.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-canonical-opencode-session.js","sourceRoot":"","sources":["../../src/react/use-canonical-opencode-session.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,mBAAmB,EAAgB,MAAM,yBAAyB,CAAC;AAC5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE1D;;;;;;;;;;;;;GAaG;AAEH;gFACgF;AAChF,MAAM,UAAU,wBAAwB;IACtC,WAAW;AACb,CAAC;AAaD,MAAM,UAAU,2BAA2B,CAAC,MAS3C;IACC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,mBAAmB,GAAG,IAAI,EAAE,GAAG,MAAM,CAAC;IAC9F,MAAM,aAAa,GAAG,mBAAmB,CAAC,mBAAmB,CAAC,CAAC;IAE/D,8EAA8E;IAC9E,sEAAsE;IACtE,8EAA8E;IAC9E,gFAAgF;IAChF,gFAAgF;IAChF,kFAAkF;IAClF,4EAA4E;IAC5E,kEAAkE;IAClE,2EAA2E;IAC3E,0EAA0E;IAC1E,2EAA2E;IAC3E,sEAAsE;IACtE,4DAA4D;IAC5D,2EAA2E;IAC3E,yEAAyE;IACzE,wEAAwE;IACxE,yEAAyE;IACzE,MAAM,mBAAmB,GAAG,iBAAiB,CAAC,SAAS,EAAE,SAAS,EAAE;QAClE,OAAO,EAAE,CAAC,YAAY,IAAI,CAAC,UAAU;KACtC,CAAC,CAAC;IACH,MAAM,GAAG,GAAG,mBAAmB,CAAC,IAAI,EAAE,mBAAmB,IAAI,IAAI,CAAC;IAClE,MAAM,aAAa,GAAG,iBAAiB,CAAC;QACtC,QAAQ,EAAE,YAAY;QACtB,UAAU;QACV,YAAY,EAAE,GAAG;KAClB,CAAC,CAAC;IAEH,OAAO;QACL,aAAa;QACb,QAAQ,EAAE,aAAa,CAAC,IAAI,IAAI,EAAE;QAClC,SAAS,EAAE,aAAa,CAAC,SAAS;QAClC,OAAO,EAAE,aAAa,CAAC,OAAO;QAC9B,MAAM,EAAE,aAAa,CAAC,SAAS;QAC/B,KAAK,EAAE,aAAa,CAAC,KAAK,IAAI,IAAI;KACnC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"use-canonical-opencode-session.js","sourceRoot":"","sources":["../../src/react/use-canonical-opencode-session.ts"],"names":[],"mappings":"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"}

package/dist/react/use-impersonation.d.ts

@@ -0,0 +1,54 @@
+import { type ImpersonationSession } from '../core/http/impersonation.js';
+/**
+ * React surface over the act-as store. The data logic (storage, expiry,
+ * header injection) lives in `core/http/impersonation`; these three hooks are
+ * the only React that knows about it, so the host renders a banner and a
+ * button and nothing else.
+ */
+/** Wire path of the mint route. */
+export declare const ADMIN_IMPERSONATE_PATH = "/admin/api/impersonate";
+/** Wire path of the revoke route for one grant. */
+export declare function adminImpersonateRevokePath(grantId: string): string;
+/** Wire path of the caller's live grants. */
+export declare const ADMIN_IMPERSONATE_ACTIVE_PATH = "/admin/api/impersonate/active";
+/** What `POST /admin/api/impersonate` answers. */
+export interface AdminImpersonateResponse {
+    grant_id: string;
+    account_id: string;
+    account_name?: string | null;
+    /** ISO-8601. Server-capped at one hour — the client never chooses it. */
+    expires_at: string;
+}
+/**
+ * The current act-as session, or null. Subscribes to the store, so a banner
+ * built on it disappears by itself when the grant expires or is exited from
+ * another component.
+ */
+export declare function useImpersonation(): ImpersonationSession | null;
+/**
+ * Start acting as an account. On success the session is stored, which makes
+ * every subsequent request from this tab carry the grant header — so the
+ * caller navigates to the app shell and nothing else needs wiring.
+ *
+ * The whole React Query cache is cleared, not invalidated: every cached entry
+ * was fetched as the OPERATOR, and re-serving one inside a customer's session
+ * would show the operator's own data under the customer's banner.
+ */
+export declare function useAdminImpersonate(): import("@tanstack/react-query").UseMutationResult<AdminImpersonateResponse, Error, {
+    accountId: string;
+    reason?: string;
+}, unknown>;
+/**
+ * Stop acting. Revokes server-side FIRST, then clears the local session — in
+ * that order, because a client that forgot the grant id can no longer revoke
+ * it, and the row would stay live for the rest of its hour.
+ *
+ * A failed revoke still clears locally: the operator asked to leave, and the
+ * grant expires on its own. The error is surfaced so the caller can say so.
+ */
+export declare function useStopImpersonation(): import("@tanstack/react-query").UseMutationResult<{
+    ok: boolean;
+} | null, Error, void | {
+    grantId?: string;
+}, unknown>;
+//# sourceMappingURL=use-impersonation.d.ts.map

package/dist/react/use-impersonation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-impersonation.d.ts","sourceRoot":"","sources":["../../src/react/use-impersonation.ts"],"names":[],"mappings":"AAGA,OAAO,EAKL,KAAK,oBAAoB,EAC1B,MAAM,4BAA4B,CAAC;AAEpC;;;;;GAKG;AAEH,mCAAmC;AACnC,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAE/D,mDAAmD;AACnD,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,6CAA6C;AAC7C,eAAO,MAAM,6BAA6B,kCAAqC,CAAC;AAEhF,kDAAkD;AAClD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,oBAAoB,GAAG,IAAI,CAS9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB;eAEgC,MAAM;aAAW,MAAM;YAqBzF;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB;QAET,OAAO;;cAA8B,MAAM;YAgBrE"}

package/dist/react/use-impersonation.js

@@ -0,0 +1,91 @@
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { useSyncExternalStore } from 'react';
+import { backendApi } from '../core/http/api-client.js';
+import { clearImpersonationSession, getImpersonationSession, setImpersonationSession, subscribeToImpersonation, } from '../core/http/impersonation.js';
+/**
+ * React surface over the act-as store. The data logic (storage, expiry,
+ * header injection) lives in `core/http/impersonation`; these three hooks are
+ * the only React that knows about it, so the host renders a banner and a
+ * button and nothing else.
+ */
+/** Wire path of the mint route. */
+export const ADMIN_IMPERSONATE_PATH = '/admin/api/impersonate';
+/** Wire path of the revoke route for one grant. */
+export function adminImpersonateRevokePath(grantId) {
+    return `${ADMIN_IMPERSONATE_PATH}/${encodeURIComponent(grantId)}`;
+}
+/** Wire path of the caller's live grants. */
+export const ADMIN_IMPERSONATE_ACTIVE_PATH = `${ADMIN_IMPERSONATE_PATH}/active`;
+/**
+ * The current act-as session, or null. Subscribes to the store, so a banner
+ * built on it disappears by itself when the grant expires or is exited from
+ * another component.
+ */
+export function useImpersonation() {
+    return useSyncExternalStore(subscribeToImpersonation, getImpersonationSession, 
+    // Server render: never acting as an account. The store is per-tab
+    // `sessionStorage`, which does not exist during SSR, and claiming a session
+    // there would flash a banner for an operator who has none.
+    () => null);
+}
+/**
+ * Start acting as an account. On success the session is stored, which makes
+ * every subsequent request from this tab carry the grant header — so the
+ * caller navigates to the app shell and nothing else needs wiring.
+ *
+ * The whole React Query cache is cleared, not invalidated: every cached entry
+ * was fetched as the OPERATOR, and re-serving one inside a customer's session
+ * would show the operator's own data under the customer's banner.
+ */
+export function useAdminImpersonate() {
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: async ({ accountId, reason }) => {
+            const body = { account_id: accountId };
+            if (reason)
+                body.reason = reason;
+            const response = await backendApi.post(ADMIN_IMPERSONATE_PATH, body);
+            if (response.error)
+                throw new Error(response.error.message);
+            return response.data;
+        },
+        onSuccess: (data) => {
+            setImpersonationSession({
+                grantId: data.grant_id,
+                accountId: data.account_id,
+                accountName: data.account_name ?? null,
+                expiresAt: data.expires_at,
+            });
+            queryClient.clear();
+        },
+    });
+}
+/**
+ * Stop acting. Revokes server-side FIRST, then clears the local session — in
+ * that order, because a client that forgot the grant id can no longer revoke
+ * it, and the row would stay live for the rest of its hour.
+ *
+ * A failed revoke still clears locally: the operator asked to leave, and the
+ * grant expires on its own. The error is surfaced so the caller can say so.
+ */
+export function useStopImpersonation() {
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: async (variables) => {
+            const grantId = variables?.grantId ?? getImpersonationSession()?.grantId;
+            if (!grantId)
+                return null;
+            try {
+                const response = await backendApi.delete(adminImpersonateRevokePath(grantId));
+                if (response.error)
+                    throw new Error(response.error.message);
+                return response.data ?? { ok: true };
+            }
+            finally {
+                clearImpersonationSession();
+                queryClient.clear();
+            }
+        },
+    });
+}
+//# sourceMappingURL=use-impersonation.js.map

package/dist/react/use-impersonation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-impersonation.js","sourceRoot":"","sources":["../../src/react/use-impersonation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB,EACvB,wBAAwB,GAEzB,MAAM,4BAA4B,CAAC;AAEpC;;;;;GAKG;AAEH,mCAAmC;AACnC,MAAM,CAAC,MAAM,sBAAsB,GAAG,wBAAwB,CAAC;AAE/D,mDAAmD;AACnD,MAAM,UAAU,0BAA0B,CAAC,OAAe;IACxD,OAAO,GAAG,sBAAsB,IAAI,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;AACpE,CAAC;AAED,6CAA6C;AAC7C,MAAM,CAAC,MAAM,6BAA6B,GAAG,GAAG,sBAAsB,SAAS,CAAC;AAWhF;;;;GAIG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,oBAAoB,CACzB,wBAAwB,EACxB,uBAAuB;IACvB,kEAAkE;IAClE,4EAA4E;IAC5E,2DAA2D;IAC3D,GAAG,EAAE,CAAC,IAAI,CACX,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB;IACjC,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;IACrC,OAAO,WAAW,CAA0E;QAC1F,UAAU,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE;YAC1C,MAAM,IAAI,GAA4B,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC;YAChE,IAAI,MAAM;gBAAE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;YACjC,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,IAAI,CACpC,sBAAsB,EACtB,IAAI,CACL,CAAC;YACF,IAAI,QAAQ,CAAC,KAAK;gBAAE,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC5D,OAAO,QAAQ,CAAC,IAAK,CAAC;QACxB,CAAC;QACD,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE;YAClB,uBAAuB,CAAC;gBACtB,OAAO,EAAE,IAAI,CAAC,QAAQ;gBACtB,SAAS,EAAE,IAAI,CAAC,UAAU;gBAC1B,WAAW,EAAE,IAAI,CAAC,YAAY,IAAI,IAAI;gBACtC,SAAS,EAAE,IAAI,CAAC,UAAU;aAC3B,CAAC,CAAC;YACH,WAAW,CAAC,KAAK,EAAE,CAAC;QACtB,CAAC;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;IACrC,OAAO,WAAW,CAA6D;QAC7E,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE;YAC9B,MAAM,OAAO,GAAG,SAAS,EAAE,OAAO,IAAI,uBAAuB,EAAE,EAAE,OAAO,CAAC;YACzE,IAAI,CAAC,OAAO;gBAAE,OAAO,IAAI,CAAC;YAC1B,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,MAAM,CACtC,0BAA0B,CAAC,OAAO,CAAC,CACpC,CAAC;gBACF,IAAI,QAAQ,CAAC,KAAK;oBAAE,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAC5D,OAAO,QAAQ,CAAC,IAAI,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;YACvC,CAAC;oBAAS,CAAC;gBACT,yBAAyB,EAAE,CAAC;gBAC5B,WAAW,CAAC,KAAK,EAAE,CAAC;YACtB,CAAC;QACH,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/react/use-opencode-events/handle-event.d.ts

@@ -4,6 +4,8 @@ import type { RefObject } from 'react';
 import { getClient } from '../../core/runtime/client.js';
 import { type SessionSyncReason } from '../../core/session-sync/session-sync-controller.js';
 import type { NormalizeDiagnosticPaths, OpenCodeEvent } from './types.js';
+/** See `createEventHandler`'s `userPartsGraceMs`. */
+export declare const USER_PARTS_GRACE_MS = 1500;
 /** Builds the SSE event handler; all closure dependencies are injected. */
 export declare function createEventHandler(deps: {
     queryClient: QueryClient;
@@ -18,6 +20,14 @@ export declare function createEventHandler(deps: {
     markSessionAbortedLocally: RefObject<(sessionID: string, message?: string) => void>;
     fetchLspDiagnosticsDebounced: RefObject<() => void>;
     reconcileSessionTail?: (sessionID: string, reason: SessionSyncReason) => Promise<void>;
+    /**
+     * How long a USER `message.updated` may sit with no parts before the tail is
+     * re-read. The runtime emits the info frame and the text part separately;
+     * lose the part (a stream reconnect during the boot hand-off) and the
+     * transcript shows an empty bubble until a reload. Injected so tests can
+     * make it immediate.
+     */
+    userPartsGraceMs?: number;
     /** The route-scoped project this SSE connection belongs to — see
      *  `refetchKortixSessionMirrors`'s doc comment for why this can't default
      *  to "every project". Optional only so existing test harnesses that don't

package/dist/react/use-opencode-events/handle-event.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handle-event.d.ts","sourceRoot":"","sources":["../../../src/react/use-opencode-events/handle-event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EACV,KAAK,IAAI,gBAAgB,EACzB,iBAAiB,EACjB,eAAe,EAChB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAUvC,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,iDAAiD,CAAC;AAczD,OAAO,KAAK,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEvE,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;IACrC,cAAc,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAClD,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,aAAa,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAChD,gBAAgB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,WAAW,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAC;IAC5C,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,wBAAwB,EAAE,SAAS,CAAC,wBAAwB,CAAC,CAAC;IAC9D,yBAAyB,EAAE,SAAS,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC,CAAC;IACpF,4BAA4B,EAAE,SAAS,CAAC,MAAM,IAAI,CAAC,CAAC;IACpD,oBAAoB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvF;;;;6DAIyD;IACzD,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,WAoC6B,aAAa,UAsf1C"}
+{"version":3,"file":"handle-event.d.ts","sourceRoot":"","sources":["../../../src/react/use-opencode-events/handle-event.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EACV,KAAK,IAAI,gBAAgB,EACzB,iBAAiB,EACjB,eAAe,EAChB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAWvC,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,iDAAiD,CAAC;AAazD,OAAO,KAAK,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEvE,qDAAqD;AACrD,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AAEzC,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,EAAE,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;IACrC,cAAc,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAClD,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,aAAa,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAChD,gBAAgB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,WAAW,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAC;IAC5C,cAAc,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,wBAAwB,EAAE,SAAS,CAAC,wBAAwB,CAAC,CAAC;IAC9D,yBAAyB,EAAE,SAAS,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC,CAAC;IACpF,4BAA4B,EAAE,SAAS,CAAC,MAAM,IAAI,CAAC,CAAC;IACpD,oBAAoB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvF;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;6DAIyD;IACzD,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,WAqC6B,aAAa,UA0jB1C"}

package/dist/react/use-opencode-events/handle-event.js

@@ -1,16 +1,19 @@
 import { infoToast, notifyPermissionRequest, notifyQuestion, notifySessionError, notifyTaskComplete, } from '../../platform/ui.js';
 import { deleteSessionFromIDB } from '../../browser/cache/idb-sync-cache.js';
 import { useSyncStore } from '../../browser/stores/sync-store.js';
+import { isAbortError } from '../../core/http/abort-error.js';
 import { getClient } from '../../core/runtime/client.js';
 import { SESSION_SYNC_PAGE_SIZE, } from '../../core/session-sync/session-sync-controller.js';
 import { fileContentKeys, fileListKeys, gitStatusKeys } from '../file-keys.js';
 import { ptyKeys } from '../use-opencode-pty.js';
 import { opencodeKeys } from '../use-opencode-sessions/index.js';
 import { applyPartDiagnostics } from './diagnostics.js';
-import { asStringOrUndefined, looksLikeAbortError, patchKortixSessionTitleMirrors, readSessionInfo, realRuntimeTitle, refetchKortixSessionMirrors, scheduleProjectMetadataRefetch, } from './helpers.js';
+import { asStringOrUndefined, patchKortixSessionTitleMirrors, readSessionInfo, realRuntimeTitle, refetchKortixSessionMirrors, scheduleProjectMetadataRefetch, } from './helpers.js';
+/** See `createEventHandler`'s `userPartsGraceMs`. */
+export const USER_PARTS_GRACE_MS = 1_500;
 /** Builds the SSE event handler; all closure dependencies are injected. */
 export function createEventHandler(deps) {
-    const { queryClient, client, applySyncEvent, stopCompaction, addPermission, removePermission, addQuestion, removeQuestion, normalizeDiagnosticPaths, markSessionAbortedLocally, fetchLspDiagnosticsDebounced, projectId = null, } = deps;
+    const { queryClient, client, applySyncEvent, stopCompaction, addPermission, removePermission, addQuestion, removeQuestion, normalizeDiagnosticPaths, markSessionAbortedLocally, fetchLspDiagnosticsDebounced, projectId = null, userPartsGraceMs = USER_PARTS_GRACE_MS, } = deps;
     const reconcileTail = deps.reconcileSessionTail ??
         (async (sessionID) => {
             const result = await client.session.messages({
@@ -43,7 +46,24 @@ export function createEventHandler(deps) {
         applySyncEvent(event);
         switch (event.type) {
             // ---- Message events — handled by sync store only ----
-            case 'message.updated':
+            case 'message.updated': {
+                // A user message is two frames — the info, then its text part. If the
+                // second never lands this tab renders an empty bubble for good; a
+                // tail re-read after a short grace repairs it from the server.
+                const info = event.properties.info;
+                const sessionID = info?.sessionID ?? event.properties.sessionID;
+                if (info?.role === 'user' && info.id && sessionID) {
+                    const messageID = info.id;
+                    setTimeout(() => {
+                        const state = useSyncStore.getState();
+                        const stillListed = state.messages[sessionID]?.some((m) => m.id === messageID);
+                        if (stillListed && !(state.parts[messageID]?.length ?? 0)) {
+                            void reconcileTail(sessionID, 'sse-gap');
+                        }
+                    }, userPartsGraceMs);
+                }
+                break;
+            }
             case 'message.removed':
                 break;
             case 'message.part.updated': {
@@ -62,6 +82,15 @@ export function createEventHandler(deps) {
             case 'session.created': {
                 const info = readSessionInfo(event);
                 if (info) {
+                    // T22 — reload/cross-tab recovery: a `Session.revert` field on the
+                    // info this event carries is the only way a fresh mount (nothing
+                    // staged locally yet, the `.staged` wire event already happened
+                    // before this tab connected) rediscovers an already-staged revert.
+                    // See `sync-store.ts`'s `syncSessionRevertFromInfo` doc comment —
+                    // absence never clears an existing record; only the three
+                    // dedicated wire events (also routed through `applySyncEvent`
+                    // above) do that.
+                    useSyncStore.getState().syncSessionRevertFromInfo(info.id, info.revert ?? null);
                     queryClient.setQueryData(opencodeKeys.sessions(), (old) => {
                         if (!old)
                             return [info];
@@ -85,6 +114,8 @@ export function createEventHandler(deps) {
             case 'session.updated': {
                 const info = readSessionInfo(event);
                 if (info) {
+                    // T22 — see the identical call in the `session.created` case above.
+                    useSyncStore.getState().syncSessionRevertFromInfo(info.id, info.revert ?? null);
                     // OpenCode auto-titles after the first message via session.updated.
                     // Capture the previous title before local cache mutation so we only
                     // force the server-owned mirror read when the title actually changed.
@@ -150,7 +181,21 @@ export function createEventHandler(deps) {
                     const client = getClient();
                     void reconcileTail(sessionID, 'compaction');
                     // Refetch the individual session to clear time.compacting
-                    // (targeted refetch, not full session list invalidation)
+                    // (targeted refetch, not full session list invalidation). This is
+                    // the FAST path — it fires the instant the frame arrives, and on
+                    // success also patches the session list mirror.
+                    //
+                    // It is not the ONLY path any more: a failure here (this fetch has
+                    // no retry of its own) used to leave `time.compacting` stale in the
+                    // `opencodeKeys.runtimeSession` cache FOREVER — `useOpenCodeSession`
+                    // reads it with `staleTime: Infinity` and nothing else refetches it,
+                    // so `projectCompacting`'s server-observed rule (`core/session/
+                    // compaction.ts`) stayed pinned `true` for the rest of the tab's
+                    // life. On failure, route the retry through the SAME query
+                    // `useOpenCodeSession` registers (3 attempts, exponential backoff)
+                    // instead of swallowing it silently. `use-session.ts` also arms a
+                    // `serverCompactionRevalidateAtMs` timer as a second, frame-
+                    // independent backstop — see that function's doc comment.
                     client.session
                         .get({ sessionID })
                         .then((res) => {
@@ -169,8 +214,32 @@ export function createEventHandler(deps) {
                                 return next;
                             });
                         }
+                        else {
+                            void queryClient.invalidateQueries({
+                                queryKey: opencodeKeys.runtimeSession(sessionID),
+                            });
+                        }
                     })
-                        .catch(() => { });
+                        .catch(() => {
+                        void queryClient.invalidateQueries({
+                            queryKey: opencodeKeys.runtimeSession(sessionID),
+                        });
+                    });
+                }
+                break;
+            }
+            // ---- Rewind commit in a view that never saw the staging ----
+            case 'session.next.revert.committed': {
+                // The store's `applyEvent` refuses to guess-delete when this tab has
+                // no tracked revert record (second tab / fresh mount) — guessing a
+                // watermark from the local tip can delete the user's REPLACEMENT
+                // prompt. It raises `sessionRevertNeedsTailReconcile` instead; this
+                // is the one consumer: fetch the server's already-truncated tail so
+                // truth arrives by read, not by guess.
+                const { sessionID } = event.properties;
+                if (sessionID && useSyncStore.getState().sessionRevertNeedsTailReconcile[sessionID]) {
+                    useSyncStore.getState().clearSessionRevertNeedsTailReconcile(sessionID);
+                    void reconcileTail(sessionID, 'manual');
                 }
                 break;
             }
@@ -270,8 +339,8 @@ export function createEventHandler(deps) {
                     // may not have persisted the partial assistant response yet,
                     // so hydrating would wipe the streamed content the user saw.
                     // The error is already patched onto the message above.
-                    const isAbortError = looksLikeAbortError(error);
-                    if (!isAbortError) {
+                    const aborted = isAbortError(error);
+                    if (!aborted) {
                         reconcileTail(sessionID, 'session-error')
                             .then(() => {
                             useSyncStore.getState().clearOptimisticMessages(sessionID);