@datalayer/core 1.1.60 → 1.2.10

package/lib/api/iam/serviceAgents.js

@@ -0,0 +1,119 @@
+/*
+ * 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.
+ */
+/**
+ * An organization's service agents: agents that are principals rather than
+ * a person's proxy.
+ *
+ * A connected agent is a grant — somebody's authority, narrowed to one
+ * client, dying with their account. A service agent is the other kind: it
+ * belongs to the organization, holds its own key, spends under its own name
+ * and outlives whoever set it up. An organization whose nightly pipeline
+ * runs on an engineer's grant loses the pipeline when the engineer leaves,
+ * and its spend shows against somebody who was asleep.
+ *
+ * **The key exists in one response and no other.** IAM stores a hash of it,
+ * so no later read can return it — `create` and `rotate` carry it and
+ * `list` never does. Anything rendering it must say so in the same breath,
+ * because somebody who does not know stores nothing and rotates an hour
+ * later.
+ *
+ * @module api/iam/serviceAgents
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
+/**
+ * What a service agent may be granted.
+ *
+ * A subset of the OAuth scopes, and deliberately not all of them: the ones
+ * about a *person* — reading their profile, acting as them — mean nothing
+ * for a principal that is not one, and IAM refuses them. Offering one would
+ * invite somebody to grant something that silently does nothing.
+ */
+export const SERVICE_AGENT_SCOPES = [
+    'runtimes:read',
+    'runtimes:write',
+    'data:read',
+    'sandboxes:manage',
+];
+const fromWire = (agent) => ({
+    uid: agent.uid,
+    name: agent.name ?? '',
+    description: agent.description ?? '',
+    teamUid: agent.team_uid ?? '',
+    scopes: agent.scopes ?? '',
+    revoked: Boolean(agent.revoked),
+    createdBy: agent.created_by ?? '',
+    createdAt: agent.created_at ?? null,
+    keyRotatedAt: agent.key_rotated_at ?? null,
+});
+const withKey = (agent) => ({
+    ...fromWire(agent),
+    key: agent.key ?? '',
+});
+const agentsUrl = (baseUrl, orgUid, suffix = '') => `${baseUrl}${API_BASE_PATHS.IAM}/organizations/${encodeURIComponent(orgUid)}` +
+    `/mcp-service-agents${suffix}`;
+/**
+ * One organization's service agents, revoked ones included.
+ *
+ * Included because hiding them makes a revoked agent invisible to whoever
+ * is deciding whether it is still needed, while its audit rows still name
+ * it. Any member of the organization may read this; only owners may write.
+ */
+export const listServiceAgents = async (token, orgUid, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await requestDatalayerAPI({
+        url: agentsUrl(baseUrl, orgUid),
+        method: 'GET',
+        token,
+    });
+    return (response.agents ?? []).map(fromWire);
+};
+/**
+ * Create one. **The key is in this answer and in no other.**
+ *
+ * Scopes are sent as the array the caller holds; IAM joins and validates
+ * them, and refuses one that is not grantable to a principal that is not a
+ * person.
+ */
+export const createServiceAgent = async (token, orgUid, agent, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await requestDatalayerAPI({
+        url: agentsUrl(baseUrl, orgUid),
+        method: 'POST',
+        token,
+        body: {
+            name: agent.name,
+            scopes: agent.scopes,
+            description: agent.description ?? '',
+            team_uid: agent.teamUid ?? '',
+        },
+    });
+    return withKey(response.agent ?? { uid: '' });
+};
+/**
+ * Replace the agent's key. The old one stops working with this call.
+ *
+ * No grace period, which is the point of rotating: a leaked key that still
+ * works for an hour is a leaked key that still works.
+ */
+export const rotateServiceAgentKey = async (token, orgUid, agentUid, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await requestDatalayerAPI({
+        url: agentsUrl(baseUrl, orgUid, `/${encodeURIComponent(agentUid)}/rotate`),
+        method: 'POST',
+        token,
+    });
+    return withKey(response.agent ?? { uid: agentUid });
+};
+/** Stop the agent, keeping it readable for its audit. */
+export const revokeServiceAgent = async (token, orgUid, agentUid, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await requestDatalayerAPI({
+        url: agentsUrl(baseUrl, orgUid, `/${encodeURIComponent(agentUid)}/revoke`),
+        method: 'POST',
+        token,
+    });
+    return fromWire(response.agent ?? { uid: agentUid });
+};

