@datalayer/core 1.1.60 → 1.2.10

package/lib/api/mcp/observability.js

@@ -0,0 +1,267 @@
+/*
+ * 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 observability of the Jupyter MCP Server, read from the Datalayer OTEL
+ * service — never from the gateway, which adds no telemetry route.
+ *
+ * Audit answers *who did what, and was it allowed*; this answers *how did
+ * it run*. A task carries its `trace_id`, so "show me this run" is the
+ * task's spans; its logs are the log records of that trace; and the four
+ * SLIs are read from the OTEL service's service levels dashboard, which
+ * computes them from the metrics as they were exported — a counter's
+ * increase, a percentile from a histogram's buckets. Nothing here adds
+ * metric points up: the gateway reports running totals, and adding those
+ * counts every earlier report again. Metrics carry no user, agent or
+ * organization label by design, so a per-agent reading is computed from the
+ * `mcp.request` spans, which do carry `client.id` and `org.uid`.
+ *
+ * @module api/mcp/observability
+ */
+import { DEFAULT_SERVICE_URLS } from '../constants.js';
+import { getTrace, listTraces } from '../otel/traces.js';
+import { listMetricNames } from '../otel/metrics.js';
+import { queryLogs } from '../otel/logs.js';
+import { getDashboardData } from '../otel/dashboards.js';
+/**
+ * The `service.name` the gateway exports under, and the one its workers use.
+ *
+ * The bare service name, like every other Datalayer service (`contents`,
+ * `iam`, `runtimes`): `instrument(app, name)` is what sets it. A worker is a
+ * process of its own and is filed separately, so a worker's last lines stay
+ * queryable after the process is gone.
+ */
+export const MCP_GATEWAY_SERVICE_NAME = 'jupyter-mcp-server';
+/** The `service.name` a worker's relayed output is filed under. */
+export const MCP_WORKER_SERVICE_NAME = 'jupyter-mcp-worker';
+/**
+ * The `service.name` the durable execution service exports under.
+ *
+ * The `durable.*` metrics come from there, not from the gateway. Querying
+ * them against the gateway would be well formed, would be answered
+ * truthfully with nothing, and would render a legitimate-looking zero — the
+ * same failure that had three panels querying `mcp.forwarded` and
+ * `mcp.sandbox_lost`. `serviceNameFor` exists so the question is answered
+ * once rather than at each call site.
+ */
+export const MCP_DURABLE_SERVICE_NAME = 'datalayer-durable';
+/**
+ * Which service emits a metric.
+ *
+ * A metric's service is a property of the metric, not of the caller. Reading
+ * it from here is what keeps a new panel from inheriting whichever constant
+ * happened to be in scope where it was written.
+ */
+export const serviceNameFor = (metric) => metric.startsWith('durable.')
+    ? MCP_DURABLE_SERVICE_NAME
+    : MCP_GATEWAY_SERVICE_NAME;
+/** The metric catalog `telemetry.py` owns; no ad-hoc counters. */
+export const MCP_METRIC_CATALOG = [
+    'mcp.calls',
+    'mcp.call.duration',
+    'mcp.refusals',
+    // A limit *not* applied because the figure it compares against could not
+    // be read. Distinct from a refusal, which is the limit working: an
+    // organization whose budget stopped being enforced otherwise looks exactly
+    // like one that never set a budget.
+    'mcp.limit.unenforced',
+    'mcp.forwards',
+    'mcp.workers',
+    'mcp.worker_start_seconds',
+    'mcp.bindings',
+    'mcp.sandbox.lost',
+    'mcp.tasks',
+    'mcp.task.duration',
+    'durable.step.duration',
+    'durable.queue.wait',
+    'durable.recoveries',
+    'sandbox.launch_seconds',
+    'mcp.audit.writes',
+    'mcp.audit.write_failures',
+    'mcp.dependency.duration',
+    'mcp.dependency.timeouts',
+    'mcp.dependency.ready',
+    'mcp.readiness.failures',
+    'mcp.audit.deleted',
+    'mcp.jobs',
+    'mcp.job.duration',
+];
+/** The four SLIs, and the catalog metric each is read from. */
+export const MCP_SLI_METRICS = {
+    availability: 'mcp.calls',
+    latency: 'mcp.call.duration',
+    taskSuccess: 'mcp.tasks',
+    sandboxLaunch: 'sandbox.launch_seconds',
+};
+/** The OTEL service's built-in dashboard the four SLIs are read from. */
+export const MCP_SERVICE_LEVELS_DASHBOARD = 'mcp-service-levels';
+/**
+ * Its panels, by the ids the OTEL service gives them. A contract test there
+ * holds them, so a panel renamed on the service fails a test rather than
+ * reading here as nothing measured.
+ */
+export const MCP_SERVICE_LEVEL_PANELS = {
+    callsByOutcome: 'mcp-calls-by-outcome',
+    callDurationP95: 'mcp-call-duration-p95',
+    tasksByStatus: 'mcp-tasks-by-status',
+    sandboxLaunchP95: 'sandbox-launch_seconds-by-provider-p95',
+    sandboxLaunches: 'sandbox-launch_seconds-by-provider-count',
+};
+const TERMINAL_STATUSES = ['completed', 'failed', 'cancelled'];
+/** The nearest-rank percentile of a sample; `null` for an empty one. */
+export const percentile = (values, fraction) => {
+    if (values.length === 0) {
+        return null;
+    }
+    const sorted = [...values].sort((a, b) => a - b);
+    const rank = Math.min(sorted.length - 1, Math.max(0, Math.ceil(fraction * sorted.length) - 1));
+    return sorted[rank];
+};
+const attribute = (holder, name) => String(holder.attributes?.[name] ?? '');
+const notBefore = (timestamp, since) => !since || !timestamp || timestamp >= since;
+/** Whether an `mcp.request` span is a failed call in the availability sense. */
+const isUnavailable = (span) => {
+    const status = attribute(span, 'http.response.status_code') || attribute(span, 'http.status_code');
+    const rpc = attribute(span, 'rpc.jsonrpc.error_code') || attribute(span, 'mcp.error.code');
+    return status.startsWith('5') || rpc === '-32001';
+};
+/**
+ * The SLIs from the service levels dashboard — the platform-wide reading.
+ *
+ * Its panels arrive summarised: calls and tasks as how much each counter grew
+ * over the window, the two p95s from their histograms' buckets. The call
+ * duration is recorded in seconds and shown in milliseconds. A panel with
+ * nothing in it reads as not measured, never as a zero.
+ */
+export const summarizeServiceLevels = (data) => {
+    const panels = new Map(data.panels.map(panel => [panel.id, panel]));
+    const byLabel = (id) => Object.fromEntries((panels.get(id)?.series ?? [])
+        .filter(entry => entry.summary !== null)
+        .map(entry => [entry.label, entry.summary]));
+    const total = (values) => Object.values(values).reduce((sum, value) => sum + value, 0);
+    const calls = byLabel(MCP_SERVICE_LEVEL_PANELS.callsByOutcome);
+    const totalCalls = total(calls);
+    const failedCalls = (calls.error ?? 0) + (calls.unavailable ?? 0);
+    const tasks = byLabel(MCP_SERVICE_LEVEL_PANELS.tasksByStatus);
+    const terminal = TERMINAL_STATUSES.reduce((sum, status) => sum + (tasks[status] ?? 0), 0);
+    const p95Seconds = byLabel(MCP_SERVICE_LEVEL_PANELS.callDurationP95)[''];
+    const p95SandboxLaunchSeconds = Object.fromEntries(Object.entries(byLabel(MCP_SERVICE_LEVEL_PANELS.sandboxLaunchP95)).map(([provider, seconds]) => [
+        provider || 'unknown',
+        seconds,
+    ]));
+    return {
+        availability: totalCalls > 0 ? (totalCalls - failedCalls) / totalCalls : null,
+        p95CallDurationMs: p95Seconds === undefined ? null : p95Seconds * 1000,
+        taskSuccessRate: terminal > 0 ? (tasks.completed ?? 0) / terminal : null,
+        p95SandboxLaunchSeconds,
+        samples: {
+            calls: totalCalls,
+            tasks: terminal,
+            launches: total(byLabel(MCP_SERVICE_LEVEL_PANELS.sandboxLaunches)),
+        },
+    };
+};
+/**
+ * The SLIs over `mcp.request` spans — the per-agent or per-organization
+ * reading, since metrics carry neither label.
+ */
+export const summarizeRequestSpans = (spans, filters = {}) => {
+    const selected = spans.filter(span => span.span_name === 'mcp.request' &&
+        notBefore(span.start_time, filters.since) &&
+        (!filters.agent || attribute(span, 'client.id') === filters.agent) &&
+        (!filters.org || attribute(span, 'org.uid') === filters.org));
+    const unavailable = selected.filter(isUnavailable).length;
+    const tasks = new Map();
+    for (const span of selected) {
+        const taskId = attribute(span, 'mcp.task.id');
+        if (taskId) {
+            tasks.set(taskId, attribute(span, 'mcp.task.status') || span.status_code || '');
+        }
+    }
+    const terminal = [...tasks.values()].filter(status => ['completed', 'failed', 'cancelled'].includes(status));
+    const completed = terminal.filter(status => status === 'completed').length;
+    return {
+        availability: selected.length > 0 ? (selected.length - unavailable) / selected.length : null,
+        p95CallDurationMs: percentile(selected.filter(span => !attribute(span, 'mcp.task.id')).map(span => span.duration_ms), 0.95),
+        taskSuccessRate: terminal.length > 0 ? completed / terminal.length : null,
+        p95SandboxLaunchSeconds: {},
+        samples: { calls: selected.length, tasks: terminal.length, launches: 0 },
+    };
+};
+/** The four SLIs and the catalog, for everyone or for one agent or organization. */
+export const fetchMcpMetrics = async (token, filters = {}, otelUrl = DEFAULT_SERVICE_URLS.OTEL) => {
+    const limit = filters.limit ?? 500;
+    const scoped = Boolean(filters.agent || filters.org);
+    const [levels, names, traces] = await Promise.all([
+        scoped
+            ? undefined
+            : getDashboardData(token, MCP_SERVICE_LEVELS_DASHBOARD, { since: filters.since ? new Date(filters.since) : undefined }, otelUrl),
+        listMetricNames(token, otelUrl),
+        scoped ? listTraces(token, { serviceName: MCP_GATEWAY_SERVICE_NAME, limit }, otelUrl) : undefined,
+    ]);
+    const reported = new Set((names.data ?? []).map(row => row.metric_name));
+    const spans = traces?.data ?? [];
+    return {
+        filters,
+        reporting: MCP_METRIC_CATALOG.filter(name => reported.has(name)),
+        spans,
+        slis: levels ? summarizeServiceLevels(levels) : summarizeRequestSpans(spans, filters),
+        readAt: new Date().toISOString(),
+    };
+};
+/** The spans of a trace as a tree, roots first, siblings by start time. */
+export const spanTree = (spans) => {
+    const nodes = new Map();
+    for (const span of spans) {
+        nodes.set(span.span_id, { span, children: [] });
+    }
+    const roots = [];
+    for (const node of nodes.values()) {
+        const parent = node.span.parent_span_id ? nodes.get(node.span.parent_span_id) : undefined;
+        (parent ? parent.children : roots).push(node);
+    }
+    const byStart = (a, b) => a.span.start_time.localeCompare(b.span.start_time);
+    const sort = (list) => {
+        list.sort(byStart);
+        list.forEach(node => sort(node.children));
+    };
+    sort(roots);
+    return roots;
+};
+/** "Show me this run": the spans of the task's trace. A task without one has none yet. */
+export const fetchRunTrace = async (token, task, otelUrl = DEFAULT_SERVICE_URLS.OTEL) => {
+    if (!task.traceId) {
+        return { taskUid: task.uid, traceId: '', spans: [], tree: [] };
+    }
+    const trace = await getTrace(token, task.traceId, otelUrl);
+    const spans = trace.data ?? [];
+    return { taskUid: task.uid, traceId: task.traceId, spans, tree: spanTree(spans) };
+};
+/**
+ * The spans of one trace, named directly.
+ *
+ * A synchronous call has no task — it finished inside its own request — but
+ * it does carry a trace, which is what the audit row records and what
+ * "show me this call" means before durable execution exists.
+ */
+export const fetchTraceSpans = async (token, traceId, otelUrl = DEFAULT_SERVICE_URLS.OTEL) => {
+    if (!traceId) {
+        return { taskUid: '', traceId: '', spans: [], tree: [] };
+    }
+    const trace = await getTrace(token, traceId, otelUrl);
+    const spans = trace.data ?? [];
+    return { taskUid: '', traceId, spans, tree: spanTree(spans) };
+};
+/** The log lines of a run, gateway and worker alike, by the trace they carry. */
+export const fetchMcpLogs = async (token, task, options = {}, otelUrl = DEFAULT_SERVICE_URLS.OTEL) => {
+    if (!task.traceId) {
+        return { taskUid: task.uid, traceId: '', records: [] };
+    }
+    const page = await queryLogs(token, { traceId: task.traceId, limit: options.limit ?? 200, severity: options.severity }, otelUrl);
+    return { taskUid: task.uid, traceId: task.traceId, records: page.data ?? [] };
+};

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

