Keep dropped desktop icons fully on screen, and fill the phone popover

A desktop icon drop is accepted only where the whole item fits above the
bottom edge. Phone popovers use the full viewport height.

.github/workflows/ai-provider-integration-tests.yaml

@@ -53,7 +53,7 @@ jobs:
             # step above fails; the tests skip themselves without the key.
             - name: Run live realtime conversation tests
               if: ${{ !cancelled() }}
-              run: npm run setupExtensions && (cd src/puter-js && npm run build) && npx vitest run --config src/puter-js/tests/api/vitest.config.ts src/puter-js/tests/api/realtime/convoLive.test.ts
+              run: npm run setupExtensions && (cd src/puter-js && npm run build) && npx vitest run --config src/puter-js/tests/api/vitest.config.ts src/puter-js/tests/api/realtime/realtimeLive.test.ts
               env:
                   CI: 'true'
                   PUTER_TEST_AI_OPENAI_API_KEY: ${{ secrets.PUTER_TEST_AI_OPENAI_API_KEY }}

.github/workflows/notify-dev.yaml

@@ -0,0 +1,48 @@
+name: Notify HeyPuter (dev)
+
+on:
+  workflow_dispatch:
+    inputs:
+      puter_ref:
+        description: "puter branch, tag or SHA"
+        type: string
+        default: "main"
+
+permissions:
+  contents: read
+
+jobs:
+  authorize:
+    if: github.repository == 'HeyPuter/puter'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require maintain or admin
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ACTOR: ${{ github.triggering_actor }}
+        run: |
+          ROLE=$(gh api "repos/$GITHUB_REPOSITORY/collaborators/$ACTOR/permission" --jq .role_name)
+          if [ "$ROLE" != "maintain" ] && [ "$ROLE" != "admin" ]; then
+            echo "::error::$ACTOR has role '$ROLE'; maintain or admin required"
+            exit 1
+          fi
+
+  notify:
+    needs: authorize
+    runs-on: ubuntu-latest
+    # Holds HEYPUTER_DISPATCH_TOKEN; limited to main so branch copies of this file can't read it.
+    environment: heyputer-dispatch
+    steps:
+      - name: Trigger heyputer dev deploy
+        env:
+          PUTER_REF: ${{ inputs.puter_ref }}
+          TOKEN: ${{ secrets.HEYPUTER_DISPATCH_TOKEN }}
+        run: |
+          jq -nc --arg ref "$PUTER_REF" \
+            '{event_type: "puter-dev-requested", client_payload: {puter_ref: $ref}}' |
+          curl -fsS -X POST \
+            -H "Authorization: token $TOKEN" \
+            -H "Accept: application/vnd.github.v3+json" \
+            https://api.github.com/repos/HeyPuter/heyputer/dispatches \
+            -d @-
+          echo "Requested \`$PUTER_REF\`" >> "$GITHUB_STEP_SUMMARY"

.github/workflows/notify-prod.yaml

@@ -8,6 +8,7 @@ on:
 jobs:
   notify:
     runs-on: ubuntu-latest
+    environment: heyputer-dispatch
     steps:
       - name: Trigger heyputer build
         run: |
@@ -15,4 +16,4 @@ jobs:
             -H "Authorization: token ${{ secrets.HEYPUTER_DISPATCH_TOKEN }}" \
             -H "Accept: application/vnd.github.v3+json" \
             https://api.github.com/repos/HeyPuter/heyputer/dispatches \
-            -d '{"event_type":"puter-main-updated","client_payload":{"puter_ref":"main"}}'
+            -d '{"event_type":"puter-main-updated","client_payload":{"puter_ref":"main"}}'

.github/workflows/puterjs-tests.yaml

@@ -176,7 +176,10 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v7
 
+      # Missing when the PR leg failed; `coverage (pr)` already reports that.
       - name: Download PR coverage
+        id: pr-coverage
+        continue-on-error: true
         uses: actions/download-artifact@v8
         with:
           name: puterjs-coverage-pr
@@ -186,6 +189,7 @@ jobs:
       # base run) — then report without the comparison column.
       - name: Download base coverage
         id: base-coverage
+        if: steps.pr-coverage.outcome == 'success'
         continue-on-error: true
         uses: actions/download-artifact@v8
         with:
@@ -193,7 +197,7 @@ jobs:
           path: coverage-base
 
       - name: Report coverage on PR
-        if: steps.base-coverage.outcome == 'success'
+        if: steps.pr-coverage.outcome == 'success' && steps.base-coverage.outcome == 'success'
         uses: davelosert/vitest-coverage-report-action@v2
         with:
           name: puter.js SDK
@@ -202,7 +206,7 @@ jobs:
           json-summary-compare-path: coverage-base/coverage-summary.json
 
       - name: Report coverage on PR (no base comparison)
-        if: steps.base-coverage.outcome != 'success'
+        if: steps.pr-coverage.outcome == 'success' && steps.base-coverage.outcome != 'success'
         uses: davelosert/vitest-coverage-report-action@v2
         with:
           name: puter.js SDK

AGENTS.md

@@ -159,13 +159,42 @@ The reference has two kinds of page:
 
 An overview page answers "what is this API and is it what I need?", and a function page answers "how exactly does this call behave?". A change to one function usually only touches that function's page, so a new `kv.list()` option goes in `KV/list.md` without a matching update to `KV.md`. Don't copy a function's options, limits, or edge cases onto the overview page for completeness. Where a detail goes is a judgment call, not a hard rule: update the overview when a change affects how someone would describe the API as a whole.
 
-When you add a page, add it to [src/docs/src/sidebar.js](src/docs/src/sidebar.js) under its area, or it won't show up in the navigation. When you add a runnable example, add its HTML to `src/docs/src/playground/examples/<slug>.html`, register the slug in [src/docs/src/examples.js](src/docs/src/examples.js), and link the code block to it by putting the slug after the language with a semicolon (` ```html;kv-set `).
+When you add a page, add it to [src/docs/src/sidebar.js](src/docs/src/sidebar.js) under its area, or it won't show up in the navigation.
+
+**Sidebar order.** Order the API areas in the sidebar by how often developers use them, most common first. Overview stays first and Objects stays last. Inside an area, order the pages by use too, and keep pages that make up one feature next to each other, such as `share()`, `unshare()`, `listShared()`, and `listSharedByMe()`. A group goes where its most-used page would go. A helper that only supports another function, such as `listModels()` for `chat()`, goes by its own use. Put create, list, get, update, and delete in that order, and constants such as `MAX_KEY_SIZE` last. The function list on the area's overview page uses the sidebar's order. When you add a runnable example, add its HTML to `src/docs/src/playground/examples/<slug>.html`, register the slug in [src/docs/src/examples.js](src/docs/src/examples.js), and link the code block to it by putting the slug after the language with a semicolon (` ```html;kv-set `).
+
+### Function page layout
+
+A function page opens with one sentence that says what the function does, in its own paragraph, such as "Given a prompt, generate an image using AI." Put any more detail in the paragraphs after it.
+
+After the intro, a function page has these `##` sections, in this order:
+
+1. Syntax
+2. Parameters
+3. Return value
+4. Errors, if the function has any
+5. Sections for specific topics, if the page needs them, with `## Model-specific features` last
+6. Examples
+
+[chat.md](src/docs/src/AI/chat.md) follows this layout.
+
+- **Options as a table.** Document an options object as a table with Option, Type, and Description columns. Give each option its own row, even when two options go together, such as `width` and `height`. Order the rows by how often developers use them, most common first, without group rows. In chat.md that's the core options, then reasoning, tools, response handling, request control, and output.
+- **Common options in the table, model-specific behavior in its own section.** A page whose function works with many models or providers, such as [chat.md](src/docs/src/AI/chat.md) and [txt2img.md](src/docs/src/AI/txt2img.md), splits its options this way:
+  - **The options table** under Parameters lists the options that work with every model, and describes each one the way it works for every model.
+  - **`## Model-specific features`**, the last section before Examples, covers everything else. It has a `###` for each model family or provider, named after it, such as "OpenAI models" or "Cloudflare models". Under it go the options only some models accept, and the common options a model handles differently, such as a narrower range, other allowed values, or an option it ignores.
+  - **Write there only what's different.** A `###` lists an option only when that model or provider adds it or handles it differently. An option that works the same everywhere stays out, even if the provider supports it, and a model or provider with nothing different gets no `###`.
+  - **Model-specific features is the only place for model-specific details.** Every limit, format, allowed value, default, price, or quirk that applies to some models goes there, in that model's or provider's `###`, and nowhere else. The options table and topic sections (such as Image inputs or Video input) describe what's true for every model and link to Model-specific features for the rest. Don't add a table or sentence there that compares providers or repeats a model's limits. Each copy is another source of truth to keep in sync, and copies drift when a model changes.
+  - **Link the two.** Directly under the options table, put `Some models accept additional options or handle these options differently. See [Model-specific features](#model-specific-features).` A row whose option behaves differently on some models can also end with `See [Model-specific features](#model-specific-features).`
+- **A long topic gets its own `##` section.** When explaining an option or feature takes more than a sentence or two, such as function calling or output dimensions, give it a section between Errors and Examples and link to it from the options table. This keeps the reference sections short.
+- **Usage patterns are examples.** A way of using the API, such as stopping a stream, goes in a runnable example that the relevant section links to ("See the [stop a stream example](/playground/ai-chat-stop-stream/)."), not in a section of its own.
+- **Each example has a `###` heading** under `## Examples`, so every example shows in the table of contents.
 
 ### Writing docs
 
 These apply to reference pages and recipes alike.
 
 - **Document the developer-facing side only.** The reader is building on top of puter.js, so cover what affects their code: signatures, defaults, return shapes, errors, limits, and behavior they can observe. Leave out internal workings (which service handles the call, storage layout, caching, retries) unless they change what the developer has to do. [rate-limits-and-quotas.md](src/docs/src/rate-limits-and-quotas.md) is the exception: it publishes every limit, including timeouts and caps that come from how the backend works.
+- **Document Puter as it runs on puter.com.** The docs are for developers building on production Puter. Leave out behavior that only happens on a self-hosted or differently configured server, such as a provider that isn't set up there.
 - **Describe the current state.** Docs aren't a changelog. Write how the API behaves now, without "now", "no longer", "existing code is unaffected", or other wording that compares it to an older version.
 - **Verify before you document.** Run the calls you describe against a running Puter instead of inferring behavior from the source.
 - **Write plainly.** Use the literal words a developer would say out loud, with contractions and everyday words. No idioms or figurative verbs ("walk away from something shared with you" → "remove your own access", "nothing to page through" → "without pagination"). No formal register ("present only while more pages remain" → "includes a `cursor` if there are more pages to load"). Prefer dev terms such as atomic, concurrent, and insertion order.
@@ -173,6 +202,7 @@ These apply to reference pages and recipes alike.
 - **Describe behavior directly.** No quoted inner-voice phrases. Write "`isNew` is `true` when the person did not have access before", not "this tells 'I just gave this to someone' from 'they already had it'".
 - **Keep references easy to follow.** Name what a list or code block belongs to in the sentence directly above it. Name a thing once and keep that name. Introduce an actor as "a user" before giving them a role: "A user can create a team. The user who creates the team becomes its owner."
 - **Sentence mechanics.** Never start a sentence with inline code: write "To store data, use the [`set()`](/KV/set/) method." Link every inline mention of an API to its page, every time. No em dashes, and no colons or semicolons mid-sentence; a colon that introduces a code block is fine.
+- **No `##` or `###` headings inside tabs.** The table of contents lists every `##` and `###` heading on the page, including the ones in a hidden tab (an `example-content` block switched by the `example-group` pills), so its links lead to content the reader can't see. Put the heading above the tabs, or use `####` inside a tab, which the table of contents skips.
 - **Show the correct way.** No "don't" and no wrong-way-first examples, in recipes and playground examples alike. Mention a wrong approach only when developers already hit it in practice, and state how it fails as a fact: "`add()` reads a plain object as a path map, so the call rejects with …".
 
 ### Recipes

BUG-BOUNTY.md

@@ -40,7 +40,7 @@ The following have already been reviewed and determined **not to be vulnerabilit
 - **SSRF via `secureFetch`.** Production routes outbound requests through an isolated proxy that has no access to internal/SSRF-sensitive resources.
 - **Attacks that depend on guessing an `appInstanceID` or app UID.** These are random 128-bit secret values and are not considered guessable.
 - **Apps invoking drivers, creating workers, or using KV.** Applications are intended to do this; worker permissions are scoped to the owning app. This is by design.
-- **App metadata or app user-count "leaks".** This information is currently public by design. This covers **private apps** too: private apps are an unreleased, admin-only beta for paid listings in the Puter App Center. Their `index_url` and other metadata are not secret, the flag is not user-settable, and no production app relies on it. Reports that a private app's metadata is reachable through a sibling route (taskbar items, `/get-launch-apps`, `index_url` drift on the hosting gate, etc.) are normalization work, not vulnerabilities.
+- **App metadata or app user-count "leaks".** This information is currently public by design. This covers **private apps** too: private apps are an unreleased, admin-only beta for paid listings in the Puter App Center. Their `index_url` and other metadata are not secret, the flag is not user-settable, and no production app relies on it. Reports that a private app's metadata is reachable through a sibling route (`/get-launch-apps`, `index_url` drift on the hosting gate, etc.) are normalization work, not vulnerabilities.
 - **Worker hot-reload driven by a share recipient.** Sharing a worker's source file with write access is how you let a collaborator change that worker's code and have it deploy live. The redeploy running as the file owner, with the owner's worker credentials, is the intended behavior of that grant — the owner chose to hand out write access to executable code. If you do not want that, do not share the source file with write access.
 - **Re-claiming a site or worker name its owner deleted.** A hosted site or worker name that its owner deletes is treated as abandoned by that owner. If one of their apps still points at it, whoever claims the name next serves that app's `index_url` and receives what the app is launched with, and a new app on the same origin may share the old one's identity. Guarding app identities against being recycled this way is ongoing hardening, not a security boundary, so new ways to re-claim an abandoned name, or to inherit an app's tokens or data through one, are not eligible.
 - **Share-mode downgrades that do not cascade.** Demoting a delegate does not retroactively revoke the grants that delegate already issued downstream. Shares are independent grants once issued, not a live-evaluated chain. Revoking the downstream grant is a separate, supported action.

CLAUDE.md

@@ -1 +1 @@
-FOLLOW ./AGENTS.md
+FOLLOW @AGENTS.md

doc/embedding-app-browser.md

@@ -0,0 +1,365 @@
+# Embedded app browser
+
+`GET /embed/apps` on the deployment's main GUI origin renders the same app browser
+as the dashboard's Apps tab, without the desktop or dashboard navigation.
+
+It supports search, paging, saved folders, and saved ordering. It uses the same
+installed-app and recommendation data as the dashboard, including the user's
+removed recommendations. Editing, adding, reordering, renaming, and uninstalling
+are disabled. Selecting an app opens it in a new browser tab at its own URL, the
+same way the dashboard does, and the host page stays open. The app's token isn't
+put in the URL: the app's SDK asks the embed for it once the tab loads, so the
+embed must still be open then. If the iframe is removed first, the app falls back
+to its normal sign-in. Apps that need the desktop (built-in and godmode apps,
+private apps the user can't open, or a failed token request) open `/app/<name>`
+on the GUI origin, cut off from the embed. Website shortcuts open their external
+destination with no opener.
+The embed follows the OS's light or dark setting. A host with a fixed theme adds
+`theme=dark` or `theme=light` to the fragment (`#user=<uuid>&theme=dark`), since
+Chromium doesn't pass an iframe's `color-scheme` on to the page inside it.
+Apps opened from the embed carry `utm_source=puter.com&utm_medium=referral&utm_campaign=app_browser_embed`;
+the desktop and dashboard send `utm_campaign=desktop` and `utm_campaign=dashboard`.
+
+## Session and framing
+
+The embed shows the GUI session only to the user the host page is signed in as.
+The host names that user's `uuid` (from `puter.auth.getUser()`) in the iframe
+URL's fragment, as `/embed/apps#user=<uuid>`. The embed reads the session, asks
+`/whoami` which user it belongs to, and shows the signed-out view unless the two
+match. So a host that names no user, a malformed one, or a user other than the
+session's, gets the signed-out view, and so does a session the API refuses. A
+failed `/whoami` check shows the error state. The fragment never reaches the
+server and can only narrow what the embed shows: naming the session's own user
+gives the same view as a direct visit to the GUI. Changing the fragment of a
+loaded embed reloads it.
+
+The embed reads the existing GUI session from local storage on its own origin.
+If that storage holds no session, the embed gets the session from the GUI origin's session cookie through
+`/get-gui-token`. This matters in Safari, which gives a framed origin separate
+local storage under each top-level origin, so even a sibling subdomain's iframe
+can't see the GUI's stored token. The session cookie is still sent, because the
+host is on the same site. The embed doesn't write that token back to storage. It
+does not create accounts, show a login dialog, or accept a token from its parent.
+Being signed in on a subdomain alone does not create a session on the main GUI
+origin.
+
+Without a session it can show, the embed shows the recommended apps (`RecommendedAppsService`)
+that the server put in the page, and nothing else: no installed apps, folders, or
+saved order, and no puter.js. Selecting one opens it at the same URL a signed-in
+launch uses, with no opener and no token on offer, so the app signs in on its own.
+Apps that need the desktop open `/app/<name>`. If the page carries no recommended
+apps, or a load fails, the embed displays an unavailable/error state.
+
+The route's `Content-Security-Policy: frame-ancestors` allows the GUI origin and
+the embedding page's origin when it is exactly one label under `config.domain`
+with the scheme and port from `config.origin`. Subdomains the server answers
+itself (`api`, `dav`, `js`, `www`, the native-app hosts, and the host of
+`api_base_url`) and the user-content hosting domains (`static_hosting_domain`,
+`private_app_hosting_domain`, and their `_alt` variants) are refused. For
+example, `https://puter.com` permits `https://spreadsheet.puter.com` but not
+`https://api.puter.com`, and `http://puter.localhost:4100` permits
+`http://spreadsheet.puter.localhost:4100` but not
+`http://someone.site.puter.localhost:4100`. The embedding page is read from the
+iframe request's referrer, so the host must not suppress it (the browser default
+`strict-origin-when-cross-origin` is enough). All ancestors in a nested iframe
+chain must be allowed. Other GUI routes retain `X-Frame-Options: SAMEORIGIN`.
+
+The embed accepts no query parameters. Requests with a query string redirect to
+the same embed path so SDK bootstrap parameters cannot override the session or API
+origin. The host needs to allow the GUI origin in its own `frame-src` CSP if it
+sets one. If sandboxing the iframe, allow scripts, same-origin storage, popups,
+and popups to escape the sandbox.
+
+## Host integration
+
+A first-party app that signs in with puter.js can place `<puter-user-menu>` from
+the SDK in its header instead (see `src/puter-js/src/ui/components.md`). It opens
+this embed with the signed-in user named and closes it when the app's sign-in
+changes. The rest of this section is for a host that builds the iframe itself.
+
+The iframe can be shown whether or not the user is signed in. Create it when
+“More apps” is opened, naming the signed-in user in its fragment, and remove it
+on close so reopening loads current apps and preferences. Remove it when the
+host's own sign-in changes too, such as on sign-out, so an open embed doesn't
+keep the previous user. The host owns the modal and close control;
+there is no parent messaging API and no app list or credential is sent to it.
+The app browser fills its iframe and responds to its size. It shows a spinner until its apps load.
+
+This example assumes `puterOrigin` comes from the host app's deployment
+settings. Translate the button and frame labels using the host app's
+localization system.
+
+```html
+<button id="more-apps" type="button">More apps</button>
+<dialog id="apps-dialog" aria-label="More apps">
+  <button id="close-apps" type="button">Close</button>
+  <div id="apps-frame"></div>
+</dialog>
+<style>
+  #apps-dialog { padding: 12px; width: min(900px, 90vw); }
+  #apps-frame iframe { width: 100%; height: min(650px, 75vh); border: 0; }
+</style>
+<script type="module">
+  const puterOrigin = 'https://puter.com'; // Use this deployment's configured origin.
+  const dialog = document.querySelector('#apps-dialog');
+  const container = document.querySelector('#apps-frame');
+  const trigger = document.querySelector('#more-apps');
+
+  trigger.addEventListener('click', async () => {
+    const url = new URL('/embed/apps', puterOrigin);
+    // Signed out, the embed shows the recommended apps.
+    const user = puter.auth.isSignedIn() ? await puter.auth.getUser().catch(() => null) : null;
+    if (user) url.hash = `user=${encodeURIComponent(user.uuid)}`;
+    const frame = document.createElement('iframe');
+    frame.title = 'Your apps';
+    frame.src = url.href;
+    container.replaceChildren(frame);
+    dialog.showModal();
+  });
+  document.querySelector('#close-apps').addEventListener('click', () => dialog.close());
+  dialog.addEventListener('close', () => {
+    container.replaceChildren();
+    trigger.focus();
+  });
+</script>
+```
+
+## Implementation
+
+`createAppBrowser` in `src/gui/src/UI/Dashboard/AppBrowser.js` owns the shared UI
+and data behavior; its `guestApps` option is the signed-out list. `TabApps.js`
+injects desktop actions. `appsEmbed.js` supplies new-tab launching through
+`launchAppInTab` (signed in) and `guestAppLaunchUrl` (signed out) in
+`src/gui/src/helpers/appTabLaunch.js`, which build the same app URL as
+`launch_app`, and loads only the embed entry, its SDK, and shared styles. `embedHostUser` in
+`src/gui/src/helpers/embedHostUser.js` reads the host's user from the fragment, and
+`embedHostTheme.js` beside it applies the host's theme.
+The normal GUI webpack build emits `bundle.min.js`, `apps-embed.min.js`, and `feedback-embed.min.js`.
+The `/embed/apps` route puts the recommended list in the page's config as
+`guestApps`. No puter.js API or app-list endpoint changes are needed.
+
+## Feedback dialog
+
+`GET /embed/feedback` is the app feedback dialog (`puter.ui.showFeedbackDialog()`)
+for a first-party page, with the same framing rules, query redirect, and
+host-user binding as `/embed/apps`. It sends the feedback for the framing
+page's origin, which the server reads from the referrer and pins with
+`frame-ancestors`; opened top-level, it does nothing. Its page is transparent
+so the dialog's own scrim covers the host.
+
+puter.js uses it on a page one label under the GUI origin, other than the
+subdomains the server refuses, when the page is signed in, framing it in a
+modal `<dialog>` that stays hidden until the embed is ready. A session check that takes longer than 200ms shows a loading scrim
+with a spinner in its place; Escape or a click on it cancels. The embed posts `{ msg: 'feedbackEmbed', state }` to its parent
+(`loading`, then `ready` or `unavailable`) and finally
+`{ msg: 'feedbackDialogClosed', sent }`. It reports `unavailable` without the
+named user's session, or while that user's email still needs confirming, and
+puter.js then uses the `/action/send-feedback` popup, which can sign in. So does
+a frame that never answers, such as one the host's CSP blocks. `feedbackEmbed.js`
+is the entry, sharing `embedSession` in `src/gui/src/helpers/embedSession.js`
+with the app browser; `showFeedbackEmbed` in `src/puter-js/src/lib/guiEmbed.js`
+is the host side.
+
+## Sign-in and file pickers
+
+`GET /embed/sign-in`, `/embed/show-open-file-picker`, `/embed/show-save-file-picker`
+and `/embed/show-directory-picker` serve the same GUI popups as `/action/<action>`
+for a first-party page, with the same framing rules, query redirect, and
+`no-store` as `/embed/apps`. Any other spelling of the path (another case, a
+trailing slash) redirects to it, since the shell boots the desktop for it. They render the normal GUI shell, which names the
+framing page (read from the referrer, pinned with `frame-ancestors`) as
+`gui_params.embed_host_origin`. The GUI then runs the popup boot unchanged, with
+the framing page as `window.opener`, and `window.close()` asks the page to
+remove the frame (`src/gui/src/helpers/popupFrame.js`). Without a framing page
+to answer (opened top-level, or framed by a refused page) it does nothing. The
+popup's parameters come from the fragment instead of the query: `msg_id`,
+`options` and `request_auth`, plus `user` for a picker.
+
+The frame posts `{ msg: 'puterPopupFrame', state }` to its parent: `loading` as
+soon as the shell boots, `ready` once it shows a window or dialog, `unavailable`
+when the page has to use the popup, `provider` when the user picks a sign-in
+provider (below), and `closed` where a popup would close. Its
+answers (`puter.token`, `fileOpenPicked`, `directoryPicked`, `fileSaved`, the
+cancel messages, `sendMeFileData`) are the popup's.
+
+puter.js uses them on a page one label under the GUI origin, other than the
+subdomains the server refuses, unless the page is cross-origin isolated or in a
+frame of another site (which `frame-ancestors` refuses too).
+`showPopupFrame` in `src/puter-js/src/lib/guiEmbed.js` shows the frame in a box
+the size of the popup window, over a scrim, hidden until `ready` and behind the
+loading spinner after 200ms. Escape closes it, on the page or in the frame. One shows per popup, as each
+popup has its own window name: a second picker request of the same kind
+replaces the one showing, and a `signIn()` call made while a framed sign-in is
+open settles with it. On
+screens up to 600px wide the box fills the screen. A frame that is refused,
+never answers, or reports `unavailable` falls back to the popup, opened through
+a consent dialog when the click that asked for it has expired. A reload or navigation the frame
+starts itself (logging out, a sign-out in another tab) names the frame as its
+referrer, so the server refuses it; the page then shows its spinner and opens
+the frame again, once per `ready`.
+
+- **Sign-in** (`puter.auth.signIn()`) has no host-user binding: it is how the
+  page gets a user. The box has a close button, which rejects with
+  `auth_window_closed` as closing the popup does. Providers refuse to be
+  framed, so choosing one posts `{ state: 'provider', url }` with the
+  provider's start URL for this sign-in's `msg_id`, then `unavailable`. The
+  page opens the popup straight at that URL, once it checks the URL is the
+  GUI's `/auth/oidc/<provider>/start` for this `msg_id`, and the provider
+  returns it as this sign-in's popup. `attempt_temp_user_creation` keeps the popup, since
+  only the popup creates a temporary account.
+- **Pickers** frame only for a signed-in page. The GUI reports `unavailable`
+  unless its session belongs to the user named in `user`, and the page then uses
+  the popup, which can sign in and switch accounts. The token the GUI sends
+  before a picker's answer isn't adopted, since it is for the page's own user.
+  Dismissing the loading scrim settles the picker as cancelled.
+
+## Upgrade
+
+`GET /embed/upgrade` is the deployment's upgrade dialog for a first-party page,
+served like the popups above: the GUI shell with the same framing rules, query
+redirect, exact-path redirect and `no-store`, naming the framing page as
+`gui_params.embed_host_origin`. It runs only when framed by an allowed page.
+
+puter.js frames it on a signed-in first-party page (the same pages as the
+pickers) for `puter.ui.requestUpgrade(details)`, and for the Upgrade button of
+the usage limit dialog a refused call shows there. Elsewhere both keep their
+behavior: inside an app `requestUpgrade()` asks the desktop, and on any other
+page the usage limit dialog opens the dashboard's upgrade page in a new tab.
+
+The frame covers the page with no box or close button, and the GUI page is
+transparent (`html.popup-frame-transparent`) so the dialog's own scrim covers
+the host. The frame allows `payment` as well as `otp-credentials`. Escape on the
+page is left to the dialog, since one there shouldn't drop a payment in
+progress. Its fragment names `user` (the page's signed-in user) and, when the
+refusal gave them, `reason` (`funds`, `subscription` or `storage`) and `method`.
+
+The GUI reports `unavailable` unless its session belongs to `user`, the account
+has no verification or password change waiting (which the frame couldn't be
+closed from), and the deployment defines `window.UIUpgradeAccount` with
+`UIUpgradeAccount.embeddable === true`. Otherwise it runs:
+
+```js
+new UIUpgradeAccount({ attribution: { appUid, reason, method }, onClose }).open_as_window();
+```
+
+`appUid` is the app the framing page's origin resolves to, never one the
+fragment names. `open_as_window()` resolves once the dialog shows, and the GUI
+then posts `ready`. While the page still hides the frame, which Chromium and
+WebKit lay out at 0x0, the GUI posts `ready` first and opens the dialog once
+the frame has a viewport, so a window it opens doesn't center on 0x0.
+`onClose({ upgraded })` must run exactly once, when the
+dialog closes or when it declines to open for the account; the GUI then posts
+`{ msg: 'puterPopupFrame', state: 'closed', upgraded }` and the page removes
+the frame. If `open_as_window()` rejects, the GUI posts `unavailable` instead. `requestUpgrade()` resolves `{ upgraded }`. A call made while the
+frame shows settles with it rather than replacing it, and a call refused while
+it shows still rejects but opens no usage limit dialog over it.
+
+When the frame can't show the upgrade (refused, never ready, `unavailable`, or
+no user to name), puter.js opens the dashboard's upgrade page in a new tab with
+what was refused, through a consent dialog when the click has expired or the
+tab is blocked, and `requestUpgrade()` resolves `{ upgraded: false }`.
+
+## Top-up
+
+`GET /embed/top-up` is the deployment's top-up dialog, where a user with a plan
+buys add-on credit, served and framed like the upgrade: a transparent GUI page
+covering the host with no box or close button, allowing `payment` and
+`otp-credentials`, with Escape left to the dialog. Its fragment names `user`.
+
+puter.js frames it for the **Add credits** item of `<puter-user-menu>`, which
+shows only when whoami reports `subscribed: true` and no `team` paying for the
+account. On a page that can't frame the GUI, the item opens the dashboard with
+`?topup=` in a new tab instead.
+
+The GUI reports `unavailable` unless its session belongs to `user`, the account
+has no verification or password change waiting, and the deployment defines
+`window.UITopUp` with `UITopUp.embeddable === true`. Otherwise it runs:
+
+```js
+new UITopUp({ onClose }).open();
+```
+
+`open()` resolves once the dialog has loaded the account and shows what it can
+buy, and `onClose({ toppedUp })` must run exactly once, when the dialog closes
+or when it declines to open for the account. The GUI then posts `{ msg: 'puterPopupFrame', state: 'closed', toppedUp }`
+and the page removes the frame. When the frame can't show the top-up, puter.js
+opens the dashboard's top-up in a new tab, as it does the upgrade.
+
+While the top-up shows, a call refused for funds still rejects but opens no
+usage limit dialog over it, and `requestUpgrade()` frames nothing over it: it
+resolves `{ upgraded: false }` once the top-up closes.
+
+## Email confirmation
+
+`GET /embed/request-email-confirmation` walks a first-party page's user through
+confirming their email, served like the upgrade: the GUI shell with the same
+framing rules, redirects and `no-store`, run only when framed by an allowed
+page. puter.js frames it on a signed-in first-party page for
+`puter.ui.requestEmailConfirmation()`. Inside an app the desktop shows the same
+windows over the app instead.
+
+Like the upgrade, the frame covers the page with no box or close button, over a
+transparent GUI page, and its fragment names `user`. Escape closes it, on the
+page or on the save-account or code window. On a window, Escape closes that
+window as its close button does, so a code already sent still answers. The GUI
+reports `unavailable` unless its session belongs to `user` and the account has
+no phone, card or password check waiting.
+An email check is fine: the boot skips its own email gate for this action, so
+the user gets one code window they can close.
+
+The GUI then runs `ensureConfirmedEmail` (`src/gui/src/helpers/ensureConfirmedEmail.js`),
+which the desktop's handler uses too: a temporary account gets the save-account
+window first, then an unconfirmed email gets the code window, each at most
+once. When the page's whoami already reads the email as confirmed,
+`requestEmailConfirmation()` resolves `{ response: true }` without framing
+anything, and a confirmation in the frame marks that whoami confirmed for the
+calls after it. An email the GUI reads as confirmed shows nothing. Before
+opening a window the GUI waits for the frame to have a viewport, as the upgrade
+does. It then posts
+`{ msg: 'puterPopupFrame', state: 'closed', confirmed }`, and
+`requestEmailConfirmation()` resolves `{ response: confirmed }`, the field an
+app reads from the desktop's answer. A call made while the frame shows settles
+with it. A frame that is refused, never ready, or `unavailable` resolves
+`{ response: false }`, since there's no popup to fall back to.
+
+## Custom domains
+
+`GET /embed/attach-custom-domain` is the custom domain dialog of
+`puter.hosting.attach()`, the popup at `/action/attach-custom-domain`, served
+like the upgrade: the GUI shell with the same framing rules, redirects and
+`no-store`, run only when framed by an allowed page. puter.js frames it on a
+signed-in first-party page (the same pages as the pickers).
+
+The frame covers the page with no box or close button, over a transparent GUI
+page, so the dialog floats over the host with its own scrim as it does on the
+desktop. The frame allows `clipboard-write`, for the dialog's copy buttons, as
+well as `otp-credentials`. Escape on the page is left to the dialog, which
+doesn't close while a request is in flight. Its fragment names `user` (the
+page's signed-in user), `subdomain` (the site to attach a domain to) and
+`msg_id`.
+
+The GUI reports `unavailable` unless its session belongs to `user` and the
+account has no verification or password change waiting. It then runs the
+popup's action unchanged, with the framing page as the requester the dialog
+names: it posts `ready` once the dialog is on the page, answers
+`{ msg: 'customDomainAttached', domain, original_msg_id }` once the dialog has
+closed and its exit has played, and then posts `closed`. `domain` is the domain the user chose, or
+null. `attach()` resolves it. A frame that closes without an answer, or a
+loading scrim the user dismisses, resolves null.
+
+A call made while the frame shows resolves null without replacing it, as a
+second call does on the desktop. A frame that is refused, never ready, or
+`unavailable` falls back to the popup, which can sign in, through a consent
+dialog when the click has expired.
+
+## Checks
+
+Run the GUI component/browser tests (with the SDK bundle built and Playwright
+Chromium installed), and the backend route tests:
+
+```sh
+npx vitest run --config src/gui/vitest.config.js src/gui/src/UI/Dashboard/AppBrowser src/feedbackEmbed
+npx vitest run src/puter-js/src/lib/guiEmbed.test.js src/puter-js/src/modules/UI.showFeedbackDialog.test.js src/puter-js/src/modules/Auth.signInFrame.test.js src/puter-js/src/modules/UI.pickerFrame.test.js src/puter-js/src/modules/UI.requestUpgrade.test.js src/puter-js/src/modules/UI.showTopUp.test.js src/puter-js/src/modules/UI.attachCustomDomainFrame.test.js src/puter-js/src/lib/upgradePrompt.test.js src/puter-js/src/modules/UsageLimitDialog.upgrade.test.js
+npx vitest run --config src/gui/vitest.config.js src/gui/src/helpers/popupFrame.test.js
+npx vitest run --config src/backend/vitest.config.ts src/backend/server.test.ts
+```

doc/pagination.md

@@ -63,6 +63,9 @@ store:
   sealed cursor: the last `id` it returned, and the last `(replaced_at, id)`
   among rows up to that id. Each is its own indexed read, merged into one
   page, so a row replaced after a client read it comes back from that cursor.
+  `from=end` with no cursor answers an empty page whose cursor holds the
+  slice's newest `id` and the slice's latest `(replaced_at, id)` as the
+  replacement mark.
 
 Cursors that carry a sort also pin it: a request that passes a cursor plus a
 conflicting sort is rejected with 400.

doc/push-client.md

@@ -1,6 +1,6 @@
 # Browser push client
 
-Puter's desktop shows pushes through `/sw.js`. Core registers it, and shows Settings → Notifications, only when the `pushEnabled` gui param is `true`; core never sets it. A backend extension that delivers pushes sets it with `services.homepage.setGuiParam('pushEnabled', true)` and can load its own code into the worker with `services.homepage.registerServiceWorkerScript(path)`.
+Puter's desktop shows pushes through `/sw.js`. Core shows Settings → Notifications only when the `pushEnabled` gui param is `true`; core never sets it. The worker is registered only when push is turned on in the browser, and a load removes one left without a subscription. A backend extension that delivers pushes sets it with `services.homepage.setGuiParam('pushEnabled', true)` and can load its own code into the worker with `services.homepage.registerServiceWorkerScript(path)`.
 
 Core subscribes the browser to a push service only when the server also publishes `pushWebPushKey` (see [Built-in Web Push client](#built-in-web-push-client)), and it has no `/push/*` routes of its own. The device, app, preference and subscription endpoints below come from that extension. On a deployment without one, such as most self-hosted servers, they answer core's plain 404 (`code: 'not_found'`), which `puter.notifications` reports as `push_unavailable` and the Notifications tab shows as unavailable. A device the extension can't find is `device_not_found`.
 
@@ -22,12 +22,13 @@ When the browser replaces the subscription (`pushsubscriptionchange`), `sw.js` p
 
 Before a notification is pushed, the server asks the open clients whether they received it live. It sends `notif.receipt` with `{ uid }` on the user's sockets for the app that sent it, or on the desktop's sockets for Puter's own notifications. The SDK remembers the uids its page received through `onNotification()`, `onPush()` or the desktop's feed, and answers once its page has that notification, or with `{ received: false }` when it never gets it. The server waits up to 5 seconds (`notificationAckTimeoutMs`).
 
-An answer carries `visibilityState`, `focused` and `showsOwn`, the last being whether the page shows the notification itself. A website page shows it itself when it is hidden or unfocused, has an `onPush()` handler and notification permission, and no other tab of the same site is focused. Inside the desktop, the desktop shows it, and an app's `onPush()` result is never shown as a browser notification.
+An answer carries `visibilityState` and `focused` as they were when the page received the notification. Pages never show a browser notification themselves; pushes do.
 
-- An answer from a page that is visible and focused, or that shows the notification itself, stops the push.
-- Otherwise the notification is pushed. A website's pushes go only to the browsers that subscribed through its own worker, never to Puter's `/sw.js`. An app inside the desktop pushes through `/sw.js`, which shows the app's name and icon.
-- A hidden desktop tab shows no banner, so answers only from hidden desktop tabs don't stop a push of Puter's own notifications.
-- A client that can't answer, such as an older puter.js, holds the push back while it is connected.
+- An answer from a page that was visible and focused stops the push (`handled` on `notif.delivery.settled`). An older client that doesn't send `focused` counts while visible.
+- Otherwise the notification is pushed, to every browser the user subscribed. A website's pushes go only to the browsers that subscribed through its own worker, never to Puter's `/sw.js`. An app inside the desktop pushes through `/sw.js`, which shows the app's name and icon.
+- A client that can't answer, such as an older puter.js, doesn't hold the push back.
+
+The ask reaches only the sockets in the asking region. So that other regions hear about a page too, a page that receives a notification live while visible and focused also sends `notif.handled` with `{ uid }` on the socket it came on. Core relays it as the node-local `notif.handled` event with the socket's user and app, at most 60 a minute per user; an extension that delivers pushes decides what to do with it.
 
 ## Registering
 

extensions/whoami.test.ts

@@ -257,8 +257,41 @@ describe('whoami extension — handleWhoami', () => {
         expect(body.created_ts).toBeGreaterThan(0);
         // `directories` is only sent to user actors — confirm it’s present.
         expect(body.directories).toBeDefined();
-        // taskbar_items is only sent to user actors.
-        expect(body).toHaveProperty('taskbar_items');
+    });
+
+    it('leaves out taskbar items saved on the account', async () => {
+        const user = await seedUser();
+        await server.stores.user.update(user.id as number, {
+            taskbar_items: JSON.stringify([{ type: 'app', name: 'editor' }]),
+        });
+        const { res, captured } = makeRes();
+
+        await runWithContext(
+            { actor: { user: { uuid: user.uuid, id: user.id as number } } },
+            () => handleWhoami(makeReq(), res),
+        );
+
+        expect(captured.body).not.toHaveProperty('taskbar_items');
+    });
+
+    it('leaves out a desktop background saved on the account', async () => {
+        const user = await seedUser();
+        await server.stores.user.update(user.id as number, {
+            desktop_bg_url: 'https://cdn.test/wallpaper.png',
+            desktop_bg_color: '#000000',
+            desktop_bg_fit: 'cover',
+        });
+        const { res, captured } = makeRes();
+
+        await runWithContext(
+            { actor: { user: { uuid: user.uuid, id: user.id as number } } },
+            () => handleWhoami(makeReq(), res),
+        );
+
+        const body = captured.body as Record<string, unknown>;
+        expect(body).not.toHaveProperty('desktop_bg_url');
+        expect(body).not.toHaveProperty('desktop_bg_color');
+        expect(body).not.toHaveProperty('desktop_bg_fit');
     });
 
     it('reports the SMS-to-card fallback only once a send has opened it', async () => {
@@ -322,7 +355,7 @@ describe('whoami extension — handleWhoami', () => {
         expect(flags.payment_bypass).toBeUndefined();
     });
 
-    it('strips desktop_bg_*, created_ts and human_readable_age fields for app actors', async () => {
+    it('strips created_ts and human_readable_age fields for app actors', async () => {
         const user = await seedUser();
         const { res, captured } = makeRes();
 
@@ -340,9 +373,6 @@ describe('whoami extension — handleWhoami', () => {
         expect(body.app_name).toBe('app-test-actor');
         // is_user_token is stripped for app actors.
         expect(body.is_user_token).toBeUndefined();
-        expect(body.desktop_bg_url).toBeUndefined();
-        expect(body.desktop_bg_color).toBeUndefined();
-        expect(body.desktop_bg_fit).toBeUndefined();
         expect(body.human_readable_age).toBeUndefined();
         // Account age, in either form, is not exposed to apps.
         expect(body.created_ts).toBeUndefined();
@@ -432,7 +462,7 @@ describe('whoami extension — handleWhoami', () => {
             });
         });
 
-        it('cannot add taskbar_items for an app actor, which core omits', async () => {
+        it('cannot add directories for an app actor, which core omits', async () => {
             const user = await seedUser();
             const body = await whoamiWithListener(
                 makeActor({
@@ -440,11 +470,11 @@ describe('whoami extension — handleWhoami', () => {
                     app: { uid: 'app-test-actor' },
                 }),
                 (_key, event) => {
-                    event.details.taskbar_items = [{ name: 'injected' }];
+                    event.details.directories = { '/injected': 'uuid' };
                 },
             );
 
-            expect(body).not.toHaveProperty('taskbar_items');
+            expect(body).not.toHaveProperty('directories');
         });
     });
 
@@ -525,7 +555,7 @@ describe('whoami extension — handleWhoami', () => {
             expect(body.otp_secret).toBeUndefined();
             expect(body.signup_ip).toBeUndefined();
             // Not just absent as a key — the values must not appear anywhere
-            // in the payload (nested under metadata, taskbar items, …).
+            // in the payload (nested under metadata, …).
             const serialized = JSON.stringify(body);
             expect(serialized).not.toContain('5551234567');
             expect(serialized).not.toContain('fp_ABC123');

extensions/whoami.ts

@@ -1,6 +1,5 @@
 import { Context } from '@heyputer/backend/src/core';
 import { extension } from '@heyputer/backend/src/extensions';
-import { APP_ICON_SIZES } from '@heyputer/backend/src/util/appIcon.js';
 import {
     buildUserDetails,
     scrubSensitive,
@@ -54,19 +53,10 @@ export const handleWhoami = async (
         return;
     }
 
-    const rawIconSize =
-        typeof req.query?.icon_size === 'string'
-            ? Number(req.query.icon_size)
-            : undefined;
-    const iconSize =
-        rawIconSize !== undefined && APP_ICON_SIZES.includes(rawIconSize)
-            ? rawIconSize
-            : undefined;
-
     const details = await buildUserDetails(
         user,
         { config: extension.config, clients, stores, services },
-        { isUser, iconSize, noIcons: !iconSize },
+        { isUser },
     );
     details.human_readable_age = user.timestamp
         ? timeago.format(new Date(user.timestamp as string))
@@ -81,9 +71,6 @@ export const handleWhoami = async (
             delete details.email;
             delete details.unconfirmed_email;
         }
-        delete details.desktop_bg_url;
-        delete details.desktop_bg_color;
-        delete details.desktop_bg_fit;
         delete details.human_readable_age;
         delete details.created_ts;
         delete details.is_user_token;
@@ -121,8 +108,7 @@ export const handleWhoami = async (
     }
 
     const subscription = details.subscription as
-        | { offering?: Record<string, unknown> }
-        | undefined;
+        { offering?: Record<string, unknown> } | undefined;
     if (subscription?.offering) {
         delete subscription.offering.group;
         delete subscription.offering.benefits;

src/backend/clients/database/DatabaseClient.test.ts

@@ -285,6 +285,18 @@ describe('AbstractDatabaseClient — SQL generation', () => {
         );
     });
 
+    it('reads the database clock as epoch milliseconds in each dialect', () => {
+        expect(sqlite().nowMsExpr()).toBe(
+            "CAST((julianday('now') - 2440587.5) * 86400000 AS INTEGER)",
+        );
+        expect(mysql().nowMsExpr()).toBe(
+            "(TIMESTAMPDIFF(MICROSECOND, '1970-01-01 00:00:00', UTC_TIMESTAMP(6)) DIV 1000)",
+        );
+        expect(postgres().nowMsExpr()).toBe(
+            'CAST(EXTRACT(EPOCH FROM clock_timestamp()) * 1000 AS BIGINT)',
+        );
+    });
+
     it('describes a stored timestamp the way each driver reads it back', () => {
         const seconds = Date.UTC(2026, 9, 11, 8, 5, 9) / 1000;
         expect(sqlite().timestampValue(seconds)).toBe('2026-10-11 08:05:09');
@@ -306,3 +318,13 @@ describe('AbstractDatabaseClient — SQL generation', () => {
         );
     });
 });
+
+
+it('builds an insert for batchWrite and shares it with insert', async () => {
+    const client = new FixtureDatabaseClient([]);
+    const entry = client.insertEntry('widget', { name: "reader's", enabled: true });
+    expect(entry.values).toEqual(["reader's", true]);
+    expect(entry.statement).toContain('VALUES (?, ?)');
+    await client.insert('widget', { name: "reader's", enabled: true });
+    expect(client.writes).toEqual([{ query: entry.statement, params: entry.values }]);
+});

src/backend/clients/database/DatabaseClient.ts

@@ -110,14 +110,23 @@ export class AbstractDatabaseClient extends PuterClient {
         tableName: string,
         data: Record<string, unknown>,
     ): Promise<WriteResult> {
+        const entry = this.insertEntry(tableName, data);
+        return this.write(
+            entry.statement + this.returningIdClause(),
+            entry.values,
+        );
+    }
+
+    /** An insert that can join other writes in a transaction. */
+    insertEntry(tableName: string, data: Record<string, unknown>): BatchEntry {
         const cols = Object.keys(data);
-        const values = Object.values(data);
-        const sql =
-            `INSERT INTO ${this.quoteIdentifier(tableName)} ` +
-            `(${cols.map((c) => this.quoteIdentifier(c)).join(', ')}) ` +
-            `VALUES (${cols.map(() => '?').join(', ')})` +
-            this.returningIdClause();
-        return this.write(sql, values);
+        return {
+            statement:
+                `INSERT INTO ${this.quoteIdentifier(tableName)} ` +
+                `(${cols.map((c) => this.quoteIdentifier(c)).join(', ')}) ` +
+                `VALUES (${cols.map(() => '?').join(', ')})`,
+            values: Object.values(data),
+        };
     }
 
     /** Whether `read()` goes to a separate replica rather than the primary. */
@@ -401,6 +410,21 @@ export class AbstractDatabaseClient extends PuterClient {
         });
     }
 
+    /**
+     * The database's own clock as epoch milliseconds, so nodes whose clocks
+     * disagree still agree on it. The mysql form ignores the session time zone,
+     * so a DST change can't shift it.
+     */
+    nowMsExpr(): string {
+        return this.case({
+            sqlite: "CAST((julianday('now') - 2440587.5) * 86400000 AS INTEGER)",
+            postgres:
+                'CAST(EXTRACT(EPOCH FROM clock_timestamp()) * 1000 AS BIGINT)',
+            otherwise:
+                "(TIMESTAMPDIFF(MICROSECOND, '1970-01-01 00:00:00', UTC_TIMESTAMP(6)) DIV 1000)",
+        });
+    }
+
     /**
      * What a read of a timestamp column holding `seconds` returns: sqlite gives
      * back the UTC text it stored, mysql2 and pg a `Date` read in node's time

src/backend/clients/database/SqliteDatabaseClient.test.ts

@@ -27,7 +27,7 @@ import { DatabaseClientFactory } from './index.js';
 import { SqliteDatabaseClient } from './SqliteDatabaseClient.js';
 
 /** Highest schema version the migration table can reach. */
-const CURRENT_SCHEMA_VERSION = 95;
+const CURRENT_SCHEMA_VERSION = 98;
 
 /**
  * These suites migrate real files on disk. Idle they finish in well under a
@@ -724,6 +724,85 @@ describe('SqliteDatabaseClient — boot and migrations', { timeout: DISK_MIGRATI
         ]);
     });
 
+    it('keeps notification.send_key unique', async () => {
+        const rows = await client.read('PRAGMA index_list(`notification`)');
+        expect(
+            rows.find((r) => r.name === 'idx_notification_send_key'),
+        ).toMatchObject({ unique: 1 });
+        const columns = await client.read(
+            'PRAGMA index_info(`idx_notification_send_key`)',
+        );
+        expect(columns.map((c) => String(c.name))).toEqual(['send_key']);
+    });
+
+    it('creates event_user_handlers with its unique and holder indexes', async () => {
+        const columns = await client.read(
+            'PRAGMA table_info(`event_user_handlers`)',
+        );
+        expect(columns.map((c) => String(c.name))).toEqual([
+            'id',
+            'app_uid',
+            'holder_user_id',
+            'name',
+            'source',
+            'source_hash',
+            'created_at',
+            'updated_at',
+            'scope_since',
+        ]);
+        const indexes = await client.read(
+            'PRAGMA index_list(`event_user_handlers`)',
+        );
+        expect(
+            indexes.find(
+                (i) => i.name === 'idx_event_user_handlers_app_holder_name',
+            ),
+        ).toMatchObject({ unique: 1 });
+        expect(
+            indexes.find((i) => i.name === 'idx_event_user_handlers_holder_app'),
+        ).toMatchObject({ unique: 0 });
+        const columnsOf = async (index: string) =>
+            (await client.read(`PRAGMA index_info(\`${index}\`)`)).map((c) =>
+                String(c.name),
+            );
+        expect(await columnsOf('idx_event_user_handlers_app_holder_name')).toEqual(
+            ['app_uid', 'holder_user_id', 'name'],
+        );
+        expect(await columnsOf('idx_event_user_handlers_holder_app')).toEqual([
+            'holder_user_id',
+            'app_uid',
+        ]);
+    });
+
+    it('leaves event_handlers as it was', async () => {
+        const columns = await client.read('PRAGMA table_info(`event_handlers`)');
+        expect(columns.map((c) => String(c.name))).toEqual([
+            'id',
+            'app_uid',
+            'name',
+            'source',
+            'source_hash',
+            'created_at',
+            'updated_at',
+        ]);
+    });
+
+    it('adds event_subscriptions.handler_scope, app scope for existing rows', async () => {
+        const columns = await client.read(
+            'PRAGMA table_info(`event_subscriptions`)',
+        );
+        expect(columns.find((c) => c.name === 'handler_scope')).toMatchObject({
+            notnull: 1,
+            dflt_value: '0',
+        });
+        const indexes = await client.read(
+            'PRAGMA index_list(`event_subscriptions`)',
+        );
+        expect(indexes.map((i) => String(i.name))).toContain(
+            'idx_event_subscriptions_holder',
+        );
+    });
+
     it('leaves an already-migrated database untouched on a second boot', async () => {
         const dir = mkdtempSync(join(tmpdir(), 'puter-sqlite-'));
         const path = join(dir, 'nested', 'puter.sqlite');

src/backend/clients/database/SqliteDatabaseClient.ts

@@ -134,6 +134,9 @@ const AVAILABLE_MIGRATIONS: [number, string[]][] = [
     [92, ['0097_user-to-user-holder-permission-index.sql']],
     [93, ['0098_notification-groups.sql']],
     [94, ['0099_kv-share-handle-notify.sql']],
+    [95, ['0100_notification-send-key.sql']],
+    [96, ['0101_user-scoped-handlers.sql']],
+    [97, ['0102_notification-scope-id-index.sql']],
 ];
 
 export class SqliteDatabaseClient extends AbstractDatabaseClient {

src/backend/clients/database/migrations/mysql/mysql_mig_54.sql

@@ -0,0 +1,43 @@
+-- Copyright (C) 2024-present Puter Technologies Inc.
+--
+-- This file is part of Puter.
+--
+-- Puter is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU Affero General Public License as published
+-- by the Free Software Foundation, either version 3 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU Affero General Public License for more details.
+--
+-- You should have received a copy of the GNU Affero General Public License
+-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+-- `notification`.`send_key`. See sqlite/0100_notification-send-key.sql for the
+-- rationale. The key is a uuid, so ascii and compared byte for byte. No
+-- per-file applied-state tracking, so every step is guarded and a replay does
+-- nothing.
+
+CALL _puter_add_col('notification', 'send_key', '`send_key` char(36) CHARACTER SET ascii COLLATE ascii_bin DEFAULT NULL');
+
+DROP PROCEDURE IF EXISTS _puter_add_notification_send_key_index;
+DELIMITER //
+CREATE PROCEDURE _puter_add_notification_send_key_index()
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM INFORMATION_SCHEMA.STATISTICS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = 'notification'
+      AND INDEX_NAME = 'idx_notification_send_key'
+  ) THEN
+    ALTER TABLE `notification` ADD UNIQUE KEY `idx_notification_send_key`
+      (`send_key`), ALGORITHM=INPLACE, LOCK=NONE;
+  END IF;
+END//
+DELIMITER ;
+
+CALL _puter_add_notification_send_key_index();
+
+DROP PROCEDURE IF EXISTS _puter_add_notification_send_key_index;

src/backend/clients/database/migrations/mysql/mysql_mig_55.sql

@@ -0,0 +1,66 @@
+-- Copyright (C) 2024-present Puter Technologies Inc.
+--
+-- This file is part of Puter.
+--
+-- Puter is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU Affero General Public License as published
+-- by the Free Software Foundation, either version 3 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU Affero General Public License for more details.
+--
+-- You should have received a copy of the GNU Affero General Public License
+-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+-- Handlers an app's user published into their own scope, kept apart from
+-- `event_handlers` so code that predates them never reads them. See
+-- sqlite/0101_user-scoped-handlers.sql for the column rationale.
+--
+-- Idempotent: `CREATE TABLE IF NOT EXISTS` with the indexes declared inline,
+-- and a guarded column add. There is no per-file applied-state tracking, so a
+-- replay has to be a no-op.
+
+CREATE TABLE IF NOT EXISTS `event_user_handlers` (
+    `id` bigint unsigned NOT NULL AUTO_INCREMENT,
+    -- Matches `apps`.`uid` exactly, charset included, so an equality against
+    -- one never falls back to a conversion.
+    `app_uid` char(40) CHARACTER SET latin1 COLLATE latin1_swedish_ci NOT NULL,
+    `holder_user_id` int unsigned NOT NULL,
+    `name` varchar(128) NOT NULL,
+    `source` mediumtext NOT NULL,
+    `source_hash` char(64) NOT NULL,
+    `created_at` bigint NOT NULL,
+    `updated_at` bigint NOT NULL,
+    -- When the scope first held a handler; kept across handler churn, so the
+    -- rent sweep sees the scope's age, not its oldest remaining handler's.
+    `scope_since` bigint NOT NULL,
+    PRIMARY KEY (`id`),
+    UNIQUE KEY `idx_event_user_handlers_app_holder_name` (`app_uid`, `holder_user_id`, `name`),
+    KEY `idx_event_user_handlers_holder_app` (`holder_user_id`, `app_uid`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- Guarded here rather than through `_puter_add_col`, so the file also applies
+-- on its own to a database that never ran the earlier migrations.
+DROP PROCEDURE IF EXISTS _puter_add_event_subscriptions_handler_scope;
+DELIMITER //
+CREATE PROCEDURE _puter_add_event_subscriptions_handler_scope()
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM INFORMATION_SCHEMA.COLUMNS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = 'event_subscriptions'
+      AND COLUMN_NAME = 'handler_scope'
+  ) THEN
+    ALTER TABLE `event_subscriptions`
+      ADD COLUMN `handler_scope` tinyint unsigned NOT NULL DEFAULT 0,
+      ALGORITHM=INSTANT;
+  END IF;
+END//
+DELIMITER ;
+
+CALL _puter_add_event_subscriptions_handler_scope();
+
+DROP PROCEDURE IF EXISTS _puter_add_event_subscriptions_handler_scope;

src/backend/clients/database/migrations/mysql/mysql_mig_56.sql

@@ -0,0 +1,41 @@
+-- Copyright (C) 2024-present Puter Technologies Inc.
+--
+-- This file is part of Puter.
+--
+-- Puter is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU Affero General Public License as published
+-- by the Free Software Foundation, either version 3 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU Affero General Public License for more details.
+--
+-- You should have received a copy of the GNU Affero General Public License
+-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+-- `notification` (`user_id`, `audience`, `app_uid`, `id`). See
+-- sqlite/0102_notification-scope-id-index.sql for the rationale. No per-file
+-- applied-state tracking, so the index is added only when missing and a
+-- replay does nothing.
+
+DROP PROCEDURE IF EXISTS _puter_add_notification_scope_id_index;
+DELIMITER //
+CREATE PROCEDURE _puter_add_notification_scope_id_index()
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM INFORMATION_SCHEMA.STATISTICS
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND TABLE_NAME = 'notification'
+      AND INDEX_NAME = 'idx_notification_scope_id'
+  ) THEN
+    ALTER TABLE `notification` ADD INDEX `idx_notification_scope_id`
+      (`user_id`, `audience`, `app_uid`, `id`), ALGORITHM=INPLACE, LOCK=NONE;
+  END IF;
+END//
+DELIMITER ;
+
+CALL _puter_add_notification_scope_id_index();
+
+DROP PROCEDURE IF EXISTS _puter_add_notification_scope_id_index;

src/backend/clients/database/migrations/postgres/postgres_mig_43.sql

@@ -0,0 +1,24 @@
+-- Copyright (C) 2024-present Puter Technologies Inc.
+--
+-- This file is part of Puter.
+--
+-- Puter is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU Affero General Public License as published
+-- by the Free Software Foundation, either version 3 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU Affero General Public License for more details.
+--
+-- You should have received a copy of the GNU Affero General Public License
+-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+-- notification.send_key. See sqlite/0100_notification-send-key.sql for the
+-- rationale. Idempotent via IF NOT EXISTS.
+
+ALTER TABLE notification ADD COLUMN IF NOT EXISTS send_key char(36) DEFAULT NULL;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_notification_send_key
+    ON notification (send_key);

src/backend/clients/database/migrations/postgres/postgres_mig_44.sql

@@ -0,0 +1,39 @@
+-- Copyright (C) 2024-present Puter Technologies Inc.
+--
+-- This file is part of Puter.
+--
+-- Puter is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU Affero General Public License as published
+-- by the Free Software Foundation, either version 3 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU Affero General Public License for more details.
+--
+-- You should have received a copy of the GNU Affero General Public License
+-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+-- Handlers an app's user published into their own scope. See
+-- sqlite/0101_user-scoped-handlers.sql for the column rationale.
+-- Idempotent via IF NOT EXISTS.
+
+CREATE TABLE IF NOT EXISTS event_user_handlers (
+    id BIGSERIAL PRIMARY KEY,
+    app_uid VARCHAR(40) NOT NULL,
+    holder_user_id INTEGER NOT NULL,
+    name VARCHAR(128) NOT NULL,
+    source TEXT NOT NULL,
+    source_hash VARCHAR(64) NOT NULL,
+    created_at BIGINT NOT NULL,
+    updated_at BIGINT NOT NULL,
+    scope_since BIGINT NOT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_event_user_handlers_app_holder_name
+    ON event_user_handlers (app_uid, holder_user_id, name);
+CREATE INDEX IF NOT EXISTS idx_event_user_handlers_holder_app
+    ON event_user_handlers (holder_user_id, app_uid);
+
+ALTER TABLE event_subscriptions ADD COLUMN IF NOT EXISTS handler_scope smallint NOT NULL DEFAULT 0;

src/backend/clients/database/migrations/postgres/postgres_mig_45.sql

@@ -0,0 +1,23 @@
+-- Copyright (C) 2024-present Puter Technologies Inc.
+--
+-- This file is part of Puter.
+--
+-- Puter is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU Affero General Public License as published
+-- by the Free Software Foundation, either version 3 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU Affero General Public License for more details.
+--
+-- You should have received a copy of the GNU Affero General Public License
+-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+-- notification (user_id, audience, app_uid, id). See
+-- sqlite/0102_notification-scope-id-index.sql for the rationale. Idempotent via
+-- IF NOT EXISTS.
+
+CREATE INDEX IF NOT EXISTS idx_notification_scope_id
+    ON notification (user_id, audience, app_uid, id);

src/backend/clients/database/migrations/sqlite/0100_notification-send-key.sql

@@ -0,0 +1,27 @@
+-- Copyright (C) 2024-present Puter Technologies Inc.
+--
+-- This file is part of Puter.
+--
+-- Puter is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU Affero General Public License as published
+-- by the Free Software Foundation, either version 3 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU Affero General Public License for more details.
+--
+-- You should have received a copy of the GNU Affero General Public License
+-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+-- `notification`.`send_key`: the key of the delayed send (a `deferred`
+-- schedule) that wrote this row or last replaced it, derived from the
+-- schedule and its slot. Unique, so one slot can never write two rows, and a
+-- send that crashed after writing finds its row again by it. Null on every row
+-- a delayed send never touched.
+
+ALTER TABLE `notification` ADD COLUMN `send_key` TEXT DEFAULT NULL;
+
+CREATE UNIQUE INDEX IF NOT EXISTS `idx_notification_send_key`
+    ON `notification` (`send_key`);

src/backend/clients/database/migrations/sqlite/0101_user-scoped-handlers.sql

@@ -0,0 +1,48 @@
+-- Copyright (C) 2024-present Puter Technologies Inc.
+--
+-- This file is part of Puter.
+--
+-- Puter is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU Affero General Public License as published
+-- by the Free Software Foundation, either version 3 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU Affero General Public License for more details.
+--
+-- You should have received a copy of the GNU Affero General Public License
+-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+-- Handlers an app's user published into their own scope, in a table of their
+-- own so `event_handlers` stays the app owner's set. Same columns as
+-- `event_handlers` (see 0076_event-handlers.sql) plus the holder.
+--
+--   - `holder_user_id` : the user whose scope this is. A name is unique per
+--                        (app, holder), so the same name can live in the app's
+--                        set and in each holder's.
+--   - `(holder_user_id, app_uid)` : a holder's scopes, for listing and for the
+--                        rent count.
+--
+-- `event_subscriptions.handler_scope` says which table a row's `handler_name`
+-- refers to: 0 the app's set, 1 the row holder's scope.
+
+CREATE TABLE IF NOT EXISTS `event_user_handlers` (
+    "id" INTEGER PRIMARY KEY AUTOINCREMENT,
+    "app_uid" TEXT NOT NULL,
+    "holder_user_id" INTEGER NOT NULL,
+    "name" TEXT NOT NULL,
+    "source" TEXT NOT NULL,
+    "source_hash" TEXT NOT NULL,
+    "created_at" INTEGER NOT NULL,    -- unix seconds
+    "updated_at" INTEGER NOT NULL,
+    "scope_since" INTEGER NOT NULL    -- unix seconds; the scope's first handler, kept across churn
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS `idx_event_user_handlers_app_holder_name`
+    ON `event_user_handlers` (`app_uid`, `holder_user_id`, `name`);
+CREATE INDEX IF NOT EXISTS `idx_event_user_handlers_holder_app`
+    ON `event_user_handlers` (`holder_user_id`, `app_uid`);
+
+ALTER TABLE `event_subscriptions` ADD COLUMN `handler_scope` INTEGER NOT NULL DEFAULT 0;

src/backend/clients/database/migrations/sqlite/0102_notification-scope-id-index.sql

@@ -0,0 +1,22 @@
+-- Copyright (C) 2024-present Puter Technologies Inc.
+--
+-- This file is part of Puter.
+--
+-- Puter is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU Affero General Public License as published
+-- by the Free Software Foundation, either version 3 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU Affero General Public License for more details.
+--
+-- You should have received a copy of the GNU Affero General Public License
+-- along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+-- Index a mailbox slice by row id, so a fetch finds the newest row of a slice,
+-- and pages forward through one, with a seek rather than a scan of the slice.
+
+CREATE INDEX IF NOT EXISTS `idx_notification_scope_id`
+    ON `notification` (`user_id`, `audience`, `app_uid`, `id`);

src/backend/clients/event/types.ts

@@ -117,7 +117,7 @@ export type EventMap = {
         model_used: string;
         service_used: string;
         intended_service: string;
-        model_details: {
+        model_details?: {
             id: string;
             provider: string;
             input_cost_key: string;
@@ -200,6 +200,16 @@ export type EventMap = {
     };
 
     // ---- Auth / signup ----
+    /**
+     * Which signup methods are open, emitted via `emitAndWait` before every
+     * signup and whenever the GUI reads the provider list. A listener sets
+     * `oidcOnly` to refuse form and temp signups, leaving OIDC and team
+     * provisioning open; `message` is what a refused form signup is told.
+     */
+    'puter.signup.policy': {
+        oidcOnly: boolean;
+        message: string | null;
+    };
     'puter.signup.validate': {
         allow: boolean;
         email?: string;
@@ -410,7 +420,11 @@ export type EventMap = {
         old_username: string;
         new_username: string;
     };
-    'user.email-changed': { user_id: number; new_email: string };
+    'user.email-changed': {
+        user_id: number;
+        old_email: string | null;
+        new_email: string;
+    };
     /** An account was suspended, or its suspension lifted. Local events. */
     'user.suspended': { userId: number };
     'user.unsuspended': { userId: number };
@@ -546,6 +560,14 @@ export type EventMap = {
     'kv.share.retired': { handles: string[]; userId: number };
 
     // ---- Notifications ----
+    /** An app message was acknowledged after its state committed. */
+    'notif.acknowledged': {
+        userId: number;
+        uid: string;
+        type: string;
+        audience: string;
+        appUid: string;
+    };
     /**
      * A notification row exists. Emitted after the insert commits — nothing
      * pushes a uid before there is a row to name — and carries the scope tuple
@@ -579,8 +601,12 @@ export type EventMap = {
         value: Record<string, unknown>;
         /** An earlier notification rewritten in place. */
         updated?: true;
+        /** Replaced an earlier notification in its group. */
+        replaced?: true;
         /** Names this one send, for a receipt asked about it. */
         sendId: string;
+        /** The same `sendId` may be emitted again, as a delayed send is. */
+        replayable?: true;
     };
     /**
      * One notification, addressed at whatever sockets each region holds for the
@@ -614,6 +640,18 @@ export type EventMap = {
         /** A peer region holds a socket for the user. */
         peerRegions: boolean;
         responders: NotifDeliveryResponder[];
+        /** A page here got it live while visible and focused. */
+        handled: boolean;
+    };
+    /**
+     * A page reported that it got a notification live while visible and
+     * focused. Node-local; `appUid` is the reporting socket's app, absent for
+     * the desktop.
+     */
+    'notif.handled': {
+        userId: number;
+        appUid?: string;
+        uid: string;
     };
 
     // ---- Metering ----
@@ -664,9 +702,18 @@ export type EventMap = {
     // and going away (1→0, whether by removing the last handler or by the
     // destroy route). `actor.user` is the app's owner, not the caller — a
     // developer session publishing for an app it owns is the common case, but
-    // billing follows ownership.
-    'events.worker.create': { actor: Actor; appUid: string };
-    'events.worker.destroy': { actor: Actor; appUid: string };
+    // billing follows ownership. For `scope: 'user'` the unit is one user's
+    // handlers in one app instead, and `actor.user` is that user.
+    'events.worker.create': {
+        actor: Actor;
+        appUid: string;
+        scope: 'app' | 'user';
+    };
+    'events.worker.destroy': {
+        actor: Actor;
+        appUid: string;
+        scope: 'app' | 'user';
+    };
 
     // ---- Outer / GUI broadcast ----
     'outer.cacheUpdate': {
@@ -830,6 +877,12 @@ export type EventMap = {
     /** One access token was revoked; only its own connections should drop. */
     'auth.access-token.revoked': { token_uid: string };
 
+    /** Same-cluster eviction for raw realtime WebSockets. */
+    'pubsub.realtime.auth-revoked': {
+        sessionUids?: string[];
+        tokenUid?: string;
+    };
+
     /**
      * A grant was withdrawn, so whatever was standing on it has to be settled
      * rather than left to fail its next check.
@@ -1055,11 +1108,6 @@ export interface NotifDeliveryResponder {
     visibilityState: 'visible' | 'hidden' | 'unknown';
     /** The page's window has focus. Absent from older clients. */
     focused?: boolean;
-    /**
-     * The page shows its own browser notification while hidden or unfocused.
-     * Absent from older clients.
-     */
-    showsOwn?: boolean;
 }
 
 export type EventMetadata = {

src/backend/clients/events/EventsWorkerInvokerClient.ts

@@ -35,6 +35,7 @@ import { PuterClient } from '../types.js';
  *     x-puter-internal-auth:  <internal secret>
  *     x-puter-events-script:  <script the handler set deploys as>
  *     x-puter-events-app:     <app uid, for the deploy-on-miss callback>
+ *     x-puter-events-holder:  <holder uuid of a user scope; absent for app scope>
  *     x-puter-events-key:     <key derived for that script>
  *     { handler, event, ctx, token }
  *
@@ -43,6 +44,20 @@ import { PuterClient } from '../types.js';
  *
  * On a miss, a handler set here may deploy the script itself and retry once
  * with `x-puter-events-deployed: 1`, skipping the dispatcher's own callback.
+ *
+ * Calls that come due within a few milliseconds of each other go out together:
+ *
+ *     POST <events dispatcher>/invoke-batch
+ *     x-puter-internal-auth:  <internal secret>
+ *     { calls: [{ script, appUid, holder?, key, deployed?, body, waitMs }] }
+ *
+ * The dispatcher runs a few at a time, in order, and streams NDJSON: `{ i,
+ * started: true }` when a call goes to its worker, then `{ i, status, handled?,
+ * error?, retryAfter?, dispatch? }` when it finishes — the same facts the
+ * single route carries in its status and headers. A call's timeout runs from
+ * its `started` line, so time spent queued behind other calls is never the
+ * handler's. A call still queued `waitMs` after the batch arrived is never
+ * started and answers `dispatch: "queue-timeout"`.
  */
 
 /** The one route an events worker answers. */
@@ -51,6 +66,27 @@ export const EVENTS_INVOKE_PATH = '/__events/invoke';
 /** The route the events dispatcher takes an invocation on. */
 export const EVENTS_DISPATCH_PATH = '/invoke';
 
+/** The route it takes several on, answering each as it finishes. */
+export const EVENTS_DISPATCH_BATCH_PATH = '/invoke-batch';
+
+/** Calls one batch carries at most. */
+export const INVOKE_BATCH_SIZE = 60;
+
+/** How long the first call of a batch waits for others to join it. */
+export const INVOKE_BATCH_WINDOW_MS = 5;
+
+/**
+ * How long a dispatcher without the batch route is sent single calls before the
+ * batch route is tried again.
+ */
+const BATCH_UNSUPPORTED_RETRY_MS = 5 * 60_000;
+
+/**
+ * How long past its wait a batched call's `started` line may take to arrive
+ * before the call is given up as never started.
+ */
+const BATCH_START_GRACE_MS = 2_000;
+
 /**
  * Header the dispatcher marks its own failures with. Anything carrying it never
  * reached a handler, so its status says nothing about the delivery.
@@ -92,6 +128,12 @@ const PLATFORM_ERROR_CODES = new Set([
  */
 export const EVENTS_DEPLOYED_HEADER = 'x-puter-events-deployed';
 
+/**
+ * Names the user whose scope a script belongs to, so a miss deploys it from
+ * their handlers. Absent for an app's own scope.
+ */
+export const EVENTS_HOLDER_HEADER = 'x-puter-events-holder';
+
 /**
  * Dispatch-error reasons this backend can resolve itself by deploying, rather
  * than wait on the rehydrate callback finding a backend behind the dispatcher's
@@ -112,21 +154,90 @@ const SELF_DEPLOYABLE_MISS_REASONS = new Set([
  */
 const ALREADY_DEPLOYED_MISS_REASONS = new Set(['deploy-timeout']);
 
+/** Whose call asked for the deploy, for the share of deploys it may take. */
+export interface WorkerMissOptions {
+    lane?: InvokeLane;
+    /**
+     * Holder uuid of the user scope the script belongs to; absent for app
+     * scope.
+     */
+    holder?: string;
+}
+
 /** What a self-deploy attempt did, and to which app/script it applies. */
 export type WorkerMissHandler = (
     appUid: string,
     script: string,
+    options: WorkerMissOptions,
 ) => Promise<'deployed' | string>;
 
+/**
+ * `work`'s result, or null once `ms` has passed. The work keeps running, and a
+ * failure after the cutoff is logged since nothing else would see it.
+ */
+const withinTime = async <T>(
+    work: Promise<T>,
+    ms: number,
+): Promise<T | null> => {
+    let timedOut = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const limit = new Promise<null>((resolve) => {
+        timer = setTimeout(
+            () => {
+                timedOut = true;
+                resolve(null);
+            },
+            Math.max(0, ms),
+        );
+    });
+    void (async () => {
+        try {
+            await work;
+        } catch (err) {
+            if (timedOut) console.warn('[events] deploy failed late', err);
+        }
+    })();
+    try {
+        return await Promise.race([work, limit]);
+    } finally {
+        clearTimeout(timer);
+    }
+};
+
 /** How long a handler has to answer before the attempt is abandoned. */
 export const EVENTS_INVOKE_TIMEOUT_MS = 30_000;
 
+/**
+ * How many invoke timeouts a delivery's worker lease lasts. The lease store
+ * reads this, and `invoke()` keeps a whole call, deploy and resend included,
+ * inside it.
+ */
+export const EVENTS_WORKER_LEASE_FACTOR = 2;
+
+/**
+ * Left unspent at the end of the lease, and the least a resend is worth
+ * starting with: below it the call is given up as `unavailable` and retried.
+ */
+export const EVENTS_DEADLINE_MARGIN_MS = 5_000;
+
 /**
  * Connections held open to the dispatcher, so a busy fleet is not
  * re-handshaking. Also how many calls one transport makes at once: a call past
  * that waits for a free one before its invoke timeout starts.
  */
 export const INVOKE_CONNECTIONS = 256;
+
+/**
+ * Of those, how many schedule runs may hold at once, so a burst of schedules
+ * can never take the connections event deliveries need.
+ */
+export const SCHEDULE_INVOKE_CONNECTIONS = 64;
+
+/** Whose call this is, for the connection share it may take. */
+export type InvokeLane = 'delivery' | 'schedule';
+
+/** What a deploy answers when another deploy of the region holds the way. */
+export const DEPLOY_BUSY = 'busy';
 const INVOKE_KEEP_ALIVE_MS = 30_000;
 
 /**
@@ -141,6 +252,8 @@ export interface WorkerInvokeRequest {
     /** Script the app's current handler set deploys as. */
     script: string;
     appUid: string;
+    /** Holder uuid, when the handler lives in a user scope. */
+    holder?: string;
     handler: string;
     /** The subscriber's app session token. */
     token: string;
@@ -154,6 +267,8 @@ export interface WorkerInvokeRequest {
 export interface EventsInvokeCall {
     script: string;
     appUid: string;
+    /** Holder uuid of the user scope the script belongs to. */
+    holder?: string;
     /** Value the script compares against its own invoke-key binding. */
     key: string;
     /** Serialized `{ handler, event, ctx, token }`. */
@@ -161,6 +276,17 @@ export interface EventsInvokeCall {
     timeoutMs: number;
     /** Set on the retry after this backend deployed the script itself. */
     deployed?: boolean;
+    lane?: InvokeLane;
+    /**
+     * Builds `body` again at send time, for a transport that waits for a
+     * connection first, so a send time stamped into it is the real one.
+     */
+    render?: () => string;
+    /**
+     * Rechecked by a transport that waits before sending; false drops the call
+     * with {@link supersededAnswer}.
+     */
+    beforeSend?: () => Promise<boolean>;
 }
 
 /** What one attempt at delivering an invocation came back with. */
@@ -176,6 +302,8 @@ export interface EventsInvokeAnswer {
     timedOut?: boolean;
     /** From a `retry-after` header in seconds. */
     retryAfterMs?: number;
+    /** A deploy this call needed was put off: another held the way. */
+    deployBusy?: boolean;
 }
 
 /**
@@ -198,6 +326,8 @@ export type WorkerInvokeOutcome =
 
 export interface WorkerInvokeResult {
     outcome: WorkerInvokeOutcome;
+    /** A deploy on miss was put off because another one held the way. */
+    deployBusy?: boolean;
     /** The status the handler answered with, or `null` when it never did. */
     status: number | null;
     /** Why it could not answer, when nothing did. */
@@ -206,9 +336,24 @@ export interface WorkerInvokeResult {
     retryAfterMs?: number;
 }
 
+/** How one invocation is sent. */
+export interface WorkerInvokeOptions {
+    lane?: InvokeLane;
+    /** Rechecked before each send, including a resend after deployment. */
+    beforeSend?: () => Promise<boolean>;
+    /** Applied to the event as each attempt is sent. */
+    stampEvent?: (event: unknown) => unknown;
+}
+
 const NO_TRANSPORT =
     'no events dispatcher configured (url and internal secret)';
 
+/** What a call whose `beforeSend` said no answers instead of being sent. */
+const supersededAnswer = (): EventsInvokeAnswer => ({
+    status: null,
+    error: 'invocation superseded',
+});
+
 export class EventsWorkerInvokerClient extends PuterClient {
     /** Set only where invocations do not leave the process — local development. */
     #transport: EventsInvokeTransport | null = null;
@@ -236,7 +381,10 @@ export class EventsWorkerInvokerClient extends PuterClient {
         this.#dispatcher = null;
     }
 
-    async invoke(request: WorkerInvokeRequest): Promise<WorkerInvokeResult> {
+    async invoke(
+        request: WorkerInvokeRequest,
+        options: WorkerInvokeOptions = {},
+    ): Promise<WorkerInvokeResult> {
         const transport = this.#pickTransport();
         if (!transport)
             return {
@@ -245,32 +393,86 @@ export class EventsWorkerInvokerClient extends PuterClient {
                 error: NO_TRANSPORT,
             };
 
-        const call: EventsInvokeCall = {
-            script: request.script,
-            appUid: request.appUid,
-            key: request.key,
-            body: JSON.stringify({
+        const { stampEvent } = options;
+        const render = (): string =>
+            JSON.stringify({
                 handler: request.handler,
-                event: request.event,
+                event: stampEvent ? stampEvent(request.event) : request.event,
                 ctx: request.ctx,
                 token: request.token,
-            }),
-            timeoutMs: this.#timeoutMs(),
+            });
+        const timeoutMs = this.#timeoutMs();
+        // The whole call, deploy and resend included, ends before the lease a
+        // delivery holds would let it be claimed again mid-run.
+        // A short configured timeout gets a proportionally short margin.
+        const margin = Math.min(EVENTS_DEADLINE_MARGIN_MS, timeoutMs / 2);
+        const deadline =
+            Date.now() + timeoutMs * EVENTS_WORKER_LEASE_FACTOR - margin;
+        const send = async (
+            deployed: boolean,
+            sendTimeoutMs = timeoutMs,
+        ): Promise<EventsInvokeAnswer> => {
+            if (options.beforeSend && !(await options.beforeSend()))
+                return supersededAnswer();
+            return transport.send({
+                script: request.script,
+                appUid: request.appUid,
+                ...(request.holder ? { holder: request.holder } : {}),
+                key: request.key,
+                body: render(),
+                timeoutMs: sendTimeoutMs,
+                ...(deployed ? { deployed: true } : {}),
+                ...(options.lane ? { lane: options.lane } : {}),
+                ...(stampEvent ? { render } : {}),
+                ...(options.beforeSend
+                    ? { beforeSend: options.beforeSend }
+                    : {}),
+            });
         };
 
-        let result = await transport.send(call);
-        if (this.#missHandler && selfDeployable(result)) {
-            const outcome = await this.#missHandler(
-                request.appUid,
-                request.script,
+        // A send may wait for a connection for half its timeout before the
+        // run's own timeout starts, so it is given what is left divided by that.
+        const resend = (): Promise<EventsInvokeAnswer> | null => {
+            const remaining = deadline - Date.now();
+            if (remaining < margin) return null;
+            return send(
+                true,
+                Math.floor(
+                    Math.min(
+                        timeoutMs,
+                        remaining / (1 + CONNECTION_WAIT_SHARE),
+                    ),
+                ),
             );
+        };
+        const outOfTime = (): WorkerInvokeResult => ({
+            outcome: 'unavailable',
+            status: null,
+            error: 'out of time to resend after deploy',
+        });
+
+        let result = await send(false);
+        if (this.#missHandler && selfDeployable(result)) {
+            // The deploy may be shared with other callers, so it is left
+            // running when this call runs out of time for it.
+            const outcome = await withinTime(
+                this.#missHandler(request.appUid, request.script, {
+                    lane: options.lane,
+                    ...(request.holder ? { holder: request.holder } : {}),
+                }),
+                deadline - Date.now() - margin,
+            );
+            if (outcome === null) return outOfTime();
             if (outcome !== 'deployed')
                 return {
                     outcome: 'unavailable',
                     status: null,
                     error: `deploy: ${outcome}`,
+                    ...(outcome === DEPLOY_BUSY ? { deployBusy: true } : {}),
                 };
-            result = await transport.send({ ...call, deployed: true });
+            const resent = await resend();
+            if (!resent) return outOfTime();
+            result = resent;
         } else if (
             result.status === null &&
             result.dispatchReason &&
@@ -278,10 +480,19 @@ export class EventsWorkerInvokerClient extends PuterClient {
         ) {
             // No deploy to trigger — just give propagation the one retry
             // it usually needs, without spending an upload on it.
-            result = await transport.send({ ...call, deployed: true });
+            const resent = await resend();
+            if (!resent) return outOfTime();
+            result = resent;
         }
 
         const { status, handled, error, timedOut, retryAfterMs } = result;
+        if (result.deployBusy)
+            return {
+                outcome: 'unavailable',
+                status: null,
+                error,
+                deployBusy: true,
+            };
         // Past the timeout the handler was most likely still running, which
         // is its own doing; any other missing answer never reached it.
         if (status === null)
@@ -313,9 +524,19 @@ export class EventsWorkerInvokerClient extends PuterClient {
         // a misconfiguration worth reporting once per attempt rather than a
         // round trip.
         if (!dispatcherUrl || !internalSecret) return null;
+        const { invokeBatchSize, invokeBatchWindowMs } =
+            this.config.events ?? {};
         this.#dispatcher ??= new DispatcherInvokeTransport(
             dispatcherUrl,
             internalSecret,
+            {
+                ...(invokeBatchSize !== undefined
+                    ? { batchSize: invokeBatchSize }
+                    : {}),
+                ...(invokeBatchWindowMs !== undefined
+                    ? { batchWindowMs: invokeBatchWindowMs }
+                    : {}),
+            },
         );
         return this.#dispatcher;
     }
@@ -328,28 +549,65 @@ export class EventsWorkerInvokerClient extends PuterClient {
     }
 }
 
+/** A call waiting in, or sent with, the current batch. */
+interface BatchedCall {
+    call: EventsInvokeCall;
+    resolve: (answer: EventsInvokeAnswer) => void;
+    /** For a `beforeSend` that threw. */
+    reject: (err: unknown) => void;
+    /** When its wait for a connection began, for what is left of it. */
+    waitingSince: number;
+}
+
+export interface DispatcherInvokeTransportOptions {
+    fetchImpl?: typeof undiciFetch;
+    /** Calls per batch; 1 sends every call on its own. */
+    batchSize?: number;
+    batchWindowMs?: number;
+}
+
 /** Reaches an events worker the only way production can: through the dispatcher. */
 export class DispatcherInvokeTransport implements EventsInvokeTransport {
     readonly #url: string;
     readonly #secret: string;
     readonly #fetchImpl: typeof undiciFetch;
+    readonly #batchSize: number;
+    readonly #batchWindowMs: number;
     #agent: Agent | null = null;
     /** Calls holding a connection slot. */
     #active = 0;
-    /** Calls waiting for one, longest-waiting first. */
-    readonly #waiting = new Set<() => void>();
+    /** Of those, schedule runs. */
+    #scheduleActive = 0;
+    /** Calls waiting for one, longest-waiting first, with their lane. */
+    readonly #waiting = new Map<() => void, InvokeLane>();
+    /** Calls gathered for the next batch. */
+    #batch: BatchedCall[] = [];
+    #batchTimer: ReturnType<typeof setTimeout> | null = null;
+    /** Until when the dispatcher is taken not to have the batch route. */
+    #batchUnsupportedUntil = 0;
 
     constructor(
         dispatcherUrl: string,
         secret: string,
-        options: { fetchImpl?: typeof undiciFetch } = {},
+        options: DispatcherInvokeTransportOptions = {},
     ) {
-        this.#url = dispatcherUrl;
+        // Joined as a string: `new URL(path, base)` resolves an absolute path
+        // against the base's origin, dropping any path prefix it carries.
+        this.#url = dispatcherUrl.replace(/\/$/, '');
         this.#secret = secret;
         this.#fetchImpl = options.fetchImpl ?? undiciFetch;
+        this.#batchSize = Math.max(
+            1,
+            Math.floor(options.batchSize ?? INVOKE_BATCH_SIZE),
+        );
+        this.#batchWindowMs = Math.max(
+            0,
+            options.batchWindowMs ?? INVOKE_BATCH_WINDOW_MS,
+        );
     }
 
     close(): void {
+        this.#flush();
         void this.#agent?.close().catch(() => {});
         this.#agent = null;
     }
@@ -357,29 +615,102 @@ export class DispatcherInvokeTransport implements EventsInvokeTransport {
     async send(call: EventsInvokeCall): Promise<EventsInvokeAnswer> {
         // No `timedOut`: the handler never got this call, so the wait is not
         // its failure.
-        if (!(await this.#acquire(call.timeoutMs * CONNECTION_WAIT_SHARE)))
+        const lane = call.lane ?? 'delivery';
+        const waitingSince = Date.now();
+        if (
+            !(await this.#acquire(call.timeoutMs * CONNECTION_WAIT_SHARE, lane))
+        )
             return {
                 status: null,
                 error: 'no free connection to the events dispatcher',
             };
         try {
-            // `new URL(path, base)` resolves an absolute path against the
-            // base's origin, dropping any path prefix `base` already carries.
-            const url = `${this.#url.replace(/\/$/, '')}${EVENTS_DISPATCH_PATH}`;
-            const response = await this.#fetchImpl(url, {
-                method: 'POST',
-                headers: {
-                    'content-type': 'application/json',
-                    'x-puter-internal-auth': this.#secret,
-                    'x-puter-events-script': call.script,
-                    'x-puter-events-app': call.appUid,
-                    'x-puter-events-key': call.key,
-                    ...(call.deployed ? { [EVENTS_DEPLOYED_HEADER]: '1' } : {}),
-                },
-                body: call.body,
-                signal: AbortSignal.timeout(call.timeoutMs),
-                dispatcher: this.#dispatcherFor(),
+            if (this.#batchSize === 1) {
+                // The wait for a connection may have outlived the call.
+                if (call.beforeSend && !(await call.beforeSend()))
+                    return supersededAnswer();
+                return await this.#sendOne(call);
+            }
+            return await new Promise<EventsInvokeAnswer>((resolve, reject) => {
+                this.#batch.push({ call, resolve, reject, waitingSince });
+                if (this.#batch.length >= this.#batchSize) this.#flush();
+                else
+                    this.#batchTimer ??= setTimeout(
+                        () => this.#flush(),
+                        this.#batchWindowMs,
+                    );
             });
+        } finally {
+            this.#release(lane);
+        }
+    }
+
+    /** Send what has gathered: alone when it is one call, else as a batch. */
+    #flush(): void {
+        if (this.#batchTimer) clearTimeout(this.#batchTimer);
+        this.#batchTimer = null;
+        const batch = this.#batch;
+        this.#batch = [];
+        if (batch.length === 0) return;
+        if (batch.some(({ call }) => call.beforeSend))
+            void this.#sendStillCurrent(batch);
+        else this.#sendGathered(batch);
+    }
+
+    #sendGathered(batch: BatchedCall[]): void {
+        if (batch.length === 1 || Date.now() < this.#batchUnsupportedUntil) {
+            for (const { call, resolve } of batch)
+                void this.#sendOne(call).then(resolve);
+            return;
+        }
+        void this.#sendBatch(batch);
+    }
+
+    /** Drops calls superseded while they were gathered, then sends the rest. */
+    async #sendStillCurrent(batch: BatchedCall[]): Promise<void> {
+        const checked = await Promise.all(
+            batch.map(async (entry) => {
+                if (!entry.call.beforeSend) return entry;
+                try {
+                    if (await entry.call.beforeSend()) return entry;
+                    entry.resolve(supersededAnswer());
+                } catch (err) {
+                    entry.reject(err);
+                }
+                return null;
+            }),
+        );
+        const current = checked.filter(
+            (entry): entry is BatchedCall => entry !== null,
+        );
+        if (current.length > 0) this.#sendGathered(current);
+    }
+
+    /** One call on the single route. */
+    async #sendOne(call: EventsInvokeCall): Promise<EventsInvokeAnswer> {
+        try {
+            const response = await this.#fetchImpl(
+                `${this.#url}${EVENTS_DISPATCH_PATH}`,
+                {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/json',
+                        'x-puter-internal-auth': this.#secret,
+                        'x-puter-events-script': call.script,
+                        'x-puter-events-app': call.appUid,
+                        ...(call.holder
+                            ? { [EVENTS_HOLDER_HEADER]: call.holder }
+                            : {}),
+                        'x-puter-events-key': call.key,
+                        ...(call.deployed
+                            ? { [EVENTS_DEPLOYED_HEADER]: '1' }
+                            : {}),
+                    },
+                    body: call.render ? call.render() : call.body,
+                    signal: AbortSignal.timeout(call.timeoutMs),
+                    dispatcher: this.#dispatcherFor(),
+                },
+            );
             // The body is not read: a handler answers with a status, and
             // whatever else it writes is its own business.
             void response.body?.cancel().catch(() => {});
@@ -390,24 +721,198 @@ export class DispatcherInvokeTransport implements EventsInvokeTransport {
                 EVENTS_DISPATCH_ERROR_HEADER,
             );
             if (dispatchError !== null)
-                return {
-                    status: null,
-                    error: `dispatcher: ${dispatchError} (${response.status})`,
-                    dispatchReason: dispatchError,
-                };
+                return dispatchAnswer(dispatchError, response.status);
 
             return answerFrom(response);
         } catch (err) {
             return failedAnswer(err);
-        } finally {
-            this.#release();
         }
     }
 
+    /**
+     * Several calls in one request. A call may wait in the dispatcher's queue
+     * for whatever is left of its connection wait, and its timeout runs from
+     * its `started` line; the request itself is dropped once every call has an
+     * answer.
+     */
+    async #sendBatch(batch: BatchedCall[]): Promise<void> {
+        const hangUp = new AbortController();
+        let open = batch.length;
+        const answered = batch.map(() => false);
+        const timers: ReturnType<typeof setTimeout>[] = [];
+        const finish = (i: number, done: (entry: BatchedCall) => void) => {
+            if (answered[i]) return;
+            answered[i] = true;
+            clearTimeout(timers[i]);
+            done(batch[i]);
+            if (--open === 0) hangUp.abort();
+        };
+        const settle = (i: number, answer: EventsInvokeAnswer): void =>
+            finish(i, (entry) => entry.resolve(answer));
+        const settleRest = (answer: EventsInvokeAnswer): void => {
+            for (let i = 0; i < batch.length; i++) settle(i, answer);
+        };
+
+        const now = Date.now();
+        const waits = batch.map(({ call, waitingSince }) =>
+            Math.max(
+                0,
+                Math.floor(
+                    call.timeoutMs * CONNECTION_WAIT_SHARE -
+                        (now - waitingSince),
+                ),
+            ),
+        );
+        const body = JSON.stringify({
+            calls: batch.map(({ call }, i) => ({
+                script: call.script,
+                appUid: call.appUid,
+                ...(call.holder ? { holder: call.holder } : {}),
+                key: call.key,
+                ...(call.deployed ? { deployed: true } : {}),
+                body: call.render ? call.render() : call.body,
+                waitMs: waits[i],
+            })),
+        });
+        const arm = (
+            i: number,
+            ms: number,
+            answer: () => EventsInvokeAnswer,
+        ) => {
+            clearTimeout(timers[i]);
+            timers[i] = setTimeout(() => settle(i, answer()), ms);
+            timers[i].unref?.();
+        };
+        // No `timedOut`: a call that never started never reached a handler.
+        batch.forEach((_, i) =>
+            arm(i, waits[i] + BATCH_START_GRACE_MS, () => ({
+                status: null,
+                error: 'dispatcher: call never started',
+            })),
+        );
+        const started = (i: number): void => {
+            if (!answered[i])
+                arm(i, batch[i].call.timeoutMs, () =>
+                    failedAnswer(timeoutError()),
+                );
+        };
+        const longest = Math.max(
+            ...batch.map(
+                ({ call }, i) =>
+                    waits[i] + BATCH_START_GRACE_MS + call.timeoutMs,
+            ),
+        );
+
+        try {
+            const response = await this.#fetchImpl(
+                `${this.#url}${EVENTS_DISPATCH_BATCH_PATH}`,
+                {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/json',
+                        'x-puter-internal-auth': this.#secret,
+                    },
+                    body,
+                    signal: AbortSignal.any([
+                        hangUp.signal,
+                        AbortSignal.timeout(longest),
+                    ]),
+                    dispatcher: this.#dispatcherFor(),
+                },
+            );
+
+            const dispatchError = response.headers.get(
+                EVENTS_DISPATCH_ERROR_HEADER,
+            );
+            if (dispatchError === 'no-such-route') {
+                // A dispatcher from before the batch route: nothing ran, so
+                // every call goes again on its own.
+                void response.body?.cancel().catch(() => {});
+                this.#batchUnsupportedUntil =
+                    Date.now() + BATCH_UNSUPPORTED_RETRY_MS;
+                batch.forEach(({ call }, i) => {
+                    if (answered[i]) return;
+                    const { beforeSend } = call;
+                    if (!beforeSend) {
+                        void this.#sendOne(call).then((a) => settle(i, a));
+                        return;
+                    }
+                    // The batch round trip may have outlived the call.
+                    void (async () => {
+                        try {
+                            if (!(await beforeSend()))
+                                return settle(i, supersededAnswer());
+                        } catch (err) {
+                            return finish(i, (entry) => entry.reject(err));
+                        }
+                        settle(i, await this.#sendOne(call));
+                    })();
+                });
+                return;
+            }
+            if (dispatchError !== null || !response.ok) {
+                void response.body?.cancel().catch(() => {});
+                // An unmarked failure (an edge 404, a WAF 403) reads as
+                // Puter's, never as any handler's answer.
+                settleRest(
+                    dispatchError !== null
+                        ? dispatchAnswer(dispatchError, response.status)
+                        : {
+                              status: null,
+                              error: `dispatcher: unmarked ${response.status} for a batch`,
+                          },
+                );
+                return;
+            }
+
+            let buffered = '';
+            const read = (line: string): void => {
+                if (line.trim() === '') return;
+                const parsed = parseAnswerLine(line);
+                if (!parsed || parsed.i >= batch.length) return;
+                if ('started' in parsed) started(parsed.i);
+                else settle(parsed.i, parsed.answer);
+            };
+            const decoder = new TextDecoder();
+            for await (const chunk of response.body ?? []) {
+                buffered += decoder.decode(chunk, { stream: true });
+                let newline = buffered.indexOf('\n');
+                while (newline !== -1) {
+                    read(buffered.slice(0, newline));
+                    buffered = buffered.slice(newline + 1);
+                    newline = buffered.indexOf('\n');
+                }
+            }
+            read(buffered);
+            settleRest({
+                status: null,
+                error: 'dispatcher: batch ended without an answer',
+            });
+        } catch (err) {
+            // Every call has its answer and the request was dropped on purpose.
+            if (open === 0) return;
+            settleRest(failedAnswer(err));
+        }
+    }
+
+    /** Whether a call on `lane` may take a connection now. */
+    #free(lane: InvokeLane): boolean {
+        return (
+            this.#active < INVOKE_CONNECTIONS &&
+            (lane !== 'schedule' ||
+                this.#scheduleActive < SCHEDULE_INVOKE_CONNECTIONS)
+        );
+    }
+
+    #take(lane: InvokeLane): void {
+        this.#active++;
+        if (lane === 'schedule') this.#scheduleActive++;
+    }
+
     /** A connection slot, or false once `waitMs` passes without one. */
-    #acquire(waitMs: number): Promise<boolean> {
-        if (this.#active < INVOKE_CONNECTIONS) {
-            this.#active++;
+    #acquire(waitMs: number, lane: InvokeLane): Promise<boolean> {
+        if (this.#free(lane)) {
+            this.#take(lane);
             return Promise.resolve(true);
         }
         return new Promise((resolve) => {
@@ -420,19 +925,24 @@ export class DispatcherInvokeTransport implements EventsInvokeTransport {
                 resolve(false);
             }, waitMs);
             timer.unref?.();
-            this.#waiting.add(granted);
+            this.#waiting.set(granted, lane);
         });
     }
 
-    /** Hand the slot to the longest waiter, or give it back. */
-    #release(): void {
-        const next = this.#waiting.values().next().value;
-        if (next) {
-            this.#waiting.delete(next);
-            next();
+    /**
+     * Give the slot back, then hand one to the longest waiter it can go to: a
+     * schedule waiter at a full schedule share doesn't hold up a delivery.
+     */
+    #release(lane: InvokeLane): void {
+        this.#active--;
+        if (lane === 'schedule') this.#scheduleActive--;
+        for (const [granted, waiting] of this.#waiting) {
+            if (!this.#free(waiting)) continue;
+            this.#waiting.delete(granted);
+            this.#take(waiting);
+            granted();
             return;
         }
-        this.#active--;
     }
 
     /** One pool per process, built on first use and closed with the server. */
@@ -446,6 +956,65 @@ export class DispatcherInvokeTransport implements EventsInvokeTransport {
     }
 }
 
+/** What a failure the dispatcher marked as its own reads as. */
+const dispatchAnswer = (
+    reason: string,
+    status: number,
+): EventsInvokeAnswer => ({
+    status: null,
+    error: `dispatcher: ${reason} (${status})`,
+    dispatchReason: reason,
+});
+
+/** What `AbortSignal.timeout` rejects with, for a batched call's own timeout. */
+const timeoutError = (): Error =>
+    new DOMException(
+        'The operation was aborted due to timeout',
+        'TimeoutError',
+    );
+
+/** One line of a batch answer, or null when it is not one. */
+export const parseAnswerLine = (
+    line: string,
+):
+    | { i: number; started: true }
+    | { i: number; answer: EventsInvokeAnswer }
+    | null => {
+    let raw: unknown;
+    try {
+        raw = JSON.parse(line);
+    } catch {
+        return null;
+    }
+    if (!raw || typeof raw !== 'object') return null;
+    const { i, started, status, handled, error, retryAfter, dispatch } =
+        raw as Record<string, unknown>;
+    if (!Number.isInteger(i) || (i as number) < 0) return null;
+    if (started === true) return { i: i as number, started: true };
+    if (typeof status !== 'number') return null;
+    if (typeof dispatch === 'string')
+        return { i: i as number, answer: dispatchAnswer(dispatch, status) };
+    return {
+        i: i as number,
+        answer: answerFrom({
+            status,
+            headers: {
+                get: (name) => {
+                    if (name === EVENTS_HANDLED_HEADER)
+                        return handled === true ? '1' : null;
+                    if (name === EVENTS_ERROR_HEADER)
+                        return typeof error === 'string' ? error : null;
+                    if (name === 'retry-after')
+                        return typeof retryAfter === 'string'
+                            ? retryAfter
+                            : null;
+                    return null;
+                },
+            },
+        }),
+    };
+};
+
 /** Whether deploying the script is what fixes this answer. */
 const selfDeployable = (result: EventsInvokeAnswer): boolean =>
     result.status === null

src/backend/clients/s3/S3Client.test.ts

@@ -21,6 +21,8 @@
 import { GetObjectCommand } from '@aws-sdk/client-s3';
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { existsSync } from 'node:fs';
+import { createServer, type Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
@@ -200,6 +202,77 @@ describe('S3Client — remote endpoint configuration', () => {
     });
 });
 
+describe('S3Client — bucket in another region', () => {
+    let server: Server;
+    let client: S3Client;
+    let signedRegions: string[];
+
+    // Answers like a bucket that lives in us-west-2: a request signed for any
+    // other region gets S3's 301 naming the bucket's region.
+    beforeEach(async () => {
+        signedRegions = [];
+        server = createServer((req, res) => {
+            const region =
+                /Credential=[^/]+\/\d{8}\/([^/]+)\//.exec(
+                    req.headers.authorization ?? '',
+                )?.[1] ?? '';
+            signedRegions.push(region);
+            if (region !== 'us-west-2') {
+                res.writeHead(301, {
+                    'content-type': 'application/xml',
+                    'x-amz-bucket-region': 'us-west-2',
+                });
+                res.end(
+                    '<?xml version="1.0" encoding="UTF-8"?><Error><Code>PermanentRedirect</Code><Message>The bucket you are attempting to access must be addressed using the specified endpoint.</Message></Error>',
+                );
+                return;
+            }
+            res.writeHead(200, {
+                'content-type': 'text/plain',
+                'content-length': '5',
+            });
+            res.end('hello');
+        });
+        await new Promise<void>((resolve) =>
+            server.listen(0, '127.0.0.1', resolve),
+        );
+        const { port } = server.address() as AddressInfo;
+        client = new S3Client({
+            port: 0,
+            extensions: [],
+            s3: {
+                s3Config: {
+                    endpoint: `http://127.0.0.1:${port}`,
+                    accessKeyId: 'fakeAccessKeyId',
+                    secretAccessKey: 'fakeSecretAccessKey',
+                    forcePathStyle: true,
+                },
+            },
+        } as unknown as IConfig);
+        await client.onServerStart();
+    });
+
+    afterEach(async () => {
+        await client.onServerShutdown();
+        server.closeAllConnections();
+        await new Promise<void>((resolve) => server.close(() => resolve()));
+    });
+
+    it("retries a read in the bucket's region when S3 redirects it", async () => {
+        const result = await client
+            .get('ap-northeast-2')
+            .send(
+                new GetObjectCommand({
+                    Bucket: 'other-bucket',
+                    Key: 'index.html',
+                }),
+            );
+
+        expect(await result.Body?.transformToString()).toBe('hello');
+        expect(signedRegions).toEqual(['ap-northeast-2', 'us-west-2']);
+    });
+});
+
 describe('S3Client — legacy storage migration', () => {
     let client: S3Client;
     let dir: string;

src/backend/clients/s3/S3Client.ts

@@ -235,6 +235,9 @@ export class S3Client extends PuterClient {
 
         const client = new AwsS3Client({
             region,
+            // Rows without a stored region are read with the server's own, so
+            // retry where S3's 301 says the bucket actually lives.
+            followRegionRedirects: true,
             requestStreamBufferSize: 32 * 1024,
             requestHandler: new NodeHttpHandler({
                 socketTimeout: 5000,

src/backend/controllers/apps/AppController.js

@@ -52,8 +52,8 @@ const APP_READ_LIMIT = {
 /**
  * Unauthenticated icon serving; no actor to key on, so the bucket is the
  * address — and an address is a NAT, a campus or a carrier gateway that can
- * hold hundreds of desktops. Each desktop boot pulls the taskbar's icons at
- * once, so a single burst from one network is already thousands of requests.
+ * hold hundreds of desktops. Each dashboard load pulls its app icons at once,
+ * so a single burst from one network is already thousands of requests.
  * Responses are publicly cacheable and usually a redirect, so the ceiling is
  * not protecting bandwidth; it is there so a client looping on a broken icon
  * can't spin unbounded.
@@ -523,7 +523,7 @@ export class AppController extends PuterController {
         };
 
         // Icons are <img src> targets from the GUI (root) AND resolved via
-        // api_base_url in taskbar payloads. Register on both so either origin
+        // api_base_url in app summaries. Register on both so either origin
         // works without a cross-subdomain redirect.
         router.get(
             '/app-icon/:app_uid',

src/backend/controllers/apps/AppController.test.ts

@@ -1271,7 +1271,7 @@ describe('AppController app-icon rate limit', () => {
     it('sizes the icon bucket for a whole network rather than one desktop', () => {
         // Icons are unauthenticated `<img src>` targets, so the only key is
         // the address — which one NAT shares across every desktop behind it,
-        // and each boot pulls the taskbar's icons in a burst.
+        // and each dashboard load pulls its app icons in a burst.
         for (const path of ['/app-icon/:app_uid', '/app-icon/:app_uid/:size']) {
             const route = router.routes.find(
                 (r) => r.method === 'get' && r.path === path,

src/backend/controllers/auth/AuthController.test.ts

@@ -1416,7 +1416,7 @@ describe('AuthController.handleLogin', () => {
             is_user_token: true,
         });
         expect(body.user.directories).toBeTypeOf('object');
-        expect(Array.isArray(body.user.taskbar_items)).toBe(true);
+        expect(body.user).not.toHaveProperty('taskbar_items');
     });
 
     // A deleted row still answering from cache reaches the session INSERT.
@@ -7468,6 +7468,11 @@ describe('AuthController user-protected mutations (validation paths)', () => {
             { expiresIn: '1h' },
         );
 
+        const heard: Array<Record<string, unknown>> = [];
+        eventClient.on('user.email-changed', (_k, data) => {
+            heard.push(data as Record<string, unknown>);
+        });
+
         const req = makeReq({});
         (req as unknown as { query: Record<string, string> }).query = {
             token: linkJwt,
@@ -7475,6 +7480,11 @@ describe('AuthController user-protected mutations (validation paths)', () => {
         const res = makeRes();
         await controller.handleChangeEmailConfirm(req, res);
         expect(res.sent).toMatch(/Email changed successfully/);
+        expect(heard).toContainEqual({
+            user_id: user.id,
+            old_email: user.email ?? null,
+            new_email: newEmail,
+        });
 
         const after = await server.stores.user.getById(user.id, {
             force: true,

src/backend/controllers/auth/AuthController.ts

@@ -2647,6 +2647,7 @@ export class AuthController extends PuterController {
                 'user.email-changed' as never,
                 {
                     user_id: user.id,
+                    old_email: user.email ?? null,
                     new_email: newEmail,
                 } as never,
                 {},

src/backend/controllers/auth/oidcLoginReturn.ts

@@ -15,7 +15,6 @@ export interface OidcLoginContinuation {
     embeddedInPopup: boolean;
     openerOrigin: string | null;
     messageId: string | null;
-    switchedToLogin: boolean;
 }
 
 interface OidcReturnDeps {
@@ -56,7 +55,6 @@ export function completeOidcLoginReturn(
         data.userUuid !== user.uuid ||
         typeof data.redirectUri !== 'string' ||
         typeof data.embeddedInPopup !== 'boolean' ||
-        typeof data.switchedToLogin !== 'boolean' ||
         (data.openerOrigin !== null && typeof data.openerOrigin !== 'string') ||
         (data.messageId !== null && typeof data.messageId !== 'string')
     ) {
@@ -91,6 +89,5 @@ export function completeOidcLoginReturn(
             ),
         );
     }
-    if (data.switchedToLogin) append('oidc_switched', 'login');
     return target;
 }

src/backend/controllers/broadcast/BroadcastController.ts

@@ -19,6 +19,7 @@
 
 import type { Request, Response } from 'express';
 import { Controller, Post } from '../../core/http/decorators.js';
+import { schedulesUnavailable } from '../../core/schedules.js';
 import type { BroadcastService } from '../../services/broadcast/BroadcastService.js';
 import type { ForwardBatch } from '../../services/events/forwardQueue.js';
 import { PuterController } from '../types.js';
@@ -108,6 +109,42 @@ export class BroadcastController extends PuterController {
         );
         res.status(200).json({ ok: true, ...reply });
     }
+
+    /**
+     * Schedule changes a region made for schedules this one owns, handed to
+     * `services.schedules`; `events_disabled` on a server without it.
+     */
+    @Post('/events/schedules', { subdomain: '*' })
+    async schedules(req: Request, res: Response): Promise<void> {
+        const broadcast = this.services.broadcast as unknown as
+            BroadcastService | undefined;
+        if (!broadcast) {
+            res.status(503).json({
+                error: { message: 'Broadcast service not registered' },
+            });
+            return;
+        }
+
+        const verified = await broadcast.verifySignedRequest(
+            req.rawBody,
+            broadcastHeaders(req),
+        );
+        if (!verified.ok) {
+            res.status(verified.status ?? 400).json({
+                error: { message: verified.message ?? 'Bad request' },
+            });
+            return;
+        }
+        if (verified.info?.ignored) {
+            res.status(200).json({ ok: true, ...verified.info });
+            return;
+        }
+
+        const schedules = this.services.schedules;
+        if (!schedules) throw schedulesUnavailable();
+        const reply = await schedules.receivePeerChanges(req.body);
+        res.status(200).json({ ok: true, ...reply });
+    }
 }
 
 const broadcastHeaders = (req: Request) => {

src/backend/controllers/desktop/DesktopController.js

@@ -25,18 +25,13 @@ const ALLOWED_SORT_BY = ['name', 'size', 'modified', 'type'];
 const ALLOWED_SORT_ORDER = ['asc', 'desc'];
 
 /**
- * Desktop/UI preference routes.
- *
- * Two categories:
- *
- * - User-level: desktop background, taskbar items (UserStore)
- * - Folder-level: layout, sort_by/sort_order (fsentries table)
+ * Folder view preference routes: layout and sort_by/sort_order, stored on the
+ * folder's fsentries row.
  */
 /**
- * Desktop preference writes — background, taskbar, layout, sort order. All four
- * persist to the user row on every call, and the GUI fires them on direct user
- * action, so a per-minute ceiling well above human speed is enough to catch a
- * stuck client.
+ * Desktop preference writes — layout, sort order. Each persists on every call,
+ * and the GUI fires them on direct user action, so a per-minute ceiling well
+ * above human speed is enough to catch a stuck client.
  */
 const PREFERENCE_WRITE_LIMIT = {
     scope: 'desktop-preference',
@@ -47,89 +42,6 @@ const PREFERENCE_WRITE_LIMIT = {
 
 export class DesktopController extends PuterController {
     registerRoutes(router) {
-        // -- Desktop background --------------------------------------
-
-        router.post(
-            '/set-desktop-bg',
-            {
-                subdomain: 'api',
-                requireUserActor: true,
-                allowFullAccessToken: true,
-                rateLimit: PREFERENCE_WRITE_LIMIT,
-            },
-            async (req, res) => {
-                const { url, color, fit } = req.body ?? {};
-
-                const patch = {};
-                if (url !== undefined) {
-                    if (url !== null && typeof url !== 'string') {
-                        throw new HttpError(
-                            400,
-                            '`url` must be a string or null',
-                            { legacyCode: 'bad_request' },
-                        );
-                    }
-                    patch.desktop_bg_url = url;
-                }
-                if (color !== undefined) {
-                    if (color !== null && typeof color !== 'string') {
-                        throw new HttpError(
-                            400,
-                            '`color` must be a string or null',
-                            { legacyCode: 'bad_request' },
-                        );
-                    }
-                    patch.desktop_bg_color = color;
-                }
-                if (fit !== undefined) {
-                    if (fit !== null && typeof fit !== 'string') {
-                        throw new HttpError(
-                            400,
-                            '`fit` must be a string or null',
-                            { legacyCode: 'bad_request' },
-                        );
-                    }
-                    patch.desktop_bg_fit = fit;
-                }
-
-                if (Object.keys(patch).length === 0) {
-                    throw new HttpError(400, 'No fields provided', {
-                        legacyCode: 'bad_request',
-                    });
-                }
-
-                await this.stores.user.update(req.actor.user.id, patch);
-                res.json({});
-            },
-        );
-
-        // -- Taskbar items -------------------------------------------
-
-        router.post(
-            '/update-taskbar-items',
-            {
-                subdomain: 'api',
-                requireUserActor: true,
-                allowFullAccessToken: true,
-                rateLimit: PREFERENCE_WRITE_LIMIT,
-            },
-            async (req, res) => {
-                const { items } = req.body ?? {};
-                if (!Array.isArray(items)) {
-                    throw new HttpError(
-                        400,
-                        'Missing or invalid `items` array',
-                        { legacyCode: 'bad_request' },
-                    );
-                }
-
-                await this.stores.user.update(req.actor.user.id, {
-                    taskbar_items: JSON.stringify(items),
-                });
-                res.json({});
-            },
-        );
-
         // -- Folder layout -------------------------------------------
 
         router.post(

src/backend/controllers/desktop/DesktopController.test.ts

@@ -130,147 +130,17 @@ const callRoute = async (
     });
 };
 
-// ── /set-desktop-bg ─────────────────────────────────────────────────
-
-describe('DesktopController POST /set-desktop-bg', () => {
-    it('persists url/color/fit on the user row', async () => {
-        const { actor, userId } = await makeUser();
-        const { res, captured } = makeRes();
-        await callRoute(
-            'post',
-            '/set-desktop-bg',
-            makeReq({
-                body: {
-                    url: 'https://cdn.test/wallpaper.png',
-                    color: '#000000',
-                    fit: 'cover',
-                },
-                actor,
-            }),
-            res,
-        );
-        expect(captured.body).toEqual({});
-
-        const refreshed = await server.stores.user.getById(userId);
-        expect(refreshed?.desktop_bg_url).toBe(
-            'https://cdn.test/wallpaper.png',
-        );
-        expect(refreshed?.desktop_bg_color).toBe('#000000');
-        expect(refreshed?.desktop_bg_fit).toBe('cover');
+describe('DesktopController routes', () => {
+    it('has no desktop background route', () => {
+        expect(
+            router.routes.some((r) => r.path === '/set-desktop-bg'),
+        ).toBe(false);
     });
 
-    it('persists only the supplied fields (partial update)', async () => {
-        const { actor, userId } = await makeUser();
-        const { res } = makeRes();
-        await callRoute(
-            'post',
-            '/set-desktop-bg',
-            makeReq({ body: { color: '#ffffff' }, actor }),
-            res,
-        );
-        const refreshed = await server.stores.user.getById(userId);
-        expect(refreshed?.desktop_bg_color).toBe('#ffffff');
-        // Untouched fields remain at their column default.
-        expect(refreshed?.desktop_bg_url).toBeFalsy();
-        expect(refreshed?.desktop_bg_fit).toBeFalsy();
-    });
-
-    it('passes through `null` to clear a field', async () => {
-        const { actor, userId } = await makeUser();
-        // First populate, then clear.
-        const populate = makeRes();
-        await callRoute(
-            'post',
-            '/set-desktop-bg',
-            makeReq({
-                body: { url: 'https://cdn.test/x.png' },
-                actor,
-            }),
-            populate.res,
-        );
-        const before = await server.stores.user.getById(userId);
-        expect(before?.desktop_bg_url).toBe('https://cdn.test/x.png');
-
-        const clear = makeRes();
-        await callRoute(
-            'post',
-            '/set-desktop-bg',
-            makeReq({ body: { url: null }, actor }),
-            clear.res,
-        );
-        const after = await server.stores.user.getById(userId);
-        expect(after?.desktop_bg_url).toBeNull();
-    });
-
-    it('throws 400 when url is not a string or null', async () => {
-        const { actor } = await makeUser();
-        const { res } = makeRes();
-        await expect(
-            callRoute(
-                'post',
-                '/set-desktop-bg',
-                makeReq({ body: { url: 123 }, actor }),
-                res,
-            ),
-        ).rejects.toMatchObject({ statusCode: 400 });
-    });
-
-    it('throws 400 when no fields are provided', async () => {
-        const { actor } = await makeUser();
-        const { res } = makeRes();
-        await expect(
-            callRoute(
-                'post',
-                '/set-desktop-bg',
-                makeReq({ body: {}, actor }),
-                res,
-            ),
-        ).rejects.toMatchObject({ statusCode: 400 });
-    });
-});
-
-// ── /update-taskbar-items ───────────────────────────────────────────
-
-describe('DesktopController POST /update-taskbar-items', () => {
-    it('persists items as a JSON-encoded string', async () => {
-        const { actor, userId } = await makeUser();
-        const items = [{ name: 'editor' }, { name: 'browser' }];
-        const { res } = makeRes();
-        await callRoute(
-            'post',
-            '/update-taskbar-items',
-            makeReq({ body: { items }, actor }),
-            res,
-        );
-
-        const refreshed = await server.stores.user.getById(userId);
-        expect(refreshed?.taskbar_items).toBe(JSON.stringify(items));
-    });
-
-    it('throws 400 when items is missing', async () => {
-        const { actor } = await makeUser();
-        const { res } = makeRes();
-        await expect(
-            callRoute(
-                'post',
-                '/update-taskbar-items',
-                makeReq({ body: {}, actor }),
-                res,
-            ),
-        ).rejects.toMatchObject({ statusCode: 400 });
-    });
-
-    it('throws 400 when items is not an array', async () => {
-        const { actor } = await makeUser();
-        const { res } = makeRes();
-        await expect(
-            callRoute(
-                'post',
-                '/update-taskbar-items',
-                makeReq({ body: { items: 'oops' }, actor }),
-                res,
-            ),
-        ).rejects.toMatchObject({ statusCode: 400 });
+    it('has no taskbar items route', () => {
+        expect(
+            router.routes.some((r) => r.path === '/update-taskbar-items'),
+        ).toBe(false);
     });
 });
 

src/backend/controllers/drivers/DriverController.test.ts

@@ -501,6 +501,29 @@ describe('DriverController.#handleCall (via captured router)', () => {
         expect(body.service.name).toBe('puter-kvstore');
     });
 
+    it('treats null `args` as no arguments', async () => {
+        const actor = await makeUserActor();
+        await server.stores.permission.setFlatUserPerm(
+            actor.user!.id!,
+            'service:puter-subdomains:ii:puter-subdomains',
+            {
+                permission: 'service:puter-subdomains:ii:puter-subdomains',
+                deleted: false,
+                issuer_user_id: actor.user!.id!,
+            } as never,
+        );
+
+        const res = makeRes();
+        const req = makeReq(
+            { interface: 'puter-subdomains', method: 'select', args: null },
+            actor,
+        );
+        await runWithContext({ actor }, () =>
+            routes['POST /call'](req, res as unknown as Response, () => {}),
+        );
+        expect((res.body as { success: boolean }).success).toBe(true);
+    });
+
     it('pipes a stream-shaped result instead of JSON', async () => {
         // Use an ephemeral driver registered onto the controller's bag.
         const streamPayload = Buffer.from('hello-world');

src/backend/controllers/drivers/DriverController.ts

@@ -276,8 +276,10 @@ export class DriverController extends PuterController {
             interface: ifaceName,
             method,
             driver: driverName,
-            args = {},
+            args: rawArgs,
         } = (req.body ?? {}) as Record<string, unknown>;
+        // Drivers read fields off `args`, so a null one counts as absent.
+        const args = rawArgs ?? {};
 
         if (!ifaceName || typeof ifaceName !== 'string') {
             throw new HttpError(400, 'Missing or invalid `interface`', {

src/backend/controllers/events/EventsController.ts

@@ -25,6 +25,11 @@ import { bodyRecord } from '../../core/http/requestBody.js';
 import { DURABLE_LIST_LIMIT_CAP } from '../../stores/events/DurableSubscriptionStore.js';
 import { EVENTS_WORKERS_LIST_LIMIT_CAP } from '../../stores/events/EventHandlerStore.js';
 import { KV_HANDLE_LIST_LIMIT_CAP } from '../../stores/events/KvShareHandleStore.js';
+import {
+    SCHEDULE_LIST_LIMIT_CAP,
+    schedulesUnavailable,
+    type ScheduleServiceContract,
+} from '../../core/schedules.js';
 import { normalizeLimit } from '../../util/pagination.js';
 import { PuterController } from '../types.js';
 import { EVENTS_WORKER_PREFIX } from '../../services/events/workerRuntime.js';
@@ -59,6 +64,8 @@ const EVENTS_SCRIPT_REGEX = new RegExp(`^${EVENTS_WORKER_PREFIX}[a-f0-9]{32}$`);
 
 /** Matches the edge dispatcher's own validation of the app uid it forwards. */
 const APP_UID_REGEX = /^app-[A-Za-z0-9_-]{1,64}$/;
+/** A user uuid. */
+const HOLDER_REGEX = /^[A-Za-z0-9-]{1,64}$/;
 
 @Controller('/events')
 export class EventsController extends PuterController {
@@ -127,7 +134,8 @@ export class EventsController extends PuterController {
      *
      * Stateless: no subscription, no stored position, nothing written. The
      * cursor comes back to the caller and goes out again as `cursor` (or
-     * `after`, the name it first shipped under).
+     * `after`, the name it first shipped under). `from=end` with no cursor
+     * starts at the newest row instead of the oldest.
      */
     @Get('/fetch', {
         subdomain: 'api',
@@ -138,9 +146,16 @@ export class EventsController extends PuterController {
     async fetch(req: Request, res: Response): Promise<void> {
         const actor = this.#requireActor(req);
         const query = (req.query ?? {}) as Record<string, unknown>;
+        const from = query.from as 'start' | 'end' | undefined;
+        if (from !== undefined && from !== 'start' && from !== 'end') {
+            throw new HttpError(400, '`from` must be `start` or `end`', {
+                legacyCode: 'bad_request',
+            });
+        }
 
         const page = await this.services.events.fetchMissed(actor, {
             subject: typeof query.subject === 'string' ? query.subject : '',
+            from,
             cursor: typeof query.cursor === 'string' ? query.cursor : undefined,
             after: typeof query.after === 'string' ? query.after : undefined,
             limit: normalizeLimit(query.limit, {
@@ -169,6 +184,99 @@ export class EventsController extends PuterController {
         res.json({});
     }
 
+    // -- Schedules ---------------------------------------------------
+    //
+    // An app's handler run on a timer, served by `services.schedules` when a
+    // server has it and answered `events_disabled` when it doesn't. Creating
+    // one needs an app context; listing, reading and removing are scoped the
+    // way the durable verbs are. The create and remove verbs spend the
+    // subscribe and unsubscribe budgets in the service, shared with those
+    // verbs.
+
+    #schedules(): ScheduleServiceContract {
+        const schedules = this.services.schedules;
+        if (!schedules) throw schedulesUnavailable();
+        return schedules;
+    }
+
+    /** POST /events/schedules — create a schedule for the calling app. */
+    @Post('/schedules', {
+        subdomain: 'api',
+        requireAuth: true,
+        allowAccessToken: true,
+    })
+    async createSchedule(req: Request, res: Response): Promise<void> {
+        const actor = this.#requireActor(req);
+        res.json(await this.#schedules().createFor(actor, bodyRecord(req)));
+    }
+
+    /** GET /events/schedules — the caller's schedules, one page at a time. */
+    @Get('/schedules', {
+        subdomain: 'api',
+        requireAuth: true,
+        allowAccessToken: true,
+        rateLimit: EVENTS_LIST_LIMIT,
+    })
+    async listSchedules(req: Request, res: Response): Promise<void> {
+        const actor = this.#requireActor(req);
+        const query = (req.query ?? {}) as Record<string, unknown>;
+
+        const page = await this.#schedules().list(actor, {
+            limit: normalizeLimit(query.limit, {
+                cap: SCHEDULE_LIST_LIMIT_CAP,
+            }),
+            cursor: typeof query.cursor === 'string' ? query.cursor : undefined,
+            includeTotal: query.includeTotal === 'true',
+        });
+
+        res.json({
+            items: page.items,
+            ...(page.cursor ? { cursor: page.cursor } : {}),
+            ...(page.total !== undefined ? { total: page.total } : {}),
+        });
+    }
+
+    @Post('/schedules/update', {
+        subdomain: 'api',
+        requireAuth: true,
+        allowAccessToken: true,
+    })
+    async updateSchedule(req: Request, res: Response): Promise<void> {
+        const actor = this.#requireActor(req);
+        const { scheduleId, changes } = bodyRecord(req);
+        res.json(await this.#schedules().update(actor, scheduleId, changes));
+    }
+
+    /**
+     * POST /events/schedules/remove — end one schedule. An id the caller does
+     * not hold reads as absent.
+     */
+    @Post('/schedules/remove', {
+        subdomain: 'api',
+        requireAuth: true,
+        allowAccessToken: true,
+    })
+    async removeSchedule(req: Request, res: Response): Promise<void> {
+        const actor = this.#requireActor(req);
+        await this.#schedules().remove(actor, bodyRecord(req).scheduleId);
+        res.json({});
+    }
+
+    /**
+     * GET /events/schedules/:scheduleId — one schedule, ended or not. An id the
+     * caller does not hold reads as absent.
+     */
+    @Get('/schedules/:scheduleId', {
+        subdomain: 'api',
+        requireAuth: true,
+        allowAccessToken: true,
+        rateLimit: EVENTS_LIST_LIMIT,
+    })
+    async getSchedule(req: Request, res: Response): Promise<void> {
+        const actor = this.#requireActor(req);
+        res.json(await this.#schedules().get(actor, req.params.scheduleId));
+    }
+
     // -- Cross-user key-value handles --------------------------------
 
     /**
@@ -315,6 +423,7 @@ export class EventsController extends PuterController {
             handlers: await this.services.events.listHandlers(actor, {
                 appUid:
                     typeof query.appUid === 'string' ? query.appUid : undefined,
+                scope: query.scope,
             }),
         });
     }
@@ -413,6 +522,15 @@ export class EventsController extends PuterController {
             throw new HttpError(400, 'Missing or invalid `script`/`appUid`', {
                 legacyCode: 'bad_request',
             });
+        // Absent or empty is the app's own scope.
+        const holder = body.holder === undefined ? '' : body.holder;
+        if (
+            typeof holder !== 'string' ||
+            !(holder === '' || HOLDER_REGEX.test(holder))
+        )
+            throw new HttpError(400, 'Invalid `holder`', {
+                legacyCode: 'bad_request',
+            });
 
         const deployer = this.#eventsWorkerDeployer();
         if (!deployer.enabled) {
@@ -420,15 +538,25 @@ export class EventsController extends PuterController {
             return;
         }
 
-        const outcome = await deployer.ensure(appUid, script);
+        const scope = await deployer.scopeFor(appUid, holder);
+        if (!scope) {
+            res.status(404).json({ deployed: false, reason: 'no-holder' });
+            return;
+        }
+
+        const outcome = await deployer.ensure(scope, script);
         if (outcome === 'deployed') {
             res.json({ deployed: true });
             return;
         }
-        // `failed` and `throttled` are worth another attempt: the rest say
-        // this script is not what the app's handlers currently are.
+        // `failed`, `throttled` and `busy` are worth another attempt: the rest
+        // say this script is not what the app's handlers currently are.
         res.status(
-            outcome === 'failed' || outcome === 'throttled' ? 502 : 404,
+            outcome === 'failed' ||
+                outcome === 'throttled' ||
+                outcome === 'busy'
+                ? 502
+                : 404,
         ).json({
             deployed: false,
             reason: outcome,
@@ -449,14 +577,22 @@ export class EventsController extends PuterController {
     override onServerStart(): void {
         const deployer = this.#eventsWorkerDeployer();
         if (!deployer.enabled) return;
+        this.services.events.useEagerDeploy((scope, script) =>
+            deployer.deployEagerly(scope, script),
+        );
         if (this.config.workers?.localServer) {
             this.services.events.useWorkerTransport(
                 new LocalEventsInvokeTransport(this.services, deployer),
             );
             return;
         }
-        this.services.events.useWorkerMissHandler((appUid, script) =>
-            deployer.ensure(appUid, script),
+        this.services.events.useWorkerMissHandler(
+            async (appUid, script, options) => {
+                const scope = await deployer.scopeFor(appUid, options.holder);
+                return scope
+                    ? deployer.ensure(scope, script, options)
+                    : 'no-holder';
+            },
         );
     }
 

src/backend/controllers/events/limits.test.ts

@@ -34,23 +34,46 @@ import {
     EVENTS_DURABLE_SUBSCRIPTIONS_MAX,
     EVENTS_DURABLE_SUBSCRIPTIONS_PER_APP,
     EVENTS_DURABLE_SUBSCRIPTIONS_PER_USER,
+    EVENTS_HANDLER_PUBLISH_LIMIT,
+    EVENTS_HANDLER_SOURCE_MAX_BYTES,
+    EVENTS_HANDLERS_PER_APP,
     EVENTS_KV_HANDLES_PER_APP,
     EVENTS_KV_HANDLES_PER_USER,
     EVENTS_KV_FILTER_EVALUATIONS_PER_EVENT,
     EVENTS_KV_MATCHED_SUBSCRIPTIONS_PER_EVENT,
     EVENTS_SINGLE_DELIVERY_LIMIT,
+    EVENTS_USER_HANDLERS_PER_SCOPE,
+    EVENTS_USER_SCOPE_SOURCE_MAX_BYTES,
+    EVENTS_USER_WORKER_DEPLOYS_PER_HOUR,
+    EVENTS_WORKER_DEPLOYS_PER_HOUR,
     EVENTS_WORKER_INVOCATION_LIMIT,
+    EVENTS_WORKER_SOURCE_MAX_BYTES,
+    RENTED_UNITS_PER_USER,
     limitFor,
+    tiered,
     type TieredLimit,
 } from './limits.js';
 
 const tiers: Array<[string, TieredLimit]> = [
-    ['durable subscriptions per account', EVENTS_DURABLE_SUBSCRIPTIONS_PER_USER],
+    [
+        'durable subscriptions per account',
+        EVENTS_DURABLE_SUBSCRIPTIONS_PER_USER,
+    ],
     ['durable subscriptions per app', EVENTS_DURABLE_SUBSCRIPTIONS_PER_APP],
     ['live share handles per account', EVENTS_KV_HANDLES_PER_USER],
     ['live share handles per app', EVENTS_KV_HANDLES_PER_APP],
 ];
 
+describe('tiered', () => {
+    it('gives paid plans the base, and the free and temporary tiers their own', () => {
+        const limit = tiered(30, 20, 10);
+        expect(limitFor(limit, null)).toBe(30);
+        expect(limitFor(limit, 'some_plan')).toBe(30);
+        expect(limitFor(limit, DEFAULT_FREE_SUBSCRIPTION)).toBe(20);
+        expect(limitFor(limit, DEFAULT_TEMP_SUBSCRIPTION)).toBe(10);
+    });
+});
+
 describe('the tiered subscription quotas', () => {
     it.each(tiers)('%s never lets a free tier exceed paid', (_name, tier) => {
         for (const n of Object.values(tier.bySubscription))
@@ -105,9 +128,9 @@ describe('the tiered subscription quotas', () => {
     });
 
     it('holds an unrecognised plan to the paid base', () => {
-        expect(limitFor(EVENTS_DURABLE_SUBSCRIPTIONS_PER_USER, 'some_plan')).toBe(
-            EVENTS_DURABLE_SUBSCRIPTIONS_PER_USER.limit,
-        );
+        expect(
+            limitFor(EVENTS_DURABLE_SUBSCRIPTIONS_PER_USER, 'some_plan'),
+        ).toBe(EVENTS_DURABLE_SUBSCRIPTIONS_PER_USER.limit);
         expect(limitFor(EVENTS_DURABLE_SUBSCRIPTIONS_PER_USER, null)).toBe(
             EVENTS_DURABLE_SUBSCRIPTIONS_PER_USER.limit,
         );
@@ -131,9 +154,9 @@ describe('the delivery budgets', () => {
             expect(
                 limitFor(EVENTS_KV_MATCHED_SUBSCRIPTIONS_PER_EVENT, plan),
             ).toBe(matched);
-            expect(
-                limitFor(EVENTS_KV_FILTER_EVALUATIONS_PER_EVENT, plan),
-            ).toBe(evaluated);
+            expect(limitFor(EVENTS_KV_FILTER_EVALUATIONS_PER_EVENT, plan)).toBe(
+                evaluated,
+            );
             expect(evaluated).toBeGreaterThanOrEqual(matched);
         }
     });
@@ -169,3 +192,42 @@ describe('the delivery budgets', () => {
         }
     });
 });
+
+describe('the handler limits', () => {
+    it('pins the app-scope numbers the quotas page lists', () => {
+        expect(EVENTS_HANDLERS_PER_APP).toBe(100);
+        expect(EVENTS_HANDLER_SOURCE_MAX_BYTES).toBe(64 * 1024);
+        expect(EVENTS_WORKER_SOURCE_MAX_BYTES).toBe(5 * 1024 * 1024);
+        expect(EVENTS_WORKER_DEPLOYS_PER_HOUR).toBe(30);
+        expect(EVENTS_HANDLER_PUBLISH_LIMIT.limit).toBe(60);
+        expect(EVENTS_HANDLER_PUBLISH_LIMIT.window).toBe(60_000);
+    });
+
+    it('pins the user-scope numbers the quotas page lists', () => {
+        expect(EVENTS_USER_HANDLERS_PER_SCOPE).toBe(20);
+        expect(EVENTS_USER_SCOPE_SOURCE_MAX_BYTES).toBe(1024 * 1024);
+        expect(EVENTS_USER_WORKER_DEPLOYS_PER_HOUR).toBe(10);
+    });
+
+    it('keeps a user scope tighter than an app scope', () => {
+        expect(EVENTS_USER_HANDLERS_PER_SCOPE).toBeLessThan(
+            EVENTS_HANDLERS_PER_APP,
+        );
+        expect(EVENTS_USER_SCOPE_SOURCE_MAX_BYTES).toBeLessThan(
+            EVENTS_WORKER_SOURCE_MAX_BYTES,
+        );
+        expect(EVENTS_USER_WORKER_DEPLOYS_PER_HOUR).toBeLessThan(
+            EVENTS_WORKER_DEPLOYS_PER_HOUR,
+        );
+    });
+
+    it('pins the rented-unit cap by plan', () => {
+        expect(RENTED_UNITS_PER_USER.limit).toBe(100);
+        expect(limitFor(RENTED_UNITS_PER_USER, DEFAULT_FREE_SUBSCRIPTION)).toBe(
+            16,
+        );
+        expect(limitFor(RENTED_UNITS_PER_USER, DEFAULT_TEMP_SUBSCRIPTION)).toBe(
+            16,
+        );
+    });
+});

src/backend/controllers/events/limits.ts

@@ -53,7 +53,12 @@ export interface TieredLimit {
     bySubscription: Record<string, number>;
 }
 
-const tiered = (paid: number, free: number, temp: number): TieredLimit => ({
+/** Paid, free and temporary caps as a {@link TieredLimit}. Called by extensions. */
+export const tiered = (
+    paid: number,
+    free: number,
+    temp: number,
+): TieredLimit => ({
     limit: paid,
     bySubscription: {
         [DEFAULT_FREE_SUBSCRIPTION]: free,
@@ -264,6 +269,12 @@ export const KV_SHARE_NOTIFY_LIMITS = [
  */
 export const EVENTS_HANDLERS_PER_APP = 100;
 
+/**
+ * Handlers one user may hold in their own scope of one app. Each is a script of
+ * its own, so the cap is tighter than the app's.
+ */
+export const EVENTS_USER_HANDLERS_PER_SCOPE = 20;
+
 /** Longest a serialized handler may be. */
 export const EVENTS_HANDLER_SOURCE_MAX_BYTES = 64 * 1024;
 
@@ -275,6 +286,9 @@ export const EVENTS_HANDLER_SOURCE_MAX_BYTES = 64 * 1024;
  */
 export const EVENTS_WORKER_SOURCE_MAX_BYTES = 5 * 1024 * 1024;
 
+/** Source one user scope may hold, all its handlers combined. */
+export const EVENTS_USER_SCOPE_SOURCE_MAX_BYTES = 1024 * 1024;
+
 /**
  * Deploys one app's events worker may trigger per hour.
  *
@@ -284,6 +298,16 @@ export const EVENTS_WORKER_SOURCE_MAX_BYTES = 5 * 1024 * 1024;
  */
 export const EVENTS_WORKER_DEPLOYS_PER_HOUR = 30;
 
+/** Deploys one user scope may trigger per hour. */
+export const EVENTS_USER_WORKER_DEPLOYS_PER_HOUR = 10;
+
+/**
+ * Units one user may rent at once: ordinary workers, user scopes, and the
+ * events workers of apps they own. Only creating a unit is refused; holdings
+ * over the cap are kept.
+ */
+export const RENTED_UNITS_PER_USER = tiered(100, 16, 16);
+
 /**
  * Handlers one `publishAll` may carry. A build step publishes its whole set in
  * one call, and the set is capped by what an app may hold anyway.
@@ -448,11 +472,13 @@ export const EVENTS_REGION_PENDING_CEILING = 1_000_000;
 // finish backs off the same way but is not the handler's failure, so it never
 // counts toward that run.
 
-/** Wait before the first retry of a delivery a handler could not take. */
-export const EVENTS_RETRY_BASE_MS = 2_000;
-
-/** Longest wait between retries, however many have failed. */
-export const EVENTS_RETRY_MAX_MS = 5 * 60 * 1000;
+// Wait before the first retry of a delivery a handler could not take, the
+// longest wait, and the doubling between them. Shared with system jobs.
+export {
+    deliveryBackoffMs,
+    EVENTS_RETRY_BASE_MS,
+    EVENTS_RETRY_MAX_MS,
+} from '../../util/retryBackoff.js';
 
 /**
  * Handler failures in a row before a subscription is suspended. Counted per
@@ -468,13 +494,6 @@ export const EVENTS_CONSECUTIVE_FAILURES = 5;
  */
 export const EVENTS_FAILURE_COUNTER_TTL_MS = 60 * 60 * 1000;
 
-/** How long to hold a delivery whose handler has failed `attempts` times. */
-export const deliveryBackoffMs = (attempts: number): number =>
-    Math.min(
-        EVENTS_RETRY_MAX_MS,
-        EVENTS_RETRY_BASE_MS * 2 ** Math.max(0, attempts - 1),
-    );
-
 // -- Suspended backlog -----------------------------------------------
 //
 // A suspended subscription stops metering but keeps what it is owed, and that

src/backend/controllers/events/scheduleRoutes.test.ts

@@ -0,0 +1,289 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/**
+ * The schedule routes are thin delegates: without `services.schedules` every
+ * one answers 503 `events_disabled`; with it, each hands its request over and
+ * answers what it returns.
+ */
+
+import type { Request, Response } from 'express';
+import {
+    afterAll,
+    afterEach,
+    beforeAll,
+    describe,
+    expect,
+    it,
+    vi,
+} from 'vitest';
+import { makeActor, type Actor } from '../../core/actor.js';
+import { isHttpError } from '../../core/http/HttpError.js';
+import type {
+    ScheduleServiceContract,
+    ScheduleView,
+} from '../../core/schedules.js';
+import type { PuterServer } from '../../server.js';
+import { setupTestServer } from '../../testUtil.js';
+import type { BroadcastController } from '../broadcast/BroadcastController.js';
+import type { EventsController } from './EventsController.js';
+
+let server: PuterServer;
+let events: EventsController;
+let broadcast: BroadcastController;
+let actor: Actor;
+let saved: unknown;
+
+const SCHEDULE_ID = '0b3a3c9e-9f61-4f0e-8d2a-2f1b6f8f2c11';
+
+const view = {
+    scheduleId: SCHEDULE_ID,
+    kind: 'recurring',
+    appUid: 'app-x',
+} as ScheduleView;
+
+const slot = () => server.services as unknown as { schedules?: unknown };
+/** Put `schedules` in the slot, or leave the slot empty. */
+const setSchedules = (schedules: unknown): void => {
+    if (schedules === undefined) delete slot().schedules;
+    else slot().schedules = schedules;
+};
+
+const fakeSchedules = () =>
+    ({
+        onSubscriptionsChanged: vi.fn(async () => {}),
+        createFor: vi.fn(async () => view),
+        list: vi.fn(async () => ({
+            items: [view],
+            cursor: 'next',
+            total: 3,
+        })),
+        get: vi.fn(async () => view),
+        update: vi.fn(async () => view),
+        remove: vi.fn(async () => {}),
+        receivePeerChanges: vi.fn(async () => ({ applied: 2 })),
+        prepareSendAt: vi.fn(),
+        createDeferredAppMessage: vi.fn(),
+    }) satisfies ScheduleServiceContract;
+
+const req = (init: {
+    body?: unknown;
+    query?: Record<string, unknown>;
+    params?: Record<string, string>;
+}): Request =>
+    ({
+        actor,
+        body: init.body ?? {},
+        query: init.query ?? {},
+        params: init.params ?? {},
+        headers: {},
+        rawBody: Buffer.from(JSON.stringify(init.body ?? {})),
+    }) as unknown as Request;
+
+const res = () => {
+    const sent: { status: number; body: unknown } = {
+        status: 200,
+        body: undefined,
+    };
+    const response = {
+        json: vi.fn((body: unknown) => {
+            sent.body = body;
+            return response;
+        }),
+        status: vi.fn((code: number) => {
+            sent.status = code;
+            return response;
+        }),
+        setHeader: vi.fn(() => response),
+    };
+    return { response: response as unknown as Response, sent };
+};
+
+/** Each route, called as the router would. */
+const routes: Array<[string, (response: Response) => Promise<void>]> = [
+    [
+        'POST /events/schedules',
+        (r) => events.createSchedule(req({ body: { every: 60_000 } }), r),
+    ],
+    [
+        'GET /events/schedules',
+        (r) => events.listSchedules(req({ query: { limit: '5' } }), r),
+    ],
+    [
+        'GET /events/schedules/:scheduleId',
+        (r) =>
+            events.getSchedule(req({ params: { scheduleId: SCHEDULE_ID } }), r),
+    ],
+    [
+        'POST /events/schedules/update',
+        (r) => events.updateSchedule(req({ body: { scheduleId: SCHEDULE_ID, changes: { every: '2h' } } }), r),
+    ],
+    [
+        'POST /events/schedules/remove',
+        (r) =>
+            events.removeSchedule(
+                req({ body: { scheduleId: SCHEDULE_ID } }),
+                r,
+            ),
+    ],
+    [
+        'POST /broadcast/events/schedules',
+        (r) =>
+            broadcast.schedules(
+                req({ body: { namespace: 'n', changes: [] } }),
+                r,
+            ),
+    ],
+];
+
+beforeAll(async () => {
+    server = await setupTestServer();
+    events = server.controllers.events as unknown as EventsController;
+    broadcast = server.controllers.broadcast as unknown as BroadcastController;
+    actor = makeActor({
+        user: { id: 1, uuid: 'u-1', username: 'someone' },
+    } as never);
+    saved = slot().schedules;
+    vi.spyOn(
+        server.services.broadcast,
+        'verifySignedRequest',
+    ).mockResolvedValue({ ok: true, peerId: 'peer' } as never);
+});
+
+afterEach(() => {
+    setSchedules(saved);
+});
+
+afterAll(async () => {
+    vi.restoreAllMocks();
+    await server?.shutdown();
+});
+
+describe('without services.schedules', () => {
+    it.each(routes)('%s answers 503 events_disabled', async (_name, call) => {
+        setSchedules(undefined);
+        const { response } = res();
+        let thrown: unknown;
+        try {
+            await call(response);
+        } catch (err) {
+            thrown = err;
+        }
+        expect(isHttpError(thrown)).toBe(true);
+        expect(thrown).toMatchObject({
+            statusCode: 503,
+            legacyCode: 'events_disabled',
+            // The designed answer, so it never pages.
+            noAlarm: true,
+        });
+    });
+
+    it('refuses an unsigned peer batch before saying schedules are off', async () => {
+        setSchedules(undefined);
+        vi.spyOn(
+            server.services.broadcast,
+            'verifySignedRequest',
+        ).mockResolvedValueOnce({
+            ok: false,
+            status: 401,
+            message: 'bad signature',
+        } as never);
+        const { response, sent } = res();
+        await broadcast.schedules(
+            req({ body: { namespace: 'n', changes: [] } }),
+            response,
+        );
+        expect(sent.status).toBe(401);
+    });
+});
+
+describe('with services.schedules', () => {
+    it('creates through createFor and answers its view', async () => {
+        const schedules = fakeSchedules();
+        setSchedules(schedules);
+        const { response, sent } = res();
+        await events.createSchedule(req({ body: { every: 60_000 } }), response);
+        expect(schedules.createFor).toHaveBeenCalledWith(actor, {
+            every: 60_000,
+        });
+        expect(sent.body).toEqual(view);
+    });
+
+    it('lists with the limit capped, the cursor and includeTotal', async () => {
+        const schedules = fakeSchedules();
+        setSchedules(schedules);
+        const { response, sent } = res();
+        await events.listSchedules(
+            req({
+                query: { limit: '5000', cursor: 'c', includeTotal: 'true' },
+            }),
+            response,
+        );
+        expect(schedules.list).toHaveBeenCalledWith(actor, {
+            limit: 200,
+            cursor: 'c',
+            includeTotal: true,
+        });
+        expect(sent.body).toEqual({ items: [view], cursor: 'next', total: 3 });
+    });
+
+    it('reads one through get', async () => {
+        const schedules = fakeSchedules();
+        setSchedules(schedules);
+        const { response, sent } = res();
+        await events.getSchedule(
+            req({ params: { scheduleId: SCHEDULE_ID } }),
+            response,
+        );
+        expect(schedules.get).toHaveBeenCalledWith(actor, SCHEDULE_ID);
+        expect(sent.body).toEqual(view);
+    });
+
+    it('updates through update and answers its view', async () => {
+        const schedules = fakeSchedules();
+        setSchedules(schedules);
+        const { response, sent } = res();
+        const changes = { every: '2h' };
+        await events.updateSchedule(req({ body: { scheduleId: SCHEDULE_ID, changes } }), response);
+        expect(schedules.update).toHaveBeenCalledWith(actor, SCHEDULE_ID, changes);
+        expect(sent.body).toEqual(view);
+    });
+
+    it('removes through remove and answers {}', async () => {
+        const schedules = fakeSchedules();
+        setSchedules(schedules);
+        const { response, sent } = res();
+        await events.removeSchedule(
+            req({ body: { scheduleId: SCHEDULE_ID } }),
+            response,
+        );
+        expect(schedules.remove).toHaveBeenCalledWith(actor, SCHEDULE_ID);
+        expect(sent.body).toEqual({});
+    });
+
+    it('hands a signed peer batch to receivePeerChanges', async () => {
+        const schedules = fakeSchedules();
+        setSchedules(schedules);
+        const { response, sent } = res();
+        const body = { namespace: 'n', changes: [] };
+        await broadcast.schedules(req({ body }), response);
+        expect(schedules.receivePeerChanges).toHaveBeenCalledWith(body);
+        expect(sent).toEqual({ status: 200, body: { ok: true, applied: 2 } });
+    });
+});

src/backend/controllers/events/updateSchedule.test.ts

@@ -0,0 +1,77 @@
+import type { Request, Response } from 'express';
+import { describe, expect, it } from 'vitest';
+import { makeActor } from '../../core/actor.js';
+import type {
+    ScheduleServiceContract,
+    ScheduleView,
+} from '../../core/schedules.js';
+import { EventsController } from './EventsController.js';
+
+const actor = makeActor({
+    user: { id: 1, uuid: 'user-1', username: 'user1' } as never,
+});
+const request = (body: unknown) => ({ actor, body }) as Request;
+const controller = (schedules?: Pick<ScheduleServiceContract, 'update'>) =>
+    new EventsController(
+        {} as never,
+        {} as never,
+        {} as never,
+        { schedules } as never,
+        {} as never,
+    );
+
+describe('update schedule route contract', () => {
+    it('answers events_disabled when schedules are unavailable', async () => {
+        await expect(
+            controller().updateSchedule(
+                request({ scheduleId: 'id', changes: {} }),
+                {} as Response,
+            ),
+        ).rejects.toMatchObject({
+            legacyCode: 'events_disabled',
+            statusCode: 503,
+            noAlarm: true,
+        });
+    });
+
+    it('passes the actor, id and changes through and returns the updated view', async () => {
+        const view = {
+            scheduleId: 'id',
+            kind: 'recurring',
+            state: 'suspended',
+        } as ScheduleView;
+        const changes = { cron: '0 9 * * *', tz: 'UTC' };
+        const calls: unknown[][] = [];
+        const events = controller({
+            update: async (...args) => {
+                calls.push(args);
+                return view;
+            },
+        });
+        let sent: unknown;
+        await events.updateSchedule(request({ scheduleId: 'id', changes }), {
+            json: (value: unknown) => {
+                sent = value;
+            },
+        } as Response);
+        expect(calls).toEqual([[actor, 'id', changes]]);
+        expect(sent).toBe(view);
+    });
+
+    it('preserves validation and sending errors from the implementation', async () => {
+        const error = {
+            code: 'events_schedule_sending',
+            message: 'Already sending',
+        };
+        await expect(
+            controller({
+                update: async () => {
+                    throw error;
+                },
+            }).updateSchedule(
+                request({ scheduleId: 'id', changes: {} }),
+                {} as Response,
+            ),
+        ).rejects.toBe(error);
+    });
+});

src/backend/controllers/events/workerDeploy.test.ts

@@ -25,9 +25,35 @@
 
 import MockRedis from 'ioredis-mock';
 import { describe, expect, it } from 'vitest';
-import { EVENTS_WORKER_DEPLOYS_PER_HOUR } from './limits.js';
-import { EventsWorkerDeployer } from './workerDeploy.js';
-import { eventsWorkerScript } from '../../services/events/workerRuntime.js';
+import type { fetch as undiciFetch } from 'undici';
+import {
+    DispatcherInvokeTransport,
+    EVENTS_DEPLOYED_HEADER,
+    EVENTS_DISPATCH_ERROR_HEADER,
+    EVENTS_HANDLED_HEADER,
+    EventsWorkerInvokerClient,
+    type EventsInvokeCall,
+} from '../../clients/events/EventsWorkerInvokerClient.js';
+import { INTERNAL_DEPLOY_TARGET } from '../../drivers/workers/WorkerDriver.js';
+import {
+    EVENTS_USER_WORKER_DEPLOYS_PER_HOUR,
+    EVENTS_WORKER_DEPLOYS_PER_HOUR,
+} from './limits.js';
+import {
+    EventsWorkerDeployer,
+    LocalEventsInvokeTransport,
+    type EventsDeployOptions,
+    type EventsDeployOutcome,
+} from './workerDeploy.js';
+import {
+    eventsWorkerScript,
+    userHandlerScript,
+} from '../../services/events/workerRuntime.js';
+import {
+    appHandlerScope,
+    hashContent,
+    type HandlerScope,
+} from '../../stores/events/EventHandlerStore.js';
 import { handlerSetHash } from '../../services/events/workerSource.js';
 import type { IConfig } from '../../types.js';
 
@@ -46,14 +72,22 @@ interface Owner {
 type Layers = ConstructorParameters<typeof EventsWorkerDeployer>[0];
 
 /** Stub layers whose only real dependency is a fresh redis mock. */
-const makeLayers = (owners: Record<string, Owner | null>) => {
+const makeLayers = (
+    owners: Record<string, Owner | null>,
+    events: Record<string, unknown> = {},
+) => {
     const redis = new MockRedis.Cluster(['redis://localhost:7001']);
     const created: string[] = [];
+    const targets: Array<Record<string, unknown>> = [];
     /** Apps whose handler sources were read, once per read. */
     const sourceReads: string[] = [];
     const layers = {
         config: {
-            events: { workerRuntime: true, internalSecret: 'sekret' },
+            events: {
+                workerRuntime: true,
+                internalSecret: 'sekret',
+                ...events,
+            },
             // `#namespace()` needs a local-worker shape to resolve without
             // throwing — this stub never reaches a real Cloudflare or
             // Miniflare deploy either way.
@@ -63,7 +97,7 @@ const makeLayers = (owners: Record<string, Owner | null>) => {
         stores: {
             eventHandler: {
                 setForApp: async () => [{ name: 'h', sourceHash: SOURCE_HASH }],
-                allForApp: async (appUid: string) => {
+                allForApp: async ({ appUid }: { appUid: string }) => {
                     sourceReads.push(appUid);
                     return [
                         {
@@ -86,6 +120,18 @@ const makeLayers = (owners: Record<string, Owner | null>) => {
                 },
             },
             user: {
+                getByUuid: async (uuid: string) => {
+                    const owner = Object.values(owners).find(
+                        (o) => `uuid-${o?.ownerUserId}` === uuid,
+                    );
+                    if (!owner) return null;
+                    return {
+                        id: owner.ownerUserId,
+                        uuid,
+                        username: `user-${owner.ownerUserId}`,
+                        suspended: owner.suspended ?? false,
+                    };
+                },
                 getById: async (id: number) => {
                     const owner = Object.values(owners).find(
                         (o) => o?.ownerUserId === id,
@@ -103,8 +149,12 @@ const makeLayers = (owners: Record<string, Owner | null>) => {
         services: {},
         drivers: {
             workers: {
-                create: async (args: { workerName: string }) => {
+                create: async (args: {
+                    workerName: string;
+                    [INTERNAL_DEPLOY_TARGET]?: Record<string, unknown>;
+                }) => {
                     created.push(args.workerName);
+                    targets.push(args[INTERNAL_DEPLOY_TARGET] ?? {});
                     return { success: true, errors: [] };
                 },
             },
@@ -113,6 +163,7 @@ const makeLayers = (owners: Record<string, Owner | null>) => {
     return {
         layers: layers as unknown as Layers,
         created,
+        targets,
         redis,
         sourceReads,
     };
@@ -131,8 +182,8 @@ describe('EventsWorkerDeployer.ensure', () => {
         const deployer = new EventsWorkerDeployer(layers);
 
         const [a, b] = await Promise.all([
-            deployer.ensure('app-a', SCRIPT),
-            deployer.ensure('app-b', SCRIPT),
+            deployer.ensure(appHandlerScope('app-a'), SCRIPT),
+            deployer.ensure(appHandlerScope('app-b'), SCRIPT),
         ]);
         expect(a).toBe('deployed');
         expect(b).toBe('no-owner');
@@ -149,7 +200,9 @@ describe('EventsWorkerDeployer.ensure', () => {
             String(EVENTS_WORKER_DEPLOYS_PER_HOUR),
         );
 
-        expect(await deployer.ensure('app-c', SCRIPT)).toBe('throttled');
+        expect(await deployer.ensure(appHandlerScope('app-c'), SCRIPT)).toBe(
+            'throttled',
+        );
         expect(sourceReads).toEqual([]);
         expect(created).toEqual([]);
     });
@@ -164,15 +217,680 @@ describe('EventsWorkerDeployer.ensure', () => {
             '',
         );
 
-        expect(await deployer.ensure('app-e', stale)).toBe('stale');
+        expect(await deployer.ensure(appHandlerScope('app-e'), stale)).toBe(
+            'stale',
+        );
         expect(sourceReads).toEqual([]);
         const hour = new Date().toISOString().slice(0, 13);
         expect(await redis.get(`ev:deploys:{app-e}:${hour}`)).toBeNull();
     });
 
+    it('passes events.workerCpuMs to the deploy target', async () => {
+        const { layers, targets } = makeLayers(
+            { 'app-f': { ownerUserId: 6 } },
+            { workerCpuMs: 50 },
+        );
+        const deployer = new EventsWorkerDeployer(layers);
+        expect(await deployer.ensure(appHandlerScope('app-f'), SCRIPT)).toBe(
+            'deployed',
+        );
+        expect(targets[0]!.cpuMs).toBe(50);
+    });
+
+    it('passes no cpuMs when events.workerCpuMs is unset', async () => {
+        const { layers, targets } = makeLayers({ 'app-g': { ownerUserId: 7 } });
+        const deployer = new EventsWorkerDeployer(layers);
+        expect(await deployer.ensure(appHandlerScope('app-g'), SCRIPT)).toBe(
+            'deployed',
+        );
+        expect(targets[0]!.cpuMs).toBeUndefined();
+    });
+
     it('deploys normally under the cap', async () => {
         const { layers } = makeLayers({ 'app-d': { ownerUserId: 4 } });
         const deployer = new EventsWorkerDeployer(layers);
-        expect(await deployer.ensure('app-d', SCRIPT)).toBe('deployed');
+        expect(await deployer.ensure(appHandlerScope('app-d'), SCRIPT)).toBe(
+            'deployed',
+        );
+    });
+});
+
+/** A server's schedules with a deploy gate that records and can refuse. */
+const withGate = (
+    layers: Layers,
+    refuse: (capped: boolean) => boolean = () => false,
+) => {
+    const gated: Array<{ script: string; capped: boolean }> = [];
+    const gate = {
+        gateDeploy: async (
+            script: string,
+            options: { capped: boolean },
+            deploy: () => Promise<EventsDeployOutcome>,
+        ): Promise<EventsDeployOutcome> => {
+            gated.push({ script, capped: options.capped });
+            return refuse(options.capped) ? 'busy' : deploy();
+        },
+    };
+    const deployer = new EventsWorkerDeployer({
+        ...layers,
+        services: { ...layers.services, schedules: gate },
+    } as unknown as Layers);
+    return { deployer, gated };
+};
+
+describe('the schedules` deploy gate', () => {
+    it('is skipped without schedules, or with schedules that have no gate', async () => {
+        const { layers, created } = makeLayers({ 'app-x': { ownerUserId: 1 } });
+        await expect(
+            new EventsWorkerDeployer(layers).ensure(
+                appHandlerScope('app-x'),
+                SCRIPT,
+                {
+                    lane: 'schedule',
+                },
+            ),
+        ).resolves.toBe('deployed');
+        const gateless = new EventsWorkerDeployer({
+            ...layers,
+            services: { ...layers.services, schedules: {} },
+        } as unknown as Layers);
+        await expect(
+            gateless.ensure(appHandlerScope('app-x'), SCRIPT, {
+                lane: 'schedule',
+            }),
+        ).resolves.toBe('deployed');
+        expect(created).toEqual([SCRIPT, SCRIPT]);
+    });
+
+    it('takes every deploy, capped only for a schedule run', async () => {
+        const { layers, created } = makeLayers({ 'app-x': { ownerUserId: 1 } });
+        const { deployer, gated } = withGate(layers);
+
+        await expect(
+            deployer.ensure(appHandlerScope('app-x'), SCRIPT),
+        ).resolves.toBe('deployed');
+        await expect(
+            deployer.ensure(appHandlerScope('app-x'), SCRIPT, {
+                lane: 'schedule',
+            }),
+        ).resolves.toBe('deployed');
+        expect(gated).toEqual([
+            { script: SCRIPT, capped: false },
+            { script: SCRIPT, capped: true },
+        ]);
+        expect(created).toEqual([SCRIPT, SCRIPT]);
+    });
+
+    it('answers a refused schedule run busy, and a delivery still deploys', async () => {
+        const { layers, created } = makeLayers({ 'app-x': { ownerUserId: 1 } });
+        const { deployer } = withGate(layers, (capped) => capped);
+
+        await expect(
+            deployer.ensure(appHandlerScope('app-x'), SCRIPT, {
+                lane: 'schedule',
+            }),
+        ).resolves.toBe('busy');
+        await expect(
+            deployer.ensure(appHandlerScope('app-x'), SCRIPT),
+        ).resolves.toBe('deployed');
+        expect(created).toEqual([SCRIPT]);
+    });
+
+    it('lets deliveries that join a schedule run`s refused deploy deploy once', async () => {
+        const { layers, created } = makeLayers({ 'app-x': { ownerUserId: 1 } });
+        const { deployer, gated } = withGate(layers, (capped) => capped);
+
+        const scheduled = deployer.ensure(appHandlerScope('app-x'), SCRIPT, {
+            lane: 'schedule',
+        });
+        const deliveries = [
+            deployer.ensure(appHandlerScope('app-x'), SCRIPT),
+            deployer.ensure(appHandlerScope('app-x'), SCRIPT),
+        ];
+        await expect(scheduled).resolves.toBe('busy');
+        await expect(Promise.all(deliveries)).resolves.toEqual([
+            'deployed',
+            'deployed',
+        ]);
+        expect(created).toEqual([SCRIPT]);
+        expect(gated.map((g) => g.capped)).toEqual([true, false]);
+    });
+
+    it('lets a schedule run join a delivery`s deploy in flight', async () => {
+        const { layers, created } = makeLayers({ 'app-x': { ownerUserId: 1 } });
+        const { deployer, gated } = withGate(layers, (capped) => capped);
+
+        const delivery = deployer.ensure(appHandlerScope('app-x'), SCRIPT);
+        const scheduled = deployer.ensure(appHandlerScope('app-x'), SCRIPT, {
+            lane: 'schedule',
+        });
+        await expect(Promise.all([delivery, scheduled])).resolves.toEqual([
+            'deployed',
+            'deployed',
+        ]);
+        expect(gated).toEqual([{ script: SCRIPT, capped: false }]);
+        expect(created).toEqual([SCRIPT]);
+    });
+});
+
+describe('LocalEventsInvokeTransport', () => {
+    it('renders each request as it goes out, after a cold deploy', async () => {
+        const bodies: string[] = [];
+        let resident = false;
+        const transport = new LocalEventsInvokeTransport(
+            {
+                localworkerservice: {
+                    dispatchEventsWorker: async (request: Request) => {
+                        bodies.push(await request.text());
+                        if (!resident) return null;
+                        return new Response(null, {
+                            status: 200,
+                            headers: { 'x-puter-events-handled': '1' },
+                        });
+                    },
+                },
+            } as never,
+            {
+                ensure: async () => {
+                    resident = true;
+                    return 'deployed';
+                },
+                scopeFor: async (appUid: string) => appHandlerScope(appUid),
+            } as unknown as EventsWorkerDeployer,
+        );
+        let renders = 0;
+        const call: EventsInvokeCall = {
+            script: SCRIPT,
+            appUid: 'app-x',
+            key: 'k',
+            body: '{"n":0}',
+            timeoutMs: 5000,
+            render: () => `{"n":${++renders}}`,
+        };
+        await expect(transport.send(call)).resolves.toMatchObject({
+            status: 200,
+        });
+        expect(bodies).toEqual(['{"n":1}', '{"n":2}']);
+    });
+});
+
+describe('deploy-on-miss of an evicted script', () => {
+    it('redeploys the evicted script, then resends the run with the deployed marker', async () => {
+        const { layers, created } = makeLayers({ 'app-m': { ownerUserId: 8 } });
+        // The namespace only has the script once the deploy lands: before
+        // that the dispatcher answers a miss.
+        let resident = false;
+        layers.drivers.workers.create = (async (args: {
+            workerName: string;
+        }) => {
+            created.push(args.workerName);
+            resident = true;
+            return { success: true, errors: [] };
+        }) as never;
+        const deployer = new EventsWorkerDeployer(layers);
+
+        const sent: boolean[] = [];
+        const fetchImpl = (async (_url: string, init?: RequestInit) => {
+            const headers = (init?.headers ?? {}) as Record<string, string>;
+            sent.push(headers[EVENTS_DEPLOYED_HEADER] === '1');
+            if (resident)
+                return new Response(null, {
+                    status: 200,
+                    headers: { [EVENTS_HANDLED_HEADER]: '1' },
+                });
+            return new Response(null, {
+                status: 404,
+                headers: { [EVENTS_DISPATCH_ERROR_HEADER]: 'missing' },
+            });
+        }) as unknown as typeof undiciFetch;
+
+        const client = new EventsWorkerInvokerClient({
+            events: { workerRuntime: true },
+        } as IConfig);
+        client.setTransport(
+            new DispatcherInvokeTransport('http://dispatcher', 's', {
+                fetchImpl,
+            }),
+        );
+        client.setMissHandler((appUid, script, options) =>
+            deployer.ensure(appHandlerScope(appUid), script, options),
+        );
+
+        const result = await client.invoke({
+            script: SCRIPT,
+            appUid: 'app-m',
+            handler: 'h',
+            token: 't',
+            key: 'k',
+            event: {},
+            ctx: {},
+        });
+
+        expect(result).toEqual({ outcome: 'settled', status: 200 });
+        expect(created).toEqual([SCRIPT]);
+        // One miss, then the resend carrying the deployed marker.
+        expect(sent).toEqual([false, true]);
+    });
+});
+
+// The redis mock is shared across tests, so each one uses its own app and code.
+let fresh = 0;
+const nextApp = () => `app-u${++fresh}`;
+const userScope = (holder: number, appUid: string) => ({ appUid, holder });
+const sourceN = (label: string) =>
+    `async () => { await ${label}${++fresh}(); }`;
+const scriptOf = (name: string, source: string) =>
+    userHandlerScript({ name, sourceHash: hashContent(source) }, '');
+
+type Sets = Record<number, Array<{ name: string; source: string }>>;
+
+/** Layers whose handler sets are per holder (0 is the app's own). */
+const withSets = (layers: Layers, sets: Sets) => {
+    const handlersOf = (scope: { appUid: string; holder: number }) =>
+        (sets[scope.holder] ?? []).map((h) => ({
+            appUid: scope.appUid,
+            name: h.name,
+            source: h.source,
+            sourceHash: hashContent(h.source),
+            createdAt: 0,
+            updatedAt: 0,
+        }));
+    const store = layers.stores.eventHandler as unknown as Record<
+        string,
+        unknown
+    >;
+    store.setForApp = async (scope: { appUid: string; holder: number }) =>
+        handlersOf(scope).map(({ name, sourceHash }) => ({ name, sourceHash }));
+    store.allForApp = async (scope: { appUid: string; holder: number }) =>
+        handlersOf(scope);
+};
+
+const holders = (...ids: number[]) =>
+    Object.fromEntries(
+        ids.map((id) => [`holder-${id}`, { ownerUserId: id }]),
+    ) as Record<string, Owner>;
+
+describe('EventsWorkerDeployer in a user scope', () => {
+    it('deploys the one handler whose script was asked for, as the holder', async () => {
+        const app = nextApp();
+        const a = sourceN('a');
+        const b = sourceN('b');
+        const { layers, created, targets } = makeLayers(holders(10));
+        withSets(layers, {
+            10: [
+                { name: 'a', source: a },
+                { name: 'b', source: b },
+            ],
+        });
+        const deployer = new EventsWorkerDeployer(layers);
+
+        const script = scriptOf('b', b);
+        expect(await deployer.ensure(userScope(10, app), script)).toBe(
+            'deployed',
+        );
+
+        expect(created).toEqual([script]);
+        const target = targets[0]!;
+        expect(target.tags).toEqual([`events-app:${app}`, 'user:uuid-10']);
+        // One handler's script: the other one's code is not in it.
+        expect(target.source).toContain(b);
+        expect(target.source).not.toContain(a);
+    });
+
+    it('answers a script no handler of the scope matches as stale, before the throttle', async () => {
+        const app = nextApp();
+        const { layers, redis, created } = makeLayers(holders(10));
+        withSets(layers, { 10: [{ name: 'a', source: sourceN('a') }] });
+        const deployer = new EventsWorkerDeployer(layers);
+
+        expect(
+            await deployer.ensure(
+                userScope(10, app),
+                scriptOf('b', sourceN('b')),
+            ),
+        ).toBe('stale');
+        expect(created).toEqual([]);
+        const hour = new Date().toISOString().slice(0, 13);
+        expect(await redis.get(`ev:deploys:{${app}}:10:${hour}`)).toBeNull();
+    });
+
+    it('answers a scope with no handlers as no-handlers', async () => {
+        const { layers } = makeLayers(holders(10));
+        withSets(layers, {});
+        const deployer = new EventsWorkerDeployer(layers);
+        expect(
+            await deployer.ensure(
+                userScope(10, nextApp()),
+                scriptOf('a', sourceN('a')),
+            ),
+        ).toBe('no-handlers');
+    });
+
+    it('does not deploy for a holder that is suspended or gone', async () => {
+        const source = sourceN('a');
+        const { layers, created } = makeLayers({
+            'holder-10': { ownerUserId: 10, suspended: true },
+        });
+        withSets(layers, {
+            10: [{ name: 'a', source }],
+            11: [{ name: 'a', source }],
+        });
+        const deployer = new EventsWorkerDeployer(layers);
+        const script = scriptOf('a', source);
+        const app = nextApp();
+
+        expect(await deployer.ensure(userScope(10, app), script)).toBe(
+            'no-owner',
+        );
+        expect(await deployer.ensure(userScope(11, app), script)).toBe(
+            'no-owner',
+        );
+        expect(created).toEqual([]);
+    });
+
+    it('gives each scope its own hourly cap, apart from the app scope', async () => {
+        const app = nextApp();
+        const source = sourceN('a');
+        const { layers, created } = makeLayers({
+            ...holders(10, 11),
+            [app]: { ownerUserId: 12 },
+        });
+        withSets(layers, {
+            0: [{ name: 'a', source }],
+            10: [{ name: 'a', source }],
+            11: [{ name: 'a', source }],
+        });
+        const deployer = new EventsWorkerDeployer(layers);
+        const script = scriptOf('a', source);
+
+        for (let i = 0; i < EVENTS_USER_WORKER_DEPLOYS_PER_HOUR; i++)
+            expect(await deployer.ensure(userScope(10, app), script)).toBe(
+                'deployed',
+            );
+        expect(await deployer.ensure(userScope(10, app), script)).toBe(
+            'throttled',
+        );
+        expect(created).toHaveLength(EVENTS_USER_WORKER_DEPLOYS_PER_HOUR);
+
+        // Another holder of the same app, and the app's own scope, still go.
+        expect(await deployer.ensure(userScope(11, app), script)).toBe(
+            'deployed',
+        );
+        expect(await deployer.ensure(appHandlerScope(app), script)).toBe(
+            'deployed',
+        );
+    });
+
+    it('collapses concurrent deploys of one script across holders into one upload', async () => {
+        const app = nextApp();
+        const source = sourceN('a');
+        const { layers, created } = makeLayers(holders(10, 11));
+        withSets(layers, {
+            10: [{ name: 'a', source }],
+            11: [{ name: 'a', source }],
+        });
+        const deployer = new EventsWorkerDeployer(layers);
+        const script = scriptOf('a', source);
+
+        await Promise.all([
+            deployer.ensure(userScope(10, app), script),
+            deployer.ensure(userScope(10, app), script),
+            deployer.ensure(userScope(11, app), script),
+            deployer.ensure(userScope(11, nextApp()), script),
+        ]);
+        expect(created).toHaveLength(1);
+    });
+
+    it('names a script for identical code the same under any holder and app', async () => {
+        const source = sourceN('a');
+        const { layers, created } = makeLayers(holders(10, 11));
+        withSets(layers, {
+            10: [{ name: '@x', source }],
+            11: [{ name: '@x', source }],
+        });
+        const deployer = new EventsWorkerDeployer(layers);
+        const script = scriptOf('@x', source);
+
+        expect(await deployer.ensure(userScope(10, nextApp()), script)).toBe(
+            'deployed',
+        );
+        expect(await deployer.ensure(userScope(11, nextApp()), script)).toBe(
+            'deployed',
+        );
+        expect(created).toEqual([script, script]);
+    });
+});
+
+describe('the deployed marker', () => {
+    const setup = () => {
+        const source = sourceN('a');
+        const made = makeLayers(holders(10, 11));
+        withSets(made.layers, {
+            10: [{ name: 'a', source }],
+            11: [{ name: 'a', source }],
+        });
+        return {
+            ...made,
+            deployer: new EventsWorkerDeployer(made.layers),
+            script: scriptOf('a', source),
+            app: nextApp(),
+        };
+    };
+
+    it('is left by a user-scope deploy with a ttl under a day', async () => {
+        const { deployer, redis, script, app } = setup();
+        await deployer.ensure(userScope(10, app), script);
+        const ttl = await redis.ttl(`ev:deployed:${script}`);
+        expect(ttl).toBeGreaterThan(0);
+        expect(ttl).toBeLessThan(24 * 60 * 60);
+    });
+
+    it('lets an eager deploy skip the upload another holder already made', async () => {
+        const { deployer, created, script, app } = setup();
+        expect(await deployer.deployEagerly(userScope(10, app), script)).toBe(
+            'deployed',
+        );
+        expect(await deployer.deployEagerly(userScope(11, app), script)).toBe(
+            'deployed',
+        );
+        expect(created).toEqual([script]);
+    });
+
+    it('spends no throttle on a skipped eager deploy', async () => {
+        const { deployer, redis, script, app } = setup();
+        await deployer.deployEagerly(userScope(10, app), script);
+        await deployer.deployEagerly(userScope(11, app), script);
+        const hour = new Date().toISOString().slice(0, 13);
+        expect(await redis.get(`ev:deploys:{${app}}:11:${hour}`)).toBeNull();
+    });
+
+    it('never skips a deploy-on-miss', async () => {
+        const { deployer, created, script, app } = setup();
+        await deployer.deployEagerly(userScope(10, app), script);
+        expect(await deployer.ensure(userScope(11, app), script)).toBe(
+            'deployed',
+        );
+        expect(created).toEqual([script, script]);
+    });
+
+    it('is not left by an app-scope deploy', async () => {
+        const app = nextApp();
+        const source = sourceN('a');
+        const { layers, redis, created } = makeLayers({
+            [app]: { ownerUserId: 4 },
+        });
+        withSets(layers, { 0: [{ name: 'a', source }] });
+        const deployer = new EventsWorkerDeployer(layers);
+        const script = scriptOf('a', source);
+        await deployer.ensure(appHandlerScope(app), script);
+        expect(created).toEqual([script]);
+        expect(await redis.get(`ev:deployed:${script}`)).toBeNull();
+    });
+
+    it('still deploys eagerly when the marker cannot be read', async () => {
+        const { deployer, redis, created, script, app } = setup();
+        await deployer.deployEagerly(userScope(10, app), script);
+        const get = redis.get.bind(redis);
+        redis.get = (async (key: string) => {
+            if (key.startsWith('ev:deployed:')) throw new Error('down');
+            return get(key);
+        }) as never;
+        expect(await deployer.deployEagerly(userScope(11, app), script)).toBe(
+            'deployed',
+        );
+        expect(created).toEqual([script, script]);
+    });
+});
+
+describe('scopeFor', () => {
+    it('reads no holder as the app scope, and resolves a uuid to the user scope', async () => {
+        const { layers } = makeLayers(holders(10));
+        const deployer = new EventsWorkerDeployer(layers);
+        expect(await deployer.scopeFor('app-u')).toEqual({
+            appUid: 'app-u',
+            holder: 0,
+        });
+        expect(await deployer.scopeFor('app-u', '')).toEqual({
+            appUid: 'app-u',
+            holder: 0,
+        });
+        expect(await deployer.scopeFor('app-u', 'uuid-10')).toEqual({
+            appUid: 'app-u',
+            holder: 10,
+        });
+        expect(await deployer.scopeFor('app-u', 'uuid-99')).toBeNull();
+    });
+});
+
+describe('LocalEventsInvokeTransport in a user scope', () => {
+    it('deploys the holder`s script on a miss and refuses an unknown holder', async () => {
+        const source = sourceN('a');
+        const { layers, created } = makeLayers(holders(10));
+        withSets(layers, { 10: [{ name: 'a', source }] });
+        const deployer = new EventsWorkerDeployer(layers);
+        let resident = false;
+        const transport = new LocalEventsInvokeTransport(
+            {
+                localworkerservice: {
+                    dispatchEventsWorker: async () => {
+                        if (!resident) return null;
+                        return new Response(null, {
+                            status: 200,
+                            headers: { 'x-puter-events-handled': '1' },
+                        });
+                    },
+                },
+            } as never,
+            {
+                ensure: async (
+                    scope: HandlerScope,
+                    script: string,
+                    options: EventsDeployOptions,
+                ) => {
+                    const outcome = await deployer.ensure(
+                        scope,
+                        script,
+                        options,
+                    );
+                    resident = outcome === 'deployed';
+                    return outcome;
+                },
+                scopeFor: (appUid: string, holder?: string) =>
+                    deployer.scopeFor(appUid, holder),
+            } as unknown as EventsWorkerDeployer,
+        );
+        const script = scriptOf('a', source);
+        const call: EventsInvokeCall = {
+            script,
+            appUid: nextApp(),
+            holder: 'uuid-10',
+            key: 'k',
+            body: '{}',
+            timeoutMs: 5000,
+        };
+
+        await expect(transport.send(call)).resolves.toMatchObject({
+            status: 200,
+        });
+        expect(created).toEqual([script]);
+
+        resident = false;
+        await expect(
+            transport.send({ ...call, holder: 'uuid-99' }),
+        ).resolves.toMatchObject({ status: null, error: 'deploy: no-holder' });
+        expect(created).toEqual([script]);
+    });
+});
+
+describe('concurrent eager deploys of one script', () => {
+    const setup = () => {
+        const source = sourceN('a');
+        const made = makeLayers(holders(10, 11));
+        withSets(made.layers, {
+            10: [{ name: 'a', source }],
+            11: [{ name: 'a', source }],
+        });
+        return {
+            ...made,
+            script: scriptOf('a', source),
+            app: nextApp(),
+        };
+    };
+
+    it('upload once when two holders publish the same new code together', async () => {
+        const { layers, created, script, app } = setup();
+        const deployer = new EventsWorkerDeployer(layers);
+
+        const outcomes = await Promise.all([
+            deployer.deployEagerly(userScope(10, app), script),
+            deployer.deployEagerly(userScope(11, app), script),
+        ]);
+
+        expect(outcomes).toEqual(['deployed', 'deployed']);
+        expect(created).toEqual([script]);
+    });
+
+    it('skip the upload when the marker appears while they wait on the gate', async () => {
+        const { layers, redis, created, script, app } = setup();
+        // Another node's deploy of the script finishes before the gate opens.
+        const gated = new EventsWorkerDeployer({
+            ...layers,
+            services: {
+                schedules: {
+                    gateDeploy: async (
+                        _script: string,
+                        _options: { capped: boolean },
+                        deploy: () => Promise<EventsDeployOutcome>,
+                    ) => {
+                        await redis.set(`ev:deployed:${script}`, '1');
+                        return deploy();
+                    },
+                },
+            },
+        } as unknown as Layers);
+
+        expect(
+            await gated.ensure(userScope(10, app), script, { eager: true }),
+        ).toBe('deployed');
+        expect(created).toEqual([]);
+        // A miss still uploads, whatever the marker says.
+        expect(await gated.ensure(userScope(11, app), script)).toBe('deployed');
+        expect(created).toEqual([script]);
+    });
+
+    it('make a miss that joins an eager deploy deploy after it', async () => {
+        const { layers, redis, created, script, app } = setup();
+        const deployer = new EventsWorkerDeployer(layers);
+        await redis.set(`ev:deployed:${script}`, '1');
+
+        const eager = deployer.ensure(userScope(10, app), script, {
+            eager: true,
+        });
+        const miss = deployer.ensure(userScope(11, app), script);
+
+        expect(await eager).toBe('deployed');
+        expect(await miss).toBe('deployed');
+        // The eager one skipped on the marker; the miss uploaded.
+        expect(created).toEqual([script]);
     });
 });

src/backend/controllers/events/workerDeploy.ts

@@ -29,6 +29,7 @@ import {
 import type {
     EventsInvokeAnswer,
     EventsInvokeCall,
+    InvokeLane,
 } from '../../clients/events/EventsWorkerInvokerClient.js';
 import {
     EVENTS_INVOKE_PATH,
@@ -36,47 +37,89 @@ import {
     failedAnswer,
 } from '../../clients/events/EventsWorkerInvokerClient.js';
 import type { puterServices } from '../../services/index.js';
+import type { IExtensionServiceInstances } from '../../services/types.js';
 import {
     eventsInvokeKey,
     eventsWorkerScope,
     eventsWorkerScript,
+    userHandlerScript,
 } from '../../services/events/workerRuntime.js';
 import {
     generateEventsWorkerSource,
     handlerSetHash,
 } from '../../services/events/workerSource.js';
+import {
+    appHandlerScope,
+    type HandlerScope,
+} from '../../stores/events/EventHandlerStore.js';
 import type { puterStores } from '../../stores/index.js';
 import type { IConfig, LayerInstances } from '../../types.js';
-import { EVENTS_WORKER_DEPLOYS_PER_HOUR } from './limits.js';
+import {
+    EVENTS_USER_WORKER_DEPLOYS_PER_HOUR,
+    EVENTS_WORKER_DEPLOYS_PER_HOUR,
+} from './limits.js';
 
 /**
  * Deploys an app's events worker from its published handlers.
  *
  * Deployed the first time a delivery needs it and again on eviction — a publish
- * only writes rows. Scripts carry no worker token and no `subdomains` row: not
- * one of the owner's workers, not addressable from the internet, not listed or
- * deleted as if it were. A republished set leaves the old script behind rather
- * than deleting it; redeploying a still-live one is always safe.
+ * only writes rows (a user-scope publish also deploys eagerly). An app's scope
+ * is one script for the whole set; a user scope is one script per handler,
+ * deployed as the holder. Scripts carry no worker token and no `subdomains`
+ * row: not one of the owner's workers, not addressable from the internet, not
+ * listed or deleted as if it were. A republished set leaves the old script
+ * behind rather than deleting it; redeploying a still-live one is always safe.
  */
 
 /** Why a deploy could not happen, for the callers that answer differently. */
 export type EventsDeployOutcome =
-    'deployed' | 'stale' | 'no-handlers' | 'no-owner' | 'throttled' | 'failed';
+    | 'deployed'
+    | 'stale'
+    | 'no-handlers'
+    | 'no-owner'
+    | 'throttled'
+    | 'failed'
+    | 'busy';
+
+/** Whose call asked for the deploy: a schedule run's is held to a share. */
+export interface EventsDeployOptions {
+    lane?: InvokeLane;
+    /**
+     * A user-scope publish's deploy, which skips the upload when the script's
+     * deployed marker is already set. A deploy-on-miss is never eager.
+     */
+    eager?: boolean;
+}
 
 interface DeployLayers {
     config: IConfig;
     clients: LayerInstances<typeof puterClients>;
     stores: LayerInstances<typeof puterStores>;
-    services: LayerInstances<typeof puterServices>;
+    services: LayerInstances<typeof puterServices> &
+        Pick<IExtensionServiceInstances, 'schedules'>;
     drivers: LayerInstances<typeof puterDrivers>;
 }
 
 /**
- * `ev:deploys:{<appUid>}:<hour>` bucket TTL — comfortably past the hour it
- * counts.
+ * `ev:deploys:{<appUid>}[:<holder>]:<hour>` bucket TTL — comfortably past the
+ * hour it counts.
  */
 const DEPLOY_THROTTLE_TTL_SECONDS = 2 * 60 * 60;
 
+/** How long `ev:deployed:<script>` says a script was uploaded. Under a day. */
+const DEPLOYED_MARKER_TTL_SECONDS = 20 * 60 * 60;
+
+const deployedMarkerKey = (script: string): string => `ev:deployed:${script}`;
+
+const isUserScope = (scope: HandlerScope): boolean => scope.holder !== 0;
+
+interface InFlightDeploy {
+    /** A schedule run's, which the region's deploy slots may refuse. */
+    capped: boolean;
+    eager: boolean;
+    promise: Promise<EventsDeployOutcome>;
+}
+
 interface DeployResult {
     success?: boolean;
     errors?: unknown[];
@@ -85,7 +128,7 @@ interface DeployResult {
 export class EventsWorkerDeployer {
     readonly #layers: DeployLayers;
     /** Collapses the burst of misses one cold app produces into one deploy. */
-    readonly #inFlight = new Map<string, Promise<EventsDeployOutcome>>();
+    readonly #inFlight = new Map<string, InFlightDeploy>();
 
     constructor(layers: DeployLayers) {
         this.#layers = layers;
@@ -100,44 +143,188 @@ export class EventsWorkerDeployer {
     }
 
     /**
-     * Deploy `script`, which must be what the app's handlers currently hash to.
-     * A request for anything else is `stale` — the set moved on, and the next
-     * delivery resolves the new script rather than this one being revived.
+     * Deploy `script`, which must be what the scope's handlers currently hash
+     * to: the whole set for an app, one handler for a user scope. A request for
+     * anything else is `stale` — the handlers moved on, and the next delivery
+     * resolves the new script rather than this one being revived. Always
+     * uploads; a deploy-on-miss means whatever said it was there is wrong.
      */
-    ensure(appUid: string, script: string): Promise<EventsDeployOutcome> {
-        const key = `${appUid}|${script}`;
+    ensure(
+        scope: HandlerScope,
+        script: string,
+        options: EventsDeployOptions = {},
+    ): Promise<EventsDeployOutcome> {
+        // A user scope's script is the same bytes whoever holds it, so
+        // concurrent deploys of it from any holder or app are one.
+        const key = isUserScope(scope)
+            ? `user|${script}`
+            : `${scope.appUid}|${scope.holder}|${script}`;
+        const capped = options.lane === 'schedule';
         const existing = this.#inFlight.get(key);
-        if (existing) return existing;
-        const started = this.#deploy(appUid, script).finally(() =>
-            this.#inFlight.delete(key),
+        if (!existing) return this.#start(key, scope, script, options);
+        // An eager deploy may have skipped the upload, which a miss must not
+        // take for done.
+        if (existing.eager && !options.eager)
+            return this.#afterEager(
+                existing.promise,
+                key,
+                scope,
+                script,
+                options,
+            );
+        if (capped || !existing.capped) return existing.promise;
+        return this.#afterCapped(existing.promise, key, scope, script, options);
+    }
+
+    /**
+     * {@link ensure} for the deploy a user-scope publish starts, which skips the
+     * upload when another holder's deploy of the same script left its marker.
+     * Only this path reads the marker.
+     */
+    async deployEagerly(
+        scope: HandlerScope,
+        script: string,
+    ): Promise<EventsDeployOutcome> {
+        if (await this.#markedDeployed(script)) return 'deployed';
+        return this.ensure(scope, script, { eager: true });
+    }
+
+    /**
+     * The scope a script request names: the app's own, or the user scope of
+     * `holder` (a user uuid). Null for a holder that does not exist.
+     */
+    async scopeFor(
+        appUid: string,
+        holder?: string | null,
+    ): Promise<HandlerScope | null> {
+        if (!holder) return appHandlerScope(appUid);
+        const user = await this.#layers.stores.user.getByUuid(holder);
+        if (!user?.id) return null;
+        return { appUid, holder: Number(user.id) };
+    }
+
+    #start(
+        key: string,
+        scope: HandlerScope,
+        script: string,
+        options: EventsDeployOptions,
+    ): Promise<EventsDeployOutcome> {
+        const entry: InFlightDeploy = {
+            capped: options.lane === 'schedule',
+            eager: options.eager === true,
+            promise: this.#gated(scope, script, options).finally(() => {
+                if (this.#inFlight.get(key) === entry)
+                    this.#inFlight.delete(key);
+            }),
+        };
+        this.#inFlight.set(key, entry);
+        return entry.promise;
+    }
+
+    /** A miss that found an eager deploy in flight deploys after it. */
+    async #afterEager(
+        eager: Promise<EventsDeployOutcome>,
+        key: string,
+        scope: HandlerScope,
+        script: string,
+        options: EventsDeployOptions,
+    ): Promise<EventsDeployOutcome> {
+        await eager;
+        const current = this.#inFlight.get(key);
+        if (current && !current.eager) return current.promise;
+        return this.#start(key, scope, script, options);
+    }
+
+    /**
+     * A delivery that joined a schedule run's deploy: `busy` means no deploy
+     * started, and a delivery is never refused a slot, so it asks again.
+     */
+    async #afterCapped(
+        capped: Promise<EventsDeployOutcome>,
+        key: string,
+        scope: HandlerScope,
+        script: string,
+        options: EventsDeployOptions,
+    ): Promise<EventsDeployOutcome> {
+        const outcome = await capped;
+        if (outcome !== 'busy') return outcome;
+        const current = this.#inFlight.get(key);
+        if (current && !current.capped) return current.promise;
+        return this.#start(key, scope, script, options);
+    }
+
+    /**
+     * Every deploy goes through the schedules' deploy gate when a server has
+     * one: a per-script lock, so a burst of runs of an evicted script deploys
+     * it once, and a region-wide cap that a schedule run's deploy (`capped`)
+     * may be refused with `busy`. A delivery's deploy is never refused.
+     */
+    #gated(
+        scope: HandlerScope,
+        script: string,
+        options: EventsDeployOptions,
+    ): Promise<EventsDeployOutcome> {
+        const deploy = () =>
+            this.#deploy(scope, script, options.eager === true);
+        return (
+            this.#layers.services.schedules?.gateDeploy?.(
+                script,
+                { capped: options.lane === 'schedule' },
+                deploy,
+            ) ?? deploy()
         );
-        this.#inFlight.set(key, started);
-        return started;
     }
 
     async #deploy(
-        appUid: string,
+        handlerScope: HandlerScope,
         script: string,
+        eager: boolean,
     ): Promise<EventsDeployOutcome> {
+        const { appUid } = handlerScope;
         const { stores, drivers } = this.#layers;
-        const scope = eventsWorkerScope(this.#layers.config);
+        const backend = eventsWorkerScope(this.#layers.config);
+        const userScope = isUserScope(handlerScope);
 
         // Names and hashes are enough to tell a stale request, so the set's
         // sources are read and built only once the throttle has let it through.
-        const set = await stores.eventHandler.setForApp(appUid);
+        const set = await stores.eventHandler.setForApp(handlerScope);
         if (set.length === 0) return 'no-handlers';
         // Two apps that published byte-identical sets share one script, which
         // is sound: the source is the same, and everything per-app arrives with
-        // the invocation. Whoever deploys first owns it.
-        if (eventsWorkerScript(handlerSetHash(set), scope) !== script)
+        // the invocation. Whoever deploys first owns it. A user scope's script
+        // is one handler's, so it is shared the same way across holders.
+        const wanted = userScope
+            ? set.find((entry) => userHandlerScript(entry, backend) === script)
+            : undefined;
+        if (
+            userScope
+                ? !wanted
+                : eventsWorkerScript(handlerSetHash(set), backend) !== script
+        )
             return 'stale';
 
-        if (await this.#tooManyDeploysThisHour(appUid)) return 'throttled';
+        // Asked again inside the gate, where another deploy of this script may
+        // have just finished.
+        if (eager && userScope && (await this.#markedDeployed(script)))
+            return 'deployed';
 
-        const handlers = await stores.eventHandler.allForApp(appUid);
+        if (await this.#tooManyDeploysThisHour(handlerScope))
+            return 'throttled';
+
+        const all = await stores.eventHandler.allForApp(handlerScope);
+        const handlers = wanted
+            ? all.filter(
+                  (handler) =>
+                      handler.name === wanted.name &&
+                      handler.sourceHash === wanted.sourceHash,
+              )
+            : all;
         const generated = generateEventsWorkerSource(handlers);
         // The set can move between the two reads.
-        if (eventsWorkerScript(generated.setHash, scope) !== script)
+        if (
+            handlers.length === 0 ||
+            eventsWorkerScript(generated.setHash, backend) !== script
+        )
             return 'stale';
         if (generated.tooLarge) {
             console.error(
@@ -151,7 +338,7 @@ export class EventsWorkerDeployer {
                 generated.broken.join(', '),
             );
 
-        const owner = await this.#owner(appUid);
+        const owner = await this.#owner(handlerScope);
         if (!owner) return 'no-owner';
 
         const secret = this.#layers.config.events?.internalSecret;
@@ -180,6 +367,7 @@ export class EventsWorkerDeployer {
                         runtime: 'events',
                         source: generated.source,
                         omitOwnerToken: true,
+                        cpuMs: this.#layers.config.events?.workerCpuMs,
                         // What the script compares an invocation against.
                         // Derived from the script name, so a redeploy of
                         // the same set binds the same key.
@@ -210,34 +398,74 @@ export class EventsWorkerDeployer {
             );
             return 'failed';
         }
+        if (userScope) await this.#markDeployed(script);
         return 'deployed';
     }
 
-    /**
-     * Whether this app has already deployed `EVENTS_WORKER_DEPLOYS_PER_HOUR`
-     * times this hour. A flapping set (publish, remove, republish) provisions
-     * upstream on every miss, and this is the ceiling on that loop.
-     */
-    async #tooManyDeploysThisHour(appUid: string): Promise<boolean> {
-        const redis = this.#layers.clients.redis;
-        const hour = new Date().toISOString().slice(0, 13);
-        const key = `ev:deploys:{${appUid}}:${hour}`;
-        const count = await redis.incr(key);
-        if (count === 1) await redis.expire(key, DEPLOY_THROTTLE_TTL_SECONDS);
-        return count > EVENTS_WORKER_DEPLOYS_PER_HOUR;
+    async #markedDeployed(script: string): Promise<boolean> {
+        try {
+            return !!(await this.#layers.clients.redis.get(
+                deployedMarkerKey(script),
+            ));
+        } catch (err) {
+            console.warn('[events] deployed marker unreadable', err);
+            return false;
+        }
     }
 
-    /** The app owner, as an actor the deploy can run as. */
+    async #markDeployed(script: string): Promise<void> {
+        try {
+            await this.#layers.clients.redis.set(
+                deployedMarkerKey(script),
+                '1',
+                'EX',
+                DEPLOYED_MARKER_TTL_SECONDS,
+            );
+        } catch (err) {
+            console.warn('[events] could not mark a script deployed', err);
+        }
+    }
+
+    /**
+     * Whether this scope has already deployed its hourly cap this hour. A
+     * flapping set (publish, remove, republish) provisions upstream on every
+     * miss, and this is the ceiling on that loop. An app's counter is per app;
+     * a user scope has its own, so one user cannot spend another's.
+     */
+    async #tooManyDeploysThisHour(scope: HandlerScope): Promise<boolean> {
+        const redis = this.#layers.clients.redis;
+        const hour = new Date().toISOString().slice(0, 13);
+        const userScope = isUserScope(scope);
+        const key = userScope
+            ? `ev:deploys:{${scope.appUid}}:${scope.holder}:${hour}`
+            : `ev:deploys:{${scope.appUid}}:${hour}`;
+        const count = await redis.incr(key);
+        if (count === 1) await redis.expire(key, DEPLOY_THROTTLE_TTL_SECONDS);
+        return (
+            count >
+            (userScope
+                ? EVENTS_USER_WORKER_DEPLOYS_PER_HOUR
+                : EVENTS_WORKER_DEPLOYS_PER_HOUR)
+        );
+    }
+
+    /**
+     * The user a scope's deploy runs as, as an actor: the app's owner, or the
+     * holder of a user scope.
+     */
     async #owner(
-        appUid: string,
+        scope: HandlerScope,
     ): Promise<
         | (Actor & { user: { id: number; uuid: string; username: string } })
         | null
     > {
         const { stores } = this.#layers;
-        const app = await stores.app.getByUid(appUid);
-        const ownerUserId = Number(app?.owner_user_id);
-        if (!app || !Number.isFinite(ownerUserId)) return null;
+        let ownerUserId = scope.holder;
+        if (!isUserScope(scope)) {
+            const app = await stores.app.getByUid(scope.appUid);
+            ownerUserId = Number(app?.owner_user_id);
+            if (!app || !Number.isFinite(ownerUserId)) return null;
+        }
 
         const user = await stores.user.getById(ownerUserId);
         if (!user?.id || !user.uuid || !user.username || user.suspended)
@@ -299,6 +527,8 @@ export class LocalEventsInvokeTransport {
     }
 
     async send(call: EventsInvokeCall): Promise<EventsInvokeAnswer> {
+        // Built per attempt, so a send time stamped into the body is taken
+        // after a cold deploy rather than before it.
         const request = (): Request =>
             new Request(
                 `http://${call.script}.workers.puter.localhost${EVENTS_INVOKE_PATH}`,
@@ -308,7 +538,7 @@ export class LocalEventsInvokeTransport {
                         'content-type': 'application/json',
                         'x-puter-events-key': call.key,
                     },
-                    body: call.body,
+                    body: call.render ? call.render() : call.body,
                 },
             );
 
@@ -316,12 +546,20 @@ export class LocalEventsInvokeTransport {
             const resident = await this.#dispatch(request(), call.timeoutMs);
             if (resident !== null) return resident;
 
-            const outcome = await this.#deployer.ensure(
+            const scope = await this.#deployer.scopeFor(
                 call.appUid,
-                call.script,
+                call.holder,
             );
+            if (!scope) return { status: null, error: 'deploy: no-holder' };
+            const outcome = await this.#deployer.ensure(scope, call.script, {
+                lane: call.lane,
+            });
             if (outcome !== 'deployed')
-                return { status: null, error: `deploy: ${outcome}` };
+                return {
+                    status: null,
+                    error: `deploy: ${outcome}`,
+                    ...(outcome === 'busy' ? { deployBusy: true } : {}),
+                };
 
             const retried = await this.#dispatch(request(), call.timeoutMs);
             if (retried === null)

src/backend/controllers/fs/LegacyFSController.test.ts

@@ -5111,9 +5111,8 @@ describe('LegacyFSController.updateFsentryThumbnail', () => {
 // ── GET /get-launch-apps ────────────────────────────────────────────
 //
 // `recent` is a launch-metadata producer: it returns `index_url` for
-// apps the user has opened before. The taskbar happens to launch these
-// by name (so AppDriver's hosted-backing guard applies), but the field
-// is served regardless, so the guard is applied here too.
+// apps the user has opened before. The field is served whoever reads it,
+// so AppDriver's hosted-backing guard is applied here too.
 
 describe('LegacyFSController GET /get-launch-apps', () => {
     const hostedUrl = (sub: string) => `https://${sub}.site.puter.localhost/`;

src/backend/controllers/fs/LegacyFSController.ts

@@ -401,11 +401,9 @@ export class LegacyFSController extends PuterController {
                             .filter(Boolean);
 
                     // Don't hand out an index_url whose puter-hosted backing is
-                    // gone or reclaimed. The taskbar launches recents by name (so
-                    // AppDriver's guard applies), but this list is a
-                    // launch-metadata producer like any other — a future consumer
-                    // reading index_url straight off it shouldn't inherit a stale
-                    // origin.
+                    // gone or reclaimed. This list is a launch-metadata producer
+                    // like any other — a consumer reading index_url straight off
+                    // it shouldn't inherit a stale origin.
                     let backingGoneFlags: boolean[];
                     try {
                         backingGoneFlags =
@@ -950,9 +948,7 @@ export class LegacyFSController extends PuterController {
             // Trash, and `null`/`{}` when restoring. See
             // `src/gui/src/helpers.js` → `window.move_items`.
             newMetadata: (body.new_metadata ?? undefined) as
-                | Record<string, unknown>
-                | null
-                | undefined,
+                Record<string, unknown> | null | undefined,
         });
         const overwrittenEntry = replacedByMove(overwriteTarget, moved, name);
         const oldPath = source.path;
@@ -1426,8 +1422,7 @@ export class LegacyFSController extends PuterController {
         }
 
         type SignedOrEmpty =
-            | (SignedFile & { path?: string })
-            | Record<string, never>;
+            (SignedFile & { path?: string }) | Record<string, never>;
         const result: { signatures: SignedOrEmpty[]; token?: string } = {
             signatures: [],
         };
@@ -2054,10 +2049,7 @@ export class LegacyFSController extends PuterController {
         const subjectRef = body.subject;
         const appRef = body.app;
         const mode = (getString(body, 'mode') ?? 'read') as
-            | 'see'
-            | 'list'
-            | 'read'
-            | 'write';
+            'see' | 'list' | 'read' | 'write';
         if (!subjectRef || !appRef)
             throw new HttpError(400, '`subject` and `app` are required', {
                 legacyCode: 'bad_request',

src/backend/controllers/homepage/HomepageController.test.ts

@@ -27,6 +27,7 @@ import type { Actor } from '../../core/actor.js';
 import { PuterRouter } from '../../core/http/PuterRouter.js';
 import { PuterServer } from '../../server.js';
 import { setupTestServer } from '../../testUtil.js';
+import { embedFrameAncestors, embedHostOrigin } from './HomepageController.js';
 
 // ── Test harness ────────────────────────────────────────────────────
 //
@@ -529,3 +530,46 @@ describe('HomepageController GET /sw.js', () => {
         expect(route?.options.subdomain).toBe('');
     });
 });
+
+describe('embedFrameAncestors', () => {
+    const config = {
+        origin: 'https://example.test',
+        domain: 'example.test',
+        api_base_url: 'https://backend.example.test',
+    };
+
+    it('names a sibling subdomain that embeds the browser', () => {
+        expect(
+            embedFrameAncestors(config, 'https://sheets.example.test/doc/1'),
+        ).toBe("'self' https://sheets.example.test");
+    });
+
+    it('refuses the configured API host even off the api label', () => {
+        expect(
+            embedFrameAncestors(config, 'https://backend.example.test/x'),
+        ).toBe("'self'");
+    });
+});
+
+describe('embedHostOrigin', () => {
+    const config = {
+        origin: 'https://example.test',
+        domain: 'example.test',
+        api_base_url: 'https://backend.example.test',
+        static_hosting_domain: 'site.example.test',
+    };
+
+    it.each([
+        ['https://sheets.example.test/doc/1', 'https://sheets.example.test'],
+        ['https://backend.example.test/x', null],
+        ['https://api.example.test/', null],
+        ['https://someone.site.example.test/', null],
+        ['https://a.sheets.example.test/', null],
+        ['http://sheets.example.test/', null],
+        ['https://example.test/', null],
+        ['not a url', null],
+        [undefined, null],
+    ])('%s frames as %s', (referer, expected) => {
+        expect(embedHostOrigin(config, referer)).toBe(expected);
+    });
+});

src/backend/controllers/homepage/HomepageController.ts

@@ -22,12 +22,35 @@ import path from 'node:path';
 import { PuterController } from '../types.js';
 import { toAppShellView } from '../../util/appShellView.js';
 import type { PuterRouter } from '../../core/http/PuterRouter';
+import {
+    isReservedSubdomain,
+    subdomainLabelOf,
+} from '../../core/http/middleware/hostRedirects.js';
+import type { IConfig } from '../../types';
 import type {
     PuterHomepageService,
     PageMeta,
     LaunchOptions,
+    PopupFrame,
 } from '../../services/homepage/PuterHomepageService';
 
+/**
+ * GUI popups a first-party page can show in a frame at `/embed/<action>`,
+ * instead of opening `/action/<action>` in a window, plus the upgrade and
+ * top-up dialogs, which it would otherwise open in a dashboard tab, and the
+ * email confirmation, which it otherwise can't show.
+ */
+export const FRAMED_POPUP_ACTIONS = [
+    'sign-in',
+    'show-open-file-picker',
+    'show-save-file-picker',
+    'show-directory-picker',
+    'upgrade',
+    'top-up',
+    'request-email-confirmation',
+    'attach-custom-domain',
+] as const;
+
 /** Longest description/og:description/twitter:description on `/app/<name>`. */
 export const APP_META_DESCRIPTION_MAX = 150;
 
@@ -43,9 +66,9 @@ const APP_LANDING_LIMIT = {
 };
 
 /**
- * App descriptions can run long; search snippets and social cards want a
- * short blurb. Collapses whitespace, then cuts at a word boundary with an
- * ellipsis so the result never exceeds `APP_META_DESCRIPTION_MAX`.
+ * App descriptions can run long; search snippets and social cards want a short
+ * blurb. Collapses whitespace, then cuts at a word boundary with an ellipsis so
+ * the result never exceeds `APP_META_DESCRIPTION_MAX`.
  */
 export function appMetaDescription(text: string): string {
     const clean = text.replace(/\s+/g, ' ').trim();
@@ -56,6 +79,64 @@ export function appMetaDescription(text: string): string {
     return `${cut.replace(/[\s,;:.!?…—-]+$/, '')}…`;
 }
 
+type EmbedFramingConfig = Pick<
+    IConfig,
+    | 'origin'
+    | 'domain'
+    | 'api_base_url'
+    | 'static_hosting_domain'
+    | 'static_hosting_domain_alt'
+    | 'private_app_hosting_domain'
+    | 'private_app_hosting_domain_alt'
+>;
+
+/**
+ * The origin of a first-party page that may frame an `/embed/*` page, named
+ * exactly from the request's referrer, or null. A wildcard over `*.<domain>`
+ * would also admit user-hosted sites whenever the hosting domains sit under it,
+ * so only a single label under `<domain>` qualifies, and not one this server
+ * answers itself (the API, WebDAV, SDK and native-app hosts).
+ */
+export function embedHostOrigin(
+    config: EmbedFramingConfig,
+    referer: string | undefined,
+): string | null {
+    const gui = new URL(config.origin ?? `https://${config.domain}`);
+    let parent: URL;
+    try {
+        parent = new URL(referer ?? '');
+    } catch {
+        return null;
+    }
+    const host = parent.hostname.toLowerCase();
+    const label = subdomainLabelOf(host, config.domain);
+    const hostingDomains = [
+        config.static_hosting_domain,
+        config.static_hosting_domain_alt,
+        config.private_app_hosting_domain,
+        config.private_app_hosting_domain_alt,
+    ]
+        .map((d) => (d ?? '').toLowerCase().split(':')[0])
+        .filter(Boolean);
+    const allowed =
+        parent.protocol === gui.protocol &&
+        parent.port === gui.port &&
+        label !== undefined &&
+        !isReservedSubdomain(label) &&
+        host !== new URL(config.api_base_url).hostname &&
+        !hostingDomains.some((d) => host === d || host.endsWith(`.${d}`));
+    return allowed ? parent.origin : null;
+}
+
+/** `frame-ancestors` for an `/embed/*` page: the GUI and {@link embedHostOrigin}. */
+export function embedFrameAncestors(
+    config: EmbedFramingConfig,
+    referer: string | undefined,
+): string {
+    const host = embedHostOrigin(config, referer);
+    return host ? `'self' ${host}` : "'self'";
+}
+
 /**
  * Routes that render the Puter GUI shell, plus a catch-all static fallback
  * under `<gui_assets_root>/src` for non-dist/src paths (images, fonts, lib
@@ -90,6 +171,7 @@ export class HomepageController extends PuterController {
             res: express.Response,
             metaOverrides: Partial<PageMeta> = {},
             launch: LaunchOptions = {},
+            popupFrame?: PopupFrame,
         ) => {
             const meta = { ...defaultMeta(req), ...metaOverrides };
             const actor =
@@ -98,13 +180,89 @@ export class HomepageController extends PuterController {
                         actor?: Parameters<typeof homepage.send>[0]['actor'];
                     }
                 ).actor ?? null;
-            await homepage.send({ req, res, actor }, meta, launch);
+            await homepage.send({ req, res, actor }, meta, launch, popupFrame);
         };
 
         // -- Root + path-aliased shell routes ------------------------
 
         router.get('/', {}, (req, res) => sendShell(req, res));
 
+        /**
+         * Headers shared by the `/embed/*` pages; false when the request was
+         * redirected instead. SDK bootstrap parameters must not change an
+         * embed's account or API origin, so a query string is dropped. Checked
+         * on the raw URL; `req.query` drops pairs past the parser's limit.
+         */
+        const prepareEmbed = (
+            req: express.Request,
+            res: express.Response,
+            path: string,
+        ): boolean => {
+            if (req.originalUrl.includes('?')) {
+                res.redirect(path);
+                return false;
+            }
+            res.removeHeader('X-Frame-Options');
+            res.setHeader(
+                'Content-Security-Policy',
+                `frame-ancestors ${embedFrameAncestors(this.config, req.get('referer'))}`,
+            );
+            res.setHeader('Cache-Control', 'no-store');
+            return true;
+        };
+
+        router.get('/embed/apps', {}, async (req, res) => {
+            if (!prepareEmbed(req, res, '/embed/apps')) return;
+            // Shown to visitors without a session; a signed-in embed fetches
+            // its own list, so a failure here only costs signed-out visitors.
+            const guestApps = await this.services.recommendedApps
+                .getRecommendedApps()
+                .catch((): Array<Record<string, unknown>> => []);
+            res.send(homepage.renderAppBrowserEmbed({ guestApps }));
+        });
+
+        router.get('/embed/feedback', {}, (req, res) => {
+            if (!prepareEmbed(req, res, '/embed/feedback')) return;
+            // The feedback is recorded against this origin, which
+            // frame-ancestors has just pinned to the actual framing page.
+            res.send(
+                homepage.renderFeedbackEmbed({
+                    hostOrigin: embedHostOrigin(
+                        this.config,
+                        req.get('referer'),
+                    ),
+                }),
+            );
+        });
+
+        // The GUI runs the popup's own boot, answering the framing page
+        // instead of an opener.
+        for (const action of FRAMED_POPUP_ACTIONS) {
+            const embedPath = `/embed/${action}`;
+            router.get(embedPath, {}, async (req, res) => {
+                // Routes match case-insensitively and with a trailing slash,
+                // and the shell boots the desktop for any other spelling, so
+                // only the exact one may be framed.
+                if (req.originalUrl !== embedPath) {
+                    res.redirect(embedPath);
+                    return;
+                }
+                if (!prepareEmbed(req, res, embedPath)) return;
+                await sendShell(
+                    req,
+                    res,
+                    {},
+                    {},
+                    {
+                        hostOrigin: embedHostOrigin(
+                            this.config,
+                            req.get('referer'),
+                        ),
+                    },
+                );
+            });
+        }
+
         router.get('/settings', {}, (req, res) => sendShell(req, res));
         router.get('/settings/*splat', {}, (req, res) => sendShell(req, res));
 

src/backend/controllers/oidc/OIDCController.test.ts

@@ -244,7 +244,10 @@ describe('OIDCController GET /auth/oidc/providers', () => {
         await callRoute('get', '/auth/oidc/providers', makeReq({}), res);
         // We configured a single `custom` provider; the live service
         // walks the config and returns its id.
-        expect(captured.body).toEqual({ providers: ['custom'] });
+        expect(captured.body).toEqual({
+            providers: ['custom'],
+            signupOidcOnly: false,
+        });
     });
 });
 
@@ -1617,7 +1620,7 @@ describe('OIDCController signup callback', () => {
         expect(captured.redirectUrl).toContain('action=signup');
     });
 
-    it('creates a fresh user without oidc_switched on first signup', async () => {
+    it('creates a fresh user on first signup', async () => {
         const state = oidc().signState({
             provider: 'custom',
             redirect_uri: TEST_ORIGIN + '/',
@@ -1643,11 +1646,9 @@ describe('OIDCController signup callback', () => {
         );
         expect(captured.cookies).toHaveLength(1);
         expect(captured.redirectUrl).toBe(TEST_ORIGIN + '/');
-        // Fresh creation — must NOT advertise "you've actually been signed in".
-        expect(captured.redirectUrl).not.toContain('oidc_switched=login');
     });
 
-    it('adds oidc_switched=login when signup hits an already-linked account', async () => {
+    it('signs in to an already-linked account on signup, returning as a login would', async () => {
         // Seed an account linked on (provider, sub) so the signup callback
         // resolves to `linked-sub` rather than creating a new user.
         const sub = `sub-${Math.random().toString(36).slice(2, 8)}`;
@@ -1683,7 +1684,7 @@ describe('OIDCController signup callback', () => {
             res,
         );
         expect(captured.cookies).toHaveLength(1);
-        expect(captured.redirectUrl).toContain('oidc_switched=login');
+        expect(captured.redirectUrl).toBe(TEST_ORIGIN + '/');
     });
 
     it('redirects to action=signup with auth_error when user resolution fails (unconfirmed email)', async () => {

src/backend/controllers/oidc/OIDCController.ts

@@ -396,9 +396,12 @@ export class OIDCController extends PuterController {
                 },
             },
             async (_req: Request, res: Response) => {
-                const providers =
-                    await this.services.oidc.getEnabledProviderIds();
-                res.json({ providers });
+                const [providers, policy] = await Promise.all([
+                    this.services.oidc.getEnabledProviderIds(),
+                    this.services.signup.signupPolicy(),
+                ]);
+                // The signup window drops its email form when this is set.
+                res.json({ providers, signupOidcOnly: policy.oidcOnly });
             },
         );
 
@@ -685,14 +688,7 @@ export class OIDCController extends PuterController {
                 );
             }
 
-            // If we landed on an existing account (either via the
-            // provider_sub or via email match), signal the GUI so it can
-            // render a "signed in" flow rather than "account created".
-            const extra =
-                resolved.origin === 'created'
-                    ? undefined
-                    : { oidc_switched: 'login' };
-            await this.#finishLogin(req, res, user, stateDecoded, extra);
+            await this.#finishLogin(req, res, user, stateDecoded);
         };
         router.get('/auth/oidc/callback/signup', cbOpts, signupCb);
         router.post('/auth/oidc/callback/signup', cbOpts, signupCb);
@@ -831,17 +827,14 @@ if (window.opener) {
         attempt = 0,
     ): Promise<
         | { error: string; code?: string; requestCode?: string }
-        | {
-              user: import('../../stores/user/UserStore.js').UserRow;
-              origin: 'linked-sub' | 'linked-email' | 'created';
-          }
+        | { user: import('../../stores/user/UserStore.js').UserRow }
     > {
         // 1. Existing provider/sub link.
         const linked = await this.services.oidc.findUserByProviderSub(
             provider,
             userinfo.sub,
         );
-        if (linked) return { user: linked, origin: 'linked-sub' };
+        if (linked) return { user: linked };
 
         // 2/3. Email match branch.
         const claimedEmail =
@@ -878,7 +871,7 @@ if (window.opener) {
                         error: outcome.error ?? 'Failed to link provider.',
                     };
                 }
-                return { user: byEmail, origin: 'linked-email' };
+                return { user: byEmail };
             }
         }
 
@@ -908,7 +901,7 @@ if (window.opener) {
                 requestCode: outcome.requestCode,
             };
         }
-        return { user: outcome.user, origin: 'created' };
+        return { user: outcome.user };
     }
 
     async #processCallback(
@@ -997,7 +990,6 @@ if (window.opener) {
         res: Response,
         user: UserRow,
         stateDecoded: Record<string, unknown>,
-        extraQueryParams?: Record<string, string>,
     ): Promise<void> {
         const origin = (this.config.origin ?? '').replace(/\/$/, '');
         const continuation: OidcLoginContinuation = {
@@ -1015,7 +1007,6 @@ if (window.opener) {
                 stateDecoded.msg_id == null
                     ? null
                     : String(stateDecoded.msg_id),
-            switchedToLogin: extraQueryParams?.oidc_switched === 'login',
         };
         if (user.otp_enabled) {
             const challenge = this.services.token.sign(

src/backend/controllers/oidc/OIDCController.twoFactor.http.test.ts

@@ -139,7 +139,7 @@ describe('OIDC account second-factor login', () => {
             expect(await response.json()).toMatchObject({
                 proceed: true,
                 next_step: 'complete',
-                redirectUrl: `${env.origin}/dashboard${flow === 'signup' ? '?oidc_switched=login' : ''}`,
+                redirectUrl: `${env.origin}/dashboard`,
             });
             expect(
                 response.headers

src/backend/controllers/puterai/PuterAIController.shapes.test.ts

@@ -201,6 +201,7 @@ describe('PuterAIController.openaiResponses parameter forwarding', () => {
                     context_management: [{ type: 'compaction' }],
                     prompt_cache_key: 'ck',
                     prompt_cache_retention: '24h',
+                    prompt_cache_options: { ttl: '12h', prewarm: true },
                     store: true,
                     truncation: 'auto',
                     service_tier: 'default',
@@ -226,6 +227,9 @@ describe('PuterAIController.openaiResponses parameter forwarding', () => {
             context_management: [{ type: 'compaction' }],
             prompt_cache_key: 'ck',
             prompt_cache_retention: '24h',
+            // Forwarded as sent; the provider keeps only the fields it
+            // accepts.
+            prompt_cache_options: { ttl: '12h', prewarm: true },
             // forced false regardless of the client's request.
             store: false,
             truncation: 'auto',
@@ -359,13 +363,18 @@ describe('PuterAIController.openaiResponses input normalization', () => {
                 role: 'user',
                 content: [
                     'a bare string part',
-                    { type: 'input_text', text: 'typed text' },
+                    {
+                        type: 'input_text',
+                        text: 'typed text',
+                        prompt_cache_breakpoint: { mode: 'explicit', ttl: '12h' },
+                    },
                     { type: 'output_text', text: 'echoed text' },
                     {
                         type: 'input_image',
                         detail: 'high',
                         image_url: 'https://img.test/a.png',
                         file_id: 'file_img',
+                        prompt_cache_breakpoint: { mode: 'explicit' },
                     },
                     { type: 'input_audio', input_audio: { data: 'AAA' } },
                     {
@@ -386,13 +395,18 @@ describe('PuterAIController.openaiResponses input normalization', () => {
                 role: 'user',
                 content: [
                     { type: 'text', text: 'a bare string part' },
-                    { type: 'text', text: 'typed text' },
+                    {
+                        type: 'text',
+                        text: 'typed text',
+                        prompt_cache_breakpoint: { mode: 'explicit', ttl: '12h' },
+                    },
                     { type: 'text', text: 'echoed text' },
                     {
                         type: 'image_url',
                         detail: 'high',
                         image_url: { url: 'https://img.test/a.png' },
                         file_id: 'file_img',
+                        prompt_cache_breakpoint: { mode: 'explicit' },
                     },
                     { type: 'input_audio', input_audio: { data: 'AAA' } },
                     {
@@ -639,6 +653,33 @@ describe('PuterAIController.openaiResponses output items', () => {
 // -- /openai/v1/chat/completions edges -------------------------------
 
 describe('PuterAIController.openaiChatCompletions translation edges', () => {
+    it('forwards the prompt-cache fields to the driver', async () => {
+        const completeSpy = stubChatComplete({
+            message: { role: 'assistant', content: 'ok' },
+        });
+
+        const { res } = makeRes();
+        await controller.openaiChatCompletions(
+            makeReq({
+                body: {
+                    model: 'gpt-test',
+                    messages: [{ role: 'user', content: 'hi' }],
+                    prompt_cache_key: 'ck',
+                    prompt_cache_retention: 'in_memory',
+                    prompt_cache_options: { ttl: '30m' },
+                },
+            }),
+            res,
+        );
+
+        const args = completeSpy.mock.calls[0]![0] as Record<string, unknown>;
+        expect(args).toMatchObject({
+            prompt_cache_key: 'ck',
+            prompt_cache_retention: 'in_memory',
+            prompt_cache_options: { ttl: '30m' },
+        });
+    });
+
     it('derives tool_calls from tool_use content blocks when the message has none', async () => {
         stubChatComplete({
             message: {

src/backend/controllers/puterai/PuterAIController.ts

@@ -447,6 +447,7 @@ export class PuterAIController extends PuterController {
                           body.reasoning_effort as ICompleteArguments['reasoning_effort'],
                   }
                 : {}),
+            ...promptCacheArgsFromBody(body),
             ...openaiCompatProvider(body),
             ...(body.fallback === false ? { fallback: false } : {}),
         };
@@ -842,15 +843,7 @@ export class PuterAIController extends PuterController {
                           body.compaction as ICompleteArguments['compaction'],
                   }
                 : {}),
-            ...(body.prompt_cache_key
-                ? { prompt_cache_key: String(body.prompt_cache_key) }
-                : {}),
-            ...(body.prompt_cache_retention
-                ? {
-                      prompt_cache_retention:
-                          body.prompt_cache_retention as ICompleteArguments['prompt_cache_retention'],
-                  }
-                : {}),
+            ...promptCacheArgsFromBody(body),
             // forced off regardless of what the caller sent — OpenAI
             // defaults `store` to true, which would persist state server-side
             // on OpenAI's end that this route gives no way to retrieve.
@@ -1343,6 +1336,33 @@ const openaiCompatProvider = (
     return { provider: DEFAULTS.openaiChat };
 };
 
+/**
+ * The prompt-cache fields both OpenAI-shaped routes forward as sent; the
+ * provider checks the values.
+ */
+const promptCacheArgsFromBody = (
+    body: Record<string, unknown>,
+): Pick<
+    ICompleteArguments,
+    'prompt_cache_key' | 'prompt_cache_retention' | 'prompt_cache_options'
+> => ({
+    ...(body.prompt_cache_key
+        ? { prompt_cache_key: String(body.prompt_cache_key) }
+        : {}),
+    ...(body.prompt_cache_retention
+        ? {
+              prompt_cache_retention:
+                  body.prompt_cache_retention as ICompleteArguments['prompt_cache_retention'],
+          }
+        : {}),
+    ...(body.prompt_cache_options
+        ? {
+              prompt_cache_options:
+                  body.prompt_cache_options as ICompleteArguments['prompt_cache_options'],
+          }
+        : {}),
+});
+
 const randomId = (): string => crypto.randomUUID().replace(/-/g, '');
 const generateId = (prefix: string): string => `${prefix}_${randomId()}`;
 
@@ -1590,12 +1610,24 @@ const parseJsonMaybe = (value: unknown): unknown => {
     }
 };
 
+/** An OpenAI `prompt_cache_breakpoint` marker, kept on the translated part. */
+const cacheBreakpointOf = (
+    p: Record<string, unknown>,
+): { prompt_cache_breakpoint?: unknown } =>
+    p.prompt_cache_breakpoint && typeof p.prompt_cache_breakpoint === 'object'
+        ? { prompt_cache_breakpoint: p.prompt_cache_breakpoint }
+        : {};
+
 const normalizeContentPart = (part: unknown): Record<string, unknown> => {
     if (typeof part === 'string') return { type: 'text', text: part };
     if (!part || typeof part !== 'object') return { type: 'text', text: '' };
     const p = part as Record<string, unknown>;
     if (p.type === 'input_text' || p.type === 'output_text') {
-        return { type: 'text', text: String(p.text ?? '') };
+        return {
+            type: 'text',
+            text: String(p.text ?? ''),
+            ...cacheBreakpointOf(p),
+        };
     }
     if (p.type === 'input_image') {
         return {
@@ -1603,6 +1635,7 @@ const normalizeContentPart = (part: unknown): Record<string, unknown> => {
             ...(p.detail ? { detail: p.detail } : {}),
             ...(p.image_url ? { image_url: { url: p.image_url } } : {}),
             ...(p.file_id ? { file_id: p.file_id } : {}),
+            ...cacheBreakpointOf(p),
         };
     }
     if (p.type === 'input_audio')
@@ -1614,6 +1647,7 @@ const normalizeContentPart = (part: unknown): Record<string, unknown> => {
             ...(p.file_id ? { file_id: p.file_id } : {}),
             ...(p.file_url ? { file_url: p.file_url } : {}),
             ...(p.filename ? { filename: p.filename } : {}),
+            ...cacheBreakpointOf(p),
         };
     }
     return p;

src/backend/controllers/static/StaticAssetsController.test.ts

@@ -19,8 +19,9 @@
 
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
+import type { AddressInfo } from 'node:net';
 import path from 'node:path';
-import type { Request, Response } from 'express';
+import express, { type Request, type Response } from 'express';
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
 import { PuterRouter } from '../../core/http/PuterRouter.js';
 import type { RouteDescriptor } from '../../core/http/types.js';
@@ -111,6 +112,7 @@ const callGetHandler = async (
     let captured: { filename?: string; root?: string } = {};
     const req = {} as Request;
     const res = {
+        setHeader: vi.fn(),
         sendFile: vi.fn((filename: string, opts: { root: string }) => {
             captured = { filename, root: opts.root };
         }),
@@ -238,6 +240,48 @@ describe('StaticAssetsController puterjs_root', () => {
     });
 });
 
+// ── push-sw.js caching ──────────────────────────────────────────────
+
+/** Serves the route's handler over real HTTP and returns the response. */
+const fetchThroughExpress = async (router: PuterRouter, routePath: string) => {
+    const route = findRoute(router, 'get', routePath);
+    if (!route) throw new Error(`No GET ${routePath} registered`);
+    const app = express();
+    app.get(routePath, (req, res, next) => route.handler(req, res, next));
+    const listener = app.listen(0);
+    await new Promise((resolve) => listener.once('listening', resolve));
+    try {
+        const { port } = listener.address() as AddressInfo;
+        return await fetch(`http://127.0.0.1:${port}${routePath}`);
+    } finally {
+        listener.close();
+    }
+};
+
+describe('StaticAssetsController push-sw.js', () => {
+    it.each([
+        ['client_libs_root', 'puter.js/push-sw.js'],
+        ['puterjs_root', 'push-sw.js'],
+    ] as const)(
+        'lets the CDN keep it for five minutes from %s',
+        async (configKey, file) => {
+            const root = makeTempDir();
+            mkdirSync(path.dirname(path.join(root, file)), { recursive: true });
+            writeFileSync(path.join(root, file), '/* worker */');
+            const router = buildController({ [configKey]: root });
+
+            for (const route of ['/push-sw.js', '/v2/push-sw.js']) {
+                const response = await fetchThroughExpress(router, route);
+                expect(response.status).toBe(200);
+                expect(response.headers.get('cache-control')).toBe(
+                    'public, max-age=0, s-maxage=300',
+                );
+                expect(await response.text()).toBe('/* worker */');
+            }
+        },
+    );
+});
+
 // ── gui_assets_root ─────────────────────────────────────────────────
 
 describe('StaticAssetsController gui_assets_root', () => {

src/backend/controllers/static/StaticAssetsController.ts

@@ -23,6 +23,9 @@ import path from 'node:path';
 import { PuterController } from '../types.js';
 import type { PuterRouter } from '../../core/http/PuterRouter';
 
+// Sites import push-sw.js by URL, so the CDN refetches it within five minutes.
+const PUSH_WORKER_CACHE_CONTROL = 'public, max-age=0, s-maxage=300';
+
 /**
  * Static asset routes.
  *
@@ -58,6 +61,7 @@ export class StaticAssetsController extends PuterController {
             // `/v2/push-sw.js` is the path older docs gave.
             for (const route of ['/push-sw.js', '/v2/push-sw.js']) {
                 router.get(route, { subdomain: 'js' }, (_req, res) => {
+                    res.setHeader('Cache-Control', PUSH_WORKER_CACHE_CONTROL);
                     res.sendFile('puter.js/push-sw.js', { root });
                 });
             }
@@ -108,6 +112,10 @@ export class StaticAssetsController extends PuterController {
                 });
                 for (const route of ['/push-sw.js', '/v2/push-sw.js']) {
                     router.get(route, { subdomain: 'js' }, (_req, res) => {
+                        res.setHeader(
+                            'Cache-Control',
+                            PUSH_WORKER_CACHE_CONTROL,
+                        );
                         res.sendFile('push-sw.js', { root: puterjsRoot });
                     });
                 }

src/backend/controllers/webdav/WebDAVController.upload.http.test.ts

@@ -0,0 +1,89 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import {
+    setupPuterTestEnv,
+    TEST_USER_CREDENTIALS,
+    type PuterTestEnv,
+} from '../../testUtil.js';
+
+/** A PUT body is the file, whatever content type the client labels it with. */
+describe('PUT stores the body as sent', () => {
+    let env: PuterTestEnv;
+
+    beforeAll(async () => {
+        env = await setupPuterTestEnv();
+    }, 60_000);
+
+    afterAll(async () => {
+        await env?.shutdown();
+    });
+
+    const dav = (path: string, init: RequestInit) => {
+        const port = new URL(env.apiOrigin).port;
+        const auth = Buffer.from(
+            `${TEST_USER_CREDENTIALS.username}:${TEST_USER_CREDENTIALS.password}`,
+        ).toString('base64');
+        return fetch(`http://dav.puter.localhost:${port}${encodeURI(path)}`, {
+            ...init,
+            headers: { Authorization: `Basic ${auth}`, ...init.headers },
+        });
+    };
+
+    it.each([
+        ['application/json', '{"name":"report","rows":[1,2,3]}'],
+        // Not JSON at all: the label alone must not get the body rejected.
+        ['application/json', 'not json'],
+        ['text/plain;actually=json', '{"a":1}'],
+        ['application/x-www-form-urlencoded', 'a=1&b=two'],
+        ['application/octet-stream', 'plain bytes'],
+    ])(
+        'with Content-Type %s',
+        async (contentType, content) => {
+            const path = `/${env.users.user.username}/Documents/put-${randomUUID().slice(0, 8)}.bin`;
+            const put = await dav(path, {
+                method: 'PUT',
+                headers: { 'Content-Type': contentType },
+                body: content,
+            });
+            expect(put.status).toBe(201);
+
+            const get = await dav(path, { method: 'GET' });
+            expect(get.status).toBe(200);
+            expect(await get.text()).toBe(content);
+        },
+        30_000,
+    );
+
+    it('with a form body over the form parser limit', async () => {
+        const path = `/${env.users.user.username}/Documents/put-${randomUUID().slice(0, 8)}.bin`;
+        const content = `a=${'x'.repeat(200 * 1024)}`;
+        const put = await dav(path, {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: content,
+        });
+        expect(put.status).toBe(201);
+
+        const get = await dav(path, { method: 'GET' });
+        expect(await get.text()).toBe(content);
+    }, 30_000);
+});

src/backend/core/http/middleware/authProbe.ts

@@ -224,7 +224,7 @@ const extractToken = (
         }
     }
 
-    // 5. Query string (used by e.g. QR login, asset URLs).
+    // 5. Query string (used by e.g. asset URLs).
     const queryToken = (req.query as { auth_token?: unknown } | undefined)
         ?.auth_token;
     if (typeof queryToken === 'string' && queryToken.length > 0) {

src/backend/core/http/middleware/hostRedirects.test.ts

@@ -187,9 +187,9 @@ describe('createUserSubdomainNotFound', () => {
     });
 
     it('passes through reserved subdomains (api, js, native apps, etc.)', () => {
-        // `api`, `js`, `dav`, `docs`, `developer`, `editor`, `pdf`,
+        // `api`, `js`, `dav`, `docs`, `developer`, `about`, `apps`,
         // `puter-app-icons`, etc. all pass through.
-        for (const sub of ['api', 'js', 'docs', 'editor', 'puter-app-icons']) {
+        for (const sub of ['api', 'js', 'docs', 'about', 'puter-app-icons']) {
             const { out, next } = run(
                 createUserSubdomainNotFound(config),
                 makeReq({
@@ -865,13 +865,13 @@ describe('createNativeAppStatic', () => {
 
     beforeAll(() => {
         root = mkdtempSync(nodePath.join(tmpdir(), 'native-apps-'));
-        mkdirSync(nodePath.join(root, 'editor', 'assets'), { recursive: true });
+        mkdirSync(nodePath.join(root, 'about', 'assets'), { recursive: true });
         writeFileSync(
-            nodePath.join(root, 'editor', 'index.html'),
-            '<h1>editor</h1>',
+            nodePath.join(root, 'about', 'index.html'),
+            '<h1>about</h1>',
         );
         writeFileSync(
-            nodePath.join(root, 'editor', 'assets', 'app.js'),
+            nodePath.join(root, 'about', 'assets', 'app.js'),
             'console.log(1);',
         );
         mkdirSync(nodePath.join(root, 'docs', 'dist'), { recursive: true });
@@ -893,7 +893,7 @@ describe('createNativeAppStatic', () => {
 
     it('leaves a native app name alone on a host outside our domains', async () => {
         const req = staticReq({
-            subdomains: ['com', 'example', 'editor'],
+            subdomains: ['com', 'example', 'about'],
             path: '/index.html',
         });
         (req as Request & { is_custom_domain?: boolean }).is_custom_domain =
@@ -907,7 +907,7 @@ describe('createNativeAppStatic', () => {
         const { out, next } = await runStatic(
             createNativeAppStatic(config),
             staticReq({
-                subdomains: ['localhost', 'puter', 'editor'],
+                subdomains: ['localhost', 'puter', 'about'],
                 path: '/index.html',
             }),
         );
@@ -915,17 +915,24 @@ describe('createNativeAppStatic', () => {
         expect(next).toHaveBeenCalledTimes(1);
     });
 
-    it('passes through subdomains that are not native apps', async () => {
-        const { out, next } = await runStatic(
-            withRoot(),
-            staticReq({
-                subdomains: ['localhost', 'puter', 'api'],
-                path: '/index.html',
-            }),
-        );
-        expect(out.sent).toBeUndefined();
-        expect(next).toHaveBeenCalledTimes(1);
-    });
+    // `editor`, `markus` and `pdf` are web apps on standard host routing,
+    // even with a folder of their own under the native apps root.
+    it.each(['api', 'editor', 'markus', 'pdf'])(
+        'passes %s through, as it is not a native app',
+        async (sub) => {
+            mkdirSync(nodePath.join(root, sub), { recursive: true });
+            writeFileSync(nodePath.join(root, sub, 'index.html'), sub);
+            const { out, next } = await runStatic(
+                withRoot(),
+                staticReq({
+                    subdomains: ['localhost', 'puter', sub],
+                    path: '/index.html',
+                }),
+            );
+            expect(out.sent).toBeUndefined();
+            expect(next).toHaveBeenCalledTimes(1);
+        },
+    );
 
     it('passes through when there is no subdomain at all', async () => {
         const { next } = await runStatic(
@@ -939,13 +946,13 @@ describe('createNativeAppStatic', () => {
         const { out, next } = await runStatic(
             withRoot(),
             staticReq({
-                subdomains: ['localhost', 'puter', 'editor'],
+                subdomains: ['localhost', 'puter', 'about'],
                 path: '/index.html',
             }),
         );
         expect(out.sent).toEqual({
             path: '/index.html',
-            root: nodePath.join(root, 'editor'),
+            root: nodePath.join(root, 'about'),
         });
         expect(next).not.toHaveBeenCalled();
     });
@@ -954,11 +961,11 @@ describe('createNativeAppStatic', () => {
         const { out } = await runStatic(
             withRoot(),
             staticReq({
-                subdomains: ['localhost', 'puter', 'EDITOR'],
+                subdomains: ['localhost', 'puter', 'ABOUT'],
                 path: '/index.html',
             }),
         );
-        expect(out.sent?.root).toBe(nodePath.join(root, 'editor'));
+        expect(out.sent?.root).toBe(nodePath.join(root, 'about'));
     });
 
     it('serves docs out of its dist/ subdirectory, not the app root', async () => {
@@ -979,7 +986,7 @@ describe('createNativeAppStatic', () => {
         const { out, next } = await runStatic(
             withRoot(),
             staticReq({
-                subdomains: ['localhost', 'puter', 'editor'],
+                subdomains: ['localhost', 'puter', 'about'],
                 path: '/assets',
                 originalUrl: '/assets?v=2',
             }),
@@ -995,7 +1002,7 @@ describe('createNativeAppStatic', () => {
         const { out } = await runStatic(
             withRoot(),
             staticReq({
-                subdomains: ['localhost', 'puter', 'editor'],
+                subdomains: ['localhost', 'puter', 'about'],
                 path: '/assets/',
             }),
         );
@@ -1007,7 +1014,7 @@ describe('createNativeAppStatic', () => {
         const { out, next } = await runStatic(
             withRoot(),
             staticReq({
-                subdomains: ['localhost', 'puter', 'editor'],
+                subdomains: ['localhost', 'puter', 'about'],
                 path: '/nope.html',
             }),
         );
@@ -1019,7 +1026,7 @@ describe('createNativeAppStatic', () => {
         const { next } = await runStatic(
             withRoot(),
             staticReq({
-                subdomains: ['localhost', 'puter', 'editor'],
+                subdomains: ['localhost', 'puter', 'about'],
                 path: '/index.html',
             }),
             new Error('send failed'),
@@ -1032,7 +1039,7 @@ describe('createNativeAppStatic', () => {
             runStatic(
                 withRoot(),
                 staticReq({
-                    subdomains: ['localhost', 'puter', 'editor'],
+                    subdomains: ['localhost', 'puter', 'about'],
                     path: '/../../etc/passwd',
                 }),
             ),

src/backend/core/http/middleware/hostRedirects.ts

@@ -27,15 +27,7 @@ import { HttpError, isHttpError } from '../HttpError';
 import { isLocalWorkerHost } from './localWorkerProxy';
 
 /** Native-app subdomains served via `nativeAppStatic`. */
-const NATIVE_APP_SUBDOMAINS = [
-    'about',
-    'developer',
-    'docs',
-    'editor',
-    'markus',
-    'pdf',
-    'apps',
-] as const;
+const NATIVE_APP_SUBDOMAINS = ['about', 'developer', 'docs', 'apps'] as const;
 
 /** Subset served out of a `dist/` subdirectory rather than the app root. */
 const NATIVE_APPS_WITH_DIST = new Set(['docs', 'developer']);
@@ -111,6 +103,10 @@ export const subdomainLabelOf = (
     return label && !label.includes('.') ? label : undefined;
 };
 
+/** Whether core itself answers `<name>.<domain>` (`www` redirects to the root). */
+export const isReservedSubdomain = (name: string): boolean =>
+    name === 'www' || RESERVED_SUBDOMAINS.has(name);
+
 /**
  * Record a claim on `<name>.<domain>`. Throws on a malformed or uppercase
  * label, a subdomain core already handles, or a name that is already claimed.
@@ -123,7 +119,7 @@ export const addClaimedSubdomain = (
     if (typeof name !== 'string' || !SUBDOMAIN_LABEL.test(name)) {
         throw new Error(`Invalid subdomain label: ${JSON.stringify(name)}`);
     }
-    if (name === 'www' || RESERVED_SUBDOMAINS.has(name)) {
+    if (isReservedSubdomain(name)) {
         throw new Error(`Subdomain '${name}' is reserved`);
     }
     if (claims.has(name)) {

src/backend/core/http/middleware/jsonBody.http.test.ts

@@ -0,0 +1,263 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { brotliCompressSync, deflateSync, gzipSync } from 'node:zlib';
+import express, {
+    type ErrorRequestHandler,
+    type RequestHandler,
+} from 'express';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { SLICE_BYTES } from '../../../util/slicedJson';
+import { createJsonBodyParser } from './jsonBody';
+
+const LIMIT = 4 * 1024 * 1024;
+const TEXT_AS_JSON = 'text/plain;actually=json';
+
+type Verify = NonNullable<Parameters<typeof express.json>[0]>['verify'];
+const captureRawBody: Verify = (req, _res, buf) => {
+    (req as { rawBody?: Buffer }).rawBody = buf;
+};
+
+/** An app that answers with what its parsers left on the request. */
+const listen = (parsers: RequestHandler[]): Promise<Server> => {
+    const app = express();
+    app.use(...parsers);
+    app.post('/', (req, res) => {
+        const rawBody = (req as { rawBody?: Buffer }).rawBody;
+        res.json({
+            body: req.body,
+            hasBody: req.body !== undefined,
+            rawBody: rawBody?.toString('base64'),
+        });
+    });
+    const onError: ErrorRequestHandler = (err, _req, res, _next) => {
+        res.status(err.statusCode ?? 500).json({ type: err.type });
+    };
+    app.use(onError);
+    return new Promise((resolve) => {
+        const server = app.listen(0, '127.0.0.1', () => resolve(server));
+    });
+};
+
+describe('createJsonBodyParser', () => {
+    let sliced: Server;
+    let framework: Server;
+
+    beforeAll(async () => {
+        sliced = await listen([
+            createJsonBodyParser({ limit: LIMIT, verify: captureRawBody }),
+        ]);
+        // What the server ran before: one parser per content type.
+        framework = await listen([
+            express.json({ limit: LIMIT, verify: captureRawBody }),
+            express.json({
+                limit: LIMIT,
+                type: (req) => req.headers['content-type'] === TEXT_AS_JSON,
+                verify: captureRawBody,
+            }),
+        ]);
+    });
+
+    afterAll(() => {
+        sliced?.close();
+        framework?.close();
+    });
+
+    const post = async (
+        server: Server,
+        body: string | Buffer | undefined,
+        headers: Record<string, string>,
+    ) => {
+        const { port } = server.address() as AddressInfo;
+        const response = await fetch(`http://127.0.0.1:${port}/`, {
+            method: 'POST',
+            headers,
+            body,
+        });
+        return { status: response.status, answer: await response.json() };
+    };
+
+    const large = `${JSON.stringify({
+        text: 'é😀 "quoted" \\ line\n'.repeat(SLICE_BYTES / 8),
+        list: Array.from({ length: 20_000 }, (_, i) => ({
+            i,
+            on: i % 2 === 0,
+        })),
+    }).slice(0, -1)},"__proto__":{"nested":true}}`;
+
+    it.each<[string, string | Buffer | undefined, Record<string, string>]>([
+        ['an object', '{"a":1}', { 'Content-Type': 'application/json' }],
+        ['an array', '[1,2]', { 'Content-Type': 'application/json' }],
+        [
+            'a body sent as text',
+            '{"interface":"x","auth_token":"t"}',
+            { 'Content-Type': TEXT_AS_JSON },
+        ],
+        ['a large body', large, { 'Content-Type': 'application/json' }],
+        ['a large body sent as text', large, { 'Content-Type': TEXT_AS_JSON }],
+        [
+            'a charset parameter',
+            large,
+            { 'Content-Type': 'application/json; charset=UTF-8' },
+        ],
+        [
+            'a quoted charset parameter',
+            '{"a":"é"}',
+            { 'Content-Type': 'application/json;charset="utf-8"' },
+        ],
+        [
+            'another parameter',
+            '{"a":1}',
+            { 'Content-Type': 'application/json; profile=x' },
+        ],
+        ['an empty body', '', { 'Content-Type': 'application/json' }],
+        ['no body', undefined, { 'Content-Type': 'application/json' }],
+        [
+            'a byte order mark',
+            `\ufeff${large}`,
+            { 'Content-Type': 'application/json' },
+        ],
+        [
+            'only a byte order mark',
+            '\ufeff',
+            { 'Content-Type': 'application/json' },
+        ],
+        ['only whitespace', '  \n', { 'Content-Type': 'application/json' }],
+        ['a bare string', '"text"', { 'Content-Type': 'application/json' }],
+        ['a bare number', ' 12', { 'Content-Type': 'application/json' }],
+        ['null', 'null', { 'Content-Type': 'application/json' }],
+        ['malformed JSON', '{"a":', { 'Content-Type': 'application/json' }],
+        [
+            'malformed large JSON',
+            `${large.slice(0, -1)},]`,
+            { 'Content-Type': 'application/json' },
+        ],
+        [
+            'a large bare string',
+            JSON.stringify('x'.repeat(4 * SLICE_BYTES)),
+            { 'Content-Type': 'application/json' },
+        ],
+        [
+            'invalid UTF-8',
+            Buffer.concat([
+                Buffer.from('{"a":"'),
+                Buffer.from([0xff, 0xe2, 0x82]),
+                Buffer.from('"}'),
+            ]),
+            { 'Content-Type': 'application/json' },
+        ],
+        [
+            'a body over the limit',
+            `["${'x'.repeat(LIMIT)}"]`,
+            { 'Content-Type': 'application/json' },
+        ],
+        [
+            'a gzipped body',
+            gzipSync(large),
+            { 'Content-Type': 'application/json', 'Content-Encoding': 'gzip' },
+        ],
+        [
+            'a deflated body',
+            deflateSync(large),
+            {
+                'Content-Type': 'application/json',
+                'Content-Encoding': 'deflate',
+            },
+        ],
+        [
+            'a brotli body',
+            brotliCompressSync(large),
+            { 'Content-Type': 'application/json', 'Content-Encoding': 'br' },
+        ],
+        [
+            'a body that inflates past the limit',
+            gzipSync(`["${'x'.repeat(LIMIT)}"]`),
+            { 'Content-Type': 'application/json', 'Content-Encoding': 'gzip' },
+        ],
+        [
+            'an unknown content encoding',
+            '{"a":1}',
+            { 'Content-Type': 'application/json', 'Content-Encoding': 'lzw' },
+        ],
+        ['plain text', '{"a":1}', { 'Content-Type': 'text/plain' }],
+        [
+            'text with the marker and a charset',
+            '{"a":1}',
+            { 'Content-Type': `${TEXT_AS_JSON}; charset=utf-8` },
+        ],
+        [
+            'a JSON-suffixed type',
+            '{"a":1}',
+            { 'Content-Type': 'application/vnd.api+json' },
+        ],
+        [
+            'form data',
+            'a=1',
+            { 'Content-Type': 'application/x-www-form-urlencoded' },
+        ],
+        ['no content type', '{"a":1}', { 'Content-Type': '' }],
+    ])('answers %s the way express.json does', async (_name, body, headers) => {
+        const got = await post(sliced, body, headers);
+        const want = await post(framework, body, headers);
+        expect(got).toEqual(want);
+    });
+
+    it('leaves a body in another charset unread', async () => {
+        for (const charset of ['utf-16', 'utf8', 'latin1']) {
+            const { status, answer } = await post(
+                sliced,
+                Buffer.from('{"a":1}', 'utf16le'),
+                { 'Content-Type': `application/json; charset=${charset}` },
+            );
+            expect(status).toBe(200);
+            expect(answer.hasBody).toBe(false);
+        }
+        // The last charset named is the one that counts.
+        const { answer } = await post(sliced, '{"a":1}', {
+            'Content-Type': 'application/json; charset=utf-8; charset=utf-16',
+        });
+        expect(answer.hasBody).toBe(false);
+    });
+
+    it('parses bodies that arrive together, each to its own result', async () => {
+        const bodies = Array.from({ length: 6 }, (_, n) =>
+            JSON.stringify({ n, pad: 'x'.repeat((n + 1) * SLICE_BYTES) }),
+        );
+        const answers = await Promise.all(
+            bodies.map((body) =>
+                post(sliced, body, { 'Content-Type': 'application/json' }),
+            ),
+        );
+        answers.forEach(({ status, answer }, n) => {
+            expect(status).toBe(200);
+            expect(answer.body).toEqual(JSON.parse(bodies[n]!));
+        });
+        // A failed parse hands its turn on like a finished one.
+        const mixed = await Promise.all([
+            post(sliced, `${bodies[5]!},`, {
+                'Content-Type': 'application/json',
+            }),
+            post(sliced, bodies[4], { 'Content-Type': 'application/json' }),
+            post(sliced, bodies[3], { 'Content-Type': 'application/json' }),
+        ]);
+        expect(mixed.map(({ status }) => status)).toEqual([400, 200, 200]);
+    });
+});

src/backend/core/http/middleware/jsonBody.ts

@@ -0,0 +1,127 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import express, { type Request, type RequestHandler } from 'express';
+import { parseJsonInSlices, SLICE_BYTES } from '../../../util/slicedJson';
+
+/** What puter.js labels a JSON driver call, to keep it a simple CORS request. */
+const TEXT_AS_JSON = 'text/plain;actually=json';
+
+const UTF8_CHARSET = /;\s*charset=("?)utf-8\1\s*(?:;|$)/i;
+
+/** No charset, or exactly UTF-8. Anything else is left to `express.json`. */
+const declaresUtf8 = (contentType: string): boolean => {
+    const mentions = contentType.match(/charset/gi)?.length ?? 0;
+    return mentions === 0 || (mentions === 1 && UTF8_CHARSET.test(contentType));
+};
+
+const isUtf8Json = (req: Request): boolean => {
+    const contentType = req.headers['content-type'];
+    if (contentType === TEXT_AS_JSON) return true;
+    return (
+        typeof contentType === 'string' &&
+        Boolean(req.is('application/json')) &&
+        declaresUtf8(contentType)
+    );
+};
+
+/** The error `express.json` raises, which the error handler answers with a 400. */
+const parseFailed = (message: string): Error =>
+    Object.assign(new SyntaxError(message), {
+        status: 400,
+        statusCode: 400,
+        expose: true,
+        type: 'entity.parse.failed',
+    });
+
+const waiting: Array<() => void> = [];
+let parsing = false;
+
+/**
+ * Bodies too large for one `JSON.parse` call parse one at a time, so a single
+ * tree is under construction however many arrive together.
+ */
+const parseInTurn = async (body: Buffer): Promise<unknown> => {
+    if (body.length <= SLICE_BYTES) return parseJsonInSlices(body);
+    if (parsing) await new Promise<void>((resolve) => waiting.push(resolve));
+    parsing = true;
+    try {
+        return await parseJsonInSlices(body);
+    } finally {
+        // Handing over keeps `parsing` set, so a new arrival can't cut in.
+        const next = waiting.shift();
+        if (next) next();
+        else parsing = false;
+    }
+};
+
+interface JsonBodyOptions {
+    limit: number;
+    verify?: NonNullable<Parameters<typeof express.raw>[0]>['verify'];
+}
+
+/**
+ * `express.json` for UTF-8 bodies, with the parse done in slices so a large
+ * body can't hold the event loop. Reading, limits, decompression and `verify`
+ * are the framework's; the result and the errors match `express.json`.
+ */
+export const createJsonBodyParser = ({
+    limit,
+    verify,
+}: JsonBodyOptions): RequestHandler => {
+    const read = express.raw({
+        limit,
+        verify,
+        type: (req) => isUtf8Json(req as Request),
+    });
+
+    return (req, res, next) => {
+        read(req, res, async (err?: unknown) => {
+            // Not a Buffer: the reader skipped this request.
+            if (err || !Buffer.isBuffer(req.body)) {
+                next(err);
+                return;
+            }
+            let body: Buffer = req.body;
+            req.body = undefined;
+            // The framework's decoder drops a byte order mark.
+            if (body[0] === 0xef && body[1] === 0xbb && body[2] === 0xbf) {
+                body = body.subarray(3);
+            }
+            if (body.length === 0) {
+                req.body = {};
+                next();
+                return;
+            }
+            let parsed: unknown;
+            try {
+                parsed = await parseInTurn(body);
+            } catch (e) {
+                next(parseFailed((e as Error).message));
+                return;
+            }
+            if (typeof parsed !== 'object' || parsed === null) {
+                next(parseFailed('JSON body must be an object or an array'));
+                return;
+            }
+            req.body = parsed;
+            next();
+        });
+    };
+};

src/backend/core/http/middleware/largeJsonBody.http.test.ts

@@ -0,0 +1,184 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { request, type Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { setImmediate as nextTurn } from 'node:timers/promises';
+import express, {
+    type ErrorRequestHandler,
+    type RequestHandler,
+} from 'express';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { createJsonBodyParser } from './jsonBody';
+import {
+    createLargeJsonBodyParser,
+    DEFAULT_JSON_LIMIT_BYTES,
+} from './largeJsonBody';
+
+const MiB = 1024 * 1024;
+const TOKEN = 'valid-token';
+const PAD = 'x'.repeat(DEFAULT_JSON_LIMIT_BYTES);
+
+/** Stands in for the auth probe: one token is valid, wherever it is sent. */
+const authProbe: RequestHandler = (req, _res, next) => {
+    const token =
+        (req.body as { auth_token?: string } | undefined)?.auth_token ??
+        req.headers.authorization;
+    if (!req.actor && token === TOKEN) {
+        req.actor = { user: { uuid: 'u1' } } as typeof req.actor;
+    }
+    next();
+};
+
+describe('a JSON body over the default limit', () => {
+    let server: Server;
+
+    beforeAll(async () => {
+        const app = express();
+        app.post(
+            '/call',
+            createLargeJsonBodyParser({
+                authProbe,
+                limitBytes: 128 * MiB,
+                budgetBytes: 256 * MiB,
+                perUserBytes: 128 * MiB,
+            }),
+        );
+        app.use(createJsonBodyParser({ limit: DEFAULT_JSON_LIMIT_BYTES }));
+        app.use(authProbe);
+        app.post('/call', (req, res) => {
+            const body = req.body as { auth_token?: string; pad: string };
+            res.json({
+                user: req.actor?.user.uuid ?? null,
+                token: body.auth_token ?? null,
+                padLength: body.pad.length,
+            });
+        });
+        const onError: ErrorRequestHandler = (err, _req, res, _next) => {
+            res.status(err.statusCode ?? 500).json({});
+        };
+        app.use(onError);
+        await new Promise<void>((resolve) => {
+            server = app.listen(0, '127.0.0.1', resolve);
+        });
+    });
+
+    afterAll(() => {
+        server?.close();
+    });
+
+    /** Sends `chunks` one write at a time, so the server sees them apart. */
+    const post = (chunks: string[], headers: Record<string, string> = {}) =>
+        new Promise<{ status: number; answer: Record<string, unknown> }>(
+            (resolve, reject) => {
+                const { port } = server.address() as AddressInfo;
+                const req = request(
+                    {
+                        host: '127.0.0.1',
+                        port,
+                        path: '/call',
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'text/plain;actually=json',
+                            'Content-Length': chunks.reduce(
+                                (total, chunk) =>
+                                    total + Buffer.byteLength(chunk),
+                                0,
+                            ),
+                            ...headers,
+                        },
+                    },
+                    (res) => {
+                        const parts: Buffer[] = [];
+                        res.on('data', (part: Buffer) => parts.push(part));
+                        res.on('end', () =>
+                            resolve({
+                                status: res.statusCode!,
+                                answer: JSON.parse(
+                                    Buffer.concat(parts).toString(),
+                                ),
+                            }),
+                        );
+                    },
+                );
+                req.on('error', reject);
+                void (async () => {
+                    for (const chunk of chunks) {
+                        req.write(chunk);
+                        await nextTurn();
+                    }
+                    req.end();
+                })();
+            },
+        );
+
+    it('is accepted when it opens with a valid auth_token', async () => {
+        const { status, answer } = await post([
+            `{"auth_token":"${TOKEN}","pad":"${PAD}"}`,
+        ]);
+        expect(status).toBe(200);
+        expect(answer).toEqual({
+            user: 'u1',
+            token: TOKEN,
+            padLength: PAD.length,
+        });
+    }, 60_000);
+
+    it('is accepted when the token arrives in pieces, with spacing', async () => {
+        const opening = ` {\n  "auth_token" : "${TOKEN}" ,`;
+        const { status, answer } = await post([...opening, `"pad":"${PAD}"}`]);
+        expect(status).toBe(200);
+        expect(answer.user).toBe('u1');
+    }, 60_000);
+
+    it('is accepted with a header credential, as before', async () => {
+        const { status, answer } = await post([`{"pad":"${PAD}"}`], {
+            Authorization: TOKEN,
+        });
+        expect(status).toBe(200);
+        expect(answer).toEqual({
+            user: 'u1',
+            token: null,
+            padLength: PAD.length,
+        });
+    }, 60_000);
+
+    it.each([
+        [
+            'its token comes after other fields',
+            `{"pad":"${PAD}","auth_token":"${TOKEN}"}`,
+        ],
+        ['its token is not valid', `{"auth_token":"expired","pad":"${PAD}"}`],
+        ['it has no token', `{"pad":"${PAD}"}`],
+        [
+            'a later field replaces the token it opens with',
+            `{"auth_token":"${TOKEN}","pad":"${PAD}","auth_token":"other"}`,
+        ],
+        [
+            'the token it opens with is nested',
+            `{"args":{"auth_token":"${TOKEN}"},"pad":"${PAD}"}`,
+        ],
+    ])(
+        'is refused with 413 when %s',
+        async (_name, body) => {
+            expect((await post([body])).status).toBe(413);
+        },
+        60_000,
+    );
+});

src/backend/core/http/middleware/largeJsonBody.test.ts

@@ -18,6 +18,7 @@
  */
 
 import { EventEmitter } from 'node:events';
+import { Readable } from 'node:stream';
 import type { NextFunction, Request, RequestHandler, Response } from 'express';
 import { describe, expect, it, vi } from 'vitest';
 import { isHttpError } from '../HttpError';
@@ -35,7 +36,7 @@ const makeReq = (
     user: string | null = 'u1',
     body?: unknown,
 ) =>
-    ({
+    Object.assign(Readable.from([]), {
         complete: true,
         body,
         headers: {

src/backend/core/http/middleware/largeJsonBody.ts

@@ -17,13 +17,54 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-import express, { type Request, type RequestHandler } from 'express';
+import type { Request, RequestHandler, Response } from 'express';
 import { actorUid } from '../../actor';
 import { HttpError } from '../HttpError';
+import { createJsonBodyParser } from './jsonBody';
 
 /** The global JSON parser's limit, which applies before auth. */
 export const DEFAULT_JSON_LIMIT_BYTES = 50 * 1024 * 1024;
 
+/** How much of a body is read to find a token it opens with. */
+const LEADING_TOKEN_BYTES = 8 * 1024;
+const LEADING_TOKEN =
+    /^[ \t\n\r]*\{[ \t\n\r]*"auth_token"[ \t\n\r]*:[ \t\n\r]*"([^"\\]+)"/;
+
+/**
+ * The first `bytes` of the body, put back for the parser to read. Empty when
+ * the body ends or fails before that many arrive.
+ */
+const peekBody = (req: Request, bytes: number): Promise<Buffer> =>
+    new Promise((resolve) => {
+        const settle = (head: Buffer | null) => {
+            req.off('readable', onReadable);
+            req.off('end', onGone);
+            req.off('close', onGone);
+            req.off('error', onGone);
+            if (head) req.unshift(head);
+            resolve(head ?? Buffer.alloc(0));
+        };
+        const onReadable = () => {
+            // Null until `bytes` are buffered.
+            const head = req.read(bytes) as Buffer | null;
+            if (head) settle(head);
+        };
+        const onGone = () => settle(null);
+        req.on('readable', onReadable);
+        req.on('end', onGone);
+        req.on('close', onGone);
+        req.on('error', onGone);
+    });
+
+/**
+ * The `auth_token` a JSON body opens with, which puter.js sends first so it can
+ * be read ahead of the body.
+ */
+const leadingBodyToken = async (req: Request): Promise<string | undefined> => {
+    const head = await peekBody(req, LEADING_TOKEN_BYTES);
+    return LEADING_TOKEN.exec(head.toString('latin1'))?.[1];
+};
+
 interface LargeJsonBodyOptions {
     /** The global auth probe; it skips requests that already carry an actor. */
     authProbe: RequestHandler;
@@ -38,9 +79,9 @@ interface LargeJsonBodyOptions {
 
 /**
  * Parses JSON bodies over the default limit, up to `limitBytes`, once the
- * caller's header or cookie credential resolves. Unauthenticated requests and
- * requests without a Content-Length fall through to the global parser and its
- * limit.
+ * caller's credential resolves: a header, a cookie, or an `auth_token` the body
+ * opens with. Unauthenticated requests and requests without a Content-Length
+ * fall through to the global parser and its limit.
  *
  * The parsed body lives as long as the request, so a body's bytes count against
  * both budgets until its response closes. Over the user's budget gets a 429,
@@ -53,82 +94,91 @@ export const createLargeJsonBodyParser = ({
     perUserBytes,
     accepts,
 }: LargeJsonBodyOptions): RequestHandler => {
-    const json = express.json({ limit: limitBytes });
-    const textAsJson = express.json({
-        limit: limitBytes,
-        type: (req) =>
-            req.headers['content-type'] === 'text/plain;actually=json',
-    });
+    const json = createJsonBodyParser({ limit: limitBytes });
     let inFlightBytes = 0;
     const inFlightByUser = new Map<string, number>();
 
-    return (req, res, next) => {
+    const probe = (req: Request, res: Response) =>
+        new Promise<void>((resolve) => {
+            void authProbe(req, res, () => resolve());
+        });
+
+    return async (req, res, next) => {
         const declared = Number(req.headers['content-length']);
         if (!(declared > DEFAULT_JSON_LIMIT_BYTES && declared <= limitBytes)) {
             next();
             return;
         }
-        void authProbe(req, res, () => {
-            // `res.closed`: the client left during the probe, so `close` has
-            // already fired and would never release a charge.
-            if (!req.actor || res.closed) {
-                next();
+        await probe(req, res);
+        let bodyToken: string | undefined;
+        if (!req.actor && !res.closed) {
+            bodyToken = await leadingBodyToken(req);
+            if (bodyToken) {
+                // Where the probe looks for a body token.
+                req.body = { auth_token: bodyToken };
+                await probe(req, res);
+                req.body = undefined;
+            }
+        }
+        // `res.closed`: the client left during the probe, so `close` has
+        // already fired and would never release a charge.
+        if (!req.actor || res.closed) {
+            next();
+            return;
+        }
+        const user = req.actor.user.uuid ?? actorUid(req.actor);
+        const userBytes = inFlightByUser.get(user) ?? 0;
+        if (userBytes + declared > perUserBytes) {
+            res.setHeader('Retry-After', '5');
+            next(
+                new HttpError(
+                    429,
+                    'Too many large requests in progress for this account',
+                    { legacyCode: 'too_many_requests' },
+                ),
+            );
+            return;
+        }
+        if (inFlightBytes + declared > budgetBytes) {
+            res.setHeader('Retry-After', '5');
+            next(
+                new HttpError(503, 'Too many large requests in progress', {
+                    code: 'large_body_capacity',
+                    // Load shedding, not a fault: record it, don't page.
+                    alarmSeverity: 'info',
+                }),
+            );
+            return;
+        }
+        inFlightBytes += declared;
+        inFlightByUser.set(user, userBytes + declared);
+        res.once('close', () => {
+            inFlightBytes -= declared;
+            const left = (inFlightByUser.get(user) ?? 0) - declared;
+            if (left > 0) inFlightByUser.set(user, left);
+            else inFlightByUser.delete(user);
+        });
+        json(req, res, (err?: unknown) => {
+            if (err) {
+                next(err);
                 return;
             }
-            const user = req.actor.user.uuid ?? actorUid(req.actor);
-            const userBytes = inFlightByUser.get(user) ?? 0;
-            if (userBytes + declared > perUserBytes) {
-                res.setHeader('Retry-After', '5');
+            // The caller was resolved from the token the body opens with,
+            // so the parsed body has to name the same one.
+            const tokenMoved =
+                bodyToken !== undefined &&
+                (req.body as { auth_token?: unknown } | undefined)
+                    ?.auth_token !== bodyToken;
+            if (tokenMoved || (accepts && !accepts(req))) {
+                // The same answer the default limit gives.
                 next(
-                    new HttpError(
-                        429,
-                        'Too many large requests in progress for this account',
-                        { legacyCode: 'too_many_requests' },
-                    ),
-                );
-                return;
-            }
-            if (inFlightBytes + declared > budgetBytes) {
-                res.setHeader('Retry-After', '5');
-                next(
-                    new HttpError(503, 'Too many large requests in progress', {
-                        code: 'large_body_capacity',
-                        // Load shedding, not a fault: record it, don't page.
-                        alarmSeverity: 'info',
+                    new HttpError(413, 'request entity too large', {
+                        legacyCode: 'client_bad_request',
                     }),
                 );
                 return;
             }
-            inFlightBytes += declared;
-            inFlightByUser.set(user, userBytes + declared);
-            res.once('close', () => {
-                inFlightBytes -= declared;
-                const left = (inFlightByUser.get(user) ?? 0) - declared;
-                if (left > 0) inFlightByUser.set(user, left);
-                else inFlightByUser.delete(user);
-            });
-            json(req, res, (err?: unknown) => {
-                if (err) {
-                    next(err);
-                    return;
-                }
-                textAsJson(req, res, (err?: unknown) => {
-                    if (err) {
-                        next(err);
-                        return;
-                    }
-                    if (accepts && !accepts(req)) {
-                        // The same answer the default limit gives.
-                        next(
-                            new HttpError(413, 'request entity too large', {
-                                legacyCode: 'client_bad_request',
-                            }),
-                        );
-                        return;
-                    }
-                    next();
-                });
-            });
+            next();
         });
     };
 };

src/backend/core/schedules.test.ts

@@ -0,0 +1,42 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { isHttpError } from './http/HttpError.js';
+import {
+    SCHEDULE_LIST_LIMIT_CAP,
+    SCHEDULE_PEER_PATH,
+    schedulesUnavailable,
+} from './schedules.js';
+
+describe('schedules contract', () => {
+    it('answers an absent schedules service with a 503 events_disabled', () => {
+        const err = schedulesUnavailable();
+        expect(isHttpError(err)).toBe(true);
+        expect(err.statusCode).toBe(503);
+        expect(err.legacyCode).toBe('events_disabled');
+        // Expected on a server without schedules, so it must not page.
+        expect(err.noAlarm).toBe(true);
+    });
+
+    it('keeps the list cap and the peer path the extension relies on', () => {
+        expect(SCHEDULE_LIST_LIMIT_CAP).toBe(200);
+        expect(SCHEDULE_PEER_PATH).toBe('/broadcast/events/schedules');
+    });
+});

src/backend/core/schedules.ts

@@ -0,0 +1,198 @@
+/*
+ * Copyright (C) 2024-present Puter Technologies Inc.
+ *
+ * This file is part of Puter.
+ *
+ * Puter is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+/**
+ * What core asks of schedules. Nothing here is an implementation: an extension
+ * registers `services.schedules`, and a server without one answers every
+ * schedule route and `notify({ sendAt })` with `events_disabled`. Called by
+ * extensions; keep these signatures stable.
+ */
+
+import type { EventsDeployOutcome } from '../controllers/events/workerDeploy.js';
+import type { AppMessage } from '../services/notification/appMessage.js';
+import type { SuspendedReason } from '../stores/events/DurableSubscriptionStore.js';
+import type { DurableSubscription } from '../stores/events/types.js';
+import type { PageResult } from '../util/pagination.js';
+import type { Actor } from './actor.js';
+import { HttpError } from './http/HttpError.js';
+
+/** Why a schedule ended. */
+export type ScheduleEndReason =
+    | 'removed'
+    | 'ended'
+    | 'app_deleted'
+    | 'uninstalled'
+    | 'permission_revoked'
+    | 'holder_gone'
+    | 'app_gone'
+    | 'orphaned'
+    | 'delivered'
+    | 'dropped';
+
+/** What happened to a set of subscription rows schedules own. */
+export type ScheduleSubscriptionChange =
+    | {
+          type: 'suspended';
+          reason: SuspendedReason;
+          /** For a reason that never lifts; defaults to that reason. */
+          endReason?: ScheduleEndReason;
+      }
+    | { type: 'resumed' }
+    | { type: 'ended'; endReason: ScheduleEndReason };
+
+/** A schedule that keeps running, one that runs once, or a delayed notification. */
+export type ScheduleViewKind = 'recurring' | 'once' | 'deferred';
+
+/**
+ * A schedule as its holder sees it. Times are epoch ms. `context` values are
+ * never returned, as for a persistent subscription: only its keys and a hash.
+ */
+export interface ScheduleView {
+    scheduleId: string;
+    kind: ScheduleViewKind;
+    appUid: string;
+    /** `null` once ended: the handler binding goes with the schedule. */
+    handlerName: string | null;
+    /** Set only when the handler lives in the holder's own scope. */
+    handlerScope?: 'user';
+    contextKeys: string[] | null;
+    contextHash: string | null;
+    /** Interval of an `every` schedule. */
+    every: number | null;
+    cron: string | null;
+    tz: string;
+    /** First allowed run; a one-shot's only run. */
+    startAt: number;
+    /** Last allowed run, inclusive. */
+    endsAt: number | null;
+    /** `sending` once a delayed send has started; it can't be cancelled then. */
+    state: 'active' | 'suspended' | 'sending' | 'ended';
+    suspendedReason: string | null;
+    endReason: string | null;
+    endedAt: number | null;
+    /**
+     * The slot it runs for next; `null` while suspended or sending, and once
+     * ended.
+     */
+    nextRunAt: number | null;
+    createdAt: number;
+}
+
+export interface ScheduleListRequest {
+    limit: number;
+    cursor?: string;
+    includeTotal: boolean;
+}
+
+/** The caps a holder's schedules are held to, from their plan. */
+export interface ScheduleQuota {
+    recurringPerUser: number;
+    recurringPerApp: number;
+    oneShotsPerUser: number;
+    oneShotsPerApp: number;
+    /** Worst-case runs per hour × 1000, summed over recurring rows. */
+    budgetPerUser: number;
+    budgetPerApp: number;
+}
+
+/** A caller cleared to supply `sendAt`, and when it asked for. */
+export interface DeferredSendPlan {
+    sendAt: number;
+    /** Due within 5 seconds, or past: sent now rather than stored. */
+    immediate: boolean;
+    holderUserId: number;
+    appUid: string;
+    handlerDepth: number;
+    quota: ScheduleQuota;
+}
+
+/** What a delayed app message stores until it is sent. */
+export interface DeferredAppMessage {
+    message: AppMessage;
+    /** A KV share handle naming the recipient. */
+    to?: string;
+}
+
+/**
+ * A condition on one row of another table that statements embed as `EXISTS
+ * (SELECT 1 FROM <table> WHERE <where>)`, binding `values`.
+ */
+export interface SqlGuard {
+    table: string;
+    where: string;
+    values: unknown[];
+}
+
+/** Ceiling of a schedule listing page. */
+export const SCHEDULE_LIST_LIMIT_CAP = 200;
+
+/** The signed peer route a region's schedule changes are sent to. */
+export const SCHEDULE_PEER_PATH = '/broadcast/events/schedules';
+
+export const schedulesUnavailable = (): HttpError =>
+    new HttpError(503, 'Schedules are not available on this server', {
+        legacyCode: 'events_disabled',
+        // The designed answer of a server without schedules, not a fault.
+        noAlarm: true,
+    });
+
+export interface ScheduleServiceContract {
+    /**
+     * Keep schedules in step with a change to the subscription rows they own.
+     * Never throws: the subscription change has already happened.
+     */
+    onSubscriptionsChanged(
+        rows: readonly DurableSubscription[],
+        change: ScheduleSubscriptionChange,
+    ): Promise<void>;
+    createFor(
+        actor: Actor,
+        body: Record<string, unknown>,
+    ): Promise<ScheduleView>;
+    list(
+        actor: Actor,
+        request: ScheduleListRequest,
+    ): Promise<PageResult<ScheduleView>>;
+    get(actor: Actor, scheduleId: unknown): Promise<ScheduleView>;
+    update(
+        actor: Actor,
+        scheduleId: unknown,
+        changes: unknown,
+    ): Promise<ScheduleView>;
+    remove(actor: Actor, scheduleId: unknown): Promise<void>;
+    /** `results`: each change's index outcome, in order (`null` if dropped). */
+    receivePeerChanges(
+        body: unknown,
+    ): Promise<{ applied: number; results?: Array<number | null> }>;
+    /** Checks a caller supplying `sendAt`; `events_disabled` when off. */
+    prepareSendAt(actor: Actor, sendAt: unknown): Promise<DeferredSendPlan>;
+    createDeferredAppMessage(
+        plan: DeferredSendPlan,
+        message: DeferredAppMessage,
+    ): Promise<{ scheduleId: string; sendAt: number }>;
+    /**
+     * Runs an events worker deploy under the schedules' deploy gate; `capped`
+     * for a schedule run's. A passthrough when schedules are off.
+     */
+    gateDeploy?(
+        script: string,
+        options: { capped: boolean },
+        deploy: () => Promise<EventsDeployOutcome>,
+    ): Promise<EventsDeployOutcome>;
+}

src/backend/drivers/ai-chat/ChatCompletionDriver.test.ts

@@ -355,6 +355,17 @@ describe('ChatCompletionDriver.complete auth and model resolution', () => {
         ).rejects.toMatchObject({ statusCode: 400 });
     });
 
+    it('rejects a model that is not a string with 400', async () => {
+        await expect(
+            withTestActor(() =>
+                driver.complete({
+                    messages: [{ role: 'user', content: 'hi' }],
+                    model: { id: 'gpt' },
+                } as unknown as ICompleteArguments),
+            ),
+        ).rejects.toMatchObject({ statusCode: 400 });
+    });
+
     it('routes by alias when a provider exposes one (puterId is auto-aliased on the bucket)', async () => {
         // Inject a model that carries a `puterId` so we can verify the
         // alias bucket resolves back to the canonical id. Spy on
@@ -2222,3 +2233,166 @@ describe('ChatCompletionDriver.countTokens', () => {
         ).rejects.toMatchObject({ statusCode: 400 });
     });
 });
+
+describe('ChatCompletionDriver service speed', () => {
+    it.each([
+        [{ serviceSpeed: 'ultrafast' }, 'fast', 0.028],
+        [{ speed: 'fast' }, 'fast', 0.028],
+        [{ serviceSpeed: 'standard', speed: 'fast' }, 'standard', 0.014],
+    ] as const)('uses the Claude catalog rate card for %j', async (options, speed, cents) => {
+        const sent: Record<string, unknown>[] = [];
+        vi.stubGlobal('fetch', async (input: Request | string, init?: RequestInit) => {
+            const body = input instanceof Request
+                ? await input.clone().json()
+                : JSON.parse(String(init?.body));
+            sent.push(body);
+            return new Response(JSON.stringify({
+                id: 'claude-speed-test', type: 'message', role: 'assistant',
+                model: body.model, stop_reason: 'end_turn',
+                content: [{ type: 'text', text: 'OK' }],
+                usage: { input_tokens: 10, output_tokens: 5, speed },
+            }), { headers: { 'content-type': 'application/json' } });
+        });
+        const d = new ChatCompletionDriver(
+            { providers: { claude: { apiKey: 'test-key' }, ollama: { enabled: false } } } as never,
+            server.clients, server.stores, server.services,
+        );
+        try {
+            await d.onServerStart();
+            const result = await withTestActor(() => d.complete({
+                model: 'claude-opus-5-5', provider: 'claude',
+                messages: [{ role: 'user', content: 'Hello' }],
+                fallback: false, max_tokens: 32, normalize: true, ...options,
+            }));
+            expect(sent).toHaveLength(1);
+            expect(sent[0]!.speed).toBe(speed === 'fast' ? 'fast' : undefined);
+            expect(result).toMatchObject({
+                message: { content: 'OK' }, usage: { usd_cents: cents },
+            });
+        } finally {
+            d.onServerShutdown();
+            vi.unstubAllGlobals();
+        }
+    });
+
+    it.each([
+        null, false, true, 0, 1, -1, NaN, Infinity, '', 'invalid', 'FAST',
+        'fast ', ' fast', 'ultraFast', [], ['fast'], {}, { speed: 'fast' },
+        { toString: 'fast' },
+    ])('rejects invalid speed %j before sending a request', async (serviceSpeed) => {
+        await expect(
+            withTestActor(() =>
+                driver.complete({
+                    model: 'fake',
+                    messages: [{ role: 'user', content: 'Hello' }],
+                    serviceSpeed: serviceSpeed as never,
+                }),
+            ),
+        ).rejects.toMatchObject({
+            statusCode: 400,
+            legacyCode: 'invalid_service_speed',
+        });
+    });
+
+    it.each([
+        ['openai-responses', true],
+        ['openai-responses', false],
+        ['openai-completion', false],
+    ] as const)(
+        'settles unavailable tiers at standard rates on %s with provider fallback disabled (admission rejection: %s)',
+        async (provider, rejectFast) => {
+            const sent: Record<string, unknown>[] = [];
+            vi.stubGlobal(
+                'fetch',
+                async (_input: unknown, init?: RequestInit) => {
+                    const body =
+                        _input instanceof Request
+                            ? await _input.clone().json()
+                            : JSON.parse(String(init?.body));
+                    sent.push(body);
+                    if (rejectFast && body.service_tier !== 'default') {
+                        return new Response(
+                            JSON.stringify({
+                                error: {
+                                    message: `${body.service_tier} service_tier capacity unavailable`,
+                                    type: 'invalid_request_error',
+                                },
+                            }),
+                            {
+                                status: 400,
+                                headers: { 'content-type': 'application/json' },
+                            },
+                        );
+                    }
+                    return new Response(
+                        JSON.stringify({
+                            id: 'response-test',
+                            object: 'response',
+                            model: body.model,
+                            status: 'completed',
+                            service_tier: 'default',
+                            output: [
+                                {
+                                    type: 'message',
+                                    role: 'assistant',
+                                    content: [
+                                        { type: 'output_text', text: 'OK' },
+                                    ],
+                                },
+                            ],
+                            usage: {
+                                input_tokens: 10,
+                                output_tokens: 2,
+                                input_tokens_details: { cached_tokens: 0 },
+                            },
+                        }),
+                        { headers: { 'content-type': 'application/json' } },
+                    );
+                },
+            );
+            const d = new ChatCompletionDriver(
+                {
+                    providers: {
+                        'openai-completion': { apiKey: 'test-key' },
+                        ollama: { enabled: false },
+                    },
+                } as never,
+                server.clients,
+                server.stores,
+                server.services,
+            );
+            try {
+                await d.onServerStart();
+                const result = (await withTestActor(() =>
+                    d.complete({
+                        model: 'gpt-6.1-sol',
+                        provider,
+                        messages: [{ role: 'user', content: 'Hello' }],
+                        serviceSpeed: 'ultrafast',
+                        fallback: false,
+                        max_tokens: 32,
+                        normalize: true,
+                    }),
+                )) as {
+                    message: { content: string };
+                    usageDetails: { serviceSpeed: string };
+                    usage: { usd_cents: number };
+                };
+                expect(sent.map((body) => body.service_tier)).toEqual(
+                    rejectFast
+                        ? ['ultrafast', 'priority', 'default']
+                        : ['ultrafast'],
+                );
+                expect(sent.every((body) => body.model === 'gpt-6.1-sol')).toBe(
+                    true,
+                );
+                expect(result.message.content).toBe('OK');
+                expect(result.usageDetails.serviceSpeed).toBe('standard');
+                expect(result.usage.usd_cents).toBeCloseTo(0.004, 8);
+            } finally {
+                d.onServerShutdown();
+                vi.unstubAllGlobals();
+            }
+        },
+    );
+});

src/backend/drivers/ai-chat/ChatCompletionDriver.ts

@@ -78,6 +78,12 @@ import type {
     UsageDetails,
 } from './types.js';
 import { normalize_tools_object } from './utils/FunctionCalling.js';
+import {
+    requestedServiceSpeed,
+    selectServiceSpeed,
+    lowerServiceSpeed,
+    isServiceSpeedUnavailable,
+} from './utils/serviceSpeed.js';
 import {
     messagesHavePuterPaths,
     modelSupportsModality,
@@ -674,6 +680,16 @@ export class ChatCompletionDriver extends PuterDriver {
     }
 
     async complete(args: ICompleteArguments): Promise<IChatCompleteResult> {
+        if (
+            args.serviceSpeed !== undefined &&
+            !['standard', 'fast', 'ultrafast'].includes(args.serviceSpeed)
+        ) {
+            throw new HttpError(
+                400,
+                'serviceSpeed must be standard, fast, or ultrafast',
+                { legacyCode: 'invalid_service_speed' },
+            );
+        }
         const abortSignal = Context.get('abortSignal');
         abortSignal?.throwIfAborted();
         const actor = Context.get('actor');
@@ -700,15 +716,16 @@ export class ChatCompletionDriver extends PuterDriver {
             args.model = this.#providers[intendedProvider].getDefaultModel();
         }
 
-        let model = await this.#resolveLoadedModel(
+        const initialModel = await this.#resolveLoadedModel(
             args.model,
             intendedProvider,
         );
-        if (!model) {
+        if (!initialModel) {
             throw new HttpError(400, `Model not found: ${args.model}`, {
                 legacyCode: 'bad_request',
             });
         }
+        let model: IChatModel = initialModel;
         // A pinned provider without a route for the model normally resolves
         // to another vendor; with `fallback: false` that is the one thing the
         // caller asked us not to do.
@@ -840,18 +857,6 @@ export class ChatCompletionDriver extends PuterDriver {
         // The instant the current attempt is priced at, from its hold to its
         // charge, so a rate change mid-request can't split the two.
         let pricingTime = new Date();
-        if (!useFakeProvider) {
-            ({
-                hold,
-                fundsCap,
-                costFactor,
-                promptTokenEstimate: attemptPromptTokenEstimate,
-            } = await this.#applyCreditGate(actor, model, args, {
-                promptTokenEstimate,
-                requestedMaxTokens,
-                pricingTime,
-            }));
-        }
 
         // First attempt
         const provider = this.#providers[model.provider!];
@@ -899,24 +904,132 @@ export class ChatCompletionDriver extends PuterDriver {
             return attempt;
         };
 
+        let variantSpeed: ICompleteArguments['serviceSpeed'];
+        let creditGateError: unknown;
         const runAttempt = async (
             attemptProvider: IChatProvider,
-            attemptModel: IChatModel,
+            baseModel: IChatModel,
         ) => {
-            if (!useFakeProvider) {
-                await this.#resolvePuterPaths(attemptProvider, args, actor);
-            }
-            // Last point where a caller who left costs nothing.
-            abortSignal?.throwIfAborted();
-            return attemptProvider.complete(
-                {
-                    ...args,
+            let requestedSpeed = requestedServiceSpeed(
+                args,
+                baseModel.provider,
+            );
+            const offers =
+                requestedSpeed !== undefined && requestedSpeed !== 'standard'
+                    ? ((await attemptProvider.serviceSpeedModels?.(
+                          baseModel,
+                      )) ?? {})
+                    : {};
+            for (;;) {
+                const selection = selectServiceSpeed(
+                    baseModel,
+                    { ...args, serviceSpeed: requestedSpeed },
+                    (id) => {
+                        const variant = this.#resolveModel(
+                            id,
+                            baseModel.provider!,
+                        );
+                        return variant &&
+                            variant.provider === baseModel.provider
+                            ? variant
+                            : undefined;
+                    },
+                    offers,
+                );
+                const attemptModel = selection.model;
+                const requestArgs = {
+                    ...selection.args,
                     model: attemptModel.id,
                     provider: attemptModel.provider,
-                },
-                this.#catalogEntries.get(attemptModel),
-                pricingTime,
-            );
+                };
+                const catalogModel = this.#resolveModel(
+                    attemptModel.id,
+                    attemptModel.provider!,
+                );
+                const rawModel = this.#catalogEntries.get(
+                    catalogModel ?? baseModel,
+                );
+                const snapshot = rawModel
+                    ? {
+                          ...rawModel,
+                          costs: attemptModel.costs,
+                          pricingOverrides: attemptModel.pricingOverrides,
+                          serviceSpeedPricing: attemptModel.serviceSpeedPricing,
+                      }
+                    : attemptModel;
+                if (!useFakeProvider) {
+                    try {
+                        ({
+                            hold,
+                            fundsCap,
+                            costFactor,
+                            promptTokenEstimate: attemptPromptTokenEstimate,
+                        } = await this.#applyCreditGate(
+                            actor,
+                            attemptModel,
+                            requestArgs,
+                            {
+                                promptTokenEstimate,
+                                requestedMaxTokens,
+                                pricingTime,
+                            },
+                        ));
+                    } catch (error) {
+                        creditGateError = error;
+                        throw error;
+                    }
+                    await this.#resolvePuterPaths(
+                        attemptProvider,
+                        requestArgs,
+                        actor,
+                    );
+                }
+                abortSignal?.throwIfAborted();
+                try {
+                    const result = await attemptProvider.complete(
+                        requestArgs,
+                        snapshot,
+                        pricingTime,
+                    );
+                    model = attemptModel;
+                    variantSpeed =
+                        attemptModel.id !== baseModel.id
+                            ? selection.speed
+                            : undefined;
+                    if (
+                        args.serviceSpeed !== undefined &&
+                        'message' in result
+                    ) {
+                        const messageResult = result as IChatMessageResult;
+                        const details =
+                            messageResult.usageDetails ??
+                            usageDetailsFromUsage(messageResult.usage, model);
+                        messageResult.usageDetails = {
+                            ...details,
+                            serviceSpeed:
+                                variantSpeed ??
+                                details?.serviceSpeed ??
+                                details?.speed ??
+                                'standard',
+                        };
+                    }
+                    return result;
+                } catch (error) {
+                    await hold.release();
+                    hold = NO_CREDIT_HOLD;
+                    if (
+                        args.serviceSpeed === undefined ||
+                        selection.speed === 'standard' ||
+                        !isServiceSpeedUnavailable(
+                            error,
+                            attemptModel.id !== baseModel.id,
+                        )
+                    )
+                        throw error;
+                    requestedSpeed = lowerServiceSpeed(selection.speed);
+                    pricingTime = new Date();
+                }
+            }
         };
 
         try {
@@ -984,29 +1097,17 @@ export class ChatCompletionDriver extends PuterDriver {
                 // The previous attempt released its hold when it failed, so
                 // this one starts from nothing held.
                 pricingTime = new Date();
-                if (!useFakeProvider) {
-                    ({
-                        hold,
-                        fundsCap,
-                        costFactor,
-                        promptTokenEstimate: attemptPromptTokenEstimate,
-                    } = await this.#applyCreditGate(actor, fallback, args, {
-                        promptTokenEstimate,
-                        requestedMaxTokens,
-                        pricingTime,
-                    }));
-                }
 
                 tried.add(routeId(fallback.provider!, fallback.id));
 
                 try {
                     res = await runAttempt(fbProvider, fallback);
-                    model = fallback;
                     lastError = null;
                     console.warn(
                         `[ai-chat] fallback served (${completionId}, ${first.provider}:${first.model} -> ${fallback.provider}:${fallback.id}, first ${first.status ?? 'none'}${first.upstreamType ? `/${first.upstreamType}` : ''})`,
                     );
                 } catch (fbErr) {
+                    if (fbErr === creditGateError) throw fbErr;
                     await hold.release();
                     hold = NO_CREDIT_HOLD;
                     abortSignal?.throwIfAborted();
@@ -1162,6 +1263,20 @@ export class ChatCompletionDriver extends PuterDriver {
                         usageDetailsFromUsage(usage, model),
                     );
                 }
+                if (
+                    args.serviceSpeed !== undefined &&
+                    chatStream.usageDetails
+                ) {
+                    const details = chatStream.usageDetails;
+                    chatStream.setUsageDetails({
+                        ...details,
+                        serviceSpeed:
+                            variantSpeed ??
+                            details.serviceSpeed ??
+                            details.speed ??
+                            'standard',
+                    });
+                }
                 withClaudeThinkingTokens(
                     enrichedUsage,
                     model,
@@ -1474,12 +1589,7 @@ export class ChatCompletionDriver extends PuterDriver {
         const metering = this.services.metering;
         const { requestedMaxTokens, pricingTime } = estimates;
         let { promptTokenEstimate } = estimates;
-        // A provider can name its own cost keys for this request (Claude's
-        // fast-mode rate card), cap its output, and size an extra reservation
-        // the per-token math can't see (a web-search/advisor tool that could
-        // run several times before the model answers) — the same clamps it
-        // applies when building the request, so the hold and the request
-        // agree.
+        // Providers reserve tool calls using the same caps they send upstream.
         const pricing =
             this.#providers[model.provider!]?.requestPricing?.(args, model, {
                 promptTokenEstimate,
@@ -2019,7 +2129,9 @@ export class ChatCompletionDriver extends PuterDriver {
     }
 
     #resolveModel(modelId: string, provider?: string): IChatModel | null {
-        const models = this.#modelIdMap[normalizeModelKey(modelId ?? '')];
+        // `model` comes straight from the caller and may not be a string.
+        if (typeof modelId !== 'string') return null;
+        const models = this.#modelIdMap[normalizeModelKey(modelId)];
         if (!models || models.length === 0) return null;
         // An explicitly requested provider is honoured even if its route is
         // marked — the caller asked for that one, not for the cheapest hop.

src/backend/drivers/ai-chat/providers/OpenAICompatProvider.ts

@@ -41,6 +41,7 @@ import {
     meterChatUsage,
     type MeterChatUsageOptions,
 } from '../utils/meterChatUsage.js';
+import { servedServiceSpeed } from '../utils/serviceSpeed.js';
 import { catalogPrice, costKeys } from '../utils/pricing.js';
 import { normalizeModelKey } from '../utils/modelRouting.js';
 import * as OpenAIUtil from '../utils/OpenAIUtil.js';
@@ -232,6 +233,8 @@ export class OpenAICompatProvider implements IChatProvider {
                   )
                 : {}),
         };
+        if (args.serviceSpeed !== undefined && args.service_tier !== undefined)
+            shared.service_tier = args.service_tier;
         const params = this.vendorParams(shared, args, model, actor);
 
         let pricingTime = attemptPricingTime ?? new Date();
@@ -271,15 +274,29 @@ export class OpenAICompatProvider implements IChatProvider {
                     source,
                     model,
                 );
-                if (usageDetails) source.setUsageDetails?.(usageDetails);
+                const serviceSpeed = servedServiceSpeed(source);
+                if (usageDetails)
+                    source.setUsageDetails?.({
+                        ...usageDetails,
+                        ...(args.serviceSpeed !== undefined
+                            ? { serviceSpeed }
+                            : {}),
+                    });
                 const metered = meterChatUsage(
                     this.#metering,
                     actor,
                     this.meteringModelKey(model.id),
                     model,
                     usage,
-                    { ...meterOptions, pricingTime },
+                    { ...meterOptions, pricingTime, serviceSpeed },
                 );
+                if (args.serviceSpeed !== undefined && !usageDetails) {
+                    const details = OpenAIUtil.usageDetailsFromTrackedUsage(
+                        metered.usage,
+                    );
+                    if (details)
+                        source.setUsageDetails?.({ ...details, serviceSpeed });
+                }
                 source.setUsageCosts(metered.costs);
                 return this.reportedUsage(metered.usage);
             },

src/backend/drivers/ai-chat/providers/alibaba/catalog.ts

@@ -174,6 +174,9 @@ export const mapAlibabaCatalogModel = (
             : undefined;
     return {
         ...existing,
+        serviceSpeedVariants: {
+            fast: id === 'glm-5.2' ? 'glm-5.2-fast-preview' : `${id}-prime`,
+        },
         id,
         puterId,
         name: raw.name ?? existing?.name ?? id,

src/backend/drivers/ai-chat/providers/alibaba/models.ts

@@ -37,6 +37,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen-max-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 160,
@@ -60,6 +61,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen-plus-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -81,6 +83,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.5-plus-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -102,6 +105,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.6-plus-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 50,
@@ -123,6 +127,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.6-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 19,
@@ -143,6 +148,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.7-plus-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 50,
@@ -164,6 +170,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.7-max-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 250,
@@ -188,6 +195,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.8-max-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200,
@@ -210,6 +218,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.8-max-0902-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200,
@@ -234,6 +243,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 5,
@@ -257,6 +267,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3-coder-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30,
@@ -282,6 +293,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.5-397b-a17b-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 60,
@@ -305,6 +317,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.5-122b-a10b-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -328,6 +341,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.5-35b-a3b-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 25,
@@ -351,6 +365,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.5-27b-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30,
@@ -376,6 +391,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.6-35b-a3b-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 24.8,
@@ -399,6 +415,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.6-27b-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 60,
@@ -422,6 +439,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3-vl-plus-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 20,
@@ -447,6 +465,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3-omni-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 43,
@@ -469,6 +488,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen-mt-plus-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 246,
@@ -491,6 +511,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen-plus-2025-01-25-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -511,6 +532,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen-plus-2025-04-28-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -531,6 +553,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen-plus-2025-07-14-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -553,6 +576,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen-plus-2025-12-01-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -574,6 +598,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.7-max-2026-05-20-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 250,
@@ -594,6 +619,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.7-max-2026-06-08-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 250,
@@ -614,6 +640,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.7-max-2026-05-17-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 250,
@@ -635,6 +662,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.7-max-preview-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 250,
@@ -657,6 +685,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.5-plus-2026-02-15-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -678,6 +707,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.5-plus-2026-04-20-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -700,6 +730,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.5-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 10,
@@ -722,6 +753,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.7-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 3,
@@ -743,6 +775,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.8-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 15,
@@ -765,6 +798,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.8-27b-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 50,
@@ -785,6 +819,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.8-2.4t-a95b-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200,
@@ -809,6 +844,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.5-omni-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -832,6 +868,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.5-omni-plus-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 140,
@@ -855,6 +892,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen3.8-omni-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 15,
@@ -877,6 +915,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen-mt-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 16,
@@ -897,6 +936,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'qwen-mt-lite-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 12,
@@ -919,6 +959,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'glm-5.1-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 140,
@@ -938,6 +979,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'glm-5.2-fast-preview' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 140,
@@ -958,6 +1000,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'glm-5.2-fast-preview-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 280,
@@ -981,6 +1024,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'deepseek-v4-flash-0731-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 44,
@@ -1003,6 +1047,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'deepseek-v4.1-flash-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30,
@@ -1023,6 +1068,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'deepseek-v4-pro-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 240,
@@ -1045,6 +1091,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'deepseek-v4-pro-0813-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 132,
@@ -1065,6 +1112,7 @@ export const ALIBABA_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'kimi-k2.7-code-prime' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 95,

src/backend/drivers/ai-chat/providers/azure/AzureChatProvider.ts

@@ -20,6 +20,10 @@
 import { HttpError } from '@heyputer/backend/src/core/http/HttpError.js';
 import { OpenAI } from 'openai';
 import { ChatCompletionCreateParams } from 'openai/resources/index.js';
+import {
+    serviceSpeedBillingModel,
+    servedServiceSpeed,
+} from '../../utils/serviceSpeed.js';
 import { Context } from '../../../../core/context.js';
 import type { FSService } from '../../../../services/fs/FSService.js';
 import type { MeteringService } from '../../../../services/metering/MeteringService.js';
@@ -153,6 +157,7 @@ export class AzureChatProvider implements IChatProvider {
 
     async complete(
         params: ICompleteArguments,
+        resolved?: IChatModel,
     ): ReturnType<IChatProvider['complete']> {
         const {
             max_tokens,
@@ -180,7 +185,9 @@ export class AzureChatProvider implements IChatProvider {
                     { legacyCode: 'bad_request' },
                 );
             }
-            return await this.#responsesProvider.complete(params);
+            return await (resolved
+                ? this.#responsesProvider.complete(params, resolved)
+                : this.#responsesProvider.complete(params));
         }
         // Inline compaction is a Responses-API feature; chat.completions can't
         // express `context_management` or a `compaction` content block.
@@ -194,7 +201,9 @@ export class AzureChatProvider implements IChatProvider {
                     { legacyCode: 'bad_request' },
                 );
             }
-            return await this.#responsesProvider.complete(params);
+            return await (resolved
+                ? this.#responsesProvider.complete(params, resolved)
+                : this.#responsesProvider.complete(params));
         }
         // Validate messages
         if (!Array.isArray(messages)) {
@@ -207,9 +216,11 @@ export class AzureChatProvider implements IChatProvider {
         model = model ?? this.#defaultModel;
 
         const modelUsed =
-            this.models().find((m) =>
+            resolved ??
+            (this.models().find((m) =>
                 [m.id, ...(m.aliases || [])].includes(model),
-            ) || this.models().find((m) => m.id === this.getDefaultModel())!;
+            ) ||
+                this.models().find((m) => m.id === this.getDefaultModel())!);
 
         // messages.unshift({
         //     role: 'system',
@@ -279,6 +290,9 @@ export class AzureChatProvider implements IChatProvider {
                   }),
             messages: messages,
             model: modelUsed.id,
+            ...(params.service_tier !== undefined
+                ? { service_tier: params.service_tier }
+                : {}),
             ...(mappedTools?.length ? { tools: mappedTools } : {}),
             ...(max_tokens !== undefined
                 ? { max_completion_tokens: max_tokens }
@@ -315,7 +329,12 @@ export class AzureChatProvider implements IChatProvider {
         );
 
         return OpenAiUtil.handle_completion_output({
-            usage_calculator: ({ usage }) => {
+            usage_calculator: ({
+                service_tier,
+                usage,
+                setUsageCosts,
+                setUsageDetails,
+            }) => {
                 const cachedTokens =
                     usage.prompt_tokens_details?.cached_tokens ?? 0;
                 const trackedUsage = {
@@ -335,9 +354,20 @@ export class AzureChatProvider implements IChatProvider {
 
                 const costsOverrideFromModel = buildCostsOverride(
                     trackedUsage,
-                    modelUsed,
+                    serviceSpeedBillingModel(
+                        modelUsed,
+                        servedServiceSpeed({ service_tier }),
+                    ),
                 );
 
+                setUsageCosts(costsOverrideFromModel);
+                if (params.serviceSpeed !== undefined)
+                    setUsageDetails({
+                        ...OpenAiUtil.usageDetailsFromTrackedUsage(
+                            trackedUsage,
+                        )!,
+                        serviceSpeed: servedServiceSpeed({ service_tier }),
+                    });
                 this.#meteringService.utilRecordUsageObject(
                     trackedUsage,
                     actor!,

src/backend/drivers/ai-chat/providers/azure/AzureResponsesProvider.test.ts

@@ -449,6 +449,22 @@ describe('AzureResponsesProvider.complete request shape', () => {
         expect(args.service_tier).toBe('default');
     });
 
+    it('sends the wire spelling of the in-memory cache retention', async () => {
+        const provider = makeProvider();
+        responsesCreateMock.mockResolvedValueOnce(okResponse);
+
+        await withTestActor(() =>
+            provider.complete({
+                model: 'gpt-5.3-codex',
+                messages: [{ role: 'user', content: 'hi' }],
+                prompt_cache_retention: 'in-memory',
+            } as never),
+        );
+
+        const [args] = responsesCreateMock.mock.calls[0]!;
+        expect(args.prompt_cache_retention).toBe('in_memory');
+    });
+
     it.each([
         ['previous_response_id', 'resp_1'],
         ['conversation', 'conv_1'],

src/backend/drivers/ai-chat/providers/azure/AzureResponsesProvider.ts

@@ -19,6 +19,10 @@
 
 import { OpenAI } from 'openai';
 import { ResponseCreateParams } from 'openai/resources/responses/responses.mjs';
+import {
+    serviceSpeedBillingModel,
+    servedServiceSpeed,
+} from '../../utils/serviceSpeed.js';
 import { Context } from '../../../../core/context.js';
 import type { FSService } from '../../../../services/fs/FSService.js';
 import type { MeteringService } from '../../../../services/metering/MeteringService.js';
@@ -35,6 +39,7 @@ import * as OpenAiUtil from '../../utils/OpenAIUtil.js';
 import {
     clampReasoningEffort,
     openAICompatParams,
+    promptCacheRetentionToWire,
     rejectStatefulResponsesFields,
 } from '../../utils/openaiParams.js';
 import { buildCostsOverride } from '../../utils/pricing.js';
@@ -151,37 +156,41 @@ export class AzureResponsesProvider implements IChatProvider {
             : {};
     }
 
-    async complete({
-        messages,
-        model,
-        max_tokens,
-        moderation,
-        tools,
-        tool_choice,
-        parallel_tool_calls,
-        include,
-        conversation,
-        compaction,
-        context_management,
-        previous_response_id,
-        instructions,
-        metadata,
-        prompt,
-        prompt_cache_key,
-        prompt_cache_retention,
-        store,
-        top_p,
-        truncation,
-        background,
-        service_tier,
-        verbosity,
-        stream,
-        reasoning,
-        reasoning_effort,
-        temperature,
-        text,
-        outputFormat,
-    }: ICompleteArguments): ReturnType<IChatProvider['complete']> {
+    async complete(
+        {
+            messages,
+            model,
+            max_tokens,
+            moderation,
+            tools,
+            tool_choice,
+            parallel_tool_calls,
+            include,
+            conversation,
+            compaction,
+            context_management,
+            previous_response_id,
+            instructions,
+            metadata,
+            prompt,
+            prompt_cache_key,
+            prompt_cache_retention,
+            store,
+            top_p,
+            truncation,
+            background,
+            service_tier,
+            serviceSpeed: requestedServiceSpeed,
+            verbosity,
+            stream,
+            reasoning,
+            reasoning_effort,
+            temperature,
+            text,
+            outputFormat,
+        }: ICompleteArguments,
+        resolved?: IChatModel,
+    ): ReturnType<IChatProvider['complete']> {
         // Validate messages
         if (!Array.isArray(messages)) {
             throw new HttpError(400, '`messages` must be an array', {
@@ -199,16 +208,20 @@ export class AzureResponsesProvider implements IChatProvider {
         model = model ?? this.#defaultModel;
 
         const modelUsed =
-            this.models({ no_restrictions: true }).find((m) =>
+            resolved ??
+            (this.models({ no_restrictions: true }).find((m) =>
                 [m.id, ...(m.aliases || [])].includes(model),
             ) ||
-            this.models({ no_restrictions: true }).find(
-                (m) => m.id === this.getDefaultModel(),
-            )!;
+                this.models({ no_restrictions: true }).find(
+                    (m) => m.id === this.getDefaultModel(),
+                )!);
 
         const userIdentifier = upstreamUserIdentifier(actor);
         // Cache key defaults to the actor identifier; see upstreamUserIdentifier.
         const cacheKey = prompt_cache_key ?? userIdentifier;
+        const cacheRetention = promptCacheRetentionToWire(
+            prompt_cache_retention,
+        );
 
         // Resolve any `puter_path` content parts into inline base64 data URLs
         // before the Responses API sees them.
@@ -307,8 +320,8 @@ export class AzureResponsesProvider implements IChatProvider {
             ...(instructions !== undefined ? { instructions } : {}),
             ...(metadata !== undefined ? { metadata } : {}),
             ...(cacheKey !== undefined ? { prompt_cache_key: cacheKey } : {}),
-            ...(prompt_cache_retention !== undefined
-                ? { prompt_cache_retention }
+            ...(cacheRetention !== undefined
+                ? { prompt_cache_retention: cacheRetention }
                 : {}),
             ...(store !== undefined ? { store } : {}),
             ...(max_tokens !== undefined
@@ -331,9 +344,11 @@ export class AzureResponsesProvider implements IChatProvider {
         return OpenAiUtil.handle_completion_output_responses_api({
             usage_calculator: ({
                 usage,
+                service_tier,
                 webSearchCalls,
                 tool_usage,
                 setUsageCosts,
+                setUsageDetails,
             }) => {
                 const numWebSearches: number =
                     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -359,7 +374,10 @@ export class AzureResponsesProvider implements IChatProvider {
 
                 const costsOverrideFromModel = buildCostsOverride(
                     trackedUsage,
-                    modelUsed,
+                    serviceSpeedBillingModel(
+                        modelUsed,
+                        servedServiceSpeed({ service_tier }),
+                    ),
                 );
                 if (numWebSearches) {
                     costsOverrideFromModel.web_search_calls =
@@ -370,6 +388,14 @@ export class AzureResponsesProvider implements IChatProvider {
                     });
                 }
 
+                setUsageCosts?.(costsOverrideFromModel);
+                if (requestedServiceSpeed !== undefined)
+                    setUsageDetails?.({
+                        ...OpenAiUtil.usageDetailsFromTrackedUsage(
+                            trackedUsage,
+                        )!,
+                        serviceSpeed: servedServiceSpeed({ service_tier }),
+                    });
                 this.#meteringService.utilRecordUsageObject(
                     trackedUsage,
                     actor,

src/backend/drivers/ai-chat/providers/azure/models.test.ts

@@ -40,7 +40,11 @@ const STANDALONE = [
 ];
 
 // Fields an Azure deployment genuinely differs from its source on, by puterId.
-const OVERRIDES: Record<string, string[]> = {};
+const OVERRIDES: Record<string, string[]> = {
+    'azure:x-ai/grok-4.3': ['serviceSpeedRates'],
+    'azure:x-ai/grok-4-20-non-reasoning': ['serviceSpeedRates'],
+    'azure:x-ai/grok-4-20-reasoning': ['serviceSpeedRates'],
+};
 
 const IDENTITY = ['id', 'puterId', 'aliases'];
 
@@ -65,6 +69,18 @@ const mirrored = AZURE_MODELS.filter(
 ).map((m) => [m.puterId!, m] as const);
 
 describe('AZURE_MODELS mirroring', () => {
+    it('inherits OpenAI fast rates without enabling direct-only speed tiers', () => {
+        for (const model of AZURE_MODELS) {
+            expect(model.serviceSpeedRates?.ultrafast).toBeUndefined();
+            if (model.puterId?.startsWith('azure:x-ai/')) {
+                expect(model.serviceSpeedRates?.fast).toBeUndefined();
+            }
+        }
+        const azure = AZURE_MODELS.find((model) => model.id === 'gpt-5.4')!;
+        expect(azure.serviceSpeedRates).toEqual({
+            fast: sourceOf(azure)!.serviceSpeedRates!.fast,
+        });
+    });
     it('has a direct-provider source for every entry not listed as standalone', () => {
         const orphans = mirrored
             .filter(([, m]) => !sourceOf(m))

src/backend/drivers/ai-chat/providers/azure/models.ts

@@ -22,10 +22,8 @@ import { OPEN_AI_MODELS } from '../openai/models.js';
 import { XAI_MODELS } from '../xai/models.js';
 
 /**
- * An Azure deployment of a model we also serve direct. Every field but the
- * identity comes from the source entry, so prices, long-context tiers and
- * limits can't drift from it. `name` is the vendor-qualified name both catalogs
- * share (`openai/gpt-5.4`); extra fields override the source.
+ * Azure shares its source model's list prices, context tiers, and limits.
+ * Identity and available service speeds belong to the deployment.
  */
 const mirror = (
     source: readonly IChatModel[],
@@ -41,6 +39,11 @@ const mirror = (
         puterId: `azure:${name}`,
         id: azure.id,
         ...shared,
+        serviceSpeedRates:
+            source === OPEN_AI_MODELS &&
+            shared.serviceSpeedRates?.fast !== undefined
+                ? { fast: shared.serviceSpeedRates.fast }
+                : undefined,
         aliases: [name],
         ...azure,
     };
@@ -127,6 +130,13 @@ export const AZURE_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 250,
+                cached_tokens: 25,
+                completion_tokens: 2000,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 125,
@@ -171,6 +181,13 @@ export const AZURE_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 45,
+                cached_tokens: 4.5,
+                completion_tokens: 360,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 25,

src/backend/drivers/ai-chat/providers/claude/ClaudeProvider.integration.test.ts

@@ -147,6 +147,22 @@ describe.skipIf(skipUnlessEnv(ENV_VAR))('ClaudeProvider (integration)', () => {
         },
     );
 
+    it('returns a completion from claude-fable-5-2', { timeout: INTEGRATION_TEST_TIMEOUT_MS }, async () => {
+        const provider = buildProvider();
+        const result = await withTestActor(() =>
+            provider.complete({
+                model: 'claude-fable-5-2',
+                messages: [{ role: 'user', content: 'Reply with OK.' }],
+                reasoning_effort: 'low',
+                max_tokens: 128,
+            }),
+        );
+        const content = (result as {
+            message: { content: Array<{ type: string; text?: string }> };
+        }).message.content;
+        expect(content.find((block) => block.type === 'text')?.text?.length).toBeGreaterThan(0);
+    });
+
     // (a) Claude Code-shaped system blocks, attribution header first — the
     // pipeline must never merge or reorder system blocks: the header is
     // only recognized by Anthropic when it is the sole content of an

src/backend/drivers/ai-chat/providers/claude/ClaudeProvider.test.ts

@@ -1173,6 +1173,7 @@ describe('ClaudeProvider.complete request shape', () => {
     });
 
     it.each([
+        'claude-fable-5-2',
         'claude-fable-5-1',
         'claude-haiku-5-5',
         'claude-opus-5-5',
@@ -1198,6 +1199,7 @@ describe('ClaudeProvider.complete request shape', () => {
     );
 
     it.each([
+        'claude-fable-5-2',
         'claude-fable-5-1',
         'claude-haiku-5-5',
         'claude-opus-5-5',
@@ -1303,6 +1305,73 @@ describe('ClaudeProvider model resolution', () => {
         );
     });
 
+    it.each([
+        'claude-fable-5-2',
+        'claude-fable-5-2-latest',
+        'claude-fable-5.2',
+        'anthropic/claude-fable-5-2',
+    ])(
+        'routes %s to Fable 5.2 with published rates',
+        async (model) => {
+            const { provider } = makeProvider();
+            messagesCreateMock.mockResolvedValueOnce({
+                content: [{ type: 'text', text: 'ok' }],
+                usage: {
+                    input_tokens: 100,
+                    output_tokens: 50,
+                    cache_read_input_tokens: 1000,
+                    cache_creation_input_tokens: 200,
+                    cache_creation: {
+                        ephemeral_5m_input_tokens: 150,
+                        ephemeral_1h_input_tokens: 50,
+                    },
+                },
+            });
+
+            await withTestActor(() =>
+                provider.complete({
+                    model,
+                    messages: [{ role: 'user', content: 'hi' }],
+                }),
+            );
+
+            expect(messagesCreateMock.mock.calls[0]![0].model).toBe(
+                'claude-fable-5-2',
+            );
+            const fable52 = CLAUDE_MODELS.find(
+                (m) => m.id === 'claude-fable-5-2',
+            )!;
+            expect(fable52.costs).toMatchObject({
+                input_tokens: 800,
+                output_tokens: 4000,
+                cache_read_input_tokens: 20,
+                ephemeral_5m_input_tokens: 1000,
+                ephemeral_1h_input_tokens: 1600,
+            });
+            expect(fable52.serviceSpeedRates?.fast).toMatchObject({
+                input_tokens: 1600,
+                output_tokens: 8000,
+                cache_read_input_tokens: 40,
+                ephemeral_5m_input_tokens: 2000,
+                ephemeral_1h_input_tokens: 3200,
+            });
+            expect(fable52.context).toBe(1_000_000);
+            expect(fable52.max_tokens).toBe(128_000);
+            const [, , prefix, overrides] = recordSpy.mock.calls[0]!;
+            expect(prefix).toBe('claude:claude-fable-5-2');
+            expect(overrides).toMatchObject({
+                input_tokens: 100 * Number(fable52.costs.input_tokens),
+                output_tokens: 50 * Number(fable52.costs.output_tokens),
+                cache_read_input_tokens:
+                    1000 * Number(fable52.costs.cache_read_input_tokens),
+                ephemeral_5m_input_tokens:
+                    150 * Number(fable52.costs.ephemeral_5m_input_tokens),
+                ephemeral_1h_input_tokens:
+                    50 * Number(fable52.costs.ephemeral_1h_input_tokens),
+            });
+        },
+    );
+
     it('routes the bare claude-fable alias to fable 5.1 rather than fable 5', async () => {
         const { provider } = makeProvider();
         messagesCreateMock.mockResolvedValueOnce(baseResponse);
@@ -2311,16 +2380,20 @@ describe('ClaudeProvider metering', () => {
         expect('thinking_tokens' in overrides).toBe(false);
     });
 
-    it('bills at the fast_* rates when the upstream reports usage.speed:"fast"', async () => {
+    it.each(['claude-opus-5-5', 'claude-fable-5-2'])('bills at fast rates for %s when the upstream reports fast usage', async (model) => {
         const { provider } = makeProvider();
         messagesCreateMock.mockResolvedValueOnce({
             content: [{ type: 'text', text: 'hi' }],
-            usage: { input_tokens: 10, output_tokens: 5, speed: 'fast' },
+            usage: {
+                input_tokens: 10, output_tokens: 5, speed: 'fast',
+                cache_creation: { ephemeral_5m_input_tokens: 7, ephemeral_1h_input_tokens: 3 },
+                cache_read_input_tokens: 20,
+            },
         });
 
         const result = (await withTestActor(() =>
             provider.complete({
-                model: 'claude-opus-5-5',
+                model,
                 messages: [{ role: 'user', content: 'hi' }],
                 speed: 'fast',
             }),
@@ -2331,11 +2404,15 @@ describe('ClaudeProvider metering', () => {
         expect('input_tokens' in result.usage).toBe(false);
         expect(result.usageDetails.speed).toBe('fast');
 
-        const opus = CLAUDE_MODELS.find((m) => m.id === 'claude-opus-5-5')!;
+        const selectedModel = CLAUDE_MODELS.find((m) => m.id === model)!;
         const [, , prefix, overrides] = recordSpy.mock.calls[0]!;
-        expect(prefix).toBe('claude:claude-opus-5-5');
-        expect(overrides.fast_input_tokens).toBe(10 * Number(opus.costs.fast_input_tokens));
-        expect(overrides.fast_output_tokens).toBe(5 * Number(opus.costs.fast_output_tokens));
+        expect(prefix).toBe(`claude:${model}`);
+        const fastRates = selectedModel.serviceSpeedRates!.fast as Record<string, number>;
+        expect(overrides.fast_input_tokens).toBe(10 * fastRates.input_tokens);
+        expect(overrides.fast_output_tokens).toBe(5 * fastRates.output_tokens);
+        expect(overrides.fast_ephemeral_5m_input_tokens).toBe(7 * fastRates.ephemeral_5m_input_tokens);
+        expect(overrides.fast_ephemeral_1h_input_tokens).toBe(3 * fastRates.ephemeral_1h_input_tokens);
+        expect(overrides.fast_cache_read_input_tokens).toBe(20 * fastRates.cache_read_input_tokens);
     });
 
     it('bills at standard rates when fast mode was requested but not granted by the upstream', async () => {
@@ -2357,13 +2434,15 @@ describe('ClaudeProvider metering', () => {
         expect('fast_input_tokens' in result.usage).toBe(false);
     });
 
-    it('retries at standard speed on Claude when fast mode is rate limited', async () => {
+    it.each([
+        [429, "This request would exceed your organization's rate limit of 0 fast mode input tokens per minute"],
+        [529, 'Overloaded'],
+        [529, 'Fast mode capacity unavailable'],
+    ])('retries at standard speed on Claude after fast capacity failure %s', async (status, message) => {
         const { provider } = makeProvider();
         const fastLimited = Object.assign(
-            new Error(
-                "This request would exceed your organization's rate limit of 0 fast mode input tokens per minute",
-            ),
-            { status: 429 },
+            new Error(message),
+            { status },
         );
         messagesCreateMock.mockRejectedValueOnce(fastLimited).mockResolvedValueOnce({
             content: [{ type: 'text', text: 'hi' }],
@@ -2587,13 +2666,13 @@ describe('ClaudeProvider.requestPricing', () => {
     const haiku = CLAUDE_MODELS.find((m) => m.id === 'claude-haiku-4-5-20251001')!;
     const opus55 = CLAUDE_MODELS.find((m) => m.id === 'claude-opus-5-5')!;
 
-    it('returns fast cost keys only when the model has fast rates and fast was requested', () => {
+    it('leaves token reservation keys to the selected catalog rate card', () => {
         const { provider } = makeProvider();
         expect(
             provider.requestPricing({ speed: 'fast', tools: [] } as never, opus55, {
                 promptTokenEstimate: 10,
             }),
-        ).toMatchObject({ inputKey: 'fast_input_tokens', outputKey: 'fast_output_tokens' });
+        ).toEqual({});
         expect(
             provider.requestPricing({ speed: 'fast', tools: [] } as never, haiku, {
                 promptTokenEstimate: 10,

src/backend/drivers/ai-chat/providers/claude/ClaudeProvider.ts

@@ -43,6 +43,7 @@ import {
 } from '../../utils/mediaParts.js';
 import { isToolChoice, toolChoiceFromWire } from '../../utils/openaiParams.js';
 import { buildCostsOverride } from '../../utils/pricing.js';
+import { serviceSpeedCosts } from '../../utils/serviceSpeed.js';
 import type {
     AIChatStream,
     AIChatTextStream,
@@ -107,20 +108,21 @@ const toAnthropicMediaPart = (part: any): any => {
     return part;
 };
 
-/** A 429 from fast mode's separate quota, not the model's normal limits. */
-const isFastModeRateLimit = (e: unknown): boolean => {
+/** Fast quota or overload failures can be retried at standard speed. */
+const isFastModeUnavailable = (e: unknown): boolean => {
     const err = e as { status?: unknown; message?: unknown };
     return (
-        err?.status === 429 &&
-        typeof err.message === 'string' &&
-        /fast mode/i.test(err.message)
+        typeof err?.message === 'string' &&
+        ((err?.status === 429 && /fast mode/i.test(err.message)) ||
+            (err?.status === 529 && /overload|fast mode/i.test(err.message)))
     );
 };
 
 // Models whose current turn rejects a non-default temperature/top_p/top_k
-// outright. Fable 5/5.1, Sonnet 5/5.5, Haiku 5.5, and Opus 4.7+.
+// outright. Fable 5/5.1/5.2, Sonnet 5/5.5, Haiku 5.5, and Opus 4.7+.
 const OMITS_SAMPLING_PARAMS = new Set([
     'claude-haiku-5-5',
+    'claude-fable-5-2',
     'claude-fable-5-1',
     'claude-fable-5',
     'claude-sonnet-5-5',
@@ -133,6 +135,7 @@ const OMITS_SAMPLING_PARAMS = new Set([
 
 const SUPPORTS_EFFORT = new Set([
     'claude-haiku-5-5',
+    'claude-fable-5-2',
     'claude-fable-5-1',
     'claude-fable-5',
     'claude-sonnet-5-5',
@@ -298,20 +301,12 @@ export class ClaudeProvider implements IChatProvider {
         return `claude:${modelId}`;
     }
 
-    /**
-     * Sizes the credit hold for Claude-only extras the generic per-token math
-     * can't see: fast mode's own rate card, and a web-search/advisor tool that
-     * could run several times before the model answers.
-     */
+    /** Reserves tools that can run several times before the model answers. */
     requestPricing(
         args: ICompleteArguments,
         model: IChatModel,
         est: { promptTokenEstimate: number },
-    ): { inputKey?: string; outputKey?: string; extraCost?: number } {
-        const fast =
-            args.speed === 'fast' &&
-            model.costs?.fast_output_tokens !== undefined;
-
+    ): { extraCost?: number } {
         let extraCost = 0;
         for (const raw of args.tools ?? []) {
             const tool = raw as Record<string, unknown>;
@@ -350,12 +345,6 @@ export class ClaudeProvider implements IChatProvider {
         }
 
         return {
-            ...(fast
-                ? {
-                      inputKey: 'fast_input_tokens',
-                      outputKey: 'fast_output_tokens',
-                  }
-                : {}),
             ...(extraCost > 0 ? { extraCost } : {}),
         };
     }
@@ -364,11 +353,9 @@ export class ClaudeProvider implements IChatProvider {
         try {
             return await this.#completeOnce(args);
         } catch (e) {
-            // Fast mode has its own quota. Anthropic's advice on that 429 is to
-            // drop `speed` and run at standard speed; doing it here keeps the
-            // request on Claude instead of marking the route unhealthy and
-            // replaying it on a reseller.
-            if (args.speed === 'fast' && isFastModeRateLimit(e)) {
+            // Retry fast-capacity failures on Claude at standard speed before
+            // considering a different provider.
+            if (args.speed === 'fast' && isFastModeUnavailable(e)) {
                 return await this.#completeOnce({ ...args, speed: undefined });
             }
             throw e;
@@ -637,7 +624,7 @@ export class ClaudeProvider implements IChatProvider {
             : undefined;
         const fast =
             args.speed === 'fast' &&
-            modelUsed.costs?.fast_output_tokens !== undefined;
+            modelUsed.serviceSpeedRates?.fast !== undefined;
         const safeguardsPolicy = applySafeguardsPolicy(
             args.safeguards,
             args.anthropicBetas,
@@ -1071,6 +1058,7 @@ export class ClaudeProvider implements IChatProvider {
         // keeps reasoning visible in the stream.
         if (
             modelId === 'claude-haiku-5-5' ||
+            modelId === 'claude-fable-5-2' ||
             modelId === 'claude-fable-5-1' ||
             modelId === 'claude-fable-5' ||
             modelId === 'claude-sonnet-5-5' ||
@@ -1505,7 +1493,8 @@ export class ClaudeProvider implements IChatProvider {
 
         const fast =
             raw.speed === 'fast' &&
-            modelUsed.costs?.fast_output_tokens !== undefined;
+            modelUsed.serviceSpeedRates?.fast !== undefined;
+        // Keep published usage keys while resolving rates from the common catalog shape.
         const executorUsage: Record<string, number> = fast
             ? Object.fromEntries(
                   Object.entries(exec).map(([k, v]) => [`fast_${k}`, v]),
@@ -1517,7 +1506,24 @@ export class ClaudeProvider implements IChatProvider {
         const fetches = raw.server_tool_use?.web_fetch_requests ?? 0;
         if (fetches) executorUsage.web_fetch_requests = fetches;
 
-        const executorCosts = buildCostsOverride(executorUsage, modelUsed);
+        const fastRates = fast
+            ? serviceSpeedCosts(modelUsed, 'fast')
+            : undefined;
+        const billingModel = fastRates
+            ? {
+                  ...modelUsed,
+                  costs: {
+                      ...modelUsed.costs,
+                      ...Object.fromEntries(
+                          Object.keys(exec).map((key) => [
+                              `fast_${key}`,
+                              fastRates[key],
+                          ]),
+                      ),
+                  },
+              }
+            : modelUsed;
+        const executorCosts = buildCostsOverride(executorUsage, billingModel);
 
         let advisorUsage: Record<string, number> | undefined;
         let advisorCosts: Record<string, number> | undefined;

src/backend/drivers/ai-chat/providers/claude/models.ts

@@ -55,6 +55,46 @@ export const CLAUDE_MODELS: IChatModel[] = [
         context: 1_000_000,
         max_tokens: 128_000,
     },
+    {
+        puterId: 'anthropic:anthropic/claude-fable-5-2',
+        id: 'claude-fable-5-2',
+        modalities: { input: ['text', 'image', 'pdf'], output: ['text'] },
+        open_weights: false,
+        tool_call: true,
+        release_date: '2026-11-09',
+        aliases: [
+            'claude-fable-5-2-latest',
+            'claude-fable-5.2',
+            'anthropic/claude-fable-5-2',
+        ],
+        name: 'Claude Fable 5.2',
+        midConversationSystem: true,
+        costs_currency: 'usd-cents',
+        input_cost_key: 'input_tokens',
+        output_cost_key: 'output_tokens',
+        // Source: https://www.anthropic.com/claude-fable-and-mythos-5-2
+        serviceSpeedRates: {
+            fast: {
+                input_tokens: 1600,
+                output_tokens: 8000,
+                ephemeral_5m_input_tokens: 1600 * 1.25,
+                ephemeral_1h_input_tokens: 1600 * 2,
+                cache_read_input_tokens: 1600 * 0.025,
+            },
+        },
+        costs: {
+            tokens: 1_000_000,
+            input_tokens: 800,
+            ephemeral_5m_input_tokens: 800 * 1.25,
+            ephemeral_1h_input_tokens: 800 * 2,
+            // 0.025x input, not the usual 0.1x.
+            cache_read_input_tokens: 800 * 0.025,
+            output_tokens: 4000,
+            web_search_requests: 1_000_000, // $10/1k requests
+        },
+        context: 1000000,
+        max_tokens: 128000,
+    },
     {
         puterId: 'anthropic:anthropic/claude-fable-5-1',
         id: 'claude-fable-5-1',
@@ -190,6 +230,15 @@ export const CLAUDE_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'input_tokens',
         output_cost_key: 'output_tokens',
+        serviceSpeedRates: {
+            fast: {
+                input_tokens: 800,
+                output_tokens: 4000,
+                ephemeral_5m_input_tokens: 1000,
+                ephemeral_1h_input_tokens: 1600,
+                cache_read_input_tokens: 40,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             input_tokens: 400,
@@ -199,12 +248,6 @@ export const CLAUDE_MODELS: IChatModel[] = [
             cache_read_input_tokens: 400 * 0.05,
             output_tokens: 2000,
             web_search_requests: 1_000_000,
-            // Fast mode (`speed:'fast'`), live-verified.
-            fast_input_tokens: 800,
-            fast_output_tokens: 4000,
-            fast_ephemeral_5m_input_tokens: 1000,
-            fast_ephemeral_1h_input_tokens: 1600,
-            fast_cache_read_input_tokens: 40, // 0.05x fast_input_tokens
         },
         context: 1000000,
         max_tokens: 128000,
@@ -223,6 +266,15 @@ export const CLAUDE_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'input_tokens',
         output_cost_key: 'output_tokens',
+        serviceSpeedRates: {
+            fast: {
+                input_tokens: 1000,
+                output_tokens: 5000,
+                ephemeral_5m_input_tokens: 1250,
+                ephemeral_1h_input_tokens: 2000,
+                cache_read_input_tokens: 100,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             input_tokens: 500,
@@ -231,11 +283,6 @@ export const CLAUDE_MODELS: IChatModel[] = [
             cache_read_input_tokens: 500 * 0.1,
             output_tokens: 2500,
             web_search_requests: 1_000_000,
-            fast_input_tokens: 1000,
-            fast_output_tokens: 5000,
-            fast_ephemeral_5m_input_tokens: 1250,
-            fast_ephemeral_1h_input_tokens: 2000,
-            fast_cache_read_input_tokens: 100,
         },
         context: 1000000,
         max_tokens: 128000,
@@ -258,6 +305,15 @@ export const CLAUDE_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'input_tokens',
         output_cost_key: 'output_tokens',
+        serviceSpeedRates: {
+            fast: {
+                input_tokens: 1000,
+                output_tokens: 5000,
+                ephemeral_5m_input_tokens: 1250,
+                ephemeral_1h_input_tokens: 2000,
+                cache_read_input_tokens: 100,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             input_tokens: 500,
@@ -266,11 +322,6 @@ export const CLAUDE_MODELS: IChatModel[] = [
             cache_read_input_tokens: 500 * 0.1,
             output_tokens: 2500,
             web_search_requests: 1_000_000,
-            fast_input_tokens: 1000,
-            fast_output_tokens: 5000,
-            fast_ephemeral_5m_input_tokens: 1250,
-            fast_ephemeral_1h_input_tokens: 2000,
-            fast_cache_read_input_tokens: 100,
         },
         context: 1000000,
         max_tokens: 128000,

src/backend/drivers/ai-chat/providers/gemini/GeminiChatProvider.ts

@@ -84,8 +84,14 @@ export class GeminiChatProvider extends OpenAICompatProvider {
             chat: {
                 completions: {
                     create: (params, options) => {
-                        const { model } = params as { model: string };
-                        if (!GEMINI_NATIVE_MODELS.has(model)) {
+                        const { model, service_tier } = params as {
+                            model: string;
+                            service_tier?: string;
+                        };
+                        if (
+                            !GEMINI_NATIVE_MODELS.has(model) &&
+                            (service_tier === undefined || !native)
+                        ) {
                             return compat.chat.completions.create(
                                 params,
                                 options,
@@ -103,7 +109,12 @@ export class GeminiChatProvider extends OpenAICompatProvider {
                 },
             },
         };
-        const models = native ? GEMINI_MODELS : COMPAT_ONLY_MODELS;
+        const models: IChatModel[] = native
+            ? GEMINI_MODELS
+            : COMPAT_ONLY_MODELS.map((model) => ({
+                  ...model,
+                  serviceSpeeds: ['standard'],
+              }));
         super(meteringService, {
             client,
             defaultModel: 'gemini-2.5-flash',
@@ -183,7 +194,10 @@ export class GeminiChatProvider extends OpenAICompatProvider {
     }
 
     protected override meteredUsage(source: UsageSource, model: IChatModel) {
-        if (GEMINI_NATIVE_MODELS.has(model.id)) {
+        if (
+            GEMINI_NATIVE_MODELS.has(model.id) ||
+            'promptTokenCount' in (source.usage ?? {})
+        ) {
             return nativeMeteredUsage(
                 source.usage as unknown as
                     GenerateContentResponseUsageMetadata | undefined,

src/backend/drivers/ai-chat/providers/gemini/geminiNative.ts

@@ -80,6 +80,7 @@ interface ChatParams {
     temperature?: number;
     reasoning_effort?: 'minimal' | 'low' | 'medium' | 'high';
     stream?: boolean;
+    service_tier?: string;
 }
 
 /** Ids made up for calls Gemini returned without one; never sent back. */
@@ -240,6 +241,12 @@ const toGenerateContentRequest = (
         ? toolConfigOf(params.tool_choice)
         : undefined;
     const config: GenerateContentConfig = {
+        ...(params.service_tier !== undefined
+            ? {
+                  serviceTier:
+                      params.service_tier as GenerateContentConfig['serviceTier'],
+              }
+            : {}),
         ...(signal ? { abortSignal: signal } : {}),
         ...(systemInstruction ? { systemInstruction } : {}),
         ...(params.max_completion_tokens !== undefined

src/backend/drivers/ai-chat/providers/gemini/models.ts

@@ -142,6 +142,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.8 },
         costs: ARGON_LAUNCH_COSTS,
         pricingOverrides: listPricingFrom(
             '2026-12-01T00:00:00Z',
@@ -174,6 +175,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
         // Google serves this endpoint with gemini-3.6-flash and bills its rates.
+        serviceSpeedRates: { fast: 1.8 },
         costs: FLASH_LAUNCH_COSTS,
         pricingOverrides: FLASH_LIST_PRICING,
     },
@@ -201,6 +203,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.8 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30,
@@ -228,6 +231,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.8 },
         costs: FLASH_LAUNCH_COSTS,
         pricingOverrides: FLASH_LIST_PRICING,
     },
@@ -250,6 +254,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
         // Google serves this endpoint with gemini-3.8-flash and bills its rates.
+        serviceSpeedRates: { fast: 1.8 },
         costs: FLASH_LAUNCH_COSTS,
         pricingOverrides: FLASH_LIST_PRICING,
     },
@@ -270,6 +275,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.8 },
         costs: FLASH_LAUNCH_COSTS,
         pricingOverrides: FLASH_LIST_PRICING,
     },
@@ -291,6 +297,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.8 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 25,
@@ -318,6 +325,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.8 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 50,
@@ -344,6 +352,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.8 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30,
@@ -374,6 +383,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.8 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 10,
@@ -402,6 +412,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.8 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 125,
@@ -448,6 +459,7 @@ export const GEMINI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.8 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200,

src/backend/drivers/ai-chat/providers/infron/InfronProvider.ts

@@ -266,6 +266,15 @@ export class InfronProvider extends OpenAICompatProvider {
         return coerced_models;
     }
 
+    async serviceSpeedModels(model: IChatModel) {
+        const variant = (await this.models()).find(
+            (entry) => entry.id === `${model.id}:priority`,
+        );
+        return variant
+            ? { fast: { ...variant, provider: model.provider } }
+            : {};
+    }
+
     protected override vendorParams(
         params: Record<string, unknown>,
         _args: unknown,

src/backend/drivers/ai-chat/providers/meta/MetaProvider.ts

@@ -23,6 +23,7 @@ import { HttpError } from '../../../../core/http/HttpError.js';
 import type { MeteringService } from '../../../../services/metering/MeteringService.js';
 import { upstreamUserIdentifier } from '../../../util/upstreamIdentifier.js';
 import type { IChatModel, ICompleteArguments } from '../../types.js';
+import { promptCacheRetentionToWire } from '../../utils/openaiParams.js';
 import { sdkClientOptions } from '../../utils/sdkClient.js';
 import {
     type ChatProviderConfig,
@@ -107,12 +108,9 @@ export class MetaProvider extends OpenAICompatProvider {
                 ? requestedEffort
                 : undefined;
 
-        // Puter spells the in-memory retention with a hyphen; Meta's enum
-        // uses an underscore.
-        const cacheRetention =
-            args.prompt_cache_retention === 'in-memory'
-                ? 'in_memory'
-                : args.prompt_cache_retention;
+        const cacheRetention = promptCacheRetentionToWire(
+            args.prompt_cache_retention,
+        );
 
         // The identifier is Puter's abuse attribution, so `custom` can't
         // override it. Cache key defaults to it; see upstreamUserIdentifier.

src/backend/drivers/ai-chat/providers/minimax/models.ts

@@ -43,6 +43,8 @@ export const MINIMAX_MODELS: MiniMaxChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.5 },
+        serviceSpeedVariants: { fast: 'minimax-m3-highspeed' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30, // $0.30 per 1M (input <= 512k tokens)
@@ -70,6 +72,7 @@ export const MINIMAX_MODELS: MiniMaxChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'minimax-m2.7-highspeed' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30, // $0.30 per 1M
@@ -122,6 +125,7 @@ export const MINIMAX_MODELS: MiniMaxChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'minimax-m2.5-highspeed' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30, // $0.30 per 1M
@@ -174,6 +178,7 @@ export const MINIMAX_MODELS: MiniMaxChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'minimax-m2.1-highspeed' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30, // $0.30 per 1M
@@ -222,6 +227,7 @@ export const MINIMAX_MODELS: MiniMaxChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'minimax-m2-highspeed' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30, // $0.30 per 1M

src/backend/drivers/ai-chat/providers/mistral/MistralAiProvider.test.ts

@@ -20,13 +20,12 @@
 /**
  * Offline unit tests for MistralAIProvider.
  *
- * Boots a real PuterServer (in-memory sqlite + dynamo + s3 + mock
- * redis) and constructs MistralAIProvider directly against the live
- * wired `MeteringService` so the recording side is exercised end-to-
- * end. The Mistral SDK is mocked at the module boundary (the real
- * network egress point) so the provider never reaches the network.
- * The companion integration test (MistralAiProvider.integration.test.ts)
- * exercises the real Mistral endpoint.
+ * Boots a real PuterServer (in-memory sqlite + dynamo + s3 + mock redis) and
+ * constructs MistralAIProvider directly against the live wired
+ * `MeteringService` so the recording side is exercised end-to- end. The Mistral
+ * SDK is mocked at the module boundary (the real network egress point) so the
+ * provider never reaches the network. The companion integration test
+ * (MistralAiProvider.integration.test.ts) exercises the real Mistral endpoint.
  */
 
 import { Context } from '../../../../core/context.js';
@@ -147,7 +146,9 @@ describe('MistralAIProvider construction', () => {
     it('constructs the Mistral SDK with the configured API key', () => {
         makeProvider();
         expect(mistralCtor).toHaveBeenCalledTimes(1);
-        expect(mistralCtor).toHaveBeenCalledWith({ apiKey: 'test-key' });
+        expect(mistralCtor).toHaveBeenCalledWith(
+            expect.objectContaining({ apiKey: 'test-key' }),
+        );
     });
 });
 
@@ -606,7 +607,11 @@ describe('MistralAIProvider.complete non-stream output', () => {
             if (stream) {
                 streamMock.mockResolvedValueOnce(
                     asAsyncIterable([
-                        { data: { choices: [{ delta: { content: 'hello' } }] } },
+                        {
+                            data: {
+                                choices: [{ delta: { content: 'hello' } }],
+                            },
+                        },
                         { data: { choices: [], usage } },
                     ]),
                 );
@@ -643,7 +648,11 @@ describe('MistralAIProvider.complete non-stream output', () => {
                 expect(result).toMatchObject({ message: { content: 'hello' } });
             }
             expect(recordSpy).toHaveBeenCalledWith(
-                { prompt_tokens: 5, cached_tokens: 1008, completion_tokens: 30 },
+                {
+                    prompt_tokens: 5,
+                    cached_tokens: 1008,
+                    completion_tokens: 30,
+                },
                 SYSTEM_ACTOR,
                 `mistral:${model}`,
                 {
@@ -688,8 +697,7 @@ describe('MistralAIProvider.complete non-stream output', () => {
         });
 
         expect(recordSpy).toHaveBeenCalledTimes(1);
-        const [usage, actor, prefix, overrides] =
-            recordSpy.mock.calls[0]!;
+        const [usage, actor, prefix, overrides] = recordSpy.mock.calls[0]!;
         expect(usage).toEqual({
             prompt_tokens: 100,
             completion_tokens: 50,
@@ -718,15 +726,11 @@ describe('MistralAIProvider.complete non-stream output', () => {
                         content: [
                             {
                                 type: 'thinking',
-                                thinking: [
-                                    { type: 'text', text: 'step one.' },
-                                ],
+                                thinking: [{ type: 'text', text: 'step one.' }],
                             },
                             {
                                 type: 'thinking',
-                                thinking: [
-                                    { type: 'text', text: 'step two.' },
-                                ],
+                                thinking: [{ type: 'text', text: 'step two.' }],
                             },
                             { type: 'text', text: 'the answer' },
                         ],
@@ -916,8 +920,7 @@ describe('MistralAIProvider.complete streaming', () => {
 
         // mistral-small-2603: prompt=15, completion=60.
         expect(recordSpy).toHaveBeenCalledTimes(1);
-        const [, , prefix, overrides] =
-            recordSpy.mock.calls[0]!;
+        const [, , prefix, overrides] = recordSpy.mock.calls[0]!;
         expect(prefix).toBe('mistral:mistral-small-2603');
         expect(overrides).toMatchObject({
             prompt_tokens: 4 * 15,
@@ -1115,7 +1118,7 @@ describe('MistralAIProvider image_url coercion', () => {
         usage: { promptTokens: 1, completionTokens: 1 },
     };
 
-    it('rewrites canonical image_url parts to the SDK\'s camelCase imageUrl', async () => {
+    it("rewrites canonical image_url parts to the SDK's camelCase imageUrl", async () => {
         const { provider } = makeProvider();
         completeMock.mockResolvedValueOnce(baseCompletion);
 
@@ -1175,7 +1178,8 @@ describe('MistralAIProvider image_url coercion', () => {
                             },
                             {
                                 type: 'image_url',
-                                image_url: 'https://example.com/already-flat.png',
+                                image_url:
+                                    'https://example.com/already-flat.png',
                             },
                         ],
                     },
@@ -1251,7 +1255,9 @@ describe('MistralAIProvider image_url coercion', () => {
                             { type: 'text', text: 'what is in this image?' },
                             {
                                 type: 'image_url',
-                                image_url: { url: 'https://example.com/photo.jpg' },
+                                image_url: {
+                                    url: 'https://example.com/photo.jpg',
+                                },
                             },
                         ],
                     },
@@ -1260,7 +1266,11 @@ describe('MistralAIProvider image_url coercion', () => {
         );
 
         const [args] = completeMock.mock.calls[0]!;
-        const parts = args.messages[0].content as { type: string; text?: string; imageUrl?: unknown }[];
+        const parts = args.messages[0].content as {
+            type: string;
+            text?: string;
+            imageUrl?: unknown;
+        }[];
         const textPart = parts.find((p) => p.type === 'text');
         const imgPart = parts.find((p) => p.type === 'image_url');
         expect(textPart?.text).toBe('what is in this image?');
@@ -1300,3 +1310,41 @@ describe('MistralAIProvider.checkModeration', () => {
         );
     });
 });
+
+describe('Mistral service speed wire mapping', () => {
+    it('adds the tier after SDK serialization and removes its internal header', async () => {
+        makeProvider();
+        const options = mistralCtor.mock.calls[0][0] as {
+            httpClient: import('@mistralai/mistralai/lib/http.js').HTTPClient;
+        };
+        let sent: Request | undefined;
+        vi.stubGlobal('fetch', async (input: Request) => {
+            sent = input;
+            return new Response('{}', {
+                headers: { 'content-type': 'application/json' },
+            });
+        });
+        try {
+            await options.httpClient.request(
+                new Request('https://api.mistral.ai/v1/chat/completions', {
+                    method: 'POST',
+                    headers: {
+                        'content-type': 'application/json',
+                        'x-puter-service-tier': 'auto',
+                    },
+                    body: JSON.stringify({
+                        model: 'mistral-medium-latest',
+                        messages: [],
+                    }),
+                }),
+            );
+            expect(sent?.headers.has('x-puter-service-tier')).toBe(false);
+            expect(await sent?.json()).toMatchObject({
+                model: 'mistral-medium-latest',
+                service_tier: 'auto',
+            });
+        } finally {
+            vi.unstubAllGlobals();
+        }
+    });
+});

src/backend/drivers/ai-chat/providers/mistral/MistralAiProvider.ts

@@ -17,6 +17,8 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+import { HTTPClient } from '@mistralai/mistralai/lib/http.js';
+import { servedServiceSpeed } from '../../utils/serviceSpeed.js';
 import { Mistral } from '@mistralai/mistralai';
 import { ChatCompletionResponse } from '@mistralai/mistralai/models/components/chatcompletionresponse.js';
 import { MistralError } from '@mistralai/mistralai/models/errors/mistralerror.js';
@@ -26,6 +28,7 @@ import { Context } from '../../../../core/context.js';
 import { HttpError } from '../../../../core/http/HttpError.js';
 import type { MeteringService } from '../../../../services/metering/MeteringService.js';
 import type {
+    IChatModel,
     IChatCompleteResult,
     IChatProvider,
     ICompleteArguments,
@@ -106,6 +109,7 @@ const coerceMistralUsage = (usage: UsageInfo) => {
         prompt_tokens: (usage.promptTokens ?? 0) - cachedTokens,
         completion_tokens: usage.completionTokens ?? 0,
         prompt_tokens_details: { cached_tokens: cachedTokens },
+        service_tier: usage.additionalProperties?.service_tier,
     };
 };
 
@@ -115,7 +119,24 @@ export class MistralAIProvider implements IChatProvider {
     #meteringService: MeteringService;
 
     constructor(config: { apiKey: string }, meteringService: MeteringService) {
+        const httpClient = new HTTPClient();
+        // The SDK strips service_tier during body serialization.
+        httpClient.addHook('beforeRequest', async (request) => {
+            const tier = request.headers.get('x-puter-service-tier');
+            if (!tier) return;
+            const headers = new Headers(request.headers);
+            headers.delete('x-puter-service-tier');
+            const body = await request.json();
+            return new Request(request, {
+                headers,
+                body: JSON.stringify({
+                    ...body,
+                    service_tier: tier === 'auto' ? 'auto' : 'standard_only',
+                }),
+            });
+        });
         this.#client = new Mistral({
+            httpClient,
             apiKey: config.apiKey,
         });
         this.#meteringService = meteringService;
@@ -181,17 +202,22 @@ export class MistralAIProvider implements IChatProvider {
         return `mistral:${modelId}`;
     }
 
-    async complete({
-        messages,
-        stream,
-        model,
-        tools,
-        max_tokens,
-        temperature,
-        normalize,
-        response,
-        custom,
-    }: ICompleteArguments): Promise<IChatCompleteResult> {
+    async complete(
+        {
+            messages,
+            stream,
+            model,
+            tools,
+            max_tokens,
+            temperature,
+            normalize,
+            response,
+            custom,
+            service_tier,
+            serviceSpeed: requestedServiceSpeed,
+        }: ICompleteArguments,
+        resolved?: IChatModel,
+    ): Promise<IChatCompleteResult> {
         // Mistral's reasoning prompt mode: with `prompt_mode: 'reasoning'`,
         // reasoning-capable models return their thinking as structured ThinkChunk
         // content (which the splitter below separates into `reasoning`)
@@ -217,10 +243,13 @@ export class MistralAIProvider implements IChatProvider {
         }
 
         const selectedModel =
-            (await this.models()).find((m) =>
+            resolved ??
+            ((await this.models()).find((m) =>
                 [m.id, ...(m.aliases || [])].includes(model),
             ) ||
-            (await this.models()).find((m) => m.id === this.getDefaultModel())!;
+                (await this.models()).find(
+                    (m) => m.id === this.getDefaultModel(),
+                )!);
         const actor = Context.get('actor');
         let completion: Awaited<
             ReturnType<Mistral['chat']['complete' | 'stream']>
@@ -242,6 +271,9 @@ export class MistralAIProvider implements IChatProvider {
                 // The SDK retries nothing by default and has no timeout once a
                 // signal is passed; a stream is bounded by its caller instead.
                 {
+                    ...(service_tier !== undefined
+                        ? { headers: { 'x-puter-service-tier': service_tier } }
+                        : {}),
                     signal: stream
                         ? Context.get('upstreamSignal')
                         : withSdkTimeout(Context.get('upstreamSignal')),
@@ -398,7 +430,8 @@ export class MistralAIProvider implements IChatProvider {
             },
             completion: completion as ChatCompletionResponse,
             stream,
-            usage_calculator: ({ usage, setUsageCosts }) => {
+            usage_calculator: ({ usage, setUsageCosts, setUsageDetails }) => {
+                const serviceSpeed = servedServiceSpeed({ usage });
                 // `coerceMistralUsage` has already taken cached reads out of
                 // `prompt_tokens`.
                 const metered = meterChatUsage(
@@ -407,8 +440,16 @@ export class MistralAIProvider implements IChatProvider {
                     this.meteringModelKey(selectedModel.id),
                     selectedModel,
                     OpenAIUtil.extractMeteredUsage(usage),
+                    { serviceSpeed },
                 );
                 setUsageCosts(metered.costs);
+                if (requestedServiceSpeed !== undefined)
+                    setUsageDetails({
+                        ...OpenAIUtil.usageDetailsFromTrackedUsage(
+                            metered.usage,
+                        )!,
+                        serviceSpeed,
+                    });
                 return metered.usage;
             },
         });

src/backend/drivers/ai-chat/providers/mistral/models.ts

@@ -42,6 +42,7 @@ export const MISTRAL_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.75 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 136,
@@ -75,6 +76,7 @@ export const MISTRAL_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.75 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 150,
@@ -105,6 +107,7 @@ export const MISTRAL_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.75 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 50,
@@ -135,6 +138,7 @@ export const MISTRAL_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.75 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 15,
@@ -159,6 +163,7 @@ export const MISTRAL_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.75 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 140,
@@ -188,6 +193,7 @@ export const MISTRAL_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.75 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 30,
@@ -213,6 +219,7 @@ export const MISTRAL_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.75 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 20,
@@ -238,6 +245,7 @@ export const MISTRAL_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.75 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 15,
@@ -262,6 +270,7 @@ export const MISTRAL_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 1.75 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 10,

src/backend/drivers/ai-chat/providers/moonshot/models.ts

@@ -30,6 +30,7 @@ export const MOONSHOT_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'kimi-k3.1-pro-highspeed' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200, // $2.00 per 1M
@@ -77,6 +78,7 @@ export const MOONSHOT_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'kimi-k3-highspeed' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 300, // $3.00 per 1M
@@ -104,6 +106,7 @@ export const MOONSHOT_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'kimi-k2.6-highspeed' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 95, // $0.95 per 1M
@@ -126,6 +129,7 @@ export const MOONSHOT_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedVariants: { fast: 'kimi-k2.7-code-highspeed' },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 95,

src/backend/drivers/ai-chat/providers/openai/OpenAiChatCompletionsProvider.test.ts

@@ -249,6 +249,130 @@ describe('OpenAiChatProvider.complete argument validation', () => {
         expect(result).toEqual({ delegated: true });
     });
 
+    it('delegates a 12h cache lifetime to the Responses provider, which is the only API that writes it', async () => {
+        const { provider } = makeProvider();
+        const sibling = {
+            complete: vi.fn().mockResolvedValue({ delegated: true }),
+        };
+        provider.setResponsesProvider(
+            sibling as unknown as Parameters<
+                typeof provider.setResponsesProvider
+            >[0],
+        );
+
+        const params = {
+            model: 'gpt-6-luna',
+            messages: [{ role: 'user', content: 'hi' }],
+            prompt_cache_options: { ttl: '12h' as const },
+        };
+        const result = await withTestActor(() => provider.complete(params));
+
+        expect(createMock).not.toHaveBeenCalled();
+        expect(sibling.complete).toHaveBeenCalledWith(params);
+        expect(result).toEqual({ delegated: true });
+    });
+
+    it.each([
+        ['30m', { mode: 'explicit', ttl: '30m' }],
+        ['12h', { mode: 'explicit', ttl: '12h' }],
+    ])(
+        'delegates a %s breakpoint lifetime to the Responses provider, since Chat Completions rejects the field',
+        async (_ttl, breakpoint) => {
+            const { provider } = makeProvider();
+            const sibling = {
+                complete: vi.fn().mockResolvedValue({ delegated: true }),
+            };
+            provider.setResponsesProvider(
+                sibling as unknown as Parameters<
+                    typeof provider.setResponsesProvider
+                >[0],
+            );
+
+            const params = {
+                model: 'gpt-6-luna',
+                messages: [
+                    {
+                        role: 'system',
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'long prefix',
+                                prompt_cache_breakpoint: breakpoint,
+                            },
+                        ],
+                    },
+                    { role: 'user', content: 'hi' },
+                ],
+            };
+            const result = await withTestActor(() =>
+                provider.complete(params as never),
+            );
+
+            expect(createMock).not.toHaveBeenCalled();
+            expect(sibling.complete).toHaveBeenCalledWith(params);
+            expect(result).toEqual({ delegated: true });
+        },
+    );
+
+    it('keeps a breakpoint without a lifetime on the Chat Completions path, intact', async () => {
+        const { provider } = makeProvider();
+        createMock.mockResolvedValueOnce({
+            choices: [
+                {
+                    message: { content: 'ok', role: 'assistant' },
+                    finish_reason: 'stop',
+                },
+            ],
+            usage: { prompt_tokens: 1, completion_tokens: 1 },
+        });
+
+        await withTestActor(() =>
+            provider.complete({
+                model: 'gpt-6-luna',
+                messages: [
+                    {
+                        role: 'system',
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'long prefix',
+                                prompt_cache_breakpoint: { mode: 'explicit' },
+                            },
+                        ],
+                    },
+                    { role: 'user', content: 'hi' },
+                ],
+            } as never),
+        );
+
+        const [args] = createMock.mock.calls[0]!;
+        expect(args.messages[0]).toMatchObject({
+            role: 'system',
+            content: [
+                {
+                    type: 'text',
+                    text: 'long prefix',
+                    prompt_cache_breakpoint: { mode: 'explicit' },
+                },
+            ],
+        });
+    });
+
+    it('throws 400 for a 12h cache lifetime without a Responses sibling provider', async () => {
+        const { provider } = makeProvider();
+
+        await expect(
+            withTestActor(() =>
+                provider.complete({
+                    model: 'gpt-6-luna',
+                    messages: [{ role: 'user', content: 'hi' }],
+                    prompt_cache_options: { ttl: '12h' },
+                }),
+            ),
+        ).rejects.toMatchObject({ statusCode: 400 });
+        expect(createMock).not.toHaveBeenCalled();
+    });
+
     it('requestPricing delegates to the Responses sibling (web_search\'s own hold), and no-ops without one', async () => {
         const { provider } = makeProvider();
         const args = {
@@ -349,6 +473,31 @@ describe('OpenAiChatProvider.complete request shape', () => {
         expect(args.safety_identifier).toBe('puter-u42');
     });
 
+    it('forwards 30m prompt_cache_options and the wire spelling of prompt_cache_retention', async () => {
+        const { provider } = makeProvider();
+        createMock.mockResolvedValueOnce(baseCompletion);
+
+        await withTestActor(() =>
+            provider.complete({
+                model: 'gpt-6-luna',
+                messages: [{ role: 'user', content: 'hello' }],
+                prompt_cache_retention: 'in-memory',
+                prompt_cache_options: {
+                    mode: 'explicit',
+                    ttl: '30m',
+                    prewarm: true,
+                } as never,
+            }),
+        );
+
+        const [args] = createMock.mock.calls[0]!;
+        expect(args.prompt_cache_retention).toBe('in_memory');
+        expect(args.prompt_cache_options).toEqual({
+            mode: 'explicit',
+            ttl: '30m',
+        });
+    });
+
     it.each([
         'gpt-6-astra',
         'gpt-6.1-sol',
@@ -665,7 +814,7 @@ describe('OpenAiChatProvider.complete non-stream output', () => {
             },
         });
 
-        await withTestActor(() =>
+        const result = await withTestActor(() =>
             provider.complete({
                 model: 'gpt-6-luna',
                 messages: [{ role: 'user', content: 'hi' }],
@@ -685,6 +834,13 @@ describe('OpenAiChatProvider.complete non-stream output', () => {
             cached_tokens: 1000 * Number(luna.costs.cached_tokens),
             cache_write_tokens: 3000 * Number(luna.costs.cache_write_tokens),
         });
+        // Chat Completions only writes OpenAI's default 30m entries.
+        expect((result as { usageDetails: unknown }).usageDetails).toEqual({
+            inputTokens: 1000,
+            outputTokens: 12,
+            cacheReadTokens: 1000,
+            cacheWrite30mTokens: 3000,
+        });
     });
 
     it('zeroes cached_tokens when prompt_tokens_details is missing', async () => {

src/backend/drivers/ai-chat/providers/openai/OpenAiChatCompletionsProvider.ts

@@ -20,6 +20,7 @@
 import { HttpError } from '@heyputer/backend/src/core/http/HttpError.js';
 import { OpenAI } from 'openai';
 import { ChatCompletionCreateParams } from 'openai/resources/index.js';
+import { servedServiceSpeed } from '../../utils/serviceSpeed.js';
 import { Context } from '../../../../core/context.js';
 import type { MeteringService } from '../../../../services/metering/MeteringService.js';
 import type {
@@ -35,7 +36,10 @@ import { make_openai_tools } from '../../utils/FunctionCalling.js';
 import * as OpenAiUtil from '../../utils/OpenAIUtil.js';
 import {
     clampReasoningEffort,
+    messagesHaveCacheBreakpointTtl,
     openAICompatParams,
+    promptCacheOptionsToWire,
+    promptCacheRetentionToWire,
 } from '../../utils/openaiParams.js';
 import { OPEN_AI_MODELS } from './models.js';
 import type { OpenAiResponsesChatProvider } from './OpenAiChatResponsesProvider.js';
@@ -114,6 +118,7 @@ export class OpenAiChatProvider implements IChatProvider {
 
     async complete(
         params: ICompleteArguments,
+        resolved?: IChatModel,
     ): ReturnType<IChatProvider['complete']> {
         const {
             max_tokens,
@@ -126,8 +131,16 @@ export class OpenAiChatProvider implements IChatProvider {
             temperature,
             text,
             prompt_cache_key,
+            prompt_cache_retention,
+            prompt_cache_options,
         } = params;
         let { messages, model } = params;
+        const cacheOptions = promptCacheOptionsToWire(prompt_cache_options);
+        if (params.service_tier === 'ultrafast' && this.#responsesProvider) {
+            return resolved
+                ? this.#responsesProvider.complete(params, resolved)
+                : this.#responsesProvider.complete(params);
+        }
         if (
             tools?.filter((e) => isWebSearchTool(e as Record<string, unknown>))
                 .length
@@ -141,7 +154,9 @@ export class OpenAiChatProvider implements IChatProvider {
                     { legacyCode: 'bad_request' },
                 );
             }
-            return await this.#responsesProvider.complete(params);
+            return await (resolved
+                ? this.#responsesProvider.complete(params, resolved)
+                : this.#responsesProvider.complete(params));
         }
         // Inline compaction is a Responses-API feature; chat.completions can't
         // express `context_management` or a `compaction` content block.
@@ -155,7 +170,26 @@ export class OpenAiChatProvider implements IChatProvider {
                     { legacyCode: 'bad_request' },
                 );
             }
-            return await this.#responsesProvider.complete(params);
+            return await (resolved
+                ? this.#responsesProvider.complete(params, resolved)
+                : this.#responsesProvider.complete(params));
+        }
+        // Only the Responses API writes 12h cache entries or takes a lifetime
+        // on a `prompt_cache_breakpoint`; Chat Completions rejects both.
+        if (
+            cacheOptions?.ttl === '12h' ||
+            messagesHaveCacheBreakpointTtl(messages)
+        ) {
+            if (!this.#responsesProvider) {
+                throw new HttpError(
+                    400,
+                    'a prompt cache lifetime requires the OpenAI Responses provider, which is not configured',
+                    { legacyCode: 'bad_request' },
+                );
+            }
+            return await (resolved
+                ? this.#responsesProvider.complete(params, resolved)
+                : this.#responsesProvider.complete(params));
         }
         // Validate messages
         if (!Array.isArray(messages)) {
@@ -168,9 +202,11 @@ export class OpenAiChatProvider implements IChatProvider {
         model = model ?? this.#defaultModel;
 
         const modelUsed =
-            this.models().find((m) =>
+            resolved ??
+            (this.models().find((m) =>
                 [m.id, ...(m.aliases || [])].includes(model),
-            ) || this.models().find((m) => m.id === this.getDefaultModel())!;
+            ) ||
+                this.models().find((m) => m.id === this.getDefaultModel())!);
 
         // messages.unshift({
         //     role: 'system',
@@ -180,6 +216,9 @@ export class OpenAiChatProvider implements IChatProvider {
         const userIdentifier = upstreamUserIdentifier(actor);
         // Cache key defaults to the actor identifier; see upstreamUserIdentifier.
         const cacheKey = prompt_cache_key ?? userIdentifier;
+        const cacheRetention = promptCacheRetentionToWire(
+            prompt_cache_retention,
+        );
 
         // Strip Anthropic-only shape a fallback-replayed message can carry
         // (thinking/server-tool blocks, cache_control, citations) before the
@@ -216,8 +255,17 @@ export class OpenAiChatProvider implements IChatProvider {
             user: userIdentifier,
             safety_identifier: userIdentifier,
             ...(cacheKey !== undefined ? { prompt_cache_key: cacheKey } : {}),
+            ...(cacheRetention !== undefined
+                ? { prompt_cache_retention: cacheRetention }
+                : {}),
+            ...(cacheOptions !== undefined
+                ? { prompt_cache_options: cacheOptions }
+                : {}),
             messages: messages,
             model: modelUsed.id,
+            ...(params.service_tier !== undefined
+                ? { service_tier: params.service_tier }
+                : {}),
             ...(mappedTools?.length ? { tools: mappedTools } : {}),
             ...(max_tokens !== undefined
                 ? { max_completion_tokens: max_tokens }
@@ -254,28 +302,17 @@ export class OpenAiChatProvider implements IChatProvider {
         );
 
         return OpenAiUtil.handle_completion_output({
-            usage_calculator: ({ usage, setUsageCosts }) => {
-                const cachedTokens =
-                    usage.prompt_tokens_details?.cached_tokens ?? 0;
-                // GPT-5.6 and later bill cache writes at 1.25x input. They're
-                // reported inside `prompt_tokens`, like cached reads.
-                // The SDK doesn't type `cache_write_tokens` yet.
-                const cacheWriteTokens =
-                    (
-                        usage.prompt_tokens_details as
-                            { cache_write_tokens?: number } | undefined
-                    )?.cache_write_tokens ?? 0;
-                const trackedUsage = {
-                    prompt_tokens:
-                        (usage.prompt_tokens ?? 0) -
-                        cachedTokens -
-                        cacheWriteTokens,
-                    completion_tokens: usage.completion_tokens ?? 0,
-                    cached_tokens: cachedTokens,
-                    ...(cacheWriteTokens
-                        ? { cache_write_tokens: cacheWriteTokens }
-                        : {}),
-                };
+            usage_calculator: ({
+                usage,
+                service_tier,
+                setUsageCosts,
+                setUsageDetails,
+            }) => {
+                const serviceSpeed = servedServiceSpeed({ service_tier });
+                // GPT-5.6 and later report cache writes inside
+                // `prompt_tokens`, like cached reads; Chat Completions only
+                // writes the default 30m entries, billed at 1.25x input.
+                const trackedUsage = OpenAiUtil.splitCachedPrompt(usage);
 
                 const metered = meterChatUsage(
                     this.#meteringService,
@@ -283,8 +320,17 @@ export class OpenAiChatProvider implements IChatProvider {
                     this.meteringModelKey(modelUsed.id),
                     modelUsed,
                     trackedUsage,
+                    { serviceSpeed },
                 );
                 setUsageCosts(metered.costs);
+                setUsageDetails({
+                    ...OpenAiUtil.usageDetailsFromTrackedUsage(metered.usage, {
+                        writeTtl: '30m',
+                    })!,
+                    ...(params.serviceSpeed !== undefined
+                        ? { serviceSpeed }
+                        : {}),
+                });
                 return metered.usage;
             },
             stream,

src/backend/drivers/ai-chat/providers/openai/OpenAiChatResponsesProvider.test.ts

@@ -44,7 +44,9 @@ import {
     type MockInstance,
 } from 'vitest';
 
-import { SYSTEM_ACTOR } from '../../../../core/actor.js';
+import { SYSTEM_ACTOR, type Actor } from '../../../../core/actor.js';
+import { v4 as uuidv4 } from 'uuid';
+import { ChatCompletionDriver } from '../../ChatCompletionDriver.js';
 import type { MeteringService } from '../../../../services/metering/MeteringService.js';
 import { PuterServer } from '../../../../server.js';
 import { setupTestServer } from '../../../../testUtil.js';
@@ -246,6 +248,7 @@ describe('OpenAiResponsesChatProvider model catalog', () => {
                     prompt_tokens: input,
                     cached_tokens: cached,
                     cache_write_tokens: input * 1.25,
+                    cache_write_12h_tokens: input * 2.5,
                     completion_tokens: output,
                 },
                 context: 1_050_000,
@@ -844,7 +847,7 @@ describe('OpenAiResponsesChatProvider.complete non-stream output', () => {
             },
         });
 
-        await withTestActor(() =>
+        const result = await withTestActor(() =>
             provider.complete({
                 model: 'gpt-6-luna',
                 messages: [{ role: 'user', content: 'hi' }],
@@ -867,6 +870,115 @@ describe('OpenAiResponsesChatProvider.complete non-stream output', () => {
             cached_tokens: 1000 * Number(luna.costs.cached_tokens),
             cache_write_tokens: 3000 * Number(luna.costs.cache_write_tokens),
         });
+        // Writes without a per-lifetime breakdown are OpenAI's default 30m
+        // entries, and the neutral breakdown says so.
+        expect((result as { usageDetails: unknown }).usageDetails).toEqual({
+            inputTokens: 1000,
+            outputTokens: 20,
+            cacheReadTokens: 1000,
+            cacheWrite30mTokens: 3000,
+        });
+    });
+
+    it('bills 12h cache writes at 2.5x input and the other writes at 1.25x', async () => {
+        const luna = OPEN_AI_MODELS.find((m) => m.id === 'gpt-6-luna')!;
+        const { provider } = makeProvider();
+        // One request can write both lifetimes: an explicit 12h breakpoint
+        // plus the implicit 30m one OpenAI adds at the end of the prompt.
+        responsesCreateMock.mockResolvedValueOnce({
+            output: [{ role: 'assistant' }],
+            output_text: 'ok',
+            usage: {
+                input_tokens: 6026,
+                output_tokens: 5,
+                input_tokens_details: {
+                    cached_tokens: 0,
+                    cache_write_tokens: 6023,
+                    cache_write_tokens_details: {
+                        ttl_12h_tokens: 6012,
+                        ttl_30m_tokens: 11,
+                    },
+                },
+            },
+        });
+
+        const result = await withTestActor(() =>
+            provider.complete({
+                model: 'gpt-6-luna',
+                messages: [{ role: 'user', content: 'hi' }],
+                prompt_cache_options: { ttl: '12h' },
+            }),
+        );
+
+        const [usage, , , overrides] = recordSpy.mock.calls[0]!;
+        expect(usage).toEqual({
+            prompt_tokens: 3,
+            completion_tokens: 5,
+            cached_tokens: 0,
+            cache_write_tokens: 11,
+            cache_write_12h_tokens: 6012,
+        });
+        expect(luna.costs.cache_write_12h_tokens).toBe(
+            Number(luna.costs.prompt_tokens) * 2.5,
+        );
+        expect(overrides).toEqual({
+            prompt_tokens: 3 * Number(luna.costs.prompt_tokens),
+            completion_tokens: 5 * Number(luna.costs.completion_tokens),
+            cached_tokens: 0,
+            cache_write_tokens: 11 * Number(luna.costs.cache_write_tokens),
+            cache_write_12h_tokens:
+                6012 * Number(luna.costs.cache_write_12h_tokens),
+        });
+        expect((result as { usageDetails: unknown }).usageDetails).toEqual({
+            inputTokens: 3,
+            outputTokens: 5,
+            cacheWrite30mTokens: 11,
+            cacheWrite12hTokens: 6012,
+        });
+    });
+
+    it('forwards prompt_cache_options and the wire spelling of prompt_cache_retention', async () => {
+        const { provider } = makeProvider();
+        responsesCreateMock.mockResolvedValueOnce({
+            output: [{ role: 'assistant' }],
+            output_text: 'ok',
+            usage: { input_tokens: 1, output_tokens: 1 },
+        });
+
+        await withTestActor(() =>
+            provider.complete({
+                model: 'gpt-6-luna',
+                messages: [{ role: 'user', content: 'hi' }],
+                prompt_cache_retention: 'in-memory',
+                prompt_cache_options: {
+                    mode: 'explicit',
+                    ttl: '12h',
+                    comparison_response_id: 'resp_1',
+                } as never,
+            }),
+        );
+
+        const [args] = responsesCreateMock.mock.calls[0]!;
+        expect(args.prompt_cache_retention).toBe('in_memory');
+        expect(args.prompt_cache_options).toEqual({
+            mode: 'explicit',
+            ttl: '12h',
+        });
+    });
+
+    it('rejects a cache lifetime OpenAI does not offer before calling upstream', async () => {
+        const { provider } = makeProvider();
+
+        await expect(
+            withTestActor(() =>
+                provider.complete({
+                    model: 'gpt-6-luna',
+                    messages: [{ role: 'user', content: 'hi' }],
+                    prompt_cache_options: { ttl: '2h' } as never,
+                }),
+            ),
+        ).rejects.toMatchObject({ statusCode: 400 });
+        expect(responsesCreateMock).not.toHaveBeenCalled();
     });
 
     it.each([
@@ -1068,6 +1180,69 @@ describe('OpenAiResponsesChatProvider.complete streaming', () => {
         });
     });
 
+    it('labels streamed cache writes by lifetime on the final usage chunk', async () => {
+        const luna = OPEN_AI_MODELS.find((m) => m.id === 'gpt-6-luna')!;
+        const { provider } = makeProvider();
+        responsesCreateMock.mockReturnValueOnce(
+            asAsyncIterable([
+                { type: 'response.output_text.delta', delta: 'ok' },
+                {
+                    type: 'response.completed',
+                    response: {
+                        usage: {
+                            input_tokens: 6026,
+                            output_tokens: 5,
+                            input_tokens_details: {
+                                cached_tokens: 0,
+                                cache_write_tokens: 6023,
+                                cache_write_tokens_details: {
+                                    ttl_12h_tokens: 6012,
+                                    ttl_30m_tokens: 11,
+                                },
+                            },
+                        },
+                    },
+                },
+            ]),
+        );
+
+        const result = await withTestActor(() =>
+            provider.complete({
+                model: 'gpt-6-luna',
+                messages: [{ role: 'user', content: 'say ok' }],
+                stream: true,
+                prompt_cache_options: { ttl: '12h' },
+            }),
+        );
+        const harness = makeCapturingChatStream();
+        await (
+            result as {
+                init_chat_stream: (p: { chatStream: unknown }) => Promise<void>;
+            }
+        ).init_chat_stream({ chatStream: harness.chatStream });
+
+        const usageEvent = harness.events().find((e) => e.type === 'usage');
+        expect(usageEvent?.usage).toEqual({
+            prompt_tokens: 3,
+            completion_tokens: 5,
+            cached_tokens: 0,
+            cache_write_tokens: 11,
+            cache_write_12h_tokens: 6012,
+        });
+        expect(usageEvent?.usageDetails).toEqual({
+            inputTokens: 3,
+            outputTokens: 5,
+            cacheWrite30mTokens: 11,
+            cacheWrite12hTokens: 6012,
+        });
+        const [, , , overrides] = recordSpy.mock.calls[0]!;
+        expect(overrides).toMatchObject({
+            cache_write_tokens: 11 * Number(luna.costs.cache_write_tokens),
+            cache_write_12h_tokens:
+                6012 * Number(luna.costs.cache_write_12h_tokens),
+        });
+    });
+
     it('emits a tool_use block when response.output_item.done arrives with a function_call', async () => {
         const { provider } = makeProvider();
         responsesCreateMock.mockReturnValueOnce(
@@ -1407,3 +1582,117 @@ describe('OpenAiResponsesChatProvider.complete error mapping', () => {
         expect(recordSpy).not.toHaveBeenCalled();
     });
 });
+
+describe('ChatCompletionDriver OpenAI billing', () => {
+    const makeBillingUser = async () => {
+        const user = await server.stores.user.create({
+            username: `billing-${uuidv4().slice(0, 8)}`,
+            uuid: uuidv4(),
+            password: null,
+            email: null,
+            free_storage: 1000000,
+            requires_email_confirmation: false,
+        });
+        return { user: { ...user, email_confirmed: true } } as Actor;
+    };
+    const makeBillingDriver = async () => {
+        const driver = new ChatCompletionDriver(
+            {
+                providers: {
+                    ollama: { enabled: false },
+                    'openai-completion': { apiKey: 'test-key' },
+                },
+            } as never,
+            server.clients,
+            server.stores,
+            server.services,
+        );
+        await driver.onServerStart();
+        return driver;
+    };
+    it('meters an empty Responses completion before returning its error', async () => {
+        const actor = await makeBillingUser();
+        const driver = await makeBillingDriver();
+        const before = await server.services.metering.getRemainingUsage(actor);
+        responsesCreateMock.mockResolvedValueOnce({
+            status: 'incomplete',
+            incomplete_details: { reason: 'max_output_tokens' },
+            output: [],
+            output_text: '',
+            usage: {
+                input_tokens: 1200,
+                output_tokens: 2000,
+                output_tokens_details: { reasoning_tokens: 2000 },
+            },
+        });
+        await expect(
+            withTestActor(
+                () =>
+                    driver.complete({
+                        model: 'gpt-5.4-mini',
+                        provider: 'openai-responses',
+                        messages: [{ role: 'user', content: 'hello' }],
+                        max_tokens: 1,
+                        fallback: false,
+                    }),
+                actor,
+            ),
+        ).rejects.toMatchObject({ statusCode: 400 });
+        expect(responsesCreateMock).toHaveBeenCalledTimes(1);
+        expect(recordSpy).toHaveBeenCalledTimes(1);
+        expect(recordSpy.mock.calls[0][0]).toMatchObject({
+            prompt_tokens: 1200,
+            completion_tokens: 2000,
+        });
+        await Promise.all(recordSpy.mock.results.map((result) => result.value));
+        expect(
+            await server.services.metering.getRemainingUsage(actor),
+        ).toBeLessThan(before);
+    });
+    it('prices a raw priority tier with the same rate card as fast service', async () => {
+        const actor = await makeBillingUser();
+        const driver = await makeBillingDriver();
+        const charges: number[] = [];
+        for (const extra of [
+            {},
+            { service_tier: 'priority' },
+            { serviceSpeed: 'fast' },
+        ]) {
+            responsesCreateMock.mockResolvedValueOnce({
+                output: [],
+                output_text: 'hi',
+                service_tier: Object.keys(extra).length
+                    ? 'priority'
+                    : 'default',
+                usage: { input_tokens: 100, output_tokens: 100 },
+            });
+            const before =
+                await server.services.metering.getRemainingUsage(actor);
+            await withTestActor(
+                () =>
+                    driver.complete({
+                        model: 'gpt-6.1-terra',
+                        provider: 'openai-responses',
+                        messages: [{ role: 'user', content: 'hello' }],
+                        max_tokens: 100,
+                        fallback: false,
+                        ...extra,
+                    } as never),
+                actor,
+            );
+            await Promise.all(
+                recordSpy.mock.results.map((result) => result.value),
+            );
+            charges.push(
+                before -
+                    (await server.services.metering.getRemainingUsage(actor)),
+            );
+        }
+        expect(responsesCreateMock.mock.calls[1][0].service_tier).toBe(
+            'priority',
+        );
+        expect(charges[0]).toBeGreaterThan(0);
+        expect(charges[1]).toBe(charges[2]);
+        expect(charges[2]).toBe(charges[0] * 2);
+    });
+});

src/backend/drivers/ai-chat/providers/openai/OpenAiChatResponsesProvider.ts

@@ -19,6 +19,7 @@
 
 import { OpenAI } from 'openai';
 import { ResponseCreateParams } from 'openai/resources/responses/responses.mjs';
+import { servedServiceSpeed } from '../../utils/serviceSpeed.js';
 import { Context } from '../../../../core/context.js';
 import type { MeteringService } from '../../../../services/metering/MeteringService.js';
 import type {
@@ -32,6 +33,8 @@ import * as OpenAiUtil from '../../utils/OpenAIUtil.js';
 import {
     clampReasoningEffort,
     openAICompatParams,
+    promptCacheOptionsToWire,
+    promptCacheRetentionToWire,
     rejectStatefulResponsesFields,
 } from '../../utils/openaiParams.js';
 import { responseSamplingParams } from '../../utils/responseSampling.js';
@@ -132,37 +135,42 @@ export class OpenAiResponsesChatProvider implements IChatProvider {
         return rate ? { extraCost: rate } : {};
     }
 
-    async complete({
-        messages,
-        model,
-        max_tokens,
-        moderation,
-        tools,
-        tool_choice,
-        parallel_tool_calls,
-        include,
-        conversation,
-        compaction,
-        context_management,
-        previous_response_id,
-        instructions,
-        metadata,
-        prompt,
-        prompt_cache_key,
-        prompt_cache_retention,
-        store,
-        top_p,
-        truncation,
-        background,
-        service_tier,
-        verbosity,
-        stream,
-        reasoning,
-        reasoning_effort,
-        temperature,
-        text,
-        outputFormat,
-    }: ICompleteArguments): ReturnType<IChatProvider['complete']> {
+    async complete(
+        {
+            messages,
+            model,
+            max_tokens,
+            moderation,
+            tools,
+            tool_choice,
+            parallel_tool_calls,
+            include,
+            conversation,
+            compaction,
+            context_management,
+            previous_response_id,
+            instructions,
+            metadata,
+            prompt,
+            prompt_cache_key,
+            prompt_cache_retention,
+            prompt_cache_options,
+            store,
+            top_p,
+            truncation,
+            background,
+            service_tier,
+            serviceSpeed: requestedServiceSpeed,
+            verbosity,
+            stream,
+            reasoning,
+            reasoning_effort,
+            temperature,
+            text,
+            outputFormat,
+        }: ICompleteArguments,
+        resolved?: IChatModel,
+    ): ReturnType<IChatProvider['complete']> {
         // Validate messages
         if (!Array.isArray(messages)) {
             throw new HttpError(400, '`messages` must be an array', {
@@ -180,12 +188,13 @@ export class OpenAiResponsesChatProvider implements IChatProvider {
         model = model ?? this.#defaultModel;
 
         const modelUsed =
-            this.models({ no_restrictions: true }).find((m) =>
+            resolved ??
+            (this.models({ no_restrictions: true }).find((m) =>
                 [m.id, ...(m.aliases || [])].includes(model),
             ) ||
-            this.models({ no_restrictions: true }).find(
-                (m) => m.id === this.getDefaultModel(),
-            )!;
+                this.models({ no_restrictions: true }).find(
+                    (m) => m.id === this.getDefaultModel(),
+                )!);
 
         // messages.unshift({
         //     role: 'system',
@@ -195,6 +204,10 @@ export class OpenAiResponsesChatProvider implements IChatProvider {
         const userIdentifier = upstreamUserIdentifier(actor);
         // Cache key defaults to the actor identifier; see upstreamUserIdentifier.
         const cacheKey = prompt_cache_key ?? userIdentifier;
+        const cacheRetention = promptCacheRetentionToWire(
+            prompt_cache_retention,
+        );
+        const cacheOptions = promptCacheOptionsToWire(prompt_cache_options);
 
         if (tools) {
             // Unravel tools to OpenAI Responses API format
@@ -288,8 +301,11 @@ export class OpenAiResponsesChatProvider implements IChatProvider {
             ...(instructions !== undefined ? { instructions } : {}),
             ...(metadata !== undefined ? { metadata } : {}),
             ...(cacheKey !== undefined ? { prompt_cache_key: cacheKey } : {}),
-            ...(prompt_cache_retention !== undefined
-                ? { prompt_cache_retention }
+            ...(cacheRetention !== undefined
+                ? { prompt_cache_retention: cacheRetention }
+                : {}),
+            ...(cacheOptions !== undefined
+                ? { prompt_cache_options: cacheOptions }
                 : {}),
             ...(store !== undefined ? { store } : {}),
             ...(max_tokens !== undefined
@@ -310,24 +326,18 @@ export class OpenAiResponsesChatProvider implements IChatProvider {
             { signal: Context.get('upstreamSignal') },
         );
         return OpenAiUtil.handle_completion_output_responses_api({
-            usage_calculator: ({ usage, webSearchCalls, setUsageCosts }) => {
-                const cachedTokens =
-                    (usage as any).input_tokens_details?.cached_tokens ?? 0;
-                // GPT-5.6 and later bill cache writes at 1.25x input. They're
-                // reported inside `input_tokens`, like cached reads.
-                const cacheWriteTokens =
-                    (usage as any).input_tokens_details?.cache_write_tokens ??
-                    0;
+            usage_calculator: ({
+                usage,
+                service_tier,
+                webSearchCalls,
+                setUsageCosts,
+                setUsageDetails,
+            }) => {
+                // GPT-5.6 and later report cache writes inside `input_tokens`,
+                // like cached reads, split by lifetime (30m and 12h entries
+                // cost 1.25x and 2.5x input to write).
                 const trackedUsage: Record<string, number> = {
-                    prompt_tokens:
-                        ((usage as any).input_tokens ?? 0) -
-                        cachedTokens -
-                        cacheWriteTokens,
-                    completion_tokens: (usage as any).output_tokens ?? 0,
-                    cached_tokens: cachedTokens,
-                    ...(cacheWriteTokens
-                        ? { cache_write_tokens: cacheWriteTokens }
-                        : {}),
+                    ...OpenAiUtil.splitCachedPrompt(usage),
                     ...(webSearchCalls
                         ? { web_search_calls: webSearchCalls }
                         : {}),
@@ -344,18 +354,31 @@ export class OpenAiResponsesChatProvider implements IChatProvider {
                     // model is a reasoning model, not a static per-model
                     // cost-table entry — the model's rates would otherwise
                     // price it (wrongly) at the input/output token rate.
-                    webSearchCalls
-                        ? {
-                              costOverrides: {
-                                  web_search_calls:
-                                      webSearchCalls *
-                                      (webSearchCallRate(tools, modelUsed.id) ??
-                                          0),
-                              },
-                          }
-                        : {},
+                    {
+                        serviceSpeed: servedServiceSpeed({ service_tier }),
+                        ...(webSearchCalls
+                            ? {
+                                  costOverrides: {
+                                      web_search_calls:
+                                          webSearchCalls *
+                                          (webSearchCallRate(
+                                              tools,
+                                              modelUsed.id,
+                                          ) ?? 0),
+                                  },
+                              }
+                            : {}),
+                    },
                 );
                 setUsageCosts?.(metered.costs);
+                setUsageDetails?.({
+                    ...(requestedServiceSpeed !== undefined
+                        ? { serviceSpeed: servedServiceSpeed({ service_tier }) }
+                        : {}),
+                    ...OpenAiUtil.usageDetailsFromTrackedUsage(metered.usage, {
+                        writeTtl: '30m',
+                    })!,
+                });
                 return metered.usage;
             },
             stream,

src/backend/drivers/ai-chat/providers/openai/models.ts

@@ -23,6 +23,8 @@ import type { IChatModel } from '../../types.js';
 
 // Prompts over 272K input tokens are billed at 2x input (cached reads and
 // cache writes included) and 1.5x output for the full request.
+// GPT-5.6 and later bill cache writes by the lifetime requested: 1.25x input
+// for the default 30m entries, 2.5x for 12h entries.
 const GPT_LONG_CONTEXT_PRICING = {
     threshold: 272_000,
     input_multiplier: 2,
@@ -44,11 +46,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 100,
             cached_tokens: 5,
             cache_write_tokens: 100 * 1.25,
+            cache_write_12h_tokens: 100 * 2.5,
             completion_tokens: 500,
         },
         long_context_pricing: GPT_LONG_CONTEXT_PRICING,
@@ -69,11 +73,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2, ultrafast: 6 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200,
             cached_tokens: 10,
             cache_write_tokens: 200 * 1.25,
+            cache_write_12h_tokens: 200 * 2.5,
             completion_tokens: 1000,
         },
         long_context_pricing: GPT_LONG_CONTEXT_PRICING,
@@ -94,11 +100,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200,
             cached_tokens: 20,
             cache_write_tokens: 200 * 1.25,
+            cache_write_12h_tokens: 200 * 2.5,
             completion_tokens: 1000,
         },
         long_context_pricing: GPT_LONG_CONTEXT_PRICING,
@@ -119,11 +127,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 10,
             cached_tokens: 1,
             cache_write_tokens: 10 * 1.25,
+            cache_write_12h_tokens: 10 * 2.5,
             completion_tokens: 50,
         },
         long_context_pricing: GPT_LONG_CONTEXT_PRICING,
@@ -144,11 +154,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2, ultrafast: 6 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 1000,
             cached_tokens: 100,
             cache_write_tokens: 1000 * 1.25,
+            cache_write_12h_tokens: 1000 * 2.5,
             completion_tokens: 5000,
         },
         long_context_pricing: GPT_LONG_CONTEXT_PRICING,
@@ -169,11 +181,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
         // OpenAI's promotional pricing, guaranteed only through 2026-11-21.
+        serviceSpeedRates: { fast: 2 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 400,
             cached_tokens: 40,
             cache_write_tokens: 400 * 1.25,
+            cache_write_12h_tokens: 400 * 2.5,
             completion_tokens: 2000,
         },
         long_context_pricing: GPT_LONG_CONTEXT_PRICING,
@@ -193,11 +207,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200,
             cached_tokens: 20,
             cache_write_tokens: 200 * 1.25,
+            cache_write_12h_tokens: 200 * 2.5,
             completion_tokens: 1200,
         },
         long_context_pricing: GPT_LONG_CONTEXT_PRICING,
@@ -217,11 +233,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: { fast: 2 },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 20,
             cached_tokens: 2,
             cache_write_tokens: 20 * 1.25,
+            cache_write_12h_tokens: 20 * 2.5,
             completion_tokens: 120,
         },
         long_context_pricing: GPT_LONG_CONTEXT_PRICING,
@@ -241,6 +259,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 1250,
+                cached_tokens: 125,
+                completion_tokens: 7500,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 500,
@@ -285,6 +310,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 500,
+                cached_tokens: 50,
+                completion_tokens: 3000,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 250,
@@ -328,6 +360,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 150,
+                cached_tokens: 15,
+                completion_tokens: 900,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 75,
@@ -415,6 +454,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 350,
+                cached_tokens: 35,
+                completion_tokens: 2800,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 175,
@@ -436,6 +482,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 250,
+                cached_tokens: 25,
+                completion_tokens: 2000,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 125,
@@ -457,6 +510,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 425,
+                cached_tokens: 212.5,
+                completion_tokens: 1700,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 250,
@@ -480,6 +540,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 25,
+                cached_tokens: 12.5,
+                completion_tokens: 100,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 15,
@@ -499,6 +566,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 350,
+                cached_tokens: 87.5,
+                completion_tokens: 1400,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 200,
@@ -520,6 +594,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 70,
+                cached_tokens: 17.5,
+                completion_tokens: 280,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 40,
@@ -561,6 +642,13 @@ export const OPEN_AI_MODELS: IChatModel[] = [
         costs_currency: 'usd-cents',
         input_cost_key: 'prompt_tokens',
         output_cost_key: 'completion_tokens',
+        serviceSpeedRates: {
+            fast: {
+                prompt_tokens: 425,
+                cached_tokens: 212.5,
+                completion_tokens: 1700,
+            },
+        },
         costs: {
             tokens: 1_000_000,
             prompt_tokens: 250,

src/backend/drivers/ai-chat/providers/openrouter/OpenRouterProvider.test.ts

@@ -20,15 +20,14 @@
 /**
  * Offline unit tests for OpenRouterProvider.
  *
- * Boots a real PuterServer (in-memory sqlite + dynamo + s3 + mock
- * redis) and constructs OpenRouterProvider directly against the live
- * wired `MeteringService` so the recording side is exercised end-to-
- * end. OpenRouter is OpenAI-compatible, so the OpenAI SDK is mocked
- * at the module boundary; the model catalog is fetched via `axios`
- * which is mocked at its module boundary too. Both are the real
- * network egress points.
- * The companion integration test (OpenRouterProvider.integration.test.ts)
- * exercises the real OpenRouter endpoint.
+ * Boots a real PuterServer (in-memory sqlite + dynamo + s3 + mock redis) and
+ * constructs OpenRouterProvider directly against the live wired
+ * `MeteringService` so the recording side is exercised end-to- end. OpenRouter
+ * is OpenAI-compatible, so the OpenAI SDK is mocked at the module boundary; the
+ * model catalog is fetched via `axios` which is mocked at its module boundary
+ * too. Both are the real network egress points. The companion integration test
+ * (OpenRouterProvider.integration.test.ts) exercises the real OpenRouter
+ * endpoint.
  */
 
 import { Writable } from 'node:stream';
@@ -300,16 +299,20 @@ describe('OpenRouterProvider model catalog', () => {
     it('coerces string prices and normalizes conditional tiers', async () => {
         const { provider } = makeProvider();
         const models = await provider.models();
-        const sol = models.find((m) => m.id === 'openrouter:openai/gpt-6.1-sol')!;
+        const sol = models.find(
+            (m) => m.id === 'openrouter:openai/gpt-6.1-sol',
+        )!;
         expect(sol.costs).toEqual({
             tokens: 1_000_000,
             prompt: 200,
             completion: 1000,
         });
-        expect(sol.pricingOverrides).toEqual([{
-            minPromptTokens: 272000,
-            costs: { prompt: 400, completion: 1500 },
-        }]);
+        expect(sol.pricingOverrides).toEqual([
+            {
+                minPromptTokens: 272000,
+                costs: { prompt: 400, completion: 1500 },
+            },
+        ]);
     });
 
     it('caches the coerced model list after the first axios round-trip', async () => {
@@ -368,9 +371,12 @@ describe('OpenRouterProvider model catalog', () => {
 
     it('does not reinterpret catalog-added timestamps as release dates', async () => {
         const { provider } = makeProvider();
-        expect((await provider.models()).every(model => model.release_date === undefined)).toBe(true);
+        expect(
+            (await provider.models()).every(
+                (model) => model.release_date === undefined,
+            ),
+        ).toBe(true);
     });
-
 });
 
 // ── Disallowed model gate ───────────────────────────────────────────
@@ -868,11 +874,14 @@ describe('OpenRouterProvider billed cost through the driver', () => {
             event.factor = factor;
         };
         server.clients.event.on('ai.cost.factor.*', listener as never);
-        return () => server.clients.event.off('ai.cost.factor.*', listener as never);
+        return () =>
+            server.clients.event.off('ai.cost.factor.*', listener as never);
     };
 
-    /** µ¢ the ledger was handed for every usage recorded so far. */
-    const ledgerTotal = (spy: MockInstance<MeteringService['batchIncrementUsages']>) =>
+    /** Μ¢ the ledger was handed for every usage recorded so far. */
+    const ledgerTotal = (
+        spy: MockInstance<MeteringService['batchIncrementUsages']>,
+    ) =>
         spy.mock.calls
             .flatMap(([, usages]) => usages)
             .reduce((total, usage) => total + (usage.costOverride ?? 0), 0);
@@ -928,7 +937,10 @@ describe('OpenRouterProvider billed cost through the driver', () => {
     it('reports what a billed completion was charged, after the cost factor', async () => {
         const driver = await makeDriver();
         const stopFactor = withCostFactor(1.6);
-        const recorded = vi.spyOn(server.services.metering, 'batchIncrementUsages');
+        const recorded = vi.spyOn(
+            server.services.metering,
+            'batchIncrementUsages',
+        );
         createMock.mockResolvedValueOnce({
             choices: [
                 {
@@ -1023,7 +1035,10 @@ describe('OpenRouterProvider billed cost through the driver', () => {
     it('ends a stream with what it was charged at the catalog rates, after the cost factor', async () => {
         const driver = await makeDriver();
         const stopFactor = withCostFactor(1.6);
-        const recorded = vi.spyOn(server.services.metering, 'batchIncrementUsages');
+        const recorded = vi.spyOn(
+            server.services.metering,
+            'batchIncrementUsages',
+        );
         createMock.mockReturnValueOnce(
             asAsyncIterable([
                 { choices: [{ delta: { content: 'hello' } }] },
@@ -1126,31 +1141,180 @@ describe('OpenRouterProvider.checkModeration', () => {
     });
 });
 
-
 describe('OpenRouter catalog refresh validation', () => {
     it('keeps missing model fields and prices unknown and blocks unpriced inference', async () => {
-        axiosRequestMock.mockResolvedValue({ data: { data: [{ id: 'fixture/model', name: 'Fixture' }] } });
+        axiosRequestMock.mockResolvedValue({
+            data: { data: [{ id: 'fixture/model', name: 'Fixture' }] },
+        });
         const { provider } = makeProvider();
         const [model] = await provider.models();
         expect(model.costs).toEqual({ tokens: 1_000_000 });
         expect(model.context).toBeUndefined();
         expect(model.max_tokens).toBe(0);
-        await expect(withTestActor(() => provider.complete({ model: 'openrouter:fixture/model', messages: [] })))
-            .rejects.toMatchObject({ legacyCode: 'model_pricing_unavailable' });
+        await expect(
+            withTestActor(() =>
+                provider.complete({
+                    model: 'openrouter:fixture/model',
+                    messages: [],
+                }),
+            ),
+        ).rejects.toMatchObject({ legacyCode: 'model_pricing_unavailable' });
         expect(createMock).not.toHaveBeenCalled();
     });
 
-    it.each(['malformed', 'failed', 'ambiguous conditional price'])('retains last-good data after a %s refresh', async failure => {
-        vi.useFakeTimers({ toFake: ['Date'] });
-        vi.spyOn(console, 'warn').mockImplementation(() => {});
+    it.each(['malformed', 'failed', 'ambiguous conditional price'])(
+        'retains last-good data after a %s refresh',
+        async (failure) => {
+            vi.useFakeTimers({ toFake: ['Date'] });
+            vi.spyOn(console, 'warn').mockImplementation(() => {});
+            const { provider } = makeProvider();
+            const good = await provider.models();
+            vi.advanceTimersByTime(15 * 60 * 1000 + 1);
+            if (failure === 'failed')
+                axiosRequestMock.mockRejectedValueOnce(
+                    new Error('unavailable'),
+                );
+            else if (failure === 'malformed')
+                axiosRequestMock.mockResolvedValueOnce({ data: {} });
+            else
+                axiosRequestMock.mockResolvedValueOnce({
+                    data: {
+                        data: [
+                            {
+                                ...SAMPLE_API_MODELS[0],
+                                pricing: {
+                                    prompt: '0.000002',
+                                    overrides: [
+                                        { min_prompt_tokens: 10, prompt: '' },
+                                    ],
+                                },
+                            },
+                        ],
+                    },
+                });
+            expect(await provider.models()).toBe(good);
+        },
+    );
+});
+
+describe('OpenRouter service speed offerings', () => {
+    it('loads and caches tier prices while reserving for endpoint and context differences', async () => {
         const { provider } = makeProvider();
-        const good = await provider.models();
-        vi.advanceTimersByTime(15 * 60 * 1000 + 1);
-        if (failure === 'failed') axiosRequestMock.mockRejectedValueOnce(new Error('unavailable'));
-        else if (failure === 'malformed') axiosRequestMock.mockResolvedValueOnce({ data: {} });
-        else axiosRequestMock.mockResolvedValueOnce({ data: { data: [{ ...SAMPLE_API_MODELS[0], pricing: {
-            prompt: '0.000002', overrides: [{ min_prompt_tokens: 10, prompt: '' }],
-        } }] } });
-        expect(await provider.models()).toBe(good);
+        const base = {
+            ...(await provider.models())[0],
+            provider: 'openrouter',
+        };
+        axiosRequestMock.mockClear();
+        axiosRequestMock.mockResolvedValueOnce({
+            data: {
+                data: {
+                    endpoints: [
+                        {
+                            service_tier: 'priority',
+                            pricing: {
+                                prompt: '0.000004',
+                                completion: '0.00002',
+                                input_cache_read: '0.0000002',
+                            },
+                        },
+                        {
+                            service_tier: 'priority',
+                            pricing: {
+                                prompt: '0.000005',
+                                completion: '0.00001',
+                            },
+                        },
+                        {
+                            service_tier: 'ultrafast',
+                            pricing: {
+                                prompt: '0.000012',
+                                completion: '0.00006',
+                                overrides: [
+                                    {
+                                        min_prompt_tokens: 272000,
+                                        prompt: '0.000024',
+                                        completion: '0.00009',
+                                    },
+                                ],
+                            },
+                        },
+                        {
+                            service_tier: 'priority',
+                            pricing: { prompt: 'invalid' },
+                        },
+                    ],
+                },
+            },
+        });
+        const offers = await provider.serviceSpeedModels(base);
+        expect(offers.fast?.costs).toMatchObject({
+            prompt: 500,
+            completion: 2000,
+            input_cache_read: 20,
+        });
+        expect(offers.ultrafast?.costs).toMatchObject({
+            prompt: 2400,
+            completion: 9000,
+        });
+        expect(await provider.serviceSpeedModels(base)).toBe(offers);
+        expect(axiosRequestMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('uses standard when the tier catalog cannot be fetched', async () => {
+        const { provider } = makeProvider();
+        const base = {
+            ...(await provider.models())[0],
+            provider: 'openrouter',
+        };
+        axiosRequestMock.mockRejectedValueOnce(new Error('Unavailable'));
+        expect(await provider.serviceSpeedModels(base)).toEqual({});
+    });
+});
+
+describe('OpenRouter speed billing', () => {
+    it('requires an authoritative bill instead of charging the reservation ceiling', async () => {
+        const { selectServiceSpeed } =
+            await import('../../utils/serviceSpeed.js');
+        const { provider } = makeProvider();
+        const base = {
+            ...(await provider.models())[0],
+            provider: 'openrouter',
+        };
+        const selected = selectServiceSpeed(
+            base,
+            {
+                model: base.id,
+                messages: [{ role: 'user', content: 'Hello' }],
+                serviceSpeed: 'fast',
+            },
+            () => undefined,
+            {
+                fast: {
+                    ...base,
+                    costs: { ...base.costs, prompt: 500, completion: 2000 },
+                },
+            },
+        );
+        const completion = {
+            choices: [
+                {
+                    index: 0,
+                    message: { role: 'assistant', content: 'OK' },
+                    finish_reason: 'stop',
+                },
+            ],
+            usage: { prompt_tokens: 10, completion_tokens: 1 },
+        };
+        createMock.mockResolvedValueOnce({
+            ...completion,
+            service_tier: 'priority',
+            usage: { ...completion.usage, cost: undefined },
+        });
+        await expect(
+            withTestActor(() =>
+                provider.complete(selected.args, selected.model),
+            ),
+        ).rejects.toMatchObject({ legacyCode: 'model_pricing_unavailable' });
+        expect(recordSpy).not.toHaveBeenCalled();
     });
 });

src/backend/drivers/ai-chat/providers/openrouter/OpenRouterProvider.ts

@@ -22,8 +22,10 @@ import { OpenAI } from 'openai';
 import { HttpError, isHttpError } from '../../../../core/http/HttpError.js';
 import { UpstreamResponseError } from '../../../util/upstreamErrors.js';
 import type { MeteringService } from '../../../../services/metering/MeteringService.js';
-import type { IChatModel, ICompleteArguments } from '../../types.js';
+import type { IChatModel, ICompleteArguments, ModelCost } from '../../types.js';
+import { BoundedTtlMap } from '../../../../util/boundedTtlMap.js';
 import { cachedRemoteCatalog } from '../../utils/cachedRemoteCatalog.js';
+import { servedServiceSpeed } from '../../utils/serviceSpeed.js';
 import { catalogPrice } from '../../utils/pricing.js';
 import { mapOpenRouterPricing } from './pricing.js';
 import { sdkClientOptions } from '../../utils/sdkClient.js';
@@ -64,6 +66,75 @@ const isPolicyBlock = (err: unknown): boolean => {
 export class OpenRouterProvider extends OpenAICompatProvider {
     #apiBaseUrl: string;
 
+    #speedCatalogs = new BoundedTtlMap<
+        string,
+        () => Promise<Partial<Record<'fast' | 'ultrafast', IChatModel>>>
+    >({ maxEntries: 256 });
+
+    async serviceSpeedModels(model: IChatModel) {
+        let load = this.#speedCatalogs.get(model.id);
+        if (!load) {
+            load = cachedRemoteCatalog({
+                name: 'OpenRouter speed catalog',
+                fallback: {} as Partial<
+                    Record<'fast' | 'ultrafast', IChatModel>
+                >,
+                fetch: async (signal) => {
+                    const id = model.id.replace(/^openrouter:/, '');
+                    const response = await axios.request({
+                        url: `${this.#apiBaseUrl}/models/${id}/endpoints`,
+                        method: 'GET',
+                        signal,
+                        maxContentLength: 2 * 1024 * 1024,
+                    });
+                    const offers: Partial<
+                        Record<'fast' | 'ultrafast', IChatModel>
+                    > = {};
+                    for (const endpoint of response.data?.data?.endpoints ??
+                        []) {
+                        const speed =
+                            endpoint.service_tier === 'ultrafast'
+                                ? 'ultrafast'
+                                : ['priority', 'fast'].includes(
+                                        endpoint.service_tier,
+                                    )
+                                  ? 'fast'
+                                  : undefined;
+                        if (!speed || !endpoint.pricing) continue;
+                        const pricing = mapOpenRouterPricing(endpoint.pricing);
+                        if (
+                            pricing.costs.prompt === undefined ||
+                            pricing.costs.completion === undefined
+                        )
+                            continue;
+                        // Reserve for the most expensive eligible endpoint and context tier.
+                        const costs: ModelCost = {
+                            ...offers[speed]?.costs,
+                            tokens: model.costs.tokens,
+                        };
+                        for (const rates of [
+                            pricing.costs,
+                            ...pricing.overrides.map(
+                                (override) => override.costs,
+                            ),
+                        ]) {
+                            for (const [key, value] of Object.entries(rates))
+                                costs[key] = Math.max(costs[key] ?? 0, value);
+                        }
+                        offers[speed] = {
+                            ...model,
+                            costs,
+                            pricingOverrides: [],
+                        };
+                    }
+                    return offers;
+                },
+            });
+            this.#speedCatalogs.set(model.id, load);
+        }
+        return load();
+    }
+
     constructor(config: ChatProviderConfig, meteringService: MeteringService) {
         const apiBaseUrl = config.apiBaseUrl || 'https://openrouter.ai/api/v1';
         super(meteringService, {
@@ -202,8 +273,17 @@ export class OpenRouterProvider extends OpenAICompatProvider {
         return { ...params, usage: { include: true } };
     }
 
-    protected override meteredUsage(source: UsageSource) {
+    protected override meteredUsage(source: UsageSource, model: IChatModel) {
         const usage = source.usage as OpenrouterUsage;
+        if (
+            model.serviceSpeedPricing &&
+            servedServiceSpeed(source) !== 'standard' &&
+            catalogPrice(usage.cost) === undefined
+        ) {
+            throw new HttpError(503, 'Service tier billing is unavailable', {
+                legacyCode: 'model_pricing_unavailable',
+            });
+        }
         return {
             usage: {
                 prompt: