mandala-computer-mcp 0.1.1 → 0.1.2

package/README.md

@@ -19,7 +19,24 @@ the way you would treat a password.
 Node 20.3 or newer. There is nothing else to install: `npx` fetches the server
 the first time a client starts it.
 
-**Claude Code**
+**Claude Code** — as a plugin, which installs the server and a skill together:
+
+```sh
+export MANDALA_API_KEY=com_…       # in the shell Claude Code starts from
+/plugin marketplace add mandalacomputer/mcp
+/plugin install mandala-computer@mandala
+```
+
+The skill — [`plugin/skills/mandala-computer/SKILL.md`](plugin/skills/mandala-computer/SKILL.md)
+— is the part the tools cannot say for themselves: when a cloud desktop is the
+right answer at all, that it costs money until it is suspended or stopped, that
+`run_agent` is usually the right level and a screenshot per click is not, and
+which refusals are worth a second try. It is a description of *when and how*,
+not a second client; once the server is installed it stays out of the way.
+`MANDALA_MODEL_KEY`, if exported alongside, is passed through and turns on
+`run_agent`.
+
+Or the server on its own, with the key inline:
 
 ```sh
 claude mcp add mandala -e MANDALA_API_KEY=com_… -- npx -y mandala-computer-mcp
@@ -122,8 +139,14 @@ already supports for when they are.
 **A running computer costs money, and a forgotten one keeps costing it.**
 `create_computer` says so in its own description, and so does everything that
 starts a machine by a side door — `restore_snapshot` boots a stopped computer,
-`write_clipboard` resumes a suspended one, and each of those is charged like
-any other start. When a stretch of work is over, `suspend_computer` (a pause:
+and `write_clipboard`, `read_file` and `cursor_position` each resume a suspended
+one, because each has to reach the guest agent to do its job. All of them are
+charged like any other start, and on a plan at its limit can come back 402
+rather than a result. The two reads are the surprising half of that list, and
+are why neither is annotated `readOnlyHint`: a host that auto-approves
+read-only tools would otherwise wake and bill a machine with nobody asked.
+`screenshot`, `read_clipboard` and `list_windows` genuinely do not start
+anything and keep the hint. When a stretch of work is over, `suspend_computer` (a pause:
 `start_computer` brings the same session back in about a second) or
 `stop_computer` (a shutdown: the disk is kept, the session is not). Idle
 suspend catches the ones a model forgets, but only after 30 minutes untouched.
@@ -258,6 +281,44 @@ they are doing — it does not receive them and has no `verify`, because a
 server with no endpoint has nothing to verify. `list_webhook_deliveries` is
 where a delivery that ran out of retries shows up; nothing is dropped silently.
 
+**A capture outlives the request that starts it.** `POST /computers/:id/snapshots`
+answers `202` with a placeholder row and copies the disk afterwards, which takes
+minutes and scales with how much has been written — longer than any HTTP request
+survives. So `create_snapshot` polls: it holds the id the platform allocated
+before the copy, watches `list_snapshots` for that row to stop reading
+`capturing`, and answers with the finished snapshot. It waits for *not
+capturing* rather than for `pending`, because replication can carry a small
+snapshot straight on to `durable` between two polls; and it matches on the id
+rather than on the newest row for the computer, because a scheduled capture
+finishing in the same window makes that wrong on exactly the long captures where
+it matters. `wait: false` hands back the id instead, for a caller that would
+rather poll on its own schedule.
+
+The three answers it can end on are kept apart deliberately. A capture that
+lands is the snapshot. A capture that FAILS mid-copy leaves no snapshot and no
+row — the `capturing` row simply disappears, and that absence is the only signal
+there is, which is why an incomplete listing is never allowed to decide it. A
+wait that runs out says the capture is still running and names the id to follow,
+because that one asks for a look rather than for another attempt.
+
+**A deletion outlives its request too, and reads the other way round.**
+`DELETE /snapshots/:id` answers `202` and then detaches the dependent snapshots
+and removes the stored objects. There is no state that means deleted, so
+`delete_snapshot` polls for the row to **go** — the mirror of a capture, which
+polls for a row to stay and change. A row that stays is one that STALLED, and it
+sits in `deleting`, a state a bare listing hides: the poll asks with
+`include=unfinished` for exactly that reason, since without it a half-deleted
+snapshot is indistinguishable from a deleted one. The platform retries a stalled
+deletion itself every fifteen minutes, so the give-up sentence says to watch
+rather than to repeat.
+
+Because absence is the success signal here, "Deleted" is said only off a listing
+read **whole**. A row missing because a hypervisor did not answer is not a row
+that is gone, and that mistake is unrecoverable in a way the others are not:
+nobody goes looking for a snapshot they have been told was destroyed. A `409`
+saying the snapshot is already being deleted is progress, not a fault — the
+answer is to watch that deletion finish, never to go and delete something else.
+
 **A schedule says when, not how long.** `snapshot_schedule` sets the window a
 computer's automatic snapshot is taken in; `get_retention` is what says how many
 of them survive, and it takes no computer because the window belongs to the
@@ -304,9 +365,12 @@ nothing; `background: true` is the only thing that works. The abandoned command
 keeps running, so the call after one of these often reports the guest agent as
 busy — that is the first failure continuing, not a second one.
 
-The ceiling belongs to that proxy rather than to the platform, which is why
-`timeout_s` still accepts up to 300: a `MANDALA_BASE_URL` pointed at an origin
-reached without the proxy in front of it does not have one.
+That roughly two-minute ceiling belongs to the hosted proxy. The server accepts
+integer foreground `timeout_s` values from 1 through 600 seconds (default 30),
+and the tool exposes that range for a `MANDALA_BASE_URL` reached without the
+proxy. The HTTP client allows 630 seconds for response headers so the server can
+report a 600-second timeout. Use `background: true` and poll the handle for
+longer work.
 
 **`list_windows` sees what a screenshot cannot.** It is how you tell an
 application that failed to start from one that has not painted yet. Match on
@@ -362,11 +426,25 @@ simply has fewer rows, an unknown number missing and nothing marking the gap.
 The other two append a row marked `unreachable` for each thing they could not
 reach — but only for a key that spans the account. A WORKSPACE-SCOPED key gets
 no marked rows either, because naming the missing ids would mean reading them
-out of a placement cache that has no workspace column, and handing a confined
+out of a host cache that has no workspace column, and handing a confined
 credential ids from the workspaces it is confined away from. For such a key all
 three listings are the `INCOMPLETE:` line and nothing else, which is why that
 line is written first and in prose.
 
+**A computer has a lifecycle of its own, separate from what its guest is
+doing.** `state` is the platform's record of whether the machine exists —
+`live`, `deleting`, `deleted`, `lost`, or `unreachable` when a listing could not
+confirm the row against its host — while `status` is the host's answer about the
+guest. A row served from the record has the first and not the second, so
+`list_computers` prints both when both are there: a computer can be running and
+being deleted at once.
+
+An unfiltered listing is `live`, `unreachable` and `deleting`. The two terminal
+states are withheld from it, so `list_computers(state: 'deleted')` is the only
+way a computer that has gone is ever shown — and an empty answer to a filtered
+listing is a fact about the filter rather than about the account, which is what
+it says rather than inviting you to create one.
+
 **Snapshots mid-deletion are billed but hidden.** A deletion that began and did
 not finish still holds objects and still counts against storage, and the default
 listing leaves it out — every ordinary caller is asking "what can I restore".
@@ -382,6 +460,10 @@ by default — the platform drops input on that socket, so it is safe to hand to
 somebody. `control: true` returns the full-control one, which is root-equivalent
 on that machine. Neither appears in any other tool's output, deliberately: a
 tool result lands in a model's context and from there in whatever captured it.
+It is also why `get_desktop_url` carries no `readOnlyHint` even though its route
+neither writes nor spends: hosts treat that hint as licence to call without
+asking, so keeping it would let a model pass out control of a desktop with
+nobody prompted.
 
 **Retiring a template cannot be undone, and takes more than it looks.**
 `retire_template` without a `version` retires **every** version of the name —
@@ -411,7 +493,17 @@ default request timeout is 60 seconds and only a progress notification can reset
 it — but the SDK resets it only for a caller that passed that option, so a client
 which merely accepts progress is still cancelled a minute into a fifteen-minute
 build. `get_build` is the answer for a client that cannot hold a request open:
-it reads once and returns. A build that *failed* is a normal answer from
+it reads once and returns.
+
+**The same applies to every tool here that waits.** `wait_for_computer`,
+`move_computer`, `create_snapshot` and `delete_snapshot` all poll, and all report
+progress on every poll — a changed line at once, an unchanged one on a ten-second
+heartbeat, so the request stays open without flooding the client. A live capture
+took 107 seconds and was cancelled at 60 before this existed, which turned every
+carefully-worded answer about what had actually happened into a transport error.
+Each of them has a way out for a client that cannot opt in: `wait: false` on the
+two snapshot tools, `list_moves` after a move, a shorter `timeout_s` and a second
+call on the wait. A build that *failed* is a normal answer from
 `watch_build`, not an error — it names the step that stopped it, which is the
 thing to fix. An `error` event is the *stream* failing and says nothing about the
 build, and the tool says so rather than letting a model rewrite a document that
@@ -472,7 +564,7 @@ naming the fix.
 | `MANDALA_BASE_URL` | Defaults to `https://app.mandala.computer/api/v1`. |
 | `MANDALA_COMPUTER_ID` | Bind a computer at startup, so `use_computer` is not needed. **stdio only** — under `--http` it is ignored rather than bound into every caller's session, since it names a machine on the operator's account. |
 | `MANDALA_MODEL_KEY` | An Anthropic key. Enables `run_agent`, which runs the platform's own loop on that key. **stdio only** — under `--http` each caller sends their own as `X-Model-Key`, and this variable is ignored. |
