withruntime 0.11.2 → 0.14.0

package/dist/identity.d.ts

@@ -25,3 +25,6 @@ export declare function identityToken(input: {
     lifetimeSeconds?: number;
     signal?: AbortSignal;
 }): Promise<IdentityToken>;
+/** Headers for a call to the website's connect API: this sandbox's identity
+ * token, or none outside a sandbox or when one cannot be had. Never throws. */
+export declare function sandboxIdentityHeaders(): Promise<Record<string, string>>;

package/dist/identity.js

@@ -55,3 +55,30 @@ export async function identityToken(input) {
         });
     return body;
 }
+/** The header and audience the website keys its per-network limits on
+ * (apps/cloud-web/src/lib/limit-key.ts): inside a sandbox, Runtime's own
+ * sign-in calls count against this sandbox, not the address every sandbox on
+ * its host shares. */
+const LIMIT_HEADER = "x-runtime-sandbox-identity";
+const LIMIT_AUDIENCE = "https://withruntime.com/limits";
+let limitToken;
+/** Headers for a call to the website's connect API: this sandbox's identity
+ * token, or none outside a sandbox or when one cannot be had. Never throws. */
+export async function sandboxIdentityHeaders() {
+    if (limitToken && Date.now() < limitToken.until)
+        return { [LIMIT_HEADER]: limitToken.token };
+    if (!(await requestCredentials()))
+        return {};
+    try {
+        const issued = await identityToken({
+            audience: LIMIT_AUDIENCE,
+            signal: AbortSignal.timeout(3_000),
+        });
+        // Renewed a minute before it lapses, so a slow call never carries a dead one.
+        limitToken = { token: issued.token, until: Date.parse(issued.expiresAt) - 60_000 };
+        return { [LIMIT_HEADER]: issued.token };
+    }
+    catch {
+        return {};
+    }
+}

package/dist/images/index.d.ts

@@ -0,0 +1,9 @@
+/** `withruntime/images`: Images alone. Custom images to start sandboxes from.
+ *
+ *   import { images } from "withruntime/images";
+ *   const client = images(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export type * from "../products/images.js";
+/** `runtime.images` of a client made with `options`. */
+export declare function images(options?: RuntimeOptions): Runtime["images"];

package/dist/images/index.js

@@ -0,0 +1,10 @@
+/** `withruntime/images`: Images alone. Custom images to start sandboxes from.
+ *
+ *   import { images } from "withruntime/images";
+ *   const client = images(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+/** `runtime.images` of a client made with `options`. */
+export function images(options) {
+    return new Runtime(options).images;
+}

package/dist/index.d.ts

@@ -16,7 +16,7 @@ export { Page } from "./page.js";
 export type { KeyLimits } from "./products/limits.js";
 export type { AuditEvent, AuditPage } from "./products/audit.js";
 export type { UsageExportQuery, UsageExportRow, UsageExportPage, } from "./products/observability.js";
-export type { JobSecret, Secret, SecretRule, SecretUse, SetSecret } from "./products/secrets.js";
+export type { JobSecret, Secret, SecretRule, SecretScope, SecretUse, SetSecret, } from "./products/secrets.js";
 export { SecretPartlyStoredError } from "./products/secrets.js";
 export type { McpCatalogEntry, McpGateway, McpServerRequest } from "./products/mcp.js";
 export type { FileEvent, FileEventType, WatchHandle, WatchNotice, WatchOptions, } from "./products/watch.js";
@@ -26,6 +26,7 @@ export type { Volume, VolumeBackup, CreateVolume, VolumeAttachment } from "./pro
 export type { CreateJob, Job, JobCompute, JobDefinition, JobLogs, JobRun, JobRunState, JobSchedule, } from "./products/jobs.js";
 export type { CheckedDomain, DnsRecord, Domain, EgressAddress, TcpPort, Tunnel as PrivateTunnel, TunnelPeer, TunnelPeerCreated, SetUpstreamProxy, UpstreamProxy, } from "./products/network-products.js";
 export type { PrivateNetwork } from "./products/private-network.js";
+export type { SignedRequests } from "./products/signed-requests.js";
 export { verifyWebhook, WebhookVerificationError, type MetricPoint, type MetricRange, type OtelExport, type RuntimeEvent, type SandboxMetrics, type Webhook, type WebhookDelivery, type WebhookEventType, } from "./products/observability.js";
 export { Snapshots, type Snapshot, type SnapshotOptions } from "./snapshots.js";
 export { Transport, VERSION, apiOrigin, type RequestOptions, type Call } from "./transport.js";
