@datalayer/agent-runtimes 1.0.29 → 1.3.11

package/lib/runtimes/browser/model.js

@@ -0,0 +1,110 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ *
+ * MIT License
+ */
+/**
+ * The model a browser agent talks to.
+ *
+ * A page cannot hold an AWS credential, so an in-browser agent does not reach
+ * Bedrock directly — it reaches the Datalayer inference service, which is
+ * OpenAI-compatible, holds the AWS credentials on the other side, and routes
+ * to Bedrock through LiteLLM. The SDK's OpenAI provider pointed at that base
+ * URL is the whole of it.
+ *
+ * **The service authenticates.** Every route on it requires a platform member,
+ * so a browser agent needs the signed-in person's Datalayer token and is
+ * refused with a 401 without one. This is the one thing an in-browser agent
+ * cannot do without a server: no runtime, no sandbox, but still an account.
+ * {@link createBrowserModel} sends the token as the bearer credential, so the
+ * request is attributed to the person making it and their usage is metered
+ * like any other.
+ *
+ * The model *name* needs no translation. A spec writes
+ * `bedrock:us.anthropic.claude-sonnet-4-6`, and the inference service already
+ * normalises that prefix for LiteLLM — the same string the server-side harness
+ * sends. Both harnesses name a model identically, which is what keeps one spec
+ * runnable in either.
+ *
+ * @module runtimes/browser/model
+ */
+import { createOpenAI } from '@ai-sdk/openai';
+/** Where the inference service's OpenAI-compatible API lives under its host. */
+export const INFERENCE_API_PATH = '/api/ai-inference/v1';
+/**
+ * The model a spec asks for when it says nothing.
+ *
+ * Matches the specs written for this harness rather than being a general
+ * default, so a caller that forgets to pass one still gets a working agent
+ * instead of a 404 from a model nobody provisioned.
+ */
+export const DEFAULT_BROWSER_MODEL = 'bedrock:us.anthropic.claude-sonnet-4-6';
+/**
+ * Whether this agent would be refused for want of a sign-in.
+ *
+ * Worth asking before showing a chat: an agent that answers every message with
+ * a 401 is worse than one a host had the sense not to offer.
+ */
+export function browserModelRequiresSignIn(options) {
+    return !options.token?.trim();
+}
+/** The API root for an inference host, given either form of the URL. */
+export function inferenceApiUrl(inferenceUrl) {
+    const trimmed = inferenceUrl.replace(/\/+$/, '');
+    return trimmed.endsWith(INFERENCE_API_PATH)
+        ? trimmed
+        : `${trimmed}${INFERENCE_API_PATH}`;
+}
+/**
+ * A fetch that says which host it could not reach.
+ *
+ * A browser agent's most likely failure is that it is pointed at the wrong
+ * host — the inference service sits with the control plane, not on the
+ * runtimes plane, and a URL for the latter fails CORS preflight because it
+ * does not serve the route at all. What the SDK surfaces for that is
+ * `TypeError: Failed to fetch`, from a stack several libraries deep, naming
+ * nothing. This says what was being called.
+ */
+function describingFetch(base, apiUrl) {
+    return async (input, init) => {
+        try {
+            return await base(input, init);
+        }
+        catch (error) {
+            throw new Error(`Could not reach the inference service at ${apiUrl}. ` +
+                'Check that this is the right host — the service runs with the ' +
+                'control plane, not the runtimes plane — and that it allows this ' +
+                `origin. (${error instanceof Error ? error.message : String(error)})`, { cause: error });
+        }
+    };
+}
+/**
+ * A language model that answers from the inference service.
+ *
+ * `.chat()` rather than the provider's default: that is the
+ * `/chat/completions` endpoint, which is the one the inference service
+ * normalises tools and model names for.
+ */
+export function createBrowserModel(options) {
+    const apiUrl = inferenceApiUrl(options.inferenceUrl);
+    const provider = createOpenAI({
+        name: 'datalayer-ai-inference',
+        baseURL: apiUrl,
+        // Sent as `Authorization: Bearer <token>`, which is what the service's
+        // bearer scheme reads — so the completion is made as the signed-in person
+        // and attributed to them.
+        //
+        // The placeholder is for the signed-out case, where the provider would
+        // otherwise go looking for a key in an environment a browser does not
+        // have: the refusal then comes from the service, as a 401 a host can
+        // report, rather than from the SDK as a missing-configuration throw.
+        apiKey: options.token?.trim() || 'anonymous',
+        headers: options.headers,
+        fetch: describingFetch(options.fetch ?? globalThis.fetch, apiUrl),
+    });
+    return provider.chat(options.model || DEFAULT_BROWSER_MODEL);
+}

