withruntime 0.7.2 → 0.8.1

package/dist/blaxel/interpreter.d.ts

@@ -0,0 +1,74 @@
+import { SandboxInstance } from "./sandbox.js";
+import type { Port, Sandbox as SandboxModel, SandboxCreateConfiguration, SandboxLifecycle } from "./types.js";
+declare class OutputMessage {
+    text: string;
+    timestamp: number | null;
+    isStderr: boolean;
+    constructor(text: string, timestamp: number | null, isStderr: boolean);
+}
+declare class Result {
+    [key: string]: unknown;
+    constructor(kwargs?: Record<string, unknown>);
+}
+declare class ExecutionError {
+    name: string;
+    value: unknown;
+    traceback: unknown;
+    constructor(name: string, value: unknown, traceback: unknown);
+}
+declare class Logs {
+    stdout: string[];
+    stderr: string[];
+}
+declare class Execution {
+    results: Result[];
+    logs: Logs;
+    error: ExecutionError | null;
+    executionCount: number | null;
+}
+declare class Context {
+    id: string;
+    constructor(id: string);
+    static fromJson(data: Record<string, unknown>): Context;
+}
+/** A sandbox that runs code, as Blaxel's CodeInterpreter. */
+export declare class CodeInterpreter extends SandboxInstance {
+    #private;
+    static readonly DEFAULT_IMAGE = "blaxel/jupyter-server";
+    static readonly DEFAULT_PORTS: Port[];
+    static readonly DEFAULT_LIFECYCLE: SandboxLifecycle;
+    static readonly OutputMessage: typeof OutputMessage;
+    static readonly Result: typeof Result;
+    static readonly ExecutionError: typeof ExecutionError;
+    static readonly Logs: typeof Logs;
+    static readonly Execution: typeof Execution;
+    static readonly Context: typeof Context;
+    /** Blaxel's defaults for a code interpreter: its image, port 8888, and
+     * deletion after 30 idle minutes (a paused sandbox kept one day). */
+    static create<T extends typeof SandboxInstance>(this: T, sandbox?: SandboxCreateConfiguration | SandboxModel | Record<string, unknown> | null, options?: {
+        safe?: boolean;
+        createIfNotExist?: boolean;
+    }): Promise<InstanceType<T>>;
+    get _jupyterUrl(): string;
+    /** Runs code in a stateful context. Errors in the code come back in
+     * `execution.error`; a run past `timeout` seconds (default 60, 0 for none)
+     * throws "Request timeout", as in Blaxel. */
+    runCode(code: string, options?: {
+        language?: string | null;
+        context?: Context | null;
+        onStdout?: (msg: OutputMessage) => void;
+        onStderr?: (msg: OutputMessage) => void;
+        onResult?: (result: Result) => void;
+        onError?: (error: ExecutionError) => void;
+        envs?: Record<string, string> | null;
+        timeout?: number | null;
+        requestTimeout?: number | null;
+    }): Promise<Execution>;
+    /** A new context: its own variables, directory and the sandbox's envs. */
+    createCodeContext(options?: {
+        cwd?: string | null;
+        language?: string | null;
+        requestTimeout?: number | null;
+    }): Promise<Context>;
+}
+export {};

package/dist/blaxel/interpreter.js

