doover-js 0.11.0 → 0.13.0

package/dist/esm/react/index.d.ts

@@ -0,0 +1,38 @@
+export { DooverProvider, useDooverClient } from "./context.js";
+export type { DooverProviderProps } from "./context.js";
+export type { DataClientStatus, DataClientConnectionState, AgentScope } from "../client/data-client.js";
+export { useClientStatus } from "./useClientStatus.js";
+export { useOfflineStatus, hasOfflineStatus } from "./useOfflineStatus.js";
+export type { OfflineStatusSnapshot, OfflineStatusClient } from "./useOfflineStatus.js";
+export { useConnectionState } from "./useConnectionState.js";
+export type { ConnectionState, ConnectionStatus } from "./useConnectionState.js";
+export { useAgentConnections, agentConnectionsQueryKey, } from "./useAgentConnections.js";
+export { useChannelSubscription, } from "./useChannelSubscription.js";
+export type { ChannelSubscriptionHandlers } from "./useChannelSubscription.js";
+export { useChannelAggregate, channelAggregateQueryKey, } from "./useChannelAggregate.js";
+export type { UseChannelAggregateOptions, UseChannelAggregateResult, } from "./useChannelAggregate.js";
+export { useAgentChannel } from "./useAgentChannel.js";
+export { useSendMessage } from "./useSendMessage.js";
+export type { UseSendMessageOptions } from "./useSendMessage.js";
+export { useUpdateAggregate } from "./useUpdateAggregate.js";
+export type { UseUpdateAggregateOptions } from "./useUpdateAggregate.js";
+export { useUpdateMessage } from "./useUpdateMessage.js";
+export type { UpdateMessageVariables, UseUpdateMessageOptions, } from "./useUpdateMessage.js";
+export { useChannelMessages, channelMessagesQueryKey, } from "./useChannelMessages.js";
+export type { UseChannelMessagesOptions, UseChannelMessagesResult, } from "./useChannelMessages.js";
+export { useChannelMessage, channelMessageQueryKey, } from "./useChannelMessage.js";
+export type { UseChannelMessageOptions, UseChannelMessageResult, } from "./useChannelMessage.js";
+export { useInvocationLogs, invocationLogsQueryKey, } from "./useInvocationLogs.js";
+export type { UseInvocationLogsOptions } from "./useInvocationLogs.js";
+export { useSendRpc } from "./useSendRpc.js";
+export type { RpcCommandId, RpcStatusEvent, SendRpcVariables, UseSendRpcOptions, UseSendRpcResult, } from "./useSendRpc.js";
+export { useMultiAgentAggregates, multiAgentAggregatesQueryKey, } from "./useMultiAgentAggregates.js";
+export type { UseMultiAgentAggregatesOptions, UseMultiAgentAggregatesResult, } from "./useMultiAgentAggregates.js";
+export { useMultiAgentChannelMessages, multiAgentChannelMessagesQueryKey, } from "./useMultiAgentChannelMessages.js";
+export type { UseMultiAgentChannelMessagesOptions, UseMultiAgentChannelMessagesResult, } from "./useMultiAgentChannelMessages.js";
+export { useDeviceMap } from "./useDeviceMap.js";
+export type { DeviceMapEntry, UseDeviceMapOptions, UseDeviceMapResult, } from "./useDeviceMap.js";
+export { useTurnCredentials } from "./useTurnCredentials.js";
+export { useAgentTokenState, useSetAgentTokenPolicy, useSetAgentAuthLock, useRevokeAgentTokens, useSetRevocationFloor, useCreateAdhocToken, useCreateDeviceToken, agentTokenStateQueryKey, } from "./useAgentTokenState.js";
+export type { UseAgentTokenStateOptions } from "./useAgentTokenState.js";
+export { getSharedQueryClient, resetSharedQueryClient, } from "./sharedQueryClient.js";

package/dist/esm/react/index.js