@@ -73,4 +74,5 @@ export type { RuntimeOptions as ClientOptions };
 export { identityToken, type IdentityToken } from "./identity.js";
 export { openWalletAccount, claimWalletAccount, type OpenedWalletAccount, type WalletClaim, type WalletOptions, } from "./wallet.js";
 export type { Topup } from "./products/billing.js";
+export type { NewKey, MadeKey, ListedKey, KeyUsage } from "./products/api-keys.js";
 export type { SsoConnection, SsoStatus } from "./products/sso.js";

package/dist/ips/index.d.ts

@@ -0,0 +1,9 @@
+/** `withruntime/ips`: IPs alone. Dedicated outbound addresses every sandbox of the account sends from.
+ *
+ *   import { ips } from "withruntime/ips";
+ *   const client = ips(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export type { EgressAddress, NetworkFunding } from "../products/network-products.js";
+/** `runtime.ips` of a client made with `options`. */
+export declare function ips(options?: RuntimeOptions): Runtime["ips"];

package/dist/ips/index.js

@@ -0,0 +1,10 @@
+/** `withruntime/ips`: IPs alone. Dedicated outbound addresses every sandbox of the account sends from.
+ *
+ *   import { ips } from "withruntime/ips";
+ *   const client = ips(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+/** `runtime.ips` of a client made with `options`. */
+export function ips(options) {
+    return new Runtime(options).ips;
+}

package/dist/jobs/index.d.ts

@@ -0,0 +1,9 @@
+/** `withruntime/jobs`: Jobs alone. A command in a fresh sandbox, once or on a schedule.
+ *
+ *   import { jobs } from "withruntime/jobs";
+ *   const client = jobs(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime, type RuntimeOptions } from "../client.js";
+export type * from "../products/jobs.js";
+/** `runtime.jobs` of a client made with `options`. */
+export declare function jobs(options?: RuntimeOptions): Runtime["jobs"];

package/dist/jobs/index.js

@@ -0,0 +1,10 @@
+/** `withruntime/jobs`: Jobs alone. A command in a fresh sandbox, once or on a schedule.
+ *
+ *   import { jobs } from "withruntime/jobs";
+ *   const client = jobs(); // RUNTIME_API_KEY, or this machine's saved connection
+ */
+import { Runtime } from "../client.js";
+/** `runtime.jobs` of a client made with `options`. */
+export function jobs(options) {
+    return new Runtime(options).jobs;
+}

package/dist/keys.js

@@ -5,6 +5,7 @@ import { promisify } from "node:util";
 import { connectionOrigins } from "./credentials.js";
 import { RuntimeError } from "./errors.js";
 import { named } from "./cli-name.js";
+import { sandboxIdentityHeaders } from "./identity.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
@@ -79,6 +80,7 @@ export async function createKey(request, env, options = {}) {
                 headers: {
                     "content-type": "application/json",
                     ...(key ? { authorization: `Bearer ${key}` } : {}),
+                    ...(await sandboxIdentityHeaders()),
                 },
                 body: JSON.stringify(body),
             });

package/dist/login.js

@@ -5,6 +5,7 @@ import { promisify } from "node:util";
 import { me, named } from "./cli-name.js";
 import { Runtime } from "./client.js";
 import { checkBrowserOrigins, connectionOrigins, connectionStore } from "./credentials.js";
+import { sandboxIdentityHeaders } from "./identity.js";
 import { describeRoute, envFetch } from "./proxy.js";
 class ConnectionError extends Error {
     status;
@@ -80,6 +81,7 @@ function connection(env, options) {
                 headers: {
                     "content-type": "application/json",
                     ...(key ? { authorization: `Bearer ${key}` } : {}),
+                    ...(await sandboxIdentityHeaders()),
                 },
                 body: JSON.stringify(body ?? {}),
             });

package/dist/machine.d.ts

@@ -17,6 +17,10 @@ export type MachineInfo = {
     expiresAt: string;
     endsAt?: string | null;
     start?: unknown;
+    /** True when getOrCreate found the name already held. */
+    reused?: boolean;
+    /** True when the answer repeats an earlier call under the same idempotency key. */
+    replayed?: boolean;
 };
 /** Any other call's request options, as the caller gave them: `timeoutMs` is
  * the call's whole deadline, and 0 turns it off. */
