@vellumai/assistant 0.12.6 → 0.12.7-staging.1

package/.env.example

@@ -2,6 +2,8 @@
 ANTHROPIC_API_KEY=sk-ant-...
 OPENAI_API_KEY=sk-...
 GEMINI_API_KEY=...
+# Optional. IO Intelligence (io.net) open-models endpoint.
+IONET_API_KEY=...
 # Optional. TypeSafe / Jev System One decision model.
 TYPESAFE_API_KEY=...
 # Optional for authenticated/proxied Ollama deployments

package/ARCHITECTURE.md

@@ -83,6 +83,7 @@ All HTTP API requests use a single `Authorization: Bearer <jwt>` header for auth
 | Profile              | Scopes                                                                                                                                                | Used by                                      |
 | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
 | `actor_client_v1`    | `chat.{read,write}`, `approval.{read,write}`, `settings.{read,write}`, `attachments.{read,write}`, `calls.{read,write}`, `feature_flags.{read,write}` | Desktop, CLI clients                         |
+| `contact_client_v1`  | `chat.write`, `approval.write`, `attachments.write`                                                                                                   | Non-guardian contact clients                 |
 | `gateway_ingress_v1` | `ingress.write`, `internal.write`                                                                                                                     | Gateway channel inbound + webhook forwarding |
 | `gateway_service_v1` | `chat.{read,write}`, `settings.{read,write}`, `attachments.{read,write}`, `internal.write`                                                            | Gateway service-to-daemon calls              |
 | `local_v1`           | `local.all`                                                                                                                                           | Local (loopback) conversation sessions       |
@@ -98,8 +99,12 @@ All HTTP API requests use a single `Authorization: Bearer <jwt>` header for auth
 
 3. **Local identity** — Local connections use deterministic identity resolution without tokens.
 
+**Token role:** Each access and refresh token records the principal it belongs to, `guardian` or `contact`. The role picks the scope profile at mint time, and rotation carries it forward.
+
 **Route policy enforcement:** Every protected endpoint declares required scopes and allowed principal types in `src/runtime/auth/route-policy.ts`. The `enforcePolicy()` function checks the AuthContext against these requirements and returns 403 when access is denied. A guard test ensures every dispatched endpoint has a corresponding policy entry.
 
+**Trust class enforcement:** A policy's `allowedTrustClasses` names whose turn may call a route, and an absent list means guardian only. A token whose scope profile is trust-checked (`isTrustCheckedScopeProfile` in `@vellumai/gateway-client`: every profile not on its exempt list, which is `contact_client_v1` today plus any unknown profile) reaches only a route whose list admits the trust class its principal resolves to on the `vellum-shared` channel. That class is read per request, so a revoked contact is refused on its next request. A trust-exempt token counts as the guardian with no lookup, so it reaches only a route whose list admits `guardian`, which every route naming no classes does. A refused caller gets 404, as an unmatched path does. The daemon's HTTP router and the gateway's IPC proxy both apply this rule (`tokenMayReachRoute` in `@vellumai/gateway-client`), since the daemon's IPC server runs no policy check of its own.
+
 **Credential storage:** Only hashed tokens are persisted. Access token hashes go in `credential_records`; refresh token hashes in `refresh_token_records`. Raw tokens are returned once and never stored server-side.
 
 **Notification scoping:** Guardian-sensitive notifications (`notification_intent`, `notification_conversation_created`) are published with `targetActorPrincipalId`, so the event hub delivers them, live, on reconnect replay, and from the `events/tail` recovery route, only to SSE connections whose verified `actorPrincipalId` is the guardian's. Connections without a principal never receive them. The payload's `targetGuardianPrincipalId` records the scoping.
