@vellumai/vellum-gateway 0.11.6 → 0.11.7-staging.2

package/AGENTS.md

@@ -179,7 +179,7 @@ A default row per enforced channel is **seeded at startup** (`seedAdmissionPolic
 
 For exempt ids, `PUT /v1/assistants/:id/channel-admission-policy/:channelType` returns **403**, the GET list omits them, and the runtime short-circuits `admitted: true` in `admission-policy.ts` (defense in depth). Codex finding from #35006 review: exemption checks must live in _both_ the gateway route handler AND the runtime stage — single-side enforcement creates a misuse wedge.
 
-**Hidden channels** (`ADMISSION_POLICY_HIDDEN_CHANNELS` = `vellum`, `whatsapp`, `discord`) — managed automatically, **not** user-configurable, but (unlike exempt channels) **still enforced at runtime**:
+**Hidden channels** (`ADMISSION_POLICY_HIDDEN_CHANNELS` = `vellum`, `whatsapp`) — managed automatically, **not** user-configurable, but (unlike exempt channels) **still enforced at runtime**:
 
 - The GET list omits them, and `PUT`/`DELETE` return **403** (`isAdmissionPolicyHiddenChannel`).
 - They are **not** exempt — the runtime still evaluates rank-vs-floor, so a real inbound channel like `whatsapp` keeps its admission floor.
@@ -242,6 +242,20 @@ The gateway classifies the actor at ingress (keyed on `actorExternalId`) and for
 
 **Intentionally NOT capability-gated** (these are identity / admission-flow decisions, not permissions, and stay raw class checks): `calls/*` guardian-identity call routing, `inbound-message-handler` heartbeat/timezone side-effects, `surface-action-routes` drift-heal re-resolution, and `channel-retry-sweep` trust-class parsing.
 
+## Operator CLI (`gateway contacts`)
+
+The gateway package ships an operator CLI (`gateway/src/cli/`, bin `gateway`) for gateway-owned contact ACL. This is the write surface for a contact's assistant-access ceiling. Do not add that write to `assistant contacts`.
+
+```
+gateway contacts list
+gateway contacts get <contactId>
+gateway contacts set-risk-threshold <contactId> --threshold none|low|medium|high|inherit
+```
+
+The CLI talks to the running gateway over its IPC socket (`set_contact_threshold`, `contacts_list_rich`, `contacts_get_rich`). It does not open `gateway.sqlite` itself.
+
+From the host: `vellum exec --service gateway -- gateway contacts ...`. Do not add a `vellum gateway contacts` verb.
+
 ## Guardian Requests (gateway-owned)
 
 The gateway owns guardian approval requests and their delivery records: the `guardian_requests` and `guardian_request_deliveries` tables (`src/db/guardian-request-store.ts`), fronted by `src/approvals/guardian-request-service.ts` and exposed to the daemon over the `guardian_requests_*` IPC routes (`src/ipc/guardian-request-handlers.ts`; shared contract in `packages/gateway-client/src/guardian-request-contract.ts`). The daemon holds no request state — it relays everything through `assistant/src/channels/gateway-guardian-requests.ts` and keeps the daemon-domain side effects: notifications, card delivery/withdrawal, pending-interaction resume, grant minting into its `scoped_approval_grants`.

package/ARCHITECTURE.md

@@ -54,7 +54,7 @@ The request carries base64-encoded WAV audio and a MIME type. The daemon resolve
 
 Clients open WebSocket connections through the gateway to the daemon's real-time STT streaming endpoint for conversation chat message capture. The gateway authenticates the downstream client using an edge JWT (actor principal required), then opens an upstream WebSocket connection to the daemon's `/v1/stt/stream` endpoint with a short-lived gateway service token. This keeps the daemon's WebSocket endpoint unreachable from the public internet while allowing authenticated clients to stream audio for real-time transcription.
 
-**Config-authoritative model:** The runtime always resolves the streaming transcriber from `services.stt.provider` in the assistant config, regardless of any `provider` query parameter. The `provider` parameter is optional compatibility metadata — when supplied and it disagrees with the configured provider, the runtime logs a mismatch warning for operator visibility.
+**Config-authoritative model:** The runtime always resolves the streaming transcriber from the assistant config, regardless of any `provider` query parameter. Dictation reads its own role (`services.stt.roles.dictation`, falling back to `services.stt.provider`). The `provider` parameter is optional compatibility metadata: when supplied and it disagrees with the provider that role resolves to, the runtime logs a mismatch warning for operator visibility.
 
 **Client path:** `wss://<gateway>/v1/stt/stream?mimeType=<mime>[&provider=<id>][&sampleRate=<hz>]`
 
@@ -1116,20 +1116,20 @@ Malformed or unprocessable provider callback payloads are logged as dead-letter
 
 Call behavior is controlled via the `calls` config block in the assistant configuration (`config/schema.ts`). All values have sensible defaults and are validated via Zod:
 
-| Field                             | Type     | Default                                                 | Description                                                                                                                                                                                                                                    |
-| --------------------------------- | -------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `calls.enabled`                   | boolean  | `true`                                                  | Master toggle for the calls feature. When `false`, call routes return 403 and tools return errors.                                                                                                                                             |
-| `calls.provider`                  | enum     | `'twilio'`                                              | Voice provider to use (currently only Twilio is supported).                                                                                                                                                                                    |
-| `calls.maxDurationSeconds`        | int      | `3600`                                                  | Maximum allowed duration per call.                                                                                                                                                                                                             |
-| `calls.userConsultTimeoutSeconds` | int      | `120`                                                   | How long to wait for a user answer before timing out a pending question.                                                                                                                                                                       |
-| `calls.disclosure.enabled`        | boolean  | `true`                                                  | Whether the AI should disclose it is an AI at the start of the call.                                                                                                                                                                           |
-| `calls.disclosure.text`           | string   | _(default disclosure prompt)_                           | The disclosure instruction included in the system prompt.                                                                                                                                                                                      |
-| `calls.safety.denyCategories`     | string[] | `[]`                                                    | Categories of calls to deny (e.g., emergency numbers are always denied regardless of this setting).                                                                                                                                            |
-| `llm.callSites.callAgent.model`   | string   | _(unset; falls back to the resolved call-site default)_ | Optional override for the LLM model used in voice call conversations.                                                                                                                                                                          |
-| `services.stt.provider`           | enum     | `'deepgram'`                                            | STT provider for all boundaries including telephony. The daemon transcribes media-stream call audio with this provider (streaming when supported, batch otherwise).                                                                            |
-| `services.stt.language`           | string   | `multi`                                                 | Spoken language for transcription: a BCP-47 code pins one language, `multi` (the schema default) enables code-switching on providers that support it. Per-language TTS voices are configured via `services.tts.providers.<id>.languageVoices`. |
-| `services.tts.provider`           | enum     | `'elevenlabs'`                                          | Active TTS provider for speech synthesis (catalog-driven; see [TTS Provider Abstraction](../assistant/ARCHITECTURE.md#tts-provider-abstraction-servicestts)).                                                                                  |
-| `services.tts.providers.<id>.*`   | object   | _(per-provider defaults)_                               | Provider-specific settings block. One block per catalog entry (e.g. `elevenlabs`, `fish-audio`).                                                                                                                                               |
+| Field                             | Type     | Default                                                 | Description                                                                                                                                                                                                                                                                                                                                        |
+| --------------------------------- | -------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `calls.enabled`                   | boolean  | `true`                                                  | Master toggle for the calls feature. When `false`, call routes return 403 and tools return errors.                                                                                                                                                                                                                                                 |
+| `calls.provider`                  | enum     | `'twilio'`                                              | Voice provider to use (currently only Twilio is supported).                                                                                                                                                                                                                                                                                        |
+| `calls.maxDurationSeconds`        | int      | `3600`                                                  | Maximum allowed duration per call.                                                                                                                                                                                                                                                                                                                 |
+| `calls.userConsultTimeoutSeconds` | int      | `120`                                                   | How long to wait for a user answer before timing out a pending question.                                                                                                                                                                                                                                                                           |
+| `calls.disclosure.enabled`        | boolean  | `true`                                                  | Whether the AI should disclose it is an AI at the start of the call.                                                                                                                                                                                                                                                                               |
+| `calls.disclosure.text`           | string   | _(default disclosure prompt)_                           | The disclosure instruction included in the system prompt.                                                                                                                                                                                                                                                                                          |
+| `calls.safety.denyCategories`     | string[] | `[]`                                                    | Categories of calls to deny (e.g., emergency numbers are always denied regardless of this setting).                                                                                                                                                                                                                                                |
+| `llm.callSites.callAgent.model`   | string   | _(unset; falls back to the resolved call-site default)_ | Optional override for the LLM model used in voice call conversations.                                                                                                                                                                                                                                                                              |
+| `services.stt.provider`           | enum     | `'deepgram'`                                            | Global STT provider. Every boundary falls back to it, and a consumer with a `services.stt.roles.<role>` override (`liveVoice`, `telephony`, `dictation`, `watch`, `batch`) uses that instead. The daemon transcribes media-stream call audio with whichever provider the `telephony` role resolves to (streaming when supported, batch otherwise). |
+| `services.stt.language`           | string   | `multi`                                                 | Spoken language for transcription: a BCP-47 code pins one language, `multi` (the schema default) enables code-switching on providers that support it. Per-language TTS voices are configured via `services.tts.providers.<id>.languageVoices`.                                                                                                     |
+| `services.tts.provider`           | enum     | `'elevenlabs'`                                          | Active TTS provider for speech synthesis (catalog-driven; see [TTS Provider Abstraction](../assistant/ARCHITECTURE.md#tts-provider-abstraction-servicestts)).                                                                                                                                                                                      |
+| `services.tts.providers.<id>.*`   | object   | _(per-provider defaults)_                               | Provider-specific settings block. One block per catalog entry (e.g. `elevenlabs`, `fish-audio`).                                                                                                                                                                                                                                                   |
 
 ### Caller Identity Resolution
 
@@ -1158,7 +1158,7 @@ For full details on the catalog-driven TTS architecture, provider catalog, call
 
 ### Telephony STT: Daemon-Side Media-Stream Transcription
 
-Telephony STT is unified under `services.stt.provider`. The voice webhook in `twilio-routes.ts` emits `<Connect><Stream>` TwiML pointing to the gateway's media-stream proxy (`/webhooks/twilio/media-stream/<callSessionId>/<token>`); the gateway forwards raw audio frames to the daemon's media-stream server, which transcribes them itself:
+Telephony STT is unified under `services.stt`: calls resolve the `telephony` role when it is set and `services.stt.provider` otherwise. The voice webhook in `twilio-routes.ts` emits `<Connect><Stream>` TwiML pointing to the gateway's media-stream proxy (`/webhooks/twilio/media-stream/<callSessionId>/<token>`); the gateway forwards raw audio frames to the daemon's media-stream server, which transcribes them itself:
 
 - **Streaming** (default) — when `calls.voice.telephonyStreaming` is enabled and the configured provider resolves a streaming transcriber, audio is decoded (mu-law → PCM16, 8 kHz → 16 kHz) and fed to the provider's realtime adapter; replies trigger only on utterance-boundary finals and barge-in fires from local energy VAD.
 - **Batch fallback** — otherwise turns are segmented with the energy-based VAD turn detector and transcribed via the provider's batch API.

package/Dockerfile

@@ -57,6 +57,9 @@ COPY --chown=gateway:gateway packages/slack-text /app/packages/slack-text
 COPY --chown=gateway:gateway packages/twilio-client /app/packages/twilio-client
 COPY --chown=gateway:gateway gateway /app/gateway
 
+RUN ln -sf /app/gateway/src/cli/index.ts /usr/local/bin/gateway \
+    && chmod +x /app/gateway/src/cli/index.ts
+
 RUN mkdir -p /gateway-security && chown gateway:gateway /gateway-security
 
 COPY packages/block-volume-bootstrap/scripts/*.sh /usr/local/bin/

package/knip.json

@@ -1,5 +1,9 @@
 {
-  "entry": ["src/**/*.test.ts", "src/**/__tests__/**/*.ts"],
+  "entry": [
+    "src/**/*.test.ts",
+    "src/**/__tests__/**/*.ts",
+    "src/cli/index.ts"
+  ],
   "project": ["src/**/*.ts"],
   "ignoreDependencies": [
     "@vellumai/assistant-client",

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/__tests__/ingress.test.ts

@@ -6,8 +6,10 @@ import {
   normalizePublicBaseUrl,
   parseRecordedAssistantId,
   parseTunnelRecord,
+  selectRestartTunnelRecord,
   trimmedNonEmptyString,
   TUNNEL_PROVIDERS,
+  type TunnelRecord,
   velayHostForPlatformHost,
 } from "../ingress.js";
 import {
@@ -221,6 +223,41 @@ describe("parseTunnelRecord", () => {
   });
 });
 
+describe("selectRestartTunnelRecord", () => {
+  const PAIRING: TunnelRecord = {
+    provider: "tailscale",
+    publicBaseUrl: "https://assistant-1.example.ts.net",
+  };
+  const LAST: TunnelRecord = {
+    provider: "ngrok",
+    publicBaseUrl: "https://assistant-1.ngrok.app",
+  };
+
+  test("prefers the pairing tunnel over the last one that ran", () => {
+    // The pairing tunnel deliberately left the older public record beside it,
+    // so naming that one would point at an ingress nobody is using.
+    expect(
+      selectRestartTunnelRecord({ lastTunnel: LAST, pairingTunnel: PAIRING }),
+    ).toEqual(PAIRING);
+  });
+
+  test("falls back to the last tunnel and to null", () => {
+    expect(selectRestartTunnelRecord({ lastTunnel: LAST })).toEqual(LAST);
+    for (const ingress of [undefined, null, {}, "nonsense", 42]) {
+      expect(selectRestartTunnelRecord(ingress)).toBeNull();
+    }
+  });
+
+  test("skips a malformed pairing record for a usable last one", () => {
+    expect(
+      selectRestartTunnelRecord({
+        lastTunnel: LAST,
+        pairingTunnel: { provider: "wireguard", publicBaseUrl: "nope" },
+      }),
+    ).toEqual(LAST);
+  });
+});
+
 describe("trimmedNonEmptyString", () => {
   test("trims and rejects blank or non-string values", () => {
     expect(trimmedNonEmptyString(" assistant-1 ")).toBe("assistant-1");

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/__tests__/remote-web-pairing.test.ts

@@ -0,0 +1,389 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  buildRemoteWebPairingUrl,
+  isDnsIndependentLoopbackUrl,
+  isLoopbackPublicUrl,
+  isPrivateNetworkPublicUrl,
+  isRetryablePairingReason,
+  pairingSessionSurvives,
+  parsePairingAddress,
+  parseRemoteWebPairingParams,
+  resolvePublicBaseUrl,
+  RETRYABLE_PAIRING_REASONS,
+  type PairingFailureReason,
+  type PublicBaseUrlRejection,
+} from "../remote-web-pairing.js";
+
+describe("parseRemoteWebPairingParams", () => {
+  test("reads snake_case fragment parameters", () => {
+    expect(
+      parseRemoteWebPairingParams(
+        "https://assistant.example.com/assistant/pair#device_code=device-1&user_code=ABCD-EFGH",
+      ),
+    ).toEqual({ deviceCode: "device-1", userCode: "ABCD-EFGH" });
+  });
+
+  test("reads camelCase query parameters", () => {
+    expect(
+      parseRemoteWebPairingParams(
+        "https://assistant.example.com/assistant/pair?deviceCode=device-2&userCode=WXYZ-1234",
+      ),
+    ).toEqual({ deviceCode: "device-2", userCode: "WXYZ-1234" });
+  });
+
+  test("accepts a relative link", () => {
+    expect(
+      parseRemoteWebPairingParams("/assistant/pair#device_code=device-3"),
+    ).toEqual({ deviceCode: "device-3", userCode: null });
+  });
+
+  test("reports null when no codes are present", () => {
+    expect(
+      parseRemoteWebPairingParams("https://assistant.example.com/assistant"),
+    ).toEqual({ deviceCode: null, userCode: null });
+  });
+});
+
+describe("parsePairingAddress", () => {
+  test("splits a pairing link into its base and device code", () => {
+    const link = buildRemoteWebPairingUrl({
+      verificationUri: "https://assistant.example.com/assistant/pair",
+      deviceCode: "device-1",
+    });
+
+    expect(parsePairingAddress(link)).toEqual({
+      ok: true,
+      publicBaseUrl: "https://assistant.example.com",
+      deviceCode: "device-1",
+    });
+  });
+
+  test("accepts the device code in the query string", () => {
+    expect(
+      parsePairingAddress(
+        "https://assistant.example.com/assistant/pair?deviceCode=device-2",
+      ),
+    ).toEqual({
+      ok: true,
+      publicBaseUrl: "https://assistant.example.com",
+      deviceCode: "device-2",
+    });
+  });
+
+  test("preserves a path prefix while dropping the app-route suffix", () => {
+    expect(
+      parsePairingAddress(
+        "https://host.example.com/assistant-123/assistant/pair#device_code=device-3",
+      ),
+    ).toEqual({
+      ok: true,
+      publicBaseUrl: "https://host.example.com/assistant-123",
+      deviceCode: "device-3",
+    });
+  });
+
+  test("drops a trailing app-route suffix from a bare address", () => {
+    expect(
+      parsePairingAddress("https://assistant.example.com/assistant/pair"),
+    ).toEqual({
+      ok: true,
+      publicBaseUrl: "https://assistant.example.com",
+      deviceCode: null,
+    });
+  });
+
+  test("accepts a bare address with no device code", () => {
+    expect(parsePairingAddress("https://assistant.example.com")).toEqual({
+      ok: true,
+      publicBaseUrl: "https://assistant.example.com",
+      deviceCode: null,
+    });
+  });
+
+  test.each<[string, PublicBaseUrlRejection]>([
+    ["not a url", "unparseable"],
+    ["https://localhost:3000", "loopback"],
+    ["https://127.0.0.1:3000", "loopback"],
+    ["http://assistant.example.com", "non-https"],
+    ["https://login.tailscale.com/admin/invite/abc123", "service-website"],
+  ])("rejects %s", (raw, reason) => {
+    expect(parsePairingAddress(raw)).toEqual({ ok: false, reason });
+  });
+});
+
+describe("resolvePublicBaseUrl private-address containment", () => {
+  // A host POSTs to whatever address was pasted, so an IP literal aimed at the
+  // local network (or at 169.254.169.254, the cloud instance metadata
+  // endpoint) is a blind SSRF target and is refused before any request.
+  test.each([
+    ["https://0.0.0.0", "0/8"],
+    ["https://10.0.0.1", "10/8"],
+    ["https://10.255.255.254:8443", "10/8 with a port"],
+    ["https://169.254.169.254", "169.254/16 cloud metadata"],
+    ["https://172.16.0.1", "172.16/12 low edge"],
+    ["https://172.31.255.254", "172.16/12 high edge"],
+    ["https://192.0.0.8", "192.0.0/24"],
+    ["https://192.168.1.5", "192.168/16"],
+    ["https://198.18.0.1", "198.18/15"],
+    ["https://198.19.255.254", "198.18/15 high half"],
+    ["https://224.0.0.1", "224/4 multicast"],
+    ["https://240.0.0.1", "240/4 reserved"],
+    ["https://255.255.255.255", "broadcast"],
+    // WHATWG URL canonicalizes these to a dotted-quad before the check.
+    ["https://2130706433", "decimal-encoded 127.0.0.1"],
+    ["https://0xa000001", "hex-encoded 10.0.0.1"],
+    ["https://[::]", "IPv6 unspecified"],
+    ["https://[fd00::1]", "fc00::/7 unique-local"],
+    ["https://[fc00::5]", "fc00::/7 low edge"],
+    ["https://[fe80::1]", "fe80::/10 link-local"],
+    ["https://[ff02::1]", "ff00::/8 multicast"],
+    ["https://[::ffff:10.0.0.1]", "IPv4-mapped private"],
+    ["https://[::ffff:169.254.169.254]", "IPv4-mapped metadata"],
+    ["https://[::192.168.1.5]", "IPv4-compatible private"],
+  ])("refuses %s (%s)", (raw) => {
+    const result = resolvePublicBaseUrl(raw);
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    // 127/8 and ::1 keep their more specific loopback reason.
+    expect(["private-address", "loopback"]).toContain(result.reason);
+  });
+
+  test.each([
+    "https://10.0.0.1",
+    "https://169.254.169.254",
+    "https://172.20.3.4",
+    "https://192.168.1.5",
+    "https://198.18.0.1",
+    "https://[fd00::1]",
+    "https://[fe80::1]",
+    "https://[::ffff:10.0.0.1]",
+  ])("reports %s as private-address, not loopback", (raw) => {
+    expect(resolvePublicBaseUrl(raw)).toEqual({
+      ok: false,
+      reason: "private-address",
+    });
+  });
+
+  // A wildcard bind reaches a listener on the machine that dials it, so it
+  // gets the more specific loopback reason and the "points back at this
+  // machine" guidance that goes with it.
+  test.each([
+    ["https://0.0.0.0", "IPv4 wildcard"],
+    ["https://[::]", "IPv6 wildcard"],
+    ["https://[::ffff:0.0.0.0]", "IPv4-mapped wildcard"],
+    ["https://[::ffff:127.0.0.1]", "IPv4-mapped loopback"],
+  ])("reports %s (%s) as loopback", (raw) => {
+    expect(isLoopbackPublicUrl(raw)).toBe(true);
+    expect(resolvePublicBaseUrl(raw)).toEqual({
+      ok: false,
+      reason: "loopback",
+    });
+  });
+
+  // Tailscale hands out 100.64.0.0/10 CGNAT addresses and `*.ts.net` names are
+  // a supported pairing target, so neither the range nor any hostname is
+  // filtered. Names are never resolved (see isPrivateNetworkPublicUrl).
+  test.each([
+    "https://my-box.tail1234.ts.net",
+    "https://assistant.example.com",
+    "https://100.101.102.103",
+    "https://[2606:4700::1111]",
+    "https://172.32.0.1",
+    "https://192.0.1.1",
+    "https://198.20.0.1",
+    "https://223.255.255.255",
+  ])("still resolves %s", (raw) => {
+    expect(resolvePublicBaseUrl(raw)).toEqual({ ok: true, url: raw });
+  });
+
+  test("isPrivateNetworkPublicUrl reports a plain hostname as public", () => {
+    expect(isPrivateNetworkPublicUrl("https://my-box.tail1234.ts.net")).toBe(
+      false,
+    );
+    expect(isPrivateNetworkPublicUrl("not a url")).toBe(false);
+    expect(isPrivateNetworkPublicUrl("https://192.168.0.1")).toBe(true);
+  });
+});
+
+describe("resolvePublicBaseUrl localhost normalization", () => {
+  // A terminal DNS root dot survives WHATWG parsing, and resolvers read the
+  // absolute name as loopback, so the dot is stripped before every host
+  // comparison. The whole `.localhost` namespace is reserved (RFC 6761) and
+  // resolves to loopback too.
+  test.each([
+    ["https://localhost.", "absolute localhost name"],
+    ["https://localhost.:3000", "absolute localhost name with a port"],
+    ["https://LOCALHOST.", "uppercase absolute localhost name"],
+    ["https://foo.localhost", "reserved .localhost namespace"],
+    ["https://foo.localhost.", "absolute .localhost namespace"],
+    ["https://a.b.localhost.", "nested .localhost namespace"],
+    ["https://127.0.0.1.", "absolute IPv4 loopback literal"],
+  ])("reports %s (%s) as loopback", (raw) => {
+    expect(isLoopbackPublicUrl(raw)).toBe(true);
+    expect(resolvePublicBaseUrl(raw)).toEqual({
+      ok: false,
+      reason: "loopback",
+    });
+  });
+
+  test("reports an absolute private literal as private-address", () => {
+    expect(isPrivateNetworkPublicUrl("https://10.0.0.1.")).toBe(true);
+    expect(resolvePublicBaseUrl("https://10.0.0.1.")).toEqual({
+      ok: false,
+      reason: "private-address",
+    });
+  });
+
+  test("reports an absolute vendor-site name as service-website", () => {
+    expect(resolvePublicBaseUrl("https://login.tailscale.com.")).toEqual({
+      ok: false,
+      reason: "service-website",
+    });
+  });
+
+  test.each([
+    "https://my-box.tail1234.ts.net.",
+    "https://assistant.example.com.",
+    "https://localhostage.example.com",
+    "https://mylocalhost.example.com.",
+  ])("still resolves %s", (raw) => {
+    expect(isLoopbackPublicUrl(raw)).toBe(false);
+    expect(resolvePublicBaseUrl(raw)).toEqual({ ok: true, url: raw });
+  });
+});
+
+describe("isDnsIndependentLoopbackUrl", () => {
+  test.each([
+    ["http://localhost:7830", "the exact name"],
+    ["http://LOCALHOST.:7830", "the absolute, uppercase name"],
+    ["http://127.0.0.1:7830", "an IPv4 loopback literal"],
+    ["http://127.9.9.9", "the rest of 127/8"],
+    ["http://[::1]:7830", "the IPv6 loopback literal"],
+    ["http://[::ffff:127.0.0.1]", "an IPv4-mapped loopback literal"],
+    ["http://0.0.0.0:7830", "the IPv4 wildcard bind"],
+    ["http://[::]:7830", "the IPv6 wildcard bind"],
+  ])("%s reaches this machine (%s)", (raw) => {
+    expect(isDnsIndependentLoopbackUrl(raw)).toBe(true);
+    expect(isLoopbackPublicUrl(raw)).toBe(true);
+  });
+
+  // RFC 6761 reserves the namespace and says resolvers should map it to
+  // loopback, but glibc does not by default, so the name is ordinary DNS and
+  // can answer with any address. The wide predicate still refuses it as
+  // loopback; the narrow one refuses to hand it a loopback privilege.
+  test.each([
+    ["https://foo.localhost", "reserved .localhost namespace"],
+    ["https://foo.localhost.", "absolute .localhost namespace"],
+    ["https://a.b.localhost", "nested .localhost namespace"],
+  ])("%s is loopback but not DNS-independent (%s)", (raw) => {
+    expect(isLoopbackPublicUrl(raw)).toBe(true);
+    expect(isDnsIndependentLoopbackUrl(raw)).toBe(false);
+  });
+
+  test.each([
+    "https://assistant.example.com",
+    "https://localhostage.example.com",
+    "https://10.0.0.5",
+    "not a url",
+  ])("%s is not loopback at all", (raw) => {
+    expect(isDnsIndependentLoopbackUrl(raw)).toBe(false);
+    expect(isLoopbackPublicUrl(raw)).toBe(false);
+  });
+});
+
+/** Every reason, so a classification table cannot silently miss one. */
+const EVERY_PAIRING_REASON: PairingFailureReason[] = [
+  "invalid-address",
+  "unknown-session",
+  "expired",
+  "unreachable",
+  "gateway-retryable",
+  "gateway",
+  "import",
+  "import-precheck",
+];
+
+describe("isRetryablePairingReason", () => {
+  test.each([
+    // Nothing reached the assistant, so the session and code are untouched.
+    "unreachable",
+    // The assistant refused with a status that released the code.
+    "gateway-retryable",
+  ] as const)("%s is worth another attempt", (reason) => {
+    expect(isRetryablePairingReason(reason)).toBe(true);
+  });
+
+  test.each([
+    "invalid-address",
+    "unknown-session",
+    "expired",
+    // The assistant answered with something unusable, past which the code is
+    // spent rather than released.
+    "gateway",
+    "import",
+    // Nothing was spent, but an identical attempt is refused identically:
+    // only a caller that changes the name it asked for gets past this.
+    "import-precheck",
+  ] as const)("%s settles the attempt", (reason) => {
+    expect(isRetryablePairingReason(reason)).toBe(false);
+  });
+
+  test("an absent reason settles the attempt", () => {
+    expect(isRetryablePairingReason(undefined)).toBe(false);
+    expect(isRetryablePairingReason(null)).toBe(false);
+  });
+
+  test("the exported set is exactly the reasons worth another attempt", () => {
+    expect(
+      EVERY_PAIRING_REASON.filter(isRetryablePairingReason).sort(),
+    ).toEqual(["gateway-retryable", "unreachable"]);
+    expect([...RETRYABLE_PAIRING_REASONS].sort()).toEqual([
+      "gateway-retryable",
+      "unreachable",
+    ]);
+  });
+});
+
+describe("pairingSessionSurvives", () => {
+  test.each([
+    // Nothing reached the assistant, so the session and code are untouched.
+    "unreachable",
+    // The assistant released the code before answering.
+    "gateway-retryable",
+    // The refusal happened before the exchange, so the code is unspent.
+    "import-precheck",
+  ] as const)("%s leaves the session pollable", (reason) => {
+    expect(pairingSessionSurvives(reason)).toBe(true);
+  });
+
+  test.each([
+    "invalid-address",
+    "unknown-session",
+    "expired",
+    "gateway",
+    // The exchange spent the code; only the local write failed.
+    "import",
+  ] as const)("%s leaves nothing to poll", (reason) => {
+    expect(pairingSessionSurvives(reason)).toBe(false);
+  });
+
+  test("an absent reason leaves nothing to poll", () => {
+    expect(pairingSessionSurvives(undefined)).toBe(false);
+    expect(pairingSessionSurvives(null)).toBe(false);
+  });
+
+  test("a pre-check refusal is the one reason the two axes disagree on", () => {
+    // A caller that reads retryability as "keep the session" throws away a
+    // device code that is still good, which is what this reason exists to
+    // prevent: nothing was spent, so the same handle completes the pairing
+    // once the caller supplies a name that is free.
+    const disagreeing = EVERY_PAIRING_REASON.filter(
+      (reason) =>
+        pairingSessionSurvives(reason) !== isRetryablePairingReason(reason),
+    );
+    expect(disagreeing).toEqual(["import-precheck"]);
+  });
+});

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/ingress.ts

@@ -147,6 +147,28 @@ export function parseTunnelRecord(value: unknown): TunnelRecord | null {
   return { provider, publicBaseUrl: normalized };
 }
 
+/**
+ * The tunnel a reader should offer to restart, given an `ingress` section, or
+ * null when it records none.
+ *
+ * A pairing-only record wins: it is written by a tunnel that deliberately left
+ * `publicBaseUrl` (and the `lastTunnel` beside it) pointing at an older public
+ * provider, so naming that older one would send the user to rebuild an ingress
+ * they are not using instead of the tunnel actually in front of them.
+ */
+export function selectRestartTunnelRecord(
+  ingress: unknown,
+): TunnelRecord | null {
+  if (typeof ingress !== "object" || ingress === null) {
+    return null;
+  }
+  const section = ingress as Record<string, unknown>;
+  return (
+    parseTunnelRecord(section[INGRESS_PAIRING_TUNNEL_KEY]) ??
+    parseTunnelRecord(section[INGRESS_LAST_TUNNEL_KEY])
+  );
+}
+
 /** Parse an `ingress.assistantId` value, or null when it is absent or blank. */
 export function parseRecordedAssistantId(value: unknown): string | null {
   return trimmedNonEmptyString(value) ?? null;