@@ -0,0 +1,256 @@
+import { ENV_FILE, parseEnvFile } from "./context.js";
+import { guard, isNotFound, NotSupportedError, ResponseError } from "./errors.js";
+import { SandboxInstance } from "./sandbox.js";
+const LANGUAGES = new Set([
+    "python",
+    "javascript",
+    "typescript",
+    "r",
+    "java",
+    "bash",
+    "go",
+]);
+const TEXT_MIME = /^text\/|json|javascript|svg|latex/;
+/** A MIME bundle's keys, as Blaxel's Jupyter server names them. */
+const FIELDS = {
+    "text/plain": "text",
+    "text/html": "html",
+    "text/markdown": "markdown",
+    "image/svg+xml": "svg",
+    "image/png": "png",
+    "image/jpeg": "jpeg",
+    "application/pdf": "pdf",
+    "text/latex": "latex",
+    "application/json": "json",
+    "application/javascript": "javascript",
+};
+function languageOf(requested) {
+    const language = requested ?? "python";
+    if (language === "js")
+        return "javascript";
+    if (language === "ts")
+        return "typescript";
+    if (!LANGUAGES.has(language))
+        throw new NotSupportedError(`Running ${language} code in the interpreter`, "Runtime's interpreter runs Python, JavaScript, TypeScript, R, Java, Bash and Go; run anything else with sandbox.process.exec.");
+    return language;
+}
+class OutputMessage {
+    text;
+    timestamp;
+    isStderr;
+    constructor(text, timestamp, isStderr) {
+        this.text = text;
+        this.timestamp = timestamp;
+        this.isStderr = isStderr;
+    }
+}
+class Result {
+    constructor(kwargs = {}) {
+        for (const [key, value] of Object.entries(kwargs))
+            this[key] = value;
+    }
+}
+class ExecutionError {
+    name;
+    value;
+    traceback;
+    constructor(name, value, traceback) {
+        this.name = name;
+        this.value = value;
+        this.traceback = traceback;
+    }
+}
+class Logs {
+    stdout = [];
+    stderr = [];
+}
+class Execution {
+    results = [];
+    logs = new Logs();
+    error = null;
+    executionCount = null;
+}
+class Context {
+    id;
+    constructor(id) {
+        this.id = id;
+    }
+    static fromJson(data) {
+        const id = data.id ?? data.context_id;
+        return new Context(typeof id === "string" || typeof id === "number" ? String(id) : "");
+    }
+}
+/** Output as the Jupyter server reports it: one entry per line. */
+function lines(text) {
+    return text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+}
+/** A sandbox that runs code, as Blaxel's CodeInterpreter. */
+export class CodeInterpreter extends SandboxInstance {
+    static DEFAULT_IMAGE = "blaxel/jupyter-server";
+    static DEFAULT_PORTS = [{ name: "jupyter", target: 8888, protocol: "HTTP" }];
+    static DEFAULT_LIFECYCLE = {
+        expirationPolicies: [{ type: "ttl-idle", value: "30m", action: "delete" }],
+    };
+    static OutputMessage = OutputMessage;
+    static Result = Result;
+    static ExecutionError = ExecutionError;
+    static Logs = Logs;
+    static Execution = Execution;
+    static Context = Context;
+    /** Contexts made to carry the sandbox's envs, one per language. */
+    #envContexts = new Map();
+    #envs;
+    /** Blaxel's defaults for a code interpreter: its image, port 8888, and
+     * deletion after 30 idle minutes (a paused sandbox kept one day). */
+    static async create(sandbox, options = {}) {
+        const defaults = {
+            image: CodeInterpreter.DEFAULT_IMAGE,
+            ports: CodeInterpreter.DEFAULT_PORTS,
+            lifecycle: CodeInterpreter.DEFAULT_LIFECYCLE,
+        };
+        let merged = defaults;
+        if (sandbox && typeof sandbox === "object") {
+            if ("metadata" in sandbox || "spec" in sandbox) {
+                const model = sandbox;
+                merged = {
+                    ...model,
+                    spec: {
+                        ...model.spec,
+                        runtime: { image: defaults.image, ports: defaults.ports, ...model.spec?.runtime },
+                        lifecycle: model.spec?.lifecycle ?? defaults.lifecycle,
+                    },
+                };
+            }
+            else
+                merged = { ...defaults, ...sandbox };
+        }
+        return super.create.call(this, merged, options);
+    }
+    get _jupyterUrl() {
+        throw new NotSupportedError("The Jupyter server's address (_jupyterUrl)", "No Jupyter server runs: use runCode, or sandbox.withruntime.interpreter.");
+    }
+    get #interpreter() {
+        return this.withruntime.interpreter;
+    }
+    /** The sandbox's envs: those this object set, else the env file's. */
+    #sandboxEnvs() {
+        const known = this.spec.runtime?.envs;
+        if (known)
+            return Promise.resolve(Object.fromEntries(known.map((e) => [e.name, e.value ?? ""])));
+        this.#envs ??= this.fs.read(ENV_FILE).then(parseEnvFile, (error) => {
+            if (isNotFound(error))
+                return {};
+            throw error;
+        });
+        return this.#envs;
+    }
+    /** The context a run goes to: the one asked for; else, when the sandbox has
+     * envs, a context made once with them; else Runtime's default one. */
+    async #contextFor(language) {
+        let id = this.#envContexts.get(language);
+        if (!id) {
+            id = (async () => {
+                const envs = await this.#sandboxEnvs();
+                if (!Object.keys(envs).length)
+                    return undefined;
+                const wanted = `blaxel-${language}`;
+                try {
+                    return (await guard(() => this.#interpreter.contexts.create({ id: wanted, language, env: envs }))).id;
+                }
+                catch (error) {
+                    // Made already, by another object for this sandbox.
+                    if (!(error instanceof ResponseError && error.status === 409))
+                        throw error;
+                    return wanted;
+                }
+            })();
+            this.#envContexts.set(language, id);
+            id.catch(() => this.#envContexts.delete(language));
+        }
+        return id;
+    }
+    async #inline(result) {
+        const data = { ...result.data };
+        for (const [mime, ref] of Object.entries(result.refs ?? {})) {
+            if (data[mime] !== undefined)
+                continue;
+            const bytes = await guard(() => this.#interpreter.result(ref));
+            data[mime] = TEXT_MIME.test(mime)
+                ? new TextDecoder().decode(bytes)
+                : Buffer.from(bytes).toString("base64");
+        }
+        const fields = {};
+        const extra = {};
+        for (const [mime, value] of Object.entries(data)) {
+            const field = FIELDS[mime];
+            if (field)
+                fields[field] = value;
+            else if (mime === "application/vnd.runtime.table+json")
+                fields.data = value;
+            else
+                extra[mime] = value;
+        }
+        return new Result({
+            ...fields,
+            ...(Object.keys(extra).length ? { extra } : {}),
+            is_main_result: result.main,
+        });
+    }
+    /** Runs code in a stateful context. Errors in the code come back in
+     * `execution.error`; a run past `timeout` seconds (default 60, 0 for none)
+     * throws "Request timeout", as in Blaxel. */
+    async runCode(code, options = {}) {
+        if (options.language && options.context)
+            throw new Error("You can provide context or language, but not both at the same time.");
+        if (options.envs && Object.keys(options.envs).length)
+            throw new NotSupportedError("Environment variables for one run (runCode envs)", "Set them in the sandbox's envs at create (every context gets them), or in the code (os.environ).");
+        const language = languageOf(options.language);
+        const context = options.context?.id ?? (await this.#contextFor(language));
+        const timeout = options.timeout === 0 ? null : (options.timeout ?? 60);
+        const now = () => Date.now() / 1000;
+        const streaming = options.onStdout || options.onStderr || options.onError;
+        const execution = await guard(() => this.#interpreter.run(code, {
+            ...(context ? { context } : { language }),
+            ...(timeout === null
+                ? { timeoutMs: 86_400_000 }
+                : { timeoutMs: Math.ceil(timeout * 1000) }),
+            ...(streaming
+                ? {
+                    onStdout: (text) => options.onStdout?.(new OutputMessage(text, now(), false)),
+                    onStderr: (text) => options.onStderr?.(new OutputMessage(text, now(), true)),
+                    onError: (error) => options.onError?.(new ExecutionError(error.name, error.value, error.traceback)),
+                }
+                : {}),
+        }));
+        if (execution.status === "timeout")
+            throw new Error("Request timeout");
+        if (execution.status === "lost")
+            throw new Error("The interpreter lost this run (its context stopped); run it again.");
+        const out = new Execution();
+        out.results = await Promise.all(execution.results.map((result) => this.#inline(result)));
+        if (options.onResult)
+            for (const result of out.results)
+                options.onResult(result);
+        out.logs.stdout = lines(execution.stdout);
+        out.logs.stderr = lines(execution.stderr);
+        if (execution.error) {
+            out.error = new ExecutionError(execution.error.name, execution.error.value, execution.error.traceback);
+            if (!streaming)
+                options.onError?.(out.error);
+        }
+        out.executionCount = execution.executionCount;
+        return out;
+    }
+    /** A new context: its own variables, directory and the sandbox's envs. */
+    async createCodeContext(options = {}) {
+        const language = languageOf(options.language);
+        const envs = await this.#sandboxEnvs();
+        const cwd = options.cwd ? options.cwd.replace(/^\/blaxel(?=\/|$)/, "/workspace") : undefined;
+        const made = await guard(() => this.#interpreter.contexts.create({
+            language,
+            ...(cwd ? { cwd } : {}),
+            ...(Object.keys(envs).length ? { env: envs } : {}),
+        }));
+        return new Context(made.id);
+    }
+}