@@ -0,0 +1,21 @@
+export { DooverProvider, useDooverClient } from "./context.js";
+export { useClientStatus } from "./useClientStatus.js";
+export { useOfflineStatus, hasOfflineStatus } from "./useOfflineStatus.js";
+export { useConnectionState } from "./useConnectionState.js";
+export { useAgentConnections, agentConnectionsQueryKey, } from "./useAgentConnections.js";
+export { useChannelSubscription, } from "./useChannelSubscription.js";
+export { useChannelAggregate, channelAggregateQueryKey, } from "./useChannelAggregate.js";
+export { useAgentChannel } from "./useAgentChannel.js";
+export { useSendMessage } from "./useSendMessage.js";
+export { useUpdateAggregate } from "./useUpdateAggregate.js";
+export { useUpdateMessage } from "./useUpdateMessage.js";
+export { useChannelMessages, channelMessagesQueryKey, } from "./useChannelMessages.js";
+export { useChannelMessage, channelMessageQueryKey, } from "./useChannelMessage.js";
+export { useInvocationLogs, invocationLogsQueryKey, } from "./useInvocationLogs.js";
+export { useSendRpc } from "./useSendRpc.js";
+export { useMultiAgentAggregates, multiAgentAggregatesQueryKey, } from "./useMultiAgentAggregates.js";
+export { useMultiAgentChannelMessages, multiAgentChannelMessagesQueryKey, } from "./useMultiAgentChannelMessages.js";
+export { useDeviceMap } from "./useDeviceMap.js";
+export { useTurnCredentials } from "./useTurnCredentials.js";
+export { useAgentTokenState, useSetAgentTokenPolicy, useSetAgentAuthLock, useRevokeAgentTokens, useSetRevocationFloor, useCreateAdhocToken, useCreateDeviceToken, agentTokenStateQueryKey, } from "./useAgentTokenState.js";
+export { getSharedQueryClient, resetSharedQueryClient, } from "./sharedQueryClient.js";

package/dist/esm/react/messageRangeStore.d.ts

@@ -0,0 +1,93 @@
+import type { MessageStructure } from "../types/common.js";
+/**
+ * A per-channel cache of *proven-complete* id ranges.
+ *
+ * `useChannelMessages` models history as a chain of cursors: each page's oldest
+ * id is the next page's `before`. That chain is anchored at its first cursor, so
+ * two windows over the same channel are two unrelated chains — re-anchoring
+ * always refetches, even over data already held.
+ *
+ * This store keeps the fact the chain throws away. A response to
+ * `before=X, limit=N` is "the N newest messages strictly older than X", so a
+ * full page proves that *every* message in `[oldest.id, X)` is in hand. History
+ * is append-only, so that stays true forever. Overlapping windows then merge
+ * into one segment instead of duplicating, and revisiting a range costs nothing.
+ *
+ * The store sits under the query, not beside it: the chains stay as they are and
+ * remain the cache React Query sees, while this layer removes the network calls
+ * underneath them.
+ *
+ * Ids are decimal snowflakes of varying length, so every comparison goes through
+ * `BigInt` — string ordering would put "500" after "4000".
+ */
+/** A contiguous range of history we can prove we hold in full. */
+export interface RangeSegment {
+    /** Id of the oldest message held. Meaningless when `atStart` (coverage runs to -inf). */
+    lo: bigint;
+    /** Exclusive upper bound of proven coverage. */
+    hi: bigint;
+    /** No messages exist below `lo` — the channel (or its retention window) starts here. */
+    atStart: boolean;
+    /**
+     * `hi` tracks the live feed. Only true while a fetch has proven coverage up to
+     * roughly now AND the socket has not dropped since — see `sealTips`.
+     */
+    live: boolean;
+    /** Ascending by id. */
+    messages: MessageStructure[];
+}
+export declare class ChannelRangeStore {
+    /** Disjoint, ascending by `lo`. */
+    private segments;
+    /**
+     * Answer "the newest `limit` messages strictly older than `before`" from cache,
+     * or `undefined` when the range isn't proven and the caller must fetch.
+     *
+     * Returns ascending by id, matching `listMessages({ order: "asc" })`.
+     */
+    read(before: bigint, limit: number): MessageStructure[] | undefined;
+    /**
+     * Record a fetched page. `before` is the cursor actually sent and `limit` the
+     * one actually requested — a short page proves the range bottoms out, which is
+     * only sound because the server rejects an over-cap `limit` rather than
+     * silently clamping it.
+     */
+    record(params: {
+        before: bigint;
+        limit: number;
+        page: MessageStructure[];
+        /** Epoch ms the request was issued, for deciding whether this segment is live. */
+        at?: number;
+    }): void;
+    /**
+     * Extend the live segment with a pushed message. Ignored unless a segment is
+     * currently live: outside that, the message and the segment may have a gap
+     * between them, and claiming coverage across it would hide messages forever.
+     */
+    recordLive(message: MessageStructure): void;
+    /**
+     * Replace a message already held by one or more proven ranges. MessageUpdate
+     * carries the complete server representation, so both data and attachments
+     * supersede the cached create-time copy without changing range coverage.
+     */
+    recordUpdate(message: MessageStructure): void;
+    /**
+     * Stop trusting the live feed to extend coverage — call when the socket drops.
+     * Messages sent while disconnected would leave a hole, so segments go back to
+     * proving coverage by fetching.
+     */
+    sealTips(): void;
+    /** Test/debug view. */
+    snapshot(): RangeSegment[];
+    clear(): void;
+    /** Union `incoming` with every segment it overlaps or merely touches. */
+    private merge;
+}
+/**
+ * Stores are per *stream* — agent, channel, and any `fields` filter, which
+ * returns a different set of messages. Deliberately NOT per anchor: sharing
+ * across anchors is the entire point.
+ */
+export declare function getChannelRangeStore(key: string): ChannelRangeStore;
+/** Drop every store. Tests only — there is no eviction in normal operation. */
+export declare function resetChannelRangeStores(): void;