package/lib/runtimes/browser/protocol.d.ts

@@ -0,0 +1,54 @@
+/**
+ * How a chat is told to talk to an in-page agent.
+ *
+ * The shape belongs with the harness rather than with whoever renders a chat.
+ * It started in the examples, and then the LOOP workspace needed the identical
+ * thing — same fields, same reasons — which is the usual sign that a shape was
+ * living in the wrong place.
+ *
+ * @module runtimes/browser/protocol
+ */
+import type { ProtocolConfig } from '../../types/protocol';
+import type { AgentStreamSubagentPayload } from '../../types/stream';
+import type { FrontendToolDefinition } from '../../types/tools';
+import type { TeamContextSharing } from '../../types/teams';
+import type { BrowserModelOptions } from './model';
+import type { BrowserSubagent } from './subagents';
+export type BrowserProtocolOptions = {
+    /** The agent's id, for the chat to name it by. */
+    agentId: string;
+    /** The agent's instructions. */
+    instructions?: string;
+    /** The model id, as a spec spells it. */
+    model?: string;
+    /** The tools the agent may call in this page, if any. */
+    frontendTools?: FrontendToolDefinition[];
+    /** Where to reach a model. */
+    inference: Omit<BrowserModelOptions, 'model'>;
+    /**
+     * Agents this one may hand work to.
+     *
+     * Each becomes a tool named after it, so the model reaches for `Compactor`
+     * rather than `delegate_task('Compactor', …)`. What the child is told about
+     * the conversation is {@link sharing}.
+     */
+    subagents?: BrowserSubagent[];
+    /** What a subagent is told about the conversation so far. */
+    sharing?: TeamContextSharing;
+    /** Told what a delegated run does, as it does it — see `subagentTools`. */
+    onSubagentEvent?: (event: AgentStreamSubagentPayload) => void;
+};
+/**
+ * The protocol config for an agent whose loop runs in this page.
+ *
+ * Two fields carry the weight:
+ *
+ * - `endpoint` is empty and stays empty. There is nothing to address, and the
+ *   live objects travel in `options` — the seam `createProtocolAdapter` leaves
+ *   for an adapter whose configuration is not a URL.
+ * - `enableConfigQuery: false`, because models, tools and skills all come from
+ *   a runtime this agent does not have. Said explicitly rather than left
+ *   undefined: the composer waits on that query before it will accept a
+ *   keystroke, so an omitted flag reads as a chat that silently ignores typing.
+ */
+export declare function browserProtocolConfig(options: BrowserProtocolOptions): ProtocolConfig;

package/lib/runtimes/browser/protocol.js

@@ -0,0 +1,35 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The protocol config for an agent whose loop runs in this page.
+ *
+ * Two fields carry the weight:
+ *
+ * - `endpoint` is empty and stays empty. There is nothing to address, and the
+ *   live objects travel in `options` — the seam `createProtocolAdapter` leaves
+ *   for an adapter whose configuration is not a URL.
+ * - `enableConfigQuery: false`, because models, tools and skills all come from
+ *   a runtime this agent does not have. Said explicitly rather than left
+ *   undefined: the composer waits on that query before it will accept a
+ *   keystroke, so an omitted flag reads as a chat that silently ignores typing.
+ */
+export function browserProtocolConfig(options) {
+    const { agentId, instructions, model, frontendTools, inference, subagents, sharing, onSubagentEvent, } = options;
+    return {
+        type: 'browser-vercel-ai',
+        endpoint: '',
+        agentId,
+        enableConfigQuery: false,
+        options: {
+            instructions,
+            model,
+            frontendTools,
+            inference,
+            subagents,
+            sharing,
+            onSubagentEvent,
+        },
+    };
+}

