@intentic/sandbox-contract 1.224.0 → 1.225.0

package/src/schemas.test.ts

@@ -3,8 +3,8 @@ import { CapabilitiesListSchema, IpsecVpnConfigSchema, SandboxSettingsSchema } f
 
 /* The settings shape spans a version seam that really moves: the browser ships with the platform, the daemon
  * ships inside the user's sandbox image, so a web build routinely parses a payload from an OLDER daemon. These
- * tests pin the property that makes that survivable — an absent key is that flag's default, not a parse
- * failure — because failing instead reaches the user as a settings page whose switches silently do nothing. */
+ * tests pin the property that makes that survivable: an absent key is that flag's default, not a parse
+ * failure, because failing instead reaches the user as a settings page whose switches silently do nothing. */
 
 test("a payload from a build that predates a toggle parses, with the new toggle at its default", () => {
     // What a daemon built before the output-cleaner backend switch answers with: every key it knew, and
@@ -19,25 +19,25 @@ test("a payload from a build that predates a toggle parses, with the new toggle
         outputHoldout: 0.1,
     };
     // The defaults come from the schema, not from a copy of it written here. Transcribing them made every
-    // setting the product gained land as a failure in this file — a diff that only ever said "the list moved",
+    // setting the product gained land as a failure in this file: a diff that only ever said "the list moved",
     // never "tolerance broke", and whose fix was always to paste the new default in. What this test is about
     // is the seam: what the old build sent survives verbatim, and what it never heard of arrives at default.
     expect(SandboxSettingsSchema.parse(older)).toEqual({ ...SandboxSettingsSchema.parse({}), ...older });
 });
 
 /* The invariant a fresh sandbox depends on: NO field is required. A settings object is written for the first
- * time only when the user changes something, so until then the daemon parses `{}` — one field without a
+ * time only when the user changes something, so until then the daemon parses `{}`: one field without a
  * `.default()` turns that into a throw at boot, and the version tolerance above is built on the same property.
  *
  * Asserted by shape rather than by value: what each default IS belongs next to the field in schemas.ts, where
  * the reason it holds is written down. A second copy here proved nothing the schema didn't already say and
  * failed on every field the product added. */
