withruntime 0.4.0 → 0.5.1

package/dist/products/audit.d.ts

@@ -0,0 +1,48 @@
+import type { RequestOptions, Transport } from "../transport.js";
+/** One entry of the account's audit log. */
+export type AuditEvent = {
+    /** Position in the log. Pass the last page's `next` as `before`. */
+    seq: string;
+    id: string;
+    /** When, ISO 8601 UTC. */
+    at: string;
+    /** What happened, like `member.role_changed`, `key.created` or `credit.purchased`. */
+    action: string;
+    actor: {
+        /** `runtime` is Runtime itself: a payment, an expiry, a takedown. */
+        kind: "person" | "agent" | "app" | "group" | "runtime";
+        id: string | null;
+        name: string | null;
+        /** For an agent: the member whose key it is. */
+        person: string | null;
+    };
+    target: {
+        type: string | null;
+        id: string | null;
+    };
+    /** The facts that matter, such as an email, a role or an amount. Never a secret. */
+    detail: Record<string, unknown>;
+    /** The client address the request came from. */
+    ip: string | null;
+    requestId: string | null;
+    via: "web" | "api" | "mcp" | "runtime";
+};
+export type AuditPage = {
+    events: AuditEvent[];
+    next: string | null;
+};
+/** `runtime.audit`: the account's audit log, newest first. Needs a key for
+ * every product or a read-only key, made by an owner or admin.
+ *
+ *   const { events, next } = await runtime.audit.list({ action: "member." });
+ */
+export declare function audit(t: Transport): {
+    list: (query?: {
+        /** An action (`key.created`), or a group ending in a dot (`member.`, `credit.`). */
+        action?: string;
+        /** 1 to 200; 50 by default. */
+        limit?: number;
+        /** The previous page's `next`. */
+        before?: string;
+    }, options?: RequestOptions) => Promise<AuditPage>;
+};

package/dist/products/audit.js

@@ -0,0 +1,10 @@
+/** `runtime.audit`: the account's audit log, newest first. Needs a key for
+ * every product or a read-only key, made by an owner or admin.
+ *
+ *   const { events, next } = await runtime.audit.list({ action: "member." });
+ */
+export function audit(t) {
+    return {
+        list: (query = {}, options) => t.json({ method: "GET", path: "/v1/audit", query, ...options }),
+    };
+}

package/dist/products/images.d.ts

@@ -1,6 +1,6 @@
 import { Page } from "../page.js";
 import type { RequestOptions, Transport } from "../transport.js";