@@ -29,7 +33,6 @@ export declare function machinePage<M, Info>(product: MachineProduct, t: Transpo
     data: Info[];
     nextCursor: string | null;
 }, query: Record<string, unknown>, options?: RequestOptions): Page<M>;
-/** One machine: its record and the verbs every machine product shares. */
 export declare abstract class Machine<Info extends MachineInfo, Settings extends object, Deleted> implements AsyncDisposable {
     #private;
     constructor(product: MachineProduct, transport: Transport, info: Info);
@@ -104,8 +107,9 @@ export declare abstract class Machine<Info extends MachineInfo, Settings extends
      * unless autoWake is off); a stopped one ends the loop. It does not keep a
      * Node or Bun process alive by itself. */
     keepAlive(options?: KeepAliveOptions): () => void;
-    /** Days a paused sandbox is kept before deletion (1 to 365). */
-    setRetention(days: number, options?: RequestOptions): Promise<this>;
+    /** Days a paused sandbox is kept before deletion (1 to 365), or `null` to
+     * keep it while your account has credit. */
+    setRetention(days: number | null, options?: RequestOptions): Promise<this>;
     /** Keeps this sandbox's whole machine (files, memory, running processes) as
      * a snapshot to start new sandboxes from. A running sandbox is paused for
      * the moment it takes, then woken; a paused one stays paused. Past
@@ -116,6 +120,10 @@ export declare abstract class Machine<Info extends MachineInfo, Settings extends
     restart(options?: RequestOptions & {
         wait?: boolean;
     }): Promise<this>;
+    /** The end of an `await using` block. A sandbox this client created is
+     * deleted, as E2B's block kills it, unless it was created with
+     * `keep: true`; one it found with `get` or `getOrCreate` is stopped, which
+     * keeps its disk. */
     [Symbol.asyncDispose](): Promise<void>;
     toJSON(): Info;
 }
@@ -133,11 +141,12 @@ export type CreateOptions = RequestOptions & {
 export declare abstract class Machines<M extends Machine<Info, object, Deleted>, Info extends MachineInfo, Create extends {
     name?: string;
     getOrCreate?: boolean;
+    keep?: boolean;
 }, Deleted> {
     #private;
     constructor(product: MachineProduct, t: Transport, wrap: (t: Transport, info: Info) => M);
     /** Creates a sandbox and waits until it is running. Every field is optional:
-     * with none you get the included usage while it lasts, the default region and a
+     * with none you get the free usage while it lasts, the default region and a
      * 2 vCPU / 4 GiB machine from a warm template. `wait: false` returns at once.
      * When every slot without credit or the account's quota is taken, it waits for one to
      * free, up to `waitForCapacityMs` (the client's, two minutes by default). */
@@ -177,4 +186,18 @@ export declare abstract class Machines<M extends Machine<Info, object, Deleted>,
             error: unknown;
         }[];
     }>;
+    /** Deletes for good every sandbox whose labels all match, stopped ones
+     * included, eight at a time, as `delete()` does one: its disk and paused
+     * memory go, its snapshots stay. Says which were deleted and which failed;
+     * one failure does not stop the rest. Needs at least one label, so deleting
+     * everything is never one call. */
+    deleteAll(filter: {
+        labels: Record<string, string>;
+    }, options?: RequestOptions): Promise<{
+        deleted: string[];
+        failed: {
+            id: string;
+            error: unknown;
+        }[];
+    }>;
 }

package/dist/machine.js

@@ -40,6 +40,10 @@ export function machinePage(product, t, wrap, body, query, options = {}) {
     }), query, options));
 }
 /** One machine: its record and the verbs every machine product shares. */
+/** Machines `create` made, which the end of an `await using` block deletes
+ * (Marc, 6 October 2026: deleted unless the code passes `keep: true`). One
+ * from `get`, or an existing one `getOrCreate` found, is only stopped. */
+const deleteAtBlockEnd = new WeakSet();
 export class Machine {
     #info;
     #keepAlive;
@@ -227,7 +231,8 @@ export class Machine {
         void tick();
         return end;
     }
-    /** Days a paused sandbox is kept before deletion (1 to 365). */
+    /** Days a paused sandbox is kept before deletion (1 to 365), or `null` to
+     * keep it while your account has credit. */
     async setRetention(days, options = {}) {
         return this.#lifecycle("retention", { ...options, wait: false }, { days });
     }
@@ -374,8 +379,16 @@ export class Machine {
         }));
         return this;
     }