package/dist/blaxel/lookup.d.ts

@@ -0,0 +1,37 @@
+import type { Runtime } from "../client.js";
+import type { RuntimeSandbox } from "./client.js";
+/** Labels the adapter keeps on a sandbox, under this prefix; the Python
+ * adapter uses the same keys, so either reads what the other wrote: image,
+ * memory, ports ("3000,8080"), region, ttl, expires (ISO), lifecycle (JSON),
+ * externalId, displayName, archived ("1"), preview.<name> (its port) and
+ * idlePauseSeconds (the idle pause to give back after keepAlive processes). */
+export declare const LABEL = "blaxel/";
+export declare const EXTERNAL_ID = "blaxel/externalId";
+export declare const DISPLAY_NAME = "blaxel/displayName";
+export declare const ARCHIVED = "blaxel/archived";
+export declare const IDLE_PAUSE = "blaxel/idlePauseSeconds";
+/** A named preview: `blaxel/preview.<name>` holds its port. */
+export declare const PREVIEW = "blaxel/preview.";
+/** The caller's labels, without the adapter's. */
+export declare function userLabels(labels?: Record<string, string>): Record<string, string>;
+/** The adapter's labels, without the caller's. */
+export declare function ownLabels(labels?: Record<string, string>): Record<string, string>;
+/** How a Blaxel sandbox behaves on Runtime: it pauses (Blaxel's standby)
+ * after the shortest idle time Runtime allows, wakes by itself on the next
+ * call, and pauses rather than ends when its lease runs out. */
+export declare const STANDBY: {
+    idlePauseSeconds: number;
+    autoWake: true;
+};
+/** Runtime's longest lease. The adapter renews it while the sandbox is used. */
+export declare const LEASE_SECONDS = 3600;
+/** The live sandbox with this name (or Runtime id): one call. A 404 when
+ * there is none, as Blaxel answers. */
+export declare function findSandbox(client: Runtime, name: string): Promise<RuntimeSandbox>;
+/** The newest live sandbox carrying `externalId`. */
+export declare function findByExternalId(client: Runtime, externalId: string): Promise<RuntimeSandbox>;
+/** Runs a create or fork that names a sandbox. When the name is still held
+ * by a sandbox that is stopping (deleted a moment ago, by this client or
+ * another), waits for it to stop, up to 30 seconds, and runs it once more, as
+ * Blaxel's createIfNotExists waits out a sandbox being deleted. */
+export declare function whenNameFree<T>(client: Runtime, work: () => Promise<T>): Promise<T>;