-/** A file for a Dockerfile's build context or a recipe. */
+/** A file for a small build context sent inline, or a recipe. */
 export type ImageFile = {
     path: string;
     content: string;
@@ -8,7 +8,7 @@ export type ImageFile = {
     mode?: number;
 };
 export type ImageRecipe = {
-    /** "runtime" (the default) or a public image reference. */
+    /** "runtime" (the default) or an image reference. */
     base?: string;
     apt?: string[];
     pip?: string[];
@@ -24,22 +24,65 @@ export type ImageBuildLimits = {
     diskMiB?: number;
     maxImageMiB?: number;
     timeoutSeconds?: number;
+    /** The most this build's layer cache may keep. */
+    cacheMiB?: number;
+};
+/** What a sandbox from the image runs as it starts, and when its create
+ * answers: once `readyPort` is listened on, or `readyCommand` exits 0. */
+export type ImageStart = {
+    command?: string;
+    argv?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    readyCommand?: string;
+    readyPort?: number;
+    readyTimeoutSeconds?: number;
+};
+/** An uploaded build context: its archive's chunks and the files it holds. */
+export type ImageContext = {
+    archive: {
+        sha256: string;
+        size: number;
+        chunks: string[];
+    };
+    files: {
+        path: string;
+        sha256: string;
+        size: number;
+        mode?: number;
+    }[];
 };
 /** Exactly one of `image`, `dockerfile` or `recipe`. */
 export type CreateImage = {
+    /** Each build of a name is its next version. */
     name?: string;
+    /** Tags the build takes when ready; a named image with none takes `latest`. */
+    tags?: string[];
     labels?: Record<string, string>;
     region?: string;
     build?: ImageBuildLimits;
     env?: Record<string, string>;
+    /** Overrides a Dockerfile's CMD and HEALTHCHECK; null runs nothing. */
+    start?: ImageStart | null;
+    /** false: build every step afresh and keep no cache. */
+    cache?: boolean;
 } & ({
     image: string;
     dockerfile?: never;
     recipe?: never;
 } | {
     dockerfile: string;
+    /** A small context sent inline (1 MiB in all). */
     files?: ImageFile[];
+    /** A folder to send as the context, with its .dockerignore; uploaded
+     * as chunks, and only the ones the server does not have. */
+    contextDir?: string;
+    /** An already uploaded context (`uploadContext`). */
+    context?: ImageContext;
+    dockerignore?: string;
     buildArgs?: Record<string, string>;
+    /** Build this stage instead of the last. */
+    target?: string;
     image?: never;
     recipe?: never;
 } | {
@@ -54,6 +97,9 @@ export type Image = {
     status: string;
     state: ImageState;
     name: string | null;
+    version: number | null;
+    tags: string[];
+    pendingTags?: string[];
     labels: Record<string, string>;
     region: string;
     source: {
@@ -61,6 +107,9 @@ export type Image = {
         digest: string;
         base: unknown;
         steps: number;
+        planVersion?: number;
+        stages?: number;
+        contextBytes?: number | null;
     };
     build: ImageBuildLimits & {
         startedAt: string | null;
@@ -68,6 +117,14 @@ export type Image = {
         cachedSteps: number;
         builderVersion: string | null;
     };
+    cache?: {
+        enabled: boolean;
+        maxMiB: number;
+        from: string | null;
+        checkpoints: number;
+        bytes: number;
+    };
+    start?: ImageStart | null;
     sizeBytes: number | null;
     sizeMiB: number | null;
     storedBytes: number | null;
@@ -98,24 +155,73 @@ export type ImageLogs = {
     truncated: boolean;
     done: boolean;
 };
-/** Custom images: `runtime.images.build({ recipe: { pip: ["pandas"] } })`, then
- * `runtime.sandboxes.create({ image: image.id })`. */
+export type ImageRegistry = {
+    id: string;
+    registry: string;
+    kind: "basic" | "ecr";
+    username: string;
+    region: string | null;
+    createdAt: string;
+};
+/** Credentials for pulling private images: a user name and token or password
+ * (Docker Hub, GitHub, Google with username `_json_key`), or an AWS access
+ * key for Amazon ECR. Sealed for Runtime's hosts; never returned. */
+export type SetImageRegistry = {
+    registry: string;
+    username: string;
+    password: string;
+} | {
+    registry: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+};
+/** Custom images: `runtime.images.build({ recipe: { pip: ["pandas"] } })`, or
+ * `runtime.images.build({ name: "app", dockerfile, contextDir: "." })`, then
+ * `runtime.sandboxes.create({ image: "app" })`. */
 export declare function images(t: Transport): {
-    /** Queue a build and return at once, state "queued". */
-    create: (input: CreateImage, options?: RequestOptions) => Promise<Image>;
+    /** Queue a build and return at once, state "queued". With `contextDir`,
+     * the folder is packed and its missing chunks uploaded first. */
+    create(input: CreateImage, options?: RequestOptions): Promise<Image>;
     /** Build and wait until the image is ready or failed, streaming log lines
      * to `onLog`. Throws when the build fails, with the build's own error. */
     build(input: CreateImage, options?: RequestOptions & {
         onLog?: (line: ImageLogLine) => void;
         pollMs?: number;
     }): Promise<Image>;
+    uploadContext: (folder: string, options?: RequestOptions & {
+        dockerignore?: string;
+        dockerfile?: string;
+    }) => Promise<ImageContext & {
+        dockerignore?: string;
+    }>;
     get: (id: string, options?: RequestOptions) => Promise<Image>;
+    resolve: (ref: string, options?: RequestOptions) => Promise<Image>;
     logs: (id: string, after?: number, options?: RequestOptions) => Promise<ImageLogs>;
+    followLogs: (id: string, onLog: (line: ImageLogLine) => void, options?: RequestOptions & {
+        after?: number;
+        pollMs?: number;
+    }) => Promise<Image>;
     list: (query?: {
         state?: ImageState;
         name?: string;
         limit?: number;
         cursor?: string;
     }, options?: RequestOptions) => Promise<Page<Image>>;
-    delete: (id: string, options?: RequestOptions) => Promise<Image>;
+    /** Every version of a name, newest first. */
+    versions: (name: string, options?: RequestOptions) => Promise<Page<Image>>;
+    /** Point `tag` of the image's name at this version. */
+    tag(ref: string, tag: string, options?: RequestOptions): Promise<Image>;
+    untag(ref: string, tag: string, options?: RequestOptions): Promise<Image>;
+    /** Delete one version (by id, name:tag or name@version) and its tags. */
+    delete(ref: string, options?: RequestOptions): Promise<Image>;
+    /** Credentials for private registries. The secret is sealed on arrival
+     * and never returned. */
+    registries: {
+        list: (options?: RequestOptions) => Promise<ImageRegistry[]>;
+        set: (input: SetImageRegistry, options?: RequestOptions) => Promise<ImageRegistry>;
+        delete: (registry: string, options?: RequestOptions) => Promise<{
+            registry: string;
+            deleted: boolean;
+        }>;
+    };
 };

package/dist/products/images.js

@@ -1,11 +1,20 @@
 import { Page } from "../page.js";
-/** Custom images: `runtime.images.build({ recipe: { pip: ["pandas"] } })`, then
- * `runtime.sandboxes.create({ image: image.id })`. */
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+const PARALLEL_UPLOADS = 4;
+/** Custom images: `runtime.images.build({ recipe: { pip: ["pandas"] } })`, or
+ * `runtime.images.build({ name: "app", dockerfile, contextDir: "." })`, then
+ * `runtime.sandboxes.create({ image: "app" })`. */
 export function images(t) {
-    const get = (id, options) => t.json({ method: "GET", path: `/v1/images/${encodeURIComponent(id)}`, ...options });
+    const enc = encodeURIComponent;
+    const get = (id, options) => t.json({ method: "GET", path: `/v1/images/${enc(id)}`, ...options });
+    /** An image by id, name (its latest tag), name:tag or name@version. */
+    const resolve = (ref, options) => UUID.test(ref)
+        ? get(ref, options)
+        : t.json({ method: "GET", path: "/v1/images/resolve", query: { ref }, ...options });
+    const idOf = async (ref, options) => UUID.test(ref) ? ref : (await resolve(ref, options)).id;
     const logs = (id, after = 0, options) => t.json({
         method: "GET",
-        path: `/v1/images/${encodeURIComponent(id)}/logs`,
+        path: `/v1/images/${enc(id)}/logs`,
         query: { after },
         ...options,
     });
@@ -18,9 +27,123 @@ export function images(t) {
         });
         return new Page(page.data, page.nextCursor, (cursor) => list({ ...query, cursor }, options));
     };
+    /** Pack a folder as a build context and upload the chunks the server does
+     * not have yet. Node and Bun. */
+    async function uploadContext(folder, options = {}) {
+        const { dockerignore, dockerfile, ...request } = options;
+        const { packContext, chunkArchive } = await import("../image-context.js");
+        const packed = await packContext(folder, {
+            ...(dockerignore === undefined ? {} : { dockerignore }),
+            ...(dockerfile === undefined ? {} : { dockerfile }),
+        });
+        const archive = await chunkArchive(packed.archive);
+        const { missing } = await t.json({
+            method: "POST",
+            path: "/v1/images/context/missing",
+            body: { digests: archive.chunks.map((c) => c.sha256) },
+            ...request,
+        });
+        const wanted = new Set(missing);
+        const queue = archive.chunks.filter((chunk) => wanted.has(chunk.sha256));
+        const upload = async () => {
+            for (let chunk = queue.shift(); chunk; chunk = queue.shift())
+                await t.json({
+                    method: "PUT",
+                    path: `/v1/images/context/${chunk.sha256}`,
+                    bytes: chunk.bytes,
+                    ...request,
+                });
+        };
+        await Promise.all(Array.from({ length: PARALLEL_UPLOADS }, upload));
+        return {
+            archive: {
+                sha256: archive.sha256,
+                size: archive.size,
+                chunks: archive.chunks.map((c) => c.sha256),
+            },
+            files: packed.files,
+            ...(packed.dockerignore === undefined ? {} : { dockerignore: packed.dockerignore }),
+        };
+    }
+    /** The request, with a context folder uploaded and named instead. */
+    async function prepare(input, options) {
+        if (!("contextDir" in input) || input.contextDir === undefined)
+            return input;
+        const { contextDir, ...rest } = input;
+        const uploaded = await uploadContext(contextDir, {
+            ...(rest.dockerignore === undefined ? {} : { dockerignore: rest.dockerignore }),
+            ...(options?.signal ? { signal: options.signal } : {}),
+        });
+        const { dockerignore, ...context } = uploaded;
+        return {
+            ...rest,
+            context,
+            ...(dockerignore === undefined ? {} : { dockerignore }),
+        };
+    }
+    /** Build log lines as they are written, until the build ends. Streams when
+     * the server can, and polls when it cannot. */
+    async function followLogs(id, onLog, options = {}) {
+        const { after: from = 0, pollMs = 1000, ...request } = options;
+        let after = from;
+        try {
+            for (;;) {
+                let resume = false;
+                for await (const event of t.events({
+                    method: "GET",
+                    path: `/v1/images/${enc(id)}/logs`,
+                    query: { after, follow: true },
+                    ...request,
+                })) {
+                    if (event.type === "line") {
+                        onLog(event);
+                        after = event.seq;
+                    }
+                    else if (event.type === "done")
+                        return event.image;
+                    else if (event.type === "continue") {
+                        after = event.after;
+                        resume = true;
+                    }
+                    else if (event.type === "error")
+                        throw new Error(event.error.message);
+                }
+                if (!resume)
+                    break;
+            }
+        }
+        catch (error) {
+            if (request.signal?.aborted)
+                throw error;
+        }
+        // A server without streamed logs, or a stream that broke: poll.
+        for (;;) {
+            const page = await logs(id, after, request);
+            for (const line of page.lines)
+                onLog(line);
+            after = page.nextAfter;
+            if (page.done)
+                return get(id, request);
+            const image = await get(id, request);
+            if (image.state !== "queued" && image.state !== "building") {
+                for (const line of (await logs(id, after, request)).lines)
+                    onLog(line);
+                return image;
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+        }
+    }
     return {
-        /** Queue a build and return at once, state "queued". */
-        create: (input, options) => t.json({ method: "POST", path: "/v1/images", body: input, ...options }),
+        /** Queue a build and return at once, state "queued". With `contextDir`,
+         * the folder is packed and its missing chunks uploaded first. */
+        async create(input, options) {
+            return t.json({
+                method: "POST",
+                path: "/v1/images",
+                body: await prepare(input, options),
+                ...options,
+            });
+        },
         /** Build and wait until the image is ready or failed, streaming log lines
          * to `onLog`. Throws when the build fails, with the build's own error. */
         async build(input, options = {}) {
@@ -28,37 +151,73 @@ export function images(t) {
             let image = await t.json({
                 method: "POST",
                 path: "/v1/images",
-                body: input,
+                body: await prepare(input, request),
                 ...request,
             });
-            let after = 0;
-            for (;;) {
-                if (onLog) {
-                    const page = await logs(image.id, after, { signal: request.signal });
-                    for (const line of page.lines)
-                        onLog(line);
-                    after = page.nextAfter;
-                }
-                image = await get(image.id, { signal: request.signal });
-                if (image.state !== "queued" && image.state !== "building")
-                    break;
+            if (onLog)
+                image = await followLogs(image.id, onLog, { ...request, pollMs });
+            while (image.state === "queued" || image.state === "building") {
                 await new Promise((resolve) => setTimeout(resolve, pollMs));
+                image = await get(image.id, { ...(request.signal ? { signal: request.signal } : {}) });
             }
-            if (onLog)
-                for (const line of (await logs(image.id, after)).lines)
-                    onLog(line);
             if (image.state !== "ready")
                 throw new Error(`Image ${image.id} ${image.state}: ${image.error ?? "no error given"}`);
             return image;
         },
+        uploadContext,
         get,
+        resolve,
         logs,
+        followLogs,
         list,
-        delete: (id, options) => t.json({
-            method: "POST",
-            path: `/v1/images/${encodeURIComponent(id)}:delete`,
-            body: {},
-            ...options,
-        }),
+        /** Every version of a name, newest first. */
+        versions: (name, options) => list({ name, limit: 100 }, options),
+        /** Point `tag` of the image's name at this version. */
+        async tag(ref, tag, options) {
+            return t.json({
+                method: "POST",
+                path: `/v1/images/${enc(await idOf(ref, options))}:tag`,
+                body: { tag },
+                ...options,
+            });
+        },
+        async untag(ref, tag, options) {
+            return t.json({
+                method: "POST",
+                path: `/v1/images/${enc(await idOf(ref, options))}:untag`,
+                body: { tag },
+                ...options,
+            });
+        },
+        /** Delete one version (by id, name:tag or name@version) and its tags. */
+        async delete(ref, options) {
+            return t.json({
+                method: "POST",
+                path: `/v1/images/${enc(await idOf(ref, options))}:delete`,
+                body: {},
+                ...options,
+            });
+        },
+        /** Credentials for private registries. The secret is sealed on arrival
+         * and never returned. */
+        registries: {
+            list: async (options) => (await t.json({
+                method: "GET",
+                path: "/v1/images/registries",
+                ...options,
+            })).data,
+            set: (input, options) => t.json({
+                method: "POST",
+                path: "/v1/images/registries",
+                body: input,
+                ...options,
+            }),
+            delete: (registry, options) => t.json({
+                method: "POST",
+                path: "/v1/images/registries:delete",
+                body: { registry },
+                ...options,
+            }),
+        },
     };
 }

package/dist/products/index.d.ts

@@ -6,19 +6,30 @@ import { sandboxInterpreter } from "./interpreter.js";
 import { sandboxNetwork } from "./network.js";
 import { sandboxPreviews } from "./previews.js";
 import { referrals } from "./referrals.js";
+import { audit } from "./audit.js";
+import { switching } from "./switching.js";
 import { limits } from "./limits.js";
 import { volumes } from "./volumes.js";
+import { secrets } from "./secrets.js";
+import { events, otel, sandboxMetrics, webhooks } from "./observability.js";
 export declare const clientExtensions: {
     images: typeof images;
     volumes: typeof volumes;
     referrals: typeof referrals;
     limits: typeof limits;
+    switching: typeof switching;
+    secrets: typeof secrets;
+    webhooks: typeof webhooks;
+    otel: typeof otel;
+    events: typeof events;
+    audit: typeof audit;
 };
 export declare const sandboxExtensions: {
     interpreter: typeof sandboxInterpreter;
     previews: typeof sandboxPreviews;
     network: typeof sandboxNetwork;
     desktop: typeof sandboxDesktop;
+    metrics: typeof sandboxMetrics;
 };
 export type ClientExtensions = {
     readonly [K in keyof typeof clientExtensions]: ReturnType<(typeof clientExtensions)[K]>;

package/dist/products/index.js

@@ -4,8 +4,12 @@ import { sandboxInterpreter } from "./interpreter.js";
 import { sandboxNetwork } from "./network.js";
 import { sandboxPreviews } from "./previews.js";
 import { referrals } from "./referrals.js";
+import { audit } from "./audit.js";
+import { switching } from "./switching.js";
 import { limits } from "./limits.js";
 import { volumes } from "./volumes.js";
+import { secrets } from "./secrets.js";
+import { events, otel, sandboxMetrics, webhooks } from "./observability.js";
 /* HOW A LANE ADDS A PRODUCT TO THE SDK
  *
  * 1. Write src/products/<name>.ts exporting a factory:
@@ -21,12 +25,24 @@ import { volumes } from "./volumes.js";
  * 2. Add ONE line to the matching object below. The Runtime client and every
  *    Sandbox pick it up, typed, with the shared auth, retries, keys and errors.
  */
-export const clientExtensions = { images, volumes, referrals, limits };
+export const clientExtensions = {
+    images,
+    volumes,
+    referrals,
+    limits,
+    switching,
+    secrets,
+    webhooks,
+    otel,
+    events,
+    audit,
+};
 export const sandboxExtensions = {
     interpreter: sandboxInterpreter,
     previews: sandboxPreviews,
     network: sandboxNetwork,
     desktop: sandboxDesktop,
+    metrics: sandboxMetrics,
 };
 /** The factories as plain pairs, for the constructors that install them. */
 export function clientFactories() {