@datalayer/core 1.1.66 → 1.2.12

package/lib/api/mcp/observability.js

@@ -13,17 +13,21 @@
  * 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`.
+ * 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 { queryMetrics } from '../otel/metrics.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.
  *
@@ -33,8 +37,15 @@ import { queryLogs } from '../otel/logs.js';
  * 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` a worker's relayed output is filed under.
+ *
+ * `mcp-worker` since the service was renamed to `datalayer-mcp-server`: the
+ * gateway names its workers, and a name carrying `jupyter` said the wrong
+ * thing about a process that serves Datalayer sandboxes as readily as a
+ * Jupyter server.
+ */
+export const MCP_WORKER_SERVICE_NAME = 'mcp-worker';
 /**
  * The `service.name` the durable execution service exports under.
  *
@@ -94,6 +105,21 @@ export const MCP_SLI_METRICS = {
     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) {
@@ -107,50 +133,43 @@ 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');
+    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.
+ * The SLIs from the service levels dashboard — 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.
+ * 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 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;
-        }
-    }
+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: percentile(durations, 0.95),
-        taskSuccessRate: totalTerminal > 0 ? completed / totalTerminal : null,
+        p95CallDurationMs: p95Seconds === undefined ? null : p95Seconds * 1000,
+        taskSuccessRate: terminal > 0 ? (tasks.completed ?? 0) / terminal : null,
         p95SandboxLaunchSeconds,
-        samples: { calls: totalCalls, tasks: totalTerminal, launches: launches.length },
+        samples: {
+            calls: totalCalls,
+            tasks: terminal,
+            launches: total(byLabel(MCP_SERVICE_LEVEL_PANELS.sandboxLaunches)),
+        },
     };
 };
 /**
@@ -173,8 +192,12 @@ export const summarizeRequestSpans = (spans, filters = {}) => {
     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),
+        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 },
@@ -183,21 +206,25 @@ export const summarizeRequestSpans = (spans, filters = {}) => {
 /** 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 ?? []
-        : [];
+    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,
-        metrics,
+        reporting: MCP_METRIC_CATALOG.filter(name => reported.has(name)),
         spans,
-        slis: scoped ? summarizeRequestSpans(spans, filters) : summarizeMetricPoints(metrics, filters),
+        slis: levels
+            ? summarizeServiceLevels(levels)
+            : summarizeRequestSpans(spans, filters),
         readAt: new Date().toISOString(),
     };
 };
@@ -209,7 +236,9 @@ export const spanTree = (spans) => {
     }
     const roots = [];
     for (const node of nodes.values()) {
-        const parent = node.span.parent_span_id ? nodes.get(node.span.parent_span_id) : undefined;
+        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);
@@ -227,7 +256,12 @@ export const fetchRunTrace = async (token, task, otelUrl = DEFAULT_SERVICE_URLS.
     }
     const trace = await getTrace(token, task.traceId, otelUrl);
     const spans = trace.data ?? [];
-    return { taskUid: task.uid, traceId: task.traceId, spans, tree: spanTree(spans) };
+    return {
+        taskUid: task.uid,
+        traceId: task.traceId,
+        spans,
+        tree: spanTree(spans),
+    };
 };
 /**
  * The spans of one trace, named directly.
@@ -249,6 +283,10 @@ export const fetchMcpLogs = async (token, task, options = {}, otelUrl = DEFAULT_
     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);
+    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/orchestration/client.d.ts

@@ -0,0 +1,53 @@
+import { type EvalsClientOptions, type EvalsQuery } from '../evals/request';
+import { type AgentsAttach, type AgentsCreate, type AgentsDiscover, type CancelAnswer, type CollectAnswer, type CommandAnswer, type DelegateAnswer, type DiscoverAnswer, type ExecutionAnswer, type ExecutionState, type ExecutionsAnswer, type ExecutionsCancel, type ExecutionsCheckpoint, type ExecutionsCollect, type ExecutionsDelegate, type ExecutionsPause, type ExecutionsResume, type ExecutionsSteer, type ExecutionsTerminate, type OrchestrationOperation, type ReportAnswer, type WorkerAnswer } from './generated';
+/** Who calls: the service origin, the caller's token, and the account the executions belong to. */
+export type OrchestrationClientOptions = EvalsClientOptions;
+/**
+ * One operation's method and path under `/api/ai-agents/v1`, with its
+ * parameters filled in and encoded.
+ *
+ * @throws Error when the control plane has no such operation, or a
+ * parameter the path names is missing.
+ */
+export declare const operationPath: (operation: string, parameters?: Record<string, string>) => {
+    method: OrchestrationOperation["method"];
+    path: string;
+};
+/** The full URL of one operation, with the account scope and a query. */
+export declare const operationUrl: (options: OrchestrationClientOptions, operation: string, parameters?: Record<string, string>, query?: EvalsQuery) => string;
+/** `agents.discover`: the workers meeting every constraint the command states. */
+export declare const discoverAgents: (options: OrchestrationClientOptions, command: AgentsDiscover) => Promise<DiscoverAnswer>;
+/** `agents.create`: bring a worker's compute up. */
+export declare const createAgent: (options: OrchestrationClientOptions, command: AgentsCreate) => Promise<WorkerAnswer>;
+/** `agents.attach`: a worker or a session that is already there. */
+export declare const attachAgent: (options: OrchestrationClientOptions, command: AgentsAttach) => Promise<WorkerAnswer>;
+/** `executions.delegate`: an objective and its context, to a worker. */
+export declare const delegateExecution: (options: OrchestrationClientOptions, command: ExecutionsDelegate) => Promise<DelegateAnswer>;
+/** `executions.steer`: instructions added while the work runs. */
+export declare const steerExecution: (options: OrchestrationClientOptions, command: ExecutionsSteer) => Promise<CommandAnswer>;
+/** `executions.pause`, where the worker's protocol can pause. */
+export declare const pauseExecution: (options: OrchestrationClientOptions, command: ExecutionsPause) => Promise<CommandAnswer>;
+/** `executions.resume`, from where it stopped or from a checkpoint. */
+export declare const resumeExecution: (options: OrchestrationClientOptions, command: ExecutionsResume) => Promise<CommandAnswer>;
+/** `executions.cancel`: stop the work, and by default everything below it. */
+export declare const cancelExecution: (options: OrchestrationClientOptions, command: ExecutionsCancel) => Promise<CancelAnswer>;
+/** `executions.checkpoint`, where the worker's protocol keeps state. */
+export declare const checkpointExecution: (options: OrchestrationClientOptions, command: ExecutionsCheckpoint) => Promise<CommandAnswer>;
+/** `executions.collect`: the artifacts of an execution and of its children. */
+export declare const collectExecution: (options: OrchestrationClientOptions, command: ExecutionsCollect) => Promise<CollectAnswer>;
+/** `executions.terminate`: release the worker, where its protocol can. */
+export declare const terminateExecution: (options: OrchestrationClientOptions, command: ExecutionsTerminate) => Promise<CommandAnswer>;
+/** One execution, its attempts, and the milestones it reached. */
+export declare const getExecution: (options: OrchestrationClientOptions, executionId: string) => Promise<ExecutionAnswer>;
+/**
+ * `executions.report`: the execution's live report, a document in the
+ * account's orchestration space, written the first time it is asked for and
+ * the same one after that.
+ */
+export declare const openExecutionReport: (options: OrchestrationClientOptions, executionId: string) => Promise<ReportAnswer>;
+/** The account's executions, oldest first: a tree by its root, a level by its parent. */
+export declare const listExecutions: (options: OrchestrationClientOptions, filter?: {
+    rootExecutionId?: string;
+    parentExecutionId?: string;
+    status?: ExecutionState;
+}) => Promise<ExecutionsAnswer>;

