@vellumai/assistant 0.11.5 → 0.11.6-dev.202608252309.48526e7

package/AGENTS.md

@@ -2,7 +2,11 @@
 
 For error handling conventions (throw vs result objects vs null), see [docs/error-handling.md](docs/error-handling.md).
 
-Subdirectory-scoped rules live in local AGENTS.md files: `src/cli/`, `src/runtime/`, `src/approvals/`, `src/notifications/`, `src/permissions/`, `src/plugins/`, `src/workspace/migrations/`.
+Subdirectory-scoped rules live in local AGENTS.md files throughout `src/`, some
+of them nested several levels down. Read the one nearest the code you are
+changing plus any above it, and follow the nearest where two disagree.
+`git ls-files ':(top)assistant/src/**/AGENTS.md'` lists them from anywhere in
+the tree.
 
 ## Adding new environment variables
 

package/ARCHITECTURE.md

@@ -84,7 +84,7 @@ All HTTP API requests use a single `Authorization: Bearer <jwt>` header for auth
 
 **Identity lifecycle:**
 
-1. **Bootstrap (loopback-only, macOS)** — On first launch, the macOS client calls `POST /v1/guardian/init` with `{ platform, deviceId }`. The endpoint is loopback-only and mints a JWT access token + refresh token pair. Returns `{ guardianPrincipalId, accessToken, accessTokenExpiresAt, refreshToken, refreshTokenExpiresAt, refreshAfter, isNew }`. The CLI obtains its bearer token during `hatch` and does not perform a separate bootstrap step.
+1. **Bootstrap (loopback-only, desktop)**: On first launch, the desktop client calls `POST /v1/guardian/init` with `{ platform, deviceId }`. The endpoint is loopback-only and mints a JWT access token + refresh token pair. Returns `{ guardianPrincipalId, accessToken, accessTokenExpiresAt, refreshToken, refreshTokenExpiresAt, refreshAfter, isNew }`. The CLI obtains its bearer token during `hatch` and does not perform a separate bootstrap step.
 
 2. **Refresh** — `POST /v1/guardian/refresh` accepts `{ refreshToken }` and returns a new access/refresh token pair. Single-use rotation with replay detection and family-based revocation.
 

package/docs/flux-turn-detection-spike.md