+    /** The end of an `await using` block. A sandbox this client created is
+     * deleted, as E2B's block kills it, unless it was created with
+     * `keep: true`; one it found with `get` or `getOrCreate` is stopped, which
+     * keeps its disk. */
     async [Symbol.asyncDispose]() {
         this.#keepAlive?.();
+        if (deleteAtBlockEnd.has(this)) {
+            await this.delete().catch(() => undefined);
+            return;
+        }
         if (this.#info.state === "stopped")
             return;
         await this.stop({ wait: false }).catch(() => undefined);
@@ -395,12 +408,12 @@ export class Machines {
         this.#wrap = wrap;
     }
     /** Creates a sandbox and waits until it is running. Every field is optional:
-     * with none you get the included usage while it lasts, the default region and a
+     * with none you get the free usage while it lasts, the default region and a
      * 2 vCPU / 4 GiB machine from a warm template. `wait: false` returns at once.
      * When every slot without credit or the account's quota is taken, it waits for one to
      * free, up to `waitForCapacityMs` (the client's, two minutes by default). */
     async create(input = {}, options = {}) {
-        const { wait, ...body } = input;
+        const { wait, keep, ...body } = input;
         const began = performance.now();
         // Time spent waiting for capacity is the room's, not the deadline's.
         let waited = 0;
@@ -417,6 +430,8 @@ export class Machines {
             },
         });
         const machine = this.#wrap(this.#t, info);
+        if (!keep && !info.reused)
+            deleteAtBlockEnd.add(machine);
         if (wait !== false && info.state !== "running") {
             // One deadline for the whole create: the wait for running gets what the
             // create left of it (1 ms when nothing is left, so it ends as a timeout).
@@ -431,7 +446,9 @@ export class Machines {
             });
             if (machine.state !== "running")
                 throw new RuntimeError({
-                    message: `${this.#product.noun} ${info.id} is ${machine.state}, not running.`,
+                    message: info.replayed
+                        ? `${this.#product.noun} ${info.id} was made by an earlier call with this idempotency key and is ${machine.state} now. It did not fail to start; create again with a new key.`
+                        : `${this.#product.noun} ${info.id} is ${machine.state}, not running.`,
                     code: "start_failed",
                     status: 0,
                     hint: `Read it with runtime.${this.#product.plural}.get(id); stopReason says why.`,
@@ -476,29 +493,44 @@ export class Machines {
      * says which stopped and which failed; one failure does not stop the rest.
      * Needs at least one label, so stopping everything is never one call. */
     async stopAll(filter, options = {}) {
+        const { done, failed } = await this.#eachLabelled("stop", filter, false, options, (m, each) => m.stop(each));
+        return { stopped: done, failed };
+    }
+    /** Deletes for good every sandbox whose labels all match, stopped ones
+     * included, eight at a time, as `delete()` does one: its disk and paused
+     * memory go, its snapshots stay. Says which were deleted and which failed;
+     * one failure does not stop the rest. Needs at least one label, so deleting
+     * everything is never one call. */
+    async deleteAll(filter, options = {}) {
+        const { done, failed } = await this.#eachLabelled("delete", filter, true, options, (m, each) => m.delete(each));
+        return { deleted: done, failed };
+    }
+    /** Lists every match first, then acts on each, eight at a time: acting
+     * while paging would move the pages under the cursor. */
+    async #eachLabelled(verb, filter, includeStopped, options, act) {
         if (!filter?.labels || Object.keys(filter.labels).length === 0) {
             const one = this.#product.noun.toLowerCase();
             throw new RuntimeError({
-                message: "stopAll needs at least one label to match.",
+                message: `${verb}All needs at least one label to match.`,
                 code: "invalid_request",
                 status: 0,
-                hint: `Stop one ${one} with ${one}.stop(), or label the ones to stop together.`,
+                hint: `${verb === "stop" ? "Stop" : "Delete"} one ${one} with ${one}.${verb}(), or label the ones to ${verb} together.`,
             });
         }
-        const live = await (await this.list({ labels: filter.labels, limit: 100 }, options)).toArray(Infinity);
-        // One key cannot name several stops: each stop makes its own.
+        const matches = await (await this.list({ labels: filter.labels, limit: 100, ...(includeStopped ? { includeStopped } : {}) }, options)).toArray(Infinity);
+        // One key cannot name several acts: each makes its own.
         const { idempotencyKey: _one, ...each } = options;
         // In list order, oldest first, whichever finishes first.
-        const errors = new Array(live.length);
+        const errors = new Array(matches.length);
         let next = 0;
         const worker = async () => {
-            for (let at = next++; at < live.length; at = next++)
-                await live[at].stop(each).catch((error) => (errors[at] = error ?? "failed"));
+            for (let at = next++; at < matches.length; at = next++)
+                await act(matches[at], each).catch((error) => (errors[at] = error ?? "failed"));
         };
-        await Promise.all(Array.from({ length: Math.min(8, live.length) }, worker));
+        await Promise.all(Array.from({ length: Math.min(8, matches.length) }, worker));
         return {
-            stopped: live.filter((_, at) => errors[at] === undefined).map((m) => m.id),
-            failed: live.flatMap((m, at) => errors[at] === undefined ? [] : [{ id: m.id, error: errors[at] }]),
+            done: matches.filter((_, at) => errors[at] === undefined).map((m) => m.id),
+            failed: matches.flatMap((m, at) => errors[at] === undefined ? [] : [{ id: m.id, error: errors[at] }]),
         };
     }
 }

package/dist/mcp.js

@@ -1,16 +1,61 @@
 import process from "node:process";
-import { resolveCredential } from "./credentials.js";
+import { checkBrowserOrigins, connectionOrigins, resolveCredential, saveWalletConnection, } from "./credentials.js";
 import { RuntimeError } from "./errors.js";
 import { beginDeviceLogin } from "./login.js";
 import { envFetch } from "./proxy.js";
 import { apiOrigin, defaultBaseUrl, VERSION } from "./transport.js";
-const CONNECT_INSTRUCTIONS = "Runtime is not connected on this machine yet. Call runtime_connect: it gives you a link and a code for the person you work for to approve in their browser (no key to copy). Once they have, call runtime_connect again; Runtime's tools then appear (sandboxes, commands, files and the rest).";
+const CONNECT_INSTRUCTIONS = "Runtime is not connected on this machine yet. Call runtime_connect: it gives you a link and a code for the person you work for to approve in their browser (no key to copy). Once they have, call runtime_connect again; Runtime's tools then appear (sandboxes, commands, files and the rest). No person to approve? Open an account paid in USDC: runtime_wallet_open gives an address and the exact amount to send, and runtime_wallet_claim connects once the payment lands (in a shell, `npx withruntime billing topup 20 --new-account --accept-terms --wait` does the same; then call runtime_connect). There is no free trial on that path.";
 const connectTool = {
     name: "runtime_connect",
     title: "Connect this machine to Runtime",
     description: "Connect Runtime on this machine with a browser approval. The first call returns a link and a code: show them to the person you work for and ask them to approve. Call again after they have; it waits up to 45 seconds for the approval, then Runtime's tools appear.",
     inputSchema: { type: "object", properties: {}, additionalProperties: false },
 };
+const walletOpenTool = {
+    name: "runtime_wallet_open",
+    title: "Open a Runtime account paid with a wallet",
+    description: "For an agent with no person to approve a browser login: opens a Runtime account and its first top-up, paid in USDC on Base, Solana or Tempo. No free trial: the account gets its key only once the payment lands. Answers with an address per network, the exact amount to send and a claim code, shown once: keep it secret, it is the only way to the account. Send exactly that amount from any wallet, then call runtime_wallet_claim with the claim code. Opening an account means agreeing to https://withruntime.com/legal/terms for whoever you act for.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            usd: {
+                type: "number",
+                description: "Dollars of credit to buy: $10 to $500 in an account's first week.",
+            },
+            acceptTerms: {
+                type: "boolean",
+                description: "true agrees to https://withruntime.com/legal/terms. Required.",
+            },
+        },
+        required: ["usd", "acceptTerms"],
+        additionalProperties: false,
+    },
+};
+const walletClaimTool = {
+    name: "runtime_wallet_claim",
+    title: "Connect to a Runtime account opened with a wallet",
+    description: "Once a runtime_wallet_open top-up is paid, saves the account's key on this machine (not shown) and connects; Runtime's tools then appear. Until the payment lands it waits up to 45 seconds and says the top-up's status: call it again.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            claimCode: { type: "string", description: "The claim code runtime_wallet_open gave." },
+        },
+        required: ["claimCode"],
+        additionalProperties: false,
+    },
+};
+/** Where to send a wallet account's first top-up, for an agent to act on. */
+function describeOpened(opened) {
+    const lines = [
+        `Opened a Runtime account. Send exactly ${opened.amount} USDC (for $${opened.amountUsd} of credit), on one of these networks:`,
+        "",
+    ];
+    for (const network of opened.networks)
+        for (const token of network.tokens)
+            lines.push(`- ${network.network}: ${token.currency.toUpperCase()} to ${network.address} (token contract ${token.contract})`);
+    lines.push("", ...(opened.payBy ? [`Send before ${opened.payBy}.`] : []), "A different amount, token or network cannot be matched or returned automatically.", "", `Claim code (shown once, keep it secret): ${opened.claimCode}`, "Once sent, call runtime_wallet_claim with this claim code: it connects when the payment lands, a few minutes after the transfer.", "A person can take the account over at https://withruntime.com/account/claim with the same code.");
+    return lines.join("\n");
+}
 /** Bridges an MCP client that speaks stdio to Runtime's hosted MCP endpoint.
  * Newline-delimited JSON-RPC in, the same out; every message is forwarded as
  * it is, so the server's tools, schemas and `instructions` reach the client
@@ -115,7 +160,73 @@ export async function serveMcp(env = process.env, options = {}) {
         for (const reply of answer.messages)
             write(reply);
     }
-    /** Not connected yet: answer the client here, with one tool that connects. */
+    /** The website's wallet sign-up, at the same origins a login would use. */
+    function wallet() {
+        const origins = connectionOrigins(env);
+        checkBrowserOrigins(origins);
+        const walletOptions = {
+            authUrl: origins.auth,
+            ...(options.fetch ? { fetch: options.fetch } : {}),
+        };
+        return {
+            open: async (input) => (await import("./wallet.js")).openWalletAccount(input, walletOptions),
+            claim: async (code) => (await import("./wallet.js")).claimWalletAccount(code, walletOptions),
+        };
+    }
+    /** A wallet account's claim: once paid, saves its key and connects. Waits up
+     * to 45 seconds for a payment on its way, as runtime_connect does. */
+    async function claimWallet(code) {
+        const until = Date.now() + 45_000;
+        for (;;) {
+            const claim = await wallet().claim(code);
+            if (claim.status === "paid") {
+                // The website issues the key once: a save that fails must not lose it.
+                let unsaved;
+                try {
+                    await saveWalletConnection(env, claim.apiKey, claim.orgId);
+                }
+                catch (error) {
+                    unsaved = error.message;
+                }
+                const said = await connected(claim.apiKey, "a wallet account");
+                return [
+                    unsaved === undefined
+                        ? said
+                        : `${said}\nThe key could not be saved (${unsaved}), and it is issued only once: keep it secret and safe now, as RUNTIME_API_KEY: ${claim.apiKey}`,
+                ];
+            }
+            if (claim.status === "expired" || claim.status === "failed")
+                return [
+                    `The top-up ${claim.status}: nothing was credited. Open a new one with runtime_wallet_open.`,
+                    true,
+                ];
+            // A top-up that never reached Stripe has no address: waiting cannot help.
+            if (claim.topup?.status === "open" && !claim.topup.networks.length)
+                return [claim.next ?? "This top-up has no address to pay to yet.", true];
+            if (Date.now() + 10_000 > until)
+                return [
+                    claim.status === "pending"
+                        ? "The payment has arrived and is being confirmed. Call runtime_wallet_claim again in a minute."
+                        : "Not paid yet. Once the transfer has gone through, call runtime_wallet_claim again with the same claim code.",
+                ];
+            await new Promise((resolve) => setTimeout(resolve, 10_000));
+        }
+    }
+    /** Starts forwarding with this key and tells the client its tools changed. */
+    async function connected(found, agentName) {
+        key = found;
+        pending = undefined;
+        await post(JSON.stringify({
+            jsonrpc: "2.0",
+            id: "runtime-connect",
+            method: "initialize",
+            params: initialize ?? {},
+        }));
+        await post(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }));
+        write({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
+        return `Connected${agentName ? ` as ${agentName}` : ""}. Runtime's tools are available now: list the tools again, then start with runtime_sandboxes_create.`;
+    }
+    /** Not connected yet: answer the client here, with the tools that connect. */
     async function connectMode(message, id) {
         const method = message.method;
         const reply = (result) => write({ jsonrpc: "2.0", id, result });
@@ -133,38 +244,51 @@ export async function serveMcp(env = process.env, options = {}) {
         if (method === "ping")
             return reply({});
         if (method === "tools/list")
-            return reply({ tools: [connectTool] });
+            return reply({ tools: [connectTool, walletOpenTool, walletClaimTool] });
+        const params = (message.params ?? {});
         if (method !== "tools/call" ||
-            message.params?.name !== "runtime_connect")
+            !["runtime_connect", "runtime_wallet_open", "runtime_wallet_claim"].includes(params.name))
             return write(failure(id, "Runtime is not connected yet: call runtime_connect first."));
-        const text = (words) => reply({ content: [{ type: "text", text: words }] });
+        const text = (words, isError = false) => reply({ content: [{ type: "text", text: words }], ...(isError ? { isError } : {}) });
+        if (params.name !== "runtime_connect") {
+            const input = (params.arguments ?? {});
+            try {
+                if (params.name === "runtime_wallet_open") {
+                    if (input.acceptTerms !== true)
+                        return text("Opening an account means agreeing to https://withruntime.com/legal/terms. Call again with acceptTerms: true to agree to them for whoever you act for.", true);
+                    if (typeof input.usd !== "number" || !(input.usd > 0))
+                        return text("Say how many dollars of credit to buy in usd, such as 20.", true);
+                    return text(describeOpened(await wallet().open({ usd: input.usd, acceptTerms: true })));
+                }
+                if (typeof input.claimCode !== "string" || !input.claimCode.trim())
+                    return text("Give the claimCode runtime_wallet_open answered.", true);
+                return text(...(await claimWallet(input.claimCode.trim())));
+            }
+            catch (error) {
+                return text(error instanceof Error ? error.message : String(error), true);
+            }
+        }
         try {
+            // A key saved since this server started (a wallet account's claim, a
+            // login in a shell) connects without a browser.
+            const saved = await resolveCredential(env).catch(() => undefined);
+            if (saved)
+                return text(await connected(saved));
             if (!pending) {
                 pending = await beginDeviceLogin(env, env.RUNTIME_AGENT_NAME ?? "MCP agent", {
                     ...(options.fetch ? { fetch: options.fetch } : {}),
                 });
                 if (!env.RUNTIME_NO_BROWSER && !pending.resumed)
                     await (options.openBrowser ?? openBrowser)(pending.url).catch(() => undefined);
-                return text(`Ask the person you work for to open ${pending.url} (it may already be open in their browser), sign in to Runtime, check that it shows the code ${pending.userCode}, and choose Connect agent. Then call runtime_connect again.`);
+                return text(`Ask the person you work for to open ${pending.url} (it may already be open in their browser), sign in to Runtime, check that it shows the code ${pending.userCode}, and choose Connect agent. Then call runtime_connect again. No person to approve? See this server's instructions to open an account paid in USDC.`);
             }
             const until = Math.min(pending.expiresAt, Date.now() + 45_000);
             while (Date.now() < until) {
                 const outcome = await pending.check();
                 if (outcome === "expired")
                     break;
-                if (outcome !== "pending") {
-                    key = await resolveCredential(env);
-                    pending = undefined;
-                    await post(JSON.stringify({
-                        jsonrpc: "2.0",
-                        id: "runtime-connect",
-                        method: "initialize",
-                        params: initialize ?? {},
-                    }));
-                    await post(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }));
-                    write({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
-                    return text(`Connected as ${outcome.agentName}. Runtime's tools are available now: list the tools again, then start with runtime_sandbox_create.`);
-                }
+                if (outcome !== "pending")
+                    return text(await connected(await resolveCredential(env), outcome.agentName));
                 await new Promise((resolve) => setTimeout(resolve, 3000));
             }
             if (Date.now() >= pending.expiresAt) {