package/dist/esm/react/messageRangeStore.js

@@ -0,0 +1,140 @@
+/**
+ * How close to "now" a fetch's `before` must be for its segment to accept live
+ * pushes. Beyond this the feed and the segment may not be contiguous.
+ */
+const LIVE_PROOF_TOLERANCE_MS = 60000;
+const idOf = (message) => BigInt(message.id);
+function sortById(messages) {
+    return [...messages].sort((a, b) => (idOf(a) < idOf(b) ? -1 : idOf(a) > idOf(b) ? 1 : 0));
+}
+function dedupeById(messages) {
+    const seen = new Map();
+    // Later wins: a live push or a refetch supersedes an older copy
+    for (const message of messages)
+        seen.set(message.id, message);
+    return sortById([...seen.values()]);
+}
+export class ChannelRangeStore {
+    constructor() {
+        /** Disjoint, ascending by `lo`. */
+        this.segments = [];
+    }
+    /**
+     * Answer "the newest `limit` messages strictly older than `before`" from cache,
+     * or `undefined` when the range isn't proven and the caller must fetch.
+     *
+     * Returns ascending by id, matching `listMessages({ order: "asc" })`.
+     */
+    read(before, limit) {
+        const segment = this.segments.find((s) => before <= s.hi && (s.atStart || before >= s.lo));
+        if (!segment)
+            return undefined;
+        const older = segment.messages.filter((m) => idOf(m) < before);
+        if (older.length >= limit)
+            return older.slice(older.length - limit);
+        // Short of `limit` only tells us the range is exhausted if nothing precedes it
+        return segment.atStart ? older : undefined;
+    }
+    /**
+     * Record a fetched page. `before` is the cursor actually sent and `limit` the
+     * one actually requested — a short page proves the range bottoms out, which is
+     * only sound because the server rejects an over-cap `limit` rather than
+     * silently clamping it.
+     */
+    record(params) {
+        const { before, limit, page } = params;
+        const at = params.at ?? Date.now();
+        const messages = sortById(page);
+        const atStart = messages.length < limit;
+        const lo = messages.length > 0 ? idOf(messages[0]) : before;
+        const live = timestampOf(before) >= at - LIVE_PROOF_TOLERANCE_MS;
+        this.merge({ lo, hi: before, atStart, live, messages });
+    }
+    /**
+     * Extend the live segment with a pushed message. Ignored unless a segment is
+     * currently live: outside that, the message and the segment may have a gap
+     * between them, and claiming coverage across it would hide messages forever.
+     */
+    recordLive(message) {
+        const id = idOf(message);
+        const tip = this.segments.find((s) => s.live);
+        if (!tip || id < tip.lo)
+            return;
+        tip.messages = dedupeById([...tip.messages, message]);
+        if (id >= tip.hi)
+            tip.hi = id + 1n;
+    }
+    /**
+     * Replace a message already held by one or more proven ranges. MessageUpdate
+     * carries the complete server representation, so both data and attachments
+     * supersede the cached create-time copy without changing range coverage.
+     */
+    recordUpdate(message) {
+        for (const segment of this.segments) {
+            const index = segment.messages.findIndex((item) => item.id === message.id);
+            if (index >= 0)
+                segment.messages[index] = message;
+        }
+    }
+    /**
+     * Stop trusting the live feed to extend coverage — call when the socket drops.
+     * Messages sent while disconnected would leave a hole, so segments go back to
+     * proving coverage by fetching.
+     */
+    sealTips() {
+        for (const segment of this.segments)
+            segment.live = false;
+    }
+    /** Test/debug view. */
+    snapshot() {
+        return this.segments.map((s) => ({ ...s, messages: [...s.messages] }));
+    }
+    clear() {
+        this.segments = [];
+    }
+    /** Union `incoming` with every segment it overlaps or merely touches. */
+    merge(incoming) {
+        const overlapping = [];
+        const rest = [];
+        for (const segment of this.segments) {
+            // Touching counts: [a,b) and [b,c) are both proven, so [a,c) is too
+            const disjoint = segment.hi < incoming.lo || segment.lo > incoming.hi;
+            (disjoint ? rest : overlapping).push(segment);
+        }
+        const merged = overlapping.reduce((acc, s) => ({
+            lo: s.lo < acc.lo ? s.lo : acc.lo,
+            hi: s.hi > acc.hi ? s.hi : acc.hi,
+            atStart: acc.atStart || s.atStart,
+            live: acc.live || s.live,
+            messages: [...acc.messages, ...s.messages],
+        }), incoming);
+        merged.messages = dedupeById(merged.messages);
+        if (merged.atStart && merged.messages.length > 0) {
+            merged.lo = idOf(merged.messages[0]);
+        }
+        this.segments = [...rest, merged].sort((a, b) => (a.lo < b.lo ? -1 : a.lo > b.lo ? 1 : 0));
+    }
+}
+const SNOWFLAKE_EPOCH_MS = 1735689600000n;
+/** Epoch ms encoded in a snowflake, without going through the string round-trip. */
+function timestampOf(id) {
+    return Number((id >> 22n) + SNOWFLAKE_EPOCH_MS);
+}
+const stores = new Map();
+/**
+ * Stores are per *stream* — agent, channel, and any `fields` filter, which
+ * returns a different set of messages. Deliberately NOT per anchor: sharing
+ * across anchors is the entire point.
+ */
+export function getChannelRangeStore(key) {
+    let store = stores.get(key);
+    if (!store) {
+        store = new ChannelRangeStore();
+        stores.set(key, store);
+    }
+    return store;
+}
+/** Drop every store. Tests only — there is no eviction in normal operation. */
+export function resetChannelRangeStores() {
+    stores.clear();
+}

