@datalayer/core 1.1.60 → 1.1.66

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

@@ -0,0 +1,22 @@
+export interface HTTPValidationError {
+    detail?: Array<ValidationError>;
+}
+export interface ValidationError {
+    loc: Array<string | number>;
+    msg: string;
+    type: string;
+    input?: unknown;
+    ctx?: Record<string, unknown>;
+}
+/** One REST route the gateway declares. */
+export interface McpGatewayRoute {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    operationId: string;
+    parameters: Array<{
+        name: string;
+        in: string;
+    }>;
+}
+/** The gateway version the routes were read from: 0.0.1. */
+export declare const MCP_GATEWAY_ROUTES: ReadonlyArray<McpGatewayRoute>;

package/lib/api/mcp/generated.js

@@ -0,0 +1,213 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** The gateway version the routes were read from: 0.0.1. */
+export const MCP_GATEWAY_ROUTES = [
+    {
+        method: 'GET',
+        path: '/.well-known/mcp-server',
+        operationId: 'server_card_endpoint__well_known_mcp_server_get',
+        parameters: [],
+    },
+    {
+        method: 'GET',
+        path: '/.well-known/oauth-protected-resource',
+        operationId: 'protected_resource_metadata_endpoint__well_known_oauth_protected_resource_get',
+        parameters: [],
+    },
+    {
+        method: 'GET',
+        path: '/.well-known/oauth-protected-resource/mcp',
+        operationId: 'protected_resource_metadata_endpoint__well_known_oauth_protected_resource_mcp_get',
+        parameters: [],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/healthz',
+        operationId: 'healthz_endpoint_api_mcp_healthz_get',
+        parameters: [],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/readyz',
+        operationId: 'readyz_endpoint_api_mcp_readyz_get',
+        parameters: [],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/activity',
+        operationId: 'activity_endpoint_api_mcp_v1_activity_get',
+        parameters: [{ name: 'org', in: 'query' }],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/alerts',
+        operationId: 'alerts_endpoint_api_mcp_v1_alerts_get',
+        parameters: [
+            { name: 'org', in: 'query' },
+            { name: 'scope', in: 'query' },
+            { name: 'unacknowledged', in: 'query' },
+        ],
+    },
+    {
+        method: 'POST',
+        path: '/api/mcp/v1/alerts/test',
+        operationId: 'test_alert_rule_endpoint_api_mcp_v1_alerts_test_post',
+        parameters: [],
+    },
+    {
+        method: 'POST',
+        path: '/api/mcp/v1/alerts/{alert_uid}/acknowledge',
+        operationId: 'acknowledge_alert_endpoint_api_mcp_v1_alerts__alert_uid__acknowledge_post',
+        parameters: [{ name: 'alert_uid', in: 'path' }],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/audit',
+        operationId: 'audit_endpoint_api_mcp_v1_audit_get',
+        parameters: [
+            { name: 'org', in: 'query' },
+            { name: 'team', in: 'query' },
+            { name: 'user', in: 'query' },
+            { name: 'client', in: 'query' },
+            { name: 'agent', in: 'query' },
+            { name: 'tool', in: 'query' },
+            { name: 'method', in: 'query' },
+            { name: 'decision', in: 'query' },
+            { name: 'outcome', in: 'query' },
+            { name: 'notebook', in: 'query' },
+            { name: 'source', in: 'query' },
+            { name: 'task', in: 'query' },
+            { name: 'since', in: 'query' },
+            { name: 'until', in: 'query' },
+            { name: 'cursor', in: 'query' },
+            { name: 'limit', in: 'query' },
+            { name: 'export', in: 'query' },
+        ],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/audit/forwarding',
+        operationId: 'audit_forwarding_endpoint_api_mcp_v1_audit_forwarding_get',
+        parameters: [{ name: 'org', in: 'query' }],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/bindings',
+        operationId: 'list_bindings_endpoint_api_mcp_v1_bindings_get',
+        parameters: [{ name: 'kind', in: 'query' }],
+    },
+    {
+        method: 'DELETE',
+        path: '/api/mcp/v1/bindings/{binding_uid}',
+        operationId: 'delete_binding_endpoint_api_mcp_v1_bindings__binding_uid__delete',
+        parameters: [{ name: 'binding_uid', in: 'path' }],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/notebooks/{notebook_uid}/tasks',
+        operationId: 'list_notebook_tasks_endpoint_api_mcp_v1_notebooks__notebook_uid__tasks_get',
+        parameters: [
+            { name: 'notebook_uid', in: 'path' },
+            { name: 'cursor', in: 'query' },
+            { name: 'limit', in: 'query' },
+        ],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/operations/jobs',
+        operationId: 'operations_jobs_endpoint_api_mcp_v1_operations_jobs_get',
+        parameters: [],
+    },
+    {
+        method: 'POST',
+        path: '/api/mcp/v1/operations/runtime-ended',
+        operationId: 'runtime_ended_endpoint_api_mcp_v1_operations_runtime_ended_post',
+        parameters: [],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/operations/workers',
+        operationId: 'operations_workers_endpoint_api_mcp_v1_operations_workers_get',
+        parameters: [],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/operations/workflows',
+        operationId: 'workflows_operations_endpoint_api_mcp_v1_operations_workflows_get',
+        parameters: [],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/organizations/{org_uid}/overview',
+        operationId: 'organization_overview_endpoint_api_mcp_v1_organizations__org_uid__overview_get',
+        parameters: [
+            { name: 'org_uid', in: 'path' },
+            { name: 'team', in: 'query' },
+        ],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/organizations/{org_uid}/usage',
+        operationId: 'organization_usage_endpoint_api_mcp_v1_organizations__org_uid__usage_get',
+        parameters: [
+            { name: 'org_uid', in: 'path' },
+            { name: 'team', in: 'query' },
+        ],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/policy',
+        operationId: 'policy_endpoint_api_mcp_v1_policy_get',
+        parameters: [
+            { name: 'agent', in: 'query' },
+            { name: 'org', in: 'query' },
+            { name: 'team', in: 'query' },
+        ],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/tasks',
+        operationId: 'list_tasks_endpoint_api_mcp_v1_tasks_get',
+        parameters: [
+            { name: 'notebook', in: 'query' },
+            { name: 'sandbox', in: 'query' },
+            { name: 'agent', in: 'query' },
+            { name: 'status', in: 'query' },
+            { name: 'org', in: 'query' },
+            { name: 'cursor', in: 'query' },
+            { name: 'limit', in: 'query' },
+        ],
+    },
+    {
+        method: 'DELETE',
+        path: '/api/mcp/v1/tasks/{task_uid}',
+        operationId: 'cancel_task_endpoint_api_mcp_v1_tasks__task_uid__delete',
+        parameters: [{ name: 'task_uid', in: 'path' }],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/tasks/{task_uid}',
+        operationId: 'get_task_endpoint_api_mcp_v1_tasks__task_uid__get',
+        parameters: [{ name: 'task_uid', in: 'path' }],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/v1/tasks/{task_uid}/events',
+        operationId: 'task_events_endpoint_api_mcp_v1_tasks__task_uid__events_get',
+        parameters: [{ name: 'task_uid', in: 'path' }],
+    },
+    {
+        method: 'POST',
+        path: '/api/mcp/v1/tasks/{task_uid}/input',
+        operationId: 'answer_task_endpoint_api_mcp_v1_tasks__task_uid__input_post',
+        parameters: [{ name: 'task_uid', in: 'path' }],
+    },
+    {
+        method: 'GET',
+        path: '/api/mcp/version',
+        operationId: 'version_endpoint_api_mcp_version_get',
+        parameters: [],
+    },
+];

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

