withruntime 0.4.0 → 0.5.1

package/dist/keys.js

@@ -0,0 +1,196 @@
+import { execFile } from "node:child_process";
+import { generateKeyPair, privateDecrypt } from "node:crypto";
+import { hostname } from "node:os";
+import { promisify } from "node:util";
+import { connectionOrigins } from "./credentials.js";
+import { RuntimeError } from "./errors.js";
+import { named } from "./login.js";
+import { describeRoute, envFetch } from "./proxy.js";
+const KEY = /^rtcloud_([a-f0-9-]{36})_[A-Za-z0-9_-]{43}$/;
+/** How often to ask whether the owner has answered. The website answers
+ * "pending" to anything faster than every 4.5 seconds. */
+const POLL_MS = 5000;
+/** Whole microdollars from a daily limit typed in dollars ("25", "7.5",
+ * "$1,000.10"), read as digits rather than through a float, from $0.01 to
+ * $1,000,000: the keys page's own rule (apps/cloud-web/src/app/account/keys/limit.ts). */
+export function dailyLimitMicros(typed) {
+    const text = typed.trim().replace(/^\$/, "").replace(/,/g, "");
+    const parts = text.match(/^(\d{1,7})(?:\.(\d{1,2}))?$/);
+    const cents = parts ? Number(parts[1]) * 100 + Number((parts[2] ?? "").padEnd(2, "0")) : 0;
+    if (cents < 1 || cents > 100_000_000)
+        throw new RuntimeError({
+            code: "usage",
+            status: 0,
+            message: "--daily-limit is an amount in US dollars from 0.01 to 1000000, such as 25.",
+        });
+    return cents * 10_000;
+}
+function failure(code, message, status = 0, hint) {
+    return new RuntimeError({ code, status, message, ...(hint ? { hint } : {}) });
+}
+async function browser(url) {
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "rundll32" : "xdg-open";
+    const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
+    await promisify(execFile)(command, args, { timeout: 10_000 });
+}
+function interrupted(cancel) {
+    const handler = () => {
+        process.stderr.write("\nCanceling the key request.\n");
+        void cancel()
+            .catch(() => undefined)
+            .finally(() => process.exit(130));
+    };
+    process.once("SIGINT", handler);
+    return () => void process.off("SIGINT", handler);
+}
+/**
+ * Asks for a key, waits for an owner to approve it in the browser, and hands
+ * it back with `confirm`, which tells the website it arrived. Call `confirm`
+ * after the key is shown: it clears the sealed copy the website held for
+ * delivery and turns the owner's page to "Key created".
+ */
+export async function createKey(request, env, options = {}) {
+    const name = request.name.trim();
+    if (!name ||
+        request.name.length > 80 ||
+        [...request.name].some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127))
+        throw failure("usage", "Give the key a name of up to 80 characters.");
+    if (request.access === "read" && request.dailyLimitMicros !== null)
+        throw failure("usage", "A read-only key cannot spend, so it takes no --daily-limit.");
+    const origins = connectionOrigins(env);
+    const fetcher = options.fetch ?? envFetch;
+    const notify = options.notify ?? ((message) => process.stderr.write(`${message}\n`));
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    // A key asked for here is approved on the page this address serves: only
+    // Runtime's own website, or one on this computer for testing.
+    const local = (origin) => ["localhost", "127.0.0.1", "[::1]"].includes(new URL(origin).hostname);
+    if (!(origins.auth === "https://withruntime.com" || local(origins.auth)))
+        throw failure("usage", "Keys are approved at https://withruntime.com, or at a local test address. Check RUNTIME_AUTH_URL.");
+    async function post(path, body, key) {
+        const address = `${origins.auth}/api/connect/${path}`;
+        let response;
+        try {
+            response = await fetcher(address, {
+                method: "POST",
+                redirect: "error",
+                signal: AbortSignal.timeout(20_000),
+                headers: {
+                    "content-type": "application/json",
+                    ...(key ? { authorization: `Bearer ${key}` } : {}),
+                },
+                body: JSON.stringify(body),
+            });
+        }
+        catch (cause) {
+            const route = options.fetch ? { via: "" } : describeRoute(address, cause, env);
+            throw failure("network_error", `Runtime could not be reached at ${origins.auth}${route.via}.`, 0, route.hint);
+        }
+        const result = (await response.json().catch(() => ({})));
+        if (!response.ok)
+            throw failure(response.status === 429 ? "rate_limited" : "key_request_failed", typeof result.error === "string" ? result.error : "Runtime could not take this request.", response.status);
+        return result;
+    }
+    const pair = await promisify(generateKeyPair)("rsa", {
+        modulusLength: 2048,
+        publicKeyEncoding: { type: "spki", format: "pem" },
+        privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    });
+    const started = await post("start", {
+        purpose: "key",
+        agentName: name,
+        access: request.access,
+        dailyLimitMicros: request.dailyLimitMicros,
+        machine: options.machine ?? hostname(),
+        publicKey: pair.publicKey,
+    });
+    if (typeof started.verificationUri !== "string" ||
+        typeof started.deviceCode !== "string" ||
+        !/^[A-Za-z0-9_-]{43}$/.test(started.deviceCode) ||
+        typeof started.userCode !== "string" ||
+        !/^[A-F0-9]{4}(-[A-F0-9]{4}){2}$/.test(started.userCode) ||
+        typeof started.expiresAt !== "number" ||
+        !Number.isFinite(started.expiresAt))
+        throw failure("key_request_failed", "Runtime returned an invalid key request.");
+    const link = new URL(started.verificationUri);
+    if (link.origin !== origins.auth ||
+        link.pathname !== "/connect" ||
+        link.username ||
+        link.password ||
+        link.hash ||
+        [...link.searchParams.keys()].some((key) => key !== "code") ||
+        link.searchParams.get("code") !== started.userCode)
+        throw failure("key_request_failed", "Runtime returned an unexpected approval address.");
+    const deviceCode = started.deviceCode;
+    const expiresAt = Math.min(started.expiresAt, Date.now() + 15 * 60_000);
+    notify(`Approve this key in your browser: ${link.href}\nCheck that the page shows code ${started.userCode}. An account owner chooses Create key.\nWaiting for the approval, up to 15 minutes. Stopping this cancels the request.`);
+    if (options.interactive ?? Boolean(process.stderr.isTTY))
+        await (options.openBrowser ?? browser)(link.href).catch(() => notify("Open the link in a browser where an account owner is signed in."));
+    const stop = (options.onInterrupt ?? interrupted)(async () => {
+        await post("token", { deviceCode, action: "cancel" });
+    });
+    try {
+        // One poll past the expiry, because an approval given in its last seconds
+        // is still delivered.
+        for (;;) {
+            await sleep(POLL_MS);
+            const last = Date.now() >= expiresAt;
+            let result;
+            try {
+                result = await post("token", { deviceCode });
+            }
+            catch (error) {
+                // A dropped connection or a busy website is not an answer: ask again.
+                if (!last &&
+                    error instanceof RuntimeError &&
+                    (error.code === "network_error" || error.status >= 500))
+                    continue;
+                throw error;
+            }
+            if (result.status === "pending") {
+                if (last)
+                    break;
+                continue;
+            }
+            if (result.status === "denied")
+                throw failure("key_request_declined", "The key request was declined. No key was created.");
+            if (result.status === "canceled")
+                throw failure("key_request_canceled", "The key request was canceled. No key was issued.");
+            if (result.status === "expired")
+                break;
+            if (result.status !== "connected" ||
+                typeof result.encryptedKey !== "string" ||
+                typeof result.agentId !== "string" ||
+                typeof result.orgId !== "string")
+                throw failure("key_request_failed", "Runtime returned an invalid key.");
+            let key;
+            try {
+                key = privateDecrypt({ key: pair.privateKey, oaepHash: "sha256" }, Buffer.from(result.encryptedKey, "base64")).toString("utf8");
+            }
+            catch {
+                throw failure("key_request_failed", "Could not open the key Runtime returned. Start again.");
+            }
+            const match = KEY.exec(key);
+            if (!match)
+                throw failure("key_request_failed", "Runtime returned an invalid key.");
+            // From here the key is this command's: an interruption must not revoke it.
+            stop();
+            return {
+                name,
+                access: request.access,
+                dailyLimitMicros: request.dailyLimitMicros,
+                key,
+                keyId: match[1],
+                agentId: result.agentId,
+                orgId: result.orgId,
+                expires: null,
+                confirm: async () => {
+                    await post("confirm", {}, key).catch(() => notify("The key works, but Runtime did not hear that it arrived. The approval page may still say Approved."));
+                },
+            };
+        }
+    }
+    finally {
+        stop();
+    }
+    throw failure("key_request_expired", named("The key request expired before it was approved. Run `runtime keys create` again."));
+}