@@ -59,7 +59,7 @@ If it does not, set the Deepgram key the ordinary way (client Settings, Speech-t
 
 ## 2. Enable Flux
 
-> **Setting `services.stt.provider` to `deepgram-flux` turns off batch transcription for the whole workspace, not just live voice.** `services.stt.provider` is the single source of truth for every STT route, and Flux is the only provider in the catalog with no `daemon-batch` boundary. For as long as it is set, these all stop working: voice-message and inbound-attachment transcription, the `transcribe` skill, the `media-processing` skill's audio segments, `POST /v1/stt/transcribe`, and phone-call transcription. Each reports a message naming Flux as the cause rather than failing silently, but they do not fall back to `deepgram` on their own. **Set `services.stt.provider` back to `deepgram` when the spike is over**, and do not run the spike on an assistant that is also taking calls or handling voice messages.
+> **Putting a provider on the `flux` model family turns off batch transcription for the whole workspace, not just live voice.** `services.stt.provider` plus `services.stt.providers.<provider>.model` is the single source of truth for every STT route, and Flux is the only family in the catalog with no `daemon-batch` boundary. For as long as it is set, these all stop working: voice-message and inbound-attachment transcription, the `transcribe` skill, the `media-processing` skill's audio segments, `POST /v1/stt/transcribe`, and phone-call transcription. Each reports a message naming Flux as the cause rather than failing silently, but they do not fall back to `deepgram` on their own. **Set `services.stt.providers.deepgram.model` back to `nova-3` when the spike is over**, and do not run the spike on an assistant that is also taking calls or handling voice messages.
 
 Two keys in `config.json`, which lives at `$VELLUM_WORKSPACE_DIR/config.json` (default `~/.vellum/workspace/config.json`):
 
@@ -67,7 +67,8 @@ Two keys in `config.json`, which lives at `$VELLUM_WORKSPACE_DIR/config.json` (d
 {
   "services": {
     "stt": {
-      "provider": "deepgram-flux"
+      "provider": "deepgram",
+      "providers": { "deepgram": { "model": "flux" } }
     }
   },
   "liveVoice": {
@@ -93,12 +94,12 @@ The rest of `liveVoice.flux` is optional and defaulted (`config/schemas/live-voi
 
 ## 3. Run the A/B
 
-**Flip `turnEnd.enabled` between runs and leave `services.stt.provider` on `deepgram-flux` in both arms.** That holds the STT engine, the model, the socket, and the transcriber lifecycle constant, so the only thing that changes is which signal commits the turn.
+**Flip `turnEnd.enabled` between runs and leave the `flux` model family selected in both arms.** That holds the STT engine, the model, the socket, and the transcriber lifecycle constant, so the only thing that changes is which signal commits the turn.
 
-- **Arm A (control):** `provider: "deepgram-flux"`, `turnEnd.enabled: false`. Flux transcribes; the four turn-detection events are ignored; the local silence boundary and the front-door hold path run exactly as they do today.
-- **Arm B (treatment):** `provider: "deepgram-flux"`, `turnEnd.enabled: true`.
+- **Arm A (control):** `providers.deepgram.model: "flux"`, `turnEnd.enabled: false`. Flux transcribes; the four turn-detection events are ignored; the local silence boundary and the front-door hold path run exactly as they do today.
+- **Arm B (treatment):** `providers.deepgram.model: "flux"`, `turnEnd.enabled: true`.
 
-**Do not A/B by switching the provider between `deepgram` and `deepgram-flux`.** That confounds two changes at once:
+**Do not A/B by switching the model family between `nova-3` and `flux`.** That confounds two changes at once:
 
 1. It swaps the STT model. `deepgram` runs `nova-2` (`DEFAULT_MODEL`, `deepgram-realtime.ts`), so any transcript-quality or first-partial difference lands in your latency numbers.
 2. It swaps the transcriber lifecycle. `deepgram` implements `finalizeUtterance`, so the session adopts it as a persistent stream shared across the whole session (`sharedTranscriber`) and never tears it down between turns. Flux implements no `finalizeUtterance`, so every utterance owns its own `/v2/listen` socket and every release closes it. That per-turn socket churn is inside `roundTripMs` and `totalMs` on the Flux side and absent on the `deepgram` side, so a naive provider-swap A/B attributes it to turn detection. The next section is what it costs and why it cannot be removed.
@@ -230,7 +231,7 @@ Check these if you port the spike anywhere else, because a run that violates eit
 
 ## 8. Falling back
 
-Set `liveVoice.flux.turnEnd.enabled` back to `false` (or delete the key) and restart. That is the whole rollback: the latch goes down, the turn-detection events become no-ops, and the silence-boundary path runs unchanged. You can leave `services.stt.provider` on `deepgram-flux` or move it back to `deepgram`; either is a working configuration.
+Set `liveVoice.flux.turnEnd.enabled` back to `false` (or delete the key) and restart. That is the whole rollback: the latch goes down, the turn-detection events become no-ops, and the silence-boundary path runs unchanged. You can leave the `flux` family selected or move back to `nova-3`; either is a working configuration.
 
 Runtime fallback needs no action. A Flux stream that never emits `turn-end` is caught by the fail-open deadline and the utterance replays onto the silence path, so an outage degrades to today's behavior rather than to a hung turn.
 

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

@@ -2,7 +2,12 @@ import { describe, expect, test } from "bun:test";
 
 import {
   normalizeHttpPublicBaseUrl,
+  normalizeHttpPublicBaseUrlWithoutTrailingSlash,
   normalizePublicBaseUrl,
+  parseRecordedAssistantId,
+  parseTunnelRecord,
+  trimmedNonEmptyString,
+  TUNNEL_PROVIDERS,
   velayHostForPlatformHost,
 } from "../ingress.js";
 import {
@@ -85,6 +90,35 @@ describe("normalizeHttpPublicBaseUrl", () => {
   });
 });
 
+describe("normalizeHttpPublicBaseUrlWithoutTrailingSlash", () => {
+  test("drops the root path its sibling always emits", () => {
+    expect(
+      normalizeHttpPublicBaseUrlWithoutTrailingSlash("https://x.test"),
+    ).toBe("https://x.test");
+    expect(
+      normalizeHttpPublicBaseUrlWithoutTrailingSlash("https://x.test/"),
+    ).toBe("https://x.test");
+    expect(
+      normalizeHttpPublicBaseUrlWithoutTrailingSlash(" https://x.test/api/// "),
+    ).toBe("https://x.test/api");
+  });
+
+  test("rejects everything its sibling rejects", () => {
+    for (const value of [
+      "",
+      "   ",
+      "notaurl",
+      "ftp://x.test",
+      "https://x.test?a=b",
+      42,
+    ]) {
+      expect(
+        normalizeHttpPublicBaseUrlWithoutTrailingSlash(value),
+      ).toBeUndefined();
+    }
+  });
+});
+
 describe("Twilio ingress helpers", () => {
   test("resolves public base URL with fallback", () => {
     expect(
@@ -123,3 +157,87 @@ describe("Twilio ingress helpers", () => {
     });
   });
 });
+
+describe("parseTunnelRecord", () => {
+  const TUNNEL_URL = "https://assistant-1.example.ts.net";
+
+  test("accepts every provider in the registry", () => {
+    for (const provider of TUNNEL_PROVIDERS) {
+      expect(
+        parseTunnelRecord({ provider, publicBaseUrl: TUNNEL_URL }),
+      ).toEqual({ provider, publicBaseUrl: TUNNEL_URL });
+    }
+  });
+
+  test("returns the URL in the shape its own validator produces", () => {
+    // Padding and trailing slashes are normalized away rather than handed
+    // back, so readers never re-normalize what they were given.
+    for (const publicBaseUrl of [
+      ` ${TUNNEL_URL} `,
+      `${TUNNEL_URL}/`,
+      `${TUNNEL_URL}///`,
+    ]) {
+      expect(
+        parseTunnelRecord({ provider: "ngrok", publicBaseUrl }),
+      ).toEqual({ provider: "ngrok", publicBaseUrl: TUNNEL_URL });
+    }
+  });
+
+  test("rejects values that are not a record", () => {
+    for (const value of [undefined, null, "nonsense", 42, []]) {
+      expect(parseTunnelRecord(value)).toBeNull();
+    }
+  });
+
+  test("rejects a record missing either field", () => {
+    expect(parseTunnelRecord({ provider: "ngrok" })).toBeNull();
+    expect(parseTunnelRecord({ publicBaseUrl: TUNNEL_URL })).toBeNull();
+  });
+
+  test("rejects a provider outside the registry", () => {
+    // Readers render the provider into a `vellum tunnel --provider <name>`
+    // command, so a hand-edited config must not reach a terminal.
+    for (const provider of ["wireguard", "; rm -rf /", "", 42]) {
+      expect(
+        parseTunnelRecord({ provider, publicBaseUrl: TUNNEL_URL }),
+      ).toBeNull();
+    }
+  });
+
+  test("rejects a URL that is not absolute HTTP(S)", () => {
+    for (const publicBaseUrl of [
+      "",
+      "   ",
+      "not-a-url",
+      "example.ts.net",
+      "ftp://x.test",
+      "https://one.ngrok.app?token=x",
+      42,
+    ]) {
+      expect(
+        parseTunnelRecord({ provider: "ngrok", publicBaseUrl }),
+      ).toBeNull();
+    }
+  });
+});
+
+describe("trimmedNonEmptyString", () => {
+  test("trims and rejects blank or non-string values", () => {
+    expect(trimmedNonEmptyString(" assistant-1 ")).toBe("assistant-1");
+    for (const value of ["", "   ", undefined, null, 42]) {
+      expect(trimmedNonEmptyString(value)).toBeUndefined();
+    }
+  });
+});
+
+describe("parseRecordedAssistantId", () => {
+  test("trims a recorded id", () => {
+    expect(parseRecordedAssistantId(" assistant-1 ")).toBe("assistant-1");
+  });
+
+  test("rejects blank and non-string values", () => {
+    for (const value of ["", "   ", undefined, null, 42]) {
+      expect(parseRecordedAssistantId(value)).toBeNull();
+    }
+  });
+});

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

@@ -48,3 +48,106 @@ export function normalizeHttpPublicBaseUrl(value: unknown): string | undefined {
     return undefined;
   }
 }
+
+/**
+ * The same validation as `normalizeHttpPublicBaseUrl`, minus the root path it
+ * always emits (`https://x` becomes `https://x/`). Callers that append a path
+ * or persist the result want this shape, so they neither join through a double
+ * slash nor re-strip what the normalizer just added.
+ */
+export function normalizeHttpPublicBaseUrlWithoutTrailingSlash(
+  value: unknown,
+): string | undefined {
+  return normalizePublicBaseUrl(normalizeHttpPublicBaseUrl(value));
+}
+
+/**
+ * A trimmed string, or undefined when the value is not a non-blank string.
+ *
+ * Exported because the identity check in the daemon's tunnel probe compares an
+ * id recorded here against one an edge serves, and the two sides have to trim
+ * alike: a padded served id must read as a match, not as a different
+ * assistant.
+ */
+export function trimmedNonEmptyString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+// Records `vellum tunnel` leaves in the workspace config's `ingress` section.
+// The CLI writes them and the daemon reads them, and the two are separate
+// build units that cannot import each other, so the key names, the provider
+// allowlist, and the validation all live here rather than in a copy on each
+// side.
+
+/** Key under `ingress` holding the tunnel that most recently ran. */
+export const INGRESS_LAST_TUNNEL_KEY = "lastTunnel";
+
+/**
+ * Key under `ingress` holding a tunnel published for device pairing alone.
+ *
+ * A tailnet-only tunnel started while webhook integrations are configured
+ * cannot carry their callbacks, so it leaves `publicBaseUrl` (the callback
+ * base) as it is and records itself here. Readers that answer the pairing card
+ * prefer this address over `publicBaseUrl`; teardown drops the key.
+ */
+export const INGRESS_PAIRING_TUNNEL_KEY = "pairingTunnel";
+
+/** Key under `ingress` holding the assistant id that tunnel fronted. */
+export const INGRESS_ASSISTANT_ID_KEY = "assistantId";
+
+/**
+ * The local tunnel providers the CLI can start, in the order they are offered.
+ * `vellum tunnel`'s accepted `--provider` values and the persisted-record
+ * validation below both derive from it.
+ */
+export const TUNNEL_PROVIDERS = ["ngrok", "cloudflare", "tailscale"] as const;
+
+export type TunnelProviderName = (typeof TUNNEL_PROVIDERS)[number];
+
+/** A recorded tunnel, kept after teardown so UIs can name the command to restart. */
+export interface TunnelRecord {
+  provider: TunnelProviderName;
+  publicBaseUrl: string;
+}
+
+function isTunnelProviderName(value: unknown): value is TunnelProviderName {
+  return (
+    typeof value === "string" &&
+    (TUNNEL_PROVIDERS as readonly string[]).includes(value)
+  );
+}
+
+/**
+ * Parse an `ingress.lastTunnel` or `ingress.pairingTunnel` value, or null when
+ * it is absent or malformed.
+ *
+ * A hand-edited config must not hand callers an unusable address or a provider
+ * name no command accepts: the provider is checked against the allowlist
+ * because readers render it into a restart command, and the URL faces the same
+ * absolute HTTP(S) constraint as every other public base URL. The URL comes
+ * back in the shape the validator produced, so readers never re-normalize it.
+ */
+export function parseTunnelRecord(value: unknown): TunnelRecord | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  const { provider, publicBaseUrl } = value as Record<string, unknown>;
+  if (!isTunnelProviderName(provider)) {
+    return null;
+  }
+  const normalized =
+    normalizeHttpPublicBaseUrlWithoutTrailingSlash(publicBaseUrl);
+  if (normalized === undefined) {
+    return null;
+  }
+  return { provider, publicBaseUrl: normalized };
+}
+
+/** Parse an `ingress.assistantId` value, or null when it is absent or blank. */
+export function parseRecordedAssistantId(value: unknown): string | null {
+  return trimmedNonEmptyString(value) ?? null;
+}

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