package/dist/esm/react/sharedQueryClient.d.ts

@@ -0,0 +1,21 @@
+import { QueryClient, type QueryClientConfig } from "@tanstack/react-query";
+/**
+ * Get a process-wide `QueryClient` instance, creating it on first call.
+ *
+ * Uses `globalThis.__doover_js_query_client__` so that every app + remote
+ * in a module-federation setup ends up with the same `QueryClient` — and
+ * therefore the same cache — even if they each load their own copy of the
+ * react-query library. The first caller's `config` wins.
+ *
+ * Wrap your tree once at the app root:
+ *
+ * ```tsx
+ * import { QueryClientProvider } from "@tanstack/react-query";
+ * import { getSharedQueryClient } from "doover-js/react";
+ *
+ * <QueryClientProvider client={getSharedQueryClient()}>…</QueryClientProvider>
+ * ```
+ */
+export declare function getSharedQueryClient(config?: QueryClientConfig): QueryClient;
+/** Test-only: clear the shared `QueryClient`. */
+export declare function resetSharedQueryClient(): void;

package/dist/esm/react/sharedQueryClient.js

@@ -0,0 +1,35 @@
+import { QueryClient, } from "@tanstack/react-query";
+const GLOBAL_KEY = "__doover_js_query_client__";
+function globalBag() {
+    return globalThis;
+}
+/**
+ * Get a process-wide `QueryClient` instance, creating it on first call.
+ *
+ * Uses `globalThis.__doover_js_query_client__` so that every app + remote
+ * in a module-federation setup ends up with the same `QueryClient` — and
+ * therefore the same cache — even if they each load their own copy of the
+ * react-query library. The first caller's `config` wins.
+ *
+ * Wrap your tree once at the app root:
+ *
+ * ```tsx
+ * import { QueryClientProvider } from "@tanstack/react-query";
+ * import { getSharedQueryClient } from "doover-js/react";
+ *
+ * <QueryClientProvider client={getSharedQueryClient()}>…</QueryClientProvider>
+ * ```
+ */
+export function getSharedQueryClient(config) {
+    const bag = globalBag();
+    const existing = bag[GLOBAL_KEY];
+    if (existing)
+        return existing;
+    const client = new QueryClient(config);
+    bag[GLOBAL_KEY] = client;
+    return client;
+}
+/** Test-only: clear the shared `QueryClient`. */
+export function resetSharedQueryClient() {
+    delete globalBag()[GLOBAL_KEY];
+}