package/lib/api/iam/trials.d.ts

@@ -0,0 +1,38 @@
+/** Where a claim carries the trial's own key. */
+export declare const TRIAL_TOKEN_HEADER = "X-Datalayer-Trial-Token";
+/** What a visitor may try here, if anything. */
+export interface TrialOffer {
+    offered: boolean;
+    /** The one benchmark a trial may run. */
+    evalsetId: string;
+    /** The credits it may spend. */
+    credits: number;
+    /** How long it lives, in seconds. */
+    ttlSeconds: number;
+}
+export interface Trial {
+    id: string;
+    /** The uid the trial's work is owned by, which is the trial's own. */
+    ownerUid: string;
+    state: 'open' | 'claimed' | 'expired';
+    evalsetId: string;
+    creditsLimit: number | null;
+    creditsSpent: number;
+    expiresAt: string | null;
+    claimedByUid: string;
+    claimedAt: string | null;
+}
+/** A trial and the key that acts as it. The key is answered once. */
+export interface IssuedTrial {
+    trial: Trial;
+    token: string;
+}
+/**
+ * Whether this deployment lets a visitor try a benchmark, and which one.
+ * Unauthenticated: it is what a public page asks before it offers the run.
+ */
+export declare const getTrialOffer: (baseUrl?: string) => Promise<TrialOffer>;
+/** Take a trial. Unauthenticated, rate limited, and refused where none are offered. */
+export declare const createTrial: (baseUrl?: string) => Promise<IssuedTrial>;
+/** The trial a key acts as: what it has left, and how long it has. */
+export declare const getCurrentTrial: (trialToken: string, baseUrl?: string) => Promise<Trial>;

package/lib/api/iam/trials.js

@@ -0,0 +1,66 @@
+/*
+ * 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.
+ */
+/**
+ * The anonymous trial: running the public benchmark before signing up
+ * (BENCHMARK.md, B2-14).
+ *
+ * A visitor with no account asks for a trial and gets a principal of its
+ * own with one benchmark it may run, a few credits and a short expiry. The
+ * work they make is owned by that principal, so when they sign up it is
+ * given to them rather than lost — `claimTrial` in the evals client moves
+ * it, and the trial's own key has to be presented alongside their new one.
+ *
+ * A deployment that has not named a public benchmark offers no trials, and
+ * `getTrialOffer` says so: a page asks before it shows the button.
+ *
+ * @module api/iam/trials
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
+/** Where a claim carries the trial's own key. */
+export const TRIAL_TOKEN_HEADER = 'X-Datalayer-Trial-Token';
+const trialsUrl = (baseUrl, suffix = '') => `${baseUrl}${API_BASE_PATHS.IAM}/trials${suffix}`;
+const asTrial = (wire) => ({
+    id: wire.id,
+    ownerUid: wire.owner_uid ?? wire.id,
+    state: wire.state ?? 'open',
+    evalsetId: wire.evalset_id ?? '',
+    creditsLimit: wire.credits_limit ?? null,
+    creditsSpent: wire.credits_spent ?? 0,
+    expiresAt: wire.expires_at ?? null,
+    claimedByUid: wire.claimed_by_uid ?? '',
+    claimedAt: wire.claimed_at ?? null,
+});
+/**
+ * Whether this deployment lets a visitor try a benchmark, and which one.
+ * Unauthenticated: it is what a public page asks before it offers the run.
+ */
+export const getTrialOffer = async (baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await requestDatalayerAPI({ url: trialsUrl(baseUrl, '/offer'), method: 'GET' });
+    return {
+        offered: !!response.offered,
+        evalsetId: response.evalset_id ?? '',
+        credits: response.credits ?? 0,
+        ttlSeconds: response.ttl_seconds ?? 0,
+    };
+};
+/** Take a trial. Unauthenticated, rate limited, and refused where none are offered. */
+export const createTrial = async (baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await requestDatalayerAPI({ url: trialsUrl(baseUrl), method: 'POST' });
+    return { trial: asTrial(response.trial), token: response.token };
+};
+/** The trial a key acts as: what it has left, and how long it has. */
+export const getCurrentTrial = async (trialToken, baseUrl = DEFAULT_SERVICE_URLS.IAM) => {
+    const response = await requestDatalayerAPI({
+        url: trialsUrl(baseUrl, '/me'),
+        method: 'GET',
+        token: trialToken,
+    });
+    return asTrial(response.trial);
+};