@@ -2,7 +2,12 @@ import { describe, expect, test } from "bun:test";
 
 import {
   normalizeHttpPublicBaseUrl,
+  normalizeHttpPublicBaseUrlWithoutTrailingSlash,
   normalizePublicBaseUrl,
+  parseRecordedAssistantId,
+  parseTunnelRecord,
+  trimmedNonEmptyString,
+  TUNNEL_PROVIDERS,
   velayHostForPlatformHost,
 } from "../ingress.js";
 import {
@@ -85,6 +90,35 @@ describe("normalizeHttpPublicBaseUrl", () => {
   });
 });
 
+describe("normalizeHttpPublicBaseUrlWithoutTrailingSlash", () => {
+  test("drops the root path its sibling always emits", () => {
+    expect(
+      normalizeHttpPublicBaseUrlWithoutTrailingSlash("https://x.test"),
+    ).toBe("https://x.test");
+    expect(
+      normalizeHttpPublicBaseUrlWithoutTrailingSlash("https://x.test/"),
+    ).toBe("https://x.test");
+    expect(
+      normalizeHttpPublicBaseUrlWithoutTrailingSlash(" https://x.test/api/// "),
+    ).toBe("https://x.test/api");
+  });
+
+  test("rejects everything its sibling rejects", () => {
+    for (const value of [
+      "",
+      "   ",
+      "notaurl",
+      "ftp://x.test",
+      "https://x.test?a=b",
+      42,
+    ]) {
+      expect(
+        normalizeHttpPublicBaseUrlWithoutTrailingSlash(value),
+      ).toBeUndefined();
+    }
+  });
+});
+
 describe("Twilio ingress helpers", () => {
   test("resolves public base URL with fallback", () => {
     expect(
@@ -123,3 +157,87 @@ describe("Twilio ingress helpers", () => {
     });
   });
 });
+
+describe("parseTunnelRecord", () => {
+  const TUNNEL_URL = "https://assistant-1.example.ts.net";
+
+  test("accepts every provider in the registry", () => {
+    for (const provider of TUNNEL_PROVIDERS) {
+      expect(
+        parseTunnelRecord({ provider, publicBaseUrl: TUNNEL_URL }),
+      ).toEqual({ provider, publicBaseUrl: TUNNEL_URL });
+    }
+  });
+
+  test("returns the URL in the shape its own validator produces", () => {
+    // Padding and trailing slashes are normalized away rather than handed
+    // back, so readers never re-normalize what they were given.
+    for (const publicBaseUrl of [
+      ` ${TUNNEL_URL} `,
+      `${TUNNEL_URL}/`,
+      `${TUNNEL_URL}///`,
+    ]) {
+      expect(
+        parseTunnelRecord({ provider: "ngrok", publicBaseUrl }),
+      ).toEqual({ provider: "ngrok", publicBaseUrl: TUNNEL_URL });
+    }
+  });
+
+  test("rejects values that are not a record", () => {
+    for (const value of [undefined, null, "nonsense", 42, []]) {
+      expect(parseTunnelRecord(value)).toBeNull();
+    }
+  });
+
+  test("rejects a record missing either field", () => {
+    expect(parseTunnelRecord({ provider: "ngrok" })).toBeNull();
+    expect(parseTunnelRecord({ publicBaseUrl: TUNNEL_URL })).toBeNull();
+  });
+
+  test("rejects a provider outside the registry", () => {
+    // Readers render the provider into a `vellum tunnel --provider <name>`
+    // command, so a hand-edited config must not reach a terminal.
+    for (const provider of ["wireguard", "; rm -rf /", "", 42]) {
+      expect(
+        parseTunnelRecord({ provider, publicBaseUrl: TUNNEL_URL }),
+      ).toBeNull();
+    }
+  });
+
+  test("rejects a URL that is not absolute HTTP(S)", () => {
+    for (const publicBaseUrl of [
+      "",
+      "   ",
+      "not-a-url",
+      "example.ts.net",
+      "ftp://x.test",
+      "https://one.ngrok.app?token=x",
+      42,
+    ]) {
+      expect(
+        parseTunnelRecord({ provider: "ngrok", publicBaseUrl }),
+      ).toBeNull();
+    }
+  });
+});
+
+describe("trimmedNonEmptyString", () => {
+  test("trims and rejects blank or non-string values", () => {
+    expect(trimmedNonEmptyString(" assistant-1 ")).toBe("assistant-1");
+    for (const value of ["", "   ", undefined, null, 42]) {
+      expect(trimmedNonEmptyString(value)).toBeUndefined();
+    }
+  });
+});
+
+describe("parseRecordedAssistantId", () => {
+  test("trims a recorded id", () => {
+    expect(parseRecordedAssistantId(" assistant-1 ")).toBe("assistant-1");
+  });
+
+  test("rejects blank and non-string values", () => {
+    for (const value of ["", "   ", undefined, null, 42]) {
+      expect(parseRecordedAssistantId(value)).toBeNull();
+    }
+  });
+});

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

@@ -48,3 +48,106 @@ export function normalizeHttpPublicBaseUrl(value: unknown): string | undefined {
     return undefined;
   }
 }