@@ -0,0 +1,83 @@
+export interface McpGatewayVersion {
+    version: string;
+    /** The MCP resource this gateway serves; what a token's `aud` must name. */
+    resource: string;
+}
+export interface McpGatewayHealth {
+    status: string;
+    version: string;
+}
+export type McpWorkerState = 'starting' | 'running' | 'idle' | 'draining' | 'stopped';
+/** One worker process of the directory, keyed by user and by sandbox binding. */
+export interface McpWorker {
+    uid: string;
+    userUid: string;
+    /** The `sb_…` binding whose sandbox this worker holds, when it holds one. */
+    sandboxBindingUid?: string | null;
+    replica: string;
+    state: McpWorkerState;
+    /** Tasks in `working`; a worker with one is never reaped. */
+    workingTasks: number;
+    startedAt: string;
+    lastUsedAt?: string | null;
+    version?: string | null;
+}
+export interface McpWorkerList {
+    items: McpWorker[];
+    /** The replica that answered. */
+    replica?: string;
+}
+export interface McpWorkflowQueue {
+    name: string;
+    backlog: number;
+    /** Seconds the oldest waiting workflow has waited. */
+    oldestWaitSeconds?: number | null;
+}
+/** One periodic job on the replica that answered. */
+export interface McpJob {
+    job: string;
+    /** Ticks this replica actually ran. */
+    ran: number;
+    /**
+     * Ticks this replica skipped because another held the lease. The ordinary
+     * outcome on every replica but one — read it per replica, never summed.
+     * Rising on *all* of them at once is the lease store refusing everybody.
+     */
+    skipped: number;
+    failed: number;
+    lastRanAt?: number | null;
+    lastError?: string;
+    lastDurationSeconds?: number;
+    healthy: boolean;
+}
+export interface McpJobSchedule {
+    /** Whether this replica's scheduler loops are running. */
+    running: boolean;
+    /** The replica that answered; the counts below are only about it. */
+    holder: string;
+    jobs: McpJob[];
+}
+/** Engine health, queue backlog and worker versions. */
+export interface McpWorkflowsHealth {
+    engine: 'temporal' | 'dbos' | string;
+    healthy: boolean;
+    detail?: string | null;
+    queues: McpWorkflowQueue[];
+    workerVersions: Record<string, number>;
+    checkedAt: string;
+}
+export declare const getGatewayVersion: (baseUrl?: string) => Promise<McpGatewayVersion>;
+export declare const getGatewayHealth: (baseUrl?: string) => Promise<McpGatewayHealth>;
+/** The worker directory across replicas; platform administrators only. */
+export declare const listWorkers: (token: string, baseUrl?: string) => Promise<McpWorkerList>;
+export declare const getWorkflowsHealth: (token: string, baseUrl?: string) => Promise<McpWorkflowsHealth>;
+/**
+ * The periodic work on the replica that answers, and what it has done.
+ *
+ * Per replica by construction: only one replica holds each job's lease at a
+ * time, so `ran` on one and `skipped` on the others is the scheduler working.
+ * A caller that wants the platform's view has to ask every replica — there is
+ * no aggregate here, because an aggregate would hide the case worth seeing,
+ * which is every replica skipping at once.
+ */
+export declare const getJobSchedule: (token: string, baseUrl?: string) => Promise<McpJobSchedule>;