package/lib/api/index.d.ts

@@ -6,8 +6,15 @@
  *
  * @module @datalayer/core/api
  */
-export { requestDatalayerAPI, RunResponseError, NetworkError, } from './DatalayerApi';
+export { requestDatalayerAPI, requestDatalayerAPIWithResponse, RunResponseError, NetworkError, TokenExpiredError, } from './DatalayerApi';
 export type { IRequestDatalayerAPIOptions } from './DatalayerApi';
+export type { IDatalayerAPIResponse } from './DatalayerApi';
 export * as iam from './iam';
+export * as contents from './contents';
+export * as evals from './evals';
+export * as mcp from './mcp';
+export * as orchestration from './orchestration';
 export * as otel from './otel';
+export * as scheduler from './scheduler';
+export * as spacer from './spacer';
 export * from '../api/DatalayerApi';

package/lib/api/index.js

@@ -11,8 +11,14 @@
  * @module @datalayer/core/api
  */
 // Base client exports
-export { requestDatalayerAPI, RunResponseError, NetworkError, } from './DatalayerApi.js';
+export { requestDatalayerAPI, requestDatalayerAPIWithResponse, RunResponseError, NetworkError, TokenExpiredError, } from './DatalayerApi.js';
 // Domain-organized API exports
 export * as iam from './iam/index.js';
+export * as contents from './contents/index.js';
+export * as evals from './evals/index.js';
+export * as mcp from './mcp/index.js';
+export * as orchestration from './orchestration/index.js';
 export * as otel from './otel/index.js';
+export * as scheduler from './scheduler/index.js';
+export * as spacer from './spacer/index.js';
 export * from '../api/DatalayerApi.js';

package/lib/api/mcp/activity.d.ts

@@ -0,0 +1,37 @@
+import type { McpAuditEvent } from '../../models/McpAuditEvent';
+import type { McpBinding } from '../../models/McpBinding';
+import type { McpTask } from '../../models/McpTask';
+/** A connected client, as the dashboard shows it, with its last call. */
+export interface McpActiveClient {
+    clientId: string;
+    clientName?: string | null;
+    /** The IAM grant behind the connection, what **Disconnect** revokes. */
+    grantUid?: string | null;
+    scopes?: string[];
+    connectedAt?: string | null;
+    lastCall?: McpAuditEvent | null;
+}
+/** Today's counts for the caller, or for the organization. */
+export interface McpActivityCounts {
+    calls: number;
+    refusals: number;
+    tasks: number;
+    /** Credits spent by agents today. */
+    credits: number;
+}
+export interface McpActivity {
+    /** The moment the answer was assembled; the cache is five seconds. */
+    at: string;
+    orgUid?: string | null;
+    clients: McpActiveClient[];
+    sandboxes: McpBinding[];
+    tasks: McpTask[];
+    calls: McpAuditEvent[];
+    today: McpActivityCounts;
+}
+export interface McpActivityFilters {
+    /** An owner's view of an organization. */
+    org?: string;
+    team?: string;
+}
+export declare const getMcpActivity: (token: string, filters?: McpActivityFilters, baseUrl?: string) => Promise<McpActivity>;

package/lib/api/mcp/activity.js