package/dist/blaxel/lookup.js

@@ -0,0 +1,82 @@
+import { RuntimeError } from "../errors.js";
+/* Finding a Blaxel sandbox on Runtime, and the labels that carry what Runtime
+   has no field for. The labels are the adapter's own: `metadata.labels`
+   shows only the caller's. */
+/** Labels the adapter keeps on a sandbox, under this prefix; the Python
+ * adapter uses the same keys, so either reads what the other wrote: image,
+ * memory, ports ("3000,8080"), region, ttl, expires (ISO), lifecycle (JSON),
+ * externalId, displayName, archived ("1"), preview.<name> (its port) and
+ * idlePauseSeconds (the idle pause to give back after keepAlive processes). */
+export const LABEL = "blaxel/";
+export const EXTERNAL_ID = `${LABEL}externalId`;
+export const DISPLAY_NAME = `${LABEL}displayName`;
+export const ARCHIVED = `${LABEL}archived`;
+export const IDLE_PAUSE = `${LABEL}idlePauseSeconds`;
+/** A named preview: `blaxel/preview.<name>` holds its port. */
+export const PREVIEW = `${LABEL}preview.`;
+const OWN = /^blaxel\//;
+/** The caller's labels, without the adapter's. */
+export function userLabels(labels = {}) {
+    return Object.fromEntries(Object.entries(labels).filter(([key]) => !OWN.test(key)));
+}
+/** The adapter's labels, without the caller's. */
+export function ownLabels(labels = {}) {
+    return Object.fromEntries(Object.entries(labels).filter(([key]) => OWN.test(key)));
+}
+/** How a Blaxel sandbox behaves on Runtime: it pauses (Blaxel's standby)
+ * after the shortest idle time Runtime allows, wakes by itself on the next
+ * call, and pauses rather than ends when its lease runs out. */
+export const STANDBY = {
+    idlePauseSeconds: 60,
+    autoWake: true,
+};
+/** Runtime's longest lease. The adapter renews it while the sandbox is used. */
+export const LEASE_SECONDS = 3600;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** The live sandbox with this name (or Runtime id): one call. A 404 when
+ * there is none, as Blaxel answers. */
+export async function findSandbox(client, name) {
+    if (UUID.test(name))
+        return client.sandboxes.get(name);
+    const page = await client.sandboxes.list({ name });
+    const found = page.data.filter((one) => one.state !== "stopped").at(-1);
+    if (!found)
+        throw notFound(`Sandbox ${name} was not found.`);
+    return found;
+}
+/** The newest live sandbox carrying `externalId`. */
+export async function findByExternalId(client, externalId) {
+    const page = await client.sandboxes.list({ labels: { [EXTERNAL_ID]: externalId } });
+    const found = page.data.filter((one) => one.state !== "stopped").at(-1);
+    if (!found)
+        throw notFound(`No sandbox has the external id ${externalId}.`);
+    return found;
+}
+/** Runs a create or fork that names a sandbox. When the name is still held
+ * by a sandbox that is stopping (deleted a moment ago, by this client or
+ * another), waits for it to stop, up to 30 seconds, and runs it once more, as
+ * Blaxel's createIfNotExists waits out a sandbox being deleted. */
+export async function whenNameFree(client, work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        const holder = error instanceof RuntimeError ? error.details?.sandboxId : undefined;
+        if (!(error instanceof RuntimeError) ||
+            error.code !== "name_taken" ||
+            error.details?.state !== "stopping" ||
+            typeof holder !== "string")
+            throw error;
+        const stopping = await client.sandboxes.get(holder);
+        await stopping.waitFor("stopped", { timeoutSeconds: 30 });
+        return work();
+    }
+}
+function notFound(message) {
+    return new RuntimeError({
+        message,
+        code: "not_found",
+        status: 404,
+        hint: "SandboxInstance.createIfNotExists({ name }) makes it when it is missing.",
+    });
+}

