@jini-ai/ui 0.4.3 → 0.4.5

package/dist/features/appearance/constants.js

@@ -1,4 +1,4 @@
-import { defaultAdminTheme } from '../../theme/default.js';
+import { defaultAdminTheme } from '../../core/theme/default.js';
 /** Plain-English defaults for the three segmented-control options — a host
  *  wanting localized copy overrides via `AppearanceTabProps.themeLabels` (the
  *  component wraps each through `useT()` regardless, so this is only the

package/dist/features/connectors/rules.d.ts

@@ -1,9 +1,4 @@
-/**
- * Pure logic ported from OD's ConnectorsBrowser.tsx + the two small pure
- * helpers it imported from EntryView.tsx (isTrustedConnectorCallbackOrigin,
- * sortConnectorsForSearch/getConnectorSearchScore/sortConnectorsForDisplay).
- * No React, no transport, no DOM — see `packages/ui/archived provenance ledger`.
- */
+/** Connector callback-origin validation and search/display sorting; no React, transport or DOM. */
 import type { Connector, ConnectorAuthorizationPendingState, ConnectorActionResult, ConnectorStatusMap, ConnectorPanelAlert, ConnectorStatus, ProviderTab } from './types.js';
 /** Restricts the catalog to a single provider tab's `match` predicate, defaulting to the first tab. */
 export declare function scopeConnectorsToProvider(connectors: Connector[], providerTabs: readonly ProviderTab[], selectedProviderId: string): Connector[];

package/dist/features/connectors/types.d.ts