@@ -0,0 +1,26 @@
+/*
+ * 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.
+ */
+/**
+ * "What is going on" for the caller, in one answer: the connected clients
+ * joined with their last call, the bound sandboxes with their state, the
+ * tasks in `working`/`input_required`, the last calls and today's counts.
+ *
+ * Read from `mcp-gateway`, `mcp-tasks` and `mcp-audit` with bounded
+ * queries, cached for five seconds per caller. An owner adds `?org=`.
+ *
+ * @module api/mcp/activity
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { DEFAULT_SERVICE_URLS } from '../constants.js';
+import { fromWire, mcpUrl } from './gateway.js';
+export const getMcpActivity = async (token, filters = {}, baseUrl = DEFAULT_SERVICE_URLS.JUPYTER_MCP_SERVER) => fromWire(await requestDatalayerAPI({
+    url: mcpUrl(baseUrl, '/activity', { ...filters }),
+    method: 'GET',
+    token,
+}));

package/lib/api/mcp/alerts.d.ts

@@ -0,0 +1,25 @@
+export interface McpAlertRuleTrial {
+    /** Whether anything could answer the condition at all. */
+    readable: boolean;
+    /** The reading, when there was one. */
+    value?: number;
+    /** Whether the rule would fire on it. */
+    wouldFire: boolean;
+    /** Why it could not be read, or what the reader had to add. */
+    detail: string;
+}
+/**
+ * What this rule would see now.
+ *
+ * The organization is the caller's own, whatever is sent — testing another
+ * organization's numbers is reading their numbers, and the gateway refuses
+ * to do it rather than trusting the body.
+ */
+export declare const testAlertRule: (token: string, rule: {
+    condition: string;
+    operator: string;
+    threshold: number;
+    windowSeconds: number;
+    scopeKind?: string;
+    scopeUid?: string;
+}, mcpServerUrl?: string) => Promise<McpAlertRuleTrial>;

package/lib/api/mcp/alerts.js

@@ -0,0 +1,51 @@
+/*
+ * 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.
+ */
+/**
+ * Trying a rule before trusting it.
+ *
+ * The gateway answers what a rule would see *right now*, recording nothing
+ * and telling nobody. The question worth asking is not what the number is
+ * but whether the condition can be **read at all**: a rule on something
+ * nothing reads never fires, and never firing is exactly what a
+ * correctly-quiet rule looks like — so writing one and waiting teaches
+ * nothing, for as long as somebody is willing to wait.
+ *
+ * @module api/mcp/alerts
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { DEFAULT_SERVICE_URLS } from '../constants.js';
+import { mcpUrl } from './gateway.js';
+/**
+ * What this rule would see now.
+ *
+ * The organization is the caller's own, whatever is sent — testing another
+ * organization's numbers is reading their numbers, and the gateway refuses
+ * to do it rather than trusting the body.
+ */
+export const testAlertRule = async (token, rule, mcpServerUrl = DEFAULT_SERVICE_URLS.JUPYTER_MCP_SERVER) => {
+    const response = await requestDatalayerAPI({
+        url: mcpUrl(mcpServerUrl, '/alerts/test'),
+        method: 'POST',
+        token,
+        body: {
+            condition: rule.condition,
+            operator: rule.operator,
+            threshold: rule.threshold,
+            window_seconds: rule.windowSeconds,
+            scope_kind: rule.scopeKind ?? 'organization',
+            scope_uid: rule.scopeUid ?? '',
+        },
+    });
+    return {
+        readable: Boolean(response.readable),
+        value: response.value,
+        wouldFire: Boolean(response.would_fire),
+        detail: response.detail ?? '',
+    };
+};

package/lib/api/mcp/audit.d.ts

@@ -0,0 +1,29 @@
+import type { McpAuditDecision, McpAuditEventList, McpAuditExportFormat, McpAuditOutcome } from '../../models/McpAuditEvent';
+export type { McpAuditDecision, McpAuditEvent, McpAuditEventList, McpAuditExportFormat, McpAuditOutcome, McpClientInfo, } from '../../models/McpAuditEvent';
+export interface McpAuditFilters {
+    org?: string;
+    team?: string;
+    /** The `client_id` of the agent, or a service agent's uid. */
+    agent?: string;
+    user?: string;
+    tool?: string;
+    method?: string;
+    decision?: McpAuditDecision;
+    outcome?: McpAuditOutcome;
+    /** ISO 8601, UTC. */
+    since?: string;
+    until?: string;
+    taskId?: string;
+    traceId?: string;
+    cursor?: string;
+    limit?: number;
+}
+/** One page of audit rows, newest first. */
+export declare const listAuditEvents: (token: string, filters?: McpAuditFilters, baseUrl?: string) => Promise<McpAuditEventList>;
+/**
+ * The rows matching the filters, whole, as one JSONL or CSV document.
+ *
+ * The cursor of the filters is ignored: an export is everything the filters
+ * select, which is what a SIEM or a spreadsheet wants.
+ */
+export declare const exportAuditEvents: (token: string, filters?: Omit<McpAuditFilters, "cursor" | "limit">, format?: McpAuditExportFormat, baseUrl?: string) => Promise<string>;