+
+/**
+ * The same validation as `normalizeHttpPublicBaseUrl`, minus the root path it
+ * always emits (`https://x` becomes `https://x/`). Callers that append a path
+ * or persist the result want this shape, so they neither join through a double
+ * slash nor re-strip what the normalizer just added.
+ */
+export function normalizeHttpPublicBaseUrlWithoutTrailingSlash(
+  value: unknown,
+): string | undefined {
+  return normalizePublicBaseUrl(normalizeHttpPublicBaseUrl(value));
+}
+
+/**
+ * A trimmed string, or undefined when the value is not a non-blank string.
+ *
+ * Exported because the identity check in the daemon's tunnel probe compares an
+ * id recorded here against one an edge serves, and the two sides have to trim
+ * alike: a padded served id must read as a match, not as a different
+ * assistant.
+ */
+export function trimmedNonEmptyString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+// Records `vellum tunnel` leaves in the workspace config's `ingress` section.
+// The CLI writes them and the daemon reads them, and the two are separate
+// build units that cannot import each other, so the key names, the provider
+// allowlist, and the validation all live here rather than in a copy on each
+// side.
+
+/** Key under `ingress` holding the tunnel that most recently ran. */
+export const INGRESS_LAST_TUNNEL_KEY = "lastTunnel";
+
+/**
+ * Key under `ingress` holding a tunnel published for device pairing alone.
+ *
+ * A tailnet-only tunnel started while webhook integrations are configured
+ * cannot carry their callbacks, so it leaves `publicBaseUrl` (the callback
+ * base) as it is and records itself here. Readers that answer the pairing card
+ * prefer this address over `publicBaseUrl`; teardown drops the key.
+ */
+export const INGRESS_PAIRING_TUNNEL_KEY = "pairingTunnel";
+
+/** Key under `ingress` holding the assistant id that tunnel fronted. */
+export const INGRESS_ASSISTANT_ID_KEY = "assistantId";
+
+/**
+ * The local tunnel providers the CLI can start, in the order they are offered.
+ * `vellum tunnel`'s accepted `--provider` values and the persisted-record
+ * validation below both derive from it.
+ */
+export const TUNNEL_PROVIDERS = ["ngrok", "cloudflare", "tailscale"] as const;
+
+export type TunnelProviderName = (typeof TUNNEL_PROVIDERS)[number];
+
+/** A recorded tunnel, kept after teardown so UIs can name the command to restart. */
+export interface TunnelRecord {
+  provider: TunnelProviderName;
+  publicBaseUrl: string;
+}
+
+function isTunnelProviderName(value: unknown): value is TunnelProviderName {
+  return (
+    typeof value === "string" &&
+    (TUNNEL_PROVIDERS as readonly string[]).includes(value)
+  );
+}
+
+/**
+ * Parse an `ingress.lastTunnel` or `ingress.pairingTunnel` value, or null when
+ * it is absent or malformed.
+ *
+ * A hand-edited config must not hand callers an unusable address or a provider
+ * name no command accepts: the provider is checked against the allowlist
+ * because readers render it into a restart command, and the URL faces the same
+ * absolute HTTP(S) constraint as every other public base URL. The URL comes
+ * back in the shape the validator produced, so readers never re-normalize it.
+ */
+export function parseTunnelRecord(value: unknown): TunnelRecord | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  const { provider, publicBaseUrl } = value as Record<string, unknown>;
+  if (!isTunnelProviderName(provider)) {
+    return null;
+  }
+  const normalized =
+    normalizeHttpPublicBaseUrlWithoutTrailingSlash(publicBaseUrl);
+  if (normalized === undefined) {
+    return null;
+  }
+  return { provider, publicBaseUrl: normalized };
+}
+
+/** Parse an `ingress.assistantId` value, or null when it is absent or blank. */
+export function parseRecordedAssistantId(value: unknown): string | null {
+  return trimmedNonEmptyString(value) ?? null;
+}