-| `MANDALA_NO_LIFECYCLE` | `1` withholds `create_computer`, `clone_computer`, `clone_snapshot`, `delete_computer` and `delete_snapshot` — every tool that makes a computer or destroys one. |
+| `MANDALA_NO_LIFECYCLE` | `1`, `true`, `yes` or `on` withholds `create_computer`, `clone_computer`, `clone_snapshot`, `delete_computer` and `delete_snapshot` — every tool that makes a computer or destroys one. `0`, `false`, `no`, `off` or unset leaves them registered. Any other value is **refused at startup** rather than read as off: a typo here would otherwise leave those tools in place on a server whose operator believes they are gone. The `--no-lifecycle` flag reads the same vocabulary and refuses the same way, except that it has no spelling for *unset*: `--no-lifecycle=` is refused rather than ignored, so a launcher template whose variable did not expand stops instead of quietly leaving the tools registered. |
 | `PORT`, `HOST` | For `--http`. Default `3000`, `127.0.0.1`. |
 | `MANDALA_ALLOWED_HOSTS`, `MANDALA_ALLOWED_ORIGINS` | Comma-separated. Which `Host` and `Origin` values this server answers to. On a loopback bind the host list defaults to the address it was given, so DNS-rebinding protection is on without configuration; set this when serving under a name. |
 
