@datalayer/core 1.1.59 → 1.1.66

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

@@ -0,0 +1,68 @@
+/**
+ * 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 declare const SERVICE_AGENT_SCOPES: readonly ["runtimes:read", "runtimes:write", "data:read", "sandboxes:manage"];
+export type ServiceAgentScope = (typeof SERVICE_AGENT_SCOPES)[number];
+export interface ServiceAgent {
+    uid: string;
+    name: string;
+    description: string;
+    /** The team it belongs to, where it is a team's rather than the organization's. */
+    teamUid: string;
+    /** Space-separated, as the token's `scope` claim carries them. */
+    scopes: string;
+    /**
+     * Revoked rather than removed. Its audit rows name it, and a uid that
+     * resolves to nothing makes a year-old row unreadable — so this is a
+     * state to render, never a reason to hide the row.
+     */
+    revoked: boolean;
+    createdBy: string;
+    createdAt?: string | null;
+    /** When the key was last replaced, so a listing can show a stale one. */
+    keyRotatedAt?: string | null;
+}
+/**
+ * A service agent as it comes back from a write, with the key.
+ *
+ * The key is present exactly twice in this API — creating and rotating —
+ * and nowhere else, ever.
+ */
+export interface ServiceAgentWithKey extends ServiceAgent {
+    key: string;
+}
+/**
+ * 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 declare const listServiceAgents: (token: string, orgUid: string, baseUrl?: string) => Promise<ServiceAgent[]>;
+/**
+ * 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 declare const createServiceAgent: (token: string, orgUid: string, agent: {
+    name: string;
+    scopes: string[];
+    description?: string;
+    teamUid?: string;
+}, baseUrl?: string) => Promise<ServiceAgentWithKey>;
+/**
+ * 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 declare const rotateServiceAgentKey: (token: string, orgUid: string, agentUid: string, baseUrl?: string) => Promise<ServiceAgentWithKey>;
+/** Stop the agent, keeping it readable for its audit. */
+export declare const revokeServiceAgent: (token: string, orgUid: string, agentUid: string, baseUrl?: string) => Promise<ServiceAgent>;

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/index.d.ts

@@ -6,8 +6,11 @@
  *
  * @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 mcp from './mcp';
 export * as otel from './otel';
 export * from '../api/DatalayerApi';

package/lib/api/index.js

@@ -11,8 +11,10 @@
  * @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 mcp from './mcp/index.js';
 export * as otel from './otel/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;

package/lib/api/mcp/gateway.js

@@ -0,0 +1,70 @@
+/*
+ * 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 every gateway client shares: where the REST routes are, and how a
+ * wire document becomes a model.
+ *
+ * The configured URL is the MCP resource — `https://mcp.datalayer.run/mcp`,
+ * the address an agent connects to and the audience a token names. The
+ * REST routes live on the same host under `/api/mcp/v1`, so the resource
+ * path is taken off before a route is appended.
+ *
+ * Wire documents are snake case and the models camel case, as with
+ * Contents, with one difference: a task's `result` and an audit row's
+ * `redactedArguments` are a tool's own — their keys are the tool's
+ * argument and output names and must survive as typed — so the envelope is
+ * converted around them, never through them.
+ *
+ * @module api/mcp/gateway
+ */
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS } from '../constants.js';
+import { contentsToCamelCase, contentsToSnakeCase } from '../../models/contents/index.js';
+/** The host and scheme of the gateway, without the `/mcp` resource path. */
+export const mcpGatewayOrigin = (mcpServerUrl = DEFAULT_SERVICE_URLS.JUPYTER_MCP_SERVER) => {
+    const trimmed = mcpServerUrl.replace(/\/+$/, '');
+    return trimmed.endsWith('/mcp') ? trimmed.slice(0, -'/mcp'.length) : trimmed;
+};
+/** A REST route of the gateway, with its query string. */
+export const mcpUrl = (mcpServerUrl, suffix, query = {}) => {
+    const parameters = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined && value !== null && value !== '') {
+            parameters.set(key, String(value));
+        }
+    }
+    const search = parameters.toString();
+    return `${mcpGatewayOrigin(mcpServerUrl)}${API_BASE_PATHS.MCP}${suffix}${search ? `?${search}` : ''}`;
+};
+/** A route outside the versioned API: `/api/mcp/version`, `/api/mcp/healthz`. */
+export const mcpServiceUrl = (mcpServerUrl, suffix) => `${mcpGatewayOrigin(mcpServerUrl)}/api/mcp${suffix}`;
+/** The fields whose keys belong to a tool, not to the contract. */
+const PRESERVED_FIELDS = new Set(['result', 'redacted_arguments', 'client_info', 'input', 'output']);
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const camelKey = (key) => key.replace(/_([a-zA-Z0-9])/g, (_, character) => character.toUpperCase());
+/**
+ * A wire document as a model: snake case to camel case through the envelope,
+ * the preserved fields carried as they came.
+ */
+export const fromWire = (value) => {
+    if (Array.isArray(value)) {
+        return value.map(item => fromWire(item));
+    }
+    if (!isObject(value)) {
+        return value;
+    }
+    const converted = {};
+    for (const [key, item] of Object.entries(value)) {
+        converted[camelKey(key)] = PRESERVED_FIELDS.has(key) ? item : fromWire(item);
+    }
+    return converted;
+};
+/** A request body as the gateway reads it. */
+export const toWire = (value) => contentsToSnakeCase(value);
+/** For the few answers with no tool-owned field, the Contents converter as is. */
+export const fromWireStrict = (value) => contentsToCamelCase(value);