@@ -0,0 +1,17 @@
+/**
+ * The Jupyter MCP Server's REST API: tasks, bindings, audit, activity,
+ * policy and operations. The MCP endpoint itself is not here — an agent
+ * speaks JSON-RPC to it; a browser reads what the agents did.
+ *
+ * @module api/mcp
+ */
+export * from './generated';
+export * from './gateway';
+export * from './tasks';
+export * from './bindings';
+export * from './audit';
+export * from './activity';
+export * from './organizations';
+export * from './policy';
+export * from './operations';
+export * from './observability';

package/lib/api/mcp/index.js

@@ -0,0 +1,25 @@
+/*
+ * 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 Jupyter MCP Server's REST API: tasks, bindings, audit, activity,
+ * policy and operations. The MCP endpoint itself is not here — an agent
+ * speaks JSON-RPC to it; a browser reads what the agents did.
+ *
+ * @module api/mcp
+ */
+export * from './generated.js';
+export * from './gateway.js';
+export * from './tasks.js';
+export * from './bindings.js';
+export * from './audit.js';
+export * from './activity.js';
+export * from './organizations.js';
+export * from './policy.js';
+export * from './operations.js';
+export * from './observability.js';

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

@@ -0,0 +1,125 @@
+import type { OtelLog, OtelMetric, OtelSpan } from '../otel/types';
+import type { McpTask } from '../../models/McpTask';
+/**
+ * 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 declare const MCP_GATEWAY_SERVICE_NAME = "jupyter-mcp-server";
+/** The `service.name` a worker's relayed output is filed under. */
+export declare 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 declare 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 declare const serviceNameFor: (metric: McpMetricName) => string;
+/** The metric catalog `telemetry.py` owns; no ad-hoc counters. */
+export declare const MCP_METRIC_CATALOG: readonly ["mcp.calls", "mcp.call.duration", "mcp.refusals", "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"];
+export type McpMetricName = (typeof MCP_METRIC_CATALOG)[number];
+/** The four SLIs, and the catalog metric each is read from. */
+export declare const MCP_SLI_METRICS: {
+    readonly availability: "mcp.calls";
+    readonly latency: "mcp.call.duration";
+    readonly taskSuccess: "mcp.tasks";
+    readonly sandboxLaunch: "sandbox.launch_seconds";
+};
+export interface McpMetricsFilters {
+    /** The `client_id` of one agent: read from spans, not from metrics. */
+    agent?: string;
+    org?: string;
+    /** ISO 8601; points and spans before it are left out. */
+    since?: string;
+    limit?: number;
+}
+export interface McpSliSummary {
+    /** Share of calls that were neither 5xx nor `-32001`; `null` with no call. */
+    availability: number | null;
+    /** p95 of the synchronous tools' call duration, in milliseconds. */
+    p95CallDurationMs: number | null;
+    /** `completed` over terminal tasks. */
+    taskSuccessRate: number | null;
+    /** p95 sandbox launch, in seconds, by provider. */
+    p95SandboxLaunchSeconds: Record<string, number>;
+    /** How many calls, tasks and launches the numbers rest on. */
+    samples: {
+        calls: number;
+        tasks: number;
+        launches: number;
+    };
+}
+export interface McpMetricsSnapshot {
+    filters: McpMetricsFilters;
+    /** The catalog points read, by metric name. */
+    metrics: Partial<Record<McpMetricName, OtelMetric[]>>;
+    /** The `mcp.request` spans a per-agent or per-organization reading rests on. */
+    spans: OtelSpan[];
+    slis: McpSliSummary;
+    readAt: string;
+}
+/** The nearest-rank percentile of a sample; `null` for an empty one. */
+export declare const percentile: (values: number[], fraction: number) => number | null;
+/**
+ * The SLIs over catalog points — the platform-wide reading.
+ *
+ * `mcp.calls{outcome}` gives availability, `mcp.call.duration{tool}` the
+ * latency, `mcp.tasks{status}` the task success rate and
+ * `sandbox.launch_seconds{provider}` the launches.
+ */
+export declare const summarizeMetricPoints: (metrics: Partial<Record<McpMetricName, OtelMetric[]>>, filters?: McpMetricsFilters) => McpSliSummary;
+/**
+ * The SLIs over `mcp.request` spans — the per-agent or per-organization
+ * reading, since metrics carry neither label.
+ */
+export declare const summarizeRequestSpans: (spans: OtelSpan[], filters?: McpMetricsFilters) => McpSliSummary;
+/** The four SLIs and the catalog, for everyone or for one agent or organization. */
+export declare const fetchMcpMetrics: (token: string, filters?: McpMetricsFilters, otelUrl?: string) => Promise<McpMetricsSnapshot>;
+/** A span with its children, as a tree reads. */
+export interface McpSpanNode {
+    span: OtelSpan;
+    children: McpSpanNode[];
+}
+/** The spans of a trace as a tree, roots first, siblings by start time. */
+export declare const spanTree: (spans: OtelSpan[]) => McpSpanNode[];
+export interface McpRunTrace {
+    taskUid: string;
+    traceId: string;
+    spans: OtelSpan[];
+    tree: McpSpanNode[];
+}
+/** "Show me this run": the spans of the task's trace. A task without one has none yet. */
+export declare const fetchRunTrace: (token: string, task: Pick<McpTask, "uid" | "traceId">, otelUrl?: string) => Promise<McpRunTrace>;
+/**
+ * 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 declare const fetchTraceSpans: (token: string, traceId: string, otelUrl?: string) => Promise<McpRunTrace>;
+export interface McpRunLogs {
+    taskUid: string;
+    traceId: string;
+    records: OtelLog[];
+}
+/** The log lines of a run, gateway and worker alike, by the trace they carry. */
+export declare const fetchMcpLogs: (token: string, task: Pick<McpTask, "uid" | "traceId">, options?: {
+    limit?: number;
+    severity?: string;
+}, otelUrl?: string) => Promise<McpRunLogs>;

