mandala-computer-mcp 0.5.0 → 0.7.0

package/dist/tools/computers.js

@@ -1,8 +1,10 @@
 import { z } from 'zod';
+import { idempotencyHeaders, idempotencyKeyFor } from '../api.js';
 import { CancelledError, ConflictError, isTransientForPoll, MoveRequiredError, NotFoundError, } from '../errors.js';
-import { describe, guarded, incompleteWarning, json, nothingAdmitted, refused, said, unwrapComputer, withErrorMetadata, withoutCredentials, } from '../format.js';
+import { describe, guarded, incompleteWarning, json, nothingAdmitted, operationClause, operationIdOf, refused, said, secretsOnTheirWay, unwrapComputer, withErrorMetadata, withoutCredentials, } from '../format.js';
 import * as P from '../paths.js';
 import { heartbeat, POLL_MS, pollDelay, sleep } from '../poll.js';
+import { buildIdempotencyKeyArg, idempotencyKeyArg, keyedFailure, restartIdempotencyKeyArg, } from './operations.js';
 import { FILES_DIR, secretBindingsSchema } from './secrets.js';
 const idArg = {
     computer_id: z
@@ -10,6 +12,52 @@ const idArg = {
         .optional()
         .describe('Which computer. Defaults to the one selected with use_computer.'),
 };
+/**
+ * A browser proxy as the tools take it: checked for shape only. Which schemes,
+ * hosts and bypass entries are accepted is the platform's rule and is growing,
+ * so a value it refuses comes back as its own 400 sentence rather than a copy
+ * of the rule here that would refuse what it has since learned to accept.
+ * Strict, as a secret binding is: a misspelt `bypass` dropped would send the
+ * browsers through the proxy for every host the caller meant to exempt. The
+ * credentials id is checked here because its form is an id's, not a rule that
+ * grows, and because a setting replaced whole without it loses the credentials.
+ */
+const browserProxySchema = z.strictObject({
+    server: z
+        .string()
+        .refine((v) => v.trim().length > 0, 'server must not be blank')
+        .describe('The proxy URL, e.g. "http://proxy.example.com:3128" or "socks5://127.0.0.1:1080". The platform says which schemes and hosts it accepts, and refuses anything else with a sentence naming why.'),
+    bypass: z
+        .array(z.string().refine((v) => v.trim().length > 0, 'a bypass entry must not be blank'))
+        .optional()
+        .describe('Hosts the browsers reach directly: "example.com", "*.example.com", an address or a range such as "192.0.2.0/24", or "<local>" for names with no dot.'),
+    credentials_secret_id: z
+        .string()
+        .regex(/^csec-[0-9a-f]{16}$/, 'credentials_secret_id must be a secret id: csec- and 16 hex')
+        .nullable()
+        .optional()
+        .describe('For a proxy that asks for a username and password: the id (csec-…, from list_secrets) of a secret whose value is "user:password". The secret must be bound to the computer as a FILE ({secret_id, file} in its secrets, at create or with set_computer_secrets), or the platform refuses the setting; a computer\'s first secrets are bound while it is stopped, and while the proxy names the secret a rebind that drops that binding is refused. Only with an http:// proxy for now. The secret\'s user:password is sent to the proxy named in server, on every request the browsers make. Leaving it out (or null) means no credentials.'),
+});
+const BROWSER_PROXY_ABOUT = "Sends the computer's browsers (Chromium, Chrome, Firefox) through a proxy; nothing else on it uses the proxy, so exec and a terminal go out directly. Linux only.";
+/**
+ * An egress proxy as the tools take it, checked for shape only, as the browser
+ * proxy is. Strict: `bypass` copied over from a browser proxy has no meaning
+ * here, and a proxy that silently covered the hosts a caller meant to leave out
+ * is worse than a refusal naming the key.
+ */
+const egressProxySchema = z.strictObject({
+    server: z
+        .string()
+        .refine((v) => v.trim().length > 0, 'server must not be blank')
+        .describe('The proxy URL with an explicit port: "http://host:port" (a proxy that takes CONNECT), "https://host:port" (the same, spoken to over TLS) or "socks5://host:port". Never a username or password in it — name a secret in credentials_secret_id instead. The platform says which hosts it accepts, and refuses anything else with a sentence naming why.'),
+    credentials_secret_id: z
+        .string()
+        .regex(/^csec-[0-9a-f]{16}$/, 'credentials_secret_id must be a secret id: csec- and 16 hex')
+        .nullable()
+        .optional()
+        .describe('For a proxy that asks for a username and password: the id (csec-…, from list_secrets) of a secret whose value is "user:password". It is NOT bound to the computer and the computer never receives it — do not add it to the computer\'s secrets: the computer\'s host holds the value and signs in to the proxy for it. With http:// and socks5:// the credentials cross the network in clear text, so prefer https:// when naming them. Leaving it out (or null) means no credentials.'),
+});
+const EGRESS_PROXY_ABOUT = "Sends ALL of the computer's outbound TCP through a proxy — exec, terminals, package managers and browsers alike — taken on its host, so nothing inside the computer can opt out. There is no bypass list. It FAILS CLOSED: when the proxy is down or refuses, or its credentials have not reached the host yet (get_computer then says its egress proxy is waiting for credentials), the connection fails and nothing is sent directly. UDP to the internet and ICMP are dropped (QUIC falls back to TCP; NTP and other UDP stop working). DNS lookups are NOT proxied; they go to the platform's resolver. Connections open through the proxy are closed when the setting changes. A host that cannot take it yet — or cannot take an https:// one, or one naming credentials — answers 409 with reason unsupported; one that cannot put it into effect now answers 503, and nothing is changed unless that error says the new setting was stored.";
 /**
  * The answer to a wait the caller ended.
  *
@@ -207,18 +255,18 @@ const finishedMove = (id, m) => {
  */
 const POWER_NEXT = {
     start: ' wait_for_computer with until="guest" is what says when the desktop is answering.',
-    restart: ' wait_for_computer with until="guest" is what says when the desktop is back.',
+    restart: ' wait_for_computer with until="guest" is what says when the desktop is back — and, on a computer with secrets bound, when they have been delivered again, where the platform reports that redelivery. Where it does not, the wait can return a few seconds before they land, so a command that finds a secret unset just after a restart is worth retrying.',
 };
 const POWER_DESCRIPTIONS = {
-    start: 'Boot a computer, or resume a suspended one — a resume restores the saved session, same processes and windows, in about a second.',
-    stop: 'Shut a computer down: the guest is asked, and given time to do it. Discards a saved session if there is one. The disk is kept. `force` pulls the power instead, for a guest that will not come down on its own.',
-    suspend: "Write the guest's RAM to disk and give the host its memory back. A pause, not a stop: start_computer resumes the same session.",
-    restart: 'Reset the computer. Refused while a session is suspended, since it would have to guess whether you meant to resume or discard it.',
+    start: "Boot a computer, or resume a suspended one — a resume restores the saved session, same processes and windows, in about a second. A resumed guest's clock is set to the current time within a few seconds, best effort through its guest agent (one whose agent does not answer keeps the old time until NTP corrects it), and the desktop panel's clock can show the old time for up to a minute after that.",
+    stop: 'Shut a computer down: the guest is asked, and given time to do it. On a suspended computer this discards the saved session, and the next start is a fresh boot. The disk is kept. `force` pulls the power instead, for a guest that will not come down on its own.',
+    suspend: "Write the guest's RAM to disk and give the host its memory back. A pause, not a stop: start_computer resumes the same session. A computer that holds secrets suspends only on a host that seals saved sessions (its memory is encrypted on the way to disk); elsewhere, and while its secrets are still being delivered, it is refused with 409. After a change to its secret bindings that dropped a secret or moved one to another revision while it ran, it cannot be suspended until it restarts, since its memory may still hold the old value.",
+    restart: 'Reset the computer, like the reset button — not a fresh boot, so a change that needs a new machine shape (a resize) needs a stop and a start instead. A suspended computer is refused with 409: start it to resume, or stop it to discard the session. A stopped computer with no secrets bound is started instead; one with secrets bound is refused with 409 while stopped (start it, which delivers them) or while its secrets are being delivered, and otherwise gets its secrets again as it comes back up, a few seconds after it reads running: wait_for_computer with until="guest" waits for them where the platform reports that redelivery, and where it does not, a command run in those seconds can see them unset. A restart issues new desktop credentials and closes open desktop connections, so a get_desktop_url link from before it stops working.',
 };
 export const registerComputers = (server, session, opts) => {
     server.registerTool('list_templates', {
         title: 'List templates',
-        description: 'The base images a computer can be created from — name, OS, and the default CPU, RAM and disk each one implies.',
+        description: 'The base images a computer can be created from — name, OS, and the default CPU, RAM and disk each one implies. For the templates the platform publishes, `name` is what a create takes as `template`; for one you published yourself, pass its `ref` (namespace/name@version) — a short name is not resolved to your own templates and falls back to the default.',
         inputSchema: {},
         annotations: { readOnlyHint: true },
     }, (_args, extra) => guarded(async () => {
@@ -426,15 +474,25 @@ export const registerComputers = (server, session, opts) => {
     // computers somebody else made still has to be able to bring one up, and a
     // stopped computer refuses every other tool here.
     //
-    // Four tools around one request, and stop registered on its own below it:
-    // stop is the only power action with a second argument to take, and folding
-    // an optional one into the loop would leave the other three advertising a
+    // Four tools around one request, with start and stop registered on their
+    // own: each has a second argument to take (resume_only, force), and folding
+    // an optional one into the loop would leave the others advertising a
     // parameter their route does not read.
     const power = (action, computer_id, extra, opts = {}) => guarded(async () => {
         const id = session.resolve(computer_id);
-        const body = await session.api
-            .with(extra.signal)
-            .json('POST', P.computerAction(id, action), { query: opts.query });
+        // Made once, before the request: the key this call is known by if its
+        // answer is lost (OPL-5127).
+        const key = idempotencyKeyFor(opts.key);
+        let body;
+        try {
+            body = await session.api.with(extra.signal).json('POST', P.computerAction(id, action), {
+                query: opts.query,
+                headers: idempotencyHeaders(key),
+            });
+        }
+        catch (err) {
+            return keyedFailure(err, `${action}_computer`, action, key);
+        }
         const c = unwrapComputer(body);
         // What the platform documents for all four is an Ack — `{ok: true}` and
         // nothing else — and that is what it sends. Formatting it as a computer
@@ -447,17 +505,42 @@ export const registerComputers = (server, session, opts) => {
         // one: the test for "is this an Ack" is the absence of an id, and a body
         // with no id is not thereby a body with no `vnc`.
         if (!c.id) {
-            return said(`${action}: ok — ${id}.${POWER_NEXT[action] ?? ''}${opts.note ?? ''}`, withoutCredentials(c));
+            return said(`${action}: ok — ${id}${operationClause(body)}.${POWER_NEXT[action] ?? ''}${opts.note ?? ''}`, withoutCredentials(c));
         }
         session.noteResolution(id, c.resolution);
-        return said(`${action}: ${describe(c)}${opts.note ?? ''}`, withoutCredentials(c));
+        return said(`${action}: ${describe(c)}${operationClause(body)}${opts.note ?? ''}`, withoutCredentials(c));
     });
-    for (const action of ['start', 'suspend', 'restart']) {
+    server.registerTool('start_computer', {
+        title: 'Start a computer',
+        description: POWER_DESCRIPTIONS.start,
+        inputSchema: {
+            ...idArg,
+            resume_only: z
+                .boolean()
+                .optional()
+                .describe('Resume a saved session only, never boot. On a suspended computer it resumes as usual; on a stopped computer with no saved session it SUCCEEDS WITHOUT BOOTING anything, so read get_computer afterwards to see which happened.'),
+            idempotency_key: idempotencyKeyArg,
+        },
+    }, ({ computer_id, resume_only, idempotency_key }, extra) => power('start', computer_id, extra, {
+        key: idempotency_key,
+        // `enum: ['true']` on the platform, as stop's `force` is: omitted
+        // rather than sent as false.
+        query: { resume_only: resume_only ? 'true' : undefined },
+        note: resume_only
+            ? '\n\nresume_only: a stopped computer with no saved session is answered the same way without being booted, so this does not say it is running — get_computer or wait_for_computer says which it is.'
+            : undefined,
+    }));
+    for (const action of ['suspend', 'restart']) {
         server.registerTool(`${action}_computer`, {
             title: `${action[0].toUpperCase()}${action.slice(1)} a computer`,
             description: POWER_DESCRIPTIONS[action],
-            inputSchema: { ...idArg },
-        }, ({ computer_id }, extra) => power(action, computer_id, extra));
+            inputSchema: {
+                ...idArg,
+                // A restart reads running before and after, so its spent-key route
+                // is not "read get_computer" (see resendAfterSpentKey).
+                idempotency_key: action === 'restart' ? restartIdempotencyKeyArg : idempotencyKeyArg,
+            },
+        }, ({ computer_id, idempotency_key }, extra) => power(action, computer_id, extra, { key: idempotency_key }));
     }
     server.registerTool('stop_computer', {
         title: 'Stop a computer',
@@ -468,8 +551,10 @@ export const registerComputers = (server, session, opts) => {
                 .boolean()
                 .optional()
                 .describe('Pull the power instead of asking, the way holding the button in does. Anything the guest had not written to disk is lost, so this is the second attempt and not the first: stop it politely, and reach for `force` when what comes back is a computer still running — a hung X session, a modal "unsaved changes" dialog, or a service that ignores SIGTERM will refuse the polite stop identically every time it is asked.'),
+            idempotency_key: idempotencyKeyArg,
         },
-    }, ({ computer_id, force }, extra) => power('stop', computer_id, extra, {
+    }, ({ computer_id, force, idempotency_key }, extra) => power('stop', computer_id, extra, {
+        key: idempotency_key,
         // The platform's schema for this one is `enum: ['true']` — a string,
         // with no false in it — so an unforced stop omits the parameter rather
         // than sending `force=false`, the way `allow_partial` and
@@ -486,7 +571,7 @@ export const registerComputers = (server, session, opts) => {
     }));
     server.registerTool('update_computer', {
         title: 'Rename or resize a computer',
-        description: "Change a computer's name, its size, or its idle window. The platform refuses these in combination on purpose — a resize needs the computer stopped and the other two do not, so one request cannot honour both without applying half of it. A SUSPENDED computer counts as stopped for a resize, and its saved desktop cannot survive one: the vCPU count and the memory size are part of the saved state, so it is discarded and the next start is a cold boot. Resume it and finish what is open before resizing, or say so before you do it.",
+        description: "Change a computer's name, its size, its idle window, its browser proxy, or its egress proxy. The platform refuses these in combination on purpose — a resize needs the computer stopped and the others do not, so one request cannot honour both without applying half of it. A SUSPENDED computer counts as stopped for a resize, and its saved desktop cannot survive one: the vCPU count and the memory size are part of the saved state, so it is discarded and the next start is a cold boot. Resume it and finish what is open before resizing, or say so before you do it.",
         inputSchema: {
             ...idArg,
             name: z.string().optional(),
@@ -502,21 +587,43 @@ export const registerComputers = (server, session, opts) => {
                 .number()
                 .int()
                 .min(0)
+                .max(10080)
+                .nullable()
+                .optional()
+                .describe("Minutes untouched before the host suspends it, at most 10080 (a week). 0 disables idle suspend and pressure eviction, up to the plan's limit on computers that never suspend (a 402 beyond it). null returns it to the host's own window. Send this on its own."),
+            browser_proxy: browserProxySchema
                 .nullable()
                 .optional()
-                .describe("Minutes untouched before the host suspends it. null follows the host's own window; send this on its own."),
+                .describe(`${BROWSER_PROXY_ABOUT} Replaces the setting whole; null removes it. To change the bypass of the same proxy, start from get_computer's browser_proxy and copy its credentials_secret_id to keep it: leaving it out removes the credentials, and the proxy then refuses the browsers. Do not carry credentials_secret_id to a different server: those credentials belong to the proxy they were set for; send a new server without it unless the user says those credentials are for that server. Send this on its own. A running computer has it within seconds — wait_for_computer with until="guest" before opening a browser that must use it — and a stopped or suspended one is given it as it starts. A browser already open picks it up at its next start.`),
+            egress_proxy: egressProxySchema
+                .nullable()
+                .optional()
+                .describe(`${EGRESS_PROXY_ABOUT} Replaces the setting whole; null removes it and the computer's traffic goes directly again. To change the server of the same proxy, start from the egress proxy get_computer returns and copy its credentials_secret_id to keep it: leaving it out removes the credentials, and the proxy then refuses every connection. Do not carry credentials_secret_id to a different server unless the user says those credentials are for that server. Send this ON ITS OWN — never beside name, a resize, idle_suspend_min or browser_proxy. A running computer has it when the answer arrives; a stopped or suspended one is given it before it starts. After any other 5xx, or no answer, it may or may not have taken effect: call get_computer, and if it does not show the setting you sent, or its egress proxy names credentials and is still waiting for them after a few seconds, send the setting again — with a new idempotency_key, or none, after a 5xx; with the key the answer named after no answer at all.`),
+            idempotency_key: idempotencyKeyArg,
         },
-    }, ({ computer_id, ...fields }, extra) => guarded(async () => {
+    }, ({ computer_id, idempotency_key, ...fields }, extra) => guarded(async () => {
         const id = session.resolve(computer_id);
-        // `null` is meaningful for idle_suspend_min and must survive the filter;
-        // every other absent field is dropped so the platform leaves it alone.
+        // `null` is meaningful for idle_suspend_min, browser_proxy and
+        // egress_proxy and must survive the filter; every other absent field is
+        // dropped so the platform leaves it alone.
         const body = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
+        if (fields.egress_proxy)
+            body.egress_proxy = P.egressProxyBody(fields.egress_proxy);
         if (!Object.keys(body).length) {
-            return refused('Nothing to change — give at least one of name, cpu, ram_mb, disk_gb, idle_suspend_min.');
+            return refused('Nothing to change — give at least one of name, cpu, ram_mb, disk_gb, idle_suspend_min, browser_proxy, egress_proxy.');
+        }
+        // The platform refuses it beside anything else; said here, before a
+        // request, since nothing about it depends on the computer's state.
+        if ('egress_proxy' in body && Object.keys(body).length > 1) {
+            const beside = Object.keys(body).filter((k) => k !== 'egress_proxy');
+            return refused(`egress_proxy must be sent on its own, not beside ${beside.join(', ')}. Send it in an update_computer call of its own. Nothing was changed.`);
         }
+        const key = idempotencyKeyFor(idempotency_key);
         let c;
         try {
-            c = unwrapComputer(await session.api.with(extra.signal).json('PATCH', P.computer(id), { body }));
+            c = unwrapComputer(await session.api
+                .with(extra.signal)
+                .json('PATCH', P.computer(id), { body, headers: idempotencyHeaders(key) }));
         }
         catch (err) {
             // The one refusal on this route that is an offer rather than an end
@@ -526,10 +633,12 @@ export const registerComputers = (server, session, opts) => {
             // knowing about.
             if (err instanceof MoveRequiredError)
                 return moveOffered(id, err);
-            throw err;
+            return keyedFailure(err, 'update_computer', 'change', key);
         }
         session.noteResolution(id, c.resolution);
-        return said(describe(c), withoutCredentials(c));
+        // A resize is recorded as an operation and its answer carries the id;
+        // a rename or a setting change carries none, and the clause is empty.
+        return said(`${describe(c)}${operationClause(c)}`, withoutCredentials(c));
     }));
     server.registerTool('move_computer', {
         title: 'Move a computer to a host that can run a bigger size',
@@ -566,8 +675,9 @@ export const registerComputers = (server, session, opts) => {
                 .max(900)
                 .default(300)
                 .describe('How long to wait for the move to finish before handing back and letting you poll.'),
+            idempotency_key: idempotencyKeyArg,
         },
-    }, ({ computer_id, ram_mb, cpu, disk_gb, timeout_s }, extra) => guarded(async () => {
+    }, ({ computer_id, ram_mb, cpu, disk_gb, timeout_s, idempotency_key }, extra) => guarded(async () => {
         const id = session.resolve(computer_id);
         const body = {
             ram_mb,
@@ -586,7 +696,21 @@ export const registerComputers = (server, session, opts) => {
         // The 202. Its body is the move as it stood the moment it was accepted,
         // and it is kept because it is the only description of this move that
         // does not depend on a later read succeeding.
-        const started = (await api.json('POST', P.computerAction(id, 'move'), { body }));
+        const key = idempotencyKeyFor(idempotency_key);
+        let started;
+        try {
+            started = (await api.json('POST', P.computerAction(id, 'move'), {
+                body,
+                headers: idempotencyHeaders(key),
+            }));
+        }
+        catch (err) {
+            return keyedFailure(err, 'move_computer', 'move', key);
+        }
+        // The rows of GET /moves never carry the operation, so it is carried
+        // onto each one this wait reports.
+        const operation = operationIdOf(started);
+        const tagged = (m) => (operation ? { ...m, operation_id: operation } : m);
         // The keepalive. A disk crossing between two hosts is minutes, and a
         // tool that says nothing for minutes is one a client cancels — see
         // heartbeat, and OPL-4579 for the wait that proved it.
@@ -670,9 +794,9 @@ export const registerComputers = (server, session, opts) => {
                     await sleep(POLL_MS, signal);
                     continue;
                 }
-                last = mine;
+                last = tagged(mine);
                 if (!mine.live)
-                    return finishedMove(id, mine);
+                    return finishedMove(id, last);
                 await beat(`Moving ${id} — ${mine.state}${mine.detail ? `: ${mine.detail}` : ''}`);
                 await sleep(POLL_MS, signal);
             }
@@ -743,13 +867,13 @@ export const registerComputers = (server, session, opts) => {
     }));
     server.registerTool('wait_for_computer', {
         title: 'Wait for a computer to be ready',
-        description: 'Poll until the computer is running, or until the software inside it answers. Use "guest" before exec, files or windows, and before expecting a screenshot to show a desktop rather than a boot screen. Reports progress while it waits, so a client that sends a progressToken and sets resetTimeoutOnProgress can hold the request open; a client that cannot should lower timeout_s and call again rather than watch its own default timeout cancel the wait.',
+        description: 'Poll until the computer is running, or until the software inside it answers. Use "guest" before exec, files or windows, and before expecting a screenshot to show a desktop rather than a boot screen; on a computer with secrets bound, "guest" also waits until they have reached the desktop, so a command run next sees them, on one whose browser proxy is being set or removed it waits until its browsers have the change, and on one whose egress proxy is waiting for its credentials it waits until they arrive, since every connection the computer opens meanwhile is closed. Reports progress while it waits, so a client that sends a progressToken and sets resetTimeoutOnProgress can hold the request open; a client that cannot should lower timeout_s and call again rather than watch its own default timeout cancel the wait.',
         inputSchema: {
             ...idArg,
             until: z
                 .enum(['running', 'guest'])
                 .default('guest')
-                .describe('"running" is the hypervisor reporting the VM up. "guest" is the software inside it answering, which is what exec and a painted desktop actually need.'),
+                .describe('"running" is the hypervisor reporting the VM up. "guest" is the software inside it answering, which is what exec and a painted desktop actually need — and, on a computer with secrets bound, its secrets delivered, on one with a browser proxy, its browsers holding it, and on one with an egress proxy that names credentials, its host holding them.'),
             timeout_s: z.number().int().min(5).max(900).default(180),
         },
         // No readOnlyHint — this is not a pure read, so the hint would overclaim —
@@ -790,6 +914,15 @@ export const registerComputers = (server, session, opts) => {
             // report, and swallowing every transient would end the wait saying only
             // that the status was never seen.
             let blocked;
+            // Which proxy flag, if any, held the last status read, so the give-up
+            // can name it. Only the last read counts, so a wait that ran out on
+            // egress_proxy_pending may have met an ordinary delivery: the give-up
+            // invites another wait first, and names what clears a flag that
+            // persists (a deleted credentials secret, an update whose answer was
+            // lost) as the fallback. browser_proxy_pending is named too, so a
+            // wait held on it does not
+            // end saying only "last seen running".
+            let heldOn;
             while (!untilDeadline.aborted) {
                 // The caller giving up ends the wait. The signal aborts the request
                 // in flight, but nothing about an aborted request stops the next
@@ -834,6 +967,7 @@ export const registerComputers = (server, session, opts) => {
                     continue;
                 }
                 blocked = undefined;
+                heldOn = undefined;
                 session.noteResolution(id, c.resolution);
                 last = c.status ?? 'unknown';
                 // ONE beat per turn, and this is not it when a guest probe is about to
@@ -897,11 +1031,44 @@ export const registerComputers = (server, session, opts) => {
                     return refused(`${id} is suspended, and that state does not clear by itself. start_computer resumes the saved session in about a second.`, withoutCredentials(c));
                 }
                 if (last === 'stopped' && nothingAdmitted(c)) {
-                    return refused(`${id} is stopped. start_computer boots it.`, withoutCredentials(c));
+                    const why = typeof c.secrets_error === 'string' && c.secrets_error.trim()
+                        ? ` Its secrets were not delivered, so the platform stopped it: ${c.secrets_error.trim()}.`
+                        : '';
+                    return refused(`${id} is stopped.${why} start_computer boots it.`, withoutCredentials(c));
                 }
                 if (last === 'running') {
                     if (until === 'running')
                         return said(`Running: ${describe(c)}`, withoutCredentials(c));
+                    // A bound computer runs, and its guest answers, a few seconds
+                    // before its secrets land — and a command run in between sees
+                    // them unset. "guest" is what a caller waits on before exec, so
+                    // it waits for those too. A delivery that fails stops the
+                    // computer, which the stopped refusal below then reports. On a
+                    // platform without secrets_delivering, the receipt says instead.
+                    if (secretsOnTheirWay(c)) {
+                        await beat(`Waiting for ${id} — running; its secrets are still on their way.`);
+                        await sleep(POLL_MS, signal);
+                        continue;
+                    }
+                    // The same gap for a browser proxy: the guest answers before the
+                    // policy is on disk, and a browser opened in between goes out
+                    // directly. Never pending on a computer that is not running, so
+                    // this is the only place it can be waited on.
+                    if (c.browser_proxy_pending === true) {
+                        heldOn = 'browser';
+                        await beat(`Waiting for ${id} — running; its browser proxy is still being applied.`);
+                        await sleep(POLL_MS, signal);
+                        continue;
+                    }
+                    // And for an egress proxy whose credentials have not reached the
+                    // host: the guest answers, but every connection it opens is
+                    // closed until they do, so a command run next cannot reach out.
+                    if (c.egress_proxy_pending === true) {
+                        heldOn = 'egress';
+                        await beat(`Waiting for ${id} — running; waiting for the egress proxy's credentials (egress_proxy_pending), which usually arrive within seconds.`);
+                        await sleep(POLL_MS, signal);
+                        continue;
+                    }
                     // "The guest is up" is not a status the platform reports, so it is
                     // asked rather than waited for: a trivial exec either answers, or
                     // refuses with the 409 that says the agent is not up yet.
@@ -966,9 +1133,21 @@ export const registerComputers = (server, session, opts) => {
             // which is the same shape of answer as a cancellation and not the same
             // as success. The message still says to call again, because the state
             // it was waiting on may yet arrive.
+            //
+            // Behind an egress proxy still waiting for its credentials, the
+            // answer names that state. It still says to call again first: the
+            // flag is read afresh on every poll, so a wait that ran out on it may
+            // have met an ordinary delivery a few seconds long. Only a flag that
+            // persists across waits points at something the caller has to fix,
+            // and even then removing the proxy is the user's call, not a fix: it
+            // sends every connection directly.
             return refused(blocked
                 ? `Gave up after ${timeout_s}s; the platform could not be asked about ${id} for the whole wait — the last attempt said: ${blocked}. Nothing was changed — call again to keep waiting.`
-                : `Gave up after ${timeout_s}s; ${id} was last seen ${last}. Nothing was changed — call again to keep waiting.`);
+                : heldOn === 'egress'
+                    ? `Gave up after ${timeout_s}s; ${id} is running, but its egress proxy's credentials have not reached its host yet (egress_proxy_pending), so every connection it opens is closed until they do. Nothing was changed — call again to keep waiting. If it persists across waits, the secret its egress_proxy.credentials_secret_id names may have been deleted, or an earlier update_computer egress_proxy change may have got a 5xx or no answer: send the egress_proxy setting again with update_computer, naming a secret that exists (list_secrets). Removing the proxy with null is for the user to decide, not a fix: it sends all of the computer's traffic directly.`
+                    : heldOn === 'browser'
+                        ? `Gave up after ${timeout_s}s; ${id} is running, but its browser proxy was still being applied in the guest (browser_proxy_pending), so a browser opened now may not use it. Nothing was changed — call again to keep waiting; if it persists, send the browser_proxy setting again with update_computer.`
+                        : `Gave up after ${timeout_s}s; ${id} was last seen ${last}. Nothing was changed — call again to keep waiting.`);
         }
         finally {
             await beat.stop();
@@ -1131,7 +1310,7 @@ export const registerComputers = (server, session, opts) => {
         return;
     server.registerTool('create_computer', {
         title: 'Create a computer',
-        description: 'Build a new cloud desktop and select it for this session. Creating and running a computer costs money on this account. Continue an image preparation refusal only as its result instructs, retaining all original create arguments, including template, and adding the returned preparation token as an argument. This token is not a create idempotency key. Stop after success; never automatically replay after a lost or ambiguous response.',
+        description: "Build a new cloud desktop and select it for this session. Creating and running a computer costs money on this account. Continue an image preparation refusal only as its result instructs, retaining all original create arguments, including template, and adding the returned preparation token as an argument. This token is not a create idempotency key. Stop after success; never automatically replay after a lost or ambiguous response without the idempotency_key that response names — with it, the same call answers the first one's result instead of building a second computer.",
         inputSchema: {
             name: z.string().optional().describe('A label. The platform picks one if you do not.'),
             size: z
@@ -1141,7 +1320,7 @@ export const registerComputers = (server, session, opts) => {
             template: z
                 .string()
                 .optional()
-                .describe('From list_templates, e.g. "base" for Linux/Xfce. Defaults to the platform default.'),
+                .describe('From list_templates: the short name of a template the platform publishes, e.g. "base" for Linux/Xfce, or a pinned ref (namespace/name@version) — which a template you published must be named by. A short name the host lacks falls back to the default template; a ref that names nothing is refused. Defaults to base.'),
             template_transfer: z
                 .string()
                 .refine((value) => value.trim().length > 0, 'template_transfer must not be blank')
@@ -1158,19 +1337,29 @@ export const registerComputers = (server, session, opts) => {
             resolution: z
                 .string()
                 .optional()
-                .describe('WIDTHxHEIGHT or WIDTHxHEIGHTxDEPTH, 640x480 to 3840x2160, even numbers. Create-time only — the display is a QEMU property and there is no route that changes it later. Defaults to 1280x800x24.'),
+                .describe('WIDTHxHEIGHT or WIDTHxHEIGHTxDEPTH, 640x480 to 3840x2160, even numbers, depth 16, 24 or 32 (24 when left out); anything else is refused. Create-time only — the display is a QEMU property and there is no route that changes it later. Defaults to 1280x800x24.'),
             start: z.boolean().optional().describe('Boot it immediately. True by default.'),
             secrets: secretBindingsSchema(false)
                 .optional()
-                .describe(`Secrets from the account to deliver into the desktop session each time the computer starts, each as an environment variable (\`env\`) or as a file under ${FILES_DIR} (\`file\`). Only ids and names are sent — never a value. Linux only, and only on a template whose image can receive them. get_computer_secrets and set_computer_secrets read and change them later.`),
+                .describe(`Secrets from the account to deliver into the desktop session each time the computer starts, each as an environment variable (\`env\`) or as a file under ${FILES_DIR} (\`file\`). Only ids and names are sent — never a value. Secret ids come from list_secrets (create_secret stores a new one). Linux only, and only on a template whose image can receive them. A value replaced later reaches the running computer live when bound as a file, and as a variable on an image that supports it reaches new shells and exec with desktop: true. get_computer_secrets and set_computer_secrets read and change the bindings later.`),
+            browser_proxy: browserProxySchema
+                .nullable()
+                .optional()
+                .describe(`${BROWSER_PROXY_ABOUT} A create carrying one is always a cold boot. A credentials_secret_id must name a secret bound as a file in this create's secrets. A template you published may carry a default browser proxy, which the computer inherits when this is left out; send another proxy to use that instead, or null to create the computer with none. wait_for_computer with until="guest" waits until its browsers have it; update_computer changes or removes it later.`),
+            egress_proxy: egressProxySchema
+                .optional()
+                .describe(`${EGRESS_PROXY_ABOUT} It is in effect from the first packet the computer sends: until a proxy's credentials reach its host, connections are closed, not sent directly (wait_for_computer with until="guest" waits for them). A create carrying one is never answered from the warm pool, and a clone does not inherit it. A credentials_secret_id naming no secret, or one whose value is not user:password, is refused with 400 before anything is created. update_computer changes or removes it later.`),
+            idempotency_key: buildIdempotencyKeyArg,
         },
         annotations: { destructiveHint: false, openWorldHint: true },
-    }, (args, extra) => guarded(async () => {
+    }, ({ idempotency_key, ...args }, extra) => guarded(async () => {
+        const key = idempotencyKeyFor(idempotency_key);
         let data;
         try {
-            data = await session.api
-                .with(extra.signal)
-                .json('POST', P.COMPUTERS, { body: P.createBody(args) });
+            data = await session.api.with(extra.signal).json('POST', P.COMPUTERS, {
+                body: P.createBody(args),
+                headers: idempotencyHeaders(key),
+            });
         }
         catch (error) {
             const body = error instanceof ConflictError
@@ -1212,7 +1401,7 @@ export const registerComputers = (server, session, opts) => {
                     ],
                 };
             }
-            throw error;
+            return keyedFailure(error, 'create_computer', 'computer', key);
         }
         const c = unwrapComputer(data);
         // Selection and the sentence claiming it are the same decision. Bound
@@ -1229,28 +1418,43 @@ export const registerComputers = (server, session, opts) => {
         // with the reason on it. Saying so plainly is the difference between a
         // model retrying the start and a model creating a second computer.
         const note = c.start_error
-            ? `Created ${describe(c)}, but it did not start: ${c.start_error}\nThe computer exists and is selected. start_computer often works on a second attempt.`
-            : `Created and selected ${describe(c)}.`;
+            ? `Created ${describe(c)}${operationClause(c)}, but it did not start: ${c.start_error}\nThe computer exists and is selected. start_computer often works on a second attempt.`
+            : `Created and selected ${describe(c)}${operationClause(c)}.`;
         return said(args.template_transfer === undefined
             ? note
             : `${note} Stop retrying this create; the template_transfer token is not a create idempotency key.`, withoutCredentials(c));
     }));
     server.registerTool('clone_computer', {
         title: 'Clone a computer',
-        description: 'Copy a computer to a new one — the fork half of snapshot-and-fork. The copy inherits the resolution, because its disk carries a desktop laid out at that size.',
+        description: 'Copy a computer\'s current disk to a new computer — the fork half of snapshot-and-fork. The source is untouched and must be stopped or suspended: a running source is refused with 409. The answer arrives as soon as the copy exists, reading status "building" while its disk is copied — wait for that to finish before starting it. The copy keeps the source\'s size and resolution (its disk carries a desktop laid out at that size), lands stopped, and has no secrets bound.',
         inputSchema: {
             ...idArg,
             name: z.string().optional().describe('A name for the copy.'),
+            idempotency_key: buildIdempotencyKeyArg,
         },
-    }, ({ computer_id, name }, extra) => guarded(async () => {
+    }, ({ computer_id, name, idempotency_key }, extra) => guarded(async () => {
         const id = session.resolve(computer_id);
-        const c = unwrapComputer(await session.api.with(extra.signal).json('POST', P.computerAction(id, 'clone'), {
-            body: name === undefined ? {} : { name },
-        }));
+        const key = idempotencyKeyFor(idempotency_key);
+        let answer;
+        try {
+            answer = await session.api
+                .with(extra.signal)
+                .json('POST', P.computerAction(id, 'clone'), {
+                body: name === undefined ? {} : { name },
+                headers: idempotencyHeaders(key),
+            });
+        }
+        catch (err) {
+            return keyedFailure(err, 'clone_computer', 'copy', key);
+        }
+        const c = unwrapComputer(answer);
         if (!c.id) {
             return refused(`The platform accepted the clone of ${id} but sent no id back, so the copy cannot be identified. It may exist and be billable — list_computers will say. The original stays selected.`, withoutCredentials(c));
         }
-        return said(`Cloned ${id} to ${describe(c)}. The original stays selected; use_computer to switch.`, withoutCredentials(c));
+        return said(`Cloned ${id} to ${describe(c)}${operationClause(c)}. The original stays selected; use_computer to switch.` +
+            (c.operation_id
+                ? ` wait_for_operation with ${c.operation_id} answers when its disk has been copied.`
+                : ''), withoutCredentials(c));
     }));
     server.registerTool('delete_computer', {
         title: 'Delete a computer',
@@ -1270,9 +1474,10 @@ export const registerComputers = (server, session, opts) => {
                 .string()
                 .optional()
                 .describe('The fingerprint from snapshot_holdings. The purge is refused unless it still names the same set, so a capture that finished after you looked cannot be swept up in a decision that was never about it.'),
+            idempotency_key: idempotencyKeyArg,
         },
         annotations: { destructiveHint: true, idempotentHint: true },
-    }, ({ computer_id, delete_snapshots, expect }, extra) => guarded(async () => {
+    }, ({ computer_id, delete_snapshots, expect, idempotency_key }, extra) => guarded(async () => {
         // The platform makes `expect` optional, for callers that cannot read the
         // holdings and so were never shown a set to be held to. An MCP caller
         // can read them — snapshot_holdings is right there — so here it is
@@ -1290,6 +1495,7 @@ export const registerComputers = (server, session, opts) => {
                 'check that the count and size are what you meant to destroy, and pass its fingerprint as `expect`. ' +
                 'Nothing has been deleted.');
         }
+        const key = idempotencyKeyFor(idempotency_key);
         let res;
         try {
             res = await session.api
@@ -1299,6 +1505,7 @@ export const registerComputers = (server, session, opts) => {
                     snapshots: delete_snapshots ? 'delete' : undefined,
                     expect: delete_snapshots ? fingerprint : undefined,
                 },
+                headers: idempotencyHeaders(key),
             });
         }
         catch (err) {
@@ -1337,7 +1544,7 @@ export const registerComputers = (server, session, opts) => {
                     if (absent && !signal.aborted)
                         session.unbind(computer_id);
                 }
-                throw err;
+                return keyedFailure(err, 'delete_computer', 'delete', key);
             }
             session.unbind(computer_id);
             // Reported as a success rather than an error, and deliberately not as
@@ -1366,9 +1573,22 @@ export const registerComputers = (server, session, opts) => {
         const purged = res?.snapshots_deleted === undefined
             ? 'its snapshots'
             : `${res.snapshots_deleted} of its snapshot(s)`;
+        // The delete's operation (kind `delete`), where the platform recorded
+        // one, said like every other lifecycle tool's and kept in the
+        // structured answer so a caller can read it back with get_operation.
+        const op = operationIdOf(res);
+        const done = `Deleted ${computer_id}${operationClause(res)}`;
         return said(delete_snapshots
-            ? `Deleted ${computer_id} and ${purged}.`
-            : `Deleted ${computer_id}. Its disk is gone; any snapshots it had remain, as orphans that can be cloned but not restored.`);
+            ? `${done} and ${purged}.`
+            : `${done}. Its disk is gone; any snapshots it had remain, as orphans that can be cloned but not restored.`, op
+            ? {
+                computer_id,
+                operation_id: op,
+                ...(res?.snapshots_deleted === undefined
+                    ? {}
+                    : { snapshots_deleted: res.snapshots_deleted }),
+            }
+            : undefined);
     }));
 };
 //# sourceMappingURL=computers.js.map