package/dist/blaxel/pagination.d.ts

@@ -0,0 +1,39 @@
+import type { Page } from "../page.js";
+export type PaginatedListMeta = {
+    hasMore?: boolean;
+    nextCursor?: string;
+    total?: number;
+    totalIsPartial?: boolean;
+};
+export type CursorPaginationQuery = {
+    cursor?: string;
+};
+export type AutoPagingEachCallback<T> = (item: T) => boolean | void | Promise<boolean | void>;
+export type AutoPagingToArrayOptions = {
+    limit: number;
+};
+export type ListResponse<T> = T[] | {
+    data?: T[] | null;
+    meta?: PaginatedListMeta | null;
+} | null | undefined;
+export type PaginatedList<T, TQuery extends CursorPaginationQuery = CursorPaginationQuery> = AsyncIterable<T> & {
+    data: T[];
+    meta: PaginatedListMeta;
+    hasMore: boolean;
+    nextCursor?: string;
+    nextPage(): Promise<PaginatedList<T, TQuery> | null>;
+    autoPagingEach(onItem: AutoPagingEachCallback<T>): Promise<void>;
+    autoPagingToArray(options: AutoPagingToArrayOptions): Promise<T[]>;
+};
+/** Blaxel's own helper: the items of a list answer in any of its shapes. */
+export declare function unwrapListData<T>(response: ListResponse<T>): T[];
+/** Blaxel's own helper, for a list fetched by `fetchPage`. */
+export declare function createPaginatedList<TRaw, TItem, TQuery extends CursorPaginationQuery>({ response, fetchPage, mapItem, query, }: {
+    response: ListResponse<TRaw>;
+    fetchPage: (query?: TQuery) => Promise<ListResponse<TRaw>>;
+    mapItem: (item: TRaw) => TItem | Promise<TItem>;
+    query?: TQuery;
+    seenCursors?: Set<string>;
+}): Promise<PaginatedList<TItem, TQuery>>;
+/** A Runtime page, each item mapped, as Blaxel's paginated list. */
+export declare function paginate<TRaw, TItem>(page: Page<TRaw>, map: (item: TRaw) => TItem): PaginatedList<TItem>;