package/lib/runtimes/browser/subagents.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Delegation, for an agent whose loop runs in the page.
+ *
+ * The server-side harness already has this: `subagents/capability.py`
+ * contributes a `delegate_task` tool to a pydantic-ai agent, runs the named
+ * subagent in a child run, and hands its final output back to the parent. This
+ * is the same idea in the browser, and deliberately built the way the Vercel AI
+ * SDK documents rather than reinvented:
+ *
+ * - a subagent is a {@link ToolLoopAgent}, the same class the parent is;
+ * - the parent reaches it through an ordinary `tool()` whose `execute` calls
+ *   `generate()` and returns the text;
+ * - what the parent's model sees is trimmed with `toModelOutput`.
+ *
+ * The one thing that is ours is *which conversation the child is given*. The
+ * SDK isolates by default and shows you how to pass `messages` instead; a
+ * teamspec says which of those a team wants, so the choice is read from the
+ * spec rather than decided here.
+ *
+ * One SDK constraint worth knowing: a subagent tool cannot take part in
+ * approval flows. A subagent that must be approved has to be a plain tool.
+ *
+ * @module runtimes/browser/subagents
+ */
+import { type ToolSet } from 'ai';
+import { type AgentStreamSubagentPayload } from '../../types/stream';
+import type { TeamContextSharing } from '../../types/teams';
+import { type BrowserModelOptions } from './model';
+/** How many turns a delegated task may take before it is stopped. */
+export declare const DEFAULT_SUBAGENT_MAX_STEPS = 12;
+/** One agent a parent may hand work to. */
+export type BrowserSubagent = {
+    /** The name the parent addresses it by. Becomes the tool name. */
+    name: string;
+    /** What it is for, and when to reach for it. Read by the parent's model. */
+    description: string;
+    /** Its instructions. */
+    instructions?: string;
+    /** Its model, as a spec spells it. Falls back to the parent's. */
+    model?: string;
+    /** Tools it may call in this page. Usually a narrower set than the parent's. */
+    tools?: ToolSet;
+    /**
+     * The octicon name its spec asked for.
+     *
+     * Carried, not used: the harness has no interface. It is here so a menu
+     * offering this subagent can draw it the same way it draws a team member,
+     * rather than the two disagreeing about what the same agent looks like.
+     */
+    icon?: string;
+};
+export type SubagentToolsOptions = {
+    subagents: BrowserSubagent[];
+    /** Where to reach a model. */
+    inference: Omit<BrowserModelOptions, 'model'>;
+    /** The parent's model, for a subagent that names none. */
+    model?: string;
+    /**
+     * What the child is told about the conversation so far.
+     *
+     * From the team's `context.sharing`. `shared` hands over the parent's
+     * messages and appends the task; anything else starts the child on the task
+     * alone — which is what the SDK does by default, and what a delegation model
+     * wants.
+     *
+     * `own-turns` collapses to isolated here on purpose: a subagent has no turns
+     * of its own to be given, so the honest reading of "only its own history" is
+     * "no history".
+     */
+    sharing?: TeamContextSharing;
+    /** Turn ceiling for one delegated task. */
+    maxSteps?: number;
+    /**
+     * Told what a delegated run does, as it does it.
+     *
+     * The same events the server-side harness puts on its monitoring stream —
+     * `start`, `text`, `tool_call`, `tool_result`, `end`, `error`, keyed by the
+     * parent's tool call — so whatever draws a delegation's progress (the
+     * side panel, the pulse in the composer) draws it the same whether the
+     * loop turns on a server or in this page.
+     */
+    onEvent?: (event: AgentStreamSubagentPayload) => void;
+    /**
+     * The page's tools, for a member that declares none of its own.
+     *
+     * A team's members all work in the page the person has open — the Reviewer
+     * re-runs the cells, Decks writes the deck — and a member reached by
+     * delegation is still that member. Without this a delegated task ran with
+     * no tools at all, and "ask the Reviewer to check this" came back as an
+     * opinion about cells it could not run. A subagent that names a narrower
+     * set of its own keeps it.
+     */
+    tools?: ToolSet;
+    /**
+     * The run's abort signal, read when a delegation starts.
+     *
+     * The SDK hands a tool the run's signal too, and the child listens to
+     * both: a person pressing stop must stop the child as surely as the
+     * parent, and a signal reached one way is as good as the other.
+     */
+    signal?: () => AbortSignal | undefined;
+};
+/**
+ * The tools a parent needs in order to delegate.
+ *
+ * One per subagent, named after it, so the model reaches for `Compactor`
+ * rather than for `delegate_task('Compactor', …)`. A name the model can read
+ * is a name it picks correctly more often, and the description is what it
+ * chooses on.
+ */
+export declare function subagentTools(options: SubagentToolsOptions): ToolSet;
+/** What a delegation says when the person stopped it. */
+export declare const STOPPED = "Stopped.";
+/** The parts of a streamed run this relays; the SDK's stream has more, which pass. */
+export type SubagentStreamPart = {
+    type: string;
+    text?: string;
+    toolName?: string;
+    input?: unknown;
+    output?: unknown;
+    error?: unknown;
+};
+/**
+ * Turn a delegated run's stream into subagent events, and return its text.
+ *
+ * Text and reasoning deltas, tool calls and their results, and errors — the
+ * phases the server-side harness reports — each emitted as the part arrives.
+ * Everything else the SDK streams (step and finish markers, sources, files)
+ * is not a phase and passes in silence.
+ */
+export declare function relaySubagentRun(stream: AsyncIterable<SubagentStreamPart>, emit: (event: Omit<AgentStreamSubagentPayload, 'subagentName' | 'toolCallId'>) => void, signal?: AbortSignal): Promise<string>;

