@datalayer/core 1.1.66 → 1.2.10

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 {};

package/lib/api/orchestration/events.js

@@ -0,0 +1,245 @@
+/*
+ * Copyright (c) 2023-2025 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { operationUrl } from './client.js';
+import { isTerminal } from './lifecycle.js';
+/** The user channel's event for a tree that moved, and the stream's roll-up. */
+export const TREE_EVENT = 'orchestration.tree';
+/**
+ * Split what has arrived into the complete events and what is left over,
+ * which is the beginning of an event still arriving.
+ */
+export const readServerSentEvents = (buffer) => {
+    const blocks = buffer.replace(/\r\n/g, '\n').split('\n\n');
+    const rest = blocks.pop() ?? '';
+    const events = blocks
+        .filter(block => block.trim() !== '')
+        .map(block => {
+        const framed = { event: 'message', data: '' };
+        const data = [];
+        for (const line of block.split('\n')) {
+            if (line.startsWith(':')) {
+                continue;
+            }
+            const colon = line.indexOf(':');
+            const field = colon === -1 ? line : line.slice(0, colon);
+            const value = colon === -1 ? '' : line.slice(colon + 1).replace(/^ /, '');
+            if (field === 'id') {
+                framed.id = value;
+            }
+            else if (field === 'event') {
+                framed.event = value;
+            }
+            else if (field === 'data') {
+                data.push(value);
+            }
+        }
+        framed.data = data.join('\n');
+        return framed;
+    });
+    return { events, rest };
+};
+/** The service refused the subscription; asking again would be refused again. */
+export class SubscriptionRefused extends Error {
+    status;
+    detail;
+    constructor(status, detail) {
+        super(`The subscription was refused with ${status}: ${detail}`);
+        this.status = status;
+        this.detail = detail;
+        this.name = 'SubscriptionRefused';
+    }
+}
+const pause = (milliseconds, signal) => new Promise(resolve => {
+    if (milliseconds <= 0 || signal?.aborted) {
+        resolve();
+        return;
+    }
+    const timer = setTimeout(resolve, milliseconds);
+    signal?.addEventListener('abort', () => {
+        clearTimeout(timer);
+        resolve();
+    }, { once: true });
+});
+/**
+ * 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 const subscribeToExecution = (options, executionId, subscribe) => {
+    let lastEventId = subscribe.lastEventId;
+    const fetcher = subscribe.fetch ??
+        ((url, init) => fetch(url, init));
+    const query = {
+        includeChildren: subscribe.includeChildren,
+        fromSequence: subscribe.fromSequence,
+    };
+    const address = new URL(operationUrl(options, 'executions.subscribe', { execution_id: executionId }, query));
+    for (const wanted of subscribe.events ?? []) {
+        address.searchParams.append('events', wanted);
+    }
+    const url = address.toString();
+    const maxReconnects = subscribe.maxReconnects ?? 5;
+    const run = async () => {
+        let dropsInARow = 0;
+        for (;;) {
+            const headers = { Accept: 'text/event-stream' };
+            if (options.token) {
+                headers.Authorization = `Bearer ${options.token}`;
+            }
+            if (lastEventId) {
+                headers['Last-Event-ID'] = lastEventId;
+            }
+            let response;
+            try {
+                response = await fetcher(url, {
+                    headers,
+                    signal: subscribe.signal,
+                    credentials: 'include',
+                });
+            }
+            catch {
+                if (subscribe.signal?.aborted) {
+                    return;
+                }
+            }
+            if (response && !response.ok) {
+                throw new SubscriptionRefused(response.status, await response.text());
+            }
+            let ended = false;
+            if (response?.body) {
+                const reader = response.body.getReader();
+                const decoder = new TextDecoder();
+                let buffer = '';
+                for (;;) {
+                    let chunk;
+                    try {
+                        chunk = await reader.read();
+                    }
+                    catch {
+                        if (subscribe.signal?.aborted) {
+                            return;
+                        }
+                        break;
+                    }
+                    if (chunk.done) {
+                        break;
+                    }
+                    buffer += decoder.decode(chunk.value, { stream: true });
+                    const { events, rest } = readServerSentEvents(buffer);
+                    buffer = rest;
+                    for (const framed of events) {
+                        if (framed.event === 'end') {
+                            ended = true;
+                            continue;
+                        }
+                        if (framed.id) {
+                            lastEventId = framed.id;
+                        }
+                        if (framed.event === TREE_EVENT) {
+                            subscribe.onTree?.(JSON.parse(framed.data), framed.id ?? '');
+                        }
+                        else {
+                            subscribe.onEvent(JSON.parse(framed.data), framed.id ?? '');
+                        }
+                        dropsInARow = 0;
+                    }
+                }
+            }
+            if (ended) {
+                subscribe.onEnd?.();
+                return;
+            }
+            if (subscribe.signal?.aborted) {
+                return;
+            }
+            dropsInARow += 1;
+            if (dropsInARow > maxReconnects) {
+                throw new Error(`The subscription to '${executionId}' dropped ${dropsInARow} times with no event in between.`);
+            }
+            await pause(subscribe.reconnectDelayMs ?? 1000, subscribe.signal);
+        }
+    };
+    return { done: run(), lastEventId: () => lastEventId };
+};
+/**
+ * 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 const treeFromEvents = (events) => {
+    const nodes = new Map();
+    let root = '';
+    const ordered = [...events].sort((one, other) => one.executionId === other.executionId
+        ? one.sequence - other.sequence
+        : one.executionId < other.executionId
+            ? -1
+            : 1);
+    for (const event of ordered) {
+        root = root || event.rootExecutionId;
+        let node = nodes.get(event.executionId);
+        if (!node) {
+            node = {
+                parent: event.parentExecutionId ?? null,
+                goal: event.message ?? '',
+                agentId: '',
+                updatedAt: event.emittedAt,
+            };
+            nodes.set(event.executionId, node);
+        }
+        node.agentId = event.agentId ?? node.agentId;
+        node.protocol = event.protocol ?? node.protocol;
+        node.status = event.state ?? node.status;
+        node.updatedAt = event.emittedAt;
+    }
+    const depth = (executionId) => {
+        const parent = nodes.get(executionId)?.parent;
+        return parent && nodes.has(parent) ? depth(parent) + 1 : 0;
+    };
+    const executions = [];
+    for (const [executionId, node] of nodes) {
+        if (node.status && node.protocol) {
+            executions.push({
+                executionId,
+                parentExecutionId: node.parent,
+                depth: depth(executionId),
+                status: node.status,
+                agentId: node.agentId,
+                protocol: node.protocol,
+                goal: node.goal,
+                updatedAt: node.updatedAt,
+            });
+        }
+    }
+    const counts = {};
+    for (const one of executions) {
+        counts[one.status] = (counts[one.status] ?? 0) + 1;
+    }
+    return {
+        rootExecutionId: root,
+        executions,
+        counts,
+        terminal: executions.every(one => isTerminal(one.status)),
+    };
+};
+/** Whether a user-channel message is a tree announcement. */
+export const isTreeAnnouncement = (message) => {
+    if (typeof message !== 'object' || message === null) {
+        return false;
+    }
+    const { event, data } = message;
+    return (event === TREE_EVENT &&
+        typeof data === 'object' &&
+        data !== null &&
+        typeof data.rootExecutionId ===
+            'string' &&
+        Array.isArray(data.executions));
+};