@@ -618,12 +623,12 @@ Every phone call connects over Twilio Media Streams: the voice webhook emits `<C
 
 Transcription mode is selected once per session in `media-stream-stt-session.ts`:
 
-- **Streaming** (default): when `calls.voice.telephonyStreaming` is enabled and the `telephony` role resolves a streaming transcriber (`resolveStreamingTranscriber({ role: "telephony" })`), inbound audio is decoded (mu-law → PCM16, resampled 8 kHz → 16 kHz) and fed to the provider's realtime adapter. Replies trigger only on utterance-boundary finals (for Deepgram, `speech_final`/`UtteranceEnd`, never mid-sentence `is_final` segments), and barge-in fires from local energy VAD, never from transcriber partials. While something is interruptible (an assistant turn in flight, thinking or speaking, or a completed turn's tail still playing from Twilio's buffer), caller speech arms the shared sustained-speech barge-in guard (`src/calls/barge-in-guard.ts`, the same accounting live voice uses: speech accumulates toward 250 ms, short gaps are tolerated, a run that is mostly silence resets) and every inbound frame feeds it; outside that window the guard is dropped, so the caller's own utterance never carries into a turn that starts before the local VAD ends it. Only a fired guard reaches `CallController.handleBargeIn`, which interrupts a turn in either phase and ignores an idle controller (the playing tail is cleared instead).
+- **Streaming** (default): when `calls.voice.telephonyStreaming` is enabled and the `telephony` role resolves a streaming transcriber (`resolveStreamingTranscriber({ role: "telephony" })`), inbound audio is decoded (mu-law → PCM16, resampled 8 kHz → 16 kHz) and fed to the provider's realtime adapter. Replies trigger only on utterance-boundary finals (for Deepgram, `speech_final`/`UtteranceEnd`, never mid-sentence `is_final` segments), and barge-in fires from local energy VAD, never from transcriber partials. Interim `partial` events are forwarded to the controller as `handleCallerPartial`: they commit nothing and start no turn, they are never persisted and never reach a setup flow, and they exist so a boundary the front door held mid-thought can be replayed on the caller's newest words rather than only the ones the provider has finalized. While something is interruptible (an assistant turn in flight, thinking or speaking, or a completed turn's tail still playing from Twilio's buffer), caller speech arms the shared sustained-speech barge-in guard (`src/calls/barge-in-guard.ts`, the same accounting live voice uses: speech accumulates toward 250 ms, short gaps are tolerated, a run that is mostly silence resets) and every inbound frame feeds it; outside that window the guard is dropped, so the caller's own utterance never carries into a turn that starts before the local VAD ends it. Only a fired guard reaches `CallController.handleBargeIn`, which interrupts a turn in either phase and ignores an idle controller (the playing tail is cleared instead).
 - **Batch fallback**: otherwise the session segments turns with the energy-based `MediaTurnDetector` and transcribes each completed turn via the same role's batch API. Both halves of a call read the `telephony` role, which is why a role names its consumer rather than a boundary.
 
-Every phone turn runs the same two-leg triage as live voice through `startVoiceTurn` (`src/calls/voice-session-bridge.ts`): `call-controller.ts` opens on a toolless front-door leg (`routingLeg: "front-door"`, the `voiceFrontDoor` call site) and drives it through the shared `createFrontDoorLegCoordinator` (`src/calls/voice-leg-coordinator.ts`), which reads the stream through the verdict machine and sequences the hand-off (pause narration, abort the leg, resolve and speak the bridge, mark it as the floor holder, start the escalated leg pinned to the conversation's own model, re-arm narration); each driver supplies only a host for how text and the bridge are spoken, how a leg is started or aborted, and (live voice only) the speculative hold and commit. Phone has no partial transcripts, so the hold verdict is never taught and routing is escalate-only. The controller also passes the bridge's turn callbacks (tool activity is recorded as `tool_use_started` / `tool_use_completed` call events, persisted row ids ride the `assistant_spoke` event), `launchedAtMs` for dispatch timing, and a `voiceTelemetry` bag keyed by the call session with a `phone_inbound` / `phone_outbound` entry. Both drivers share the spoken progress narration cadence (`src/calls/voice-progress-cadence.ts`, tuned by `voice.frontModel.progress`): the cadence owns the tool-activity log, the triggers (an ops burst, a long operation completing, a full interval of audible silence with news, the `maxSilenceMs` heartbeat) and the generated or static phrase, while each driver supplies its own view of audible silence (live voice from its TTS queue and playback-tail estimate; the media-stream transport from `isPlaybackIdle()` and a running sum of sent frame durations) and how to speak a phrase.
+Every phone turn runs the same two-leg triage as live voice through `startVoiceTurn` (`src/calls/voice-session-bridge.ts`): `call-controller.ts` opens on a toolless front-door leg (`routingLeg: "front-door"`, the `voiceFrontDoor` call site) and drives it through the shared `createFrontDoorLegCoordinator` (`src/calls/voice-leg-coordinator.ts`), which reads the stream through the verdict machine and sequences the hand-off (pause narration, abort the leg, resolve and speak the bridge, mark it as the floor holder, start the escalated leg pinned to the conversation's own model, re-arm narration); each driver supplies only a host for how text and the bridge are spoken, how a leg is started or aborted, and (live voice only) the speculative hold and commit. A leg that carries the caller's own words is also the turn's endpoint decision, so it is taught the hold verdict: silence alone cannot tell a finished sentence from a thinking pause, and answering a fragment makes the rest of the sentence read as a barge-in that interrupts the assistant's own reply. On a hold the leg is discarded (its persisted user row rolled back through the handle's `discard`), the floor goes straight back to the caller, and the words are carried into their next final so the whole sentence is judged together. If no next words arrive, a replay timer (`voice.frontModel.endpointExtensionMs`) answers the sentence as it stands; any partial re-arms that timer and the next final cancels it. A partial also stretches the wait to at least `calls.voice.utteranceEndMs` plus a margin, because the provider still owes a final for those words and that final is the better boundary: racing it would ask the same words twice, once on the interim guess and once on the committed text. Reaching the timer with a partial outstanding therefore means no final is coming, so the interim text rides along as the only record of what the caller said. `voice.frontModel.endpointMaxExtensions` caps consecutive holds per sentence, after which the leg must answer. Openers, instructions, and other assistant-initiated turns are never dispatched that way. The controller also passes the bridge's turn callbacks (tool activity is recorded as `tool_use_started` / `tool_use_completed` call events, persisted row ids ride the `assistant_spoke` event), `launchedAtMs` for dispatch timing, and a `voiceTelemetry` bag keyed by the call session with a `phone_inbound` / `phone_outbound` entry. Both drivers share the spoken progress narration cadence (`src/calls/voice-progress-cadence.ts`, tuned by `voice.frontModel.progress`): the cadence owns the tool-activity log, the triggers (an ops burst, a long operation completing, a full interval of audible silence with news, the `maxSilenceMs` heartbeat) and the generated or static phrase, while each driver supplies its own view of audible silence (live voice from its TTS queue and playback-tail estimate; the media-stream transport from `isPlaybackIdle()` and a running sum of sent frame durations) and how to speak a phrase.
 
-Both drivers also share the per-turn latency marks (`src/calls/voice-metrics.ts`). The controller opens a turn's marks when it dispatches, seeded with when the caller's transcript arrived, and stamps the leg dispatch, the first assistant delta, the first audible audio, a barge-in, and how the turn settled. Live voice streams a snapshot to its client on every mark; a call has no client on the line, so the aggregate is logged once per turn, cancelled turns included. Each call also records a `phone_call_started` / `phone_call_ended` pair on the onboarding telemetry substrate (`src/telemetry/phone-call-funnel.ts`), written by the call store at session creation and at the single terminal status transition: duration is the gap between the two rows, and a call that took no caller turn carries why on the end row (`silent_no_connect` when it never connected, `silent_no_turn` when it did and nobody spoke).
+Both drivers also share the per-turn latency marks (`src/calls/voice-metrics.ts`). The controller opens a turn's marks when it dispatches, seeded with when the caller's transcript arrived and when the provider first had interim words for that same utterance, and stamps the leg dispatch, the first assistant delta, the first audible audio, a barge-in, an endpoint hold, and how the turn settled. A held turn settles as `endpoint_hold` and hands both seeds to the turn that finally answers, so the caller's wait is still measured from the moment they stopped talking. Live voice streams a snapshot to its client on every mark; a call has no client on the line, so the aggregate is logged once per turn, cancelled turns included. Each call also records a `phone_call_started` / `phone_call_ended` pair on the onboarding telemetry substrate (`src/telemetry/phone-call-funnel.ts`), written by the call store at session creation and at the single terminal status transition: duration is the gap between the two rows, and a call that took no caller turn carries why on the end row (`silent_no_connect` when it never connected, `silent_no_turn` when it did and nobody spoke).
 
 A credential preflight (`resolveTelephonyCredentialReadiness()` in `src/calls/telephony-credential-preflight.ts`) gates every call: it requires a credentialed, telephony-capable STT provider **and** a media-stream-playable TTS provider (the configured one or a credentialed playable fallback). Inbound calls that fail the preflight receive `<Say>` setup-required copy plus `<Hangup/>` instead of a doomed stream; outbound placement fails before dialing via `preflightVoiceIngress()` with the same user-facing message.
 
@@ -1238,14 +1243,10 @@ graph TB
     EXEC -->|"file_read / file_write / file_edit"| SB_FILE_TOOLS["Sandbox file tools<br/>path-scoped to sandbox root"]
     SB_FILE_TOOLS --> SB_FS
 
-    EXEC -->|"bash"| WRAP["wrapCommand()<br/>sandbox.ts"]
-
-    WRAP --> NATIVE["NativeBackend"]
-
-    NATIVE -->|"macOS"| SBPL["sandbox-exec<br/>SBPL profile<br/>deny-default + allow workdir"]
-    NATIVE -->|"Linux"| BWRAP["bwrap<br/>bubblewrap<br/>ro-root + rw-workdir<br/>unshare-net + unshare-pid"]
-    SBPL --> SB_FS["Sandbox filesystem root<br/>$VELLUM_WORKSPACE_DIR"]
-    BWRAP --> SB_FS
+    EXEC -->|"bash"| WRAP["buildShellInvocation()<br/>(packages/environments/shell)"]
+    WRAP --> SHELL["bash -c in $VELLUM_WORKSPACE_DIR<br/>sanitized env (safe-env allowlist)"]
+    SHELL --> SB_FS["Workspace filesystem root<br/>$VELLUM_WORKSPACE_DIR"]
+    SHELL -.->|containerized deployments| CONTAINER["Container boundary<br/>(Docker / remote host) provides<br/>OS-level isolation"]
 
     EXEC -->|"host_file_* / host_bash"| HOST_TOOLS["Host-target tools<br/>(unchanged by backend choice)"]
     EXEC -->|"computer_use_* (skill-projected<br/>in CU sessions only)"| SKILL_CU_TOOLS["CU skill tools<br/>(bundled computer-use skill)"]
@@ -1259,9 +1260,8 @@ graph TB
     USER --> CHECK
 ```
 