package/lib/api/mcp/observability.js

@@ -0,0 +1,254 @@
+/*
+ * 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 gateway's metric catalog. 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 { queryMetrics } from '../otel/metrics.js';
+import { queryLogs } from '../otel/logs.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 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 over catalog points — the platform-wide reading.
+ *
+ * `mcp.calls{outcome}` gives availability, `mcp.call.duration{tool}` the
+ * latency, `mcp.tasks{status}` the task success rate and
+ * `sandbox.launch_seconds{provider}` the launches.
+ */
+export const summarizeMetricPoints = (metrics, filters = {}) => {
+    const within = (point) => notBefore(point.timestamp, filters.since);
+    const calls = (metrics['mcp.calls'] ?? []).filter(within);
+    const totalCalls = calls.reduce((sum, point) => sum + point.value, 0);
+    const failedCalls = calls
+        .filter(point => ['error', 'unavailable'].includes(attribute(point, 'outcome')))
+        .reduce((sum, point) => sum + point.value, 0);
+    const durations = (metrics['mcp.call.duration'] ?? []).filter(within).map(point => point.value);
+    const tasks = (metrics['mcp.tasks'] ?? []).filter(within);
+    const terminal = tasks.filter(point => ['completed', 'failed', 'cancelled'].includes(attribute(point, 'status')));
+    const totalTerminal = terminal.reduce((sum, point) => sum + point.value, 0);
+    const completed = terminal
+        .filter(point => attribute(point, 'status') === 'completed')
+        .reduce((sum, point) => sum + point.value, 0);
+    const launches = (metrics['sandbox.launch_seconds'] ?? []).filter(within);
+    const byProvider = new Map();
+    for (const point of launches) {
+        const provider = attribute(point, 'provider') || 'unknown';
+        byProvider.set(provider, [...(byProvider.get(provider) ?? []), point.value]);
+    }
+    const p95SandboxLaunchSeconds = {};
+    for (const [provider, values] of byProvider) {
+        const p95 = percentile(values, 0.95);
+        if (p95 !== null) {
+            p95SandboxLaunchSeconds[provider] = p95;
+        }
+    }
+    return {
+        availability: totalCalls > 0 ? (totalCalls - failedCalls) / totalCalls : null,
+        p95CallDurationMs: percentile(durations, 0.95),
+        taskSuccessRate: totalTerminal > 0 ? completed / totalTerminal : null,
+        p95SandboxLaunchSeconds,
+        samples: { calls: totalCalls, tasks: totalTerminal, launches: launches.length },
+    };
+};
+/**
+ * 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 names = Object.values(MCP_SLI_METRICS);
+    const pages = await Promise.all(names.map(name => queryMetrics(token, { metricName: name, serviceName: serviceNameFor(name), limit }, otelUrl)));
+    const metrics = {};
+    names.forEach((name, index) => {
+        metrics[name] = pages[index].data ?? [];
+    });
+    const scoped = Boolean(filters.agent || filters.org);
+    const spans = scoped
+        ? (await listTraces(token, { serviceName: MCP_GATEWAY_SERVICE_NAME, limit }, otelUrl)).data ?? []
+        : [];
+    return {
+        filters,
+        metrics,
+        spans,
+        slis: scoped ? summarizeRequestSpans(spans, filters) : summarizeMetricPoints(metrics, 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 ?? [] };
+};