package/node_modules/@vellumai/gateway-client/src/__tests__/contact-read-contracts.test.ts

@@ -20,6 +20,7 @@ describe("contact read contracts", () => {
       contactType: "human",
       lastInteraction: 1700000000,
       interactionCount: 12,
+      autoApproveThreshold: "medium",
       createdAt: 1699000000,
       updatedAt: 1700000000,
       channels: [
@@ -46,6 +47,7 @@ describe("contact read contracts", () => {
     const parsed = ContactReadSchema.parse(contact);
     expect(parsed.createdAt).toBe(1699000000);
     expect(parsed.updatedAt).toBe(1700000000);
+    expect(parsed.autoApproveThreshold).toBe("medium");
   });
 
   test("ContactReadSchema accepts null interactionCount (daemon-native gateway-telemetry outage fail-soft)", () => {
@@ -82,6 +84,36 @@ describe("contact read contracts", () => {
     const parsed = ContactReadSchema.parse(contact);
     expect(parsed.interactionCount).toBeNull();
     expect(parsed.channels[0].interactionCount).toBeNull();
+    expect(parsed.autoApproveThreshold).toBeUndefined();
+  });
+
+  test("ContactReadSchema accepts a null auto-approve threshold", () => {
+    const contact = {
+      id: "c1",
+      displayName: "Example User",
+      role: "contact",
+      interactionCount: 0,
+      autoApproveThreshold: null,
+      createdAt: 1699000000,
+      updatedAt: 1700000000,
+      channels: [],
+    };
+    expect(ContactReadSchema.parse(contact).autoApproveThreshold).toBeNull();
+  });
+
+  test("ContactReadSchema rejects an unknown auto-approve threshold", () => {
+    expect(() =>
+      ContactReadSchema.parse({
+        id: "c1",
+        displayName: "Example User",
+        role: "contact",
+        interactionCount: 0,
+        autoApproveThreshold: "full",
+        createdAt: 1699000000,
+        updatedAt: 1700000000,
+        channels: [],
+      }),
+    ).toThrow();
   });
 
   test("ContactReadSchema requires createdAt/updatedAt", () => {

package/node_modules/@vellumai/gateway-client/src/__tests__/trust-verdict-contract.test.ts

@@ -31,6 +31,7 @@ const fullVerdict: TrustVerdict = {
   verifiedAt: 1699999999,
   interactionCount: 12,
   memberDisplayName: "Member Name",
+  autoApproveThreshold: "high",
 };
 
 describe("TrustVerdictSchema", () => {
@@ -38,6 +39,23 @@ describe("TrustVerdictSchema", () => {
     expect(TrustVerdictSchema.parse(fullVerdict)).toEqual(fullVerdict);
   });
 
+  test("parses a verdict with a null contact auto-approve threshold", () => {
+    const verdict = {
+      ...fullVerdict,
+      autoApproveThreshold: null,
+    } satisfies TrustVerdict;
+    expect(TrustVerdictSchema.parse(verdict)).toEqual(verdict);
+  });
+
+  test("rejects an unknown contact auto-approve threshold", () => {
+    expect(() =>
+      TrustVerdictSchema.parse({
+        ...fullVerdict,
+        autoApproveThreshold: "full",
+      }),
+    ).toThrow();
+  });
+
   test("parses a minimal verdict", () => {
     const minimal = {
       trustClass: "unknown",

package/node_modules/@vellumai/gateway-client/src/admission-policy-contract.ts

@@ -82,15 +82,10 @@ export function isAdmissionPolicyExemptChannel(channelType: string): boolean {
  * `vellum` is the local desktop/web client surface; the guardian is always
  * max-rank there, so the seed default admits them regardless of the floor.
  *
- * `discord` has no ingress implementation, so there is nothing for a floor to
- * gate and nothing for the user to configure. Hiding keeps it pinned at the
- * seed default rather than offering a Channel Trust Floors row for a channel
- * that receives nothing.
  */
 export const ADMISSION_POLICY_HIDDEN_CHANNELS: ReadonlySet<string> = new Set([
   "vellum",
   "whatsapp",
-  "discord",
 ]);
 
 export function isAdmissionPolicyHiddenChannel(channelType: string): boolean {

package/node_modules/@vellumai/gateway-client/src/channel-permission-contract.ts

@@ -10,7 +10,9 @@
  *
  * Storage lives in the gateway DB (`channel_permission_overrides`) so the
  * assistant cannot tamper with it, matching `channel_admission_policy` and
- * `auto_approve_thresholds`.
+ * `auto_approve_thresholds`. A contact-level ceiling can live on
+ * `contacts.auto_approve_threshold` and is stamped on the trust verdict;
+ * that override is not a matrix cell.
  */
 
 import { z } from "zod";