package/lib/api/orchestration/client.js

@@ -0,0 +1,105 @@
+/*
+ * 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 orchestration control plane, as a caller reaches it.
+ *
+ * Every path comes from `ORCHESTRATION_API`, which is generated from the
+ * control plane's own OpenAPI document: this module spells no URL itself, so
+ * a route that moves on the service moves here when the types are
+ * regenerated — or fails the check that they were not. A view calls these
+ * functions and never builds an orchestration path of its own.
+ *
+ * Bodies are the canonical commands as they are and answers the envelopes
+ * the service returns; the wire is camel case on both sides, so nothing is
+ * converted.
+ *
+ * @module api/orchestration/client
+ */
+import { API_BASE_PATHS } from '../constants.js';
+import { aiAgentsRequest, aiAgentsUrl, } from '../evals/request.js';
+import { ORCHESTRATION_API, } from './generated.js';
+/**
+ * One operation's method and path under `/api/ai-agents/v1`, with its
+ * parameters filled in and encoded.
+ *
+ * @throws Error when the control plane has no such operation, or a
+ * parameter the path names is missing.
+ */
+export const operationPath = (operation, parameters = {}) => {
+    const found = ORCHESTRATION_API.find(one => one.operation === operation);
+    if (!found) {
+        throw new Error(`The control plane has no operation '${operation}'.`);
+    }
+    const path = found.path.replace(/\{([^}]+)\}/g, (_, name) => {
+        const value = parameters[name];
+        if (value === undefined || value === '') {
+            throw new Error(`'${operation}' needs '${name}'.`);
+        }
+        return encodeURIComponent(value);
+    });
+    if (!path.startsWith(API_BASE_PATHS.AI_AGENTS)) {
+        throw new Error(`'${operation}' is not under ${API_BASE_PATHS.AI_AGENTS}: ${found.path}`);
+    }
+    return {
+        method: found.method,
+        path: path.slice(API_BASE_PATHS.AI_AGENTS.length),
+    };
+};
+/** The full URL of one operation, with the account scope and a query. */
+export const operationUrl = (options, operation, parameters = {}, query = {}) => aiAgentsUrl(options, operationPath(operation, parameters).path, query);
+const call = (options, operation, init = {}) => {
+    const { method, path } = operationPath(operation, init.parameters);
+    return aiAgentsRequest(options, path, {
+        method,
+        body: init.body,
+        query: init.query,
+    });
+};
+/** `agents.discover`: the workers meeting every constraint the command states. */
+export const discoverAgents = (options, command) => call(options, 'agents.discover', { body: command });
+/** `agents.create`: bring a worker's compute up. */
+export const createAgent = (options, command) => call(options, 'agents.create', { body: command });
+/** `agents.attach`: a worker or a session that is already there. */
+export const attachAgent = (options, command) => call(options, 'agents.attach', { body: command });
+/** `executions.delegate`: an objective and its context, to a worker. */
+export const delegateExecution = (options, command) => call(options, 'executions.delegate', { body: command });
+/** `executions.steer`: instructions added while the work runs. */
+export const steerExecution = (options, command) => call(options, 'executions.steer', { body: command });
+/** `executions.pause`, where the worker's protocol can pause. */
+export const pauseExecution = (options, command) => call(options, 'executions.pause', { body: command });
+/** `executions.resume`, from where it stopped or from a checkpoint. */
+export const resumeExecution = (options, command) => call(options, 'executions.resume', { body: command });
+/** `executions.cancel`: stop the work, and by default everything below it. */
+export const cancelExecution = (options, command) => call(options, 'executions.cancel', { body: command });
+/** `executions.checkpoint`, where the worker's protocol keeps state. */
+export const checkpointExecution = (options, command) => call(options, 'executions.checkpoint', { body: command });
+/** `executions.collect`: the artifacts of an execution and of its children. */
+export const collectExecution = (options, command) => call(options, 'executions.collect', { body: command });
+/** `executions.terminate`: release the worker, where its protocol can. */
+export const terminateExecution = (options, command) => call(options, 'executions.terminate', { body: command });
+/** One execution, its attempts, and the milestones it reached. */
+export const getExecution = (options, executionId) => call(options, 'executions.get', {
+    parameters: { execution_id: executionId },
+});
+/**
+ * `executions.report`: the execution's live report, a document in the
+ * account's orchestration space, written the first time it is asked for and
+ * the same one after that.
+ */
+export const openExecutionReport = (options, executionId) => call(options, 'executions.report', {
+    parameters: { execution_id: executionId },
+});
+/** The account's executions, oldest first: a tree by its root, a level by its parent. */
+export const listExecutions = (options, filter = {}) => call(options, 'executions.list', {
+    query: {
+        rootExecutionId: filter.rootExecutionId,
+        parentExecutionId: filter.parentExecutionId,
+        status: filter.status,
+    },
+});