package/lib/api/mcp/operations.js

@@ -0,0 +1,50 @@
+/*
+ * 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 gateway seen by a platform administrator: its version and liveness,
+ * the worker directory, the engine's health. No raw history, no secrets.
+ *
+ * @module api/mcp/operations
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { DEFAULT_SERVICE_URLS } from '../constants.js';
+import { fromWire, mcpServiceUrl, mcpUrl } from './gateway.js';
+export const getGatewayVersion = async (baseUrl = DEFAULT_SERVICE_URLS.JUPYTER_MCP_SERVER) => requestDatalayerAPI({
+    url: mcpServiceUrl(baseUrl, '/version'),
+    method: 'GET',
+});
+export const getGatewayHealth = async (baseUrl = DEFAULT_SERVICE_URLS.JUPYTER_MCP_SERVER) => requestDatalayerAPI({
+    url: mcpServiceUrl(baseUrl, '/healthz'),
+    method: 'GET',
+});
+/** The worker directory across replicas; platform administrators only. */
+export const listWorkers = async (token, baseUrl = DEFAULT_SERVICE_URLS.JUPYTER_MCP_SERVER) => fromWire(await requestDatalayerAPI({
+    url: mcpUrl(baseUrl, '/operations/workers'),
+    method: 'GET',
+    token,
+}));
+export const getWorkflowsHealth = async (token, baseUrl = DEFAULT_SERVICE_URLS.JUPYTER_MCP_SERVER) => fromWire(await requestDatalayerAPI({
+    url: mcpUrl(baseUrl, '/operations/workflows'),
+    method: 'GET',
+    token,
+}));
+/**
+ * The periodic work on the replica that answers, and what it has done.
+ *
+ * Per replica by construction: only one replica holds each job's lease at a
+ * time, so `ran` on one and `skipped` on the others is the scheduler working.
+ * A caller that wants the platform's view has to ask every replica — there is
+ * no aggregate here, because an aggregate would hide the case worth seeing,
+ * which is every replica skipping at once.
+ */
+export const getJobSchedule = async (token, baseUrl = DEFAULT_SERVICE_URLS.JUPYTER_MCP_SERVER) => fromWire(await requestDatalayerAPI({
+    url: mcpUrl(baseUrl, '/operations/jobs'),
+    method: 'GET',
+    token,
+}));

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