package/lib/api/mcp/audit.js

@@ -0,0 +1,55 @@
+/*
+ * 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.
+ */
+/**
+ * The audit log of the Jupyter MCP Server, for `organization_security_auditor`s
+ * and owners: cursor-paged, exportable as JSONL or CSV.
+ *
+ * @module api/mcp/audit
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { DEFAULT_SERVICE_URLS } from '../constants.js';
+import { fromWire, mcpUrl } from './gateway.js';
+const auditQuery = (filters) => ({
+    org: filters.org,
+    team: filters.team,
+    agent: filters.agent,
+    user: filters.user,
+    tool: filters.tool,
+    method: filters.method,
+    decision: filters.decision,
+    outcome: filters.outcome,
+    since: filters.since,
+    until: filters.until,
+    task_id: filters.taskId,
+    trace_id: filters.traceId,
+    cursor: filters.cursor,
+    limit: filters.limit,
+});
+/** One page of audit rows, newest first. */
+export const listAuditEvents = async (token, filters = {}, baseUrl = DEFAULT_SERVICE_URLS.JUPYTER_MCP_SERVER) => fromWire(await requestDatalayerAPI({
+    url: mcpUrl(baseUrl, '/audit', auditQuery(filters)),
+    method: 'GET',
+    token,
+}));
+/**
+ * The rows matching the filters, whole, as one JSONL or CSV document.
+ *
+ * The cursor of the filters is ignored: an export is everything the filters
+ * select, which is what a SIEM or a spreadsheet wants.
+ */
+export const exportAuditEvents = async (token, filters = {}, format = 'jsonl', baseUrl = DEFAULT_SERVICE_URLS.JUPYTER_MCP_SERVER) => {
+    const data = await requestDatalayerAPI({
+        url: mcpUrl(baseUrl, '/audit', { ...auditQuery(filters), export: format }),
+        method: 'GET',
+        token,
+        headers: { Accept: format === 'csv' ? 'text/csv' : 'application/x-ndjson' },
+        responseType: 'text',
+    });
+    return typeof data === 'string' ? data : JSON.stringify(data);
+};

package/lib/api/mcp/bindings.d.ts

@@ -0,0 +1,18 @@
+import type { McpBinding, McpBindingKind, McpBindingList, McpBindingState } from '../../models/McpBinding';
+export type { McpBinding, McpBindingKind, McpBindingList, McpBindingOnLost, McpBindingState, } from '../../models/McpBinding';
+export interface McpBindingListFilters {
+    kind?: McpBindingKind;
+    state?: McpBindingState;
+    /** The `client_id` of the agent holding the handle. */
+    agent?: string;
+    org?: string;
+    cursor?: string;
+    limit?: number;
+}
+/** Every handle the caller holds, optionally of one kind. */
+export declare const listBindings: (token: string, filters?: McpBindingListFilters, baseUrl?: string) => Promise<McpBindingList>;
+/**
+ * Release a handle. For a sandbox binding this terminates the runtime; a
+ * notebook or toolset binding is simply forgotten.
+ */
+export declare const terminateBinding: (token: string, bindingUid: string, baseUrl?: string) => Promise<McpBinding>;

package/lib/api/mcp/bindings.js

@@ -0,0 +1,42 @@
+/*
+ * 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.
+ */
+/**
+ * The caller's handles: notebooks, toolsets and the sandbox bindings that
+ * are their sessions.
+ *
+ * `DELETE /bindings/{uid}` on a sandbox binding terminates the runtime
+ * through Runtimes and ends the tasks running on it `SANDBOX_LOST`.
+ *
+ * @module api/mcp/bindings
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { DEFAULT_SERVICE_URLS } from '../constants.js';
+import { fromWire, mcpUrl } from './gateway.js';
+/** Every handle the caller holds, optionally of one kind. */
+export const listBindings = async (token, filters = {}, baseUrl = DEFAULT_SERVICE_URLS.JUPYTER_MCP_SERVER) => fromWire(await requestDatalayerAPI({
+    url: mcpUrl(baseUrl, '/bindings', {
+        kind: filters.kind,
+        state: filters.state,
+        agent: filters.agent,
+        org: filters.org,
+        cursor: filters.cursor,
+        limit: filters.limit,
+    }),
+    method: 'GET',
+    token,
+}));
+/**
+ * Release a handle. For a sandbox binding this terminates the runtime; a
+ * notebook or toolset binding is simply forgotten.
+ */
+export const terminateBinding = async (token, bindingUid, baseUrl = DEFAULT_SERVICE_URLS.JUPYTER_MCP_SERVER) => fromWire(await requestDatalayerAPI({
+    url: mcpUrl(baseUrl, `/bindings/${encodeURIComponent(bindingUid)}`),
+    method: 'DELETE',
+    token,
+}));