@@ -526,7 +618,7 @@ platform team; the diff is enforced from the platform's own CI, which checks
 this repository out beside itself and runs the same script.
 
 ```
-check:surface — the mirror matches the platform (56 routes, 89 parameters, from …/mandala-computer).
+check:surface — the mirror matches the platform (N routes, N parameters, from …).
 ```
 
 ## See also

package/dist/api.d.ts

@@ -1,3 +1,4 @@
+import { Agent } from 'undici';
 export declare const DEFAULT_BASE_URL = "https://app.mandala.computer/api/v1";
 /** Anthropic's own key, forwarded for the one route that runs a model. */
 export declare const MODEL_KEY_HEADER = "X-Model-Key";
@@ -54,10 +55,10 @@ export type Bytes = {
     unrangeable: boolean;
 };
 /**
- * The longest guest exec waits 300 seconds before it answers. Node's bundled
- * fetch also gives response headers 300 seconds by default, so the client can
- * lose that race while the command is still finishing in the guest. Keep the
- * public exec limit and give the platform enough time to report its timeout.
+ * The longest foreground guest exec waits 600 seconds before it answers.
+ * Node's bundled fetch gives response headers 300 seconds by default, so the
+ * client can lose that race while the command is still finishing in the guest.
+ * Allow 30 seconds beyond the public exec limit for the timeout response.
  *
  * The body is a different clock. undici's default `bodyTimeout` is 300 seconds
  * of silence *between chunks*, and `run_agent` SSE (or a long exec that has
@@ -66,9 +67,10 @@ export type Bytes = {
  * disables it: a quiet gap is not a dead connection, and the caller's
  * AbortSignal is what ends a request nobody is waiting for.
  */