@@ -0,0 +1,102 @@
+/** One line of the compliance strip: green, or naming what is missing. */
+export interface McpComplianceCheck {
+    /** The rule's name, e.g. `sso_required`, `admitted_clients_only`. */
+    name: string;
+    ok: boolean;
+    /** What is missing, when it is not `ok`. */
+    detail?: string | null;
+}
+/** How many principals act through MCP for the organization. */
+export interface McpOverviewAgents {
+    delegated: number;
+    service: number;
+    activeToday: number;
+}
+export interface McpOverviewRuns {
+    today: number;
+    succeeded: number;
+    failed: number;
+    /** `completed` over terminal tasks; `null` when nothing ran. */
+    successRate?: number | null;
+}
+/** Milestone 3 fills the quota; until then only what was spent is known. */
+export interface McpOverviewSpend {
+    creditsToday: number;
+    creditsMonth: number;
+    quotaMonth?: number | null;
+}
+export interface McpRefusalCount {
+    reason: string;
+    count: number;
+}
+export interface McpOrganizationOverview {
+    orgUid: string;
+    teamUid?: string | null;
+    /** The moment the answer was assembled. */
+    at: string;
+    agents: McpOverviewAgents;
+    runs: McpOverviewRuns;
+    spend?: McpOverviewSpend | null;
+    refusals: McpRefusalCount[];
+    approvalsWaiting?: number | null;
+    alertsFiring?: number | null;
+    compliance: McpComplianceCheck[];
+}
+export interface McpOrganizationOverviewFilters {
+    /** One team of the organization, rather than all of them. */
+    team?: string;
+}
+export declare const getOrganizationMcpOverview: (token: string, orgUid: string, filters?: McpOrganizationOverviewFilters, baseUrl?: string) => Promise<McpOrganizationOverview>;
+/** One quota: what may be used, what is, and the share of the two.
+ *
+ * `used` is `null` where the figure could not be read, with `unknown` saying
+ * why. Absent and unreadable look identical in a dashboard — no number
+ * beside a heading — and mean opposite things: one is "no limit set", the
+ * other is "we cannot tell you what your limit is".
+ */
+export interface McpQuota {
+    limit?: number | null;
+    used?: number | null;
+    /** `used / limit`, computed by the gateway so a page and an alert cannot
+     * divide differently. */
+    fraction?: number | null;
+    /** Why the figure could not be read. Present only when it could not. */
+    unknown?: string;
+}
+/** What one agent spent of the day's credits. */
+export interface McpAgentSpend {
+    /** The MCP client it connected as, e.g. `claude`. Empty for a service
+     * agent reaching Runtimes through the gateway. */
+    clientId: string;
+    /** The service agent's uid, where it is one. */
+    agentUid: string;
+    credits: number;
+    /** Usage records behind the figure. */
+    records: number;
+}
+export interface McpOrganizationUsage {
+    orgUid: string;
+    teamUid?: string | null;
+    window: {
+        seconds: number;
+    };
+    quotas: {
+        creditsPerDay?: McpQuota;
+        concurrentSandboxes?: McpQuota;
+        callsPerMinute?: McpQuota;
+    };
+    /** Which agents the day's credits went to, biggest spender first. Empty
+     * where the total could not be read — the parts under an unreadable whole
+     * make every agent look cheap. */
+    byAgent: McpAgentSpend[];
+    /** Where a limit is changed, which is not here. */
+    setAt: string;
+}
+/**
+ * One organization's use against its quotas, and who spent it.
+ *
+ * Never throws for a figure it could not read: this is a page somebody opens
+ * when something is wrong, and the half of it that works is worth more than
+ * an error saying one number was unavailable.
+ */
+export declare const getOrganizationMcpUsage: (token: string, orgUid: string, filters?: McpOrganizationOverviewFilters, baseUrl?: string) => Promise<McpOrganizationUsage>;