package/lib/api/mcp/forwarding.d.ts

@@ -0,0 +1,25 @@
+export interface McpForwardingState {
+    orgUid: string;
+    /** When a batch was last accepted by the destination. */
+    lastDeliveredAt?: string | null;
+    /** What the destination last said, when it refused. */
+    lastError?: string | null;
+    lastErrorAt?: string | null;
+    delivered: number;
+    failed: number;
+    /** Whether the last attempt succeeded. */
+    healthy: boolean;
+}
+export interface McpForwarding {
+    /**
+     * Whether anything has ever been delivered or attempted.
+     *
+     * Kept apart from `healthy` because "never attempted" and "working" read
+     * the same in a counter — and for an organization that configured a
+     * destination, the first is the worse state and the one that looks most
+     * like fine.
+     */
+    configured: boolean;
+    state: McpForwardingState | null;
+}
+export declare const getMcpForwarding: (token: string, org?: string, mcpServerUrl?: string) => Promise<McpForwarding>;

package/lib/api/mcp/forwarding.js

@@ -0,0 +1,46 @@
+/*
+ * 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.
+ */
+/**
+ * Whether an organization's audit is reaching its own system of record.
+ *
+ * Forwarding never fails the call it describes — an audit row that could not
+ * be shipped is still a row, and holding up somebody's tool call because
+ * their SIEM is down would be the worse trade. Which means a failure is
+ * **invisible unless something reports it**, and a silently dropped record
+ * looks exactly like nothing having happened.
+ *
+ * This is that something.
+ *
+ * @module api/mcp/forwarding
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { DEFAULT_SERVICE_URLS } from '../constants.js';
+import { mcpUrl } from './gateway.js';
+export const getMcpForwarding = async (token, org = '', mcpServerUrl = DEFAULT_SERVICE_URLS.JUPYTER_MCP_SERVER) => {
+    const response = await requestDatalayerAPI({
+        url: mcpUrl(mcpServerUrl, '/audit/forwarding', org ? { org } : {}),
+        method: 'GET',
+        token,
+    });
+    const wire = response.state;
+    return {
+        configured: Boolean(response.configured),
+        state: wire
+            ? {
+                orgUid: wire.org_uid ?? '',
+                lastDeliveredAt: wire.last_delivered_at ?? null,
+                lastError: wire.last_error ?? null,
+                lastErrorAt: wire.last_error_at ?? null,
+                delivered: wire.delivered ?? 0,
+                failed: wire.failed ?? 0,
+                healthy: Boolean(wire.healthy),
+            }
+            : null,
+    };
+};

package/lib/api/mcp/gateway.d.ts

@@ -0,0 +1,16 @@
+/** The host and scheme of the gateway, without the `/mcp` resource path. */
+export declare const mcpGatewayOrigin: (mcpServerUrl?: string) => string;
+export type McpQuery = Record<string, string | number | boolean | undefined | null>;
+/** A REST route of the gateway, with its query string. */
+export declare const mcpUrl: (mcpServerUrl: string, suffix: string, query?: McpQuery) => string;
+/** A route outside the versioned API: `/api/mcp/version`, `/api/mcp/healthz`. */
+export declare const mcpServiceUrl: (mcpServerUrl: string, suffix: string) => string;
+/**
+ * A wire document as a model: snake case to camel case through the envelope,
+ * the preserved fields carried as they came.
+ */
+export declare const fromWire: <T>(value: unknown) => T;
+/** A request body as the gateway reads it. */
+export declare const toWire: (value: unknown) => unknown;
+/** For the few answers with no tool-owned field, the Contents converter as is. */
+export declare const fromWireStrict: <T>(value: unknown) => T;