-- **Native backend**: Uses OS-level sandboxing — `sandbox-exec` with SBPL profiles on macOS, `bwrap` (bubblewrap) on Linux. Denies network access and restricts filesystem writes to the sandbox root, `/tmp`, `/private/tmp`, and `/var/folders` (macOS) or the sandbox root and `/tmp` (Linux).
-- **Fail-closed**: The native backend refuses to execute unsandboxed if its prerequisites are unavailable, throwing `ToolError` with actionable messages on failure.
-- **Host tools unchanged**: `host_bash`, `host_file_read`, `host_file_write`, and `host_file_edit` always execute directly on the host regardless of which sandbox backend is active.
+- **Workspace scoping (software-enforced)**: `file_read`, `file_write`, and `file_edit` path-check every access against `$VELLUM_WORKSPACE_DIR`, including symlink resolution. `bash` spawns `bash -c` in the workspace directory with a sanitized environment and is not OS-confined on local installs; commands are gated by risk classification and the conversation's auto-approve threshold, with workspace path checks applied to allowlisted commands on non-containerized installs. Containerized deployments (`vellum hatch --remote docker`, remote hosts) get OS-level isolation from the container boundary. Workflow scripts run in a separate QuickJS-WASM sandbox with no ambient capabilities.
+- **Host tools unchanged**: `host_bash`, `host_file_read`, `host_file_write`, and `host_file_edit` always execute directly on the host regardless of deployment mode.
 - Sandbox defaults: `file_*` and `bash` execute within `$VELLUM_WORKSPACE_DIR`.
 - Host access is explicit: `host_file_read`, `host_file_write`, `host_file_edit`, and `host_bash` are separate tools.
 - Prompt defaults: host tools and `computer_use_*` skill-projected actions default to `ask` unless a trust rule allowlists/denylists them.