-export declare const PLATFORM_HEADERS_TIMEOUT_MS = 330000;
+export declare const PLATFORM_HEADERS_TIMEOUT_MS = 630000;
 /** Disabled. A finite idle limit is what used to kill a quiet SSE stream. */
 export declare const PLATFORM_BODY_TIMEOUT_MS = 0;
+export declare const PLATFORM_DISPATCHER: Agent;
 /**
  * The fetch a platform request actually goes through, and why it is not simply
  * `fetch`.
@@ -160,7 +162,7 @@ export declare class Api {
      * short 200 — but a caller that opts in gets the list plus `X-GC-Incomplete`,
      * and a header is only a warning if something reads it.
      *
-     * It is the count of what the placement cache could account for, and it is
+     * It is the count of what the host cache could account for, and it is
      * legitimately `0`: a computer created during the outage was never cached
      * against the host now holding it. So presence is the signal and the number is
      * detail, which is why this returns `null` versus a number rather than a
@@ -181,6 +183,17 @@ export declare class Api {
      */
     sse(method: string, path: string, opts?: RequestOptions): AsyncGenerator<SSEEvent>;
 }
+/**
+ * Every error under one, including the ones a fetch hides two levels down.
+ *
+ * A rejected fetch is a `TypeError: fetch failed` whose `cause` is what
+ * actually went wrong, and on a dual-stack host that cause is an
+ * `AggregateError` holding one attempt per address. Neither the top error nor
+ * its immediate cause carries the code the classifiers below read, so both
+ * links have to be followed. Bounded, because a cause chain is user-reachable
+ * data and nothing here needs to be robust to a cycle.
+ */
+export declare function causes(err: unknown, depth?: number): Generator<Record<string, unknown>>;
 /** The filename the platform put on a download, if it put one there. */
 export declare function filenameFrom(disposition: string | null): string | undefined;
 //# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/api.js

@@ -1,5 +1,5 @@
 import { Agent, fetch as undiciFetch } from 'undici';
-import { CancelledError, ConnectivityError, ConnectivityInterruptedError, errorForStatus, MandalaError, RangeNotSatisfiableError, RateLimitError, } from './errors.js';
+import { CancelledError, ConnectivityError, ConnectivityInterruptedError, errorForStatus, MandalaError, RangeNotSatisfiableError, RateLimitError, RedirectError, } from './errors.js';
 export const DEFAULT_BASE_URL = 'https://app.mandala.computer/api/v1';
 /** Anthropic's own key, forwarded for the one route that runs a model. */
 export const MODEL_KEY_HEADER = 'X-Model-Key';
@@ -11,14 +11,28 @@ export const MODEL_KEY_HEADER = 'X-Model-Key';
  * until the process runs out of memory.
  */
 const MAX_SSE_BUFFER = 8 * 1024 * 1024;