package/dist/login.js

@@ -1,5 +1,6 @@
 import { execFile } from "node:child_process";
 import { generateKeyPair, privateDecrypt } from "node:crypto";
+import { hostname } from "node:os";
 import { promisify } from "node:util";
 import { Runtime } from "./index.js";
 import { connectionOrigins, connectionStore } from "./credentials.js";
@@ -163,9 +164,14 @@ export async function authenticationCommand(args, env, options = {}) {
     let noBrowser = false;
     let withKey = false;
     let wait;
+    // `runtime account add`: connect another account even though this machine
+    // is connected already; the one in use is kept among the saved accounts.
+    let another = false;
     for (let i = 0; i < rest.length; i++) {
         if (rest[i] === "--no-browser")
             noBrowser = true;
+        else if (rest[i] === "--another-account")
+            another = true;
         else if (rest[i] === "--with-key")
             withKey = true;
         else if (rest[i] === "--wait")
@@ -212,7 +218,7 @@ export async function authenticationCommand(args, env, options = {}) {
         }).usage();
         return { connected: true, source: "environment" };
     }
-    const saved = await store.read();
+    const saved = another ? null : await store.read();
     if (saved) {
         try {
             await request("confirm", undefined, saved.key);
@@ -277,7 +283,13 @@ export async function beginDeviceLogin(env, agentName, options = {}) {
             publicKeyEncoding: { type: "spki", format: "pem" },
             privateKeyEncoding: { type: "pkcs8", format: "pem" },
         });
-        const started = await request("start", { agentName, publicKey: pair.publicKey });
+        // The computer's own name goes to the approval page beside the code, so an
+        // owner can tell this request from a link somebody else started.
+        const started = await request("start", {
+            agentName,
+            publicKey: pair.publicKey,
+            machine: hostname(),
+        });
         if (typeof started.verificationUri !== "string" ||
             typeof started.deviceCode !== "string" ||
             !/^[A-Za-z0-9_-]{43}$/.test(started.deviceCode) ||

package/dist/openai-agents/index.d.ts

@@ -0,0 +1,132 @@
+/** Runtime Cloud sandboxes for the OpenAI Agents SDK (JavaScript).
+ *
+ * `RuntimeCloudSandboxClient` is a sandbox client for `SandboxAgent`: the
+ * agent's shell (with PTY sessions and stdin), file edits, image views and
+ * manifest all live in one Runtime Cloud microVM, and the agent definition
+ * does not change:
+ *
+ *   import { run } from "@openai/agents";
+ *   import { SandboxAgent } from "@openai/agents/sandbox";
+ *   import { RuntimeCloudSandboxClient } from "withruntime/openai-agents";
+ *
+ *   const agent = new SandboxAgent({ name: "Coder", instructions: "Fix the failing test." });
+ *   await run(agent, "Go.", {
+ *     sandbox: { client: new RuntimeCloudSandboxClient({ create: { funding: "trial" } }) },
+ *   });
+ *
+ * Needs `@openai/agents` 0.18 or newer beside this package. The key comes from
+ * RUNTIME_API_KEY or this machine's `runtime login`. Plain function tools for
+ * an ordinary `Agent` are `runtimeFunctionTools(sandbox)`. */
+import { type Editor } from "@openai/agents-core";
+import type { Manifest } from "@openai/agents-core/sandbox";
+import { type ExecCommandArgs, type ExposedPortEndpoint, type ListDirectoryArgs, type MaterializeEntryArgs, type ReadFileArgs, type SandboxClient, type SandboxClientCreateArgs, type SandboxDirectoryEntry, type SandboxExecResult, type SandboxSession, type SandboxSessionState, type ViewImageArgs, type WorkspaceArchiveData, type WriteStdinArgs } from "@openai/agents-core/sandbox";
+import { Runtime } from "../client.js";
+import type { Sandbox } from "../sandbox.js";
+import { type SandboxToolOptions } from "../tools/index.js";
+import type { CreateSandbox } from "../types.js";
+export declare const BACKEND_ID = "runtime_cloud";
+export type RuntimeCloudSandboxClientOptions = {
+    /** How to create the sandbox: every field `runtime.sandboxes.create` takes
+     * (funding, image, snapshot, vcpu, memoryMiB, network...). */
+    create?: CreateSandbox;
+    /** Set for every command, under the manifest's own environment. */
+    env?: Record<string, string>;
+    /** Ports `resolveExposedPort` may share as Runtime previews. */
+    exposedPorts?: number[];
+    /** Private previews carry their token in the endpoint's query. Default private. */
+    previewVisibility?: "private" | "public";
+    /** Pause instead of stopping at the end, so `resume` wakes the same machine. */
+    pauseOnExit?: boolean;
+    /** Longest a command may run. Default one hour; at most 24 hours. */
+    execTimeoutMs?: number;
+};
+export interface RuntimeCloudSandboxSessionState extends SandboxSessionState {
+    sandboxId: string;
+    create: CreateSandbox;
+    environment: Record<string, string>;
+    configuredExposedPorts?: number[];
+    previewVisibility: "private" | "public";
+    pauseOnExit: boolean;
+    execTimeoutMs: number;
+}
+/** One Runtime Cloud sandbox as an Agents SDK sandbox session. */
+export declare class RuntimeCloudSandboxSession implements SandboxSession<RuntimeCloudSandboxSessionState> {
+    #private;
+    readonly state: RuntimeCloudSandboxSessionState;
+    constructor(args: {
+        state: RuntimeCloudSandboxSessionState;
+        runtime: Runtime;
+        sandbox?: Sandbox;
+    });
+    /** The Runtime sandbox, created (or woken) on first use. */
+    sandbox(): Promise<Sandbox>;
+    /** An absolute path inside the workspace root or a granted path; anything else is refused. */
+    resolvePath(path: string): string;
+    supportsPty(): boolean;
+    exec(args: ExecCommandArgs): Promise<SandboxExecResult>;
+    /** Starts the command and returns its output so far: finished, with its exit
+     * code, or still running, with a session id for `writeStdin`. */
+    execCommand(args: ExecCommandArgs): Promise<string>;
+    writeStdin(args: WriteStdinArgs): Promise<string>;
+    readFile(args: ReadFileArgs): Promise<Uint8Array>;
+    viewImage(args: ViewImageArgs): Promise<{
+        type: "image";
+        providerData?: Record<string, any> | undefined;
+        image?: string | {
+            data: string | Uint8Array<ArrayBuffer>;
+            mediaType?: string | undefined;
+        } | {
+            url: string;
+        } | {
+            fileId: string;
+        } | undefined;
+        detail?: "auto" | "high" | "low" | (string & {}) | undefined;
+    }>;
+    listDir(args: ListDirectoryArgs): Promise<SandboxDirectoryEntry[]>;
+    pathExists(path: string, runAs?: string): Promise<boolean>;
+    directoryExists(path: string, runAs?: string): Promise<boolean>;
+    createEditor(runAs?: string): Editor;
+    prepareWorkspaceRoot(): Promise<void>;
+    applyManifest(manifest: Manifest, runAs?: string): Promise<void>;
+    materializeEntry(args: MaterializeEntryArgs): Promise<void>;
+    resolveExposedPort(port: number): Promise<ExposedPortEndpoint>;
+    persistWorkspace(): Promise<Uint8Array>;
+    hydrateWorkspace(data: WorkspaceArchiveData): Promise<void>;
+    running(): Promise<boolean>;
+    /** Ends every process the agent started. */
+    shutdown(): Promise<void>;
+    /** Stops the sandbox, or pauses it with `pauseOnExit`. */
+    delete(): Promise<void>;
+    close(): Promise<void>;
+}
+/** Creates, resumes and deletes Runtime Cloud sandbox sessions. */
+export declare class RuntimeCloudSandboxClient implements SandboxClient<RuntimeCloudSandboxClientOptions, RuntimeCloudSandboxSessionState> {
+    #private;
+    readonly backendId = "runtime_cloud";
+    readonly runtime: Runtime;
+    constructor(options?: RuntimeCloudSandboxClientOptions & {
+        runtime?: Runtime;
+    });
+    create(args?: SandboxClientCreateArgs<RuntimeCloudSandboxClientOptions> | Manifest, manifestOptions?: RuntimeCloudSandboxClientOptions): Promise<RuntimeCloudSandboxSession>;
+    /** Reattaches to the same sandbox while it runs (waking it when paused);
+     * otherwise starts a new one and applies the manifest again. */
+    resume(state: RuntimeCloudSandboxSessionState): Promise<RuntimeCloudSandboxSession>;
+    delete(state: RuntimeCloudSandboxSessionState): Promise<void>;
+    canPersistOwnedSessionState(state: RuntimeCloudSandboxSessionState): boolean;
+    /** The state without secrets: the environment is materialized again on the way back. */
+    serializeSessionState(state: RuntimeCloudSandboxSessionState): Promise<Record<string, unknown>>;
+    deserializeSessionState(record: Record<string, unknown>): Promise<RuntimeCloudSandboxSessionState>;
+}
+/** The four sandbox tools as function tools for an ordinary `Agent`
+ * (no SandboxAgent): runtime_exec, runtime_read_file, runtime_write_file and
+ * runtime_list_files, bound to `sandbox`. */
+export declare function runtimeFunctionTools(sandbox: Sandbox, options?: SandboxToolOptions): import("@openai/agents-core").FunctionTool<unknown, {
+    type: "object";
+    properties: Record<string, {
+        type: "string" | "integer";
+        description: string;
+        minimum?: number;
+    }>;
+    required: string[];
+    additionalProperties: true;
+}, string>[];