package/dist/blaxel/pagination.js

@@ -0,0 +1,60 @@
+import { guard } from "./errors.js";
+/** Blaxel's own helper: the items of a list answer in any of its shapes. */
+export function unwrapListData(response) {
+    if (!response)
+        return [];
+    if (Array.isArray(response))
+        return response;
+    return response.data ?? [];
+}
+/** Blaxel's own helper, for a list fetched by `fetchPage`. */
+export async function createPaginatedList({ response, fetchPage, mapItem, query, }) {
+    const meta = !response || Array.isArray(response) ? {} : (response.meta ?? {});
+    const data = await Promise.all(unwrapListData(response).map(mapItem));
+    return build(data, meta.nextCursor || undefined, async (cursor) => createPaginatedList({
+        response: await fetchPage({ ...(query ?? {}), cursor }),
+        fetchPage,
+        mapItem,
+        ...(query ? { query: { ...query, cursor } } : {}),
+    }));
+}
+/** A Runtime page, each item mapped, as Blaxel's paginated list. */
+export function paginate(page, map) {
+    return build(page.data.map(map), page.nextCursor ?? undefined, async () => {
+        const next = await guard(() => page.next());
+        return next ? paginate(next, map) : null;
+    });
+}
+function build(data, nextCursor, more) {
+    const list = {
+        data,
+        meta: { hasMore: nextCursor !== undefined, ...(nextCursor ? { nextCursor } : {}) },
+        hasMore: nextCursor !== undefined,
+        ...(nextCursor ? { nextCursor } : {}),
+        nextPage: async () => (nextCursor ? more(nextCursor) : null),
+        async autoPagingEach(onItem) {
+            for await (const item of list)
+                if ((await onItem(item)) === false)
+                    return;
+        },
+        async autoPagingToArray(options) {
+            if (!options || !Number.isFinite(options.limit) || options.limit <= 0)
+                throw new Error("autoPagingToArray requires a positive limit");
+            const items = [];
+            for await (const item of list) {
+                items.push(item);
+                if (items.length >= options.limit)
+                    break;
+            }
+            return items;
+        },
+        async *[Symbol.asyncIterator]() {
+            let current = list;
+            while (current) {
+                yield* current.data;
+                current = await current.nextPage();
+            }
+        },
+    };
+    return list;
+}

package/dist/blaxel/preview.d.ts