package/dist/esm/react/useAgentChannel.d.ts

@@ -0,0 +1,8 @@
+import type { Aggregate } from "../types/common.js";
+import { type UseChannelAggregateOptions } from "./useChannelAggregate.js";
+/**
+ * Convenience wrapper around `useChannelAggregate` that accepts an agent id
+ * and channel name as separate arguments — the most common shape at call
+ * sites where the identifier isn't already a `ChannelIdentifier`.
+ */
+export declare function useAgentChannel<TData = Aggregate["data"]>(agentId: string | undefined, channelName: string, options?: UseChannelAggregateOptions): import("./useChannelAggregate.js").UseChannelAggregateResult<TData>;

package/dist/esm/react/useAgentChannel.js

@@ -0,0 +1,9 @@
+import { useChannelAggregate, } from "./useChannelAggregate.js";
+/**
+ * Convenience wrapper around `useChannelAggregate` that accepts an agent id
+ * and channel name as separate arguments — the most common shape at call
+ * sites where the identifier isn't already a `ChannelIdentifier`.
+ */
+export function useAgentChannel(agentId, channelName, options) {
+    return useChannelAggregate({ agentId, channelName }, options);
+}

package/dist/esm/react/useAgentConnections.d.ts

@@ -0,0 +1,8 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { ConnectionDetails } from "../types/common.js";
+export declare function agentConnectionsQueryKey(agentId: string | undefined): readonly ["doover", "agent", string | undefined, "connections"];
+/**
+ * Fetch the list of active WSS connections for an agent. Query key:
+ * `["doover", "agent", agentId, "connections"]`.
+ */
+export declare function useAgentConnections(agentId: string | undefined): UseQueryResult<ConnectionDetails[]>;

package/dist/esm/react/useAgentConnections.js

@@ -0,0 +1,20 @@
+import { useQuery } from "@tanstack/react-query";
+import { useDooverClient } from "./context.js";
+export function agentConnectionsQueryKey(agentId) {
+    return ["doover", "agent", agentId, "connections"];
+}
+/**
+ * Fetch the list of active WSS connections for an agent. Query key:
+ * `["doover", "agent", agentId, "connections"]`.
+ */
+export function useAgentConnections(agentId) {
+    const client = useDooverClient();
+    return useQuery({
+        queryKey: agentConnectionsQueryKey(agentId),
+        enabled: !!agentId,
+        staleTime: 30000,
+        queryFn: () => agentId
+            ? client.connections.getAgentConnections(agentId)
+            : Promise.resolve([]),
+    });
+}