@@ -1,9 +1,4 @@
-/**
- * Generic OAuth-integration-marketplace domain types. Ported from the origin
- * product's ConnectorsBrowser.tsx (see the vendored reference tree cited in
- * `packages/ui/archived provenance ledger`), stripped of Connector Provider/product-specific
- * wire-shape specifics — see that file for the full provenance note.
- */
+/** Generic OAuth-integration marketplace types; hosts own provider-specific wire shapes. */
 export type ConnectorStatus = 'available' | 'connected' | 'error' | 'disabled';
 export interface ConnectorToolSafety {
     sideEffect: string;

package/dist/features/connectors/types.js

@@ -1,8 +1,3 @@
-/**
- * Generic OAuth-integration-marketplace domain types. Ported from the origin
- * product's ConnectorsBrowser.tsx (see the vendored reference tree cited in
- * `packages/ui/archived provenance ledger`), stripped of Connector Provider/product-specific
- * wire-shape specifics — see that file for the full provenance note.
- */
+/** Generic OAuth-integration marketplace types; hosts own provider-specific wire shapes. */
 export {};
 //# sourceMappingURL=types.js.map

package/dist/features/execution/http-adapter.d.ts

@@ -0,0 +1,111 @@
+import type { ByokConfig, DetectedAgent } from './types.js';
+import type { ExecutionPort } from './ports.js';
+/** Decoded HTTP operations; hosts retain auth, URLs and transport validation. */
+export interface ExecutionProbeTransport {
+    detectExecutionAgents(required: Record<string, never>, optional?: Record<string, never>): Promise<{
+        data: readonly DetectedAgent[];
+    }>;
+    testExecutionConnection(required: Pick<ByokConfig, "protocol" | "baseUrl" | "apiKey" | "model"> & ExecutionProbeFlags, optional?: Record<string, never>): Promise<{
+        ok: boolean;
+        message?: string;
+    }>;
+    testExecutionAgent(required: {
+        agentId: string;
+        model?: string;
+    }, optional?: Record<string, never>): ReturnType<NonNullable<ExecutionPort["testAgent"]>>;
+    listExecutionModels(required: Pick<ByokConfig, "protocol" | "baseUrl" | "apiKey"> & ExecutionProbeFlags, optional?: Record<string, never>): Promise<{
+        ok: boolean;
+        models: readonly string[];
+        message?: string;
+    }>;
+}
+interface ExecutionProbeFlags {
+    useStoredCredential?: boolean;
+    useAdminStoredCredential?: boolean;
+}
+/**
+ * Unwraps `{ data }` off an `api.*` response, or throws a named error identifying which call
+ * produced the malformed body.
+ *
+ * `request()` (`lib/api.ts`) validates shape on the FAILURE path only — a non-2xx always becomes
+ * an `ApiError` — but a 2xx body is returned as `body as T` with no runtime check that it actually
+ * has the shape `T` claims. Every caller in this file that read `.data` straight off that promise
+ * used to let a malformed 200 (body present, `data` missing/`null`) fall through to whatever the
+ * FIRST thing touching the result happened to be: `loadExecutionConfig`'s own `rows.map(...)`
+ * threw `Cannot read properties of undefined (reading 'map')`, while `loadAdminExecutionCredential`
+ * had no local dereference at all, so it silently RESOLVED to `undefined` and the crash only
+ * surfaced later, at whichever caller first read a field off it (live case: `AssistantDock.hooks
+ * .tsx`'s `view.isSet`, `Cannot read properties of undefined (reading 'isSet')`). Both are the same
+ * underlying defect wearing different symptoms depending on what the caller happened to do next.
+ * Centralizing the check here means every one of those call sites fails at its own source, with a
+ * message naming the actual `api.*` method — not a raw property-access trace an on-call engineer
+ * has to work backward from.
+ *
+ * Every existing caller's own failure contract is unchanged by this: `loadExecutionConfig`/
+ * `loadAdminExecutionCredential` still get caught by `AssistantDock`'s `.catch()`-and-log-and-
+ * fall-back-to-defaults; `saveAdminExecutionCredential` still surfaces as a failed save; the local
+ * agent-detection port's methods still reject, per this file's own error-reporting contract (see
+ * `requestAgentDetection`'s doc). This function only makes the THROWN message legible — it never
+ * suppresses a malformed response into a silent default (an earlier draft's `?? []` would have hidden
+ * the same failure behind "shows up as empty settings, no explanation" instead of fixing it).
+ *
+ * @complexity O(1) — one shape check, no iteration.
+ */
+export declare function requireExecutionResponseData<T>({ response, callSite }: {
+    response: {
+        data?: T | null;
+    } | null | undefined;
+    callSite: string;
+}, _options?: Record<string, never>): T;
+export interface CreateExecutionPortOptions {
+    /**
+     * When `true`, probes that receive no typed API key ask the server to use the workspace's STORED
+     * site credential instead.
+     *
+     * For the AI Assistant tab, whose key is encrypted server-side and write-only: the operator
+     * returns to a screen with a saved, working key and an EMPTY field, so "Test connection" and model
+     * discovery had nothing to send and sat permanently disabled next to a credential that works.
+     *
+     * Left `false` for Settings → Execution mode, and that default is the safety property, not an
+     * oversight: that screen probes the ADMIN's own credential (server-side since 2026-08-05, but
+     * still a DIFFERENT stored row from the site's), a different purpose from this flag entirely. If
+     * it opted in, an empty field there would silently probe — and report results for — the visitor
+     * key, crossing the boundary ADR-058 §5 makes structural. (The admin's OWN stored fallback for a
+     * BYOK *turn* is unconditional and happens entirely server-side in `assistant-byok.ts` — this
+     * flag only ever concerns the SITE credential these `test-connection`/`list-models` probes can
+     * optionally fall back to.)
+     */
+    useStoredCredential?: boolean;
+    /**
+     * When `true`, probes that receive no typed API key ask the server to use the CALLING ADMIN'S OWN
+     * stored execution credential — the other write-only key, and a different row from
+     * {@link CreateExecutionPortOptions.useStoredCredential}'s.
+     *
+     * Same symptom on the other screen. The admin's own key moved server-side on 2026-08-05, so
+     * `ExecutionTab`'s Model field asked the server to discover models with an empty key and got back
+     * "No API key — model discovery needs the key from this browser" — beside a stored key the server
+     * uses on every admin turn. The visible consequence was that the admin BYOK panel never reached
+     * `modelDiscovery.status === 'ok'`, so `ByokProviderForm` fell back to its free-text Model input
+     * while the visitor panel next to it showed a real live-model picker from the same component.
+     *
+     * The server scopes the row to the SESSION's principal, so this can only ever reach the caller's
+     * own credential. Deliberately a second flag rather than a widened `useStoredCredential`: see
+     * `server/inbound/admin-http/routes/assistant/stored-credential-probe.ts`'s header.
+     */
+    useAdminStoredCredential?: boolean;
+}
+/** Create one adapter per host transport. Keep it outside React mounts so detection is shared.
+ * Failed detections remain retryable; rescans always replace the cache with a fresh request.
+ * Transport errors reject; connection/CLI outcomes may resolve ok:false.
+ * @complexity O(1) local work per operation, excluding transport.
+ * @example const adapter = createExecutionHttpAdapter({ transport }, {});
+ * const port = adapter.createPort({}, { useAdminStoredCredential: true });
+ */
+export declare function createExecutionHttpAdapter({ transport }: {
+    transport: ExecutionProbeTransport;
+}, _options?: Record<string, never>): {
+    createPort: (_required?: Record<string, never>, options?: CreateExecutionPortOptions) => ExecutionPort;
+    resetDetectionCache: (_required?: Record<string, never>, _optional?: Record<string, never>) => void;
+};
+export {};
+//# sourceMappingURL=http-adapter.d.ts.map

package/dist/features/execution/http-adapter.js

@@ -0,0 +1,160 @@
+/**
+ * Unwraps `{ data }` off an `api.*` response, or throws a named error identifying which call
+ * produced the malformed body.
+ *
+ * `request()` (`lib/api.ts`) validates shape on the FAILURE path only — a non-2xx always becomes
+ * an `ApiError` — but a 2xx body is returned as `body as T` with no runtime check that it actually
+ * has the shape `T` claims. Every caller in this file that read `.data` straight off that promise
+ * used to let a malformed 200 (body present, `data` missing/`null`) fall through to whatever the
+ * FIRST thing touching the result happened to be: `loadExecutionConfig`'s own `rows.map(...)`
+ * threw `Cannot read properties of undefined (reading 'map')`, while `loadAdminExecutionCredential`
+ * had no local dereference at all, so it silently RESOLVED to `undefined` and the crash only
+ * surfaced later, at whichever caller first read a field off it (live case: `AssistantDock.hooks
+ * .tsx`'s `view.isSet`, `Cannot read properties of undefined (reading 'isSet')`). Both are the same
+ * underlying defect wearing different symptoms depending on what the caller happened to do next.
+ * Centralizing the check here means every one of those call sites fails at its own source, with a
+ * message naming the actual `api.*` method — not a raw property-access trace an on-call engineer
+ * has to work backward from.
+ *
+ * Every existing caller's own failure contract is unchanged by this: `loadExecutionConfig`/
+ * `loadAdminExecutionCredential` still get caught by `AssistantDock`'s `.catch()`-and-log-and-
+ * fall-back-to-defaults; `saveAdminExecutionCredential` still surfaces as a failed save; the local
+ * agent-detection port's methods still reject, per this file's own error-reporting contract (see
+ * `requestAgentDetection`'s doc). This function only makes the THROWN message legible — it never
+ * suppresses a malformed response into a silent default (an earlier draft's `?? []` would have hidden
+ * the same failure behind "shows up as empty settings, no explanation" instead of fixing it).
+ *
+ * @complexity O(1) — one shape check, no iteration.
+ */
+export function requireExecutionResponseData({ response, callSite }, _options = {}) {
+    if (response === null || response === undefined || response.data === undefined || response.data === null) {
+        throw new Error(`${callSite} response missing data`);
+    }
+    return response.data;
+}
+/** Create one adapter per host transport. Keep it outside React mounts so detection is shared.
+ * Failed detections remain retryable; rescans always replace the cache with a fresh request.
+ * Transport errors reject; connection/CLI outcomes may resolve ok:false.
+ * @complexity O(1) local work per operation, excluding transport.
+ * @example const adapter = createExecutionHttpAdapter({ transport }, {});
+ * const port = adapter.createPort({}, { useAdminStoredCredential: true });
+ */
+export function createExecutionHttpAdapter({ transport }, _options = {}) {
+    /**
+     * host's real `ExecutionPort` — wired to `src/server/modules/assistant-
+     * execution.ts`'s 3 routes (`@jini-ai/agent-runtime` underneath). Follows
+     * `@jini-ai/ui`'s `ports.ts` contract (error-reporting contract §3.1):
+     *
+     * - `detectLocalAgents`/`rescanLocalAgents`/`listModels` REJECT on any
+     *   failure (a network error, a non-2xx from this admin's own route, a
+     *   provider that could not be reached). An empty array is reserved for a
+     *   real "detection ran, found nothing" / "no models" outcome — collapsing a
+     *   broken request into `[]` would make it indistinguishable from that,
+     *   which is exactly the bug this port used to have.
+     * - `testConnection` is the one documented exception: `api.testExecutionConnection`
+     *   already classifies "reached the provider, credentials rejected" as an
+     *   `{ok:false}` VALUE server-side (`test-connection.ts`), so this method
+     *   simply returns whatever it resolves with. It only REJECTS when the
+     *   route call itself fails (session expired, network down, this admin's own
+     *   route 500ing) — a case with no provider-side answer to report as a value.
+     */
+    async function requestAgentDetection() {
+        return requireExecutionResponseData({ response: await transport.detectExecutionAgents({}, {}), callSite: "detectExecutionAgents" }, {});
+    }
+    /**
+     * Last detection, shared across every `ExecutionTab` mount in this tab's
+     * lifetime.
+     *
+     * Detection is not cheap and it is not local: `detect-agents.ts` calls
+     * `@jini-ai/agent-runtime`'s `detectAgents()`, which SPAWNS every known CLI
+     * with `--version` — two dozen processes on the host server per call. The tab
+     * asks for it unconditionally on mount (`useExecutionTab.ts`'s auto-detect
+     * effect), and the shell renders only the ACTIVE tab's panel, so leaving
+     * Execution mode unmounts the component and returning to it re-runs the whole
+     * sweep. Same on every visit to the settings page. Without this cache the
+     * operator pays a fresh 24-process scan for what is, in practice, a fixed
+     * answer.
+     *
+     * Host-scoped rather than a `useRef`/context on purpose: the point is to
+     * outlive the component, and `SettingsUi` builds a NEW port object per mount
+     * (`useRef(createExecutionPort())`), so anything held on the port instance
+     * would die with it.
+     *
+     * Deliberately no TTL. Installing a CLI mid-session is the only way this goes
+     * stale, and that case already has a purpose-built, clearly-labelled escape
+     * hatch — the Rescan button, which bypasses this cache (see
+     * `rescanLocalAgents` below). A reload clears it too. A TTL would only add a
+     * second, invisible refresh rule on top of the explicit one.
+     */
+    let cachedDetection = null;
+    /** Caches the in-flight promise, not just the settled value — two tabs
+     *  mounting in the same frame then share one request instead of racing two
+     *  identical process sweeps. */
+    function cacheDetection(inFlight) {
+        cachedDetection = inFlight;
+        // A rejection must never be cached: one network blip would otherwise pin the
+        // error in place for the rest of the session, and the port's contract is
+        // that a failure REJECTS (see this function's doc) — so a retry has to be
+        // able to actually retry.
+        inFlight.catch(() => {
+            if (cachedDetection === inFlight)
+                cachedDetection = null;
+        });
+        return inFlight;
+    }
+    /** Test seam. Module state persists across cases in a file, so a suite that
+     *  asserts on detection has to be able to start from cold. */
+    function resetLocalAgentDetectionCache(_required = {}, _optional = {}) {
+        cachedDetection = null;
+    }
+    function createExecutionPort(_required = {}, options = {}) {
+        const { useStoredCredential = false, useAdminStoredCredential = false } = options;
+        return {
+            async detectLocalAgents() {
+                return cachedDetection ?? cacheDetection(requestAgentDetection());
+            },
+            async rescanLocalAgents() {
+                // Explicit operator action: always re-probe, and make the fresh result
+                // the new baseline for subsequent mounts.
+                return cacheDetection(requestAgentDetection());
+            },
+            async testConnection(config) {
+                return transport.testExecutionConnection({
+                    protocol: config.protocol,
+                    baseUrl: config.baseUrl,
+                    apiKey: config.apiKey,
+                    model: config.model,
+                    ...(useStoredCredential ? { useStoredCredential: true } : {}),
+                    ...(useAdminStoredCredential ? { useAdminStoredCredential: true } : {}),
+                }, {});
+            },
+            async testAgent(agentId, model) {
+                // Same `{ok:false}`-is-a-value split as `testConnection`: the route
+                // classifies "the CLI ran and reported it is not usable" server-side and
+                // returns it as a value, and REJECTS (throws out of `api.*`) only when
+                // the probe could not run at all.
+                return transport.testExecutionAgent({ agentId, ...(model ? { model } : {}) }, {});
+            },
+            async listModels(config) {
+                const result = await transport.listExecutionModels({
+                    protocol: config.protocol,
+                    baseUrl: config.baseUrl,
+                    apiKey: config.apiKey,
+                    ...(useStoredCredential ? { useStoredCredential: true } : {}),
+                    ...(useAdminStoredCredential ? { useAdminStoredCredential: true } : {}),
+                }, {});
+                // `result.ok === false` here is ALWAYS "discovery could not reach/read the
+                // provider" (auth failure, timeout, blocked base URL, unsupported protocol)
+                // — `list-models.ts`'s route never reports a reachable-but-genuinely-empty
+                // catalog as `ok:false`, so there is no legitimate value to return here.
+                // Reject with the server's own message rather than resolving `[]`.
+                if (!result.ok) {
+                    throw new Error(result.message?.trim() ? result.message : "Model discovery failed");
+                }
+                return result.models;
+            },
+        };
+    }
+    return { createPort: createExecutionPort, resetDetectionCache: resetLocalAgentDetectionCache };
+}
+//# sourceMappingURL=http-adapter.js.map

package/dist/features/execution/index.d.ts

@@ -21,4 +21,8 @@ export { SearchableModelSelect } from './react/components/SearchableModelSelect.
 export type { SearchableModelSelectProps, SearchableModelSelectAdditionalOption, } from './react/components/SearchableModelSelect.js';
 export { useExecutionTab } from './react/hooks/useExecutionTab.js';
 export type { UseExecutionTabOptions, UseExecutionTabResult } from './react/hooks/useExecutionTab.js';
+export { createExecutionHttpAdapter, requireExecutionResponseData } from './http-adapter.js';
+export type { CreateExecutionPortOptions, ExecutionProbeTransport } from './http-adapter.js';
+export { useExecutionCredential } from './react/hooks/use-execution-credential.hooks.js';
+export type { UseExecutionCredentialInput, ExecutionCredentialController, ExecutionCredentialSaveState, ExecutionCredentialView, ExecutionCredentialPatch, ExecutionCredentialPort, ExecutionCredentialEffects } from './react/hooks/use-execution-credential.hooks.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/features/execution/index.js

@@ -10,4 +10,6 @@ export { AgentDiagnosticRow } from './react/components/AgentDiagnosticRow.js';
 export { AgentCliEnvFields } from './react/components/AgentCliEnvFields.js';
 export { SearchableModelSelect } from './react/components/SearchableModelSelect.js';
 export { useExecutionTab } from './react/hooks/useExecutionTab.js';
+export { createExecutionHttpAdapter, requireExecutionResponseData } from './http-adapter.js';
+export { useExecutionCredential } from './react/hooks/use-execution-credential.hooks.js';
 //# sourceMappingURL=index.js.map

package/dist/features/execution/react/hooks/use-execution-credential.hooks.d.ts

@@ -0,0 +1,232 @@
+import type { ByokConfig } from "../../types.js";
+import type { SettingsSliceRefreshPort } from "../../../panel-kit/hooks/use-settings-slice.hooks.js";
+/** The metadata read by this controller. Hosts retain any additional write-only view fields. */
+export interface ExecutionCredentialView {
+    isSet: boolean;
+    masked: string | null;
+    baseUrl: string | null;
+}
+/** Explicit key and non-secret patches remain distinct; the controller never autosaves a key. */
+export interface ExecutionCredentialPatch {
+    apiKey?: string;
+    protocol?: string;
+    providerId?: string | null;
+    baseUrl?: string;
+    model?: string;
+    maxTokens?: number;
+}
+/** The host owns routes and authorization; only a write-only view may be returned. */
+export interface ExecutionCredentialPort<TStored extends ExecutionCredentialView> {
+    loadAdminExecutionCredential(required: Record<string, never>, optional?: Record<string, never>): Promise<TStored>;
+    saveAdminExecutionCredential(required: {
+        patch: ExecutionCredentialPatch;
+    }, optional?: Record<string, never>): Promise<TStored>;
+}
+/** Host migration, notification and display policies. Product-specific error/copy stays in the host. */
+export interface ExecutionCredentialEffects<TStored extends ExecutionCredentialView> {
+    namespace: string;
+    refreshPort: SettingsSliceRefreshPort;
+    readLegacyCredential(required: Record<string, never>, optional?: Record<string, never>): string | null;
+    clearLegacyCredential(required: Record<string, never>, optional?: Record<string, never>): void;
+    describeError(required: {
+        error: unknown;
+        fallback: string;
+    }, optional?: Record<string, never>): string;
+    hasTypedKey(required: {
+        apiKey: string;
+    }, optional?: Record<string, never>): boolean;
+    storedKeyIsForOtherEndpoint(required: {
+        stored: TStored | null;
+        baseUrl: string;
+    }, optional?: Record<string, never>): boolean;
+    hasUsableKey(required: {
+        apiKey: string;
+        stored: TStored | null;
+        baseUrl: string;
+    }, optional?: Record<string, never>): boolean;
+    storedKeyBlocksProbe(required: {
+        apiKey: string;
+        stored: TStored | null;
+        baseUrl: string;
+    }, optional?: Record<string, never>): boolean;
+    credentialHint(required: {
+        stored: TStored | null;
+        storedKeyIsForOtherEndpoint: boolean;
+    }, optional?: {
+        locale?: string | undefined;
+    }): string | undefined;
+}
+/**
+ * @file State for the admin's own BYOK credential — the "Save key" and "Save settings" controls and
+ * the one-time `localStorage`-to-server migration prompt, shared verbatim by `SettingsUi.tsx`'s Execution tab
+ * and `AiAssistant.tsx`'s `AdminExecutionMode` (both render `ExecutionTab` over the SAME ledger
+ * namespace and now the same server-side credential row; per `AdminExecutionMode`'s own "must never
+ * disagree" comment about `useStoredCredential`, the two mounts cannot be allowed to diverge here
+ * either — hence one hook rather than two independent implementations).
+ *
+ * Modeled closely on the already-shipped, owner-reviewed
+ * `features/ai-assistant/hooks/use-visitor-credential-form.hooks.ts`: explicit save only, the field
+ * clears on success, a failed save never touches what is already stored/local. The two differ where
+ * the underlying screens differ — this one does not own the whole BYOK form (only the "Save key"
+ * affordance under the key field and the "Save settings" affordance at the foot of the card, since
+ * `ExecutionTab` owns the provider chips and the fields themselves via the existing `core.execution`
+ * ledger slice) and it additionally owns the migration prompt, which the visitor screen has no
+ * equivalent of (there was never a browser-local visitor key to migrate).
+ *
+ * ## One button per patch (owner ruling, 2026-09-02)
+ *
+ * There used to be ONE control here, writing the key and the row's non-secret companion fields
+ * together. That overload is what made the screen lie: pressing it with a blank field sent a patch
+ * with no `apiKey` at all and still answered "Saved to the server, encrypted." Patching the message
+ * left the cause in place, and disabling the button on a blank field broke the only way to save a
+ * model change. The split closes both: `saveKey` writes `{ apiKey }`, `saveSettings` writes the
+ * non-secret fields and never an `apiKey` property, and each carries its own save state so neither
+ * can report the other's work.
+ *
+ * ## Cross-mount staleness (disclosed residual, closed here)
+ *
+ * `stored`/`apiKeyStoredExternally` is each mounted instance's OWN copy of one server fact — every
+ * `SettingsUi.tsx` mount, every `AiAssistant.tsx` mount, AND `AssistantDock.hooks.tsx`'s own
+ * independent `loadAdminExecutionCredential()` call (`useExecutionConfig`'s `hasStoredAdminKey`) are
+ * three separate reads of the same row. A save/migrate in ONE of them updated only its own local
+ * `stored` state, so the other two kept showing whatever they last fetched — briefly, if the operator
+ * happened to remount that screen soon after, or indefinitely for the dock, which mounts once at the
+ * app shell and never remounts for the session (`AssistantDock.tsx`'s own header comment). Now wired
+ * to `settings-refresh-bus.ts`, the same seam `useSettingsSlice`'s `runSave` already uses for exactly
+ * this "same-tab sibling with no shared state" problem: every successful write publishes
+ * `EXECUTION_NAMESPACE`, and every mount (including the publisher's own, harmlessly — see
+ * `runSave`'s doc for why that redundant self-refresh is accepted rather than tracked around) re-reads
+ * on receiving it.
+ *
+ * `port` (the two functions that reach `api.getAdminExecutionCredential`/`api.setAdminExecutionCredential`
+ * under the hood) is injected — see `admin-execution-credential-port.hooks.ts` for exactly what is and
+ * is not in it, and why. `useWiredAdminExecutionCredential` below is the zero-argument pair
+ * `SettingsUi.tsx`/`AiAssistant.tsx` actually mount; `AssistantDock.hooks.tsx`'s own separate
+ * `loadAdminExecutionCredential()` call (this file's "Cross-mount staleness" doc above) is a
+ * different hook entirely, out of scope here.
+ */
+export type ExecutionCredentialSaveState = {
+    status: "idle";
+} | {
+    status: "saving";
+} | {
+    status: "saved";
+} | {
+    status: "error";
+    message: string;
+};
+export interface UseExecutionCredentialInput {
+    locale?: string | undefined;
+    /** The live BYOK half of whichever `ExecutionConfig` the host owns. Read fresh on every
+     *  `saveKey()`/`migrateLegacyKey()` call (never captured once), so a save always sends whatever
+     *  protocol/baseUrl/model/maxTokens the operator currently has selected. */
+    byok: ByokConfig;
+    /** How a successful key save clears the just-saved plaintext back out of the host's own state —
+     *  same reasoning `use-visitor-credential-form.hooks.ts`'s `saveCredential` documents: leaving it
+     *  in React state after it is safely persisted keeps it readable in devtools for no benefit, and
+     *  the masked placeholder now carries the "which key" answer the field would otherwise be giving. */
+    onByokChange: (next: ByokConfig) => void;
+}
+export interface ExecutionCredentialController<TStored extends ExecutionCredentialView> {
+    /** The server's write-only view of what is currently stored — `null` until the initial GET
+     *  settles. Never contains key material. */
+    stored: TStored | null;
+    /** Tells `ExecutionTab`'s `apiKeyStoredExternally` prop that an empty key field is not a missing
+     *  required field, because a credential already exists server-side FOR THE FORM'S ENDPOINT. A key
+     *  stored for another endpoint does not count (the server will not send it here), so after a
+     *  provider switch the field is required again and Test connection waits for a typed key. Same rule
+     *  as the visitor screen: `lib/stored-credential-endpoint.ts`'s `hasUsableKey`. */
+    apiKeyStoredExternally: boolean;
+    /** The server's `••••<last 4>`, or `undefined` when nothing is stored or the stored key belongs to
+     *  another endpoint (under a different provider it would read as that provider's key) — feeds
+     *  `ExecutionTab`'s `apiKeyPlaceholder`. Always a placeholder, never a value: `byok.apiKey` is
+     *  untouched by this controller until an explicit save succeeds. */
+    apiKeyPlaceholder: string | undefined;
+    /** A key is stored, but the server saved it for another endpoint than the form's (a provider
+     *  switch). Drives the key footer's "paste a key for this one" line. See
+     *  `lib/stored-credential-endpoint.ts`'s `storedKeyIsForOtherEndpoint`; `false` until the stored
+     *  view loads. */
+    storedKeyIsForOtherEndpoint: boolean;
+    /** Feeds `ExecutionTab`'s `canDiscoverModels`: `false` only when nothing is typed and the stored key
+     *  belongs to another endpoint, the one discovery the server can only refuse. `ExecutionTab` reads
+     *  it but never probes merely because it turned `true` — "Save settings" re-pointing the stored row
+     *  flips it, and that must not send the old provider's key to the new endpoint unasked. */
+    canDiscoverModels: boolean;
+    /** The "Save key" button's own save state — and the migration prompt's, which writes the same
+     *  key. Never advanced by {@link saveSettings}; see {@link settingsSaveState}. */
+    saveState: ExecutionCredentialSaveState;
+    /** The "Save settings" button's own save state, deliberately separate from {@link saveState}.
+     *
+     *  One shared state is what made the old single control dishonest: its status line said "Saved to
+     *  the server, encrypted." after a press that sent no key at all. Two buttons that write two
+     *  disjoint patches need two answers, so each owns its own status line and neither can report the
+     *  other's work. */
+    settingsSaveState: ExecutionCredentialSaveState;
+    /** Whether {@link saveKey} would do anything right now — the same "is there a key in the field"
+     *  guard `saveKey` itself applies, exposed so the Save key button can disable correctly without
+     *  duplicating the rule.
+     *
+     *  Derived synchronously from the trimmed field on every render, never debounced: a delayed
+     *  evaluation would leave the button enabled for the moment right after the field is cleared,
+     *  which is the bug this rule exists to close, merely shortened. */
+    canSaveKey: boolean;
+    /**
+     * Explicit save, called ONLY from a "Save key" button press — never from any debounced or
+     * automatic path. Writes the KEY and nothing else: the patch is `{ apiKey }`, with no
+     * protocol/providerId/baseUrl/model/maxTokens riding along.
+     *
+     * That narrowing (owner ruling, 2026-09-02) is the fix for a whole defect class rather than one
+     * bug. A control that wrote two different things could not honestly report what it had just done,
+     * and the "which of my two jobs did I do" bookkeeping that answer needed was itself the thing that
+     * let an `apiKey: ""` reach the server. A button with one job needs no bookkeeping. The
+     * non-secret fields moved to {@link saveSettings}.
+     *
+     * A no-op when the field is empty — see {@link canSaveKey}.
+     */
+    saveKey: () => Promise<void>;
+    /**
+     * Explicit save, called ONLY from a "Save settings" button press. Writes
+     * protocol/providerId/baseUrl/model/maxTokens and NEVER an `apiKey` property — not even an empty
+     * string, which the server rejects (400) and which is precisely the write the old overloaded
+     * control could make.
+     *
+     * ## Why this is not a second writer for the ledger's values
+     *
+     * The same protocol/baseUrl/model the operator edits here ALSO live in the `core.execution`
+     * settings ledger, written on their own debounced path by `use-admin-execution-mode.hooks.ts`'s
+     * `useSettingsSlice`. Two stores, deliberately (see `execution-settings.ts`'s
+     * `loadAdminExecutionCredential` doc): the ledger holds the live values this browser's form shows,
+     * while the credential ROW holds a snapshot the SERVER reads when a browser sends no credential of
+     * its own — `byok-credential.ts`'s `createStoredExecutionCredentialPort`, which treats a row with
+     * no `model` as unusable.
+     *
+     * Before the split, that snapshot was refreshed as a side effect of every key save. With
+     * {@link saveKey} narrowed to the key, this button is the ONLY thing that writes it. Each of the
+     * two stores still has exactly one writer; what changed is that the credential row's writer is now
+     * a control the operator can see and press, rather than a hidden passenger on a different button.
+     */
+    saveSettings: () => Promise<void>;
+    /** A pre-server-store `localStorage` key this browser still holds, or `null` when there is
+     *  nothing to migrate (never had one, already migrated, or the prompt was dismissed this
+     *  session). Non-`null` is what a caller renders the migration banner on. */
+    legacyKey: string | null;
+    /** Confirms the migration: PUTs the legacy key (plus the current `byok` non-secret fields) to the
+     *  server, and clears the `localStorage` entry ONLY once that PUT has actually succeeded — a
+     *  failed save leaves the local copy fully intact, per the design's explicit "no auto-clear"
+     *  requirement. */
+    migrateLegacyKey: () => Promise<void>;
+    /** Declines the prompt for the rest of this mount — no `localStorage` change either way. The
+     *  design's "no auto-clear" rule means a decline must not delete the local key, so the prompt is
+     *  free to reappear on a later mount (a page reload, navigating back to this tab); that is a minor
+     *  repeat-ask, not a data-loss risk, which is the asymmetry the design accepts. */
+    dismissLegacyPrompt: () => void;
+}
+/**
+ * @complexity Time: O(1) per call — one GET on mount, one PUT per explicit save/migrate. Space:
+ * O(1) — no caller-controlled collections.
+ */
+export declare function useExecutionCredential<TStored extends ExecutionCredentialView>({ byok, onByokChange, locale, port, effects }: UseExecutionCredentialInput & {
+    port: ExecutionCredentialPort<TStored>;
+    effects: ExecutionCredentialEffects<TStored>;
+}, _options?: Record<string, never>): ExecutionCredentialController<TStored>;
+//# sourceMappingURL=use-execution-credential.hooks.d.ts.map