withruntime 0.12.0 → 0.16.0

package/dist/machine.d.ts

@@ -57,18 +57,21 @@ export declare abstract class Machine<Info extends MachineInfo, Settings extends
      * answers the same. */
     delete(options?: RequestOptions): Promise<Deleted>;
     /** Carries on a paused sandbox; for one with a time limit,
-     * `timeoutSeconds` is its new one. */
-    wake(options?: RequestOptions & {
-        wait?: boolean;
+     * `timeoutSeconds` is its new one. A wake stays on its server; when that
+     * server is full for now (`no_capacity`) it waits for room as `create`
+     * does, up to `waitForCapacityMs` (the client's, two minutes by default). */
+    wake(options?: LifecycleOptions & {
         timeoutSeconds?: number;
     }): Promise<this>;
-    /** More time before its time limit ends (at most an hour ahead of now). A
+    /** More time before its time limit ends (at most 24 hours ahead of now). A
      * sandbox with no time limit needs none: the call answers at once and
-     * changes nothing. */
+     * changes nothing. To set the end sooner, or give one with no limit a limit,
+     * `update({ timeoutSeconds })`. */
     extend(seconds: number, options?: RequestOptions): Promise<this>;
-    /** Changes its name, labels, automatic wake, idle pause or persistence;
-     * fields left out stay as they are. `persistent: true` keeps it running
-     * while credit lasts (paid only). */
+    /** Changes its name, labels, automatic wake, idle pause, time limit, end
+     * action or persistence; fields left out stay as they are. `persistent:
+     * true` keeps it running while credit lasts (paid only). `timeoutSeconds`
+     * ends it that long from now, sooner or later than before (0: no limit). */
     update(settings: Settings, options?: RequestOptions): Promise<this>;
     /** Moves it to another image (id, name, name:tag or name@version), keeping
      * its id, /workspace (its home: dotfiles, pip --user and npm -g installs),
@@ -116,10 +119,10 @@ export declare abstract class Machine<Info extends MachineInfo, Settings extends
      * `timeoutMs` (ten minutes unless given) mid-capture, it stays paused and
      * the error names the snapshot. */
     snapshot(options?: SnapshotOptions & RequestOptions): Promise<Snapshot>;
-    /** Starts a stopped persistent sandbox again from its disk (memory is not kept). */
-    restart(options?: RequestOptions & {
-        wait?: boolean;
-    }): Promise<this>;
+    /** Starts a stopped persistent sandbox again from its disk (memory is not
+     * kept), waiting for room on a full server as `wake` does. Its image's
+     * start command runs again, reported in `info.start`. */
+    restart(options?: LifecycleOptions): 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
@@ -137,6 +140,15 @@ export type CreateOptions = RequestOptions & {
      * next try: to tell a person why nothing has happened yet. */
     onCapacityWait?: (refusal: RuntimeError, waitMs: number) => void;
 };
+/** How `wake` and `restart` wait when the sandbox's server is full for now. */
+export type LifecycleOptions = RequestOptions & {
+    wait?: boolean;
+    /** How long to keep retrying `no_capacity` and the like. Default: the
+     * client's, two minutes; 0 fails at once. */
+    waitForCapacityMs?: number;
+    /** Called before each wait, with the refusal and the milliseconds until the next try. */
+    onCapacityWait?: (refusal: RuntimeError, waitMs: number) => void;
+};
 /** A machine product's collection: `runtime.<product>`. */
 export declare abstract class Machines<M extends Machine<Info, object, Deleted>, Info extends MachineInfo, Create extends {
     name?: string;
@@ -146,7 +158,7 @@ export declare abstract class Machines<M extends Machine<Info, object, 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). */
@@ -186,4 +198,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

@@ -41,7 +41,7 @@ export function machinePage(product, t, wrap, body, 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
+ * (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 {
@@ -111,7 +111,9 @@ export class Machine {
         return deleteMachine(this.#product, this.#t, this.id, options);
     }
     /** Carries on a paused sandbox; for one with a time limit,
-     * `timeoutSeconds` is its new one. */
+     * `timeoutSeconds` is its new one. A wake stays on its server; when that
+     * server is full for now (`no_capacity`) it waits for room as `create`
+     * does, up to `waitForCapacityMs` (the client's, two minutes by default). */
     async wake(options = {}) {
         const { timeoutSeconds, ...rest } = options;
         try {
@@ -128,15 +130,17 @@ export class Machine {
             return this;
         }
     }
-    /** More time before its time limit ends (at most an hour ahead of now). A
+    /** More time before its time limit ends (at most 24 hours ahead of now). A
      * sandbox with no time limit needs none: the call answers at once and
-     * changes nothing. */
+     * changes nothing. To set the end sooner, or give one with no limit a limit,
+     * `update({ timeoutSeconds })`. */
     async extend(seconds, options = {}) {
         return this.#lifecycle("extend", { ...options, wait: false }, { seconds });
     }
-    /** Changes its name, labels, automatic wake, idle pause or persistence;
-     * fields left out stay as they are. `persistent: true` keeps it running
-     * while credit lasts (paid only). */
+    /** Changes its name, labels, automatic wake, idle pause, time limit, end
+     * action or persistence; fields left out stay as they are. `persistent:
+     * true` keeps it running while credit lasts (paid only). `timeoutSeconds`
+     * ends it that long from now, sooner or later than before (0: no limit). */
     async update(settings, options = {}) {
         return this.#lifecycle("update", { ...options, wait: false }, { ...settings });
     }
@@ -277,20 +281,26 @@ export class Machine {
         await this.refresh(request());
         // Straight after a fork or a wake the sandbox is still `resuming`, and
         // after a pause still `pausing`: wait for where it is going, or a
-        // snapshot of it is refused as not paused (user lane, 23 September 2026).
+        // snapshot of it is refused as not paused (23 September 2026).
         if (this.state === "resuming" || this.state === "starting")
             await this.waitFor("running", request());
         else if (this.state === "pausing")
             await this.waitFor("paused", request());
         running = this.state === "running";
         // Check before entering cleanup: an abort during refresh must not pause or wake.
-        const pauseOptions = running ? request() : undefined;
+        request();
         let captured;
         let primary;
         let failed = false;
+        /** Whether the server may have left a running source paused: it answered
+         * before the capture was over, or not at all. */
+        let leftPaused = running;
         try {
-            if (running)
-                await this.pause(pauseOptions);
+            // One call: the server pauses a running source for the capture, and
+            // wakes it before it answers a capture that is over (ready or failed).
+            // Pausing, snapshotting and waking it from here took four calls: a
+            // repeat snapshot of a 4 GiB sandbox took 1.96 s at the median against
+            // 1.19 s for this one (15 October 2026).
             let snapshot = await this.#t.json({
                 method: "POST",
                 path: this.#path(":snapshot"),
@@ -300,6 +310,7 @@ export class Machine {
                 ...request(),
             });
             captured = snapshot;
+            leftPaused = running && snapshot.state === "capturing";
             // Prefer: wait is bounded on the server. A capture still in progress
             // must keep its source paused, or the worker refuses it after we wake.
             while (snapshot.state === "capturing") {
@@ -337,9 +348,17 @@ export class Machine {
         }
         // A capture still running needs its source paused: the worker fails one
         // whose source woke. The timeout says so and leaves the wake to the caller.
-        if (running && !late) {
+        if (leftPaused && !late) {
             try {
-                await this.wake();
+                // A call that failed may have been refused before anything paused
+                // (pausable: false, volumes): only a source that is paused is woken.
+                if (failed && captured === undefined)
+                    await this.refresh();
+                if (!failed ||
+                    captured !== undefined ||
+                    this.state === "paused" ||
+                    this.state === "pausing")
+                    await this.wake();
             }
             catch (wakeError) {
                 const recovery = {
@@ -365,17 +384,30 @@ export class Machine {
             throw primary;
         return captured;
     }
-    /** Starts a stopped persistent sandbox again from its disk (memory is not kept). */
+    /** Starts a stopped persistent sandbox again from its disk (memory is not
+     * kept), waiting for room on a full server as `wake` does. Its image's
+     * start command runs again, reported in `info.start`. */
     async restart(options = {}) {
         return this.#lifecycle("restart", options);
     }
     async #lifecycle(verb, options, body = {}) {
+        // A wake or restart refused for room ran nothing and is sent again with
+        // the same key (api.md, "A refusal is not kept"). Until 17 October 2026
+        // only create waited: the product check's wake was refused no_capacity
+        // in 36 ms on 16 October, where a create would have waited for room.
+        const room = verb === "wake" || verb === "restart"
+            ? {
+                waitForCapacityMs: options.waitForCapacityMs ?? this.#t.waitForCapacityMs,
+                ...(options.onCapacityWait ? { onCapacityWait: options.onCapacityWait } : {}),
+            }
+            : {};
         this.#keep(await this.#t.json({
             method: "POST",
             path: this.#path(`:${verb}`),
             body,
             wait: options.wait === false ? 0 : 60,
             ...requestOnly(options),
+            ...room,
         }));
         return this;
     }
@@ -408,7 +440,7 @@ 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). */
@@ -493,29 +525,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,86 @@ 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.
+     * The client read CONNECT_INSTRUCTIONS on its own initialize and will not
+     * read instructions again, so the hosted server's (limits, safe writes,
+     * cleanup, the task) come back in this answer, or an agent's first session
+     * never sees them. Not every client re-lists tools when told; a restart of
+     * this server finds the saved key and serves them at once. */
+    async function connected(found, agentName) {
+        key = found;
+        pending = undefined;
+        const { messages } = 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" });
+        const instructions = messages
+            .map((reply) => reply.result?.instructions)
+            .find((words) => typeof words === "string" && words.length > 0);
+        return [
+            `Connected${agentName ? ` as ${agentName}` : ""}. Runtime's tools are available now: list the tools again, then start with runtime_sandboxes_create. If they do not appear, restart this MCP server (or the client): the connection is saved, so it connects at once.`,
+            ...(instructions
+                ? ["", "Runtime's instructions, to follow from here:", "", instructions]
+                : []),
+        ].join("\n");
+    }
+    /** 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 +257,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_sandboxes_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) {

package/dist/modal/index.d.ts

@@ -47,6 +47,7 @@ export declare class App {
     readonly name?: string | undefined;
     readonly environmentName?: string | undefined;
     constructor(appId: string, name?: string | undefined, environmentName?: string | undefined);
+    readonly info: RefusedAsync;
 }
 export declare class AppService {
     private readonly client;
@@ -90,6 +91,7 @@ export declare class VolumeService {
     fromName(name: string, params?: {
         createIfMissing?: boolean;
         environment?: string;
+        version?: 1 | 2;
     }): Promise<Volume>;
     delete(name: string, params?: {
         allowMissing?: boolean;
@@ -211,6 +213,14 @@ export declare class SandboxSnapshotService {
     constructor(client: ModalClient);
     fromId(snapshotId: string): Promise<SandboxSnapshot>;
 }
+/** `client.environments` (modal 0.11.1): refused, as `environment` options are. */
+export declare class EnvironmentService {
+    readonly fromName: RefusedAsync;
+    readonly objects: Refused;
+}
+export declare const Environment: Refused;
+export declare const EnvironmentAppsService: Refused;
+export declare const EnvironmentObjectsService: Refused;
 export type ModalClientParams = ClientOptions & {
     tokenId?: string;
     tokenSecret?: string;
@@ -237,6 +247,7 @@ export declare class ModalClient {
     readonly cloudBucketMounts: CloudBucketMountService;
     readonly sandboxSnapshots: SandboxSnapshotService;
     readonly proxies: ProxyService;
+    readonly environments: EnvironmentService;
     constructor(options?: ModalClientParams);
     /** Throws once close() was called, as Modal's client does. */
     open(): void;
@@ -292,11 +303,15 @@ export declare class SandboxService {
     create(app: App, image: Image, params?: SandboxCreateParams): Promise<Sandbox>;
     experimentalCreate(app: App, image: Image, params?: SandboxCreateParams): Promise<Sandbox>;
     fromId(id: string): Promise<Sandbox>;
+    /** The running sandbox of that name; with includeTerminated, when none
+     * runs, the one that stopped last (modal 0.11.1). */
     fromName(appName: string, name: string, params?: {
         environment?: string;
+        includeTerminated?: boolean;
     }): Promise<Sandbox>;
     experimentalFromName(appName: string, name: string, params?: {
         environment?: string;
+        includeTerminated?: boolean;
     }): Promise<Sandbox>;
     /** A new sandbox continuing a memory snapshot: its files, memory and
      * running entrypoint, under the snapshot's app and tags. */