@datalayer/core 1.2.27 → 1.2.29

package/lib/hooks/useDatalayer.js

@@ -67,23 +67,19 @@ export function useDatalayer(props = {}) {
                 }
                 else {
                     if (notifyOnError_ && !isForbidden) {
-                        if (responseError.warnings) {
-                            responseError.warnings.forEach(warning => enqueueToast(`${warning}`, { variant: 'warning' }));
-                        }
-                        if (responseError.errors) {
-                            responseError.errors.forEach(error => enqueueToast(`${error}`, { variant: 'error' }));
-                        }
-                        if (responseError.message) {
-                            enqueueToast(`${responseError.message}`, { variant: 'error' });
-                        }
-                        else {
-                            enqueueToast(`API Error`, { variant: 'error' });
-                        }
-                        if (responseError.exceptionMessage) {
-                            enqueueToast(`${responseError.exceptionMessage}`, {
-                                variant: 'error',
-                            });
+                        // One toast per failed request, its lines together and each once
+                        // (2 November 2026: its message and its exception were a toast
+                        // each, so a page that asked twice showed four).
+                        const once = (lines) => Array.from(new Set(lines.map(line => `${line ?? ''}`.trim()).filter(Boolean))).join('\n');
+                        const warnings = once(responseError.warnings ?? []);
+                        if (warnings) {
+                            enqueueToast(warnings, { variant: 'warning' });
                         }
+                        enqueueToast(once([
+                            ...(responseError.errors ?? []),
+                            responseError.message || 'API Error',
+                            responseError.exceptionMessage,
+                        ]), { variant: 'error' });
                     }
                 }
                 const response = {

package/lib/hooks/useKeptScroll.d.ts

@@ -0,0 +1,6 @@
+/** The nearest ancestor of `marker` that scrolls vertically, if any. */
+export declare function scrollingAncestor(marker: HTMLElement | null): HTMLElement | null;
+/** Where the sidebar kept under `key` was last scrolled to, if it was. */
+export declare const keptScrollOf: (key: string) => number | undefined;
+export declare function useKeptScroll<T extends HTMLElement = HTMLElement>(key: string): import("react").RefObject<T | null>;
+export default useKeptScroll;

package/lib/hooks/useKeptScroll.js

@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * A sidebar keeps its scroll across pages: an entry pressed far down the list
+ * leaves the list where it was, so the next one is still under the pointer.
+ *
+ * `useKeptScroll(key)` returns a ref for a small element placed inside the
+ * sidebar; the nearest ancestor that scrolls is the one kept. Its position is
+ * remembered under `key` while it scrolls, and given back when a sidebar with
+ * the same key is mounted again (a layout rendered anew by the next route).
+ * The panel must not be one `useNavigate` brings to the top: it is not marked
+ * `data-scroll-root`.
+ *
+ * @module hooks/useKeptScroll
+ */
+import { useLayoutEffect, useRef } from 'react';
+const kept = new Map();
+const scrollsY = (element) => {
+    const overflow = window.getComputedStyle(element).overflowY;
+    return overflow === 'auto' || overflow === 'scroll';
+};
+/** The nearest ancestor of `marker` that scrolls vertically, if any. */
+export function scrollingAncestor(marker) {
+    let element = marker?.parentElement ?? null;
+    while (element && !scrollsY(element)) {
+        element = element.parentElement;
+    }
+    return element;
+}
+/** Where the sidebar kept under `key` was last scrolled to, if it was. */
+export const keptScrollOf = (key) => kept.get(key);
+export function useKeptScroll(key) {
+    const ref = useRef(null);
+    useLayoutEffect(() => {
+        const panel = scrollingAncestor(ref.current);
+        if (!panel) {
+            return;
+        }
+        const saved = kept.get(key);
+        if (saved !== undefined) {
+            panel.scrollTop = saved;
+        }
+        const remember = () => kept.set(key, panel.scrollTop);
+        panel.addEventListener('scroll', remember, { passive: true });
+        return () => {
+            remember();
+            panel.removeEventListener('scroll', remember);
+        };
+    }, [key]);
+    return ref;
+}
+export default useKeptScroll;

package/lib/hooks/useMcp.d.ts

@@ -1,4 +1,4 @@
-import { type McpTaskAnswered, type McpActivity, type McpActivityFilters, type McpAuditFilters, type McpBindingListFilters, type McpGatewayVersion, type McpMetricsFilters, type McpMetricsSnapshot, type McpOrganizationOverview, type McpOrganizationUsage, type McpOrganizationOverviewFilters, type McpPolicyFilters, type McpRunLogs, type McpRunTrace, type McpTaskEvent, type McpTaskListFilters, type McpWorkerList, type McpWorkflowsHealth } from '../api/mcp';
+import { type McpTaskAnswered, type McpTaskCancelled, type McpActivity, type McpActivityFilters, type McpAuditFilters, type McpBindingListFilters, type McpGatewayVersion, type McpMetricsFilters, type McpMetricsSnapshot, type McpOrganizationOverview, type McpOrganizationUsage, type McpOrganizationOverviewFilters, type McpPolicyFilters, type McpRunLogs, type McpRunTrace, type McpTaskEvent, type McpTaskListFilters, type McpWorkerList, type McpWorkflowsHealth } from '../api/mcp';
 import { type ConnectedAgent } from '../api/iam/connectedAgents';
 import { type OrganizationTeam } from '../api/iam/organizationTeams';
 import { setAuditSettings, type McpAuditSettings } from '../api/iam/mcpAuditSettings';
@@ -28,7 +28,7 @@ export declare const useTaskEvents: (taskUid?: string, options?: {
     enabled?: boolean;
     onEvent?: (event: McpTaskEvent) => void;
 }) => void;
-export declare const useCancelTask: () => import("@tanstack/react-query").UseMutationResult<McpTask, Error, string, unknown>;
+export declare const useCancelTask: () => import("@tanstack/react-query").UseMutationResult<McpTaskCancelled, Error, string, unknown>;
 export declare const useAnswerTask: () => import("@tanstack/react-query").UseMutationResult<McpTaskAnswered, Error, {
     taskUid: string;
     input: Record<string, unknown>;

package/lib/hooks/useMcp.js

@@ -124,8 +124,11 @@ export const useCancelTask = () => {
     const mcpUrl = useMcpServerUrl();
     return useMutation({
         mutationFn: taskUid => cancelTask(token ?? '', taskUid, mcpUrl),
-        onSuccess: task => {
-            queryClient.setQueryData(queryKeys.mcp.task(task.uid), task);
+        // The gateway answers `{uid, cancelled, status}`, not the task: read the
+        // task again rather than caching that reply in its place (the run page
+        // lost its tool and output on a cancel, as it did on an answer).
+        onSuccess: (_cancelled, taskUid) => {
+            queryClient.invalidateQueries({ queryKey: queryKeys.mcp.task(taskUid) });
             queryClient.invalidateQueries({ queryKey: queryKeys.mcp.tasks() });
             queryClient.invalidateQueries({ queryKey: queryKeys.mcp.activity() });
         },

package/lib/hooks/useNavigate.d.ts

@@ -5,8 +5,15 @@ export interface NavigateOptions {
     state?: unknown;
     /** Open the destination in a new tab and leave this one where it is. */
     newTab?: boolean;
-    /** Scroll to the top on arrival; on by default. */
-    scroll?: boolean;
+    /**
+     * Where the reader lands: the top of the page when unsaid or `true`; an
+     * element, by its id (with or without its `#`), scrolled into view once
+     * the page has it; `false` to leave the scroll where it is. The page and
+     * every scroll panel marked `data-scroll-root` are scrolled, so a layout
+     * that scrolls inside its own panel lands at the top too (the user,
+     * 6 November 2026: the Trust page opened scrolled down).
+     */
+    scroll?: boolean | string;
     /**
      * Close the layout's side portals on the way; on by default. Only the
      * history API host has them.
@@ -40,5 +47,12 @@ export type Navigate = (to: NavigateTarget, optionsOrEvent?: NavigateOptions | N
 export declare function isNewTabClick(event: NavigateEvent): boolean;
 /** Open `to` in a new tab, without handing it this window. */
 export declare function openInNewTab(to: string): void;
+/**
+ * Scroll on arrival: to the top (`undefined` or `true`), to an element by
+ * its id (a string, `#` or not), or nowhere (`false`). Done now and again
+ * on the next frames, since the page navigated to renders after the call
+ * and a layout's panel keeps its scroll across pages.
+ */
+export declare function scrollOnArrival(target: boolean | string | undefined): void;
 export declare const useNavigate: () => Navigate;
 export default useNavigate;

package/lib/hooks/useNavigate.js

@@ -62,6 +62,68 @@ function isLinkTo(event, to) {
         return false;
     }
 }
+/**
+ * The scroll panels a layout marks, beside the page itself: `data-scroll-root`,
+ * or the `dla-scroll-root` class for a component that passes a class name but
+ * no data attribute (Primer's `PageLayout.Content`, whose own element is the
+ * one that scrolls; 9 November 2026, a card on /agentspecs/identities opened
+ * its page scrolled down).
+ */
+const scrollRoots = () => Array.from(document.querySelectorAll('[data-scroll-root], .dla-scroll-root'));
+const nextFrame = (run) => {
+    if (typeof requestAnimationFrame === 'function') {
+        requestAnimationFrame(run);
+    }
+    else {
+        setTimeout(run, 16);
+    }
+};
+/** How many frames an element is waited for: a page loaded lazily takes a few. */
+const ARRIVAL_FRAMES = 60;
+/**
+ * Scroll on arrival: to the top (`undefined` or `true`), to an element by
+ * its id (a string, `#` or not), or nowhere (`false`). Done now and again
+ * on the next frames, since the page navigated to renders after the call
+ * and a layout's panel keeps its scroll across pages.
+ */
+export function scrollOnArrival(target) {
+    if (target === false || typeof document === 'undefined') {
+        return;
+    }
+    const id = typeof target === 'string' ? target.replace(/^#/, '') : '';
+    if (!id) {
+        const toTop = () => {
+            window.scrollTo(0, 0);
+            document.body.scrollTop = 0;
+            document.documentElement.scrollTop = 0;
+            for (const root of scrollRoots()) {
+                root.scrollTop = 0;
+            }
+        };
+        toTop();
+        let frames = 0;
+        const again = () => {
+            toTop();
+            if (++frames < 2) {
+                nextFrame(again);
+            }
+        };
+        nextFrame(again);
+        return;
+    }
+    let tries = 0;
+    const attempt = () => {
+        const element = document.getElementById(id);
+        if (element) {
+            element.scrollIntoView({ block: 'start' });
+            return;
+        }
+        if (++tries < ARRIVAL_FRAMES) {
+            nextFrame(attempt);
+        }
+    };
+    attempt();
+}
 const isEvent = (value) => !!value && typeof value.preventDefault === 'function';
 function parseCall(optionsOrEvent, third, fourth) {
     if (isEvent(optionsOrEvent)) {
@@ -129,10 +191,7 @@ export const useNavigate = () => {
             return;
         }
         event?.preventDefault();
-        if (options.scroll !== false) {
-            window.scrollTo(0, 0);
-            document.body.scrollTop = 0;
-        }
+        scrollOnArrival(options.scroll);
         // Where the reader is now, for the shell they are in. A new tab and a
         // step back through history are both already past by here. Only for
         // somebody signed in: the shells are theirs, and a page a visitor read
@@ -152,7 +211,8 @@ export const useNavigate = () => {
         nativeNavigate(to, {
             replace: options.replace,
             state: options.state,
-            scroll: options.scroll,
+            // Scrolled above, after the page has rendered.
+            scroll: false,
         });
     }, [rrNavigate, nativeNavigate, layoutStore]);
 };

package/lib/hooks/useToast.d.ts

@@ -14,6 +14,12 @@ export type ToastProps = {
      */
     variant: 'info' | 'success' | 'warning' | 'error';
 };
+/**
+ * Toasts in JupyterLab, as they always were: its notifications, or
+ * react-toastify until they are loaded. Everywhere else (the SaaS, the
+ * desktop…) they go to `ToastPanel`, primer-addons' sliding panel, which the
+ * application mounts once (2 November 2026).
+ */
 export declare const useToast: () => Readonly<{
     /**
      * Emit a message as a toast.

package/lib/hooks/useToast.js

@@ -3,6 +3,7 @@ import React from 'react';
 import { toast } from 'react-toastify';
 import { Button } from '@primer/react';
 import { isInsideJupyterLab } from '../utils/index.js';
+import { defaultAutoClose, toastQueue } from '../components/toast/toastQueue.js';
 // `@datalayer/jupyter-react` and `@jupyterlab/apputils` are heavy (they pull
 // JupyterLab / CodeMirror / lumino) and are only needed when running INSIDE
 // JupyterLab. They are lazily loaded here so the standalone bundle (landing app)
@@ -76,11 +77,25 @@ function createContent(message, closeHandler, actions) {
                         return (_jsx(React.Suspense, { fallback: null, children: _jsx(JupyterReactTheme, { children: _jsx(ToastButton, { action: action, closeToast: closeHandler }) }) }, 'button-' + idx));
                     })] }))] }));
 }
+/**
+ * Toasts in JupyterLab, as they always were: its notifications, or
+ * react-toastify until they are loaded. Everywhere else (the SaaS, the
+ * desktop…) they go to `ToastPanel`, primer-addons' sliding panel, which the
+ * application mounts once (2 November 2026).
+ */
 export const useToast = () => {
     // This CANNOT use Jupyter React hooks as it may be used outside Jupyter React context.
     const insideJupyterLab = isInsideJupyterLab();
     const enqueueToast = (message, options = { variant: 'info' }) => {
         const { actions, autoClose } = options;
+        if (!insideJupyterLab) {
+            return toastQueue.push({
+                variant: options.variant,
+                message,
+                actions,
+                autoClose: autoClose ?? defaultAutoClose(options.variant),
+            });
+        }
         const theme = resolveToastTheme();
         switch (options.variant) {
             case 'info': {
@@ -138,6 +153,27 @@ export const useToast = () => {
         }
     };
     const trackAsyncTask = (promise, options) => {
+        if (!insideJupyterLab) {
+            // One toast for the task: pending, then what it came to.
+            const message = (value, result) => typeof value === 'function'
+                ? String(value(result))
+                : String(value);
+            const id = toastQueue.push({
+                variant: 'info',
+                message: message(options.pending.message, undefined),
+                autoClose: false,
+            });
+            promise.then(result => toastQueue.update(id, {
+                variant: 'success',
+                message: message(options.success.message, result),
+                autoClose: defaultAutoClose('success'),
+            }), reason => toastQueue.update(id, {
+                variant: 'error',
+                message: message(options.error.message, reason),
+                autoClose: defaultAutoClose('error'),
+            }));
+            return id;
+        }
         const theme = resolveToastTheme();
         return insideJupyterLab && NotificationApi
             ? NotificationApi.promise(promise, options)
@@ -169,7 +205,10 @@ export const useToast = () => {
          * @param id Toast id
          */
         dismiss: (id) => {
-            if (insideJupyterLab && NotificationApi) {
+            if (!insideJupyterLab) {
+                toastQueue.dismiss(id === undefined ? undefined : String(id));
+            }
+            else if (insideJupyterLab && NotificationApi) {
                 NotificationApi.dismiss(id);
             }
             else {

package/lib/models/McpAgentAccess.d.ts

@@ -0,0 +1,95 @@
+/**
+ * What one agent may execute and reach, as the Jupyter MCP Server decides it.
+ *
+ * Every answer here comes from the steps a call goes through — the token's
+ * scopes, the policy layers, then Spacer or Contents for the object — so a
+ * tool or a notebook listed as refused is one the agent would be refused.
+ *
+ * @module models/McpAgentAccess
+ */
+/** The agent an answer is about. `grant` is null for the token that asked. */
+export interface McpAgentNamed {
+    grant: string | null;
+    clientId: string | null;
+    clientName: string | null;
+    scopes: string[];
+    orgUid: string | null;
+    teamUid: string | null;
+}
+export type McpToolsetHealthState = 'ready' | 'degraded' | 'unknown';
+export interface McpToolsetHealth {
+    /** `unknown` is a toolset nothing here measures, never one reported well. */
+    state: McpToolsetHealthState;
+    detail: string;
+}
+/**
+ * How a client comes to hold a toolset: the plain endpoint serves `base`, a
+ * URL names an `optional` one, a `source` is enabled in a session, and an
+ * `application` one is reached through an application's connection.
+ */
+export type McpToolsetSelected = 'base' | 'optional' | 'source' | 'application';
+/** One tool, decided for this agent. */
+export interface McpAgentTool {
+    name: string;
+    /** The scopes it requires, space-separated. */
+    scope: string;
+    allowed: boolean;
+    /** Why not: `scope`, a policy rule, `connection` or `item`. */
+    rule: string | null;
+    /** Which layer decided. */
+    decidedBy: string | null;
+    detail: string | null;
+    /** The layer that makes a person approve a call first, when one does. */
+    approval: string | null;
+}
+/** A source's own rule for its calls, as Contents keeps it. */
+export type McpSourceApprovalPolicy = 'explicit' | 'auto-allowlisted' | 'never';
+export interface McpAgentToolset {
+    kind: 'toolset' | 'source';
+    /** The source, when it is one. */
+    uid?: string;
+    name: string;
+    title: string;
+    description: string | null;
+    selected: McpToolsetSelected;
+    health: McpToolsetHealth;
+    /** A source's; a toolset's tools each say their own `approval`. */
+    approvalPolicy: McpSourceApprovalPolicy | null;
+    tools: McpAgentTool[];
+}
+export interface McpAgentToolsets {
+    agent: McpAgentNamed;
+    toolsets: McpAgentToolset[];
+    /** Why the sources are missing, when Contents could not be read. */
+    sourcesError: string | null;
+}
+/** One notebook or source, and how far this agent reaches it. */
+export interface McpReachRow {
+    kind: 'notebook' | 'source';
+    uid: string;
+    name: string;
+    /** A notebook's Space, a source's kind. */
+    where: string | null;
+    read: boolean;
+    write: boolean;
+    execute: boolean;
+    /** Why it stops short of `execute`, in sentences. */
+    refused: string[];
+    /** Whether a source is the caller's own. */
+    yours?: boolean;
+    /** Set when the check could not run: an answer about the check, not the agent. */
+    unchecked: string | null;
+}
+export interface McpAgentReach {
+    agent: McpAgentNamed;
+    notebooks: McpReachRow[];
+    sources: McpReachRow[];
+    /** How many there are of each, of which `limit` were asked about. */
+    notebooksListed: number;
+    sourcesListed: number;
+    limit: number;
+    /** Contents has more than were read. */
+    sourcesTruncated: boolean;
+    notebooksError: string | null;
+    sourcesError: string | null;
+}

package/lib/models/McpAgentAccess.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export {};

package/lib/models/Usage.d.ts

@@ -8,6 +8,15 @@ interface IResources {
     memory: string;
     'nvidia.com/gpu'?: string;
 }
+/**
+ * What ran and hosted the agent a usage record is for (`runtime_engine`):
+ * a Datalayer runtime, kagent, or AWS AgentCore in an organization's AWS
+ * account. IAM records it from the launch; a record from before, or of a
+ * call with no agent runtime behind it, has none.
+ */
+export type UsageRuntimeEngine = 'datalayer' | 'kagent' | 'agentcore';
+/** The engine a raw record says, or `undefined` when it says none (or one not known). */
+export declare const usageRuntimeEngineOf: (value: unknown) => UsageRuntimeEngine | undefined;
 export interface IRawUsage {
     account_uid: string;
     resource_uid: string;
@@ -26,6 +35,7 @@ export interface IRawUsage {
     usage_period_label?: string;
     usage_period_start?: string;
     usage_period_end?: string;
+    runtime_engine?: UsageRuntimeEngine | null;
     metadata: Map<string, string>;
 }
 export declare const asUsage: (u: any) => {
@@ -46,6 +56,7 @@ export declare const asUsage: (u: any) => {
     usagePeriodLabel: any;
     usagePeriodStart: Date | undefined;
     usagePeriodEnd: Date | undefined;
+    runtimeEngine: UsageRuntimeEngine | undefined;
     metadata: Map<string, string>;
 };
 export interface IUsage {
@@ -66,6 +77,8 @@ export interface IUsage {
     usagePeriodLabel?: string;
     usagePeriodStart?: Date;
     usagePeriodEnd?: Date;
+    /** What ran and hosted its agent; absent on a record that says none. */
+    runtimeEngine?: UsageRuntimeEngine;
     metadata: Map<string, string>;
 }
 export {};

package/lib/models/Usage.js

@@ -2,6 +2,10 @@
  * Copyright (c) 2023-2025 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
+/** The engine a raw record says, or `undefined` when it says none (or one not known). */
+export const usageRuntimeEngineOf = (value) => value === 'datalayer' || value === 'kagent' || value === 'agentcore'
+    ? value
+    : undefined;
 export const asUsage = (u) => {
     const usagePeriodKey = u.usage_period_key;
     const usagePeriodLabel = u.usage_period_label;
@@ -25,6 +29,7 @@ export const asUsage = (u) => {
         usagePeriodLabel,
         usagePeriodStart: usagePeriodStart ? new Date(usagePeriodStart) : undefined,
         usagePeriodEnd: usagePeriodEnd ? new Date(usagePeriodEnd) : undefined,
+        runtimeEngine: usageRuntimeEngineOf(u.runtime_engine),
         metadata: new Map(Object.entries(u.metadata ?? {})),
     };
 };

package/lib/models/index.d.ts

@@ -51,6 +51,7 @@ export * from './Invite';
 export * from './LandingRoles';
 export * from './McpAuditEvent';
 export * from './McpBinding';
+export * from './McpAgentAccess';
 export * from './McpPolicy';
 export * from './McpTask';
 export * from './Member';

package/lib/models/index.js

@@ -55,6 +55,7 @@ export * from './Invite.js';
 export * from './LandingRoles.js';
 export * from './McpAuditEvent.js';
 export * from './McpBinding.js';
+export * from './McpAgentAccess.js';
 export * from './McpPolicy.js';
 export * from './McpTask.js';
 export * from './Member.js';

package/lib/otel/client/OtelClient.d.ts

@@ -1,5 +1,53 @@
 import type { OtelSpan, OtelLog, OtelMetric, OtelQueryResult } from '../types';
 import type { OtelSystemData, OtelSystemProcess, OtelSystemDisk, OtelSystemTable } from '../hooks';
+export interface FetchTokenUsageOptions {
+    /** The window, in hours back from now (24 by default). */
+    hours?: number;
+    /** Only these services (runtimes); every one by default. */
+    serviceNames?: string[];
+    accountUid?: string;
+}
+/** What `GET /api/otel/v1/metrics/tokens` answers. */
+export interface OtelTokenUsage {
+    total: number;
+    prompt: number;
+    completion: number;
+    by_service: Array<{
+        service_name: string;
+        total: number;
+        prompt: number;
+        completion: number;
+    }>;
+    window?: {
+        start: number;
+        end: number;
+        hours: number;
+    };
+    /**
+     * When telemetry last reached the store, whatever the account: `at` in
+     * unix nanoseconds, from rows ingested since the service started
+     * (`ingest`) or from its newest stored file (`files`); `null` with the
+     * `reason` when nothing was ever stored or the time could not be read.
+     * Absent from a service that does not say it.
+     */
+    last_received?: OtelLastReceived;
+    /**
+     * The same for the asked account, known only from what arrived since the
+     * service started (`since`, unix nanoseconds): `at` is `null`, with a
+     * `reason`, until rows of the account arrive.
+     */
+    account_last_received?: OtelAccountLastReceived;
+}
+export interface OtelLastReceived {
+    at: number | null;
+    source: 'ingest' | 'files' | null;
+    reason: string | null;
+}
+export interface OtelAccountLastReceived {
+    at: number | null;
+    since: number;
+    reason: string | null;
+}
 export interface OtelClientOptions {
     /**
      * Base URL of the OTEL service.
@@ -65,6 +113,14 @@ export declare class OtelClient {
         data: OtelMetric[];
         count: number;
     }>;
+    /**
+     * The tokens agents counted over the last `hours` (24 by default): total,
+     * prompt and completion, overall and per service, in one request — the
+     * service reads each counter's increase over the window in one scan. The
+     * answer also says when telemetry last reached the store (`last_received`),
+     * so a total of 0 can be told from a store that stopped receiving.
+     */
+    fetchTokenUsage(options?: FetchTokenUsageOptions): Promise<OtelTokenUsage>;
     /** Sum all values for one metric name, with optional service filter. */
     fetchMetricTotal(metricName: string, options?: FetchMetricTotalOptions): Promise<number>;
     /** List known service names observed in traces. */

package/lib/otel/client/OtelClient.js

@@ -177,6 +177,31 @@ export class OtelClient {
             : [];
         return { data: normalized, count: normalized.length };
     }
+    /**
+     * The tokens agents counted over the last `hours` (24 by default): total,
+     * prompt and completion, overall and per service, in one request — the
+     * service reads each counter's increase over the window in one scan. The
+     * answer also says when telemetry last reached the store (`last_received`),
+     * so a total of 0 can be told from a store that stopped receiving.
+     */
+    async fetchTokenUsage(options = {}) {
+        const params = new URLSearchParams({ hours: String(options.hours ?? 24) });
+        for (const name of options.serviceNames ?? []) {
+            params.append('service_name', name);
+        }
+        if (options.accountUid)
+            params.set('account_uid', options.accountUid);
+        const resp = await otelFetch(`${this.baseUrl}/api/otel/v1/metrics/tokens?${params}`, this.token, this.userUid);
+        return {
+            total: Number(resp.total ?? 0),
+            prompt: Number(resp.prompt ?? 0),
+            completion: Number(resp.completion ?? 0),
+            by_service: Array.isArray(resp.by_service) ? resp.by_service : [],
+            window: resp.window,
+            last_received: resp.last_received,
+            account_last_received: resp.account_last_received,
+        };
+    }
     /** Sum all values for one metric name, with optional service filter. */
     async fetchMetricTotal(metricName, options = {}) {
         const { serviceName, limit = 500, fallbackWithoutService = true, accountUid, } = options;

package/lib/otel/client/index.d.ts

@@ -1,2 +1,2 @@
 export { OtelClient, createOtelClient } from './OtelClient';
-export type { OtelClientOptions, FetchTracesOptions, FetchLogsOptions, FetchMetricsOptions, FetchMetricTotalOptions, OtelSystemData, OtelSystemProcess, OtelSystemDisk, OtelSystemTable, } from './OtelClient';
+export type { OtelClientOptions, FetchTracesOptions, FetchLogsOptions, FetchMetricsOptions, FetchMetricTotalOptions, FetchTokenUsageOptions, OtelTokenUsage, OtelLastReceived, OtelAccountLastReceived, OtelSystemData, OtelSystemProcess, OtelSystemDisk, OtelSystemTable, } from './OtelClient';

package/lib/otel/index.d.ts

@@ -20,7 +20,7 @@ export type { ResolvedOtelAuth } from './auth';
 export { useOtelTraces, useOtelTrace, useOtelLogs, useOtelMetrics, useOtelServices, useOtelStats, useOtelQuery, useOtelSystem, useOtelWebSocket, setOtelOnUnauthorized, } from './hooks';
 export type { OtelWsMessage, OtelWsCallbacks, OtelSystemData, OtelSystemProcess, OtelSystemDisk, OtelSystemTable, } from './hooks';
 export { OtelClient, createOtelClient } from './client';
-export type { OtelClientOptions, FetchTracesOptions, FetchLogsOptions, FetchMetricsOptions, FetchMetricTotalOptions, } from './client';
+export type { OtelClientOptions, FetchTracesOptions, FetchLogsOptions, FetchMetricsOptions, FetchMetricTotalOptions, FetchTokenUsageOptions, OtelTokenUsage, OtelLastReceived, OtelAccountLastReceived, } from './client';
 export { OtelLive } from './views';
 export { OtelTracesList } from './views';
 export { OtelSpanDetail } from './views';