withruntime 0.23.0 → 0.33.1

package/dist/products/ci.d.ts

@@ -0,0 +1,335 @@
+import { Page } from "../page.js";
+import type { RequestOptions, Transport } from "../transport.js";
+export type CiCheckState = "queued" | "running" | "passed" | "failed" | "cancelled";
+export type CiJobState = "queued" | "running" | "passed" | "failed" | "flaky" | "cached" | "cancelled" | "skipped";
+/** A GitHub repository connected for checks. */
+export type CiRepository = {
+    id: string;
+    name: string | null;
+    labels: Record<string, string>;
+    createdAt: number;
+    updatedAt: number;
+    deletedAt: number | null;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+    /** owner/name on GitHub. */
+    repository: string;
+    /** The branch whose pushes are checked as landed. */
+    productionBranch: string;
+    /** Where in the repository its checks are written. */
+    configPath: string;
+    /** The organization's installation of Runtime's GitHub App it is read through. */
+    installation: number;
+    /** GitHub's id for it, learned from its first event. */
+    githubRepositoryId: number | null;
+    /** The GitHub Apps (`<app-slug>[bot]`, lowercase, sorted) whose pushes run
+     * as the code of someone who can write. */
+    trustedApps: string[];
+    state: "connected" | "disconnected";
+};
+export type ConnectCiRepository = {
+    repository: string;
+    productionBranch?: string;
+    configPath?: string;
+    installation?: number;
+    /** Trusted from the connect on, in the same request: a connection trusts
+     * no App until told, so one made again names them here. */
+    trustedApps?: string[];
+    name?: string;
+    labels?: Record<string, string>;
+};
+export type ListCiRepositories = {
+    limit?: number;
+    cursor?: string;
+    name?: string;
+    /** key:value, each one the repository must have. */
+    label?: string[];
+    state?: CiRepository["state"][];
+};
+/** One check: a commit of a connected repository, run as its plan of jobs. */
+export type CiCheck = {
+    id: string;
+    repositoryId: string;
+    /** owner/name on GitHub. */
+    repository: string;
+    commit: string;
+    branch: string | null;
+    event: "push" | "pull_request" | "merge_group" | "rerun";
+    pullRequest: number | null;
+    baseCommit: string | null;
+    /** The GitHub login that pushed, opened or re-ran it. */
+    actor: string | null;
+    /** The repository's writers' code. A fork's pull request is not, and runs
+     * nothing until a writer re-runs it on GitHub. */
+    trusted: boolean;
+    /** Queued for a writer's approval: nothing of it runs. */
+    waiting: boolean;
+    approvedBy: string | null;
+    approvedAt: number | null;
+    /** Writers' code on the production branch, or a merge group. */
+    landed: boolean;
+    state: CiCheckState;
+    /** Why it ended. */
+    reason: string | null;
+    /** How many of its jobs are in each state. */
+    counts: Partial<Record<CiJobState, number>>;
+    /** Where its machines came from and how soon; null until the runner says. */
+    machines: CiMachines | null;
+    createdAt: number;
+    updatedAt: number;
+    startedAt: number | null;
+    endedAt: number | null;
+};
+/** Where a check's machines came from and how soon: woken from its pull
+ * request's own, left paused by its last check (reused), or from the warm
+ * pool (pooled); copies of batch forks (forked, in `forks` calls); made from
+ * the warm snapshot (created); left paused for its next push (kept); the
+ * first machine's, the first ask's whole and the first test's milliseconds;
+ * and its wait in the account's line. */
+export type CiMachines = {
+    reused: number;
+    pooled: number;
+    forked: number;
+    forks: number;
+    created: number;
+    kept: number;
+    firstMs: number | null;
+    readyMs: number | null;
+    firstTestMs: number | null;
+    lineMs: number;
+};
+/** One job of a check's plan: a step, or one part of a step split in parts. */
+export type CiJob = {
+    id: string;
+    checkId: string;
+    repositoryId: string;
+    name: string;
+    part: number;
+    parts: number;
+    needs: string[];
+    command: string;
+    cacheKey: string | null;
+    state: CiJobState;
+    /** The passed job a cached one stands on. */
+    cachedFrom: string | null;
+    exitCode: number | null;
+    reason: string | null;
+    /** The sandboxes it ran in. A failure's may be kept paused: wake it, or
+     * exec in it, with runtime.sandboxes. */
+    sandboxIds: string[];
+    githubCheckRun: number | null;
+    /** A review step's verdict on the commit; null for a command's job. */
+    review: CiReview | null;
+    ms: number | null;
+    createdAt: number;
+    updatedAt: number;
+    startedAt: number | null;
+    endedAt: number | null;
+};
+/** What one finding of a review is about. */
+export type CiReviewKind = "bug" | "missed-case" | "data-at-risk" | "money-at-risk" | "auth-bypass" | "privilege-escalation" | "secret-exposed" | "made-public" | "command-injection" | "manipulation" | "other";
+/** One thing a review found in the change. */
+export type CiReviewFinding = {
+    kind: CiReviewKind;
+    file: string;
+    /** The line in the new file; 0 for the file as a whole. */
+    line: number;
+    /** What is wrong, and what it breaks. */
+    what: string;
+    /** What would put it right. */
+    fix: string;
+};
+/** A review step's verdict on one commit: it passes only with no findings. */
+export type CiReview = {
+    verdict: "pass" | "block";
+    summary: string;
+    findings: CiReviewFinding[];
+    /** Things worth a look that do not block. */
+    notes: {
+        file: string;
+        line: number;
+        what: string;
+    }[];
+    /** The Runtime Agent that reviewed, the account it ran on and its model. */
+    agent: string;
+    account: string;
+    model: string;
+    /** The agent session that gave the verdict. */
+    session: string;
+    /** True when the diff was too long and its end was not read. */
+    cut: boolean;
+};
+/** A check with its jobs, in plan order. */
+export type CiCheckDetail = CiCheck & {
+    jobs: CiJob[];
+};
+/** A job with the tail of its output: at most 256 KiB, the oldest dropped first. */
+export type CiJobDetail = CiJob & {
+    log: string;
+};
+export type ListCiChecks = {
+    repositoryId?: string;
+    state?: CiCheckState[];
+    branch?: string;
+    /** A full commit SHA. */
+    commit?: string;
+    pullRequest?: number;
+    limit?: number;
+    cursor?: string;
+};
+/** One test file of a repository: its recent time and its last 20 runs. */
+export type CiTest = {
+    repositoryId: string;
+    file: string;
+    ms: number;
+    /** Since when its failures do not fail a check; null: they do. */
+    quarantinedSince: number | null;
+    runs: {
+        at: number;
+        check: string;
+        job: string;
+        outcome: "passed" | "failed" | "flaky" | "skipped";
+        ms: number | null;
+        /** false for an approved outsider's run. */
+        writers: boolean;
+    }[];
+    updatedAt: number;
+};
+export type ListCiTests = {
+    quarantined?: boolean;
+    limit?: number;
+    cursor?: string;
+};
+/** One run of a test file: by commit and content key; its first run, its
+ * run again alone after a failure, or a repeat (a new test's 20, a flake's
+ * proof of 100). */
+export type CiTestResult = {
+    file: string;
+    commit: string;
+    key: string;
+    passed: boolean;
+    attempt: "first" | "again" | "repeat";
+    ms: number | null;
+    machine: string | null;
+    checkId: string;
+    jobId: string;
+    /** A run of the production branch's own commit. */
+    main: boolean;
+    message: string | null;
+    at: number;
+};
+export type CiFlakeState = "quarantined" | "gating" | "fixed" | "deleted";
+/** A test that passed and failed on the same inputs, one run main's:
+ * quarantined at once (it still runs and reports, and blocks nothing), or
+ * still gating when the repository protects it; handed to an owner with 48
+ * hours to fix it or delete it with a reason; fixed once 100 runs of a main
+ * commit in parallel forks all pass. */
+export type CiFlake = {
+    id: string;
+    repositoryId: string;
+    file: string;
+    state: CiFlakeState;
+    gates: {
+        why: string;
+        words: string;
+    } | null;
+    proof: {
+        key: string;
+        commit: string;
+        checkId: string;
+        jobId: string;
+        failedIn: string[];
+        passedIn: string[];
+    };
+    again: number;
+    owner: {
+        login: string;
+        from: "codeowners" | "last change" | "handed" | null;
+        pullRequest: number | null;
+        branch: string | null;
+    } | null;
+    since: number;
+    dueAt: number;
+    overdue: boolean;
+    tried: {
+        blob: string;
+        at: number;
+    } | null;
+    proveAskedAt: number | null;
+    deleteReason: string | null;
+    endedAt: number | null;
+    endedCheckId: string | null;
+    updatedAt: number;
+};
+/** A flake with its test file's newest 200 runs and each failure's job,
+ * whose log `jobs.get` reads. */
+export type CiFlakeDetail = CiFlake & {
+    runs: CiTestResult[];
+    failures: {
+        jobId: string;
+        checkId: string;
+        commit: string;
+        message: string | null;
+        at: number;
+    }[];
+};
+export type ListCiFlakes = {
+    repositoryId?: string;
+    state?: CiFlakeState[];
+    limit?: number;
+    cursor?: string;
+};
+/** An owner's say: its proof runs again at main's next commit, a new
+ * owner, or why its test is deleted. */
+export type UpdateCiFlake = {
+    prove?: true;
+    owner?: string;
+    deleteReason?: string;
+};
+export declare function ci(t: Transport): {
+    repositories: {
+        /** Connect a GitHub repository for checks. Only a full key connects
+         * one, since every push runs its code for the whole account. */
+        connect: (input: ConnectCiRepository, options?: RequestOptions) => Promise<CiRepository>;
+        list: (query?: ListCiRepositories, options?: RequestOptions) => Promise<Page<CiRepository>>;
+        find: (idOrName: string, options?: RequestOptions) => Promise<CiRepository | undefined>;
+        /** Replaces the whole list of trusted Apps; `[]` trusts none. */
+        setTrustedApps: (id: string, trustedApps: string[], options?: RequestOptions) => Promise<CiRepository>;
+        /** Adds Apps to those it trusts, keeping the rest: `id` is its id or
+         * owner/name. */
+        trust: (id: string, apps: string[], options?: RequestOptions) => Promise<CiRepository>;
+        /** Takes Apps off those it trusts, keeping the rest. */
+        untrust: (id: string, apps: string[], options?: RequestOptions) => Promise<CiRepository>;
+        /** Disconnect: its checks still going are cancelled; what ended stays. */
+        disconnect: (id: string, options?: RequestOptions) => Promise<CiRepository>;
+    };
+    checks: {
+        /** Checks, newest first. */
+        list: (query?: ListCiChecks, options?: RequestOptions) => Promise<Page<CiCheck>>;
+        /** A check with its jobs in plan order. */
+        get: (id: string, options?: RequestOptions) => Promise<CiCheckDetail>;
+        /** Cancel a queued or running check: its jobs end and its machines
+         * are let go. A check that has ended is answered as it is. */
+        cancel: (id: string, options?: RequestOptions) => Promise<CiCheckDetail>;
+    };
+    jobs: {
+        /** A job with the tail of its log and the sandboxes it ran in. */
+        get: (id: string, options?: RequestOptions) => Promise<CiJobDetail>;
+    };
+    tests: {
+        /** A repository's test files by name, with their quarantine. */
+        list: (repositoryId: string, query?: ListCiTests, options?: RequestOptions) => Promise<Page<CiTest>>;
+    };
+    flakes: {
+        /** Flaky tests, newest first; `state: ["quarantined", "gating"]`
+         * lists the open ones. */
+        list: (query?: ListCiFlakes, options?: RequestOptions) => Promise<Page<CiFlake>>;
+        /** A flaky test with its runs and its failures' jobs. */
+        get: (id: string, options?: RequestOptions) => Promise<CiFlakeDetail>;
+        /** Ask for its 100 proof runs again, hand it on, or say why its test
+         * is deleted. */
+        update: (id: string, change: UpdateCiFlake, options?: RequestOptions) => Promise<CiFlakeDetail>;
+    };
+};

