portal-mojo 0.2.18 → 0.2.20

package/docs/auth-pages.md

@@ -124,12 +124,18 @@ Client surface (`portal-mojo/client`):
 - `withFreshAuth(fn)` — run fn; on a 440 prompt, then retry **once** after a
   successful re-login; a dismissed prompt rejects with the ORIGINAL error.
 
-The modal re-prompts credentials OVER the current screen — page state
-survives. It pins the identity to the current session's email (step-up is
-"prove you are still you"), offers password + passkey + the MFA step, and
-keeps the session in its original storage (`sessionIsPersistent()` →
-`remember`). Dev affordance: `__mojo.requestFreshAuth()` in the console
-exercises the modal without a 440.
+In hosted mode (including packaged Admin), the native dialog offers Cancel
+and Continue to sign-in. Continue opens the existing configured sign-in page
+with `force_reauth=1`, so Google-only deployments can use Google. It preserves
+the exact return route and original storage choice. The pending challenge
+resolves false before unloading: after returning, re-read and deliberately
+retry the action. Picking another account starts a new session and screen;
+the former account's operation is never carried over.
+
+In explicit in-app/mock mode the modal re-prompts credentials over the current
+screen, pins the current email when available, and keeps the existing
+password/passkey/MFA and storage behavior. Dev affordance:
+`__mojo.requestFreshAuth()` exercises the modal without a 440.
 
 Call-site pattern:
 
@@ -172,6 +178,12 @@ bouncer-enforcing deployments.
 
 ## Mock affordances
 
+`npm run verify:hosted-reauth` covers the mounted hosted confirmation and
+return/storage paths. For native dialog, responsive and theme checks, run
+`node scripts/serve-hosted-reauth.mjs` and open its printed local URL. The
+fixture uses the actual Portal host/bridge and a simulated Google-only sign-in
+page; it does not prove a live OAuth provider exchange.
+
 Under the mock transport the pages show inline dev hints: password `mojo`
 for any seeded user (e.g. `ian@mojoverify.com`); Maya (seeded user 2) requires
 MFA; TOTP `123456`, recovery `mock-recovery`, and SMS `654321`; reset code

package/docs/auth.md

@@ -102,11 +102,25 @@ its bot-check interstitial). Flow:
    `<origin>/auth?redirect=<HASH-FREE current url>`. Hash-free is
    load-bearing: the page string-appends `?auth_code=<code>` to the
    redirect, and a `#` in it would swallow the code.
-2. User signs in on the hosted page; it mints a single-use 60s handoff code
+2. User signs in using that page's configured methods (Google, password,
+   passkey, etc.). Same-origin return uses its existing stored session;
+   a cross-origin return mints a single-use 60s handoff code
    (`POST /api/auth/handoff`) and navigates back with `?auth_code=`.
 3. `handleAuthCodeFromURL()` (boot) exchanges it (`POST /api/auth/exchange`),
    scrubs the code from the URL synchronously, restores the stashed route.
-   Handles a hash-embedded `#/route?auth_code=` landing too.
+   It also restores same-origin returns without a code. Handles a
+   hash-embedded `#/route?auth_code=` landing too. Await this at boot before
+   creating the router.
+
+`redirectToHostedAuth({forceReauth: true})` uses the same page with
+`force_reauth=1`, bypassing its automatic existing-session check. It retains
+the initiating persistent/session-only choice, including when the hosted
+page writes localStorage. `remember` may explicitly supply the choice captured
+when the challenge opened. Tab-local return metadata contains only the route,
+destination, time and storage choice; it is consumed once, expires after 30
+minutes, and applies only at the matching origin/path/query. It never carries
+an operation or establishes freshness. The server still enforces `auth_time`.
+When storage cannot retain the choice, step-up navigation returns false.
 
 `hostedAuthUrl()` returns null under the mock transport — there is no page
 to host; the UI should fall back to a dev affordance (`__mojo.login(...)`).

package/docs/collection-select.md

