portal-mojo 0.2.18 → 0.2.19

package/README.md

@@ -145,3 +145,15 @@ The non-negotiables live in the repo root `PLAN.md` ("Architecture rules") and
 boundary; failure is unmissable; controlled inputs only; models are
 definitions + hooks (TanStack Query owns cache); `ReactNode` slots, never
 trusted-HTML strings; both themes from day one.
+
+### Owner-only AI Assistant setup
+
+The Assistant domain includes a dedicated `/assistant/setup` page (also embedded
+under the Admin mount prefix), protected by the additive literal-superuser
+`AdminRoute.requireSuperuser` / `MenuItem.requireSuperuser` gate. It provides
+explicit key check/save and enablement, with separate advanced Platform key,
+deployed policy/safety, remote access and incident triage sections. Setup secrets
+and actions stay page-local and cache-free. Fresh-auth requires key re-entry,
+and deployment owns the runtime route. See [Admin Assistant](docs/admin-assistant.md)
+for exact schema-2 actions, lifecycle guarantees, mock showcase and verification;
+[Admin credentials](docs/admin-credentials.md) documents the shared core gate.

package/docs/README.md

@@ -41,7 +41,7 @@ everything: run the showcase (`npm run dev:showcase`) → **Develop → Componen
 | [admin-messaging.md](admin-messaging.md) | SES domains/mailboxes/sent/templates plus public contact requests, with write-only credentials and offline HTML previews |
 | [admin-phonehub.md](admin-phonehub.md) | Global Phone Hub: evidence-backed lookup, sanitized SMS audits, and write-only provider configuration |
 | [admin-push.md](admin-push.md) | Global Push admin: caller stats, global metrics, strict audits, templates, and cache-free FCM configuration |
-| [admin-assistant.md](admin-assistant.md) | Global Assistant streaming selection/reconciliation, strict projectors/blocks, context reuse, skills, and explicit tiered memory |
+| [admin-assistant.md](admin-assistant.md) | Owner-only AI Assistant Setup, credential/safety/remote controls and global Assistant streaming selection/reconciliation, strict projectors/blocks, context reuse, skills, and explicit tiered memory |
 | [ModelTable.md](ModelTable.md) | The server-driven table: columns, filters, selection/batch, chooser, persist, autoRefresh, expand, groupBy, export, skeleton |
 | [forms.md](forms.md) | The `Field` language, `SchemaForm`, `formModal`, `FormView` inline autosave + showWhen + tabsets |
 | [tabs-and-form-wizard.md](tabs-and-form-wizard.md) | Accessible Tabs variants and shared-state FormWizard, async finish, reset/roster semantics, modal helper |

package/docs/admin-assistant.md

@@ -2,7 +2,158 @@
 
 Import from `portal-mojo/admin`.
 