@@ -0,0 +1,110 @@
+import type { RuntimeSandbox } from "./client.js";
+export type PreviewMetadata = {
+    name: string;
+    displayName?: string;
+    resourceName?: string;
+    resourceType?: string;
+    workspace?: string;
+    createdAt?: string;
+    updatedAt?: string;
+};
+export type PreviewSpec = {
+    customDomain?: string;
+    expires?: string;
+    port?: number;
+    prefixUrl?: string;
+    public?: boolean;
+    readonly region?: string;
+    requestHeaders?: {
+        [key: string]: string;
+    };
+    responseHeaders?: {
+        [key: string]: string;
+    };
+    ttl?: string;
+    readonly url?: string;
+};
+export type Preview = {
+    events?: Array<Record<string, unknown>>;
+    metadata: PreviewMetadata;
+    spec: PreviewSpec;
+    status?: string;
+};
+export type PreviewToken = {
+    metadata: {
+        name: string;
+        resourceName?: string;
+        previewName?: string;
+    };
+    spec: {
+        readonly expired?: boolean;
+        expiresAt?: string;
+        readonly token?: string;
+    };
+};
+/** What the previews need from their sandbox. */
+export interface PreviewContext {
+    readonly sandboxName: string;
+    run<T>(work: (runtime: RuntimeSandbox) => Promise<T>): Promise<T>;
+    /** The sandbox's labels as last read. */
+    labels(): Record<string, string>;
+    /** Sets (or with undefined removes) some of the adapter's labels. */
+    setLabels(changes: Record<string, string | undefined>): Promise<void>;
+}
+/** A preview token, as Blaxel's. Runtime reads it from the
+ * `x-runtime-preview-token` header or `?runtime_preview_token=`. */
+export declare class SandboxPreviewToken {
+    #private;
+    constructor(previewToken: PreviewToken);
+    get value(): string;
+    get expiresAt(): string | Date;
+    get expired(): boolean;
+}
+/** A preview's tokens. Runtime signs a token for a duration; it keeps no
+ * list of the tokens issued. */
+export declare class SandboxPreviewTokens {
+    #private;
+    constructor(preview: SandboxPreview, ctx: PreviewContext);
+    get previewName(): string;
+    get resourceName(): string;
+    /** A token that lasts until `expiresAt` (at least a minute, at most a week). */
+    create(expiresAt: Date): Promise<SandboxPreviewToken>;
+    list(): Promise<never>;
+    /** Revokes the preview's tokens. Runtime cannot revoke one token alone, so
+     * every token issued for this preview stops working. */
+    delete(_tokenName: string): Promise<{
+        message?: string;
+    }>;
+}
+/** A shared port, as Blaxel's SandboxPreview. */
+export declare class SandboxPreview {
+    #private;
+    readonly tokens: SandboxPreviewTokens;
+    constructor(preview: Preview, ctx: PreviewContext);
+    get name(): string;
+    get metadata(): PreviewMetadata;
+    get spec(): PreviewSpec;
+}
+/** `sandbox.previews`. */
+export declare class SandboxPreviews {
+    #private;
+    constructor(ctx: PreviewContext);
+    get sandboxName(): string;
+    /** Every shared port. One Runtime shared without a Blaxel name is named
+     * `preview-<port>`. */
+    list(): Promise<SandboxPreview[]>;
+    /** Shares `spec.port`: public with `spec.public`, else behind a token. */
+    create(preview: Preview, _force?: boolean): Promise<SandboxPreview>;
+    /** The named preview, or a new one when there is none. */
+    createIfNotExists(preview: Preview, force?: boolean): Promise<SandboxPreview>;
+    get(previewName: string): Promise<SandboxPreview>;
+    /** Stops sharing the port; open connections close within seconds. */
+    delete(previewName: string): Promise<Preview>;
+}
+/** A private preview of `port` with a token that lasts a while, for
+ * `sandbox.fetch`: made once, then reused until its token nears its end. */
+export declare function portAccess(runtime: RuntimeSandbox, port: number): Promise<{
+    url: string;
+    token: string | null;
+    until: number;
+}>;