@@ -130,3 +130,17 @@ too — there is no parallel fetch path.
   handed a picker that says to pick a group they can't pick there.
 - Don't wire `onChange` to a per-keystroke autosave expectation — it fires
   on commit (that is the point; see the B3 autosave contract).
+
+### Optional ingress projection
+
+`sanitizeRow={(row) => publicProjection(row)}` projects list and one-record
+responses before Query cache storage. Such pickers use a separate cache keyed
+by the sanitizer identity, auth UID and session revision; they never scan or
+reuse raw endpoint caches. Keep the callback stable. Default consumers retain
+the existing shared model keys and behavior. The callback must return only the
+approved fields or reject malformed input. Full selected objects also need to
+be projected by the caller before passing them in.
+
+An endpoint with query-based hydration should hydrate through its own safe
+`?id=` helper and pass the full selected object; do not pass a bare id that
+would invent a `/<id>` record route.

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.20",
     "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';

package/src/admin/assistant/setup.ts

@@ -0,0 +1,174 @@
+/** Owner-only, imperative setup protocol. Never put these operations in Query/Mutation caches. */
+import { apiOrigin, mojoCall, usingMockTransport, type FetchOpts } from '../../client/client';
+
+export const ASSISTANT_SETUP_ENDPOINT = '/api/account/admin/assistant';
+export type SetupTarget = 'assistant' | 'handler';
+export interface SetupKey { configured: boolean; source: 'admin' | 'deployment' | 'none'; hint: string }
+export interface SetupCheck { ok: boolean | null; code: string; message: string; at: string }
+export interface SetupGrant {
+    id: number; client: { id: number; client_id: string; name: string };
+    user: { id: number; email: string; display_name: string }; resource: string; scopes: string[];
+    access: 'tools' | 'api' | 'both'; created: string; last_used: string; expires: string; is_active: boolean; revoked_reason: string;
+}
+export interface AssistantSetupState {
+    schema_version: 2; enabled: boolean; key: SetupKey; handler_key: SetupKey;
+    model: { selected: string; effective: string; source: string; choices: Array<{ id: string; label: string }>; capability?: {
+        mode: 'auto' | 'pinned' | 'fixed'; editable: boolean; policy_model: string;
+        restriction: '' | 'fixed_policy' | 'provider_unsupported' | 'deployment_pin' | 'policy_unavailable';
+        discovery: { status: 'fresh' | 'stale' | 'unavailable' | 'not_applicable'; fetched_at: string | null; attempted_at: string | null; expires_at: string | null; max_stale_at: string | null; error_code: string };
+        refresh: { attempted: boolean; ok: boolean | null; code: string };
+    } };
+    verify: SetupCheck; handler_verify: SetupCheck;
+    emergency_stop: boolean; emergency_stop_static: boolean; emergency_stop_database: boolean;
+    route: { feature: string; provider: string; model: string; credential: string; credential_configured: boolean; ready: boolean; can_invoke?: boolean; error: string };
+    autonomous_triage: boolean; autonomous_triage_activated_at: string;
+    assistant_installed: boolean; realtime_installed: boolean;
+    mcp: { enabled: boolean; path: string; url: string; discovery_url: string;
+        discovery: { ok: boolean | null; code: string; detail: string; checked_at: string }; grants: SetupGrant[]; grant_count: number };
+    safety: { hours: number; error: string; requests: Array<{ provider: string; feature: string; status: string; requests: number; input_tokens: number; output_tokens: number }>;
+        breakers: Array<{ provider: string; state: string; error_code: string; count: number }> };
+}
+export interface SetupSave {
+    action: 'save'; enabled: boolean; model?: string; api_key?: string; clear_api_key?: boolean;
+    handler_api_key?: string; clear_handler_api_key?: boolean; mcp_enabled?: boolean; emergency_stop?: boolean; autonomous_triage?: boolean;
+}
+export type SetupAction = SetupSave
+    | { action: 'set_model_selection'; mode: 'auto'; model?: never }
+    | { action: 'set_model_selection'; mode: 'pinned'; model: string }
+    | { action: 'verify'; target: SetupTarget; api_key?: string }
+    | { action: 'activate_policy' }
+    | { action: 'reset_breaker'; provider?: 'anthropic' | 'bedrock' }
+    | { action: 'historical_triage'; before: string; limit: number }
+    | { action: 'revoke_grant'; grant_id: number }
+    | { action: 'revoke_all_grants' };
+export interface SetupActionResult { state: AssistantSetupState; result?: SetupCheck; saved?: boolean; verified?: boolean; activated?: boolean; reset?: number; revoked?: number; queued?: number }
+const object = (v: unknown): Record<string, unknown> => v != null && typeof v === 'object' && !Array.isArray(v) ? v as Record<string, unknown> : {};
+const text = (v: unknown, max = 160): string => typeof v === 'string' ? v.slice(0, max) : '';
+const number = (v: unknown): number => typeof v === 'number' && Number.isFinite(v) ? Math.max(0, v) : 0;
+const verdict = (v: unknown): boolean | null => typeof v === 'boolean' ? v : null;
+const rows = (v: unknown, max: number): Record<string, unknown>[] => Array.isArray(v) ? v.slice(0, max).map(object) : [];
+const identifier = (v: unknown): string => /^[a-z0-9][a-z0-9.\-]{0,80}$/.test(text(v, 82)) ? text(v, 81) : '';
+// The additive wire capability is all-or-nothing; malformed fields never enable a writer.
+const runtimeIdentifier = (v: unknown): string => typeof v === 'string' && v.length <= 200 && /^[^\s\x00-\x1f\x7f]+$/.test(v) ? v : '';
+const safeCode = (v: unknown): string => typeof v === 'string' && /^[a-z0-9_]{0,64}$/.test(v) ? v : '';
+function projectModelCapability(model: Record<string, unknown>): AssistantSetupState['model']['capability'] {
+    const d = object(model.discovery), r = object(model.refresh);
+    const timestamp = (v: unknown) => v === null || (typeof v === 'string' && v.length <= 40 && /^\d{4}-\d\d-\d\dT/.test(v) && Number.isFinite(Date.parse(v)));
+    if (typeof model.mode !== 'string' || typeof model.restriction !== 'string' || typeof model.source !== 'string' || typeof d.status !== 'string' || !['auto', 'pinned', 'fixed'].includes(model.mode) || typeof model.editable !== 'boolean'
+        || typeof model.policy_model !== 'string' || model.policy_model.length > 200
+        || !['', 'fixed_policy', 'provider_unsupported', 'deployment_pin', 'policy_unavailable'].includes(model.restriction)
+        || !['automatic', 'admin', 'deployment', 'policy'].includes(model.source)
+        || !['fresh', 'stale', 'unavailable', 'not_applicable'].includes(d.status)
+        || !['fetched_at', 'attempted_at', 'expires_at', 'max_stale_at'].every((key) => timestamp(d[key]))
+        || typeof d.error_code !== 'string' || safeCode(d.error_code) !== d.error_code
+        || typeof r.attempted !== 'boolean' || (r.ok !== null && typeof r.ok !== 'boolean')
+        || typeof r.code !== 'string' || safeCode(r.code) !== r.code) return undefined;
+    if (model.mode === 'fixed' ? model.editable !== false || !['fixed_policy', 'provider_unsupported', 'policy_unavailable'].includes(model.restriction)
+        : model.editable !== true || model.policy_model !== 'auto:sonnet' || !['', 'deployment_pin'].includes(model.restriction)
+            || (model.mode === 'auto' ? model.source !== 'automatic' || model.restriction !== '' : !['admin', 'deployment'].includes(model.source) || !identifier(model.selected))) return undefined;
+    return {
+        mode: model.mode as 'auto' | 'pinned' | 'fixed', editable: model.editable, policy_model: model.policy_model,
+        restriction: model.restriction as NonNullable<AssistantSetupState['model']['capability']>['restriction'],
+        discovery: { status: d.status as 'fresh' | 'stale' | 'unavailable' | 'not_applicable', fetched_at: d.fetched_at as string | null, attempted_at: d.attempted_at as string | null, expires_at: d.expires_at as string | null, max_stale_at: d.max_stale_at as string | null, error_code: d.error_code },
+        refresh: { attempted: r.attempted, ok: r.ok as boolean | null, code: r.code },
+    };
+}
+const CHECK_MESSAGES: Record<string, string> = { verified: 'Anthropic accepted this key.', invalid_key: 'Anthropic rejected this key.', unreachable: 'Anthropic could not be reached to check this key.', not_configured: 'No API key is configured to check.' };
+function projectCheck(raw: unknown): SetupCheck {
+    const v = object(raw); const code = text(v.code, 64);
+    return { ok: verdict(v.ok), code, message: CHECK_MESSAGES[code] ?? 'No stored check is available.', at: text(v.at, 40) };
+}
+function projectKey(raw: unknown): SetupKey {
+    const v = object(raw);
+    return { configured: v.configured === true, source: v.source === 'admin' || v.source === 'deployment' ? v.source : 'none', hint: text(v.hint, 32) };
+}
+/** Positive bounded schema projection. Raw response objects never enter component state. */
+export function projectAssistantSetup(raw: unknown): AssistantSetupState {
+    const v = object(raw);
+    if (v.schema_version !== 2) throw new Error('Assistant setup schema is unavailable.');
+    const model = object(v.model), route = object(v.route), mcp = object(v.mcp), discovery = object(mcp.discovery), safety = object(v.safety);
+    const capability = projectModelCapability(model);
+    return {
+        schema_version: 2, enabled: v.enabled === true, key: projectKey(v.key), handler_key: projectKey(v.handler_key),
+        model: { selected: identifier(model.selected), effective: text(model.effective, 200), source: ['automatic', 'admin', 'deployment', 'policy', 'setting', 'default'].includes(String(model.source)) ? String(model.source) : '', choices: rows(model.choices, 200).map((row) => ({ id: runtimeIdentifier(row.id), label: text(row.label) })).filter((row) => row.id !== ''), ...(capability ? { capability } : {}) },
+        verify: projectCheck(v.verify), handler_verify: projectCheck(v.handler_verify),
+        emergency_stop: v.emergency_stop !== false, emergency_stop_static: v.emergency_stop_static !== false, emergency_stop_database: v.emergency_stop_database !== false,
+        route: { feature: text(route.feature, 64), provider: ['anthropic', 'bedrock'].includes(String(route.provider)) ? String(route.provider) : '', model: text(route.model, 200), credential: ['admin', 'handler', 'aws'].includes(String(route.credential)) ? String(route.credential) : '', credential_configured: route.credential_configured === true, ready: route.ready === true, ...(typeof route.can_invoke === 'boolean' ? { can_invoke: route.can_invoke } : {}), error: text(route.error, 64) },
+        autonomous_triage: v.autonomous_triage === true, autonomous_triage_activated_at: text(v.autonomous_triage_activated_at, 40),
+        assistant_installed: v.assistant_installed === true, realtime_installed: v.realtime_installed === true,
+        mcp: { enabled: mcp.enabled === true, path: text(mcp.path, 500), url: text(mcp.url, 2000), discovery_url: text(mcp.discovery_url, 2000),
+            discovery: { ok: verdict(discovery.ok), code: text(discovery.code, 64), detail: text(discovery.detail, 500), checked_at: text(discovery.checked_at, 40) }, grant_count: number(mcp.grant_count),
+            grants: rows(mcp.grants, 200).map((row): SetupGrant => { const client = object(row.client), user = object(row.user); return {
+                id: number(row.id), client: { id: number(client.id), client_id: text(client.client_id), name: text(client.name) },
+                user: { id: number(user.id), email: text(user.email, 254), display_name: text(user.display_name) }, resource: text(row.resource, 2000),
+                scopes: Array.isArray(row.scopes) ? row.scopes.filter((s): s is string => typeof s === 'string').slice(0, 30).map((s) => s.slice(0, 64)) : [],
+                access: row.access === 'api' || row.access === 'both' ? row.access : 'tools', created: text(row.created, 40), last_used: text(row.last_used, 40), expires: text(row.expires, 40), is_active: row.is_active === true, revoked_reason: text(row.revoked_reason, 160),
+            }; }).filter((row) => Number.isSafeInteger(row.id) && row.id > 0) },
+        safety: { hours: number(safety.hours), error: text(safety.error, 64),
+            requests: rows(safety.requests, 200).map((row) => ({ provider: text(row.provider, 64), feature: text(row.feature, 64), status: text(row.status, 64), requests: number(row.requests), input_tokens: number(row.input_tokens), output_tokens: number(row.output_tokens) })),
+            breakers: rows(safety.breakers, 100).map((row) => ({ provider: text(row.provider, 64), state: text(row.state, 64), error_code: text(row.error_code, 64), count: number(row.count) })) },
+    };
+}
+export function assistantSetupReadiness(state: AssistantSetupState): string {
+    if (!state.assistant_installed) return 'The Assistant application is not installed.';
+    if (!state.realtime_installed) return 'The realtime application is not installed. Install it before using the Assistant.';
+    if (state.emergency_stop) return 'An emergency stop is blocking Assistant requests.';
+    if (state.model.capability?.mode === 'auto' && state.route.provider && state.route.credential && !state.model.effective) return 'Automatic model resolution is unavailable. Refresh the provider catalogue and review its reported freshness. Request admission does not prove that a usable model is ready.';
+    if (!state.route.provider || !state.route.model || !state.route.credential) return 'The deployment’s model and key selection are unavailable. Review the deployed policy and its selected credential in advanced controls; adding an Assistant key alone may not resolve this.';
+    if (!state.route.ready) return 'The deployment configuration needs attention. Review its selected key and policy.';
+    if (!state.enabled) return 'The deployment configuration is ready. Enable the Assistant when you are ready.';
+    return 'Assistant configuration is ready. Provider availability has not been checked.';
+}
+export function assertAssistantSetupOrigin(): void {
+    if (usingMockTransport()) return;
+    if (new URL(apiOrigin(), window.location.origin).origin !== window.location.origin) throw new Error('Assistant setup actions require the same origin.');
+}
+export type SetupRequestOptions = Pick<FetchOpts, 'signal' | 'beforeSend'>;
+export async function getAssistantSetup(options: SetupRequestOptions = {}, probe?: 'models' | 'discovery'): Promise<AssistantSetupState> {
+    const body = await mojoCall(ASSISTANT_SETUP_ENDPOINT, { ...options, params: probe === 'models' ? { refresh: 'models' } : probe === 'discovery' ? { check: 'discovery' } : undefined });
+    return projectAssistantSetup(body.data);
+}
+const ACTION_KEYS: Record<SetupAction['action'], readonly string[]> = {
+    save: ['action', 'enabled', 'model', 'api_key', 'clear_api_key', 'handler_api_key', 'clear_handler_api_key', 'mcp_enabled', 'emergency_stop', 'autonomous_triage'],
+    set_model_selection: ['action', 'mode', 'model'],
+    verify: ['action', 'target', 'api_key'], activate_policy: ['action'], reset_breaker: ['action', 'provider'], historical_triage: ['action', 'before', 'limit'], revoke_grant: ['action', 'grant_id'], revoke_all_grants: ['action'],
+};
+export function validateAssistantSetupAction(action: SetupAction): void {
+    if (!ACTION_KEYS[action.action] || Object.keys(action).some((key) => !ACTION_KEYS[action.action].includes(key))) throw new Error('Unsupported setup action fields.');
+    const v = action as unknown as Record<string, unknown>;
+    for (const key of ['api_key', 'handler_api_key']) if (v[key] !== undefined && (typeof v[key] !== 'string' || (v[key] as string).length > 4096 || /\s/.test(v[key] as string))) throw new Error('Enter a valid key without spaces.');
+    if (action.action === 'save') {
+        if (typeof action.enabled !== 'boolean' || (action.model !== undefined && (typeof action.model !== 'string' || (action.model !== '' && identifier(action.model) !== action.model)))) throw new Error('Enabled and a valid optional legacy model are required.');
+        for (const key of ['clear_api_key', 'clear_handler_api_key', 'mcp_enabled', 'emergency_stop', 'autonomous_triage']) if (v[key] !== undefined && typeof v[key] !== 'boolean') throw new Error('Setup switches must be boolean.');
+        if ((action.api_key && action.clear_api_key) || (action.handler_api_key && action.clear_handler_api_key)) throw new Error('Replace and clear are separate operations.');
+    }
+    if (action.action === 'set_model_selection' && (action.mode === 'auto' ? Object.hasOwn(action, 'model') : action.mode !== 'pinned' || !action.model || identifier(action.model) !== action.model)) throw new Error('Choose Automatic without a model or a valid manual pin.');
+    if (action.action === 'verify' && action.target !== 'assistant' && action.target !== 'handler') throw new Error('Select a credential target.');
+    if (action.action === 'reset_breaker' && action.provider !== undefined && !['anthropic', 'bedrock'].includes(action.provider)) throw new Error('Unsupported provider.');
+    if (action.action === 'historical_triage' && (!/^\d{4}-\d\d-\d\dT/.test(action.before) || !Number.isFinite(Date.parse(action.before)) || !Number.isInteger(action.limit) || action.limit < 1 || action.limit > 100)) throw new Error('Choose an ISO cutoff and a limit from 1 through 100.');
+    if (action.action === 'revoke_grant' && (!Number.isSafeInteger(action.grant_id) || action.grant_id <= 0)) throw new Error('Select a valid connection.');
+}
+export async function mutateAssistantSetup(action: SetupAction, options: SetupRequestOptions = {}): Promise<SetupActionResult> {
+    validateAssistantSetupAction(action); assertAssistantSetupOrigin();
+    const body = await mojoCall(ASSISTANT_SETUP_ENDPOINT, { method: 'POST', body: { ...action }, signal: options.signal, beforeSend: () => { assertAssistantSetupOrigin(); options.beforeSend?.(); } });
+    const raw = object(body.data);
+    if (raw.schema_version !== 2) throw new Error('Assistant setup schema is unavailable.');
+    return { state: projectAssistantSetup(raw.state), ...(action.action === 'verify' ? { result: projectCheck(raw.result) } : {}),
+        ...(typeof raw.saved === 'boolean' ? { saved: raw.saved } : {}), ...(typeof raw.verified === 'boolean' ? { verified: raw.verified } : {}), ...(typeof raw.activated === 'boolean' ? { activated: raw.activated } : {}),
+        ...(typeof raw.reset === 'number' ? { reset: number(raw.reset) } : {}), ...(typeof raw.revoked === 'number' ? { revoked: number(raw.revoked) } : {}), ...(typeof raw.queued === 'number' ? { queued: number(raw.queued) } : {}) };
+}
+/** Preserve old-server baselines; capable servers own model selection through its dedicated action. */
+export function assistantSetupSave(state: AssistantSetupState, changes: Omit<SetupSave, 'action' | 'enabled' | 'model'> & { enabled?: boolean; model?: string }): SetupSave {
+    const { model, ...other } = changes;
+    return { action: 'save', enabled: state.enabled, ...(!state.model.capability ? { model: model ?? state.model.selected } : {}), ...other };
+}
+
+/** Only backend fixed pre-write credential refusals earn a definite no-write message. */
+export function assistantSetupCredentialRefusal(error: unknown): string | null {
+    if (!(error instanceof Error)) return null;
+    for (const [wire, label] of [['api key', 'Assistant key'], ['handler api key', 'Platform key']] as const) {
+        if (error.message === `The ${wire} was not accepted. Anthropic rejected this key.`) return `The ${label} was rejected. Check the replacement and try again. Nothing was stored.`;
+        if (error.message === `The ${wire} was not accepted. Anthropic could not be reached to check this key.`) return `The ${label} could not be checked because Anthropic was unreachable. Nothing was stored; try again when the provider is available.`;
+    }
+    return null;
+}