withruntime 0.12.0 → 0.16.0

package/dist/blaxel/errors.js

@@ -198,3 +198,117 @@ export function codeOf(error) {
         return error.runtimeCode;
     return undefined;
 }
+function readProperty(value, key) {
+    try {
+        return typeof value === "object" && value !== null
+            ? value[key]
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const isCode = (value) => (typeof value === "string" && value.length > 0) ||
+    (typeof value === "number" && Number.isFinite(value));
+const isStatus = (value) => typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 599;
+/** True for an error this package throws for an API failure (ResponseError,
+ * SandboxGatewayError, SandboxCreationTimeoutError) or a raw Blaxel error body
+ * (`{ error, code }`, `{ code, message, status_code }`,
+ * `{ error: { code, message, status } }`). False for plain errors, strings and
+ * NotSupportedError, which is a refusal made here, not an API failure. Never
+ * throws. */
+export function isBlaxelError(err) {
+    try {
+        if (err instanceof Error)
+            return err instanceof ResponseError || err instanceof SandboxCreationTimeoutError;
+        if (typeof err !== "object" || err === null || Array.isArray(err))
+            return false;
+        const error = readProperty(err, "error");
+        if (typeof error === "string")
+            return isStatus(readProperty(err, "code"));
+        if (typeof readProperty(err, "code") === "string" &&
+            typeof readProperty(err, "message") === "string" &&
+            isStatus(readProperty(err, "status_code")))
+            return true;
+        return (typeof error === "object" &&
+            error !== null &&
+            !Array.isArray(error) &&
+            typeof readProperty(error, "code") === "string" &&
+            typeof readProperty(error, "message") === "string" &&
+            isStatus(readProperty(error, "status")));
+    }
+    catch {
+        return false;
+    }
+}
+function errorCandidates(err) {
+    const bodies = [err, readProperty(err, "error"), readProperty(err, "data")];
+    return bodies.flatMap((body) => [body, readProperty(body, "error")]);
+}
+function readHeader(err, name) {
+    try {
+        const headers = readProperty(readProperty(err, "response"), "headers");
+        const get = readProperty(headers, "get");
+        if (typeof get !== "function")
+            return undefined;
+        const value = Reflect.apply(get, headers, [name]);
+        return typeof value === "string" && value.length > 0 ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The error's code, then its body's, then the X-Blaxel-Error-Code header. A
+ * ResponseError from Runtime answers its HTTP status (its `code`); Runtime's
+ * own code is `runtimeCode`. Never throws. */
+export function getBlaxelErrorCode(err) {
+    for (const candidate of errorCandidates(err)) {
+        const code = readProperty(candidate, "code");
+        if (isCode(code))
+            return code;
+    }
+    return readHeader(err, "x-blaxel-error-code");
+}
+/** The HTTP status: the error's, its response's, then its body's (`status`,
+ * `status_code` or a numeric `code`). Never throws. */
+export function getBlaxelErrorStatus(err) {
+    const status = readProperty(err, "status");
+    if (isStatus(status))
+        return status;
+    const responseStatus = readProperty(readProperty(err, "response"), "status");
+    if (isStatus(responseStatus))
+        return responseStatus;
+    for (const candidate of errorCandidates(err))
+        for (const key of ["status", "status_code", "code"]) {
+            const value = readProperty(candidate, key);
+            if (isStatus(value))
+                return value;
+        }
+    return undefined;
+}
+/** The error's message, else its body's message or error text. Never throws. */
+export function getBlaxelErrorMessage(err) {
+    for (const candidate of errorCandidates(err)) {
+        const message = typeof candidate === "string" ? candidate : readProperty(candidate, "message");
+        if (typeof message === "string" && message.length > 0)
+            return message;
+    }
+    return undefined;
+}
+/** Blaxel's request id headers (X-Cf-Request-Id, X-Amz-Cf-Id, CF-Ray) on the
+ * error's response, else the Runtime request id a ResponseError carries
+ * (`requestId`). Never throws. */
+export function getBlaxelErrorRequestId(err) {
+    for (const name of ["x-cf-request-id", "x-amz-cf-id", "cf-ray"]) {
+        const value = readHeader(err, name);
+        if (value !== undefined)
+            return value;
+    }
+    try {
+        const runtime = err instanceof ResponseError ? err.requestId : undefined;
+        return typeof runtime === "string" && runtime.length > 0 ? runtime : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/blaxel/index.d.ts

@@ -3,9 +3,9 @@ export { SandboxInstance, DEFAULT_IMAGE, DEFAULT_MEMORY, MEMORY_PER_VCPU, durati
 export { CodeInterpreter } from "./interpreter.js";
 export { SandboxFileSystem, retryOnTransient, type File, type FileWithContent, type Subdirectory, type Directory, type SuccessResponse, type FindMatch, type FindResponse, type FuzzySearchMatch, type FuzzySearchResponse, type ContentSearchMatch, type ContentSearchResponse, type CopyResponse, type WatchEvent, type SandboxFilesystemFile, type FilesystemSearchOptions, type FilesystemFindOptions, type FilesystemGrepOptions, } from "./filesystem.js";
 export { SandboxProcess, type ProcessRequest, type ProcessResponse, type ProcessRequestWithLog, type ProcessResponseWithLog, type PostProcessResponse, type GetProcessResponse, type GetProcessByIdentifierResponse, type DeleteProcessByIdentifierResponse, type DeleteProcessByIdentifierKillResponse, type ProcessLogs, } from "./process.js";
-export { SandboxPreview, SandboxPreviews, SandboxPreviewToken, SandboxPreviewTokens, type Preview, type PreviewMetadata, type PreviewSpec, type PreviewToken, } from "./preview.js";
+export { SandboxPreview, SandboxPreviews, SandboxPreviewToken, SandboxPreviewTokens, type Preview, type PreviewMetadata, type PreviewSpec, type PreviewToken, type SandboxPreviewCreateConfiguration, } from "./preview.js";
 export { Snapshot, SandboxSnapshotsResource, type Env, type SandboxSnapshot, type SandboxSnapshotSource, type SandboxSnapshotSpec, type SandboxForkResponse, type SandboxRestoreResponse, type SnapshotCreateConfiguration, type SnapshotForkOptions, type SnapshotListQuery, } from "./snapshot.js";
-export { ResponseError, SandboxCreationTimeoutError, isCreationTimeoutError, SandboxGatewayError, isGatewayError, isGatewayTimeout, CredentialsError, NotSupportedError, } from "./errors.js";
+export { ResponseError, SandboxCreationTimeoutError, isCreationTimeoutError, SandboxGatewayError, isGatewayError, isGatewayTimeout, CredentialsError, NotSupportedError, isBlaxelError, getBlaxelErrorCode, getBlaxelErrorStatus, getBlaxelErrorMessage, getBlaxelErrorRequestId, type BlaxelGatewayErrorCode, type BlaxelAuthErrorCode, type BlaxelSandboxCreationErrorCode, type BlaxelErrorCode, type BlaxelErrorCodeValue, type BlaxelApiErrorBody, type BlaxelActionErrorBody, type BlaxelPlatformErrorBody, type BlaxelSandboxApiErrorBody, type BlaxelErrorLike, } from "./errors.js";
 export { createPaginatedList, unwrapListData, type PaginatedList, type PaginatedListMeta, type ListResponse, type CursorPaginationQuery, type AutoPagingEachCallback, type AutoPagingToArrayOptions, } from "./pagination.js";
 export { normalizePorts, normalizeEnvs, normalizeVolumes, type Status, type Port, type EnvVar, type ExpirationPolicy, type SandboxLifecycle, type SandboxNetwork, type VolumeBinding, type VolumeAttachment, type Metadata, type SandboxRuntime, type SandboxSpec, type CoreEvent, type Sandbox, type SandboxConfiguration, type SandboxCreateConfiguration, type SandboxUpdateMetadata, type SandboxUpdateNetwork, type SessionCreateOptions, type SessionWithToken, } from "./types.js";
 export { initialize, type Config, type WithRuntime, type RuntimeOptions } from "./client.js";
@@ -35,11 +35,13 @@ export declare const logger: {
     error: (...message: unknown[]) => void;
 };
 /** Blaxel's settings, as far as they mean anything on Runtime. `setConfig`
- * takes a Runtime key as `apikey`; anything else throws NotSupportedError. */
+ * takes a Runtime key as `apikey`; `integration` is kept but never sent;
+ * anything else throws NotSupportedError. */
 export declare const settings: {
     readonly env: string;
     readonly region: string | undefined;
     readonly workspace: string;
+    integration: string;
     setConfig(config: Config): void;
     authenticate(): Promise<void>;
     readonly [key: string]: unknown;
@@ -124,6 +126,7 @@ export declare const updateDrive: import("./unsupported.js").Unsupported;
 export declare const createDriveAccessToken: import("./unsupported.js").Unsupported;
 export declare const getDriveByExternalId: import("./unsupported.js").Unsupported;
 export declare const getDriveJwks: import("./unsupported.js").Unsupported;
+export declare const deleteDriveFolder: import("./unsupported.js").Unsupported;
 export declare const listAllEgressGateways: import("./unsupported.js").Unsupported;
 export declare const getEgressGatewayUsage: import("./unsupported.js").Unsupported;
 export declare const listAllEgressIps: import("./unsupported.js").Unsupported;
@@ -214,6 +217,10 @@ export declare const getSandboxByExternalId: import("./unsupported.js").Unsuppor
 export declare const listScheduleExecutions: import("./unsupported.js").Unsupported;
 export declare const listSchedules: import("./unsupported.js").Unsupported;
 export declare const getSandboxScheduleMetrics: import("./unsupported.js").Unsupported;
+export declare const listSecrets: import("./unsupported.js").Unsupported;
+export declare const upsertSecret: import("./unsupported.js").Unsupported;
+export declare const deleteSecret: import("./unsupported.js").Unsupported;
+export declare const deleteSecretByQuery: import("./unsupported.js").Unsupported;
 export declare const getWorkspaceServiceAccounts: import("./unsupported.js").Unsupported;
 export declare const createWorkspaceServiceAccount: import("./unsupported.js").Unsupported;
 export declare const deleteWorkspaceServiceAccount: import("./unsupported.js").Unsupported;

package/dist/blaxel/index.js

@@ -4,11 +4,11 @@
  *   import { SandboxInstance } from "withruntime/blaxel"; // was: from "@blaxel/core"
  *
  * and set RUNTIME_API_KEY, or run `npx withruntime login` once. A Blaxel key
- * (BL_API_KEY) is never sent anywhere. Every name `@blaxel/core` 0.3.25
+ * (BL_API_KEY) is never sent anywhere. Every name `@blaxel/core` 0.3.30
  * exports can be imported; what Runtime cannot do the way Blaxel does throws
  * NotSupportedError, naming what to use. */
 import { RuntimeError } from "../errors.js";
-import { initialize } from "./client.js";
+import { initialize, integrationToken, setIntegrationToken } from "./client.js";
 import { NotSupportedError } from "./errors.js";
 import { CODEGEN, DRIVES, SCHEDULES, SYSTEM, unsupportedExport } from "./unsupported.js";
 export { SandboxInstance, DEFAULT_IMAGE, DEFAULT_MEMORY, MEMORY_PER_VCPU, durationMs, imageRef, lifetimeOf, networkRules, MAX_CREATION_TIMEOUT_SECONDS, } from "./sandbox.js";
@@ -17,7 +17,7 @@ export { SandboxFileSystem, retryOnTransient, } from "./filesystem.js";
 export { SandboxProcess, } from "./process.js";
 export { SandboxPreview, SandboxPreviews, SandboxPreviewToken, SandboxPreviewTokens, } from "./preview.js";
 export { Snapshot, SandboxSnapshotsResource, } from "./snapshot.js";
-export { ResponseError, SandboxCreationTimeoutError, isCreationTimeoutError, SandboxGatewayError, isGatewayError, isGatewayTimeout, CredentialsError, NotSupportedError, } from "./errors.js";
+export { ResponseError, SandboxCreationTimeoutError, isCreationTimeoutError, SandboxGatewayError, isGatewayError, isGatewayTimeout, CredentialsError, NotSupportedError, isBlaxelError, getBlaxelErrorCode, getBlaxelErrorStatus, getBlaxelErrorMessage, getBlaxelErrorRequestId, } from "./errors.js";
 export { createPaginatedList, unwrapListData, } from "./pagination.js";
 export { normalizePorts, normalizeEnvs, normalizeVolumes, } from "./types.js";
 export { initialize } from "./client.js";
@@ -54,7 +54,8 @@ export const logger = {
     error: (...message) => sink.error(text(message)),
 };
 /** Blaxel's settings, as far as they mean anything on Runtime. `setConfig`
- * takes a Runtime key as `apikey`; anything else throws NotSupportedError. */
+ * takes a Runtime key as `apikey`; `integration` is kept but never sent;
+ * anything else throws NotSupportedError. */
 export const settings = new Proxy({
     get env() {
         return "prod";
@@ -65,6 +66,14 @@ export const settings = new Proxy({
     get workspace() {
         return env.BL_WORKSPACE ?? "";
     },
+    /* Blaxel's product token for an integration (0.3.29): checked and kept
+       as Blaxel does, never sent; Runtime does not attribute traffic by it. */
+    get integration() {
+        return integrationToken();
+    },
+    set integration(value) {
+        setIntegrationToken(value);
+    },
     setConfig: (config) => initialize(config),
     authenticate,
 }, {
@@ -176,6 +185,7 @@ export const updateDrive = api("updateDrive");
 export const createDriveAccessToken = api("createDriveAccessToken");
 export const getDriveByExternalId = api("getDriveByExternalId");
 export const getDriveJwks = api("getDriveJwks");
+export const deleteDriveFolder = api("deleteDriveFolder");
 export const listAllEgressGateways = api("listAllEgressGateways");
 export const getEgressGatewayUsage = api("getEgressGatewayUsage");
 export const listAllEgressIps = api("listAllEgressIps");
@@ -266,6 +276,15 @@ export const getSandboxByExternalId = api("getSandboxByExternalId");
 export const listScheduleExecutions = api("listScheduleExecutions");
 export const listSchedules = api("listSchedules");
 export const getSandboxScheduleMetrics = api("getSandboxScheduleMetrics");
+/* @blaxel/core 0.3.30's workspace secrets, which Blaxel's proxy puts into a
+   sandbox's routing as {{SECRET:name}}. Runtime's secrets are bound to the
+   hosts they may reach, which Blaxel's calls do not name. */
+const SECRETS = 'Use Runtime secrets, which name the hosts a secret may reach: runtime.secrets.set(name, { value, hosts }) (`import { Runtime } from "withruntime"`); the egress proxy adds the value on HTTPS to those hosts and the sandbox never sees it.';
+const secretApi = (name) => unsupportedExport(`API function ${name}`, SECRETS);
+export const listSecrets = secretApi("listSecrets");
+export const upsertSecret = secretApi("upsertSecret");
+export const deleteSecret = secretApi("deleteSecret");
+export const deleteSecretByQuery = secretApi("deleteSecretByQuery");
 export const getWorkspaceServiceAccounts = api("getWorkspaceServiceAccounts");
 export const createWorkspaceServiceAccount = api("createWorkspaceServiceAccount");
 export const deleteWorkspaceServiceAccount = api("deleteWorkspaceServiceAccount");

package/dist/blaxel/preview.d.ts

@@ -30,6 +30,14 @@ export type Preview = {
     spec: PreviewSpec;
     status?: string;
 };
+/** @blaxel/core 0.3.29's shorthand for `previews.create` and
+ * `createIfNotExists`: a port, with a name (`preview-<port>` when left out)
+ * and public (false when left out). */
+export type SandboxPreviewCreateConfiguration = {
+    port: number;
+    name?: string;
+    public?: boolean;
+};
 export type PreviewToken = {
     metadata: {
         name: string;
@@ -45,6 +53,9 @@ export type PreviewToken = {
 /** What the previews need from their sandbox. */
 export interface PreviewContext {
     readonly sandboxName: string;
+    /** The Runtime sandbox's id, when known: tokens made for a sandbox are
+     * never reused for another of the same name. */
+    readonly sandboxId?: string;
     run<T>(work: (runtime: RuntimeSandbox) => Promise<T>): Promise<T>;
     /** The sandbox's labels as last read. */
     labels(): Record<string, string>;
@@ -56,6 +67,7 @@ export interface PreviewContext {
 export declare class SandboxPreviewToken {
     #private;
     constructor(previewToken: PreviewToken);
+    get name(): string;
     get value(): string;
     get expiresAt(): string | Date;
     get expired(): boolean;
@@ -70,6 +82,13 @@ export declare class SandboxPreviewTokens {
     /** A token bounded by `expiresAt`; native signing floors milliseconds and
      * caps it to the caller's session. Older servers refuse without a TTL fallback. */
     create(expiresAt: Date): Promise<SandboxPreviewToken>;
+    /** Blaxel's (0.3.29): the latest token lasting at least `minValidity` ms
+     * more (an hour unless given) and not past `expiresAt` (a day from now
+     * unless given), else a new one until `expiresAt`. Blaxel picks among the
+     * preview's listed tokens; Runtime keeps no list, so the one reused is the
+     * token this call made last in this process for this sandbox's port, and a
+     * new process makes a new one. Arguments are checked as Blaxel does. */
+    createIfExpired(expiresAt?: Date, minValidity?: number): 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. */
@@ -85,6 +104,8 @@ export declare class SandboxPreview {
     get name(): string;
     get metadata(): PreviewMetadata;
     get spec(): PreviewSpec;
+    /** The preview's address (`spec.url`), or `""`. */
+    get url(): string;
 }
 /** `sandbox.previews`. */
 export declare class SandboxPreviews {
@@ -94,10 +115,14 @@ export declare class SandboxPreviews {
     /** 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>;
+    /** Shares `spec.port`: public with `spec.public`, else behind a token.
+     * Blaxel's shorthand `{ port, name?, public? }` is a private
+     * `preview-<port>` unless it says otherwise. */
+    create(input: Preview | SandboxPreviewCreateConfiguration, _force?: boolean): Promise<SandboxPreview>;
+    /** The named preview, or a new one when there is none. An existing
+     * preview is answered as it is: the shorthand's private default applies
+     * only to a new one. */
+    createIfNotExists(input: Preview | SandboxPreviewCreateConfiguration, force?: boolean): Promise<SandboxPreview>;
     get(previewName: string): Promise<SandboxPreview>;
     /** Stops sharing the port; its open connections are closed before this returns. */
     delete(previewName: string): Promise<Preview>;

package/dist/blaxel/preview.js

@@ -1,5 +1,22 @@
 import { guard, isNotFound, NotSupportedError, responseError } from "./errors.js";
 import { PREVIEW } from "./lookup.js";
+const isShorthand = (preview) => !("metadata" in preview || "spec" in preview);
+/** Blaxel's shorthand as the full shape, with Blaxel's checks and messages. */
+function normalizePreview(preview) {
+    if (!isShorthand(preview))
+        return preview;
+    const short = preview;
+    if (!Number.isInteger(short.port) || short.port < 1 || short.port > 65535)
+        throw new RangeError("Preview port must be an integer between 1 and 65535");
+    if (short.name !== undefined && (typeof short.name !== "string" || short.name.length === 0))
+        throw new RangeError("Preview name must be a nonempty string");
+    if (short.public !== undefined && typeof short.public !== "boolean")
+        throw new RangeError("Preview public must be a boolean");
+    return {
+        metadata: { name: short.name ?? `preview-${short.port}` },
+        spec: { port: short.port, public: short.public ?? false },
+    };
+}
 function checkName(name) {
     if (!/^[A-Za-z0-9._-]{1,48}$/.test(name))
         throw new NotSupportedError(`The preview name "${name}"`, "Use 1 to 48 letters, digits, dots, dashes or underscores.");
@@ -27,6 +44,9 @@ export class SandboxPreviewToken {
     constructor(previewToken) {
         this.#token = previewToken;
     }
+    get name() {
+        return this.#token.metadata?.name ?? "";
+    }
     get value() {
         return this.#token.spec.token ?? "";
     }
@@ -38,6 +58,9 @@ export class SandboxPreviewToken {
         return at !== undefined && Date.parse(at) <= Date.now();
     }
 }
+/** The token createIfExpired made last, per sandbox and port, in this
+ * process: Runtime keeps no list of the tokens it signed. */
+const madeTokens = new Map();
 /** A preview's tokens. Runtime signs a token for a duration; it keeps no
  * list of the tokens issued. */
 export class SandboxPreviewTokens {
@@ -53,6 +76,9 @@ export class SandboxPreviewTokens {
     get resourceName() {
         return this.#ctx.sandboxName;
     }
+    #key() {
+        return `${this.#ctx.sandboxId ?? this.#ctx.sandboxName}:${this.#preview.spec.port}`;
+    }
     /** A token bounded by `expiresAt`; native signing floors milliseconds and
      * caps it to the caller's session. Older servers refuse without a TTL fallback. */
     async create(expiresAt) {
@@ -73,6 +99,35 @@ export class SandboxPreviewTokens {
             spec: { token: got.token, expiresAt: got.tokenExpiresAt },
         });
     }
+    /** Blaxel's (0.3.29): the latest token lasting at least `minValidity` ms
+     * more (an hour unless given) and not past `expiresAt` (a day from now
+     * unless given), else a new one until `expiresAt`. Blaxel picks among the
+     * preview's listed tokens; Runtime keeps no list, so the one reused is the
+     * token this call made last in this process for this sandbox's port, and a
+     * new process makes a new one. Arguments are checked as Blaxel does. */
+    async createIfExpired(expiresAt, minValidity = 3_600_000) {
+        const now = Date.now();
+        if (!Number.isFinite(minValidity) || minValidity < 0)
+            throw new RangeError("minValidity must be finite and non-negative");
+        const requested = expiresAt ?? new Date(now + 86_400_000);
+        const ceiling = requested instanceof Date ? requested.getTime() : Number.NaN;
+        if (!Number.isFinite(ceiling) || ceiling <= now || ceiling < now + minValidity)
+            throw new RangeError("expiresAt must be a valid future date at least minValidity from now");
+        if (this.#preview.spec.public === true)
+            throw new Error("Cannot create or reuse a token for a public preview");
+        const key = this.#key();
+        const kept = madeTokens.get(key);
+        if (kept &&
+            kept.expiresAt > now &&
+            kept.expiresAt >= now + minValidity &&
+            kept.expiresAt <= ceiling)
+            return kept.token;
+        const token = await this.create(requested);
+        const until = Date.parse(String(token.expiresAt));
+        if (Number.isFinite(until))
+            madeTokens.set(key, { token, expiresAt: until });
+        return token;
+    }
     list() {
         return Promise.reject(new NotSupportedError("Listing a preview's tokens", "Runtime keeps no list of issued tokens: keep the ones you create, or create a new one."));
     }
@@ -81,6 +136,7 @@ export class SandboxPreviewTokens {
     async delete(_tokenName) {
         const port = this.#preview.spec.port;
         await this.#ctx.run((runtime) => runtime.previews.rotate(port));
+        madeTokens.delete(this.#key());
         return { message: "Every token of this preview was revoked" };
     }
 }
@@ -101,6 +157,10 @@ export class SandboxPreview {
     get spec() {
         return this.#preview.spec;
     }
+    /** The preview's address (`spec.url`), or `""`. */
+    get url() {
+        return this.#preview.spec?.url ?? "";
+    }
 }
 /** `sandbox.previews`. */
 export class SandboxPreviews {
@@ -133,8 +193,11 @@ export class SandboxPreviews {
         const names = this.#names();
         return previews.map((one) => new SandboxPreview(modelOf(one, names.get(one.port) ?? `preview-${one.port}`, this.sandboxName), this.#ctx));
     }
-    /** Shares `spec.port`: public with `spec.public`, else behind a token. */
-    async create(preview, _force) {
+    /** Shares `spec.port`: public with `spec.public`, else behind a token.
+     * Blaxel's shorthand `{ port, name?, public? }` is a private
+     * `preview-<port>` unless it says otherwise. */
+    async create(input, _force) {
+        const preview = input && typeof input === "object" ? normalizePreview(input) : input;
         const spec = preview?.spec ?? {};
         const name = preview?.metadata?.name;
         const refusals = [
@@ -177,15 +240,26 @@ export class SandboxPreviews {
         ]);
         return new SandboxPreview(modelOf(made, name ?? `preview-${port}`, this.sandboxName), this.#ctx);
     }
-    /** The named preview, or a new one when there is none. */
-    async createIfNotExists(preview, force) {
+    /** The named preview, or a new one when there is none. An existing
+     * preview is answered as it is: the shorthand's private default applies
+     * only to a new one. */
+    async createIfNotExists(input, force) {
+        const preview = normalizePreview(input);
         try {
             return await this.get(preview.metadata.name);
         }
         catch (error) {
             if (!isNotFound(error))
                 throw error;
-            return this.create(preview, force);
+        }
+        try {
+            return await this.create(preview, force);
+        }
+        catch (error) {
+            // Blaxel's race: another caller made it first.
+            if (!isShorthand(input) || error?.status !== 409)
+                throw error;
+            return this.get(preview.metadata.name);
         }
     }
     async get(previewName) {

package/dist/blaxel/sandbox.d.ts

@@ -139,7 +139,7 @@ export declare class SandboxInstance {
     get expiresIn(): number | undefined;
     /** Creates a sandbox and answers once it runs. Blaxel's defaults: the base
      * image (Runtime's stock image) and 4096 MB, with vCPUs at one per 2048 MB.
-     * Funding is left to Runtime: the included usage first, then prepaid credit. A name another live sandbox holds is refused
+     * Funding is left to Runtime: the free usage first, then prepaid credit. A name another live sandbox holds is refused
      * with a 409, as in Blaxel. */
     static create<T extends typeof SandboxInstance>(this: T, sandbox?: SandboxCreateConfiguration | SandboxModel, options?: SandboxCreateOptions): Promise<InstanceType<T>>;
     /** The named sandbox, or a new one when no live sandbox has the name.

package/dist/blaxel/sandbox.js

@@ -332,6 +332,7 @@ export class SandboxInstance {
         });
         this.previews = new SandboxPreviews({
             sandboxName: this.name,
+            sandboxId: this.#rt.id,
             run,
             labels: () => this.#rt.info.labels,
             setLabels: (changes) => this.#setLabels(changes),
@@ -573,7 +574,7 @@ export class SandboxInstance {
     // ---- create, get, list ---------------------------------------------------
     /** Creates a sandbox and answers once it runs. Blaxel's defaults: the base
      * image (Runtime's stock image) and 4096 MB, with vCPUs at one per 2048 MB.
-     * Funding is left to Runtime: the included usage first, then prepaid credit. A name another live sandbox holds is refused
+     * Funding is left to Runtime: the free usage first, then prepaid credit. A name another live sandbox holds is refused
      * with a 409, as in Blaxel. */
     static async create(sandbox, options = {}) {
         const { createIfNotExist = false, safe = false } = options;

package/dist/blaxel/session.js

@@ -44,8 +44,10 @@ function origins(headers = {}) {
     return found;
 }
 function seconds(expiresAt) {
-    const at = expiresAt ?? new Date(Date.now() + DAY_MS);
-    const left = Math.floor((at.getTime() - Date.now()) / 1000);
+    // Blaxel's default is a day; counted from a moment ago it would be a second short.
+    if (!expiresAt)
+        return DAY_MS / 1000;
+    const left = Math.floor((expiresAt.getTime() - Date.now()) / 1000);
     if (!Number.isFinite(left) || left < 60)
         throw responseError(400, "A session must last at least a minute.");
     if (left > DAY_MS / 1000 + 5)

package/dist/cli-extras.js

@@ -108,7 +108,7 @@ export async function mcpCommand(sbx, argv, out, kit) {
     };
     switch (action) {
         case "start": {
-            const args = parse(rest, ["replace"], ["secret", "env", "option", "port"]);
+            const args = parse(rest, ["replace", "public"], ["secret", "env", "option", "port"]);
             if (!args.positional.length)
                 throw usage("Name the servers: runtime sandboxes mcp <id> start github fetch");
             const scoped = (name) => {
@@ -133,6 +133,7 @@ export async function mcpCommand(sbx, argv, out, kit) {
             const gw = await sbx.mcp.start(servers, {
                 ...(integer(args, "port") ? { port: integer(args, "port") } : {}),
                 ...(has(args, "replace") ? { replace: true } : {}),
+                ...(has(args, "public") ? { public: true } : {}),
             });
             print(`${show(gw)}\nServers are installing; \`${me} sandboxes mcp ${sbx.id}\` shows when they are ready.`, gw);
             return 0;

package/dist/cli-words.js

@@ -24,6 +24,7 @@ const OPTIONS = {
     funding: { flag: "--trial / --paid" },
     image: { flag: "--image" },
     snapshot: { flag: "--snapshot" },
+    spreadFrom: { flag: "--spread-from" },
     volumes: { flag: "--volume" },
     network: { flag: "--allow / --deny / --connect / --no-internet" },
     maxCostMicros: { flag: "--max-cost", micros: true },

package/dist/cli.d.ts

@@ -2,7 +2,7 @@
 import { RuntimeError } from "./errors.js";
 import type { OutOfMemory, Usage } from "./types.js";
 import type { SwitchProvider } from "./products/switching.js";
-import type { SecretRule } from "./products/secrets.js";
+import type { SecretRule, SecretScope } from "./products/secrets.js";
 type Out = {
     json: boolean;
     write: (text: string) => void;
@@ -30,7 +30,7 @@ declare const kit: {
 };
 export type CliKit = typeof kit;
 export declare function run(argv: string[], env?: NodeJS.ProcessEnv, out?: Out): Promise<number>;
-/** `runtime usage` for a person: the balance, the included usage and what each kind
+/** `runtime usage` for a person: the balance, the free usage and what each kind
  * of resource was charged, in dollars. --json keeps every figure, and each
  * resource with its rates and CPU time. */
 /** One row per resource, for a spreadsheet: when it ran, how big it was, how
@@ -44,12 +44,27 @@ export declare function usageCsv(u: Usage): string;
 export declare function outOfMemoryLines(memory: OutOfMemory | undefined): string | undefined;
 /** How to move a rival's code across, when one import does it. */
 export declare function dropInLines(provider: SwitchProvider | undefined): string[];
+/** A secret's value, from standard input only, so it never sits in shell
+ * history or a process list. Piped: everything, less one trailing newline.
+ * A terminal: one line, not shown. */
+/** A pasted secret as the header it becomes: no line breaks (a token copied
+ * from a terminal arrives wrapped), no bracketed-paste markers, no space at
+ * either end. 13 October 2026: a user's pasted Claude token was refused as
+ * "not visible ASCII". A header cannot hold a line break, so none is lost. */
+export declare function cleanSecret(raw: string): string;
 /** `--allow` values as secret rules: each is `[METHOD[,METHOD]...] PATH`, and
  * rules naming the same methods share one rule's paths. Only the shape is read
  * here; the API holds every rule to the same check the host makes
  * (ARCHITECTURE.md section 10, "Per-path rules on an egress secret") and says
  * which one it refused. */
 export declare function parseSecretRules(values: string[]): SecretRule[];
+/** `--only-label role=hub,tier=x --only-sandbox <id>`: a sandbox whose labels
+ * hold every pair of any one --only-label gets the secret, and so does each
+ * --only-sandbox. `--all-sandboxes`: every sandbox again. Nothing: undefined,
+ * so a replacement keeps the scope it has. */
+export declare function parseSecretScope(labels: string[] | undefined, sandboxes: string[] | undefined, all: boolean): SecretScope | undefined;
+/** Who gets a secret, in a few words. */
+export declare const scopeText: (only: SecretScope | undefined) => string;
 export declare function secretsCommand(argv: string[], env: NodeJS.ProcessEnv, out: Out, 
 /** Tests give the value here; the CLI reads standard input. */
 read?: () => Promise<string>): Promise<number>;