@datalayer/core 1.1.59 → 1.1.66

package/lib/hooks/useProjectStore.js

@@ -34,19 +34,19 @@ export const useProjectStore = create()((set, get) => ({
             },
         },
     })),
-    setAgent: (projectId, agentPodName, agentName, agentStatus, agentSpecId) => set(state => ({
+    setAgent: (projectId, agentRuntimeName, agentName, agentStatus, agentSpecId) => set(state => ({
         projects: {
             ...state.projects,
             [projectId]: {
                 ...state.projects[projectId],
-                agentPodName,
+                agentRuntimeName,
                 agentName,
                 // When removing the agent, also clear the status.
                 // When setting, use provided status or preserve existing.
-                agentStatus: agentPodName !== undefined
+                agentStatus: agentRuntimeName !== undefined
                     ? (agentStatus ?? state.projects[projectId]?.agentStatus)
                     : undefined,
-                agentSpecId: agentPodName !== undefined
+                agentSpecId: agentRuntimeName !== undefined
                     ? (agentSpecId ?? state.projects[projectId]?.agentSpecId)
                     : undefined,
             },

package/lib/hooks/useRef.d.ts

@@ -7,4 +7,4 @@ import React from 'react';
  * @param providedRef The ref to use - if undefined, will use the ref from a call to React.useRef
  * @type TRef The type of the RefObject which should be created.
  */
-export declare function useProvidedRefOrCreate<TRef>(providedRef?: React.RefObject<TRef>): React.RefObject<TRef>;
+export declare function useProvidedRefOrCreate<TRef>(providedRef?: React.RefObject<TRef | null>): React.RefObject<TRef | null>;

package/lib/hooks/useRef.js

@@ -11,6 +11,9 @@ import { useRef } from 'react';
  * @param providedRef The ref to use - if undefined, will use the ref from a call to React.useRef
  * @type TRef The type of the RefObject which should be created.
  */
+// React 19 types `useRef<T>(null)` as `RefObject<T | null>`, so both the
+// accepted and returned ref are nullable here. Primer 37 still declares the
+// React 18 shape, so its call sites cast at the boundary.
 export function useProvidedRefOrCreate(providedRef) {
     const createdRef = useRef(null);
     return providedRef ?? createdRef;

package/lib/hooks/useScreencapture.d.ts

@@ -1,3 +1,4 @@
+import type { JSX } from 'react';
 import { ReactNode } from 'react';
 export type ScreencaptureContextType = {
     closeScreencapture: () => void;
@@ -15,4 +16,4 @@ export type IScreencaptureProviderProps = {
     disableDarken?: boolean;
     screenshotSurface?: (qfds: any) => JSX.Element;
 };
-export declare function ScreencaptureProvider({ children, zIndex, disableDarken, screenshotSurface, }: IScreencaptureProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function ScreencaptureProvider({ children, zIndex, disableDarken, screenshotSurface, }: IScreencaptureProviderProps): JSX.Element;

package/lib/hooks/useScreencapture.js

@@ -1,8 +1,4 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-/*
- * Copyright (c) 2023-2025 Datalayer, Inc.
- * Distributed under the terms of the Modified BSD License.
- */
 import { createContext, useState, useContext } from 'react';
 import { LayoutScreencapture } from './layouts/index.js';
 export const ScreencaptureContext = createContext({

package/lib/hooks/useToast.js

@@ -1,8 +1,4 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-/*
- * Copyright (c) 2023-2025 Datalayer, Inc.
- * Distributed under the terms of the Modified BSD License.
- */
 import React from 'react';
 import { toast } from 'react-toastify';
 import { Button } from '@primer/react';

package/lib/hooks/useUser.js

@@ -15,6 +15,28 @@ const isOnPublicPath = () => {
     }
     return isPublicPath(window.location?.pathname || '');
 };
+/**
+ * Whether these views are running inside JupyterLab.
+ *
+ * Read from the configuration JupyterLab writes into its own page, so nothing
+ * has to be imported from it: this module is used by the web application as
+ * well, which has no such configuration.
+ */
+const isInsideJupyterLab = () => {
+    if (typeof document === 'undefined') {
+        return false;
+    }
+    const config = document.getElementById('jupyter-config-data');
+    if (!config) {
+        return false;
+    }
+    try {
+        return JSON.parse(config.textContent || '{}').appName === 'JupyterLab';
+    }
+    catch {
+        return false;
+    }
+};
 export const useUser = (role) => {
     const { user } = useIAMStore();
     if (role) {
@@ -22,6 +44,10 @@ export const useUser = (role) => {
             if (isOnPublicPath()) {
                 return user;
             }
+            if (isInsideJupyterLab()) {
+                // Same reason as below: the router of these views answers this.
+                return user;
+            }
             console.warn(`User should have role ${role.handle} - Forcing navigation to login page...`);
             window.location.href = LOGIN_HREF;
             throw new Error(`User should have role ${role.handle}`);
@@ -31,6 +57,22 @@ export const useUser = (role) => {
         if (isOnPublicPath()) {
             return user;
         }
+        /*
+         * Inside JupyterLab, nobody leaves the page.
+         *
+         * `/login` is a page of the web application, at the root of the origin —
+         * and the origin of a JupyterLab is the Jupyter Server, which serves
+         * something else entirely there. Signing out of a view thus threw the user
+         * out of JupyterLab and onto a page of the server, which is not even a
+         * sign-in form.
+         *
+         * The views of Datalayer carry their own sign-in route under the base of
+         * JupyterLab, and their router shows it as soon as there is no user — so
+         * the way to reach it is to let that render, not to navigate away from it.
+         */
+        if (isInsideJupyterLab()) {
+            return user;
+        }
         console.warn('No user found... Forcing navigation to /login');
         window.location.href = LOGIN_HREF;
     }

package/lib/hooks/useVisibilityObserver.d.ts

@@ -2,4 +2,4 @@ import { RefObject } from 'react';
 export type VisibilityMap = {
     [key: string]: boolean;
 };
-export declare function useVisibilityObserver(navigationRef: RefObject<HTMLUListElement>, children: any): VisibilityMap[];
+export declare function useVisibilityObserver(navigationRef: RefObject<HTMLUListElement | null>, children: any): VisibilityMap[];

package/lib/index.d.ts

@@ -3,10 +3,13 @@ export * from './utils';
 export * from './state';
 export * from './navigation';
 export * from './hooks';
-export { requestDatalayerAPI, RunResponseError, NetworkError, } from './api/DatalayerApi';
+export { requestDatalayerAPI, requestDatalayerAPIWithResponse, RunResponseError, NetworkError, } from './api/DatalayerApi';
 export type { IRequestDatalayerAPIOptions } from './api/DatalayerApi';
+export type { IDatalayerAPIResponse } from './api/DatalayerApi';
 export { API_BASE_PATHS } from './api/constants';
 export * as iamApi from './api/iam';
+export * as contentsApi from './api/contents';
 export * from './client';
+export * from './models/contents';
 export * from './otel';
 export * from './views';

package/lib/index.js

@@ -10,10 +10,12 @@ export * from './state/index.js';
 export * from './navigation/index.js';
 export * from './hooks/index.js';
 // Export APIs.
-export { requestDatalayerAPI, RunResponseError, NetworkError, } from './api/DatalayerApi.js';
+export { requestDatalayerAPI, requestDatalayerAPIWithResponse, RunResponseError, NetworkError, } from './api/DatalayerApi.js';
 export { API_BASE_PATHS } from './api/constants.js';
 export * as iamApi from './api/iam/index.js';
+export * as contentsApi from './api/contents/index.js';
 export * from './client/index.js';
+export * from './models/contents/index.js';
 // OTEL observability components, hooks, and types
 export * from './otel/index.js';
 // Reusable views (sign-in pages, etc.)

package/lib/mocks/components/FlashMock.d.ts

@@ -1,2 +1,2 @@
-export declare const FlashMock: () => import("react/jsx-runtime").JSX.Element;
+export declare const FlashMock: () => import("react").JSX.Element;
 export default FlashMock;

package/lib/mocks/views/ActionMenuMock.d.ts

@@ -1,5 +1,5 @@
 type Props = {
     title: string;
 };
-export declare const ActionMenuMock: (props: Props) => import("react/jsx-runtime").JSX.Element;
+export declare const ActionMenuMock: (props: Props) => import("react").JSX.Element;
 export default ActionMenuMock;

package/lib/mocks/views/ChartMock.d.ts

@@ -1,5 +1,5 @@
 type Props = {
     title: string;
 };
-export declare const ChartMock: (props: Props) => import("react/jsx-runtime").JSX.Element;
+export declare const ChartMock: (props: Props) => import("react").JSX.Element;
 export default ChartMock;

package/lib/mocks/views/DashboardMock.d.ts

@@ -1,2 +1,2 @@
-export declare const DashboardMock: () => import("react/jsx-runtime").JSX.Element;
+export declare const DashboardMock: () => import("react").JSX.Element;
 export default DashboardMock;

package/lib/mocks/views/FormMock.d.ts

@@ -1,5 +1,5 @@
 type Props = {
     title: string;
 };
-export declare const FormMock: (props: Props) => import("react/jsx-runtime").JSX.Element;
+export declare const FormMock: (props: Props) => import("react").JSX.Element;
 export default FormMock;

package/lib/mocks/views/TableMock.d.ts

@@ -1,5 +1,5 @@
 type Props = {
     title: string;
 };
-export declare const TableMock: (props: Props) => import("react/jsx-runtime").JSX.Element;
+export declare const TableMock: (props: Props) => import("react").JSX.Element;
 export default TableMock;

package/lib/mocks/views/WipMock.d.ts

@@ -1,5 +1,5 @@
 type Props = {
     title: string;
 };
-export declare const WipMock: (props: Props) => import("react/jsx-runtime").JSX.Element;
+export declare const WipMock: (props: Props) => import("react").JSX.Element;
 export default WipMock;

package/lib/models/Credits.d.ts

@@ -25,6 +25,22 @@ export interface ICredits {
      */
     last_update: string;
 }
+/**
+ * The credits an account can still spend.
+ *
+ * `credits` means one of two things depending on whether a quota is set: what
+ * is left, or what has been consumed against the quota. IAM omits `quota`
+ * entirely for an account without one, so an absent quota is read the same as
+ * an explicit `null` — testing only against `null` let `undefined` take the
+ * quota branch and produced `NaN`, which then travelled silently into every
+ * reader of this number.
+ *
+ * Outstanding reservations are already committed, so they are subtracted:
+ * what is returned is what a new reservation may still claim.
+ */
+export declare const availableCredits: (credits: Pick<ICredits, "credits" | "quota">, reservations?: readonly {
+    credits: number;
+}[]) => number;
 export interface ICheckoutPortal {
     /**
      * External checkout portal URL to open in a new tab.

package/lib/models/Credits.js

@@ -9,3 +9,25 @@
  * TODO what is a good LOW_CREDITS bar? - A better way would be to set it from a server settings or a cloud config.
  */
 export const LOW_CREDITS = 3;
+/**
+ * The credits an account can still spend.
+ *
+ * `credits` means one of two things depending on whether a quota is set: what
+ * is left, or what has been consumed against the quota. IAM omits `quota`
+ * entirely for an account without one, so an absent quota is read the same as
+ * an explicit `null` — testing only against `null` let `undefined` take the
+ * quota branch and produced `NaN`, which then travelled silently into every
+ * reader of this number.
+ *
+ * Outstanding reservations are already committed, so they are subtracted:
+ * what is returned is what a new reservation may still claim.
+ */
+export const availableCredits = (credits, reservations = []) => {
+    const quota = credits.quota;
+    const balance = typeof quota === 'number' ? quota - credits.credits : credits.credits;
+    if (!Number.isFinite(balance)) {
+        return 0;
+    }
+    const reserved = reservations.reduce((consumed, reservation) => consumed + (Number.isFinite(reservation.credits) ? reservation.credits : 0), 0);
+    return Math.max(0, balance - reserved);
+};

package/lib/models/McpAuditEvent.d.ts

@@ -0,0 +1,52 @@
+/**
+ * An audit row of the Jupyter MCP Server: one call or one decision, written
+ * by the gateway for every request, append-only in `mcp-audit`.
+ *
+ * Audit answers *who did what, and was it allowed*. It is not telemetry: a
+ * row carries the trace id so one trace joins both trails, and never an
+ * argument in clear — arguments are hashed and redacted with the Contents
+ * rules before they reach the row.
+ *
+ * @module models/McpAuditEvent
+ */
+export type McpAuditDecision = 'allowed' | 'refused';
+export type McpAuditOutcome = 'ok' | 'error' | 'is_error';
+export interface McpClientInfo {
+    name?: string;
+    version?: string;
+    [key: string]: unknown;
+}
+export interface McpAuditEvent {
+    uid: string;
+    at: string;
+    orgUid?: string | null;
+    teamUid?: string | null;
+    userUid: string;
+    clientId?: string | null;
+    agentUid?: string | null;
+    /** The delegation chain (RFC 8693 `act`), outermost first. */
+    act?: string[];
+    /** The JSON-RPC method, or the REST route for a gateway API call. */
+    method: string;
+    tool?: string | null;
+    itemUid?: string | null;
+    sourceUid?: string | null;
+    cellId?: string | null;
+    argumentsHash?: string | null;
+    redactedArguments?: Record<string, unknown> | null;
+    decision: McpAuditDecision;
+    /** Names the rule and, once policy has layers, the layer that decided. */
+    refusalReason?: string | null;
+    outcome?: McpAuditOutcome | null;
+    durationMs?: number | null;
+    taskId?: string | null;
+    traceId?: string | null;
+    replica?: string | null;
+    protocolVersion?: string | null;
+    clientInfo?: McpClientInfo | null;
+}
+export interface McpAuditEventList {
+    items: McpAuditEvent[];
+    nextCursor?: string | null;
+}
+export type McpAuditExportFormat = 'jsonl' | 'csv';

package/lib/models/McpAuditEvent.js

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

package/lib/models/McpBinding.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A binding of the Jupyter MCP Server: a handle an agent holds on a
+ * notebook (`nb_…`), a toolset (`ts_…`) or a sandbox (`sb_…`).
+ *
+ * The sandbox binding *is* the session: one per (user, client) unless a
+ * client holds several on purpose. A notebook binding names the sandbox its
+ * cells execute on. Bindings live in `mcp-gateway`, expire with the item or
+ * the reservation they follow, and are refreshed on use.
+ *
+ * @module models/McpBinding
+ */
+export type McpBindingKind = 'notebook' | 'toolset' | 'sandbox';
+/** What the gateway does when the sandbox behind a binding is gone. */
+export type McpBindingOnLost = 'fail' | 'relaunch';
+/** Where a sandbox binding is; `lost` is what `SANDBOX_LOST` reports. */
+export type McpBindingState = 'active' | 'lost' | 'closed' | 'expired';
+export interface McpBinding {
+    /** The handle: `nb_…`, `ts_…` or `sb_…`. */
+    uid: string;
+    kind: McpBindingKind;
+    userUid: string;
+    clientId?: string | null;
+    agentUid?: string | null;
+    orgUid?: string | null;
+    alias?: string | null;
+    /** The Spacer notebook, for a `notebook` binding. */
+    itemUid?: string | null;
+    /** The Contents source and session, for a `toolset` binding. */
+    sourceUid?: string | null;
+    sessionUid?: string | null;
+    /** The runtime, for a `sandbox` binding. */
+    sandboxUid?: string | null;
+    sandboxProvider?: string | null;
+    /** What the runtime reported it can do. */
+    capabilities?: string[];
+    onLost?: McpBindingOnLost;
+    /** The gateway replica whose worker holds the connection. */
+    workerReplica?: string | null;
+    /** The owner's uid when the sandbox is shared with the caller through its ACL. */
+    sharedFrom?: string | null;
+    /** For a notebook binding: the sandbox its cells execute on. */
+    sandboxBindingUid?: string | null;
+    state?: McpBindingState;
+    createdAt: string;
+    lastUsedAt?: string | null;
+    expiresAt?: string | null;
+}
+export interface McpBindingList {
+    items: McpBinding[];
+    nextCursor?: string | null;
+}

package/lib/models/McpBinding.js

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

package/lib/models/McpPolicy.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The MCP policy: what an agent *may do*.
+ *
+ * Policy is layered and each layer only narrows: platform ∩ organization ∩
+ * team for an organization-scope token, platform ∩ personal for a
+ * personal-scope one. The organization's and the person's layers are IAM
+ * settings; the gateway answers the **effective** policy for a token with,
+ * per rule, which layer decided — what the Policies page renders as
+ * "Datalayer default", "required by your organization" or "you asked".
+ *
+ * Until milestone 3 adds the layers, `GET /api/mcp/v1/policy` answers the
+ * platform defaults from `tool_policy.py` and the token's scopes.
+ *
+ * @module models/McpPolicy
+ */
+export type McpPolicyLayer = 'platform' | 'organization' | 'team' | 'personal';
+/** The Contents approval vocabulary. */
+export type McpApprovalPolicy = 'explicit' | 'auto-allowlisted' | 'never';
+export type McpPolicyScope = 'personal' | 'organization';
+/** One rule of the effective policy, and the layer that decided it. */
+export interface McpPolicyRule {
+    /** The rule's name in the organization policy vocabulary, e.g. `tool_denylist`. */
+    name: string;
+    value: unknown;
+    decidedBy: McpPolicyLayer;
+    /** Why, when the gateway has a sentence for it. */
+    reason?: string | null;
+}
+/** What one tool needs, and what happens before it runs. */
+export interface McpToolRule {
+    tool: string;
+    scope: string;
+    access?: 'read' | 'write' | 'execute';
+    approval?: McpApprovalPolicy;
+    allowed: boolean;
+    decidedBy: McpPolicyLayer;
+}
+/** The effective policy for one token, redacted to what its holder may see. */
+export interface McpEffectivePolicy {
+    scope: McpPolicyScope;
+    orgUid?: string | null;
+    teamUid?: string | null;
+    /** The agent the policy was evaluated for, when previewing as one. */
+    clientId?: string | null;
+    /** The scopes the token carries; the ceiling over every tool rule. */
+    scopes: string[];
+    rules: McpPolicyRule[];
+    tools: McpToolRule[];
+    evaluatedAt?: string;
+}
+/**
+ * The organization (or team) MCP policy as IAM keeps it, versioned and
+ * audited. Every field is optional: an absent rule narrows nothing.
+ */
+export interface McpOrganizationPolicy {
+    version?: number;
+    /** CIMD URLs, client ids or software ids; fails closed. */
+    allowedClients?: string[];
+    requireDpop?: boolean;
+    requireOrgSso?: boolean;
+    maxScopes?: string[];
+    toolAllowlist?: string[];
+    toolDenylist?: string[];
+    /** Per tool, or per annotation (`destructiveHint`, `readOnlyHint`). */
+    approvalPolicy?: Record<string, McpApprovalPolicy>;
+    allowedEnvironments?: string[];
+    allowedProviders?: string[];
+    maxGpu?: number;
+    maxReservationMinutes?: number;
+    creditsPerDay?: number;
+    callsPerMinute?: number;
+    sessionMaxHours?: number;
+    updatedAt?: string;
+    updatedBy?: string;
+}
+/** A person's rules for the agents acting for them outside any organization. */
+export type McpPersonalPolicy = Pick<McpOrganizationPolicy, 'version' | 'approvalPolicy' | 'creditsPerDay' | 'toolDenylist' | 'allowedEnvironments' | 'sessionMaxHours' | 'updatedAt'>;

package/lib/models/McpPolicy.js

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

package/lib/models/McpTask.d.ts

@@ -0,0 +1,94 @@
+/**
+ * A task of the Jupyter MCP Server: one tool call that outlives the request
+ * that started it.
+ *
+ * The `uid` is the MCP `taskId`. A task is submitted by an agent, runs in
+ * the sandbox its session is bound to, and is reachable by anyone allowed to
+ * see the notebook it touched — from another device, forty minutes later.
+ * The gateway keeps the portable projection in `mcp-tasks`; the workflow
+ * engine owns claims and recovery, which is why there are no lease fields.
+ *
+ * Snake case on the wire, camel case here, exactly as Contents does.
+ *
+ * @module models/McpTask
+ */
+/** Where a task has got to; the MCP task status vocabulary. */
+export type McpTaskStatus = 'working' | 'input_required' | 'completed' | 'failed' | 'cancelled';
+/** The engine a task's workflow runs on. */
+export type McpWorkflowEngine = 'temporal' | 'dbos';
+/** A tool result small enough to travel with the task. */
+export interface McpCallToolResult {
+    content?: Array<Record<string, unknown>>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+    [key: string]: unknown;
+}
+/** One output of a task, in order; large outputs are references. */
+export interface McpTaskOutput {
+    index: number;
+    outputType: string;
+    mimeType?: string | null;
+    /** Inline text under the size limit. */
+    text?: string | null;
+    /** An object reference for anything larger. */
+    reference?: string | null;
+}
+export interface McpTask {
+    uid: string;
+    status: McpTaskStatus;
+    statusMessage?: string | null;
+    tool: string;
+    notebookUid?: string | null;
+    cellId?: string | null;
+    sandboxUid?: string | null;
+    /** A Contents operation, when the task wraps one. */
+    operationUid?: string | null;
+    /** An attachment, when the task follows its lifecycle without an operation. */
+    attachmentUid?: string | null;
+    /** A Contents `mcp_approval` or an ai-agents tool approval. */
+    approvalUid?: string | null;
+    /** The session the task executes in; never empty for an execution task. */
+    sandboxBindingUid?: string | null;
+    initiatingUser: string;
+    initiatingClient?: string | null;
+    orgUid?: string | null;
+    createdAt: string;
+    lastUpdatedAt: string;
+    ttlMs?: number | null;
+    pollIntervalMs?: number | null;
+    /** The `CallToolResult` for small results; a resource URI otherwise. */
+    result?: McpCallToolResult | string | null;
+    error?: string | null;
+    traceId?: string | null;
+    workflowEngine?: McpWorkflowEngine | null;
+    /** Always the task uid, so a retried start cannot create a second execution. */
+    workflowId?: string | null;
+    /** The Temporal run id; empty for DBOS. */
+    workflowRunId?: string | null;
+    queue?: string | null;
+    sandboxProvider?: string | null;
+    workerReplica?: string | null;
+    outputs?: McpTaskOutput[];
+}
+export interface McpTaskList {
+    items: McpTask[];
+    nextCursor?: string | null;
+}
+/** What `POST /tasks/{uid}/input` carries: the REST face of `tasks/update`. */
+export interface McpTaskInput {
+    input: Record<string, unknown>;
+}
+/** A `notifications/tasks` payload, as the SSE stream and the socket carry it. */
+export interface McpTaskEvent {
+    /** `status`, `output`, `input_required`, `completed`, `failed`, `cancelled`. */
+    event: string;
+    taskId: string;
+    status?: McpTaskStatus;
+    statusMessage?: string | null;
+    output?: McpTaskOutput;
+    task?: McpTask;
+    at?: string;
+}
+/** The statuses from which nothing more happens. */
+export declare const MCP_TERMINAL_TASK_STATUSES: ReadonlySet<McpTaskStatus>;
+export declare const isMcpTaskTerminal: (status: McpTaskStatus) => boolean;

package/lib/models/McpTask.js

@@ -0,0 +1,7 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** The statuses from which nothing more happens. */
+export const MCP_TERMINAL_TASK_STATUSES = new Set(['completed', 'failed', 'cancelled']);
+export const isMcpTaskTerminal = (status) => MCP_TERMINAL_TASK_STATUSES.has(status);

package/lib/models/StartedBy.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Who started a runtime: a person, one of their agents, or a service agent.
+ *
+ * The reservation has carried this since agents could make one — IAM writes
+ * `client_id_s` and `agent_uid_s` onto the usage record's metadata, and
+ * `useUsages` already hands the whole map to the views. Nothing displayed
+ * it, so a person looking at their running runtimes could not tell which of
+ * them they had started and which an agent had, on a platform whose premise
+ * is that agents start things on your behalf.
+ *
+ * The distinction that matters is **agent versus service agent**, not
+ * "automated versus not". A delegated agent runs as you, spends your
+ * credits, and stops when you disconnect it. A service agent is the
+ * organization's own principal with its own key: it keeps running when the
+ * person who set it up leaves, and it is the row somebody has to go and turn
+ * off. Told apart, one is "I did that yesterday" and the other is "who owns
+ * this".
+ *
+ * @module models/StartedBy
+ */
+/** The Solr field names IAM writes the dimensions on. */
+export declare const CLIENT_ID_KEY = "client_id_s";
+export declare const AGENT_UID_KEY = "agent_uid_s";
+export type StartedByKind = 'person' | 'agent' | 'service-agent';
+export interface StartedBy {
+    kind: StartedByKind;
+    /** What to show in a cell: a client id, an agent uid, or "You". */
+    label: string;
+    /** The MCP client it connected as, where there is one. */
+    clientId: string;
+    /** The service agent's uid, where it is one. */
+    agentUid: string;
+}
+/** Metadata as `useUsages` builds it, or as a plain object. */
+export type UsageMetadata = Map<string, unknown> | Record<string, unknown> | null | undefined;
+/**
+ * Who started this reservation.
+ *
+ * `agent_uid_s` decides before `client_id_s`, because a service agent
+ * reaching Runtimes through the MCP gateway carries **the gateway's** client
+ * id: read the other way round, every one of an organization's pipelines
+ * would show as the same agent.
+ *
+ * A record with neither dimension is a person's own work. It is *not* an
+ * agent whose name we failed to read, and saying "unknown" would suggest it
+ * was — so the answer is the reader themselves.
+ */
+export declare const startedBy: (metadata: UsageMetadata) => StartedBy;
+/**
+ * The words a search box matches on for this row.
+ *
+ * "agent" matches every agent-started runtime, the client id matches one
+ * client, and "you" matches your own — so the filter the plan asks for is the
+ * search box that is already there rather than a second control beside it.
+ */
+export declare const startedBySearchTerms: (metadata: UsageMetadata) => string;
+export default startedBy;