-/** Finite response-body ceilings for the two paths that decode text. */
-const MAX_JSON_BODY_BYTES = 16 * 1024 * 1024;
+/**
+ * Finite response-body ceilings for the two paths that decode text.
+ *
+ * The JSON one is sized off the largest legitimate response on any route, which
+ * is an exec answer (OPL-4542). The guest agent caps its capture at 16 MiB PER
+ * STREAM, and both streams now travel as base64 — four characters for every
+ * three bytes — so a foreground command that filled both arrives as about
+ * 42.7 MiB of JSON. This used to be 16 MiB, sized when those fields were JSON
+ * strings of the decoded bytes, and a body over it is not truncated but
+ * REFUSED: the model would have lost the whole answer, truncation sentence
+ * included, somewhere north of 12 MiB of output. Under the platform's own
+ * 64 MiB transfer cap, and still finite, which is the only thing this guard is
+ * for — it exists to refuse an unbounded body, not to set a policy on a large
+ * one.
+ */
+const MAX_JSON_BODY_BYTES = 48 * 1024 * 1024;
 const MAX_ERROR_BODY_BYTES = 1024 * 1024;
 /**
- * The longest guest exec waits 300 seconds before it answers. Node's bundled
- * fetch also gives response headers 300 seconds by default, so the client can
- * lose that race while the command is still finishing in the guest. Keep the
- * public exec limit and give the platform enough time to report its timeout.
+ * The longest foreground guest exec waits 600 seconds before it answers.
+ * Node's bundled fetch gives response headers 300 seconds by default, so the
+ * client can lose that race while the command is still finishing in the guest.
+ * Allow 30 seconds beyond the public exec limit for the timeout response.
  *
  * The body is a different clock. undici's default `bodyTimeout` is 300 seconds
  * of silence *between chunks*, and `run_agent` SSE (or a long exec that has
@@ -27,10 +41,10 @@ const MAX_ERROR_BODY_BYTES = 1024 * 1024;
  * disables it: a quiet gap is not a dead connection, and the caller's
  * AbortSignal is what ends a request nobody is waiting for.
  */
-export const PLATFORM_HEADERS_TIMEOUT_MS = 330_000;
+export const PLATFORM_HEADERS_TIMEOUT_MS = 630_000;
 /** Disabled. A finite idle limit is what used to kill a quiet SSE stream. */
 export const PLATFORM_BODY_TIMEOUT_MS = 0;