package/dist/products/ci.js

@@ -0,0 +1,108 @@
+/** CI/CD: each push and pull request of a connected GitHub repository is
+ * checked in sandboxes, as the plan its config writes. The runner writes the
+ * checks, their jobs and logs; these read them. In a private beta. */
+import { RuntimeError } from "../errors.js";
+import { Page } from "../page.js";
+export function ci(t) {
+    const at = (base, id) => `${base}/${encodeURIComponent(id)}`;
+    async function paged(path, query, options) {
+        const page = await t.json({ method: "GET", path, query, ...options });
+        return new Page(page.data, page.nextCursor, (cursor) => paged(path, { ...query, cursor }, options));
+    }
+    const setTrustedApps = (id, trustedApps, options) => t.json({
+        method: "POST",
+        path: `${at("/v1/ci/repositories", id)}:update`,
+        body: { trustedApps },
+        ...options,
+    });
+    const listRepositories = (query = {}, options) => paged("/v1/ci/repositories", query, options);
+    /** A connected repository by its id or its owner/name. */
+    const find = async (idOrName, options) => {
+        const all = await (await listRepositories({ limit: 100, state: ["connected"] }, options)).toArray(Infinity);
+        const wanted = idOrName.toLowerCase();
+        return all.find((r) => r.id === wanted || r.repository.toLowerCase() === wanted);
+    };
+    /** As find, or a not_found that says what this key lists. */
+    const needed = async (idOrName, options) => {
+        const repo = await find(idOrName, options);
+        if (repo)
+            return repo;
+        throw new RuntimeError({
+            message: `No connected CI/CD repository ${idOrName} that this key lists.`,
+            code: "not_found",
+            status: 404,
+            hint: "Any key an owner or admin made lists the account's repositories; another key, only those its own agent connected.",
+        });
+    };
+    return {
+        repositories: {
+            /** Connect a GitHub repository for checks. Only a full key connects
+             * one, since every push runs its code for the whole account. */
+            connect: (input, options) => t.json({
+                method: "POST",
+                path: "/v1/ci/repositories",
+                body: input,
+                ...options,
+            }),
+            list: listRepositories,
+            find,
+            /** Replaces the whole list of trusted Apps; `[]` trusts none. */
+            setTrustedApps,
+            /** Adds Apps to those it trusts, keeping the rest: `id` is its id or
+             * owner/name. */
+            trust: async (id, apps, options) => {
+                const repo = await needed(id, options);
+                const all = [...new Set([...repo.trustedApps, ...apps.map((a) => a.toLowerCase())])];
+                return setTrustedApps(repo.id, all, options);
+            },
+            /** Takes Apps off those it trusts, keeping the rest. */
+            untrust: async (id, apps, options) => {
+                const repo = await needed(id, options);
+                const drop = new Set(apps.map((a) => a.toLowerCase()));
+                return setTrustedApps(repo.id, repo.trustedApps.filter((a) => !drop.has(a)), options);
+            },
+            /** Disconnect: its checks still going are cancelled; what ended stays. */
+            disconnect: (id, options) => t.json({
+                method: "DELETE",
+                path: at("/v1/ci/repositories", id),
+                ...options,
+            }),
+        },
+        checks: {
+            /** Checks, newest first. */
+            list: (query = {}, options) => paged("/v1/ci/checks", query, options),
+            /** A check with its jobs in plan order. */
+            get: (id, options) => t.json({ method: "GET", path: at("/v1/ci/checks", id), ...options }),
+            /** Cancel a queued or running check: its jobs end and its machines
+             * are let go. A check that has ended is answered as it is. */
+            cancel: (id, options) => t.json({
+                method: "POST",
+                path: `${at("/v1/ci/checks", id)}:cancel`,
+                ...options,
+            }),
+        },
+        jobs: {
+            /** A job with the tail of its log and the sandboxes it ran in. */
+            get: (id, options) => t.json({ method: "GET", path: at("/v1/ci/jobs", id), ...options }),
+        },
+        tests: {
+            /** A repository's test files by name, with their quarantine. */
+            list: (repositoryId, query = {}, options) => paged("/v1/ci/tests", { ...query, repositoryId }, options),
+        },
+        flakes: {
+            /** Flaky tests, newest first; `state: ["quarantined", "gating"]`
+             * lists the open ones. */
+            list: (query = {}, options) => paged("/v1/ci/flakes", query, options),
+            /** A flaky test with its runs and its failures' jobs. */
+            get: (id, options) => t.json({ method: "GET", path: at("/v1/ci/flakes", id), ...options }),
+            /** Ask for its 100 proof runs again, hand it on, or say why its test
+             * is deleted. */
+            update: (id, change, options) => t.json({
+                method: "POST",
+                path: `${at("/v1/ci/flakes", id)}:update`,
+                body: change,
+                ...options,
+            }),
+        },
+    };
+}

