withruntime 0.11.2 → 0.14.0

package/dist/products/builds.js

@@ -0,0 +1,227 @@
+/** Builds uses the shared request keys and paged lists.
+ * Unwired until the build planner's production adapter is ready. */
+import { ConnectionError, RuntimeError } from "../errors.js";
+import { Page } from "../page.js";
+import { timeoutSignal } from "../transport.js";
+const terminal = new Set(["succeeded", "failed", "cancelled", "superseded"]);
+function validFailure(value) {
+    if (value === null)
+        return true;
+    if (!value || typeof value !== "object")
+        return false;
+    const step = value;
+    return (typeof step.name === "string" &&
+        (step.exitCode === null || Number.isSafeInteger(step.exitCode)) &&
+        Array.isArray(step.lastLines) &&
+        step.lastLines.length <= 20 &&
+        step.lastLines.every((line) => typeof line === "string"));
+}
+function failure(code, hint, cursor) {
+    return new RuntimeError({ code, status: 0, message: hint, hint, details: { cursor } });
+}
+function validCursor(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= 4096 &&
+        ![...value].some((c) => c.charCodeAt(0) < 0x20 || c.charCodeAt(0) === 0x7f));
+}
+/** Why a wait ended: the signal's own reason, always as an Error. */
+const abortReason = (signal) => signal?.reason instanceof Error ? signal.reason : new Error(String(signal?.reason ?? "aborted"));
+async function* boundedEvents(source, signal) {
+    try {
+        for (;;) {
+            signal?.throwIfAborted();
+            let abort = () => { };
+            let next;
+            try {
+                next = await Promise.race([
+                    source.next(),
+                    new Promise((_, reject) => {
+                        abort = () => reject(abortReason(signal));
+                        signal?.addEventListener("abort", abort, { once: true });
+                        if (signal?.aborted)
+                            abort();
+                    }),
+                ]);
+            }
+            finally {
+                signal?.removeEventListener("abort", abort);
+            }
+            if (next.done)
+                return;
+            yield next.value;
+        }
+    }
+    finally {
+        // An injected transport can ignore abort while next() is pending. It must
+        // not prevent the caller's deadline from resolving; request its cleanup.
+        const closed = source.return(undefined);
+        if (signal?.aborted)
+            void closed.catch(() => { });
+        else
+            await closed;
+    }
+}
+export function builds(t) {
+    const path = (id) => `/v1/builds/${encodeURIComponent(id)}`;
+    const list = async (query = {}, options) => {
+        const page = await t.json({
+            method: "GET",
+            path: "/v1/builds",
+            query,
+            ...options,
+        });
+        return new Page(page.data, page.nextCursor, (cursor) => list({ ...query, cursor }, options));
+    };
+    const listRepositories = async (query = {}, options) => {
+        const page = await t.json({
+            method: "GET",
+            path: "/v1/repositories",
+            query,
+            ...options,
+        });
+        return new Page(page.data, page.nextCursor, (cursor) => listRepositories({ ...query, cursor }, options));
+    };
+    async function* follow(id, query, options = {}) {
+        let cursor = query.cursor ?? null;
+        if ((cursor !== null && !validCursor(cursor)) || query.pageCursor !== undefined)
+            throw failure("invalid_log_options", "Use an opaque cursor for follow; pageCursor is only for search pages.", cursor);
+        const seen = new Set(cursor === null ? [] : [cursor]);
+        let failures = 0;
+        // Bound the entire follow when the caller sets a deadline, including
+        // reconnections. Transport's per-request deadline alone resets on retry.
+        const signal = (options.timeoutMs ?? 120_000) > 0
+            ? AbortSignal.any([
+                ...(options.signal ? [options.signal] : []),
+                timeoutSignal(options.timeoutMs ?? 120_000),
+            ])
+            : options.signal;
+        for (;;) {
+            signal?.throwIfAborted();
+            let continued = false;
+            try {
+                for await (const event of boundedEvents(t.events({
+                    method: "GET",
+                    path: `${path(id)}/logs`,
+                    query: { follow: true, ...(cursor === null ? {} : { cursor }) },
+                    ...options,
+                    ...(signal ? { signal } : {}),
+                }), signal)) {
+                    signal?.throwIfAborted();
+                    if (!event || typeof event !== "object")
+                        throw failure("build_log_invalid", "Retry the log from the last received cursor.", cursor);
+                    if (event.cursor !== null && !validCursor(event.cursor))
+                        throw failure("build_log_invalid", "Retry from the last received cursor.", cursor);
+                    if (event.type === "line") {
+                        if (typeof event.text !== "string" ||
+                            !["stdout", "stderr"].includes(event.stream) ||
+                            !Number.isSafeInteger(event.at) ||
+                            event.at < 0 ||
+                            (event.step !== null && typeof event.step !== "string") ||
+                            !validCursor(event.cursor))
+                            throw failure("build_log_invalid", "Retry the log from the last received cursor.", cursor);
+                        // Opaque physical positions cannot be ordered or incremented.
+                        if (seen.has(event.cursor))
+                            continue;
+                        seen.add(event.cursor);
+                        if (seen.size > 10_000)
+                            seen.delete(seen.values().next().value);
+                        cursor = event.cursor;
+                        failures = 0;
+                        yield event;
+                    }
+                    else if (event.type === "gap") {
+                        if (!validCursor(event.earliestCursor) || (cursor !== null && event.cursor !== cursor))
+                            throw failure("build_log_invalid", "Retry from the last received cursor.", cursor);
+                        cursor = event.cursor;
+                        yield event;
+                    }
+                    else if (event.type === "terminal") {
+                        if ((cursor !== null && event.cursor !== cursor) ||
+                            !terminal.has(event.state) ||
+                            typeof event.reason !== "string" ||
+                            !event.reason ||
+                            !validFailure(event.failingStep) ||
+                            (event.state !== "failed" && event.failingStep !== null))
+                            throw failure("build_log_invalid", "Retry the log from the last received cursor.", cursor);
+                        yield event;
+                        return;
+                    }
+                    else if (event.type === "continue") {
+                        if (cursor !== null && event.cursor !== cursor)
+                            throw failure("build_log_gap", "Resume from details.cursor; report a persistent missing log line.", cursor);
+                        cursor = event.cursor;
+                        continued = true;
+                        break;
+                    }
+                    else if (event.type === "error") {
+                        if (event.cursor !== cursor ||
+                            typeof event.code !== "string" ||
+                            !event.code ||
+                            typeof event.hint !== "string" ||
+                            !event.hint)
+                            throw failure("build_log_invalid", "Retry the log from the last received cursor.", cursor);
+                        throw failure(event.code, event.hint, cursor);
+                    }
+                    else
+                        throw failure("build_log_invalid", "Retry the log from the last received cursor.", cursor);
+                }
+            }
+            catch (error) {
+                signal?.throwIfAborted();
+                if (error instanceof SyntaxError)
+                    throw failure("build_log_invalid", "The log contained invalid JSON; retry from details.cursor.", cursor);
+                // HTTP refusals and protocol errors are actionable, not connection
+                // loss. The transport itself retries retryable HTTP responses.
+                if (!(error instanceof TypeError) && !(error instanceof ConnectionError))
+                    throw error;
+            }
+            if (!continued && ++failures > 3)
+                throw failure("build_log_interrupted", "Reconnect with logs(id, { follow: true, cursor: details.cursor }).", cursor);
+            // Prevent a disconnected service or repeated continuations busy-looping.
+            await new Promise((resolve, reject) => {
+                const done = () => {
+                    signal?.removeEventListener("abort", abort);
+                    resolve();
+                };
+                const timer = setTimeout(done, 50 * Math.max(1, failures));
+                const abort = () => {
+                    clearTimeout(timer);
+                    signal?.removeEventListener("abort", abort);
+                    reject(abortReason(signal));
+                };
+                if (signal?.aborted)
+                    abort();
+                else
+                    signal?.addEventListener("abort", abort, { once: true });
+            });
+        }
+    }
+    function logs(id, query = {}, options) {
+        return query.follow
+            ? follow(id, query, options)
+            : t.json({ method: "GET", path: `${path(id)}/logs`, query, ...options });
+    }
+    return {
+        create: (input, options) => t.json({ method: "POST", path: "/v1/builds", body: input, ...options }),
+        get: (id, options) => t.json({ method: "GET", path: path(id), ...options }),
+        list,
+        logs,
+        cancel: (id, options) => t.json({ method: "POST", path: `${path(id)}:cancel`, ...options }),
+        repositories: {
+            connect: (input, options) => t.json({ method: "POST", path: "/v1/repositories", body: input, ...options }),
+            list: listRepositories,
+            update: (id, change, options) => t.json({
+                method: "POST",
+                path: `/v1/repositories/${encodeURIComponent(id)}:update`,
+                body: change,
+                ...options,
+            }),
+            disconnect: (id, options) => t.json({
+                method: "DELETE",
+                path: `/v1/repositories/${encodeURIComponent(id)}`,
+                ...options,
+            }),
+        },
+    };
+}