package/docs/architecture/integrations.md

@@ -269,7 +269,7 @@ Scripts executed via the `bash` tool can optionally run through a per-session HT
 
 ### Proxied Bash Execution Path
 
-When a bash command requires network access with credential injection, the sandbox backend switches from `network=none` to `network=bridge` and injects proxy environment variables so all HTTP/HTTPS traffic routes through the session proxy.
+When a bash command requires network access with credential injection, the tool injects proxy environment variables into the spawned shell so all HTTP/HTTPS traffic routes through the session proxy.
 
 ```mermaid
 graph TB
@@ -283,8 +283,8 @@ graph TB
         PROMPT["Prompt user<br/>persistentDecisionsAllowed: false<br/>(no trust rule saving for proxied bash)"]
     end
 
-    subgraph "Sandbox"
-        SANDBOX["NativeBackend.wrap()<br/>networkMode: 'proxied'"]
+    subgraph "Shell Execution"
+        SHELL["bash -c spawn<br/>(buildShellInvocation)"]
         ENV_INJECT["Inject env vars:<br/>HTTP_PROXY, HTTPS_PROXY,<br/>NO_PROXY, NODE_EXTRA_CA_CERTS"]
     end
 
@@ -298,8 +298,8 @@ graph TB
     BASH_CALL --> EXECUTOR
     EXECUTOR --> PERM
     PERM --> PROMPT
-    PROMPT -->|"allowed"| SANDBOX
-    SANDBOX --> ENV_INJECT
+    PROMPT -->|"allowed"| SHELL
+    SHELL --> ENV_INJECT
     ENV_INJECT -->|"HTTP"| HTTP_FWD
     ENV_INJECT -->|"HTTPS CONNECT"| CONNECT
     CONNECT --> ROUTER

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

@@ -24,6 +24,7 @@ describe("isChannelId", () => {
     // so these must remain canonical for that assertion to mean anything.
     expect(isChannelId("platform")).toBe(true);
     expect(isChannelId("vellum")).toBe(true);
+    expect(isChannelId("vellum-shared")).toBe(true);
   });
 
   test("includes discord", () => {
@@ -58,6 +59,7 @@ describe("botProviderForChannel and channelForBotProvider", () => {
   test("answer nothing for a channel without a bot, a person's grant, or an unknown key", () => {
     expect(botProviderForChannel("phone")).toBeUndefined();
     expect(botProviderForChannel("vellum")).toBeUndefined();
+    expect(botProviderForChannel("vellum-shared")).toBeUndefined();
     expect(botProviderForChannel("not-a-channel")).toBeUndefined();
     // `slack` is the person's integration standing beside the bot's key.
     expect(channelForBotProvider("slack")).toBeUndefined();

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

@@ -4,8 +4,9 @@
  *
  * A "channel" is an external messaging surface an actor can reach the
  * assistant through (Slack, Telegram, WhatsApp, phone, …) plus a couple of
- * internal ids (`vellum` for native app conversations, `platform` for the
- * internal control plane). This is the single source of truth for that set:
+ * internal ids (`vellum` for native app conversations, `vellum-shared` for
+ * conversations a guardian shares with a contact, `platform` for the internal
+ * control plane). This is the single source of truth for that set:
  *
  * One id, `plugin`, does not name a surface: it names *every* surface a plugin
  * brings. A plugin channel's real identity is the plugin, which is workspace
@@ -41,6 +42,9 @@ export const CHANNEL_IDS = [
   "a2a",
   "discord",
   "plugin",
+  // Internal id for conversations a guardian shares with a contact. It has no
+  // transport: the contact's own client holds the connection.
+  "vellum-shared",
 ] as const;
 
 export type ChannelId = (typeof CHANNEL_IDS)[number];
@@ -78,8 +82,8 @@ export function isChannelId(value: unknown): value is ChannelId {
  * here would be a second copy of a different fact.
  *
  * Channels absent from this map reach the assistant without a bot credential
- * of their own: `phone` through the voice provider, `vellum` and `platform`
- * internally.
+ * of their own: `phone` through the voice provider, `vellum`, `vellum-shared`
+ * and `platform` internally.
  */
 export const CHANNEL_BOT_PROVIDER = {
   slack: "slack_channel",

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

@@ -24,6 +24,7 @@ describe("isChannelId", () => {
     // so these must remain canonical for that assertion to mean anything.
     expect(isChannelId("platform")).toBe(true);
     expect(isChannelId("vellum")).toBe(true);
+    expect(isChannelId("vellum-shared")).toBe(true);
   });
 
   test("includes discord", () => {
@@ -58,6 +59,7 @@ describe("botProviderForChannel and channelForBotProvider", () => {
   test("answer nothing for a channel without a bot, a person's grant, or an unknown key", () => {
     expect(botProviderForChannel("phone")).toBeUndefined();
     expect(botProviderForChannel("vellum")).toBeUndefined();
+    expect(botProviderForChannel("vellum-shared")).toBeUndefined();
     expect(botProviderForChannel("not-a-channel")).toBeUndefined();
     // `slack` is the person's integration standing beside the bot's key.
     expect(channelForBotProvider("slack")).toBeUndefined();

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

@@ -4,8 +4,9 @@
  *
  * A "channel" is an external messaging surface an actor can reach the
  * assistant through (Slack, Telegram, WhatsApp, phone, …) plus a couple of
- * internal ids (`vellum` for native app conversations, `platform` for the
- * internal control plane). This is the single source of truth for that set:
+ * internal ids (`vellum` for native app conversations, `vellum-shared` for
+ * conversations a guardian shares with a contact, `platform` for the internal
+ * control plane). This is the single source of truth for that set:
  *
  * One id, `plugin`, does not name a surface: it names *every* surface a plugin
  * brings. A plugin channel's real identity is the plugin, which is workspace
@@ -41,6 +42,9 @@ export const CHANNEL_IDS = [
   "a2a",
   "discord",
   "plugin",
+  // Internal id for conversations a guardian shares with a contact. It has no
+  // transport: the contact's own client holds the connection.
+  "vellum-shared",
 ] as const;
 
 export type ChannelId = (typeof CHANNEL_IDS)[number];
@@ -78,8 +82,8 @@ export function isChannelId(value: unknown): value is ChannelId {
  * here would be a second copy of a different fact.
  *
  * Channels absent from this map reach the assistant without a bot credential
- * of their own: `phone` through the voice provider, `vellum` and `platform`
- * internally.
+ * of their own: `phone` through the voice provider, `vellum`, `vellum-shared`
+ * and `platform` internally.
  */
 export const CHANNEL_BOT_PROVIDER = {
   slack: "slack_channel",

package/node_modules/@vellumai/gateway-client/src/__tests__/route-trust-class.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, mock, test } from "bun:test";
+
+import {
+  isTrustCheckedScopeProfile,
+  routeAdmitsTrustClass,
+  tokenMayReachRoute,
+  TRUST_EXEMPT_SCOPE_PROFILES,
+} from "../route-trust-class.js";
+
+const CONTACT_ROUTE = ["guardian", "trusted_contact", "unverified_contact"];
+
+const contactMayReach = (
+  allowed: readonly string[] | undefined,
+  resolve: () => Promise<string | undefined>,
+) => tokenMayReachRoute("contact_client_v1", allowed, resolve);
+
+describe("routeAdmitsTrustClass", () => {
+  test("an absent list admits the guardian only", () => {
+    expect(routeAdmitsTrustClass(undefined, "guardian")).toBe(true);
+    expect(routeAdmitsTrustClass(undefined, "trusted_contact")).toBe(false);
+    expect(routeAdmitsTrustClass(undefined, "unknown")).toBe(false);
+  });
+
+  test("a listed class is admitted and an unlisted one refused", () => {
+    expect(routeAdmitsTrustClass(CONTACT_ROUTE, "trusted_contact")).toBe(true);
+    expect(routeAdmitsTrustClass(CONTACT_ROUTE, "unknown")).toBe(false);
+  });
+
+  test("a value outside the vocabulary is refused even when listed", () => {
+    expect(routeAdmitsTrustClass(["owner"], "owner")).toBe(false);
+    expect(routeAdmitsTrustClass(CONTACT_ROUTE, undefined)).toBe(false);
+  });
+});
+
+describe("tokenMayReachRoute for a contact token", () => {
+  test("a route admitting only the guardian refuses without resolving", async () => {
+    const resolve = mock(async () => "trusted_contact");
+    expect(await contactMayReach(undefined, resolve)).toBe(false);
+    expect(await contactMayReach(["guardian"], resolve)).toBe(false);
+    expect(resolve).not.toHaveBeenCalled();
+  });
+
+  test.each([
+    ["trusted_contact", true],
+    ["unverified_contact", true],
+    ["unknown", false],
+    ["guardian", false],
+    [undefined, false],
+  ] as const)(
+    "a contact route resolving %p admits: %p",
+    async (trustClass, admitted) => {
+      expect(await contactMayReach(CONTACT_ROUTE, async () => trustClass)).toBe(
+        admitted,
+      );
+    },
+  );
+
+  test("a class the route does not list is refused", async () => {
+    expect(
+      await contactMayReach(
+        ["guardian", "trusted_contact"],
+        async () => "unverified_contact",
+      ),
+    ).toBe(false);
+  });
+
+  test("a resolver that throws refuses", async () => {
+    expect(
+      await contactMayReach(CONTACT_ROUTE, async () => {
+        throw new Error("gateway unreachable");
+      }),
+    ).toBe(false);
+  });
+});
+
+describe("isTrustCheckedScopeProfile", () => {
+  test("an exempt profile is not trust-checked", () => {
+    for (const profile of TRUST_EXEMPT_SCOPE_PROFILES) {
+      expect(isTrustCheckedScopeProfile(profile)).toBe(false);
+    }
+  });
+
+  test("the contact profile, unknown profiles and prototype keys are", () => {
+    for (const profile of [
+      "contact_client_v1",
+      "bogus_v1",
+      "toString",
+      "constructor",
+      "__proto__",
+    ]) {
+      expect(isTrustCheckedScopeProfile(profile)).toBe(true);
+    }
+  });
+});
+
+describe("tokenMayReachRoute for a trust-exempt token", () => {
+  test.each([...TRUST_EXEMPT_SCOPE_PROFILES])(
+    "%s counts as the guardian without a lookup",
+    async (profile) => {
+      const resolve = mock(async () => "trusted_contact");
+      expect(await tokenMayReachRoute(profile, undefined, resolve)).toBe(true);
+      expect(await tokenMayReachRoute(profile, CONTACT_ROUTE, resolve)).toBe(
+        true,
+      );
+      expect(
+        await tokenMayReachRoute(profile, ["trusted_contact"], resolve),
+      ).toBe(false);
+      expect(resolve).not.toHaveBeenCalled();
+    },
+  );
+});

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

@@ -56,8 +56,8 @@ export const ADMISSION_FLOOR: Record<AdmissionPolicy, number> = {
  *
  * `phone` is NOT exempt — voice ingress enforces the admission floor.
  *
- * `vellum` / `whatsapp` are NOT exempt — their floors are still enforced at
- * runtime — but they are hidden from the configurable UI; see
+ * `vellum` / `vellum-shared` / `whatsapp` are NOT exempt: their floors are
+ * still enforced at runtime, but they are hidden from the configurable UI; see
  * {@link ADMISSION_POLICY_HIDDEN_CHANNELS}.
  */
 export const ADMISSION_POLICY_EXEMPT_CHANNELS: ReadonlySet<string> = new Set([
@@ -81,9 +81,12 @@ 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.
  *
+ * `vellum-shared` carries conversations a guardian shares with a contact. Its
+ * seed default is `guardian_only`, which admits no contact.
  */
 export const ADMISSION_POLICY_HIDDEN_CHANNELS: ReadonlySet<string> = new Set([
   "vellum",
+  "vellum-shared",
   "whatsapp",
 ]);
 

package/node_modules/@vellumai/gateway-client/src/index.ts

@@ -132,6 +132,15 @@ export type {
   TrustVerdict,
 } from "./trust-verdict-contract.js";
 
+// Route trust class, applied by both the daemon router and the gateway IPC proxy
+export {
+  DEFAULT_ROUTE_TRUST_CLASSES,
+  isTrustCheckedScopeProfile,
+  routeAdmitsTrustClass,
+  tokenMayReachRoute,
+  TRUST_EXEMPT_SCOPE_PROFILES,
+} from "./route-trust-class.js";
+
 // Invite contract (shared gateway ↔ daemon) — hash/generate helpers,
 // channel gating, redemption outcome, method map + invite IPC schemas
 export {

package/node_modules/@vellumai/gateway-client/src/route-trust-class.ts

@@ -0,0 +1,94 @@
+/**
+ * Which trust classes a route admits, shared by the daemon's HTTP router and
+ * the gateway's IPC proxy so both enforcement points apply one rule.
+ *
+ * A route policy's `allowedTrustClasses` reaches the gateway on the IPC route
+ * schema as plain strings, and is absent from a null policy or a schema served
+ * by a daemon that predates the field. Absent means guardian only.
+ */
+
+import { isTrustClass, type TrustClass } from "./trust-verdict-contract.js";
+
+/**
+ * Scope profiles whose holders are not trust-checked: the guardian's own
+ * client, and service, local and single-route grants that route policy
+ * already governs. Any profile not listed here is trust-checked, so an
+ * unknown or newly added profile fails closed until it is judged exempt.
+ */
+export const TRUST_EXEMPT_SCOPE_PROFILES: readonly string[] = [
+  "actor_client_v1",
+  "gateway_ingress_v1",
+  "gateway_service_v1",
+  "local_v1",
+  "oauth_proxy_v1",
+  "speech_relay_v1",
+  "ui_page_v1",
+];
+
+const TRUST_EXEMPT_SET: ReadonlySet<string> = new Set(
+  TRUST_EXEMPT_SCOPE_PROFILES,
+);
+
+/**
+ * True when a token of `profile` reaches a route only if the route admits
+ * its holder's trust class.
+ */
+export function isTrustCheckedScopeProfile(profile: string): boolean {
+  return !TRUST_EXEMPT_SET.has(profile);
+}
+
+/** Trust classes a route admits when its policy names none. */
+export const DEFAULT_ROUTE_TRUST_CLASSES: readonly TrustClass[] = ["guardian"];
+
+/**
+ * Whether a route admitting `allowedTrustClasses` admits a caller of
+ * `trustClass`. A value outside the vocabulary is refused, since a wire-sourced
+ * class can carry anything.
+ */
+export function routeAdmitsTrustClass(
+  allowedTrustClasses: readonly string[] | undefined,
+  trustClass: string | undefined,
+): boolean {
+  if (typeof trustClass !== "string" || !isTrustClass(trustClass)) {
+    return false;
+  }
+  return (allowedTrustClasses ?? DEFAULT_ROUTE_TRUST_CLASSES).includes(
+    trustClass,
+  );
+}
+
+/**
+ * Whether a caller whose token carries `scopeProfile` may reach a route
+ * admitting `allowedTrustClasses`.
+ *
+ * A trust-exempt profile stands for the guardian, so it reaches exactly the
+ * routes that admit `guardian`, with no lookup. That is every route naming no
+ * classes.
+ *
+ * A trust-checked token never speaks for the guardian, so a route admitting no
+ * other class refuses it without calling `resolveTrustClass`. Otherwise the
+ * resolved class must be one the route admits and must not be `guardian`. A
+ * resolver that throws or resolves nothing refuses.
+ */
+export async function tokenMayReachRoute(
+  scopeProfile: string,
+  allowedTrustClasses: readonly string[] | undefined,
+  resolveTrustClass: () => Promise<string | undefined>,
+): Promise<boolean> {
+  if (!isTrustCheckedScopeProfile(scopeProfile)) {
+    return routeAdmitsTrustClass(allowedTrustClasses, "guardian");
+  }
+  const allowed = allowedTrustClasses ?? DEFAULT_ROUTE_TRUST_CLASSES;
+  if (!allowed.some((trustClass) => trustClass !== "guardian")) {
+    return false;
+  }
+  let trustClass: string | undefined;
+  try {
+    trustClass = await resolveTrustClass();
+  } catch {
+    return false;
+  }
+  return (
+    trustClass !== "guardian" && routeAdmitsTrustClass(allowed, trustClass)
+  );
+}

package/node_modules/@vellumai/service-contracts/src/__tests__/channels.test.ts

@@ -24,6 +24,7 @@ describe("isChannelId", () => {
     // so these must remain canonical for that assertion to mean anything.
     expect(isChannelId("platform")).toBe(true);
     expect(isChannelId("vellum")).toBe(true);
+    expect(isChannelId("vellum-shared")).toBe(true);
   });
 
   test("includes discord", () => {
@@ -58,6 +59,7 @@ describe("botProviderForChannel and channelForBotProvider", () => {
   test("answer nothing for a channel without a bot, a person's grant, or an unknown key", () => {
     expect(botProviderForChannel("phone")).toBeUndefined();
     expect(botProviderForChannel("vellum")).toBeUndefined();
+    expect(botProviderForChannel("vellum-shared")).toBeUndefined();
     expect(botProviderForChannel("not-a-channel")).toBeUndefined();
     // `slack` is the person's integration standing beside the bot's key.
     expect(channelForBotProvider("slack")).toBeUndefined();

package/node_modules/@vellumai/service-contracts/src/channels.ts

@@ -4,8 +4,9 @@
  *
  * A "channel" is an external messaging surface an actor can reach the
  * assistant through (Slack, Telegram, WhatsApp, phone, …) plus a couple of
- * internal ids (`vellum` for native app conversations, `platform` for the
- * internal control plane). This is the single source of truth for that set:
+ * internal ids (`vellum` for native app conversations, `vellum-shared` for
+ * conversations a guardian shares with a contact, `platform` for the internal
+ * control plane). This is the single source of truth for that set:
  *
  * One id, `plugin`, does not name a surface: it names *every* surface a plugin
  * brings. A plugin channel's real identity is the plugin, which is workspace
@@ -41,6 +42,9 @@ export const CHANNEL_IDS = [
   "a2a",
   "discord",
   "plugin",
+  // Internal id for conversations a guardian shares with a contact. It has no
+  // transport: the contact's own client holds the connection.
+  "vellum-shared",
 ] as const;
 
 export type ChannelId = (typeof CHANNEL_IDS)[number];
@@ -78,8 +82,8 @@ export function isChannelId(value: unknown): value is ChannelId {
  * here would be a second copy of a different fact.
  *
  * Channels absent from this map reach the assistant without a bot credential
- * of their own: `phone` through the voice provider, `vellum` and `platform`
- * internally.
+ * of their own: `phone` through the voice provider, `vellum`, `vellum-shared`
+ * and `platform` internally.
  */
 export const CHANNEL_BOT_PROVIDER = {
   slack: "slack_channel",