package/lib/api/mcp/organizations.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.
+ */
+/**
+ * What an administrator sees first: the organization's MCP overview.
+ *
+ * One answer for the Enterprise console's Overview page — the agents that
+ * acted today, the runs and their success rate, the refusals by reason, the
+ * approvals waiting and the compliance strip over what IAM knows. Spend,
+ * quota and alerts join the same answer in milestone 3; a field the gateway
+ * does not fill yet is absent rather than zero, so the page can say "not
+ * measured yet" instead of "none".
+ *
+ * `?team=` narrows every part of it to one team.
+ *
+ * @module api/mcp/organizations
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { DEFAULT_SERVICE_URLS } from '../constants.js';
+import { fromWire, mcpUrl } from './gateway.js';
+export const getOrganizationMcpOverview = async (token, orgUid, filters = {}, baseUrl = DEFAULT_SERVICE_URLS.JUPYTER_MCP_SERVER) => fromWire(await requestDatalayerAPI({
+    url: mcpUrl(baseUrl, `/organizations/${encodeURIComponent(orgUid)}/overview`, {
+        team: filters.team,
+    }),
+    method: 'GET',
+    token,
+}));
+/**
+ * One organization's use against its quotas, and who spent it.
+ *
+ * Never throws for a figure it could not read: this is a page somebody opens
+ * when something is wrong, and the half of it that works is worth more than
+ * an error saying one number was unavailable.
+ */
+export const getOrganizationMcpUsage = async (token, orgUid, filters = {}, baseUrl = DEFAULT_SERVICE_URLS.JUPYTER_MCP_SERVER) => fromWire(await requestDatalayerAPI({
+    url: mcpUrl(baseUrl, `/organizations/${encodeURIComponent(orgUid)}/usage`, {
+        team: filters.team,
+    }),
+    method: 'GET',
+    token,
+}));

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