package/lib/api/orchestration/events.d.ts

@@ -0,0 +1,88 @@
+import { type OrchestrationClientOptions } from './client';
+import type { ExecutionEvent, LifecycleEvent, TreeSummary } from './generated';
+/** The user channel's event for a tree that moved, and the stream's roll-up. */
+export declare const TREE_EVENT = "orchestration.tree";
+/** One Server-Sent Event, as it was framed. */
+export interface ServerSentEvent {
+    id?: string;
+    event: string;
+    data: string;
+}
+/**
+ * Split what has arrived into the complete events and what is left over,
+ * which is the beginning of an event still arriving.
+ */
+export declare const readServerSentEvents: (buffer: string) => {
+    events: ServerSentEvent[];
+    rest: string;
+};
+/** The service refused the subscription; asking again would be refused again. */
+export declare class SubscriptionRefused extends Error {
+    readonly status: number;
+    readonly detail: string;
+    constructor(status: number, detail: string);
+}
+/** What `fetch` answers, as much of it as a subscription reads. */
+interface StreamedResponse {
+    ok: boolean;
+    status: number;
+    body: ReadableStream<Uint8Array> | null;
+    text(): Promise<string>;
+}
+export interface SubscribeOptions {
+    /** Every event of the tree below the execution too; the service's default. */
+    includeChildren?: boolean;
+    /** Replay the execution's own events after this sequence. */
+    fromSequence?: number;
+    /** Only these lifecycle events; every event when empty. */
+    events?: LifecycleEvent[];
+    /** The id of the last event already received, to resume after it. */
+    lastEventId?: string;
+    /** Each event once, in the order the service sent them, with the cursor it moved the subscription to. */
+    onEvent: (event: ExecutionEvent, cursor: string) => void;
+    /** What the executions the subscription covers are doing, after each batch of events that changed it. */
+    onTree?: (tree: TreeSummary, cursor: string) => void;
+    /** The subscription ended because every execution it covers is over. */
+    onEnd?: () => void;
+    /** How many drops in a row, with no event between them, before giving up. */
+    maxReconnects?: number;
+    /** How long to wait before reconnecting, in milliseconds. */
+    reconnectDelayMs?: number;
+    signal?: AbortSignal;
+    /** The `fetch` to use; the global one by default. */
+    fetch?: (url: string, init: RequestInit) => Promise<StreamedResponse>;
+}
+export interface Subscription {
+    /** Settles when the stream ends, is aborted, or cannot be resumed. */
+    done: Promise<void>;
+    /** The id a later subscription resumes from. */
+    lastEventId: () => string | undefined;
+}
+/**
+ * Subscribe to an execution — and its tree — until it is over.
+ *
+ * A dropped connection, before the service answered or in the middle of the
+ * stream, is resumed from the last event received. A refusal is not: it
+ * rejects `done` with `SubscriptionRefused`. An abort ends the subscription
+ * quietly, because stopping is the caller's decision rather than a failure.
+ */
+export declare const subscribeToExecution: (options: OrchestrationClientOptions, executionId: string, subscribe: SubscribeOptions) => Subscription;
+/**
+ * What a tree is doing, worked out from its canonical events alone (O2-03).
+ *
+ * The same summary the subscription sends as `orchestration.tree`: each
+ * execution's latest state, its parent, its worker and its goal — the message
+ * of the event that created it — and its depth below the first execution the
+ * events cover. Each execution's events are read in their own sequence,
+ * whatever order they arrived in.
+ */
+export declare const treeFromEvents: (events: readonly ExecutionEvent[]) => TreeSummary;
+/** A message of the app's user channel announcing that a tree moved. */
+export interface TreeAnnouncement {
+    channel: string;
+    event: typeof TREE_EVENT;
+    data: TreeSummary;
+}
+/** Whether a user-channel message is a tree announcement. */
+export declare const isTreeAnnouncement: (message: unknown) => message is TreeAnnouncement;
+export {};