@datalayer/core 1.1.60 → 1.2.10

package/lib/hooks/useMcp.js

@@ -0,0 +1,891 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Hooks over the Jupyter MCP Server, IAM's connected agents and the OTEL
+ * service, in the `useContents.ts` shape: `enabled` on token and URL,
+ * `staleTime` per resource, filters in the query key, mutations that
+ * `setQueryData` and invalidate.
+ *
+ * Polling by predicate: a task refetches every two seconds while it is not
+ * terminal and stops when it is; the activity answer every ten seconds as
+ * the fallback under the websocket; audit and policy on demand. An open
+ * Runs panel subscribes to the task's server-sent events instead.
+ *
+ * @module hooks/useMcp
+ */
+import { useEffect } from 'react';
+import { useMutation, useQueries, useQuery, useQueryClient, } from '@tanstack/react-query';
+import { answerTask, cancelTask, exportAuditEvents, fetchMcpLogs, fetchMcpMetrics, fetchRunTrace, fetchTraceSpans, getEffectivePolicy, getGatewayVersion, getMcpActivity, getOrganizationMcpOverview, getOrganizationMcpUsage, getTask, getWorkflowsHealth, isMcpTaskTerminal, listAuditEvents, listBindings, listNotebookTasks, listTasks, listWorkers, subscribeTaskEvents, terminateBinding, } from '../api/mcp/index.js';
+import { disconnectAgent, disconnectEveryAgent, disconnectEveryAgentInTeam, listConnectedAgents, } from '../api/iam/connectedAgents.js';
+import { listOrganizationTeams, } from '../api/iam/organizationTeams.js';
+import { getAuditSettings, setAuditSettings, } from '../api/iam/mcpAuditSettings.js';
+import { getMcpForwarding } from '../api/mcp/forwarding.js';
+import { testAlertRule } from '../api/mcp/alerts.js';
+import { createAlertRule, deleteAlertRule, listAlertRules, updateAlertRule, } from '../api/iam/mcpAlertRules.js';
+import { createIdentityProvider, deleteIdentityProvider, disableIdentityProvider, enableIdentityProvider, getDomainVerification, listIdentityProviders, updateIdentityProvider, verifyDomain, } from '../api/iam/identityProviders.js';
+import { createScimToken, listScimTokens, revokeScimToken, rotateScimToken, } from '../api/iam/scimTokens.js';
+import { deleteMcpPolicy, getAdmittedClients, getMcpPolicy, setMcpPolicy, } from '../api/iam/mcpPolicy.js';
+import { createServiceAgent, listServiceAgents, revokeServiceAgent, rotateServiceAgentKey, } from '../api/iam/serviceAgents.js';
+import { useCoreStore, useIAMStore } from '../state/index.js';
+import { queryKeys } from './useCache.js';
+const useMcpServerUrl = () => useCoreStore(state => state.configuration.jupyterMcpServerUrl);
+const useIamUrl = () => useCoreStore(state => state.configuration.iamUrl);
+const useOtelUrl = () => useCoreStore(state => state.configuration.otelUrl);
+// -- Tasks -----------------------------------------------------------------
+export const useTasks = (filters = {}, options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const mcpUrl = useMcpServerUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.taskList(filters),
+        queryFn: () => listTasks(token ?? '', filters, mcpUrl),
+        enabled: Boolean(token && mcpUrl) && (options.enabled ?? true),
+        staleTime: 5_000,
+        refetchInterval: filters.status && !isMcpTaskTerminal(filters.status) ? 5_000 : false,
+    });
+};
+/** One task, polled every two seconds until it is terminal. */
+export const useTask = (taskUid) => {
+    const token = useIAMStore(state => state.token);
+    const mcpUrl = useMcpServerUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.task(taskUid ?? ''),
+        queryFn: () => getTask(token ?? '', taskUid, mcpUrl),
+        enabled: Boolean(token && mcpUrl && taskUid),
+        refetchInterval: query => query.state.data && isMcpTaskTerminal(query.state.data.status)
+            ? false
+            : 2_000,
+    });
+};
+export const useNotebookTasks = (notebookUid, filters = {}) => {
+    const token = useIAMStore(state => state.token);
+    const mcpUrl = useMcpServerUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.notebookTasks(notebookUid ?? '', filters),
+        queryFn: () => listNotebookTasks(token ?? '', notebookUid, filters, mcpUrl),
+        enabled: Boolean(token && mcpUrl && notebookUid),
+        staleTime: 5_000,
+    });
+};
+/**
+ * The task's server-sent events, patched into the task's cache entry so
+ * every `useTask` of it updates without polling. Ends by itself when the
+ * task is terminal; the subscription closes with the component.
+ */
+export const useTaskEvents = (taskUid, options = {}) => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const mcpUrl = useMcpServerUrl();
+    const enabled = Boolean(token && mcpUrl && taskUid) && (options.enabled ?? true);
+    const { onEvent } = options;
+    useEffect(() => {
+        if (!enabled) {
+            return undefined;
+        }
+        const close = subscribeTaskEvents(token ?? '', taskUid, {
+            onEvent: event => {
+                queryClient.setQueryData(queryKeys.mcp.task(taskUid), current => {
+                    if (event.task) {
+                        return event.task;
+                    }
+                    if (!current) {
+                        return current;
+                    }
+                    return {
+                        ...current,
+                        status: event.status ?? current.status,
+                        statusMessage: event.statusMessage ?? current.statusMessage,
+                        lastUpdatedAt: event.at ?? current.lastUpdatedAt,
+                        outputs: event.output
+                            ? [...(current.outputs ?? []), event.output]
+                            : current.outputs,
+                    };
+                });
+                onEvent?.(event);
+            },
+            onClose: () => {
+                queryClient.invalidateQueries({
+                    queryKey: queryKeys.mcp.task(taskUid),
+                });
+                queryClient.invalidateQueries({ queryKey: queryKeys.mcp.tasks() });
+            },
+        }, mcpUrl);
+        return close;
+    }, [enabled, token, taskUid, mcpUrl, queryClient, onEvent]);
+};
+export const useCancelTask = () => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const mcpUrl = useMcpServerUrl();
+    return useMutation({
+        mutationFn: taskUid => cancelTask(token ?? '', taskUid, mcpUrl),
+        onSuccess: task => {
+            queryClient.setQueryData(queryKeys.mcp.task(task.uid), task);
+            queryClient.invalidateQueries({ queryKey: queryKeys.mcp.tasks() });
+            queryClient.invalidateQueries({ queryKey: queryKeys.mcp.activity() });
+        },
+    });
+};
+export const useAnswerTask = () => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const mcpUrl = useMcpServerUrl();
+    return useMutation({
+        mutationFn: ({ taskUid, input }) => answerTask(token ?? '', taskUid, { input }, crypto.randomUUID(), mcpUrl),
+        onSuccess: task => {
+            queryClient.setQueryData(queryKeys.mcp.task(task.uid), task);
+            queryClient.invalidateQueries({ queryKey: queryKeys.mcp.tasks() });
+        },
+    });
+};
+// -- Bindings --------------------------------------------------------------
+export const useBindings = (filters = {}, options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const mcpUrl = useMcpServerUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.bindingList(filters),
+        queryFn: () => listBindings(token ?? '', filters, mcpUrl),
+        enabled: Boolean(token && mcpUrl) && (options.enabled ?? true),
+        staleTime: 10_000,
+    });
+};
+export const useTerminateBinding = () => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const mcpUrl = useMcpServerUrl();
+    return useMutation({
+        mutationFn: bindingUid => terminateBinding(token ?? '', bindingUid, mcpUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({ queryKey: queryKeys.mcp.bindings() });
+            queryClient.invalidateQueries({ queryKey: queryKeys.mcp.activity() });
+        },
+    });
+};
+// -- Activity --------------------------------------------------------------
+/**
+ * What is going on for the caller, refetched every ten seconds as the
+ * fallback under the ai-agents websocket, which patches the same entry.
+ */
+export const useMcpActivity = (filters = {}, options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const mcpUrl = useMcpServerUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.activity(filters),
+        queryFn: () => getMcpActivity(token ?? '', filters, mcpUrl),
+        enabled: Boolean(token && mcpUrl) && (options.enabled ?? true),
+        staleTime: 5_000,
+        /*
+         * A poll that cannot succeed stops polling.
+         *
+         * `refetchInterval` as a plain number re-arms after *every* settle,
+         * failures included — so an endpoint the browser refuses outright (no
+         * CORS header, a dead host, a revoked token) turned this into a tight
+         * loop: fetch, fail, re-arm, fetch. Each failure is a query state change,
+         * and every observer re-rendered on each one, which read as a page
+         * repainting on a timer with nothing behind it.
+         *
+         * As a function it can decline. One error is enough to stand down; a
+         * remount, a refocus or a token change starts it again, which is when
+         * the answer could genuinely have changed.
+         */
+        refetchInterval: query => query.state.status === 'error'
+            ? false
+            : (options.pollIntervalMs ?? 10_000),
+        refetchIntervalInBackground: false,
+        // One retry, not the default three. The failures worth retrying here are
+        // transient; a refused origin is not, and three attempts only make the
+        // loop above three times as loud.
+        retry: 1,
+        /*
+         * Re-render for the answer, not for the asking.
+         *
+         * This polls for as long as the page is open, and by default a query
+         * notifies on every observed field — so `isFetching` going true and back
+         * again re-rendered every consumer twice a poll, whether or not a single
+         * byte had changed. On a dashboard that reads only the data, that is a
+         * repaint on a timer with nothing behind it.
+         *
+         * Structural sharing already keeps `data` referentially stable when the
+         * payload is unchanged, so with this the quiet polls cost nothing.
+         */
+        /*
+         * Re-render for the answer, not for the asking.
+         *
+         * `error` is deliberately absent: this is a background poll, and a
+         * consumer that redraws every time it fails is redrawing for something it
+         * does not show. `isPending` covers the one transition that matters —
+         * nothing yet, then something.
+         */
+        notifyOnChangeProps: ['data', 'isPending'],
+    });
+};
+// -- Audit -----------------------------------------------------------------
+/** One page of the audit log; the cursor is one of the filters, as the URL keeps it. */
+export const useAuditEvents = (filters = {}, options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const mcpUrl = useMcpServerUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.auditList(filters),
+        queryFn: () => listAuditEvents(token ?? '', filters, mcpUrl),
+        enabled: Boolean(token && mcpUrl) && (options.enabled ?? true),
+        staleTime: 30_000,
+        placeholderData: previous => previous,
+    });
+};
+/** The whole selection as one JSONL or CSV document, on demand. */
+export const useAuditExport = () => {
+    const token = useIAMStore(state => state.token);
+    const mcpUrl = useMcpServerUrl();
+    return useMutation({
+        mutationFn: ({ filters = {}, format = 'jsonl' }) => exportAuditEvents(token ?? '', filters, format, mcpUrl),
+    });
+};
+// -- Policy ----------------------------------------------------------------
+/** The effective policy for the caller, or previewed as one agent. */
+export const useEffectivePolicy = (agent, filters = {}, options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const mcpUrl = useMcpServerUrl();
+    const policyFilters = { agent, ...filters };
+    return useQuery({
+        queryKey: queryKeys.mcp.policy(policyFilters),
+        queryFn: () => getEffectivePolicy(token ?? '', policyFilters, mcpUrl),
+        enabled: Boolean(token && mcpUrl) && (options.enabled ?? true),
+        staleTime: 60_000,
+    });
+};
+// -- Organizations (the Enterprise console) --------------------------------
+/**
+ * The organization's MCP overview, for the console's first page.
+ *
+ * Read on demand and kept for a minute: an administrator reads it, acts, and
+ * comes back — it is not a live pane, and a page that re-asked every ten
+ * seconds would cost the gateway three bounded queries for nothing.
+ */
+export const useOrgMcpOverview = (orgUid, filters = {}, options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const mcpUrl = useMcpServerUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.orgOverview(orgUid ?? '', filters),
+        queryFn: () => getOrganizationMcpOverview(token ?? '', orgUid, filters, mcpUrl),
+        enabled: Boolean(token && mcpUrl && orgUid) && (options.enabled ?? true),
+        staleTime: 60_000,
+    });
+};
+/**
+ * The organization's use against its quotas, and which agents spent it.
+ *
+ * Kept for a minute like the overview, and for the same reason: an
+ * administrator reads it, acts, and comes back. A budget that re-asked every
+ * ten seconds would cost IAM a ledger query for a number that moves in
+ * credits, not in milliseconds.
+ */
+export const useOrgMcpUsage = (orgUid, filters = {}, options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const mcpUrl = useMcpServerUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.orgUsage(orgUid ?? '', filters),
+        queryFn: () => getOrganizationMcpUsage(token ?? '', orgUid, filters, mcpUrl),
+        enabled: Boolean(token && mcpUrl && orgUid) && (options.enabled ?? true),
+        staleTime: 60_000,
+    });
+};
+// -- Connected agents (IAM) ------------------------------------------------
+export const useConnectedAgents = (options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.connectedAgents(),
+        queryFn: () => listConnectedAgents(token ?? '', iamUrl),
+        enabled: Boolean(token && iamUrl) && (options.enabled ?? true),
+        staleTime: 30_000,
+    });
+};
+/** Revoke a grant; the list and the activity are refreshed, never guessed. */
+export const useDisconnectAgent = () => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: grantUid => disconnectAgent(token ?? '', grantUid, iamUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: queryKeys.mcp.connectedAgents(),
+            });
+            queryClient.invalidateQueries({ queryKey: queryKeys.mcp.activity() });
+        },
+    });
+};
+/**
+ * Disconnect every agent of this person — and so force the next
+ * authorization through the consent screen.
+ *
+ * The grant *is* the consent, so there is no separate "ask again" to keep in
+ * step: ending them all is what forcing re-consent means.
+ */
+export const useDisconnectEveryAgent = () => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: () => disconnectEveryAgent(token ?? '', iamUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: queryKeys.mcp.connectedAgents(),
+            });
+            queryClient.invalidateQueries({ queryKey: queryKeys.mcp.activity() });
+        },
+    });
+};
+/** The same for one team's agents, for whoever may manage that team. */
+export const useDisconnectEveryAgentInTeam = () => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: teamUid => disconnectEveryAgentInTeam(token ?? '', teamUid, iamUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: queryKeys.mcp.connectedAgents(),
+            });
+            queryClient.invalidateQueries({ queryKey: queryKeys.mcp.activity() });
+        },
+    });
+};
+// -- Teams (IAM) ------------------------------------------------------------
+/** One organization's teams, for the console's team policy page. */
+export const useOrganizationTeams = (orgUid, options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.organizationTeams(orgUid),
+        queryFn: () => listOrganizationTeams(token ?? '', orgUid, iamUrl),
+        enabled: Boolean(token && iamUrl && orgUid) && (options.enabled ?? true),
+        staleTime: 60_000,
+    });
+};
+/**
+ * Whether the audit is reaching the organization's own system of record.
+ *
+ * Polled rather than read once: a destination that stops answering does so
+ * while somebody is looking at the page, and the point of the panel is to
+ * say when that happens.
+ */
+export const useMcpForwarding = (org = '', options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const mcpUrl = useMcpServerUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.forwarding(org),
+        queryFn: () => getMcpForwarding(token ?? '', org, mcpUrl),
+        enabled: Boolean(token && mcpUrl) && (options.enabled ?? true),
+        staleTime: 30_000,
+        refetchInterval: 60_000,
+    });
+};
+// -- Audit settings: retention, forwarding, alert destinations (IAM) --------
+/** One organization's settings, or `null` where it has decided nothing. */
+export const useAuditSettings = (orgUid, options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.auditSettings(orgUid),
+        queryFn: () => getAuditSettings(token ?? '', orgUid, iamUrl),
+        enabled: Boolean(token && iamUrl && orgUid) && (options.enabled ?? true),
+        staleTime: 30_000,
+    });
+};
+/**
+ * Change some of them. Only what is passed is sent, because IAM merges: a
+ * page editing the alert destinations must not clear a retention it never
+ * showed.
+ */
+export const useSetAuditSettings = (orgUid) => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: ({ settings, expectedVersion }) => setAuditSettings(token ?? '', orgUid, settings, { expectedVersion }, iamUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: queryKeys.mcp.auditSettings(orgUid),
+            });
+        },
+    });
+};
+/**
+ * Try a rule against current values.
+ *
+ * A mutation rather than a query: it is something somebody asks for, once,
+ * by pressing a button — and caching "what does this see now" would answer
+ * the second press with the first press's numbers.
+ */
+export const useTestAlertRule = () => {
+    const token = useIAMStore(state => state.token);
+    const mcpUrl = useMcpServerUrl();
+    return useMutation({
+        mutationFn: rule => testAlertRule(token ?? '', rule, mcpUrl),
+    });
+};
+// -- Alert rules (IAM) ------------------------------------------------------
+/** One organization's alert rules, disabled ones included. */
+export const useAlertRules = (orgUid, options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.alertRules(orgUid),
+        queryFn: () => listAlertRules(token ?? '', orgUid, iamUrl),
+        enabled: Boolean(token && iamUrl && orgUid) && (options.enabled ?? true),
+        staleTime: 30_000,
+    });
+};
+export const useCreateAlertRule = (orgUid) => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: rule => createAlertRule(token ?? '', orgUid, rule, iamUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: queryKeys.mcp.alertRules(orgUid),
+            });
+        },
+    });
+};
+export const useUpdateAlertRule = (orgUid) => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: ({ uid, rule }) => updateAlertRule(token ?? '', orgUid, uid, rule, iamUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: queryKeys.mcp.alertRules(orgUid),
+            });
+        },
+    });
+};
+export const useDeleteAlertRule = (orgUid) => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: uid => deleteAlertRule(token ?? '', orgUid, uid, iamUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: queryKeys.mcp.alertRules(orgUid),
+            });
+        },
+    });
+};
+// -- Identity providers (IAM) -----------------------------------------------
+/** One organization's identity providers, disabled ones included. */
+export const useIdentityProviders = (orgUid, options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.identityProviders(orgUid),
+        queryFn: () => listIdentityProviders(token ?? '', orgUid, iamUrl),
+        enabled: Boolean(token && iamUrl && orgUid) && (options.enabled ?? true),
+        staleTime: 30_000,
+    });
+};
+export const useCreateIdentityProvider = (orgUid) => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: provider => createIdentityProvider(token ?? '', orgUid, provider, iamUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: queryKeys.mcp.identityProviders(orgUid),
+            });
+        },
+    });
+};
+export const useUpdateIdentityProvider = (orgUid) => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: ({ uid, provider }) => updateIdentityProvider(token ?? '', orgUid, uid, provider, iamUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: queryKeys.mcp.identityProviders(orgUid),
+            });
+        },
+    });
+};
+export const useSetIdentityProviderEnabled = (orgUid) => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: ({ uid, enabled }) => enabled
+            ? enableIdentityProvider(token ?? '', orgUid, uid, iamUrl)
+            : disableIdentityProvider(token ?? '', orgUid, uid, iamUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: queryKeys.mcp.identityProviders(orgUid),
+            });
+        },
+    });
+};
+/**
+ * What one layer's `allowedClients` entries actually name.
+ *
+ * Deliberately *not* folded into `useMcpPolicyLayer`. That query is read
+ * whenever a policy form mounts; this one may make the server fetch a client
+ * document per entry, and an editor typing in a textarea must not set that
+ * off on every keystroke — so it is fetched from what is **stored**, and goes
+ * stale until the draft is saved.
+ */
+export const useAdmittedClients = (scope, subjectUid, options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.admittedClients(scope, subjectUid),
+        queryFn: () => getAdmittedClients(token ?? '', scope, subjectUid, iamUrl),
+        enabled: Boolean(token && iamUrl && subjectUid) && (options.enabled ?? true),
+        // Longer than the policy layer's: a client document is cached by the
+        // server for as long as its own headers say, and re-asking on every
+        // focus would make a console page a source of outbound traffic.
+        staleTime: 300_000,
+    });
+};
+// -- SCIM provisioning credentials (IAM) ------------------------------------
+/**
+ * One organization's SCIM tokens, revoked ones included.
+ *
+ * Revoked ones are *not* filtered out here. A console that hid them would
+ * make an organization whose every token is revoked look identical to one
+ * that never had any — and those are different problems with different
+ * fixes, only one of which is "nobody is being deprovisioned right now".
+ */
+export const useScimTokens = (orgUid, options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.scimTokens(orgUid),
+        queryFn: () => listScimTokens(token ?? '', orgUid, iamUrl),
+        enabled: Boolean(token && iamUrl && orgUid) && (options.enabled ?? true),
+        staleTime: 30_000,
+    });
+};
+/**
+ * Mint one. The secret is in the result and nowhere else, ever again.
+ *
+ * The mutation result is deliberately not written into the query cache: a
+ * secret that lived in a cache would be re-rendered on every refetch of the
+ * list, and outlive the dialog it was shown in.
+ */
+export const useCreateScimToken = (orgUid) => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: name => createScimToken(token ?? '', orgUid, name, iamUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: queryKeys.mcp.scimTokens(orgUid),
+            });
+        },
+    });
+};
+export const useRotateScimToken = (orgUid) => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: uid => rotateScimToken(token ?? '', orgUid, uid, iamUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: queryKeys.mcp.scimTokens(orgUid),
+            });
+        },
+    });
+};
+export const useRevokeScimToken = (orgUid) => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: uid => revokeScimToken(token ?? '', orgUid, uid, iamUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: queryKeys.mcp.scimTokens(orgUid),
+            });
+        },
+    });
+};
+export const useDeleteIdentityProvider = (orgUid) => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: uid => deleteIdentityProvider(token ?? '', orgUid, uid, iamUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: queryKeys.mcp.identityProviders(orgUid),
+            });
+        },
+    });
+};
+/**
+ * What to publish in DNS, fetched on demand rather than kept fresh.
+ *
+ * A mutation, not a query with a `refetch`: this is asked for once when
+ * somebody opens the verification panel, and the value never changes for a
+ * given provider and domain — what changes is `verified`, which the
+ * `verify` call below answers directly from the provider it returns.
+ */
+export const useDomainVerification = (orgUid) => {
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: ({ uid, domain }) => getDomainVerification(token ?? '', orgUid, uid, domain, iamUrl),
+    });
+};
+export const useVerifyDomain = (orgUid) => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: ({ uid, domain }) => verifyDomain(token ?? '', orgUid, uid, domain, iamUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: queryKeys.mcp.identityProviders(orgUid),
+            });
+        },
+    });
+};
+// -- The policy layer IAM stores (IAM) -------------------------------------
+/**
+ * One layer's rules, or `null` where nobody has written one.
+ *
+ * `null` is a real answer and not an error: most organizations have never
+ * written a policy, and a form needs to tell "narrows nothing" from "does
+ * not exist" — only the second has nothing to remove.
+ */
+export const useMcpPolicyLayer = (scope, subjectUid, options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.policyLayer(scope, subjectUid),
+        queryFn: () => getMcpPolicy(token ?? '', scope, subjectUid, iamUrl),
+        enabled: Boolean(token && iamUrl && subjectUid) && (options.enabled ?? true),
+        staleTime: 30_000,
+    });
+};
+/**
+ * Several layers at once, for a page that has to compare against them all.
+ *
+ * The personal policy page needs every organization a person belongs to in
+ * order to say which of their values will have no effect. One hook per
+ * organization is not something a component can do — the count changes — so
+ * they are fetched together and answered in the order asked.
+ *
+ * A layer that could not be read comes back `null`, the same as one nobody
+ * has written. That is the safe direction here: the page would rather say
+ * nothing about narrowing than invent a cap somebody does not have.
+ */
+export const useMcpPolicyLayers = (scope, subjectUids) => {
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useQueries({
+        queries: subjectUids.map(subjectUid => ({
+            queryKey: queryKeys.mcp.policyLayer(scope, subjectUid),
+            queryFn: () => getMcpPolicy(token ?? '', scope, subjectUid, iamUrl),
+            enabled: Boolean(token && iamUrl && subjectUid),
+            staleTime: 30_000,
+        })),
+    });
+};
+/**
+ * Replace one layer's rules.
+ *
+ * The **effective** policy is invalidated alongside the layer: the two are
+ * the same fact read two ways, and a page still showing the old effective
+ * policy after a write is a page saying the change did not take.
+ */
+export const useSetMcpPolicyLayer = (scope, subjectUid) => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: ({ rules, expectedVersion }) => setMcpPolicy(token ?? '', scope, subjectUid, rules, { expectedVersion }, iamUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: queryKeys.mcp.policyLayer(scope, subjectUid),
+            });
+            queryClient.invalidateQueries({ queryKey: queryKeys.mcp.policy() });
+        },
+    });
+};
+/** Remove one layer, so it narrows nothing again. */
+export const useDeleteMcpPolicyLayer = (scope, subjectUid) => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: () => deleteMcpPolicy(token ?? '', scope, subjectUid, iamUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: queryKeys.mcp.policyLayer(scope, subjectUid),
+            });
+            queryClient.invalidateQueries({ queryKey: queryKeys.mcp.policy() });
+        },
+    });
+};
+// -- Service agents (IAM) --------------------------------------------------
+/**
+ * One organization's service agents, revoked ones included.
+ *
+ * Keyed by the organization: two organizations' lists must never share a
+ * cache entry, or an owner of both would see one under the other's name.
+ */
+export const useServiceAgents = (orgUid, options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.serviceAgents(orgUid),
+        queryFn: () => listServiceAgents(token ?? '', orgUid, iamUrl),
+        enabled: Boolean(token && iamUrl && orgUid) && (options.enabled ?? true),
+        staleTime: 30_000,
+    });
+};
+/**
+ * Create one. The answer carries the key, and it is the only place it
+ * exists — so the caller must render it before doing anything else with it.
+ */
+export const useCreateServiceAgent = (orgUid) => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: agent => createServiceAgent(token ?? '', orgUid, agent, iamUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: queryKeys.mcp.serviceAgents(orgUid),
+            });
+        },
+    });
+};
+/** Replace an agent's key; the old one stops working with the call. */
+export const useRotateServiceAgentKey = (orgUid) => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: agentUid => rotateServiceAgentKey(token ?? '', orgUid, agentUid, iamUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: queryKeys.mcp.serviceAgents(orgUid),
+            });
+        },
+    });
+};
+/** Stop an agent. The list is refetched rather than edited in place. */
+export const useRevokeServiceAgent = (orgUid) => {
+    const queryClient = useQueryClient();
+    const token = useIAMStore(state => state.token);
+    const iamUrl = useIamUrl();
+    return useMutation({
+        mutationFn: agentUid => revokeServiceAgent(token ?? '', orgUid, agentUid, iamUrl),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: queryKeys.mcp.serviceAgents(orgUid),
+            });
+        },
+    });
+};
+// -- Observability (OTEL) --------------------------------------------------
+/** The spans of a run, from the task's trace id; asked again while the task runs. */
+export const useRunTrace = (taskUid, options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const otelUrl = useOtelUrl();
+    const task = useTask(taskUid);
+    return useQuery({
+        queryKey: queryKeys.mcp.trace(taskUid ?? ''),
+        queryFn: () => fetchRunTrace(token ?? '', task.data, otelUrl),
+        enabled: Boolean(token && otelUrl && task.data) && (options.enabled ?? true),
+        staleTime: 15_000,
+        refetchInterval: task.data && !isMcpTaskTerminal(task.data.status) ? 5_000 : false,
+    });
+};
+/**
+ * The spans of one trace, for a call that finished inside its own request.
+ *
+ * Read once and kept: a finished trace does not change, and the pane that
+ * shows it is opened from an audit row rather than watched.
+ */
+export const useMcpTrace = (traceId, options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const otelUrl = useOtelUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.traceById(traceId ?? ''),
+        queryFn: () => fetchTraceSpans(token ?? '', traceId, otelUrl),
+        enabled: Boolean(token && otelUrl && traceId) && (options.enabled ?? true),
+        staleTime: 60_000,
+    });
+};
+/** The four SLIs and the catalog, platform-wide or for one agent or organization. */
+export const useMcpMetrics = (filters = {}, options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const otelUrl = useOtelUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.metrics(filters),
+        queryFn: () => fetchMcpMetrics(token ?? '', filters, otelUrl),
+        enabled: Boolean(token && otelUrl) && (options.enabled ?? true),
+        staleTime: 30_000,
+    });
+};
+/** The log lines of a run, gateway and worker alike, by its trace. */
+export const useMcpLogs = (taskUid, options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const otelUrl = useOtelUrl();
+    const task = useTask(taskUid);
+    return useQuery({
+        queryKey: queryKeys.mcp.logs(taskUid ?? ''),
+        queryFn: () => fetchMcpLogs(token ?? '', task.data, { limit: options.limit, severity: options.severity }, otelUrl),
+        enabled: Boolean(token && otelUrl && task.data) && (options.enabled ?? true),
+        staleTime: 15_000,
+        refetchInterval: task.data && !isMcpTaskTerminal(task.data.status) ? 5_000 : false,
+    });
+};
+// -- Operations (platform administrators) ----------------------------------
+export const useMcpWorkers = (options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const mcpUrl = useMcpServerUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.workers(),
+        queryFn: () => listWorkers(token ?? '', mcpUrl),
+        enabled: Boolean(token && mcpUrl) && (options.enabled ?? true),
+        staleTime: 5_000,
+        refetchInterval: 10_000,
+    });
+};
+export const useMcpWorkflowsHealth = (options = {}) => {
+    const token = useIAMStore(state => state.token);
+    const mcpUrl = useMcpServerUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.workflows(),
+        queryFn: () => getWorkflowsHealth(token ?? '', mcpUrl),
+        enabled: Boolean(token && mcpUrl) && (options.enabled ?? true),
+        staleTime: 10_000,
+        refetchInterval: 30_000,
+    });
+};
+/** The gateway's version and resource; no token needed. */
+export const useMcpGatewayVersion = () => {
+    const mcpUrl = useMcpServerUrl();
+    return useQuery({
+        queryKey: queryKeys.mcp.gatewayVersion(),
+        queryFn: () => getGatewayVersion(mcpUrl),
+        enabled: Boolean(mcpUrl),
+        staleTime: 300_000,
+    });
+};