package/lib/runtimes/browser/subagents.js

@@ -0,0 +1,241 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/*
+ * Copyright (c) 2023-2026 Datalayer, Inc.
+ *
+ * MIT License
+ */
+/**
+ * Delegation, for an agent whose loop runs in the page.
+ *
+ * The server-side harness already has this: `subagents/capability.py`
+ * contributes a `delegate_task` tool to a pydantic-ai agent, runs the named
+ * subagent in a child run, and hands its final output back to the parent. This
+ * is the same idea in the browser, and deliberately built the way the Vercel AI
+ * SDK documents rather than reinvented:
+ *
+ * - a subagent is a {@link ToolLoopAgent}, the same class the parent is;
+ * - the parent reaches it through an ordinary `tool()` whose `execute` calls
+ *   `generate()` and returns the text;
+ * - what the parent's model sees is trimmed with `toModelOutput`.
+ *
+ * The one thing that is ours is *which conversation the child is given*. The
+ * SDK isolates by default and shows you how to pass `messages` instead; a
+ * teamspec says which of those a team wants, so the choice is read from the
+ * spec rather than decided here.
+ *
+ * One SDK constraint worth knowing: a subagent tool cannot take part in
+ * approval flows. A subagent that must be approved has to be a plain tool.
+ *
+ * @module runtimes/browser/subagents
+ */
+import { ToolLoopAgent, stepCountIs, tool, jsonSchema, } from 'ai';
+import { SUBAGENT_STOPPED, } from '../../types/stream';
+import { createBrowserModel } from './model';
+/** How many turns a delegated task may take before it is stopped. */
+export const DEFAULT_SUBAGENT_MAX_STEPS = 12;
+/** The input every delegation tool takes. */
+const TASK_SCHEMA = {
+    type: 'object',
+    properties: {
+        task: {
+            type: 'string',
+            description: 'What to do, stated so that it can be carried out without the rest of this conversation.',
+        },
+    },
+    required: ['task'],
+};
+/**
+ * The tools a parent needs in order to delegate.
+ *
+ * One per subagent, named after it, so the model reaches for `Compactor`
+ * rather than for `delegate_task('Compactor', …)`. A name the model can read
+ * is a name it picks correctly more often, and the description is what it
+ * chooses on.
+ */
+export function subagentTools(options) {
+    const { subagents, inference, model, sharing = 'shared', maxSteps = DEFAULT_SUBAGENT_MAX_STEPS, tools: shared, onEvent, signal: runSignal, } = options;
+    const tools = {};
+    for (const subagent of subagents) {
+        tools[subagent.name] = tool({
+            description: subagent.description,
+            inputSchema: jsonSchema(TASK_SCHEMA),
+            execute: async (input, executionOptions) => {
+                const { task } = (input ?? {});
+                if (!task?.trim()) {
+                    return { error: 'A delegated task needs to say what to do.' };
+                }
+                // Keyed by the parent's tool call, as the server keys its events:
+                // one delegation, one timeline, whichever side ran it. A run ends
+                // once: a stream that reports an error and then rejects would
+                // otherwise say so twice.
+                const toolCallId = executionOptions?.toolCallId ?? null;
+                let ended = false;
+                const emit = (event) => {
+                    if (event.phase === 'end' || event.phase === 'error') {
+                        if (ended) {
+                            return;
+                        }
+                        ended = true;
+                    }
+                    onEvent?.({ subagentName: subagent.name, toolCallId, ...event });
+                };
+                const child = new ToolLoopAgent({
+                    id: subagent.name,
+                    model: createBrowserModel({
+                        ...inference,
+                        model: subagent.model ?? model,
+                    }),
+                    instructions: subagent.instructions,
+                    tools: subagent.tools ?? shared ?? {},
+                    stopWhen: stepCountIs(maxSteps),
+                });
+                // Stopped when either the run or this tool call is: the two signals
+                // are one to the child.
+                const signal = anySignal([
+                    executionOptions?.abortSignal,
+                    runSignal?.(),
+                ]);
+                emit({ phase: 'start', task });
+                try {
+                    // `messages` for a shared conversation, `prompt` for an isolated
+                    // one — the same two shapes the SDK documents, chosen by the team.
+                    const history = sharing === 'shared'
+                        ? (executionOptions?.messages ?? [])
+                        : [];
+                    // Streamed rather than generated, so the run can be watched: each
+                    // part becomes an event as it arrives, and the text is what the
+                    // parent is handed at the end.
+                    const result = await child.stream({
+                        messages: [...history, { role: 'user', content: task }],
+                        abortSignal: signal,
+                    });
+                    const streamed = await relaySubagentRun(result.fullStream, emit, signal);
+                    if (signal?.aborted) {
+                        emit({ phase: 'error', error: STOPPED });
+                        return { agent: subagent.name, error: STOPPED };
+                    }
+                    const output = streamed || (await result.text);
+                    emit({ phase: 'end', output });
+                    return { agent: subagent.name, result: output };
+                }
+                catch (reason) {
+                    // Returned rather than thrown: a failed delegation is a step the
+                    // parent can recover from — try another member, or tell the person
+                    // — and a throw would abort the whole run instead.
+                    // A stop is said as a stop, not as whatever the aborted fetch threw.
+                    const error = signal?.aborted
+                        ? STOPPED
+                        : reason instanceof Error
+                            ? reason.message
+                            : String(reason);
+                    emit({ phase: 'error', error });
+                    return { agent: subagent.name, error };
+                }
+            },
+            // What the parent's model reads. The person can see the whole delegated
+            // run in the transcript; the parent only needs its conclusion, and
+            // paying for the rest in context is how a delegation model runs out of
+            // room three hand-offs in.
+            toModelOutput: ({ output }) => {
+                const value = output;
+                return {
+                    type: 'text',
+                    value: value?.error
+                        ? `${subagent.name} could not finish: ${value.error}`
+                        : (value?.result ?? 'Done.'),
+                };
+            },
+        });
+    }
+    return tools;
+}
+/** What a delegation says when the person stopped it. */
+export const STOPPED = SUBAGENT_STOPPED;
+/** One signal for several, or the one there is. */
+function anySignal(signals) {
+    const present = signals.filter((entry) => Boolean(entry));
+    if (present.length <= 1) {
+        return present[0];
+    }
+    if (typeof AbortSignal.any === 'function') {
+        return AbortSignal.any(present);
+    }
+    // Older runtimes: a controller that follows whichever fires first.
+    const controller = new AbortController();
+    for (const entry of present) {
+        if (entry.aborted) {
+            controller.abort(entry.reason);
+            break;
+        }
+        entry.addEventListener('abort', () => controller.abort(entry.reason), {
+            once: true,
+        });
+    }
+    return controller.signal;
+}
+/** A tool's result as a line the timeline can show. */
+function preview(value) {
+    const text = typeof value === 'string' ? value : JSON.stringify(value);
+    return text.length > 400 ? `${text.slice(0, 400)}…` : text;
+}
+/**
+ * Turn a delegated run's stream into subagent events, and return its text.
+ *
+ * Text and reasoning deltas, tool calls and their results, and errors — the
+ * phases the server-side harness reports — each emitted as the part arrives.
+ * Everything else the SDK streams (step and finish markers, sources, files)
+ * is not a phase and passes in silence.
+ */
+export async function relaySubagentRun(stream, emit, signal) {
+    let text = '';
+    for await (const part of stream) {
+        // Stopped: whatever is still in the pipe is not worth relaying.
+        if (signal?.aborted) {
+            break;
+        }
+        switch (part.type) {
+            case 'text-delta':
+                text += part.text ?? '';
+                emit({ phase: 'text', text: part.text ?? '' });
+                break;
+            case 'reasoning-delta':
+                emit({ phase: 'thinking', text: part.text ?? '' });
+                break;
+            case 'tool-call':
+                emit({
+                    phase: 'tool_call',
+                    toolName: part.toolName,
+                    toolArgs: (part.input ?? {}),
+                });
+                break;
+            case 'tool-result':
+                emit({
+                    phase: 'tool_result',
+                    toolName: part.toolName,
+                    result: preview(part.output),
+                });
+                break;
+            case 'tool-error':
+                emit({
+                    phase: 'tool_result',
+                    toolName: part.toolName,
+                    result: preview(part.error),
+                });
+                break;
+            case 'error':
+                emit({
+                    phase: 'error',
+                    error: part.error instanceof Error
+                        ? part.error.message
+                        : String(part.error),
+                });
+                break;
+            default:
+                break;
+        }
+    }
+    return text;
+}