package/dist/products/index.d.ts

@@ -8,12 +8,14 @@ import { sandboxNetwork } from "./network.js";
 import { domains, ips, networks, ports } from "./network-products.js";
 import { sandboxPreviews } from "./previews.js";
 import { referrals } from "./referrals.js";
+import { plans } from "./plans.js";
 import { billing } from "./billing.js";
 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 { reservations } from "./reservations.js";
 import { volumes } from "./volumes.js";
 import { jobs } from "./jobs.js";
 import { sandboxMounts } from "./mounts.js";
@@ -23,15 +25,19 @@ import { mcp, sandboxMcp } from "./mcp.js";
 import { events, otel, sandboxMetrics, webhooks } from "./observability.js";
 import { agents } from "./agents.js";
 import { builds } from "./builds.js";
+import { ci } from "./ci.js";
 import { containers } from "./containers.js";
+import { apps } from "./apps.js";
 export declare const clientExtensions: {
     images: typeof images;
     volumes: typeof volumes;
     jobs: typeof jobs;
     referrals: typeof referrals;
+    plans: typeof plans;
     billing: typeof billing;
     limits: typeof limits;
     keys: typeof keys;
+    reservations: typeof reservations;
     switching: typeof switching;
     secrets: typeof secrets;
     webhooks: typeof webhooks;
@@ -46,7 +52,9 @@ export declare const clientExtensions: {
     networks: typeof networks;
     agents: typeof agents;
     builds: typeof builds;
+    ci: typeof ci;
     containers: typeof containers;
+    apps: typeof apps;
 };
 export declare const sandboxExtensions: {
     interpreter: typeof sandboxInterpreter;

package/dist/products/index.js

@@ -6,12 +6,14 @@ import { sandboxNetwork } from "./network.js";
 import { domains, ips, networks, ports } from "./network-products.js";
 import { sandboxPreviews } from "./previews.js";
 import { referrals } from "./referrals.js";
+import { plans } from "./plans.js";
 import { billing } from "./billing.js";
 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 { reservations } from "./reservations.js";
 import { volumes } from "./volumes.js";
 import { jobs } from "./jobs.js";
 import { sandboxMounts } from "./mounts.js";
@@ -21,7 +23,13 @@ import { mcp, sandboxMcp } from "./mcp.js";
 import { events, otel, sandboxMetrics, webhooks } from "./observability.js";
 import { agents } from "./agents.js";
 import { builds } from "./builds.js";
+import { ci } from "./ci.js";
 import { containers } from "./containers.js";
+// The hub loads this file, so it loads apps.ts and resources.ts too: request
+// builders over Transport whose top level holds only types, functions and
+// imports of files the hub loads, so importing them runs nothing in the hub
+// (agents/hub-sdk-products.test.ts parses every product file the hub loads).
+import { apps } from "./apps.js";
 /* HOW A LANE ADDS A PRODUCT TO THE SDK
  *
  * 1. Write src/products/<name>.ts exporting a factory:
@@ -42,9 +50,11 @@ export const clientExtensions = {
     volumes,
     jobs,
     referrals,
+    plans,
     billing,
     limits,
     keys,
+    reservations,
     switching,
     secrets,
     webhooks,
@@ -60,7 +70,12 @@ export const clientExtensions = {
     agents,
     // Builds (beta): the API answers product_in_beta outside its list.
     builds,
+    // CI/CD (beta): the API answers product_in_beta outside its list.
+    ci,
     containers,
+    // A private beta (PRODUCT_BETAS): an account outside it is refused with
+    // product_in_beta until Apps launches.
+    apps,
 };
 export const sandboxExtensions = {
     interpreter: sandboxInterpreter,