-test("no field is required — a workspace that has never written settings parses", () => {
+test("no field is required: a workspace that has never written settings parses", () => {
     const defaults = SandboxSettingsSchema.parse({});
     expect(Object.keys(defaults).toSorted()).toEqual(Object.keys(SandboxSettingsSchema.shape).toSorted());
 });
 
-test("a key of the wrong type is still a parse failure — tolerance is for absence, not for garbage", () => {
+test("a key of the wrong type is still a parse failure: tolerance is for absence, not for garbage", () => {
     expect(SandboxSettingsSchema.safeParse({ iqSearch: "yes" }).success).toBe(false);
     expect(SandboxSettingsSchema.safeParse({ outputHoldout: 4 }).success).toBe(false);
     // The prompt cap is a real bound, not advice: the text IS the system prompt, and every turn pays for it.
@@ -46,7 +46,7 @@ test("a key of the wrong type is still a parse failure — tolerance is for abse
 
 /* The capability list crosses the same seam, and its failure mode is worse than a dead switch: the browser
  * parses ONE object for the whole page, so a required key the older daemon never sends takes the Capabilities
- * page down entirely — to hide an advisory badge. */
+ * page down entirely: to hide an advisory badge. */
 
 test("a capability list from a daemon that predates recommendations parses, with none recommended", () => {
     const older = { capabilities: [{ id: "github", kind: "cli", status: { state: "active" }, config: { provider: "github" } }] };
@@ -66,7 +66,7 @@ test("an ipsec tunnel is a full tunnel unless it says otherwise", () => {
 test("routed networks take a CIDR list and reject what charon could not load", () => {
     expect(IpsecVpnConfigSchema.parse({ ...ipsec, routedNetworks: "10.0.0.0/8, 192.168.0.0/16" }).routedNetworks).toBe("10.0.0.0/8, 192.168.0.0/16");
     expect(IpsecVpnConfigSchema.parse({ ...ipsec, routedNetworks: "fd00::/8" }).routedNetworks).toBe("fd00::/8");
-    // A bare host address is the easy mistake — strongSwan wants the prefix, and the message says so.
+    // A bare host address is the easy mistake: strongSwan wants the prefix, and the message says so.
     expect(IpsecVpnConfigSchema.safeParse({ ...ipsec, routedNetworks: "192.168.0.168" }).success).toBe(false);
     expect(IpsecVpnConfigSchema.safeParse({ ...ipsec, routedNetworks: "10.0.0.0/8,nonsense" }).success).toBe(false);
     expect(IpsecVpnConfigSchema.safeParse({ ...ipsec, routedNetworks: "" }).success).toBe(false);

package/src/schemas.ts

@@ -1873,6 +1873,39 @@ export const SandboxSettingsSchema = z.object({
      * surface MAY still name one (the shared run button's caret, Acceptance's per-run pick), and that wins. */
     agentRunModels: z.array(z.string()).max(10).default([]),
     agentRunEffort: z.string().default(""),
+    /* AUTOMATIC TIER SELECTION: may the daemon run an easy-looking turn on a cheaper rung of the provider the
+     * user is already on, instead of on the model they picked?
+     *
+     * THREE STATES RATHER THAN A TOGGLE, because the middle one is the only honest way to reach the third.
+     * Nobody, this repo included, can name a sensible cutoff for "easy enough" without traffic to fit it
+     * against, and a routing threshold guessed in advance is how a cost feature quietly becomes a quality
+     * regression. So:
+     *   off     — the judge never runs. Nothing is scored, nothing is recorded, turns run on the user's pick.
+     *   shadow  — the judge runs and its verdict is written to the spend ledger beside what the turn actually
+     *             cost, and NOTHING IS ROUTED. This is the default: it spends no tokens, changes no behaviour,
+     *             and is the only thing that can turn the weights in prompt-complexity.ts from a hypothesis
+     *             into a measurement.
+     *   on      — a turn judged fast runs on the cheap rung (fast-tier.ts), when the provider publishes one.
+     *
+     * IT CAN ONLY EVER ROUTE DOWN. There is no "which model is the standard tier" setting because the standard
+     * tier is the model the user already chose, so the worst case of a wrong verdict is one turn's quality on a
+     * model they can see on the card and correct, never a bill they did not ask for. That asymmetry is why this
+     * can default to shadow rather than to off: shadow costs nothing and `on` cannot overspend. */
+    autoTier: z.enum(["off", "shadow", "on"]).default("shadow"),
+    /* WHICH CHEAP MODEL A DOWNGRADED TURN LANDS ON, an ordered list of `${provider}:${model}` keys
+     * (quickModelKey), or EMPTY for Auto.
+     *
+     * Empty is the default and the interesting case, exactly as quickModel's is: Auto is the cheapest row the
+     * turn's own provider publishes, read through the same cheap-end order (compareCheapestFirst), so the two
+     * features can never disagree about which rung is the cheap one, and connecting an account tomorrow
+     * improves the answer by itself.
+     *
+     * A LIST, so a sandbox working across several providers can name the rung it wants on each. But unlike the
+     * two lists above this one is NOT a failure ladder: entries naming a provider other than the turn's own are
+     * dropped rather than tried, because switching provider retires the conversation's session (turnRequest.ts
+     * `resumes`), and starting the conversation over to save a fraction of a cent is not a saving. The first
+     * entry that names this provider AND is genuinely cheaper than the pick wins; if none does, Auto answers. */
+    autoFastModels: z.array(z.string()).max(10).default([]),
     // How long a finished agent stays on the board before it is archived automatically (days; 0 ⇒ never).
     // Unlike every other flag here this one defaults ON, because the lane it governs is the board's only
     // terminal state: without a sweep the Finished lane grows for the life of the sandbox, and each card it
@@ -3192,12 +3225,14 @@ export const CapabilityKindSchema = z.enum([
     "extension",
     "ssh",
     "vpn",
+    "exit",
     "docker",
     "browser",
     "identity",
     "host",
     "agent",
     "endpoint",
+    "localmodel",
     "wallet",
 ]);
 export type CapabilityKind = z.infer<typeof CapabilityKindSchema>;
@@ -3316,7 +3351,7 @@ export const isForticlientCiphertext = (value: string): boolean => /^Enc[X]?\s+[
 
 const notForticlientCiphertext = <T extends z.ZodType<string>>(field: T, label: string): T =>
     field.refine((value) => !isForticlientCiphertext(value), {
-        message: `That looks like a value copied straight out of a FortiClient config — FortiClient encrypts it with a key tied to the machine that exported it, so it can't be used here. Enter the actual ${label} (ask whoever administers the gateway).`,
+        message: `That looks like a value copied straight out of a FortiClient config, FortiClient encrypts it with a key tied to the machine that exported it, so it can't be used here. Enter the actual ${label} (ask whoever administers the gateway).`,
     }) as unknown as T;
 
 export const WireguardVpnConfigSchema = z.object({
@@ -3393,6 +3428,75 @@ export const IpsecVpnConfigSchema = z.object({
     autoConnect,
 });
 export const VpnConfigSchema = z.discriminatedUnion("provider", [WireguardVpnConfigSchema, FortinetVpnConfigSchema, IpsecVpnConfigSchema]);
+
+// ---- exit ----
+/* A GEO EXIT: somewhere the agent's traffic can LEAVE from, so a page fetches as if read in Berlin or Osaka.
+ * Its own kind rather than a fourth `vpn` provider, and the distinction is the whole reason this works:
+ *
+ *   a `vpn` REACHES a private network , one stored gateway, dialled, pushing its routes into the main table.
+ *   an `exit` LEAVES from somewhere else, a POOL with a catalog, switched at runtime, routing NOTHING into
+ *     the main table.
+ *
+ * That last clause is load-bearing. An exit is a full tunnel by definition, and a full tunnel on the main
+ * table swallows the sandbox's own uplink, the model endpoint and the tunnel that makes this sandbox
+ * reachable, which reads to a user as the agent breaking mid-turn (see IpsecVpnConfigSchema.routedNetworks
+ * for the same trap on the vpn kind). So an exit never touches the default route. It publishes a local SOCKS
+ * proxy and callers opt in: a browser account naming it, `curl --proxy`, and nothing else. The side benefit
+ * is trust, a volunteer relay carries only what was pointed at it, never the agent's own working traffic.
+ *
+ * Three providers, chosen because each is reachable with no paid account:
+ *   tor      , the Tor network. ~52 exit countries, no account, no credentials, no privileges: it is a SOCKS
+ *              proxy already. Country is a torrc line, a new IP is a control-port signal. The free default.
+ *   vpngate  , the University of Tsukuba's volunteer relay pool. No account; its public CSV IS the catalog,
+ *              so servers auto-fill. Overwhelmingly Japan/Korea in practice, which is the half of the map Tor
+ *              covers worst, so the two complement rather than duplicate.
+ *   wireguard, bring your own .conf files, one per country, from a provider's dashboard (Proton VPN's free
+ *              tier, Mullvad, anything). The catalog is built by parsing what was pasted.
+ * Starting, switching country and rotating are LIVE operations (see exit.contract.ts), never config, so an
+ * exit's real state is read off the machine. `country` is the resting preference and `autoStart` the only
+ * other persisted intent. */
+export const ExitProviderSchema = z.enum(["tor", "vpngate", "wireguard"]);
+export type ExitProvider = z.infer<typeof ExitProviderSchema>;
+
+// An ISO 3166-1 alpha-2 code, normalised up so "de", "DE" and "De" are one country rather than three. The
+// catalogs, the CLI and the manifest all speak this one spelling.
+export const CountryCodeSchema = z
+    .string()
+    .regex(/^[A-Za-z]{2}$/, "A country is its two-letter code, like DE, US or JP.")
+    .transform((value) => value.toUpperCase());
+
+// Exits rest DOWN by default, the opposite of a vpn's autoConnect. A vpn is dialled because something behind
+// it is unreachable otherwise; an exit costs volunteer bandwidth (tor, vpngate) and buys nothing until a task
+// actually wants a different country, so the honest default is to hold it until asked.
+const autoStart = z.enum(["on", "off"]).default("off");
+
+export const TorExitConfigSchema = z.object({
+    provider: z.literal("tor"),
+    // Where to come out, when nothing has asked for somewhere else. Absent ⇒ let Tor choose, which is both
+    // faster and kinder to the network.
+    country: CountryCodeSchema.optional(),
+    autoStart,
+});
+export const VpngateExitConfigSchema = z.object({
+    provider: z.literal("vpngate"),
+    country: CountryCodeSchema.optional(),
+    autoStart,
+});
+export const WireguardExitConfigSchema = z.object({
+    /* One or more WireGuard .conf files in one field, pasted back to back. One field rather than one
+     * capability per country because they are one POOL: the whole point is switching between them under a
+     * proxy port that never moves, and a user with five Proton free countries should not add five capabilities
+     * to get five countries out of one account.
+     *
+     * Country per conf comes from an optional `# country: DE` line, else from the provider's own naming
+     * convention in the Endpoint host (Proton's `de-free-01.protonvpn.net`, Mullvad's `de-ber-wg-001`), else
+     * from a lookup through the tunnel once it is up. Whole thing is the secret: each conf holds a private key. */
+    provider: z.literal("wireguard"),
+    config: z.string().min(1),
+    country: CountryCodeSchema.optional(),
+    autoStart,
+});
+export const ExitConfigSchema = z.discriminatedUnion("provider", [TorExitConfigSchema, VpngateExitConfigSchema, WireguardExitConfigSchema]);
 /* What is OPTIONAL about the in-sandbox Docker Engine. The engine itself takes no configuring, the capability
  * either runs dockerd or it doesn't, so this holds only what a user chooses, and the bar for landing here is
  * that the sandbox works without it. (`--privileged` therefore is not here and never will be: dockerd does not
@@ -3403,7 +3507,7 @@ export const VpnConfigSchema = z.discriminatedUnion("provider", [WireguardVpnCon
  *
  *   IMAGE (`gpu`), rides the environment overlay. Changing it recomposes the Dockerfile, so it costs an
  *     owner-approved rebuild and a container recreate. Only `fragment()` may read these.
- *   ENGINE (everything below it) — /etc/docker/daemon.json, which dockerd reads at start. Changing one
+ *   ENGINE (everything below it): /etc/docker/daemon.json, which dockerd reads at start. Changing one
  *     rewrites the file and restarts dockerd: no rebuild, no new image, but it DOES stop whatever containers
  *     the engine is running, which is why it is disclosed rather than silently applied.
  *
@@ -3475,6 +3579,15 @@ export const BrowserConfigSchema = z
         purpose: z.string().optional(),
         // ISO-8601 date, stamped when the agent opens the account, absent for one connected by hand.
         openedAt: z.string().optional(),
+        /* WHERE THIS ACCOUNT BROWSES FROM: the id of an `exit` capability. Set it and every page this profile
+         * opens comes out of that country, with the browser's clock, locale and languages set to match.
+         *
+         * Only meaningful on an account that owns its OWN profile. An account born from an identity shares
+         * that identity's browser, cookies, passkeys and all, so it shares its exit too and this field is
+         * ignored for it (see the daemon's browser/browser-exit.ts). That is not a limitation, it is the
+         * point: one Google session appearing from Berlin in one tab and Osaka in another is a far louder
+         * signal than any address, so the exit belongs to whatever owns the profile. */
+        exit: z.string().optional(),
     })
     .catchall(z.string());
 /* ONE EMAIL IDENTITY THE SANDBOX ACTS AS ONLINE, the container platform accounts are born from, and the answer
@@ -3507,6 +3620,10 @@ export const IdentityConfigSchema = z.object({
     mailbox: z.string().optional(),
     loginUrl: z.url().optional(),
     openAccounts: z.enum(["on", "off"]).default("off"),
+    /* WHERE THIS IDENTITY LIVES, the id of an `exit` capability. An identity OWNS a browser profile, and every
+     * account born from it shares that profile, so setting it here sets it for all of them at once, which is
+     * the only coherent place to set it: the shared thing is one browser, and one browser is in one place. */
+    exit: z.string().optional(),
 });
 export type IdentityConfig = z.infer<typeof IdentityConfigSchema>;
 /* A connected COMPUTER of the user's own, the inverse of `ssh`, which reaches a server the sandbox can dial.
@@ -3600,6 +3717,28 @@ export const EndpointConfigSchema = z.object({
     apiKey: z.string().optional(),
     headers: z.string().optional(),
 });
+
+/* A MODEL THE SANDBOX RUNS ITSELF, the managed counterpart of `endpoint`. An endpoint points at a server the
+ * USER operates; this one names weights, and the daemon does the operating: it downloads the file into the
+ * workspace cache, serves it with the image's bundled llama-server on a loopback port it owns, and registers
+ * the result exactly as if the user had added an endpoint at that port. Everything downstream (the picker, the
+ * translator, quick-model pinning) sees an `endpoint/<id>` provider and never learns the difference, which is
+ * why there is no baseUrl here: the URL is derived from the entry's id (the daemon's endpoints/local-model.ts),
+ * not a fact anyone typed.
+ *
+ * `model` is WHICH WEIGHTS, as a Hugging Face path (`owner/repo/file.gguf`, resolved to the repo's own
+ * download), so shipping a new recommended model is a catalog-card edit, not a daemon release. The reserved
+ * value "custom" defers to `url`, a direct GGUF link for people who know exactly what they want.
+ *
+ * `gpu` mirrors the docker card's option and rides the same allowlisted `--gpus=all` directive: the ASK lives
+ * here, what became of it is SANDBOX_GPU, stamped by the runner (see the docker handler's gpuState). "on"/"off"
+ * rather than a boolean for the manifest-wide reason DockerConfigSchema gives. */
+export const LocalModelConfigSchema = z.object({
+    model: z.string().min(1),
+    gpu: z.enum(["on", "off"]).default("off"),
+    url: z.url().optional(),
+});
+export type LocalModelConfig = z.infer<typeof LocalModelConfigSchema>;
 /* THE SANDBOX WALLET, a USDC balance the agent can spend on x402-payable endpoints, under owner policy.
  *
  * WHAT IS DELIBERATELY NOT HERE IS A KEY. The signing key lives with the PLATFORM (one wallet per owner,
@@ -3619,7 +3758,7 @@ export const EndpointConfigSchema = z.object({
  * `allow`/`deny` are hostname lists (comma- or newline-separated). Empty allow = any host, each behind its
  * card; deny wins over allow. One capability per sandbox (singleton card): a second balance would just be a
  * second opinion about the same owner's wallet. */
-const usdAmount = z.string().regex(/^\d+(\.\d{1,6})?$/, "a USD amount like 0.50 (up to six decimals — USDC's own precision)");
+const usdAmount = z.string().regex(/^\d+(\.\d{1,6})?$/, "a USD amount like 0.50 (up to six decimals: USDC's own precision)");
 export const WalletNetworkSchema = z.enum(["eip155:8453", "eip155:84532"]);
 export type WalletNetwork = z.infer<typeof WalletNetworkSchema>;
 export const WalletConfigSchema = z.object({
@@ -3650,6 +3789,10 @@ export type WireguardVpnConfig = z.infer<typeof WireguardVpnConfigSchema>;
 export type FortinetVpnConfig = z.infer<typeof FortinetVpnConfigSchema>;
 export type IpsecVpnConfig = z.infer<typeof IpsecVpnConfigSchema>;
 export type VpnConfig = z.infer<typeof VpnConfigSchema>;
+export type TorExitConfig = z.infer<typeof TorExitConfigSchema>;
+export type VpngateExitConfig = z.infer<typeof VpngateExitConfigSchema>;
+export type WireguardExitConfig = z.infer<typeof WireguardExitConfigSchema>;
+export type ExitConfig = z.infer<typeof ExitConfigSchema>;
 export type DockerConfig = z.infer<typeof DockerConfigSchema>;
 export type BrowserConfig = z.infer<typeof BrowserConfigSchema>;
 export type HostConfig = z.infer<typeof HostConfigSchema>;
@@ -3671,6 +3814,9 @@ export const CapabilitySchema = z.discriminatedUnion("kind", [
     // No IFNAMSIZ cap on the id: the tunnel's interface name is DERIVED (see the daemon's vpn/vpn-paths.ts
     // interfaceName) rather than being the id itself, so a descriptive name is free.
     z.object({ id: entryId, kind: z.literal("vpn"), config: VpnConfigSchema }),
+    // A geo exit (ExitConfigSchema). Same interface-name derivation as vpn, and deliberately NOT a vpn arm:
+    // it routes nothing into the main table, so the full-tunnel warning the vpn kind carries stays true.
+    z.object({ id: entryId, kind: z.literal("exit"), config: ExitConfigSchema }),
     // The in-sandbox Docker Engine (baked into the base image, dormant by default). Its `--privileged` runtime
     // directive is not in the config and never will be: dockerd does not work without it (see the handler's
     // isPrivileged), so a switch there would offer a broken sandbox as a choice. What IS optional lives in
@@ -3687,6 +3833,10 @@ export const CapabilitySchema = z.discriminatedUnion("kind", [
     // precedent, with the prefix because these two are the only capability kinds that mint providers and they
     // want opposite ability records (an ACP agent owns its own loop; an endpoint runs the full Claude Code one).
     z.object({ id: entryId, kind: z.literal("endpoint"), config: EndpointConfigSchema }),
+    // A model the sandbox downloads and serves itself (LocalModelConfigSchema). Deliberately minting the SAME
+    // `endpoint/<id>` provider ids as the endpoint kind: to every consumer it IS an endpoint, one the daemon
+    // happens to operate, so a second provider namespace would be a second code path for the same turns.
+    z.object({ id: entryId, kind: z.literal("localmodel"), config: LocalModelConfigSchema }),
     // The sandbox's USDC wallet (WalletConfigSchema), one per sandbox; the key never enters the container.
     z.object({ id: entryId, kind: z.literal("wallet"), config: WalletConfigSchema }),
 ]);
@@ -4142,6 +4292,138 @@ export const ForticlientConnectionSchema = z.object({
 export type ForticlientConnection = z.infer<typeof ForticlientConnectionSchema>;
 export const ForticlientImportSchema = z.object({ connections: z.array(ForticlientConnectionSchema) });
 
+// ---- exit: live state, the catalog, and the observation that makes a switch true ----
+// The manifest says which exits EXIST; this says which are up, where they come out, and what the world sees.
+// Read off the machine and off the wire, never remembered: an exit the agent stopped from a shell and one the
+// UI stopped read identically, and a daemon restart observes the truth rather than a stale guess.
+
+export const ExitStateSchema = z.enum([
+    // Carrying traffic: the proxy is listening and the last check came out where it was asked to.
+    "up",
+    // Coming up, or moving to another country. The proxy port may already be open and not yet where you want.
+    "starting",
+    // Configured and idle. The resting state, and the default one: exits are not held open for nothing.
+    "down",
+    // The client isn't installed yet (tor, openvpn): the capability's image fragment needs an owner rebuild.
+    "unavailable",
+    // The last start or switch failed; `detail` carries the reason.
+    "failed",
+]);
+export type ExitState = z.infer<typeof ExitStateSchema>;
+
+/* WHAT THE WORLD SEES, fetched THROUGH the exit's own proxy. This is the load-bearing type of the whole
+ * feature: "switch to Germany" is worth nothing as a report that a tunnel came up, and worth everything as a
+ * report that the egress address is now German. Every start, use and rotate ends by producing one of these,
+ * and a switch that cannot produce one fails instead of quietly leaving traffic where it was. */
+export const ExitObservationSchema = z.object({
+    ip: z.string(),
+    // Absent when the lookup answered with an address but no country: a switch is judged on the country when
+    // one is known, and on the address having CHANGED when it is not.
+    country: z.string().optional(),
+    countryName: z.string().optional(),
+});
+export type ExitObservation = z.infer<typeof ExitObservationSchema>;
+
+/* One country an exit can come out of, as the picker and `exit countries` render it. `servers` and `share`
+ * are what stop a country list being a lie: Tor lists 52 countries and a third of them are one underpowered
+ * relay, so the ranking has to carry how much is actually there, not just that the flag exists. */
+export const ExitPointSchema = z.object({
+    country: z.string(),
+    countryName: z.string(),
+    // How many relays/servers this provider has there right now.
+    servers: z.number(),
+    // This country's share of the provider's total exit capacity, 0..1. Used to sort and to grey out the
+    // countries that technically exist and practically do not.
+    share: z.number().optional(),
+});
+export type ExitPoint = z.infer<typeof ExitPointSchema>;
+export const ExitCountriesSchema = z.object({
+    countries: z.array(ExitPointSchema),
+    // Whether this list came off the provider live or out of the baked fallback (no network, or the provider
+    // is down). The picker says so rather than presenting a stale list as current.
+    live: z.boolean(),
+});
+
+export const ExitLinkSchema = z.object({
+    id: z.string(),
+    provider: ExitProviderSchema,
+    state: ExitStateSchema,
+    // The SOCKS endpoint callers point at. Fixed per exit and stable across country switches, which is what
+    // lets a long task change country halfway without reconfiguring anything downstream.
+    proxy: z.string(),
+    // The country ASKED for (manifest preference, or the last `use`). Absent = provider's choice.
+    country: z.string().optional(),
+    // The country actually OBSERVED at the last check, and the address behind it. These two disagreeing is
+    // the single most useful fault signal this feature has, so they are separate fields, never merged.
+    observedCountry: z.string().optional(),
+    ip: z.string().optional(),
+    // Epoch ms of the observation above, so a stale reading can be rendered as stale.
+    checkedAt: z.number().optional(),
+    // The tunnel interface, for the providers that have one (vpngate, wireguard). Tor has none by design.
+    interface: z.string().optional(),
+    since: z.number().optional(),
+    autoStart: z.boolean(),
+    detail: z.string().optional(),
+});
+export type ExitLink = z.infer<typeof ExitLinkSchema>;
+export const ExitListSchema = z.object({ links: z.array(ExitLinkSchema) });
+
+/* WHERE EACH FREE PROVIDER CAN ACTUALLY COME OUT, as measured, and the reason it lives in the contract rather
+ * than in the daemon: two consumers need the same answer and must not drift. The daemon uses it as the
+ * FALLBACK catalog when a provider's own list cannot be fetched; the add form uses it to fill the country
+ * picker, so a user chooses from a list instead of guessing a code and finding out later that nothing serves
+ * it. A second copy of these numbers would let the picker offer a country the driver cannot dial.
+ *
+ * `share` is the country's slice of the provider's exit capacity, and it is the number that matters. A third
+ * of Tor's fifty-two countries are one overloaded relay behind a flag; ranking by relay COUNT alone would put
+ * the United States first on 1,171 slow relays when the Netherlands carries three times the traffic on half as
+ * many. Both surfaces sort on this so the top of the list is the part that works.
+ *
+ * Measured 2026-08-21 from onionoo.torproject.org and vpngate.net's public CSV. Stale by construction, which
+ * is exactly why the daemon prefers a live fetch and labels this one as not-live when it falls back to it. */
+export const TOR_EXIT_COUNTRIES: readonly ExitPoint[] = [
+    { country: "NL", countryName: "Netherlands", servers: 607, share: 0.304 },
+    { country: "DE", countryName: "Germany", servers: 415, share: 0.242 },
+    { country: "SE", countryName: "Sweden", servers: 344, share: 0.14 },
+    { country: "US", countryName: "United States", servers: 1171, share: 0.097 },
+    { country: "AT", countryName: "Austria", servers: 123, share: 0.054 },
+    { country: "LU", countryName: "Luxembourg", servers: 92, share: 0.033 },
+    { country: "FR", countryName: "France", servers: 63, share: 0.032 },
+    { country: "NO", countryName: "Norway", servers: 54, share: 0.026 },
+    { country: "RO", countryName: "Romania", servers: 71, share: 0.011 },
+    { country: "DK", countryName: "Denmark", servers: 15, share: 0.007 },
+    { country: "HU", countryName: "Hungary", servers: 20, share: 0.006 },
+    { country: "IT", countryName: "Italy", servers: 15, share: 0.006 },
+    { country: "UA", countryName: "Ukraine", servers: 23, share: 0.006 },
+    { country: "CH", countryName: "Switzerland", servers: 23, share: 0.006 },
+    { country: "IS", countryName: "Iceland", servers: 23, share: 0.003 },
+    { country: "PL", countryName: "Poland", servers: 8, share: 0.002 },
+    { country: "BG", countryName: "Bulgaria", servers: 17, share: 0.002 },
+    { country: "GB", countryName: "United Kingdom", servers: 8, share: 0.002 },
+    { country: "FI", countryName: "Finland", servers: 13, share: 0.002 },
+];
+
+// VPN Gate, and its shape is the honest headline: 87% of its pool is Japan and Korea. That is not a defect to
+// hide behind a long country list, it is the reason to have it, Tor's Asian exit capacity is close to nothing,
+// so the two providers cover each other rather than overlapping.
+export const VPNGATE_EXIT_COUNTRIES: readonly ExitPoint[] = [
+    { country: "JP", countryName: "Japan", servers: 46, share: 0.48 },
+    { country: "KR", countryName: "Korea, South", servers: 37, share: 0.39 },
+    { country: "VN", countryName: "Vietnam", servers: 3, share: 0.03 },
+    { country: "TH", countryName: "Thailand", servers: 2, share: 0.02 },
+    { country: "RU", countryName: "Russia", servers: 2, share: 0.02 },
+    { country: "RO", countryName: "Romania", servers: 1, share: 0.01 },
+    { country: "MX", countryName: "Mexico", servers: 1, share: 0.01 },
+    { country: "IN", countryName: "India", servers: 1, share: 0.01 },
+    { country: "CN", countryName: "China", servers: 1, share: 0.01 },
+    { country: "BY", countryName: "Belarus", servers: 1, share: 0.01 },
+];
+
+export const ExitIdParamSchema = z.object({ id: z.string() });
+// POST /exit/{id}/use body. An absent country means "let the provider choose", the same thing an absent
+// `country` in the manifest means, so clearing a country is expressible rather than only setting one.
+export const ExitUseInputSchema = z.object({ id: z.string(), country: CountryCodeSchema.optional() });
+
 // Browse an extension/plugin registry (a git repo with .claude-plugin/marketplace.json, see
 // @intentic/registry for the format). POST so the optional token for a private registry never rides a URL or
 // an access log.
@@ -5431,14 +5713,14 @@ export const PortSummarySchema = z.object({
     // processes, published container ports), the previewable set; `system` = the sandbox's own machinery
     // (agent runtimes, translator, dockerd, sshd), listed for transparency but nobody previews it.
     kind: z.enum(["workspace", "system"]),
-    /* WHAT IS ON THIS PORT, IN WORDS — resolved by the daemon (ports/port-identity.ts), because the two facts
+    /* WHAT IS ON THIS PORT, IN WORDS: resolved by the daemon (ports/port-identity.ts), because the two facts
      * that attribute a listener (the panel key → extension index, the workspace root) exist there and nowhere
      * else. `title` is what a person would call it ("Vite dev server", "Sandbox service", "Container port"),
-     * `purpose` is the one sentence a row shows under it, and `origin` says who put it there — which is what
+     * `purpose` is the one sentence a row shows under it, and `origin` says who put it there, which is what
      * the reader is really asking when they ask what a port is: mine, my agent's, or the box's own.
      *
      * All three are required. A listener nothing can explain still gets a name ("Unclaimed port") and a
-     * sentence that says so out loud, because the alternative — a raw argv, or nothing — is what made this
+     * sentence that says so out loud, because the alternative (a raw argv, or nothing) is what made this
      * view unreadable, and the button beside the row publishes the port to the internet. */
     title: z.string(),
     purpose: z.string(),
@@ -6596,6 +6878,29 @@ export const UsageTurnSchema = z.object({
      *
      * Absent ⇒ as for `searchCalls`. */
     openingSearches: z.number().optional(),
+    /* WHAT THE COMPLEXITY JUDGE SAID ABOUT THIS TURN, and whether anything was done about it. The three fields
+     * automatic tier selection is calibrated from, and the reason it can ship in shadow at all.
+     *
+     * They live on the SPEND ledger rather than in a log of their own because the question they exist to answer
+     * is a question about money: what did the turns we would have downgraded actually cost, and what did the
+     * ones we did downgrade cost instead. A separate log would have to be joined back to this one on every
+     * read, and the join key (a turn) is already the row.
+     *
+     * `tierScore` is 0..1 from judgeComplexity, comparable against FAST_CEILING, which is the cutoff it was
+     * judged against at the time. Absent ⇒ the judge did not run (settings.autoTier "off", or a row written
+     * before this existed), which is NOT the same as a turn that scored zero.
+     *
+     * `tierRules` is which named features fired, and it is the half that makes the ledger analysable rather
+     * than merely tallyable: a score says a threshold was crossed, the rules say which feature is doing the
+     * work, and re-fitting the weights needs the second. Bounded by construction, there are ~19 of them.
+     *
+     * `tierRouted` is whether the turn ACTUALLY ran on the cheap rung. It is not implied by the score: a turn
+     * judged fast still runs standard in shadow mode, and still runs standard in `on` mode when the provider
+     * publishes nothing cheaper than the user's pick. Reading the score as the decision would report savings
+     * that were never made. */
+    tierScore: z.number().optional(),
+    tierRules: z.array(z.string()).optional(),
+    tierRouted: z.boolean().optional(),
 });
 export type UsageTurn = z.infer<typeof UsageTurnSchema>;
 

package/src/search-globs.test.ts

@@ -11,7 +11,7 @@ test("an empty field scopes nothing", () => {
 test("a bare name is a file as well as a folder, at any depth", () => {
     expect(includeGlobs(`package.json`).globs).toEqual([`**/package.json`, `**/package.json/**`]);
     expect(includeGlobs(`docs`).globs).toEqual([`**/docs`, `**/docs/**`]);
-    // A trailing slash is noise — the folder form is generated either way.
+    // A trailing slash is noise: the folder form is generated either way.
     expect(includeGlobs(`docs/`).globs).toEqual([`**/docs`, `**/docs/**`]);
 });
 
@@ -41,6 +41,6 @@ test("a leading ! excludes instead", () => {
         globs: [`**/src`, `**/src/**`],
         notGlobs: [`**/*.test.ts`, `**/*.test.ts/**`],
     });
-    // A lone "!" excludes nothing — expanded, it would have matched everything.
+    // A lone "!" excludes nothing: expanded, it would have matched everything.
     expect(includeGlobs(`!`)).toEqual({ globs: [], notGlobs: [] });
 });

package/src/share-paths.test.ts

@@ -17,7 +17,7 @@ describe("the readable half", () => {
     });
 
     // A title in a writing system this alphabet cannot carry leaves the random half standing alone, which is
-    // still a perfectly good id — and a better outcome than an address full of percent-encoding.
+    // still a perfectly good id, and a better outcome than an address full of percent-encoding.
     it("falls back to the random half when a title has no letters to give", () => {
         expect(shareStem("日本語のタイトル")).toBe("");
         expect(shareId("日本語のタイトル", "3f9c")).toBe("3f9c");

package/src/title.test.ts

@@ -7,13 +7,13 @@ import { deriveTitle } from "./title.js";
  * politeness, or stopped mid-syllable. */
 
 test("spends the budget on the ask rather than on the politeness in front of it", () => {
-    // `Can you please fix the auth…` is what the naive cut produced — three of its five words are ceremony.
+    // `Can you please fix the auth…` is what the naive cut produced: three of its five words are ceremony.
     expect(deriveTitle("Can you please fix the auth tests?")).toBe("Fix the auth tests?");
     expect(deriveTitle("Hey, can you please look at the flaky test")).toBe("Look at the flaky test");
 });
 
 test("keeps a greeting whole when peeling it off would leave a fragment", () => {
-    // `Hi there` is not a conversation about `there`, and `So what?` is not one about `what?` — a one-word
+    // `Hi there` is not a conversation about `there`, and `So what?` is not one about `what?`: a one-word
     // remnant means the opener was carrying the sentence, so the line stands as the user wrote it.
     expect(deriveTitle("Hi there")).toBe("Hi there");
     expect(deriveTitle("So what?")).toBe("So what?");
@@ -35,7 +35,7 @@ test("titles a pasted stack trace after the sentence the user wrote around it",
 
 test("skips a greeting line and takes the ask from the line below it", () => {
     // A line that unwinds to nothing was throat-clearing; the ask is further down. The naive rule stopped at
-    // the greeting and named every such conversation `Hey, quick one —`.
+    // the greeting and named every such conversation `Hey, quick one -`.
     expect(deriveTitle("Hey, quick one —\n\nWhy does the tab title truncate mid-word?")).toBe("Why does the tab title truncate mid-word?");
 });
 
@@ -61,7 +61,7 @@ test("cuts on a word boundary instead of mid-syllable", () => {
 
 test("keeps a cut it cannot put on a word boundary inside the budget anyway", () => {
     /* The sibling of the case above: a long unbroken token straddling the cut leaves no space late enough to
-     * back off to, so the length clamp alone ends the title — and it used to end it one character OVER. That
+     * back off to, so the length clamp alone ends the title, and it used to end it one character OVER. That
      * character is not a cosmetic overflow, it is a 400 on the turn carrying the name, and it wedged the
      * conversation for good: the browser stores the derived title before it sends, so every retry re-sent the
      * same rejected one. */
@@ -72,7 +72,7 @@ test("keeps a cut it cannot put on a word boundary inside the budget anyway", ()
     // Asserted THROUGH the contract rather than against a repeated literal: the clamp and the cap drifting
     // apart is the entire bug, and a second copy of the number is how they drift.
     expect(AgentTurnSchema.safeParse({ prompt, title }).success).toBe(true);
-    // Not a property of that one sentence — any token wide enough to swallow the window does it.
+    // Not a property of that one sentence: any token wide enough to swallow the window does it.
     const wide = `Investigate ${"X".repeat(120)} please`;
     expect(AgentTurnSchema.safeParse({ prompt: wide, title: deriveTitle(wide) }).success).toBe(true);
 });
@@ -111,7 +111,7 @@ test("names a prompt that is nothing but a paste after what was pasted", () => {
 });
 
 test("never returns empty for a prompt that has any content at all", () => {
-    // A greeting with no ask behind it, and a prompt with no letters in it — both still have to name a tab.
+    // A greeting with no ask behind it, and a prompt with no letters in it: both still have to name a tab.
     expect(deriveTitle("Hey!")).toBe("Hey!");
     expect(deriveTitle("!!!")).toBe("!!!");
 });
@@ -121,7 +121,7 @@ test("reads past quoted material to the user's own words", () => {
 });
 
 test("skips past-work narration to the instruction behind it", () => {
-    // `We have recently added…` is the scene, not the ask — titling from it names every such conversation
+    // `We have recently added…` is the scene, not the ask: titling from it names every such conversation
     // after last week's work. The instruction further in is what the conversation is about.
     expect(deriveTitle("We have recently added iq map and iq deps commands. Now let's also add a health contract for the daemon.")).toBe(
         "Add a health contract for the daemon",
@@ -134,13 +134,13 @@ test("skips narration to an outright question", () => {
 });
 
 test("keeps narration when nothing behind it is unmistakably the ask", () => {
-    // A hazy follow-up is not worth skipping for — better a title about last week's work than one about `it`.
+    // A hazy follow-up is not worth skipping for: better a title about last week's work than one about `it`.
     expect(deriveTitle("We migrated the board to SSE last week. It feels slower since.")).toBe("We migrated the board to SSE last week");
 });
 
 test("keeps a declarative problem report even when advice follows it", () => {
     // Only NARRATION is skippable. A problem statement is the ask, and the imperative behind it is merely a
-    // pointer — `Check the broadcast path` names a step, not the conversation.
+    // pointer: `Check the broadcast path` names a step, not the conversation.
     expect(deriveTitle("The fleet board flickers when agents land. Check the broadcast path.")).toBe("The fleet board flickers when agents land");
 });
 

package/src/title.ts

@@ -104,7 +104,7 @@ const proseLines = (prompt: string): string[] => {
  *
  * Three outcomes, and the difference between them is the whole point. A remnant of SEVERAL words is the ask,
  * `Can you please fix the auth tests?` was carrying `fix the auth tests?`. A remnant of NOTHING was pure
- * greeting (`Hey, quick one —`), and returning empty is how the caller learns to read the next line instead.
+ * greeting (`Hey, quick one -`), and returning empty is how the caller learns to read the next line instead.
  * A remnant of ONE word means the opener was meaningful. `Hi there` is not a conversation about `there`,
  * and `So what?` is not one about `what?`, so the line stands as written. */
 const withoutOpener = (line: string): string => {

package/src/tunnel-ids.test.ts

@@ -34,11 +34,11 @@ test("port slots are a fixed-size pool of DNS-safe labels, stable per token", ()
     expect(portSlotsFromToken(TOKEN)).toEqual(slots);
 });
 
-/* The whole point of the salt. The sandbox id is public — it is the leading label of the sandbox's own URL and
- * of every preview link its owner has shared — so anything derived from the id ALONE is derivable by whoever
+/* The whole point of the salt. The sandbox id is public: it is the leading label of the sandbox's own URL and
+ * of every preview link its owner has shared, so anything derived from the id ALONE is derivable by whoever
  * holds one of those links. Slots must not be: knowing a sandbox's id must not tell you where its forwarded
  * ports live. */
-test("slots are not derivable from the sandbox id — only from the token behind it", () => {
+test("slots are not derivable from the sandbox id: only from the token behind it", () => {
     expect(portSlotsFromToken(OTHER)).not.toEqual(portSlotsFromToken(TOKEN));
     // No slot leaks the id it will be paired with in `port-<slot>-<sandboxId>`.
     const id = sandboxIdFromToken(TOKEN);