-const PLATFORM_DISPATCHER = new Agent({
+export const PLATFORM_DISPATCHER = new Agent({
     headersTimeout: PLATFORM_HEADERS_TIMEOUT_MS,
     bodyTimeout: PLATFORM_BODY_TIMEOUT_MS,
 });
@@ -195,6 +209,8 @@ export class Api {
         }
         const signal = opts.signal ?? this.#signal;
         let resp;
+        /** Kept so a relative `Location` can be resolved against what was asked. */
+        let requested = this.#base;
         try {
             // `dispatcher` is Node/undici's extension to RequestInit. It is kept on
             // a typed variable so the standard fetch signature can still be used.
@@ -203,9 +219,17 @@ export class Api {
                 headers,
                 body,
                 signal,
+                // Answered, not followed. `isTransientForPoll` has always documented
+                // this client as one that does not follow redirects — the `>= 500` rule
+                // is argued from it — and the default `'follow'` quietly made that
+                // false: up to twenty hops, with the bearer still attached on the
+                // same-origin ones, and an operator whose MANDALA_BASE_URL is wrong
+                // never finding out. See {@link RedirectError}.
+                redirect: 'manual',
                 dispatcher: PLATFORM_DISPATCHER,
             };
-            resp = await platformFetch()(this.#url(path, opts.query), init);
+            requested = this.#url(path, opts.query);
+            resp = await platformFetch()(requested, init);
         }
         catch (cause) {
             // Cancellation first, because it is not a connectivity failure and the
@@ -236,6 +260,38 @@ export class Api {
                 `was sent: ${detail}. It may have been received, so treat anything it would have ` +
                 'changed as unknown rather than undone.');
         }
+        // Before the general mapping, because a 3xx carries no error body to read
+        // and its one useful field is a HEADER. Left to `#error` it would arrive as
+        // a bare `HTTP 301`, which says nothing about the value that has to change.
+        if (resp.status >= 300 && resp.status < 400) {
+            // Resolved against the request, because `Location` is very often relative
+            // and `redirect: 'manual'` hands back the raw header. "set
+            // MANDALA_BASE_URL to /api/v1/computers" names something that is not a URL
+            // and would not work — and naming the value to paste is the entire reason
+            // this branch exists rather than a bare `HTTP 301`.
+            const raw = resp.headers.get('location');
+            let to = raw ?? undefined;
+            if (raw) {
+                try {
+                    to = new URL(raw, requested).toString();
+                }
+                catch {
+                    // A Location this client cannot parse is still worth repeating
+                    // verbatim: the operator can see what the platform said.
+                    to = raw;
+                }
+            }
+            // Cancelled before the throw, the way every other exit in this file
+            // cancels its reader. A 3xx body is nothing anybody wants, but an unread
+            // one holds its undici connection open until the GC gets to it — and the
+            // whole point of this branch is a misconfigured base URL, which means
+            // EVERY request takes it.
+            await resp.body?.cancel().catch(() => { });
+            throw new RedirectError(`${method} /${path.replace(/^\/+/, '')} was redirected (HTTP ${resp.status}${to ? ` to ${to}` : ', with no Location header'}). This client does not follow redirects, because a redirect says the ` +
+                `address it was given is not the address in use — set MANDALA_BASE_URL to ` +
+                `${to ? 'that URL' : 'the URL the platform actually serves'} rather than relying on ` +
+                `a hop on every request. Retrying this unchanged gets the same answer.`, resp.status);
+        }
         if (!resp.ok)
             throw await this.#error(resp, method, path, signal);
         return resp;
@@ -377,7 +433,7 @@ export class Api {
      * short 200 — but a caller that opts in gets the list plus `X-GC-Incomplete`,
      * and a header is only a warning if something reads it.
      *
-     * It is the count of what the placement cache could account for, and it is
+     * It is the count of what the host cache could account for, and it is
      * legitimately `0`: a computer created during the outage was never cached
      * against the host now holding it. So presence is the signal and the number is
      * detail, which is why this returns `null` versus a number rather than a
@@ -415,7 +471,7 @@ export class Api {
         // because assuming is the exact failure the status exists to prevent, and
         // because nothing downstream can tell the difference afterwards.
         //
-        // The platform always sends the header (`bytes %d-%d/%d` in server/api.go).
+        // The platform always sends the header, formatted `bytes %d-%d/%d`.
         // A hop in front of it that drops the header is the case this is for, and
         // the same one mandala-computer-typescript's toFileChunk refuses.
         if (resp.status === 206 && !window) {
@@ -466,6 +522,8 @@ export class Api {
         });
         const contentType = mediaType(resp.headers.get('content-type'));
         if (contentType !== 'text/event-stream') {
+            // No reader owns this body yet; release a rejected response ourselves.
+            await resp.body?.cancel().catch(() => { });
             throw new MandalaError(`${method} ${path} expected text/event-stream, but the platform answered ${contentType}`);
         }
         if (!resp.body)
@@ -551,7 +609,7 @@ function isCancellation(_cause, signal) {
  * links have to be followed. Bounded, because a cause chain is user-reachable
  * data and nothing here needs to be robust to a cycle.
  */
-function* causes(err, depth = 0) {
+export function* causes(err, depth = 0) {
     if (!err || typeof err !== 'object' || depth > 5)
         return;
     const e = err;
@@ -795,11 +853,20 @@ const MAX_TIMER_MS = 2_147_483_647;
  * delta-seconds is not malformed enough to stop there: `Date.parse('-5')` is a
  * date in 2001, so it falls through to the branch below and lands on 0, which
  * is the same answer a date in the past gets and is why nothing worse happens.
+ *
+ * DECIMAL DIGITS for the first branch, not whatever `Number()` will take. The
+ * header's grammar is delta-seconds or an HTTP-date, and `0x10` and `1e3` are
+ * neither — but `Number()` reads them as 16 and 1000, so a broken or hostile
+ * intermediary could spell a sixteen-minute sleep in three characters and have
+ * a poll loop honour it as if the platform had asked. Gated the way
+ * {@link contentLength} below and `port()` in cli.ts already gate the same
+ * `Number()` footgun; anything else falls through to the date branch, which
+ * refuses it, and the loop keeps its own interval.
  */
 function retryAfterMs(header) {
     if (!header)
         return undefined;
-    const seconds = Number(header);
+    const seconds = /^\d+$/.test(header.trim()) ? Number(header) : Number.NaN;
     if (Number.isFinite(seconds) && seconds >= 0)
         return Math.min(seconds * 1_000, MAX_TIMER_MS);
     const at = Date.parse(header);
@@ -902,31 +969,146 @@ function parseEvent(chunk) {
         return { event, data: joined };
     }
 }
+/**
+ * Split a `Content-Disposition` header into its parameters, per the grammar in
+ * RFC 6266 §4.1 and RFC 7230 §3.2.6 rather than by regex.
+ *
+ * Two attempts at this shipped a worse bug than the one they fixed, and both
+ * failed at the same place: deciding what a `"` means without tracking where in
+ * the grammar the reader is. A `"` is only a delimiter where a value begins.
+ * Anywhere else — `note=a"b` — it is an ordinary character of a token, and a
+ * reader that toggles on every quote it meets turns the rest of the header into
+ * one run and loses the real `filename` after it.
+ *
+ * Inside a quoted string, `\` escapes the next character (`quoted-pair`), so a
+ * `\"` does NOT close the value. A reader that stops at the first `"` it sees
+ * lets a trailing `\"` smuggle a `; filename=` out of a value the sender
+ * controls and into the parameter list.
+ *
+ * An unterminated quoted value runs to the end of the header. That is the one
+ * decision here that is a judgment rather than the grammar — see the comment on
+ * `filenameFrom` — and it is what keeps such a value's contents from being read
+ * as parameters at all.
+ */
+function dispositionParams(header) {
+    const params = [];
+    // The disposition-type comes first and is a bare token; parameters begin at
+    // the first `;`. A header with no `;` has no parameters and no filename.
+    let i = header.indexOf(';');
+    if (i === -1)
+        return params;
+    while (i < header.length) {
+        i += 1; // past the ';' that begins this parameter
+        while (i < header.length && /\s/.test(header[i]))
+            i += 1;
+        const nameFrom = i;
+        while (i < header.length && header[i] !== '=' && header[i] !== ';')
+            i += 1;
+        const name = header.slice(nameFrom, i).trim().toLowerCase();
+        if (header[i] !== '=') {
+            // A parameter with no `=` at all. Recorded so it cannot be mistaken for
+            // the next one, and skipped.
+            if (name)
+                params.push({ name, value: '' });
+            continue;
+        }
+        i += 1; // past the '='
+        // BWS: RFC 7230 allows whitespace either side of the `=`, and a value that
+        // begins after it is still that parameter's value.
+        while (i < header.length && /[ \t]/.test(header[i]))
+            i += 1;
+        let value = '';
+        if (header[i] === '"') {
+            i += 1;
+            let out = '';
+            for (; i < header.length; i += 1) {
+                const ch = header[i];
+                if (ch === '\\' && i + 1 < header.length) {
+                    out += header[i + 1];
+                    i += 1;
+                }
+                else if (ch === '"') {
+                    i += 1;
+                    break;
+                }
+                else
+                    out += ch;
+            }
+            value = out;
+            // Anything between the closing quote and the next `;` is not part of the
+            // value and is not a parameter either.
+            while (i < header.length && header[i] !== ';')
+                i += 1;
+        }
+        else {
+            const from = i;
+            while (i < header.length && header[i] !== ';')
+                i += 1;
+            // A token value carries no delimiters, so the whitespace around it is the
+            // header's formatting rather than the name: `filename=real.txt ; x=1`
+            // named a file with a trailing space on it.
+            value = header.slice(from, i).trim();
+        }
+        if (name)
+            params.push({ name, value });
+    }
+    return params;
+}
 /** The filename the platform put on a download, if it put one there. */
 export function filenameFrom(disposition) {
     if (!disposition)
         return undefined;
-    // Any charset and any language, not only `UTF-8''`. RFC 5987 writes this
-    // value as charset, language, then the text, with the language ordinarily
-    // empty — and matching only the empty spelling meant that both
-    // `filename*=ISO-8859-1''…` and `filename*=UTF-8'en'…` were read by neither
-    // branch — the plain form below cannot match either, since there is no
-    // `filename=` in them — so a download the platform had named came back with
-    // no name at all. Three groups, not two: the middle one is the language tag,
-    // present or empty.
-    const star = /filename\*=([^']*)'([^']*)'([^;]+)/i.exec(disposition);
-    if (star) {
-        // A stray `%` in a guest filename is legal on disk and makes this throw.
-        // Letting it out would turn a download whose bytes already arrived intact
-        // into a failure, over the label on it.
+    // Parsed rather than matched. Every previous spelling of this read the header
+    // with one regex, and each one in turn found a `filename=` that belonged to
+    // some other parameter's value — `inline; x-filename=q.txt` through a missing
+    // parameter boundary, then `note="a; filename=evil.txt"` through a `;` inside
+    // a quoted string. What the sender controls should not be able to add a
+    // parameter the sender did not send.
+    //
+    // The judgment call, stated because the grammar does not make it: an
+    // unterminated quoted value consumes the rest of the header. It is what the
+    // WHATWG "collect an HTTP quoted string" algorithm does, and it is the only
+    // reading under which `note="a; filename=evil.txt\"` — where the `\"` escapes
+    // the quote that would have closed the value — yields no filename at all. The
+    // cost is that a sloppy sender's unterminated value swallows a real
+    // `filename` after it; the benefit is that a hostile one cannot smuggle a
+    // fake one out. `filename="report.pdf` still works, because there the
+    // unterminated value IS the filename.
+    const params = dispositionParams(disposition);
+    // RFC 8187: charset, language, then the text, with the language ordinarily
+    // empty. Any charset and any language, not only `UTF-8''` — matching the
+    // empty spelling alone meant `ISO-8859-1''…` and `UTF-8'en'…` were read by
+    // neither branch, and a download the platform had named came back unnamed.
+    // The FIRST USABLE one of each name, not the first one. A repeated parameter
+    // is malformed and the platform never sends one, but the regex this replaced
+    // walked on from an occurrence it could not read — `[^";]+` cannot match an
+    // empty value — and answered from the next. Stopping at the first occurrence
+    // instead means `filename=""; filename=real.txt` loses a name that was there,
+    // which is a regression on an already-invalid header rather than a defence:
+    // every parameter in this list is one the sender genuinely wrote at the top
+    // level, since a smuggled one never becomes a parameter at all.
+    for (const p of params) {
+        if (p.name !== 'filename*')
+            continue;
+        const ext = /^[^']*'[^']*'([\s\S]*)$/.exec(p.value);
+        // An empty `filename*` names nothing, so keep looking — at another
+        // `filename*`, and then at the plain `filename` beside it. Either beats
+        // answering with the empty string.
+        if (!ext?.[1])
+            continue;
         try {
-            return decodeURIComponent(star[3]);
+            return decodeURIComponent(ext[1]);
         }
         catch {
-            return star[3];
+            // A stray `%` in a guest filename is legal on disk and makes this throw.
+            // Letting it out would turn a download whose bytes already arrived intact
+            // into a failure, over the label on it.
+            return ext[1];
         }
     }
-    const plain = /filename="?([^";]+)"?/i.exec(disposition);
-    return plain ? plain[1] : undefined;
+    for (const p of params)
+        if (p.name === 'filename' && p.value)
+            return p.value;
+    return undefined;
 }
 //# sourceMappingURL=api.js.map