package/lib/runtimes/index.d.ts

@@ -1,5 +1,8 @@
 export * from './actions';
+export * from './lifecycle';
 export * from './apis';
 export * from './settings';
 export * from './snapshots';
 export * from './utils';
+export * from './variants';
+export * from './browser';

package/lib/runtimes/index.js

@@ -3,7 +3,10 @@
  * Distributed under the terms of the Modified BSD License.
  */
 export * from './actions';
+export * from './lifecycle';
 export * from './apis';
 export * from './settings';
 export * from './snapshots';
 export * from './utils';
+export * from './variants';
+export * from './browser';

package/lib/runtimes/lifecycle.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The converged sandbox lifecycle, in TypeScript.
+ *
+ * The Python side states this vocabulary in `code_sandboxes.lifecycle` and the
+ * Runtimes client is written to it. This is the same statement for callers that
+ * reach the API from a browser: one place that knows how a runtime URL is
+ * spelled, so a hook, a mixin and a page cannot drift from each other the way
+ * they did when each built its own string.
+ *
+ * Transport stays with the caller — `requestDatalayerAPI`, `requestDatalayer`
+ * and a bare `fetch` all have their reasons. Only the URLs and the verbs are
+ * shared, because those are what has to agree.
+ */
+/**
+ * A verb a caller may use, and the REST spelling it corresponds to.
+ *
+ * Mirrors `LIFECYCLE_OPERATIONS` in `code_sandboxes.lifecycle` — if one of them
+ * changes, so does the other, and the tests on both sides say so.
+ */
+export declare const LIFECYCLE_OPERATIONS: {
+    readonly create: "POST /runtimes";
+    readonly start: "POST /runtimes (implied) — begin a created sandbox";
+    readonly stop: "DELETE /runtimes/{runtime_name}";
+    readonly pause: "POST /runtimes/{runtime_name}/pause";
+    readonly resume: "POST /runtimes/{runtime_name}/resume";
+    readonly list: "GET /runtimes";
+    readonly get: "GET /runtimes/{runtime_name}";
+    readonly update: "PUT /runtimes/{runtime_name}";
+    readonly snapshot: "POST /sandbox-snapshots";
+    readonly execute: "run code in the sandbox";
+};
+/**
+ * The name of a lifecycle verb.
+ */
+export type LifecycleOperation = keyof typeof LIFECYCLE_OPERATIONS;
+/**
+ * The Runtimes API prefix, below whichever host serves it.
+ */
+export declare const RUNTIMES_API_PREFIX = "api/runtimes/v1";
+/**
+ * Every runtime — the collection.
+ *
+ * `create` posts here and `list` gets here.
+ */
+export declare function runtimesUrl(baseUrl: string): string;
+/**
+ * One runtime, by pod name.
+ *
+ * `get` reads it, `update` puts to it, and `stop` deletes it — whether the
+ * runtime is running or paused, which is why there is no second path for the
+ * paused case.
+ */
+export declare function runtimeUrl(baseUrl: string, runtimeName: string): string;
+/**
+ * Suspend one runtime, keeping its state.
+ */
+export declare function runtimePauseUrl(baseUrl: string, runtimeName: string): string;
+/**
+ * Bring one paused runtime back.
+ */
+export declare function runtimeResumeUrl(baseUrl: string, runtimeName: string): string;
+/**
+ * The snapshots collection.
+ *
+ * A snapshot outlives the runtime it came from, which is why it is its own
+ * resource rather than a sub-path of the pod.
+ */
+export declare function sandboxSnapshotsUrl(baseUrl: string): string;
+/**
+ * One snapshot, by UID.
+ */
+export declare function sandboxSnapshotUrl(baseUrl: string, id: string): string;
+/**
+ * The checkpoint records behind pause and resume.
+ */
+export declare function runtimeCheckpointsUrl(baseUrl: string): string;