package/dist/esm/react/useAgentTokenState.d.ts

@@ -0,0 +1,70 @@
+import { type UseQueryResult } from "@tanstack/react-query";
+import type { AgentTokenPolicy, AgentTokenState, ResourcePermission } from "../apis/agents-api.js";
+export declare function agentTokenStateQueryKey(agentId: string | undefined): readonly ["doover", "agent", string | null, "tokenState"];
+export interface UseAgentTokenStateOptions {
+    enabled?: boolean;
+    staleTime?: number;
+}
+/**
+ * Read an agent's credential state — revocation floor, auth kill-switch, and the
+ * token posture resolved across the per-agent override and organisation default.
+ *
+ * Deliberately short `staleTime`: `auth_locked` can be flipped by doover-data
+ * itself (automatic lockout on suspected token reuse), so this value changes
+ * without any action from this client. Showing a stale "not locked" on the one
+ * screen someone opens *because* their device went offline would be worse than
+ * an extra fetch.
+ */
+export declare function useAgentTokenState(agentId: string | undefined, options?: UseAgentTokenStateOptions): UseQueryResult<AgentTokenState>;
+/**
+ * Write an agent's token-posture override. Full replacement — a null field means
+ * "inherit the organisation default".
+ *
+ * Invalidates the token-state query on success so the inherited-vs-overridden
+ * display reflects the write without the caller wiring that up.
+ */
+export declare function useSetAgentTokenPolicy(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<{
+    effective: AgentTokenPolicy;
+}, Error, AgentTokenPolicy, unknown>;
+/** Set or clear the auth kill-switch. */
+export declare function useSetAgentAuthLock(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<void, Error, boolean, unknown>;
+/**
+ * Mint a short-lived scoped token for ad-hoc access to an agent.
+ *
+ * Does not invalidate the token-state query: an ad-hoc token is a JWT with its
+ * own expiry and doesn't touch the revocation floor or the agent's posture, so
+ * there is nothing in that query for it to change.
+ *
+ * The resulting token is returned once and is not retrievable afterwards — hand
+ * it straight to the user and don't cache it.
+ */
+export declare function useCreateAdhocToken(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<import("../apis/agents-api.js").AdhocTokenResponse, Error, {
+    permissions?: ResourcePermission[];
+    timeout?: number;
+}, unknown>;
+/**
+ * Set the revocation floor to an explicit point; pass `0` or `null` to clear it.
+ *
+ * Lowering it reverses a revocation, so this is for undoing one made by mistake
+ * rather than for recovering a device whose credentials leaked.
+ */
+export declare function useSetRevocationFloor(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<{
+    tokens_valid_from: number | null;
+}, Error, number | null, unknown>;
+/**
+ * Mint the device's long-lived credential for manual provisioning, returned once.
+ *
+ * Invalidates the token-state query so the revocation floor display stays honest
+ * — the mint itself is additive and doesn't move the floor, but refetching keeps
+ * this in step with anything else that has changed since the panel loaded.
+ */
+export declare function useCreateDeviceToken(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<import("../apis/agents-api.js").DeviceTokenResponse, Error, void, unknown>;
+/**
+ * Revoke every outstanding long-lived credential for an agent.
+ *
+ * Break-glass: the device stays offline until it is re-provisioned. Confirm with
+ * the user before calling.
+ */
+export declare function useRevokeAgentTokens(agentId: string | undefined): import("@tanstack/react-query").UseMutationResult<{
+    tokens_valid_from: number;
+}, Error, void, unknown>;

package/dist/esm/react/useAgentTokenState.js

@@ -0,0 +1,127 @@
+import { useMutation, useQuery, useQueryClient, } from "@tanstack/react-query";
+import { useDooverClient } from "./context.js";
+export function agentTokenStateQueryKey(agentId) {
+    return ["doover", "agent", agentId ?? null, "tokenState"];
+}
+/**
+ * Read an agent's credential state — revocation floor, auth kill-switch, and the
+ * token posture resolved across the per-agent override and organisation default.
+ *
+ * Deliberately short `staleTime`: `auth_locked` can be flipped by doover-data
+ * itself (automatic lockout on suspected token reuse), so this value changes
+ * without any action from this client. Showing a stale "not locked" on the one
+ * screen someone opens *because* their device went offline would be worse than
+ * an extra fetch.
+ */
+export function useAgentTokenState(agentId, options) {
+    const client = useDooverClient();
+    return useQuery({
+        queryKey: agentTokenStateQueryKey(agentId),
+        enabled: (options?.enabled ?? true) && Boolean(agentId),
+        staleTime: options?.staleTime ?? 15 * 1000,
+        queryFn: () => client.agents.getTokenState(agentId),
+    });
+}
+/**
+ * Write an agent's token-posture override. Full replacement — a null field means
+ * "inherit the organisation default".
+ *
+ * Invalidates the token-state query on success so the inherited-vs-overridden
+ * display reflects the write without the caller wiring that up.
+ */
+export function useSetAgentTokenPolicy(agentId) {
+    const client = useDooverClient();
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (policy) => client.agents.setTokenPolicy(agentId, policy),
+        onSuccess: () => {
+            void queryClient.invalidateQueries({
+                queryKey: agentTokenStateQueryKey(agentId),
+            });
+        },
+    });
+}
+/** Set or clear the auth kill-switch. */
+export function useSetAgentAuthLock(agentId) {
+    const client = useDooverClient();
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (locked) => client.agents.setAuthLock(agentId, locked),
+        onSuccess: () => {
+            void queryClient.invalidateQueries({
+                queryKey: agentTokenStateQueryKey(agentId),
+            });
+        },
+    });
+}
+/**
+ * Mint a short-lived scoped token for ad-hoc access to an agent.
+ *
+ * Does not invalidate the token-state query: an ad-hoc token is a JWT with its
+ * own expiry and doesn't touch the revocation floor or the agent's posture, so
+ * there is nothing in that query for it to change.
+ *
+ * The resulting token is returned once and is not retrievable afterwards — hand
+ * it straight to the user and don't cache it.
+ */
+export function useCreateAdhocToken(agentId) {
+    const client = useDooverClient();
+    return useMutation({
+        mutationFn: (options) => client.agents.createAdhocToken(agentId, options),
+    });
+}
+/**
+ * Set the revocation floor to an explicit point; pass `0` or `null` to clear it.
+ *
+ * Lowering it reverses a revocation, so this is for undoing one made by mistake
+ * rather than for recovering a device whose credentials leaked.
+ */
+export function useSetRevocationFloor(agentId) {
+    const client = useDooverClient();
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: (tokensValidFrom) => client.agents.setRevocationFloor(agentId, tokensValidFrom),
+        onSuccess: () => {
+            void queryClient.invalidateQueries({
+                queryKey: agentTokenStateQueryKey(agentId),
+            });
+        },
+    });
+}
+/**
+ * Mint the device's long-lived credential for manual provisioning, returned once.
+ *
+ * Invalidates the token-state query so the revocation floor display stays honest
+ * — the mint itself is additive and doesn't move the floor, but refetching keeps
+ * this in step with anything else that has changed since the panel loaded.
+ */
+export function useCreateDeviceToken(agentId) {
+    const client = useDooverClient();
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: () => client.agents.createDeviceToken(agentId),
+        onSuccess: () => {
+            void queryClient.invalidateQueries({
+                queryKey: agentTokenStateQueryKey(agentId),
+            });
+        },
+    });
+}
+/**
+ * Revoke every outstanding long-lived credential for an agent.
+ *
+ * Break-glass: the device stays offline until it is re-provisioned. Confirm with
+ * the user before calling.
+ */
+export function useRevokeAgentTokens(agentId) {
+    const client = useDooverClient();
+    const queryClient = useQueryClient();
+    return useMutation({
+        mutationFn: () => client.agents.revokeAllTokens(agentId),
+        onSuccess: () => {
+            void queryClient.invalidateQueries({
+                queryKey: agentTokenStateQueryKey(agentId),
+            });
+        },
+    });
+}