-`ASSISTANT_ADMIN_SECTION` registers Conversations, Skills, and Memory beneath the Assistant navigation group. Its section clause is global-only ANY-of `sys.view_admin` or `sys.assistant`; Memory narrows its route to `sys.assistant`, matching the backend. Active-group grants never reveal it. `AssistantLauncher` uses the section gate. `AssistantContextLauncher` additionally requires `sys.view_security` or `sys.security` and only accepts `incident.Incident` or `incident.Ticket`.
+`ASSISTANT_ADMIN_SECTION` registers Setup, Conversations, Skills, and Memory beneath the Assistant navigation group. Its section clause is global-only ANY-of `sys.view_admin` or `sys.assistant`; Memory narrows its route to `sys.assistant`, matching the backend. Active-group grants never reveal it. `AssistantLauncher` uses the section gate. `AssistantContextLauncher` additionally requires `sys.view_security` or `sys.security` and only accepts `incident.Incident` or `incident.Ticket`.
+
+## AI Assistant setup
+
+`AssistantSetupPage` is a dedicated global owner page at `/assistant/setup`, or
+`/system/assistant/setup` when the Admin helpers receive `mount: '/system'`.
+The literal `me.is_superuser === true` requirement applies before lazy loading,
+in grouped and ordinary menu entries, landing selection, direct component
+mounting and every action. Permission-driven `admin`, `manage_settings`,
+Assistant permissions and member/group grants cannot satisfy it. The server
+also rejects confined ApiKey/GroupScopedToken sessions and enforces person
+ownership; the client does not invent a broader per-user-key ban.
+
+The basic section shows deployment readiness, exact provider/model/key
+selection, Automatic — latest Sonnet or an explicit manual pin, credential source and optional server hint, blank replacement input,
+Check and save key, Check current key and enable/disable. A configured key and
+an enabled switch do not prove readiness. `route.ready` describes configuration,
+not current provider health. Unknown routes remain unknown: a missing
+credential can cause the backend to omit the entire route. Only an explicit
+`handler` route points to the Platform credential section. Bedrock uses AWS
+identity from deployment. Assistant, Platform and AWS credentials never
+substitute for one another. Missing Assistant/realtime applications are also
+reported. Runtime model identifiers preserve provider punctuation, including
+Bedrock colons; only a manual pin uses the backend's restricted pin syntax.
+
+Advanced native details separate Platform credentials, deployed policy/safety,
+remote access/connections and incident triage. Policy activation acknowledges
+the deployed policy on this node, does not edit it and never establishes
+fleet-wide agreement. Static, database and effective emergency stops are
+separate; only the database switch is writable. Activation and breaker reset
+cannot release a stop.
+
+Model selection controls the protected runtime selection only when the backend
+returns a valid capability for the explicit Anthropic `auto:sonnet` policy.
+Fixed Anthropic policies, Bedrock and unavailable policies remain read-only.
+A deployment pin permits an owner manual override, but Automatic remains
+unavailable until deployment removes that pin. Mode is authoritative even when
+a fixed route retains an inert legacy `selected` value.
+
+The exact resolved runtime identifier (`model.effective`) and source are
+separate from the selection draft and `route.ready`. Advanced → Deployed policy
+and safety contains the raw policy model and admission diagnostic. The additive
+`route.can_invoke` reports admission to the guarded request path: a cold
+automatic catalogue can admit a request while configuration readiness remains
+false. It does not prove that a usable model or healthy provider is ready.
+
+Refresh catalogue is an explicit backend request; only the backend contacts the
+provider. The browser never decides which model is newest. A refresh announces
+success only for `model.refresh.ok === true`, including when a manual pin
+remains selected. Failed/throttled/in-flight attempts may retain a fresh or
+stale cached resolution; the page reports its exact freshness, last successful
+fetch and attempt without claiming a newer model. Passive reads neither refresh
+the catalogue nor repeat the preceding explicit refresh outcome.
+
+Check public discovery explicitly probes this installation's public address
+(server cache: 60 seconds). Ordinary page reads trigger neither probe.
+
+Both credential drafts and all setup operations stay imperative and page-local.
+There is no autosave, model definition, Query/Mutation entry, browser
+persistence, export, URL value or secret-bearing mock history. The backend
+checks a replacement before encrypted storage; a candidate-only verification
+never updates the stored-key check record. Successful credential saves and
+clears empty the relevant draft. Clearing protected storage may reveal a
+deployment fallback, so the returned source remains authoritative. Fixed
+backend pre-write rejection/unreachable messages map to safe actionable copy;
+unknown failures refresh authoritative state and report an uncertain outcome
+without replaying the operation.
+
+One operation/confirmation lock, AbortSignal and live owner/session guard cover
+loads, confirmations, auth waits and late responses. Leaving the page,
+revocation, logout or explicit session replacement discards drafts and pending
+work. Ordinary same-tab token renewal preserves a draft. Cross-tab auth-storage
+changes conservatively discard it: the shared auth API cannot distinguish
+renewal from same-person replacement across tabs. A 440 uses the existing
+fresh-auth UI after clearing credential drafts; even successful reauthentication
+requires explicit re-entry/retry. No secret is silently replayed. Confirmation
+is page-local, focuses Cancel, and ends with the page/session scope.
+
+Protocol helpers are exported from `portal-mojo/admin/assistant`:
+`getAssistantSetup(options, probe?)`, `mutateAssistantSetup(action, options)`,
+`assistantSetupSave(state, changes)`, `projectAssistantSetup`,
+`assistantSetupReadiness`, and `assistantSetupCredentialRefusal`. Options accept
+`signal` and a `beforeSend` validity guard; mutation helpers enforce same-origin
+before and after auth preflight and use the existing `mojoCall` envelope boundary.
+`schema_version: 2` responses are positively projected with bounds of 200
+model choices/connections/request aggregates and 100 breaker rows. Runtime IDs
+preserve provider punctuation; only manual pins use the backend's restricted
+81-character lowercase alphanumeric/dot/hyphen syntax.
+
+The additive wire fields live directly under `model`: `mode` (`auto`, `pinned`,
+`fixed`), `editable`, `policy_model`, `restriction` (empty, `fixed_policy`,
+`provider_unsupported`, `deployment_pin`, `policy_unavailable`), `discovery`
+(`status`: `fresh`, `stale`, `unavailable`, `not_applicable`; nullable ISO
+`fetched_at`, `attempted_at`, `expires_at`, `max_stale_at`; safe `error_code`),
+and `refresh` (`attempted`, nullable boolean `ok`, safe `code`). The client
+positively projects the complete valid set into optional `model.capability`.
+Absent, malformed or unknown capabilities keep runtime facts visible, with
+upgrade/read-only copy and no enabled selection action. No latest ID ships in
+the production UI; returned bounded choices supply the datalist.
+
+| Request | Exact body / query |
+|---|---|
+| Passive GET `/api/account/admin/assistant` | No probe parameters |
+| Explicit catalogue / discovery GET | `refresh=models` / `check=discovery` |
+| Save POST | `{action:'save',enabled:boolean,model?:string}` plus only intended optional `api_key`, `clear_api_key`, `handler_api_key`, `clear_handler_api_key`, `mcp_enabled`, `emergency_stop`, `autonomous_triage` |
+| Model selection POST | Exactly `{action:'set_model_selection',mode:'auto'}` (no `model`) or `{action:'set_model_selection',mode:'pinned',model:ID}`; `saved:boolean` |
+| Verify POST | `{action:'verify',target:'assistant'|'handler',api_key?}`; omitted candidate checks that exact stored credential |
+| Policy POST | Exactly `{action:'activate_policy'}`; `activated:boolean` |
+| Breaker POST | `{action:'reset_breaker',provider?:'anthropic'|'bedrock'}`; `reset:number` |
+| Historical triage POST | Exactly `{action:'historical_triage',before:ISO,limit:1..100}`; `queued:number` |
+| Disconnect POST | Exactly `{action:'revoke_grant',grant_id:positiveInteger}` or `{action:'revoke_all_grants'}`; `revoked:number` |
+
+Every mutation returns fresh `state` plus the action result. Verification may
+return `result.ok:false` in a successful envelope; that remains a failed check.
+Save always sends authoritative `enabled`. With a valid capability it omits
+`model` and cannot reset runtime selection; only the dedicated selection action
+can change it. Capability-absent older schema-2 servers retain the required
+`enabled`/legacy `model` baseline because they write both even when omitted.
+On delegated `auto:sonnet` routes, new servers reject a differing legacy model
+echo, preventing stale clients from reverting the active choice. Fixed policies,
+Bedrock and unavailable-policy routes retain an inert legacy writer; these
+values cannot change their deployed runtime model. Model actions carry no
+enabled/key/stop/MCP/triage fields, and all selection drafts reset from each
+authoritative response. Optional section switches are not
+echoed during unrelated saves, and effective stop is never used as the database
+stop. Replacement and clear are separate operations. The server retains its
+600-second fresh-auth, protected settings, auditing and same-origin checks;
+generic Settings still cannot write the Assistant-owned protected keys.
+
+Remote access off pauses existing grants without revoking them. The connection
+count remains the full server count when rows are capped at 200. Tools, Full API
+and combined grants are labeled separately; Full API carries the signed-in
+user's API authority. Disconnect all spans both resource paths for every user.
+Returned addresses are inert text/read-only select-to-copy inputs. Triage
+activation establishes the no-history watermark; historical processing requires
+an explicit cutoff, bounded limit and confirmation.
+
+The mock-only Assistant showcase adds Setup with explicit fake owner/denied
+permission-admin buttons, a one-shot fresh-auth challenge button, and ready, missing policy/key, handler, Bedrock, static
+stop, rejected key, discovery failure, bounded-grants and deployment-fallback
+scenarios. Model scenarios include manual pins, fixed policy, deployment pin
+(including an owner override), fresh/stale refresh failure, unavailable
+resolution, throttled/in-flight refresh, old-server capability absence and
+malformed capability. `fixture-sonnet-2099-01` and `fixture-sonnet-2099-02` are
+visibly fake future IDs; explicit catalogue refresh advances the fake catalogue,
+preserves manual pins, and returning to Automatic adopts the successor. Seeded `assistant.owner@nativemojo.com` is a literal superuser;
+`assistant.wildcard@nativemojo.com` has permission-driven admin only. Both use
+fake password `mojo`. No real credentials or deployment changes belong in demos.
+`verify:admin-assistant-setup` covers wire contracts, owner navigation/admission,
+projections and mounted auth/draft/confirmation/fresh-auth/transport/cache
+lifecycle; it is wired into `verify:release`. Browser checks separately establish
+both-theme layout, native details, keyboard controls and console behavior.
 
 ## Conversation transport
 