@@ -0,0 +1,9 @@
+import type { McpEffectivePolicy } from '../../models/McpPolicy';
+export type { McpApprovalPolicy, McpEffectivePolicy, McpOrganizationPolicy, McpPersonalPolicy, McpPolicyLayer, McpPolicyRule, McpPolicyScope, McpToolRule, } from '../../models/McpPolicy';
+export interface McpPolicyFilters {
+    /** Preview as: the `client_id` of an agent. */
+    agent?: string;
+    org?: string;
+    team?: string;
+}
+export declare const getEffectivePolicy: (token: string, filters?: McpPolicyFilters, baseUrl?: string) => Promise<McpEffectivePolicy>;

package/lib/api/mcp/policy.js

@@ -0,0 +1,23 @@
+/*
+ * 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 effective policy for the caller's token, redacted, each rule naming
+ * the layer that decided it. `?agent=` previews the policy as one agent
+ * would see it.
+ *
+ * @module api/mcp/policy
+ */
+import { requestDatalayerAPI } from '../DatalayerApi.js';
+import { DEFAULT_SERVICE_URLS } from '../constants.js';
+import { fromWire, mcpUrl } from './gateway.js';
+export const getEffectivePolicy = async (token, filters = {}, baseUrl = DEFAULT_SERVICE_URLS.JUPYTER_MCP_SERVER) => fromWire(await requestDatalayerAPI({
+    url: mcpUrl(baseUrl, '/policy', { ...filters }),
+    method: 'GET',
+    token,
+}));

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

