@datalayer/agent-runtimes 1.0.28 → 1.3.10

package/lib/api/notifications.js

@@ -5,17 +5,34 @@
 /**
  * Agent notifications API functions.
  *
- * Provides CRUD operations for agent-generated notifications.
- * Agents emit notifications for guardrail events, budget warnings,
- * task completions, and other notable events.
+ * The caller's inbox on the AI Agents service: agents emit notifications for
+ * guardrail events, budget warnings and task completions, and benchmark runs,
+ * approvals and investigations leave theirs too. Every route answers for the
+ * caller's own notifications only.
+ *
+ * The service answers snake case records inside an envelope; these functions
+ * return `AgentNotification`s, so a caller never reads the wire shape.
  *
  * @module api/notifications
  */
 import { requestDatalayerAPI } from '@datalayer/core/lib/api/DatalayerApi';
 import { API_BASE_PATHS, DEFAULT_SERVICE_URLS, } from '@datalayer/core/lib/api/constants';
 import { validateToken } from '@datalayer/core/lib/api/utils/validation';
+/** A record of the service as the notification this client returns. */
+export const toAgentNotification = (record) => ({
+    id: record.id,
+    agentId: record.agent_id ?? '',
+    runtimeName: '',
+    level: (record.level ?? 'info'),
+    title: record.title ?? '',
+    body: record.message ?? '',
+    read: Boolean(record.read),
+    createdAt: record.created_at ?? '',
+    category: record.category ?? 'general',
+    metadata: record.metadata ?? {},
+});
 /**
- * List agent notifications with optional filters.
+ * List the caller's notifications with optional filters.
  * @param token - Authentication token
  * @param filters - Optional filters (agentId, level, unreadOnly, category, limit, offset)
  * @param baseUrl - Base URL
@@ -37,25 +54,27 @@ export const getNotifications = async (token, filters, baseUrl = DEFAULT_SERVICE
     if (filters?.offset)
         params.set('offset', String(filters.offset));
     const query = params.toString() ? `?${params.toString()}` : '';
-    return requestDatalayerAPI({
+    const answer = await requestDatalayerAPI({
         url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/notifications${query}`,
         method: 'GET',
         token,
     });
+    return (answer?.notifications ?? []).map(toAgentNotification);
 };
 /**
- * Get a specific notification by ID.
+ * Get one of the caller's notifications by ID.
  * @param token - Authentication token
  * @param id - Notification ID
  * @param baseUrl - Base URL
  */
 export const getNotification = async (token, id, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
     validateToken(token);
-    return requestDatalayerAPI({
+    const record = await requestDatalayerAPI({
         url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/notifications/${encodeURIComponent(id)}`,
         method: 'GET',
         token,
     });
+    return toAgentNotification(record);
 };
 /**
  * Mark a notification as read.
@@ -72,23 +91,22 @@ export const markNotificationRead = async (token, id, baseUrl = DEFAULT_SERVICE_
     });
 };
 /**
- * Mark all notifications as read.
+ * Mark the caller's notifications as read: the ones named, or all of them.
  * @param token - Authentication token
- * @param agentId - Optional: only for a specific agent
+ * @param notificationIds - Optional: only these notifications
  * @param baseUrl - Base URL
  */
-export const markAllRead = async (token, agentId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+export const markAllRead = async (token, notificationIds, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
     validateToken(token);
-    const body = agentId ? { agent_id: agentId } : {};
     await requestDatalayerAPI({
-        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/notifications/read-all`,
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/notifications/mark-all-read`,
         method: 'POST',
-        body,
+        body: notificationIds?.length ? { notification_ids: notificationIds } : {},
         token,
     });
 };
 /**
- * Get count of unread notifications.
+ * Get the count of the caller's unread notifications.
  * @param token - Authentication token
  * @param baseUrl - Base URL
  * @returns Promise resolving to unread count

package/lib/api/runtimes/environments.d.ts

@@ -1,9 +1,390 @@
-import { ListEnvironmentsResponse } from '../../models/EnvironmentDTO';
+import type { EnvironmentData, ListEnvironmentsResponse } from '../../models/EnvironmentDTO';
+import type { ICreateEnvironmentBuildsRequest, ICreateEnvironmentRequest, ICreateEnvironmentVersionRequest, IDatalayerEnvironment, IEnvironmentArtifactsPage, IEnvironmentBuildLogChunk, IEnvironmentBuildLogPage, IEnvironmentBuildRecord, IEnvironmentBuildsCreated, IEnvironmentBuildsPage, IEnvironmentFork, IEnvironmentPublicationRecord, IEnvironmentRecord, IEnvironmentsError, IEnvironmentsPageQuery, IEnvironmentTrial, IEnvironmentValidationReport, IEnvironmentVersionRecord, IEnvironmentVersionsPage, IForkEnvironmentVersionRequest, IListEnvironmentsQuery, IPromoteEnvironmentVersionRequest, ITrialEnvironmentVersionRequest, IUpdateEnvironmentRequest, IUpdateEnvironmentVersionRequest, IValidateEnvironmentVersionRequest } from '../../models/Environment';
+/** What every environments call may carry. */
+export interface IEnvironmentsRequestOptions {
+    /** Sent as `X-Correlation-Id`; a refusal answers with it. */
+    correlationId?: string;
+    /** Cancels the request. */
+    signal?: AbortSignal;
+}
+/** A create the service replays: the same key answers the first resource. */
+export interface IEnvironmentsIdempotentOptions extends IEnvironmentsRequestOptions {
+    /** Sent as `Idempotency-Key`. */
+    idempotencyKey?: string;
+}
+/** A write that may name the record it replaces. */
+export interface IEnvironmentsConditionalOptions extends IEnvironmentsRequestOptions {
+    /** Sent as `If-Match`: the `etag` of the record read. */
+    ifMatch?: string;
+}
 /**
- * List all available computing environments.
+ * A page of `GET /environments`: the platform's entries, on the first page
+ * only, then the user environments the caller may use.
+ */
+export type ListEnvironmentsPage = Omit<ListEnvironmentsResponse, 'environments'> & {
+    environments: Array<EnvironmentData & Pick<IDatalayerEnvironment, 'uid' | 'origin' | 'owner' | 'promotedVersion' | 'variants' | 'availableVariants' | 'sizeClass'>>;
+    /** The cursor of the next page; absent on the last one. */
+    nextCursor?: string;
+};
+/**
+ * The section 10 body of a refusal, from the error a call rejected with.
+ *
+ * @param error - What an environments call rejected with
+ * @returns The body, with its `code` and `correlationId`; `undefined` when the
+ *   error is not a refusal that carries one
+ */
+export declare const asEnvironmentsError: (error: unknown) => Promise<IEnvironmentsError | undefined>;
+/**
+ * List the environments the caller may use: the platform's, then its own and
+ * its organizations'.
  * @param token - Authentication token
  * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
- * @returns Promise resolving to list of available environments
+ * @param query - Filters, and the cursor of the page to read
+ * @param options - Correlation id and abort signal
+ * @returns Promise resolving to one page of environments
  * @throws {Error} If authentication token is missing or invalid
  */
-export declare const listEnvironments: (token: string, baseUrl?: string) => Promise<ListEnvironmentsResponse>;
+export declare const listEnvironments: (token: string, baseUrl?: string, query?: IListEnvironmentsQuery, options?: IEnvironmentsRequestOptions) => Promise<ListEnvironmentsPage>;
+/**
+ * Create a user environment, for the caller's account or an organization it owns.
+ * @param token - Authentication token
+ * @param request - Its name, and optionally title, description, visibility and owner
+ * @param options - Idempotency key, correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the environment created, or the one a replayed key created
+ */
+export declare const createEnvironment: (token: string, request: ICreateEnvironmentRequest, options?: IEnvironmentsIdempotentOptions, baseUrl?: string) => Promise<IEnvironmentRecord>;
+/**
+ * Get a user environment.
+ * @param token - Authentication token
+ * @param environmentUid - The environment's uid
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the environment
+ */
+export declare const getEnvironment: (token: string, environmentUid: string, options?: IEnvironmentsRequestOptions, baseUrl?: string) => Promise<IEnvironmentRecord>;
+/**
+ * Change an environment's title, description or visibility.
+ * @param token - Authentication token
+ * @param environmentUid - The environment's uid
+ * @param changes - The fields to change
+ * @param ifMatch - The `etag` of the environment read; a stale one is refused with 412
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the environment changed
+ */
+export declare const updateEnvironment: (token: string, environmentUid: string, changes: IUpdateEnvironmentRequest, ifMatch: string, options?: IEnvironmentsRequestOptions, baseUrl?: string) => Promise<IEnvironmentRecord>;
+/**
+ * Delete an environment, softly. Refused with 409 `DL_ENV_CONFLICT` while a
+ * version is promoted, an artifact is referenced, or a runtime still runs one
+ * of its artifacts, whoever launched it: the refusal's `detail` is an
+ * `IEnvironmentDeletionConflict`, whose `runtimes` name each one (E1-15).
+ * Refused with 503 `DL_ENV_UNAVAILABLE` when the service cannot read which
+ * runtimes run it; nothing is deleted then either.
+ * @param token - Authentication token
+ * @param environmentUid - The environment's uid
+ * @param options - If-Match, correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving once the environment is deleted
+ */
+export declare const deleteEnvironment: (token: string, environmentUid: string, options?: IEnvironmentsConditionalOptions, baseUrl?: string) => Promise<void>;
+/**
+ * Archive an environment: kept and readable, no longer offered for launches.
+ * @param token - Authentication token
+ * @param environmentUid - The environment's uid
+ * @param options - If-Match, correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the environment archived
+ */
+export declare const archiveEnvironment: (token: string, environmentUid: string, options?: IEnvironmentsConditionalOptions, baseUrl?: string) => Promise<IEnvironmentRecord>;
+/**
+ * Promote a version, or none with `versionUid: null`; a rollback is the same
+ * call with an older version, and builds nothing (E1-15).
+ *
+ * A partially ready version is promoted only when
+ * `acknowledgeUnavailableVariants` names exactly its unavailable variants:
+ * otherwise 409 `DL_ENV_CONFLICT`, whose `detail` is an
+ * `IEnvironmentPromotionConflict` naming them. The promotion is recorded on
+ * the version, as its `promotion`. Asking again for the version already
+ * promoted writes nothing and answers the environment, even with a stale
+ * `If-Match`; asking for another with a stale one is refused with 412.
+ * @param token - Authentication token
+ * @param environmentUid - The environment's uid
+ * @param request - `{versionUid, acknowledgeUnavailableVariants}`
+ * @param ifMatch - The `etag` of the environment read; a stale one is refused with 412
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the environment, naming its promoted version
+ */
+export declare const promoteEnvironmentVersion: (token: string, environmentUid: string, request: IPromoteEnvironmentVersionRequest, ifMatch: string, options?: IEnvironmentsRequestOptions, baseUrl?: string) => Promise<IEnvironmentRecord>;
+/**
+ * Create a draft version of an environment from a specification.
+ * @param token - Authentication token
+ * @param environmentUid - The environment's uid
+ * @param request - `{spec, label}`
+ * @param options - Idempotency key, correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the draft, or the one a replayed key created
+ */
+export declare const createEnvironmentVersion: (token: string, environmentUid: string, request: ICreateEnvironmentVersionRequest, options?: IEnvironmentsIdempotentOptions, baseUrl?: string) => Promise<IEnvironmentVersionRecord>;
+/**
+ * List an environment's versions, newest first.
+ * @param token - Authentication token
+ * @param environmentUid - The environment's uid
+ * @param page - The cursor of the page to read, and its size
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to one page of versions
+ */
+export declare const listEnvironmentVersions: (token: string, environmentUid: string, page?: IEnvironmentsPageQuery, options?: IEnvironmentsRequestOptions, baseUrl?: string) => Promise<IEnvironmentVersionsPage>;
+/**
+ * Get a version, with its specification and its status.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the version
+ */
+export declare const getEnvironmentVersion: (token: string, versionUid: string, options?: IEnvironmentsRequestOptions, baseUrl?: string) => Promise<IEnvironmentVersionRecord>;
+/**
+ * Edit a draft's specification or label.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param changes - `{spec, label}`, either or both
+ * @param ifMatch - The `etag` of the version read; a stale one is refused with 412
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the draft changed
+ */
+export declare const updateEnvironmentVersion: (token: string, versionUid: string, changes: IUpdateEnvironmentVersionRequest, ifMatch: string, options?: IEnvironmentsRequestOptions, baseUrl?: string) => Promise<IEnvironmentVersionRecord>;
+/**
+ * Validate a version: a dry run answering a capability report per variant.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param request - `{variants}`: the version's own variants when absent
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the report
+ */
+export declare const validateEnvironmentVersion: (token: string, versionUid: string, request?: IValidateEnvironmentVersionRequest, options?: IEnvironmentsRequestOptions, baseUrl?: string) => Promise<IEnvironmentValidationReport>;
+/**
+ * Resolve a version into its lock. The service answers 501 until PLAN_ENV.md
+ * E1-04 builds the resolver, whose answer this resolves to.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the service's answer
+ */
+export declare const resolveEnvironmentVersion: (token: string, versionUid: string, options?: IEnvironmentsRequestOptions, baseUrl?: string) => Promise<unknown>;
+/**
+ * Queue a build per variant and region.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param request - `{variants, requiredVariants, regions, force}`
+ * @param options - Idempotency key, correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the builds queued, or those a replayed key queued
+ */
+export declare const createEnvironmentBuilds: (token: string, versionUid: string, request?: ICreateEnvironmentBuildsRequest, options?: IEnvironmentsIdempotentOptions, baseUrl?: string) => Promise<IEnvironmentBuildsCreated>;
+/**
+ * List a version's builds, newest first.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param page - The cursor of the page to read, and its size
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to one page of builds
+ */
+export declare const listEnvironmentBuilds: (token: string, versionUid: string, page?: IEnvironmentsPageQuery, options?: IEnvironmentsRequestOptions, baseUrl?: string) => Promise<IEnvironmentBuildsPage>;
+/**
+ * List a version's artifacts, one per variant and region.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param page - The cursor of the page to read, and its size
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to one page of artifacts
+ */
+export declare const listEnvironmentArtifacts: (token: string, versionUid: string, page?: IEnvironmentsPageQuery, options?: IEnvironmentsRequestOptions, baseUrl?: string) => Promise<IEnvironmentArtifactsPage>;
+/**
+ * Launch a trial sandbox of a ready or partially ready version, before it is
+ * promoted (E1-14).
+ *
+ * Only an owner tries a version. The runtime is launched as `POST /runtimes`
+ * launches one, with the version pinned, a given name saying which version it
+ * tries, and a credits limit no higher than the service's cap. A draft, a
+ * failed or a deprecated version is refused with 409 `DL_ENV_CONFLICT`, and a
+ * version with no artifact on the plane with 422 `DL_ENV_ARTIFACT_MISSING`.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param request - `{creditsLimit}`, lowered to the service's cap when higher
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the runtime launched, its environment naming the version and artifact
+ */
+export declare const trialEnvironmentVersion: (token: string, versionUid: string, request?: ITrialEnvironmentVersionRequest, options?: IEnvironmentsRequestOptions, baseUrl?: string) => Promise<IEnvironmentTrial>;
+/**
+ * Publish a promoted version to the public Library (D-12, E2-15).
+ *
+ * Only an owner publishes (D-19), and only a version whose every input is
+ * public — no build secret, only public indexes — and whose Datalayer
+ * artifact passed its scan: otherwise the refusal is `DL_ENV_PUBLICATION_BLOCKED`.
+ * The snapshot frozen is immutable, so publishing the same version again reads
+ * it back and a withdrawal followed by a re-publish restores exactly what was
+ * public.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param options - Optional If-Match, correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the publication, with its immutable snapshot
+ */
+export declare const publishEnvironmentVersion: (token: string, versionUid: string, options?: IEnvironmentsConditionalOptions, baseUrl?: string) => Promise<IEnvironmentPublicationRecord>;
+/**
+ * Withdraw a version from the public Library; running sandboxes keep it (D-12,
+ * E2-15). The snapshot is kept, so a later publish restores exactly what was
+ * public.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the withdrawn publication
+ */
+export declare const unpublishEnvironmentVersion: (token: string, versionUid: string, options?: IEnvironmentsRequestOptions, baseUrl?: string) => Promise<IEnvironmentPublicationRecord>;
+/**
+ * A version's public publication and its immutable snapshot (D-12, E2-15), or
+ * a 404 when it is not public. The publication is world-visible, so any
+ * signed-in caller reads it; a version never published, or one withdrawn,
+ * reads 404.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the publication, with its immutable snapshot
+ */
+export declare const getEnvironmentPublication: (token: string, versionUid: string, options?: IEnvironmentsRequestOptions, baseUrl?: string) => Promise<IEnvironmentPublicationRecord>;
+/**
+ * Fork a published version into the caller's own private environment (D-12,
+ * E2-15).
+ *
+ * Any signed-in caller forks. The fork is made from the published version's
+ * exact spec and reuses the published Datalayer artifact — the same immutable
+ * reference — when its inputs are unchanged, so it launches without a rebuild;
+ * a fork under a new `name` re-specialises the spec and builds fresh.
+ * @param token - Authentication token
+ * @param versionUid - The published version's uid
+ * @param request - `{name}`: the source environment's name by default
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the fork: its environment, version and reused artifacts
+ */
+export declare const forkEnvironmentVersion: (token: string, versionUid: string, request?: IForkEnvironmentVersionRequest, options?: IEnvironmentsRequestOptions, baseUrl?: string) => Promise<IEnvironmentFork>;
+/**
+ * Deprecate a version: no new launches, and running sandboxes keep it.
+ * @param token - Authentication token
+ * @param versionUid - The version's uid
+ * @param options - If-Match, correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the version deprecated
+ */
+export declare const deprecateEnvironmentVersion: (token: string, versionUid: string, options?: IEnvironmentsConditionalOptions, baseUrl?: string) => Promise<IEnvironmentVersionRecord>;
+/**
+ * Get a build.
+ * @param token - Authentication token
+ * @param buildUid - The build's uid
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the build
+ */
+export declare const getEnvironmentBuild: (token: string, buildUid: string, options?: IEnvironmentsRequestOptions, baseUrl?: string) => Promise<IEnvironmentBuildRecord>;
+/**
+ * Read a build's stored log chunks after a cursor: the polling side of D-15.
+ * @param token - Authentication token
+ * @param buildUid - The build's uid
+ * @param page - `cursor`, the sequence of the last chunk read, and the page size
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the chunks, the next cursor, and whether the log is complete
+ */
+export declare const getEnvironmentBuildLogs: (token: string, buildUid: string, page?: IEnvironmentsPageQuery, options?: IEnvironmentsRequestOptions, baseUrl?: string) => Promise<IEnvironmentBuildLogPage>;
+/**
+ * Cancel a build that has not ended.
+ * @param token - Authentication token
+ * @param buildUid - The build's uid
+ * @param options - If-Match, correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the build cancelled
+ */
+export declare const cancelEnvironmentBuild: (token: string, buildUid: string, options?: IEnvironmentsConditionalOptions, baseUrl?: string) => Promise<IEnvironmentBuildRecord>;
+/**
+ * Queue the next attempt of a cancelled build, or of one that failed under a
+ * retryable code, once however often it is asked for.
+ *
+ * A retryable failure — a timeout, a quota, a missing artifact, an unmapped
+ * provider failure — reopens its version, `failed` back to `building`. Any
+ * other failure is refused with `DL_ENV_CONFLICT` naming the code: a new
+ * version is what changes it, not another attempt.
+ * @param token - Authentication token
+ * @param buildUid - The build's uid
+ * @param options - Correlation id and abort signal
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns Promise resolving to the attempt queued
+ */
+export declare const retryEnvironmentBuild: (token: string, buildUid: string, options?: IEnvironmentsRequestOptions, baseUrl?: string) => Promise<IEnvironmentBuildRecord>;
+/** The event the log stream ends with, once the build is terminal and every chunk is sent. */
+export declare const BUILD_LOG_END_EVENT = "end";
+/** The service refused to stream the log; asking again would be refused again. */
+export declare class BuildLogSubscriptionRefused extends Error {
+    readonly status: number;
+    readonly detail: string;
+    constructor(status: number, detail: string);
+}
+/** What `fetch` answers, as much of it as a subscription reads. */
+export interface IBuildLogStreamResponse {
+    ok: boolean;
+    status: number;
+    body: ReadableStream<Uint8Array> | null;
+    text(): Promise<string>;
+}
+export interface ISubscribeToBuildLogsOptions {
+    /** The id of the last event already received, to resume after it. */
+    lastEventId?: string;
+    /** Each chunk once, in sequence, with the id the subscription resumes from. */
+    onChunk: (chunk: IEnvironmentBuildLogChunk, lastEventId: string) => void;
+    /** The stream ended because the build is terminal and every chunk was sent. */
+    onEnd?: () => void;
+    /** How many drops in a row, with no chunk 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<IBuildLogStreamResponse>;
+}
+export interface IBuildLogSubscription {
+    /** Settles when the stream ends, is aborted, or cannot be resumed. */
+    done: Promise<void>;
+    /** The id a later subscription resumes from. */
+    lastEventId: () => string | undefined;
+}
+/**
+ * Follow a build's log until the build is terminal (D-15).
+ *
+ * Modelled on core's `subscribeToExecution`: the stream is Server-Sent Events
+ * read with `fetch`, which unlike `EventSource` carries the bearer token. Each
+ * event's id is the sequence of its chunk. A connection that drops, before the
+ * service answered or in the middle of the stream, is resumed with the last id
+ * received as `Last-Event-ID`, so no chunk is repeated; after `maxReconnects`
+ * drops in a row with no chunk between them, `done` rejects. The stream ends
+ * with `end` once the build is terminal and every chunk is sent (E1-16). A
+ * refusal is not retried: `done` rejects with `BuildLogSubscriptionRefused`,
+ * such as the 404 a caller who may not read the build is answered before the
+ * stream opens. An abort ends the subscription quietly.
+ *
+ * @param token - Authentication token
+ * @param buildUid - The build's uid
+ * @param subscribe - The callbacks, the resume point and the reconnect bounds
+ * @param baseUrl - Base URL for the API (defaults to production Runtimes URL)
+ * @returns The subscription
+ */
+export declare const subscribeToBuildLogs: (token: string, buildUid: string, subscribe: ISubscribeToBuildLogsOptions, baseUrl?: string) => IBuildLogSubscription;