package/dist/products/index.d.ts

@@ -5,7 +5,7 @@ import { sandboxDesktop } from "./desktop.js";
 import { sandboxBrowser } from "./browser.js";
 import { sandboxInterpreter } from "./interpreter.js";
 import { sandboxNetwork } from "./network.js";
-import { addresses, domains, network, ports, tunnel } from "./network-products.js";
+import { domains, ips, networks, ports } from "./network-products.js";
 import { sandboxPreviews } from "./previews.js";
 import { referrals } from "./referrals.js";
 import { billing } from "./billing.js";
@@ -13,6 +13,7 @@ import { audit } from "./audit.js";
 import { sso } from "./sso.js";
 import { switching } from "./switching.js";
 import { limits } from "./limits.js";
+import { keys } from "./api-keys.js";
 import { volumes } from "./volumes.js";
 import { jobs } from "./jobs.js";
 import { sandboxMounts } from "./mounts.js";
@@ -27,6 +28,7 @@ export declare const clientExtensions: {
     referrals: typeof referrals;
     billing: typeof billing;
     limits: typeof limits;
+    keys: typeof keys;
     switching: typeof switching;
     secrets: typeof secrets;
     webhooks: typeof webhooks;
@@ -37,19 +39,8 @@ export declare const clientExtensions: {
     sso: typeof sso;
     domains: typeof domains;
     ports: typeof ports;
-    addresses: typeof addresses;
-    tunnel: typeof tunnel;
-    network: typeof network;
-};
-/** Canonical CLI product names share the existing factory instance. Account
- * commands such as secrets, events and billing retain their current names. */
-export declare const clientProductAliases: {
-    readonly image: "images";
-    readonly volume: "volumes";
-    readonly job: "jobs";
-    readonly domain: "domains";
-    readonly port: "ports";
-    readonly address: "addresses";
+    ips: typeof ips;
+    networks: typeof networks;
 };
 export declare const sandboxExtensions: {
     interpreter: typeof sandboxInterpreter;
@@ -64,8 +55,6 @@ export declare const sandboxExtensions: {
 };
 export type ClientExtensions = {
     readonly [K in keyof typeof clientExtensions]: ReturnType<(typeof clientExtensions)[K]>;
-} & {
-    readonly [K in keyof typeof clientProductAliases]: ReturnType<(typeof clientExtensions)[(typeof clientProductAliases)[K]]>;
 };
 export type SandboxExtensions = {
     readonly [K in keyof typeof sandboxExtensions]: ReturnType<(typeof sandboxExtensions)[K]>;

package/dist/products/index.js

@@ -3,7 +3,7 @@ import { sandboxDesktop } from "./desktop.js";
 import { sandboxBrowser } from "./browser.js";
 import { sandboxInterpreter } from "./interpreter.js";
 import { sandboxNetwork } from "./network.js";
-import { addresses, domains, network, ports, tunnel } from "./network-products.js";
+import { domains, ips, networks, ports } from "./network-products.js";
 import { sandboxPreviews } from "./previews.js";
 import { referrals } from "./referrals.js";
 import { billing } from "./billing.js";
@@ -11,6 +11,7 @@ import { audit } from "./audit.js";
 import { sso } from "./sso.js";
 import { switching } from "./switching.js";
 import { limits } from "./limits.js";
+import { keys } from "./api-keys.js";
 import { volumes } from "./volumes.js";
 import { jobs } from "./jobs.js";
 import { sandboxMounts } from "./mounts.js";
@@ -40,6 +41,7 @@ export const clientExtensions = {
     referrals,
     billing,
     limits,
+    keys,
     switching,
     secrets,
     webhooks,
@@ -50,19 +52,8 @@ export const clientExtensions = {
     sso,
     domains,
     ports,
-    addresses,
-    tunnel,
-    network,
-};
-/** Canonical CLI product names share the existing factory instance. Account
- * commands such as secrets, events and billing retain their current names. */
-export const clientProductAliases = {
-    image: "images",
-    volume: "volumes",
-    job: "jobs",
-    domain: "domains",
-    port: "ports",
-    address: "addresses",
+    ips,
+    networks,
 };
 export const sandboxExtensions = {
     interpreter: sandboxInterpreter,

package/dist/products/jobs.d.ts

@@ -1,7 +1,7 @@
 import { Page } from "../page.js";
 import type { RequestOptions, Transport } from "../transport.js";
 /** A run's sandbox. Every field has a default; a run is a sandbox of this
- * size, on the included usage first and then on credit at the sandbox rates. */
+ * size, on the free usage first and then on credit at the sandbox rates. */
 export type JobCompute = {
     region: string;
     vcpu: number;
@@ -53,6 +53,9 @@ export type Job = {
     version: number;
     /** Unix milliseconds, or null when nothing more is scheduled. */
     nextRunAt: number | null;
+    /** When `trigger` asked for a run that has not started yet, in Unix
+     * milliseconds; null otherwise. */
+    runRequestedAt: number | null;
     /** Why the last due run could not start, retried every 30 seconds:
      * `credits` (add credit), `capacity`, `cost_cap` (maxTotalCostMicros or a
      * key's daily limit) or `permission` (the key that made the job lost it). */
@@ -68,6 +71,8 @@ export type JobRun = {
     occurrenceId: string;
     attempt: number;
     scheduledFor: number;
+    /** `manual`: a run `trigger` asked for, and its retries. */
+    trigger: "schedule" | "manual";
     resourceId: string;
     /** `unknown`: the outcome could not be observed (the sandbox stopped under
      * it). It is never retried by itself. */
@@ -159,6 +164,9 @@ export declare const JOB_LIMITS: {
 };
 /** Unix milliseconds from a Date, an ISO time or a number. */
 export declare function jobTime(at: Date | string | number): number;
+/** The API's schedule from what `create` and `reschedule` take: `{ at }`,
+ * `{ cron, timezone? }` or the raw `{ kind: ... }`. */
+export declare function jobSchedule(input: CreateJob["schedule"]): JobSchedule;
 /** The API's job body from `CreateJob`, with every default filled in and the
  * sandbox's size checked before anything is sent. */
 export declare function jobBody(input: CreateJob): Record<string, unknown>;
@@ -168,7 +176,7 @@ export declare function jobBody(input: CreateJob): Record<string, unknown>;
  * request id, and says no retry will change it. */
 export declare function switchedOff(product: string): (error: unknown) => never;
 /** Scheduled jobs: a command run in a fresh sandbox, once or on a cron
- * schedule. Each run is a sandbox, paid for as one: from the included usage first while the run fits the limits without credit, then from credit
+ * schedule. Each run is a sandbox, paid for as one: from the free usage first while the run fits the limits without credit, then from credit
  * at the sandbox rates, through the same holds and spending limits.
  *
  *   const job = await runtime.jobs.create({
@@ -211,4 +219,13 @@ export declare function jobs(transport: Transport): {
     /** End the job for good and stop any run in progress. A run that already
      * finished keeps its result. Cancelling again answers the same job. */
     cancel: (id: string, options?: RequestOptions) => Promise<Job>;
+    /** Run it now, once, beside its schedule, which does not move. A paused
+     * job runs once and stays paused. While a run is starting or going it is
+     * refused with `run_in_progress`; a cancelled or finished job with
+     * `invalid_state`. The run is in `runs` with `trigger: "manual"`. */
+    trigger: (id: string, options?: RequestOptions) => Promise<Job>;
+    /** A new schedule, in any form `create` takes: `{ cron, timezone? }` or
+     * `{ at }`. The next run is the new schedule's next time; a run going
+     * finishes as it began, and a paused job stays paused. */
+    reschedule: (id: string, schedule: CreateJob["schedule"], options?: RequestOptions) => Promise<Job>;
 };

package/dist/products/jobs.js

@@ -47,25 +47,28 @@ export function jobTime(at) {
         throw invalid(`schedule.at must be a time: a Date, an ISO time such as 2026-10-01T03:00:00Z, or Unix milliseconds; got ${String(at)}.`, "schedule.at");
     return ms;
 }
-/** The API's job body from `CreateJob`, with every default filled in and the
- * sandbox's size checked before anything is sent. */
-export function jobBody(input) {
-    const s = input.schedule;
-    let schedule;
+/** The API's schedule from what `create` and `reschedule` take: `{ at }`,
+ * `{ cron, timezone? }` or the raw `{ kind: ... }`. */
+export function jobSchedule(input) {
+    const s = (input ?? {});
     if (s.kind === "once" || (s.kind === undefined && s.at !== undefined))
-        schedule = { kind: "once", at: jobTime(s.at) };
-    else if (s.kind === "cron" || (s.kind === undefined && s.cron !== undefined)) {
+        return { kind: "once", at: jobTime(s.at) };
+    if (s.kind === "cron" || (s.kind === undefined && s.cron !== undefined)) {
         const expression = String(s.expression ?? s.cron).trim();
         if (expression.split(/\s+/).length !== 5)
             throw invalid(`A cron schedule has five fields, minute hour day-of-month month day-of-week, such as "0 3 * * *"; got "${expression}".`, "schedule.cron");
-        schedule = {
+        return {
             kind: "cron",
             expression,
             ...(s.timezone === undefined ? {} : { timezone: s.timezone }),
         };
     }
-    else
-        throw invalid("schedule takes { at } or { cron }.", "schedule");
+    throw invalid("schedule takes { at } or { cron }.", "schedule");
+}
+/** The API's job body from `CreateJob`, with every default filled in and the
+ * sandbox's size checked before anything is sent. */
+export function jobBody(input) {
+    const schedule = jobSchedule(input.schedule);
     const command = Array.isArray(input.command) ? { argv: input.command } : input.command;
     if (!command?.argv?.length)
         throw invalid('command is an argv array such as ["python3", "job.py"].', "command");
@@ -128,7 +131,7 @@ export function switchedOff(product) {
     };
 }
 /** Scheduled jobs: a command run in a fresh sandbox, once or on a cron
- * schedule. Each run is a sandbox, paid for as one: from the included usage first while the run fits the limits without credit, then from credit
+ * schedule. Each run is a sandbox, paid for as one: from the free usage first while the run fits the limits without credit, then from credit
  * at the sandbox rates, through the same holds and spending limits.
  *
  *   const job = await runtime.jobs.create({
@@ -186,5 +189,19 @@ export function jobs(transport) {
         /** End the job for good and stop any run in progress. A run that already
          * finished keeps its result. Cancelling again answers the same job. */
         cancel: (id, options) => verb(id, "cancel", options),
+        /** Run it now, once, beside its schedule, which does not move. A paused
+         * job runs once and stays paused. While a run is starting or going it is
+         * refused with `run_in_progress`; a cancelled or finished job with
+         * `invalid_state`. The run is in `runs` with `trigger: "manual"`. */
+        trigger: (id, options) => verb(id, "trigger", options),
+        /** A new schedule, in any form `create` takes: `{ cron, timezone? }` or
+         * `{ at }`. The next run is the new schedule's next time; a run going
+         * finishes as it began, and a paused job stays paused. */
+        reschedule: (id, schedule, options) => t.json({
+            method: "POST",
+            path: `/v1/jobs/${enc(id)}:reschedule`,
+            body: { schedule: jobSchedule(schedule) },
+            ...options,
+        }),
     };
 }