@@ -0,0 +1,49 @@
+import type { McpTask, McpTaskEvent, McpTaskInput, McpTaskList, McpTaskStatus } from '../../models/McpTask';
+export { MCP_TERMINAL_TASK_STATUSES, isMcpTaskTerminal, } from '../../models/McpTask';
+export type { McpCallToolResult, McpTask, McpTaskEvent, McpTaskInput, McpTaskList, McpTaskOutput, McpTaskStatus, McpWorkflowEngine, } from '../../models/McpTask';
+export interface McpTaskListFilters {
+    notebook?: string;
+    sandbox?: string;
+    /** The `client_id` of the agent, or a service agent's uid. */
+    agent?: string;
+    status?: McpTaskStatus;
+    /** An owner's view of an organization. */
+    org?: string;
+    cursor?: string;
+    limit?: number;
+}
+/** The caller's tasks, newest first; an owner narrows to an organization. */
+export declare const listTasks: (token: string, filters?: McpTaskListFilters, baseUrl?: string) => Promise<McpTaskList>;
+export declare const getTask: (token: string, taskUid: string, baseUrl?: string) => Promise<McpTask>;
+/** Stop a task that is still going. Idempotent: a finished task is answered as it is. */
+export declare const cancelTask: (token: string, taskUid: string, baseUrl?: string) => Promise<McpTask>;
+/**
+ * Answer a task that is `input_required`.
+ *
+ * The input is the tool's own and goes over as typed; only the envelope is
+ * converted. The idempotency key makes a retried answer one answer.
+ */
+export declare const answerTask: (token: string, taskUid: string, request: McpTaskInput, idempotencyKey: string, baseUrl?: string) => Promise<McpTask>;
+/** The tasks of one notebook; empty until milestone 2 fills it. */
+export declare const listNotebookTasks: (token: string, notebookUid: string, filters?: Pick<McpTaskListFilters, "status" | "cursor" | "limit">, baseUrl?: string) => Promise<McpTaskList>;
+/** Where a task's server-sent events are. */
+export declare const taskEventsUrl: (taskUid: string, baseUrl?: string) => string;
+export interface McpTaskEventHandlers {
+    onEvent: (event: McpTaskEvent) => void;
+    onError?: (error: Error) => void;
+    /** The stream ended: the task reached a terminal status or the server closed. */
+    onClose?: () => void;
+}
+/**
+ * One SSE frame as the gateway writes it: `event:` then `data:` lines, a
+ * blank line between frames.
+ */
+export declare const parseTaskEventFrame: (frame: string) => McpTaskEvent | undefined;
+/**
+ * Subscribe to a task's events.
+ *
+ * `EventSource` cannot carry a bearer token, so this reads the stream with
+ * `fetch`. The returned function closes the subscription; the stream also
+ * ends by itself when the task is terminal.
+ */
+export declare const subscribeTaskEvents: (token: string, taskUid: string, handlers: McpTaskEventHandlers, baseUrl?: string) => (() => void);