package/docs/admin-credentials.md

@@ -26,6 +26,17 @@ use `basePath: ''`; its labeled routes become visible child links rather than
 claiming `/`. Prefixed sections receive an index redirect to the first route
 the current operator can see.
 
+## Literal-owner routes
+
+`AdminRoute.requireSuperuser?: boolean` is an additive opt-in gate. It requires
+literal `me.is_superuser === true` before a lazy page can load and during
+section/mount landing selection. `adminSectionsMenu` carries it into grouped
+and ordinary `MenuItem.requireSuperuser` entries. Permission-driven admin and
+group grants never satisfy it; existing permission semantics remain unchanged.
+Built-in Assistant Setup uses this gate and additionally checks live ownership
+and session lifetime within the component/actions. Toolkit consumers can opt
+into the same route/menu guard without changing other routes.
+
 ## Group API keys
 
 ```tsx

package/docs/admin-identity-users.md

@@ -62,6 +62,16 @@ per endpoint, so `UserDetail` and the fleet-wide tables share one cache.
 
 ## Action contracts
 
+- **Set temporary password** is available in the user header menu and Security
+  section with `sys.users | sys.manage_users`. Confirmation identifies the user
+  and explains that their password is replaced and all sessions are revoked.
+  `POST /api/account/admin/user/password/temporary` sends only `{user: id}`
+  through `withFreshAuth` (440 prompts and retries once). The generated password
+  appears once in a copyable dialog; closing or losing permission removes it.
+  It never enters Query/Mutation cache, storage, or a toast. The server requires
+  a person session, restricts superuser recovery to superusers, and forces the
+  recipient to replace the password before completing sign-in. This uses the
+  existing django-mojo endpoint; no backend upgrade or new permission is added.
 - Username changes use the `change_username` POST_SAVE_ACTION, not a direct
   field save. Model saves/actions retry one fresh-auth 440 automatically;
   combined `disable_totp` writes explicitly use `withFreshAuth`.

package/docs/grouping-and-fmt.md

@@ -45,7 +45,7 @@ the type checker and was the source's silent-failure vector) and the
 
 | Fn | Notes |
 |---|---|
-| `fmt.date(v, fallback='—')` / `fmt.datetime(v, fallback='—')` | `MM/DD/YYYY` / `Mon D, YYYY h:mm` — accepts **epoch seconds** (the django-mojo wire shape), ms, ISO, Date |
+| `fmt.date(v, fallback='—')` / `fmt.datetime(v, fallback='—')` | `MM/DD/YYYY` / `Mon D, YYYY h:mm` — accepts **epoch seconds** (the django-mojo wire shape), ms, ISO, Date. A **date-only** value (`'YYYY-MM-DD'`, `'YYYY-MM'`, `'YYYY'`) shows its own calendar day at its own precision in every browser zone, with no time: `10/17/2026` / `Oct 17, 2026`, `10/2026` / `Oct 2026`, `2026` / `2026`; `groupByDay`/`groupByRecency` bucket it under that same day |
 | `fmt.relative(v, fallback='Never')` | "3 weeks ago" style |
 | `fmt.relativeShort(v, fallback='—')` | compact age for chips: `now` / `5h` / `3d` / `3w` / `2mo` / `1y`. **Magnitude only** — a future date reads the same as a past one (use `relative` when direction matters). Source boundaries kept (`>`, not `>=`): 7d is `7d`, 8d is `1w` |
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "portal-mojo",
-    "version": "0.2.18",
+    "version": "0.2.19",
     "description": "React portal toolkit for django-mojo — typed client + params store, mission-control UI, dependency-free SVG charts, admin section bundles.",
     "type": "module",
     "license": "Apache-2.0",

package/src/account/PasskeyList.tsx

@@ -34,7 +34,7 @@ export function shortDate(epochSeconds: number | null | undefined): string {
 }
 
 function passkeyIcon(row: PasskeyRow): string {
-    const transports = (row.transports ?? '').split(',');
+    const transports = Array.isArray(row.transports) ? row.transports : [];
     if (transports.includes('usb') || transports.includes('nfc')) return 'bi-usb-drive';
     const name = (row.friendly_name ?? '').toLowerCase();
     if (/iphone|android|phone/.test(name)) return 'bi-phone';

package/src/account/credential-models.ts

@@ -20,7 +20,8 @@ export interface PasskeyRow {
     rp_id: string;
     is_enabled: boolean;
     sign_count: number;
-    transports: string | null;
+    /** WebAuthn transport hints as django-mojo stores them: a JSON list, `[]` when none. */
+    transports: string[];
     aaguid: string | null;
     last_used: number | null;
     created: number;

package/src/admin/assistant/AssistantSetupPage.tsx

@@ -0,0 +1,196 @@
+import { useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { useAuthSnapshot, useMe, type Me } from '../../client/me';
+import { getAuthSessionRevision, getAuthSnapshot, isReauthRequired, requestFreshAuth, subscribeAuth } from '../../client/auth';
+import {
+    assistantSetupCredentialRefusal, assistantSetupReadiness, assistantSetupSave, getAssistantSetup, mutateAssistantSetup,
+    type AssistantSetupState, type SetupAction, type SetupKey, type SetupCheck, type SetupTarget,
+} from './setup';
+
+type Operation = { controller: AbortController; revision: number };
+/** Also gates direct component consumers, independently of navigation and lazy-route admission. */
+export function AssistantSetupPage() {
+    const { data: me } = useMe();
+    const auth = useAuthSnapshot();
+    const revision = useSyncExternalStore(subscribeAuth, getAuthSessionRevision, getAuthSessionRevision);
+    if (!auth.authenticated || me?.is_superuser !== true || String(me.id) !== auth.uid) return <div className="panel panel-pad" role="alert"><h2>Owner access required</h2><p>Assistant setup requires a literal installation superuser signed in as a person.</p></div>;
+    return <OwnerSetup key={`${auth.uid}:${revision}`} ownerId={me.id} revision={revision} />;
+}
+function KeySummary({ label, value, check }: { label: string; value: SetupKey; check: SetupCheck }) {
+    return <div className="assistant-setup-key-status"><p><strong>{label} source:</strong> {value.source === 'admin' ? 'Protected Admin storage' : value.source === 'deployment' ? 'Deployment configuration' : 'Not configured'}{value.hint && <span> · server hint: <code>{value.hint}</code></span>}</p><p className="dim">Last stored-key check: {check.ok === null ? 'Not checked' : check.ok ? 'Accepted' : 'Failed'}{check.at && ` · ${check.at}`} · {check.message}</p></div>;
+}
+function OwnerSetup({ ownerId, revision }: { ownerId: number; revision: number }) {
+    const queryClient = useQueryClient();
+    const [state, setState] = useState<AssistantSetupState | null>(null);
+    const stateRef = useRef(state); stateRef.current = state;
+    const [draft, setDraft] = useState(''); const [handlerDraft, setHandlerDraft] = useState('');
+    const [modelDraft, setModelDraft] = useState('');
+    const [modeDraft, setModeDraft] = useState<'auto' | 'pinned' | ''>('');
+    const [before, setBefore] = useState(''); const [limit, setLimit] = useState('25');
+    const [pending, setPending] = useState(''); const [notice, setNotice] = useState(''); const [error, setError] = useState('');
+    const [confirmation, setConfirmation] = useState<{ message: string; accept: () => void; cancel: () => void } | null>(null);
+    const live = useRef(false); const operation = useRef<Operation | null>(null);
+    const platform = useRef<HTMLDetailsElement>(null); const platformTitle = useRef<HTMLElement>(null);
+    const validOwner = () => {
+        const auth = getAuthSnapshot();
+        const me = queryClient.getQueryData<Me>(['me', auth.uid]);
+        return live.current && getAuthSessionRevision() === revision && auth.authenticated && auth.uid === String(ownerId) && me?.id === ownerId && me.is_superuser === true;
+    };
+    const clearDrafts = () => { setDraft(''); setHandlerDraft(''); setBefore(''); setLimit('25'); setModelDraft(''); setModeDraft(''); };
+    const dispose = () => {
+        operation.current?.controller.abort(); operation.current = null;
+        clearDrafts(); setConfirmation(null); setPending(''); setState(null); stateRef.current = null; setNotice(''); setError('');
+    };
+    const guard = (op: Operation) => {
+        if (!validOwner() || operation.current !== op || op.controller.signal.aborted) throw new DOMException('Setup scope ended', 'AbortError');
+    };
+    const options = (op: Operation) => ({ signal: op.controller.signal, beforeSend: () => guard(op) });
+    const apply = (next: AssistantSetupState, op: Operation) => { guard(op); stateRef.current = next; setState(next); setModelDraft(next.model.capability?.mode === 'pinned' ? next.model.selected : ''); setModeDraft(next.model.capability?.mode === 'auto' || next.model.capability?.mode === 'pinned' ? next.model.capability.mode : ''); };
+    const begin = (label: string): Operation | null => {
+        if (!validOwner() || operation.current) return null;
+        const op = { controller: new AbortController(), revision }; operation.current = op; setPending(label); setNotice(''); setError(''); return op;
+    };
+    const finish = (op: Operation) => { if (operation.current === op) { operation.current = null; setPending(''); setConfirmation(null); } };
+    async function failure(err: unknown, op: Operation, mutation: boolean) {
+        if (!validOwner() || operation.current !== op || op.controller.signal.aborted) return;
+        if (isReauthRequired(err)) {
+            clearDrafts(); setConfirmation(null); setNotice('Sign in again, then re-enter any key and explicitly retry. Nothing is automatically replayed.');
+            // Step-up replaces the session. Never close over a secret for retry.
+            await requestFreshAuth(); return;
+        }
+        setError(assistantSetupCredentialRefusal(err) ?? (mutation ? 'The operation was refused or its outcome is unknown. Refreshing current configuration; no operation will be retried automatically.' : 'Assistant setup could not be loaded. Try Refresh setup.'));
+        if (mutation) {
+            try { apply(await getAssistantSetup(options(op)), op); }
+            catch { if (validOwner() && operation.current === op) { setState(null); stateRef.current = null; } }
+        }
+    }
+    async function load(probe?: 'models' | 'discovery') {
+        const op = begin(probe ? 'Checking…' : 'Loading setup…'); if (!op) return;
+        try {
+            const next = await getAssistantSetup(options(op), probe); apply(next, op);
+            if (probe === 'models') {
+                guard(op);
+                const refresh = next.model.capability?.refresh;
+                if (refresh?.ok === true) setNotice('Provider catalogue refreshed. Review the resolved runtime model below.');
+                else setError(refresh?.code === 'refresh_in_progress' ? 'A catalogue refresh is already in progress. Returned configuration is unchanged; try again later.' : refresh?.code === 'refresh_throttled' ? 'Catalogue refresh is temporarily limited. Returned configuration is unchanged; try again later.' : 'Provider catalogue refresh was not confirmed. Any returned cached model keeps its reported freshness; no newer model is confirmed.');
+            } else if (probe === 'discovery') { guard(op); setNotice('Discovery check completed. Review its verdict below.'); }
+        }
+        catch (err) { await failure(err, op, false); } finally { finish(op); }
+    }
+    function change(make: (current: AssistantSetupState) => SetupAction, label: string, confirm?: string, credential?: SetupTarget) {
+        if (!stateRef.current) return;
+        const op = begin(label); if (!op) return;
+        const run = async () => {
+            let action: SetupAction | null = null;
+            try {
+                guard(op); setConfirmation(null);
+                if (!stateRef.current) throw new Error('Reload setup.');
+                action = make(stateRef.current);
+                const result = await mutateAssistantSetup(action, options(op));
+                guard(op); apply(result.state, op);
+                if (credential === 'assistant') setDraft(''); if (credential === 'handler') setHandlerDraft('');
+                if (result.result) {
+                    if (result.result.ok === true) setNotice(result.result.message);
+                    else setError(result.result.message || 'The credential check failed.');
+                } else setNotice(result.queued !== undefined ? `Historical triage queued: ${result.queued}.` : result.revoked !== undefined ? `Connections disconnected: ${result.revoked}.` : result.reset !== undefined ? `Breakers reset: ${result.reset}. Emergency stops are unchanged.` : label === 'Activating policy…' ? 'Deployed policy acknowledged on this node. Fleet-wide agreement has not been established.' : 'Configuration saved.');
+            } catch (err) {
+                // Drop request-local candidate references before showing any fresh-auth UI.
+                if (action && 'api_key' in action) delete action.api_key;
+                if (action && 'handler_api_key' in action) delete action.handler_api_key;
+                action = null;
+                await failure(err, op, true);
+            } finally {
+                if (action && 'api_key' in action) delete action.api_key;
+                if (action && 'handler_api_key' in action) delete action.handler_api_key;
+                finish(op);
+            }
+        };
+        if (confirm) setConfirmation({ message: confirm, accept: () => { void run(); }, cancel: () => finish(op) });
+        else void run();
+    }
+    useEffect(() => {
+        live.current = true;
+        const revoke = () => { if (!validOwner()) dispose(); };
+        const offAuth = subscribeAuth(revoke); const offQuery = queryClient.getQueryCache().subscribe(revoke);
+        void load();
+        return () => { live.current = false; operation.current?.controller.abort(); operation.current = null; offAuth(); offQuery(); };
+    // The keyed boundary owns identity/revision. Ordinary token renewal preserves this instance.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const locked = pending !== '';
+    const capability = state?.model.capability;
+    const modelEditable = capability?.editable === true && capability.policy_model === 'auto:sonnet' && capability.mode !== 'fixed' && (capability.restriction === '' || capability.restriction === 'deployment_pin');
+    const autoAvailable = modelEditable && capability?.restriction !== 'deployment_pin';
+    const restriction = !capability ? 'Runtime model selection is unavailable on this server. Upgrade the backend to select Automatic or a manual pin.'
+        : capability.restriction === 'fixed_policy' ? 'The deployed policy fixes the model. Model selection is read-only.'
+        : capability.restriction === 'provider_unsupported' ? 'This provider uses a deployment-owned model. Automatic Sonnet and manual selection are unavailable.'
+        : capability.restriction === 'policy_unavailable' ? 'The deployed model policy is unavailable. Model selection is read-only.'
+        : capability.restriction === 'deployment_pin' ? 'A deployment pin is active beneath owner overrides. You may save a manual pin; remove the deployment pin before choosing Automatic.'
+        : !modelEditable ? 'Runtime model selection is read-only for this deployment.' : '';
+
+    const saveKey = (target: SetupTarget) => change((current) => assistantSetupSave(current, target === 'assistant' ? { api_key: draft } : { handler_api_key: handlerDraft }), 'Checking and saving key…', undefined, target);
+    const clearKey = (target: SetupTarget) => change((current) => assistantSetupSave(current, target === 'assistant' ? { clear_api_key: true } : { clear_handler_api_key: true }), 'Clearing protected key…', 'Clear the protected Admin credential? A deployment credential may become active. Review the returned source after saving.', target);
+    const openPlatform = () => { if (platform.current) platform.current.open = true; platformTitle.current?.focus(); };
+    return <main className="assistant-setup" aria-labelledby="assistant-setup-title">
+        <header className="assistant-setup-header"><div><div className="eyebrow">Installation owner</div><h1 id="assistant-setup-title">AI Assistant setup</h1><p className="dim">Set up your AI Assistant and review the controls that keep it safe.</p></div><button type="button" className="btn" disabled={locked} onClick={() => void load()}>Refresh setup</button></header>
+        <div role="status" aria-live="polite">{notice || (pending && !confirmation ? pending : '')}</div>
+        {error && <div className="assistant-setup-warning" role="alert">{error}</div>}
+        {confirmation && <section className="panel panel-pad assistant-setup-confirm" role="group" aria-label="Confirm setup operation"><p>{confirmation.message}</p><div className="assistant-action-row"><button className="btn" type="button" autoFocus onClick={confirmation.cancel}>Cancel</button><button className="btn btn-primary" type="button" onClick={confirmation.accept}>Confirm operation</button></div></section>}
+        {state && <>
+            <section className="panel panel-pad"><div className="eyebrow">Basic setup</div><h2>{state.enabled && state.route.ready && !state.emergency_stop && state.assistant_installed && state.realtime_installed ? 'Ready to use' : 'Needs attention'}</h2><p>{assistantSetupReadiness(state)}</p>
+                <dl className="assistant-setup-facts"><div><dt>Provider</dt><dd>{state.route.provider === 'anthropic' ? 'Anthropic' : state.route.provider === 'bedrock' ? 'AWS Bedrock' : 'Unavailable'}</dd></div><div><dt>Resolved runtime model</dt><dd><code>{state.model.effective || state.route.model || 'Unavailable'}</code></dd></div><div><dt>Selected credential</dt><dd>{state.route.credential === 'admin' ? 'Assistant key' : state.route.credential === 'handler' ? 'Platform key' : state.route.credential === 'aws' ? 'AWS identity' : 'Unavailable'}</dd></div><div><dt>Deployment configuration</dt><dd>{state.route.ready ? 'Ready' : 'Needs attention'}</dd></div></dl>
+                <section className="assistant-setup-model" aria-labelledby="assistant-model-title">
+                    <h3 id="assistant-model-title">Model selection</h3>
+                    <p>Selection mode: <strong>{capability?.mode === 'auto' ? 'Automatic' : capability?.mode === 'pinned' ? 'Manual pin' : capability?.mode === 'fixed' ? 'Fixed by deployment' : 'Unavailable'}</strong> · source: {capability ? state.model.source : state.model.source || 'Unavailable'}</p>
+                    {restriction && <p className="assistant-setup-warning" id="assistant-model-restriction">{restriction}</p>}
+                    {modelEditable && <>
+                        <label className="assistant-setup-field" htmlFor="assistant-model-mode">Selection method<select className="input" id="assistant-model-mode" value={modeDraft} disabled={locked} onChange={(event) => setModeDraft(event.target.value as 'auto' | 'pinned')} aria-describedby="assistant-model-help">
+                            {!modeDraft && <option value="" disabled>Choose selection method</option>}<option value="auto" disabled={!autoAvailable}>Automatic — latest Sonnet</option><option value="pinned">Manual pin</option>
+                        </select></label>
+                        {modeDraft === 'pinned' && <label className="assistant-setup-field" htmlFor="assistant-model-pin">Manual model identifier<input className="input" id="assistant-model-pin" value={modelDraft} onChange={(event) => setModelDraft(event.target.value)} disabled={locked} list="assistant-model-choices" maxLength={81} autoComplete="off" spellCheck={false} /></label>}
+                        <datalist id="assistant-model-choices">{state.model.choices.map((choice) => <option key={choice.id} value={choice.id}>{choice.label}</option>)}</datalist>
+                        <p className="dim" id="assistant-model-help">Automatic lets the backend resolve a compatible Sonnet from its provider catalogue. A manual pin takes effect only after saving. Refreshing cannot replace a manual pin.</p>
+                        <div className="assistant-action-row"><button className="btn btn-primary" type="button" disabled={locked || !modeDraft || (modeDraft === 'auto' ? !autoAvailable : !/^[a-z0-9][a-z0-9.\-]{0,80}$/.test(modelDraft))} onClick={() => change(() => modeDraft === 'auto' ? { action: 'set_model_selection', mode: 'auto' } : { action: 'set_model_selection', mode: 'pinned', model: modelDraft }, 'Saving model selection…')}>Save model selection</button><button className="btn" type="button" disabled={locked} onClick={() => void load('models')}>Refresh provider catalogue</button></div>
+                    </>}
+                    {capability && <div className="assistant-setup-catalogue" aria-label="Provider catalogue status">
+                        <p>Catalogue: <strong>{capability.discovery.status === 'fresh' ? 'Fresh cache' : capability.discovery.status === 'stale' ? 'Stale cache — cached resolution only' : capability.discovery.status === 'unavailable' ? 'Unavailable — no usable automatic resolution' : 'Not applicable to the selected mode'}</strong>{capability.discovery.error_code && ' · The backend reports a discovery problem.'}</p>
+                        <dl className="assistant-setup-facts"><div><dt>Last successful fetch</dt><dd>{capability.discovery.fetched_at || 'None reported'}</dd></div><div><dt>Last attempt</dt><dd>{capability.discovery.attempted_at || 'None reported'}</dd></div><div><dt>Fresh until</dt><dd>{capability.discovery.expires_at || 'Not applicable'}</dd></div><div><dt>Usable cached limit</dt><dd>{capability.discovery.max_stale_at || 'Not applicable'}</dd></div></dl>
+                    </div>}
+                </section>
+                {state.route.credential === 'handler' && <div className="assistant-setup-warning"><p>This deployed route uses the Platform credential. An Assistant key will not supply it.</p><button className="btn" type="button" onClick={openPlatform}>Open Platform credential</button></div>}
+                {state.route.credential === 'aws' && <p>The Bedrock route uses deployment AWS identity. Browser key fields do not configure that identity.</p>}
+                <KeySummary label="Assistant key" value={state.key} check={state.verify} />
+                <label className="assistant-setup-field" htmlFor="assistant-replacement-key">Replacement Assistant key<input id="assistant-replacement-key" className="input" type="password" value={draft} onChange={(event) => setDraft(event.target.value)} autoComplete="new-password" spellCheck={false} maxLength={4096} disabled={locked} aria-describedby="assistant-key-help" /></label>
+                <p className="dim" id="assistant-key-help">Write-only replacement. The server checks a new key before storing it. Nothing saves while you type.</p>
+                <div className="assistant-action-row"><button type="button" className="btn btn-primary" disabled={locked || !draft.trim()} onClick={() => saveKey('assistant')}>Check and save key</button><button type="button" className="btn" disabled={locked} onClick={() => change(() => ({ action: 'verify', target: 'assistant' }), 'Checking current key…')}>Check current key</button><button type="button" className="btn" disabled={locked || state.key.source !== 'admin'} onClick={() => clearKey('assistant')}>Clear stored Assistant key</button></div>
+                <div className="assistant-setup-switch"><span>Assistant is <strong>{state.enabled ? 'enabled' : 'disabled'}</strong>. Enabling does not override deployment policy or emergency stops.</span><button className="btn" type="button" disabled={locked} onClick={() => change((current) => assistantSetupSave(current, { enabled: !current.enabled }), 'Saving Assistant switch…')}>{state.enabled ? 'Disable Assistant' : 'Enable Assistant'}</button></div>
+            </section>
+            <p className="dim">Advanced controls · deployment, safety, remote access and incident processing</p>
+            <details className="panel assistant-setup-advanced" ref={platform}><summary ref={platformTitle} tabIndex={0}>Platform credential</summary><div className="panel-pad">
+                <p>Used only by deployed routes selecting <code>handler</code>. Credentials never substitute for one another.</p><KeySummary label="Platform key" value={state.handler_key} check={state.handler_verify} />
+                <label className="assistant-setup-field" htmlFor="handler-replacement-key">Replacement Platform key<input id="handler-replacement-key" className="input" type="password" value={handlerDraft} onChange={(event) => setHandlerDraft(event.target.value)} autoComplete="new-password" spellCheck={false} maxLength={4096} disabled={locked} /></label>
+                <div className="assistant-action-row"><button className="btn btn-primary" type="button" disabled={locked || !handlerDraft.trim()} onClick={() => saveKey('handler')}>Check and save Platform key</button><button className="btn" type="button" disabled={locked} onClick={() => change(() => ({ action: 'verify', target: 'handler' }), 'Checking Platform key…')}>Check current Platform key</button><button className="btn" type="button" disabled={locked || state.handler_key.source !== 'admin'} onClick={() => clearKey('handler')}>Clear stored Platform key</button></div>
+            </div></details>
+            <details className="panel assistant-setup-advanced"><summary>Deployed policy and safety</summary><div className="panel-pad">
+                {capability && <p className="dim">Deployed policy model: <code>{capability.policy_model || 'Unavailable'}</code></p>}
+                {state.route.can_invoke !== undefined && <dl className="assistant-setup-facts"><div><dt>Guarded request admission</dt><dd>{state.route.can_invoke ? 'Allowed to attempt' : 'Blocked'} · separate from configuration readiness</dd></div></dl>}
+                <p>Policy status: {state.route.error || 'Ready'}. Deployment owns policy content and the runtime route. Activation acknowledges the policy on this node; it cannot establish fleet-wide agreement.</p><button type="button" className="btn" disabled={locked} onClick={() => change(() => ({ action: 'activate_policy' }), 'Activating policy…', 'Acknowledge the currently deployed policy on this node? This does not edit policy content, check other nodes or release an emergency stop.')}>Acknowledge deployed policy</button>
+                <dl className="assistant-setup-facts"><div><dt>Deployment stop (read-only)</dt><dd>{state.emergency_stop_static ? 'On' : 'Off'}</dd></div><div><dt>Database stop</dt><dd>{state.emergency_stop_database ? 'On' : 'Off'}</dd></div><div><dt>Effective stop</dt><dd>{state.emergency_stop ? 'On' : 'Off'}</dd></div></dl>
+                <button type="button" className="btn" disabled={locked} onClick={() => change((current) => assistantSetupSave(current, { emergency_stop: !current.emergency_stop_database }), 'Saving database stop…', 'Change only the database emergency stop? A deployment stop remains authoritative.')}>{state.emergency_stop_database ? 'Release database stop' : 'Set database stop'}</button>
+                <h3>Requests · last {state.safety.hours || 24} hours</h3>{state.safety.error && <p role="alert">Safety statistics unavailable.</p>}
+                <div className="assistant-table-scroll"><table><caption>Guarded request aggregates</caption><thead><tr><th>Provider / feature</th><th>Status</th><th>Requests</th><th>Tokens in / out</th></tr></thead><tbody>{state.safety.requests.map((row, i) => <tr key={i}><td>{row.provider} / {row.feature}</td><td>{row.status}</td><td>{row.requests}</td><td>{row.input_tokens} / {row.output_tokens}</td></tr>)}</tbody></table></div>
+                <h3>Circuit breakers</h3><div className="assistant-table-scroll"><table><caption>Breaker state by provider</caption><thead><tr><th>Provider</th><th>State</th><th>Error</th><th>Count</th></tr></thead><tbody>{state.safety.breakers.map((row, i) => <tr key={i}><td>{row.provider}</td><td>{row.state}</td><td>{row.error_code || 'None'}</td><td>{row.count}</td></tr>)}</tbody></table></div>
+                <div className="assistant-action-row">{(['all', 'anthropic', 'bedrock'] as const).map((provider) => <button key={provider} type="button" className="btn" disabled={locked} onClick={() => change(() => ({ action: 'reset_breaker', ...(provider === 'all' ? {} : { provider }) }), 'Resetting breakers…', `Reset ${provider} circuit breakers? Requests may try again; policy and emergency stops remain enforced.`)}>Reset {provider} breakers</button>)}</div>
+            </div></details>
+            <details className="panel assistant-setup-advanced"><summary>Remote agent access and connections</summary><div className="panel-pad"><p>Remote agents can receive Tools, Full API or both kinds of access according to their grants. Full API access carries the signed-in user’s API authority. Turning access off pauses connections without revoking them.</p>
+                <p>Remote access is <strong>{state.mcp.enabled ? 'on' : 'off'}</strong>.</p><button type="button" className="btn" disabled={locked} onClick={() => change((current) => assistantSetupSave(current, { mcp_enabled: !current.mcp.enabled }), 'Saving remote access…', 'Change remote agent access? Existing grants are retained; Disconnect revokes them.')}>{state.mcp.enabled ? 'Pause remote access' : 'Enable remote access'}</button>
+                <label className="assistant-setup-field" htmlFor="assistant-connect-address">Connect address (select to copy)<input id="assistant-connect-address" className="input" value={state.mcp.url} readOnly onFocus={(event) => event.target.select()} /></label><p className="dim">{state.mcp.discovery_url || 'No public discovery address configured.'}</p>
+                <button type="button" className="btn" disabled={locked} onClick={() => void load('discovery')}>Check public discovery</button><p role={state.mcp.discovery.ok === false ? 'alert' : undefined}>Discovery: {state.mcp.discovery.ok === null ? 'Not checked' : state.mcp.discovery.ok ? 'Reachable' : 'Failed'} · {state.mcp.discovery.detail}{state.mcp.discovery.checked_at && ` · ${state.mcp.discovery.checked_at}`}</p>
+                <h3>Connected agents · {state.mcp.grant_count} total</h3><p className="dim">Showing {state.mcp.grants.length} connections, capped at 200. Disconnect all spans Tools and Full API grants for every user.</p><div className="assistant-table-scroll"><table><caption>Remote connections</caption><thead><tr><th>Client / user</th><th>Access</th><th>Last used / expires</th><th>Connection</th></tr></thead><tbody>{state.mcp.grants.map((row) => <tr key={row.id}><td>{row.client.name || row.client.client_id}<br />{row.user.display_name || row.user.email}</td><td>{row.access === 'api' ? 'Full API' : row.access === 'both' ? 'Tools and Full API' : 'Tools'}</td><td>{row.last_used || 'Not used'}<br />{row.expires}</td><td><button type="button" className="btn" disabled={locked} onClick={() => change(() => ({ action: 'revoke_grant', grant_id: row.id }), 'Disconnecting agent…', `Disconnect ${row.client.name || 'this agent'} for ${row.user.display_name || row.user.email}? A new authorization is required to reconnect.`)}>Disconnect #{row.id}</button></td></tr>)}</tbody></table></div><button type="button" className="btn" disabled={locked || state.mcp.grant_count === 0} onClick={() => change(() => ({ action: 'revoke_all_grants' }), 'Disconnecting all agents…', 'Disconnect every remote Tools and Full API grant, for every user? New authorizations will be required.')}>Disconnect all agents</button>
+            </div></details>
+            <details className="panel assistant-setup-advanced"><summary>Incident triage</summary><div className="panel-pad"><p>Autonomous incident triage is <strong>{state.autonomous_triage ? 'on' : 'off'}</strong>. Enabling establishes a no-history watermark; older incidents need an explicit historical run.</p><p>Watermark: {state.autonomous_triage_activated_at || 'Not activated'}</p><button type="button" className="btn" disabled={locked} onClick={() => change((current) => assistantSetupSave(current, { autonomous_triage: !current.autonomous_triage }), 'Saving autonomous triage…', 'Change autonomous incident triage? New activation establishes a watermark; it does not queue older incidents.')}>{state.autonomous_triage ? 'Disable autonomous triage' : 'Enable autonomous triage'}</button>
+                <h3>Historical incident triage</h3><label className="assistant-setup-field" htmlFor="assistant-triage-before">Incidents before (local time)<input className="input" id="assistant-triage-before" type="datetime-local" value={before} onChange={(event) => setBefore(event.target.value)} disabled={locked} /></label><label className="assistant-setup-field" htmlFor="assistant-triage-limit">Maximum incidents (1–100)<input className="input" id="assistant-triage-limit" type="number" min={1} max={100} step={1} value={limit} onChange={(event) => setLimit(event.target.value)} disabled={locked} /></label><button type="button" className="btn" disabled={locked || !before || !Number.isInteger(Number(limit)) || Number(limit) < 1 || Number(limit) > 100} onClick={() => change(() => ({ action: 'historical_triage', before: new Date(before).toISOString(), limit: Number(limit) }), 'Queueing historical triage…', `Queue up to ${limit} incidents before ${before}? This explicitly processes historical incidents and can incur provider cost.`)}>Queue historical triage</button>
+            </div></details>
+        </>}
+    </main>;
+}

package/src/admin/assistant/index.ts

@@ -9,3 +9,5 @@ export * from './pages';
 export * from './streaming';
 
 export { ASSISTANT_ADMIN_SECTION } from '../domains/assistant';
+export * from './setup';
+export * from './AssistantSetupPage';