@vellumai/vellum-gateway 0.9.0 → 0.10.0-staging.2

package/AGENTS.md

@@ -16,10 +16,7 @@ Why: the gateway is the single point of ingress, handling TLS termination, auth,
 
 All assistant API requests from clients, CLI, skills, and user-facing tooling **MUST** target gateway URLs. Never construct URLs using the daemon runtime port (`7821`) or `RUNTIME_HTTP_PORT` for external API consumption.
 
-**Exception boundary:** The gateway service itself may call the runtime internally. Tests may use direct runtime URLs for isolated unit/integration scenarios. Intentional local daemon-control paths are exempt:
-
-- `clients/shared/Network/DaemonClient.swift`
-- `clients/macos/vellum-assistant/Features/Settings/SettingsConnectTab.swift` (health probe)
+**Exception boundary:** The gateway service itself may call the runtime internally. Tests may use direct runtime URLs for isolated unit/integration scenarios. Intentional local daemon-control paths (e.g. health probes) are exempt; the authoritative allowlist lives in `assistant/src/__tests__/gateway-only-guard.test.ts`.
 
 **Migration rule:** If a needed endpoint is not available at the gateway, add a gateway route/proxy first, then consume it. Do not work around a missing gateway endpoint by hitting the runtime directly.
 
@@ -67,3 +64,80 @@ Gateway inbound events use a channel-discriminated union model (`GatewayInboundE
 Trust/guardian decisions must be keyed on `actorExternalId` only — never fall back to `conversationExternalId` for actor identity.
 
 Physical DB column names (`externalUserId`, `externalChatId`) are unchanged; the rename is at the API/type layer only.
+
+## Channel Trust Classification & Admission Policy
+
+The gateway owns per-channel `AdmissionPolicy` storage (`gateway/src/db/admission-policy-store.ts`, HTTP in `gateway/src/http/routes/channel-admission-policy.ts`) and attaches the floor to every forwarded inbound via `sourceMetadata.admissionPolicy`. The runtime (`assistant/src/runtime/routes/inbound-stages/admission-policy.ts`) emits `admitted: true | false` based on `TRUST_CLASS_RANK[trustClass] >= ADMISSION_FLOOR[policy]`.
+
+A default row per enforced channel is **seeded at startup** (`seedAdmissionPolicyDefaults` in `gateway/src/db/seed-admission-policy.ts`) — `trusted_contacts` for every channel except `vellum` (`guardian_only`). Per-channel defaults live only in that seed; the store/cache fall back to `ADMISSION_POLICY_DEFAULT` (`trusted_contacts`) only if a row is somehow absent.
+
+**5 policies, ranked floors** (seed default `trusted_contacts`):
+
+| Policy | Floor | Notes |
+|---|---|---|
+| `no_one` | 5 | Hard-deny at gateway *before* forwarding (kill switch in `handle-inbound.ts`). Includes the guardian — this channel is *OFF*. |
+| `guardian_only` | 4 | Seeded default for `vellum`. |
+| `trusted_contacts` | 3 | Seeded default for all other channels; also the read-path safety fallback. |
+| `any_contact` | 2 | May surface Slack DM / email upgrade challenge on deny. |
+| `strangers` | 1 | May surface upgrade challenge. |
+
+**Exempt channels** (no policy ever applies — gateway **AND** runtime both short-circuit):
+
+- `platform` — internal platform control plane.
+- `a2a` — assistant-to-assistant peer traffic (out of human-trust model).
+
+`phone` is now an enforced channel (voice ingress reads the policy): it seeds the universal default `trusted_contacts` and accepts PUT like other enforced channels.
+
+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`) — 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.
+- Their floor is pinned to the seed default; `seedAdmissionPolicyDefaults` **overwrites** any drifted/legacy row at startup (e.g. a stale `whatsapp = no_one`), so a stranded floor can't silently block a channel the user can no longer see or reset. The guardian is always max-rank on `vellum`, so its `guardian_only` seed default never locks them out — there is **no** `no_one` picker or 422 kill-switch path for hidden channels.
+
+Only the **assistant-scoped** routes (`/v1/assistants/:id/channel-admission-policy/...`) exist; admission policy is gateway-global so the id is matched and discarded. (The flat `/v1/channel-admission-policy/...` variants were removed with the CLI that used them.)
+
+**Split enforcement** (locked decision):
+
+- **Gateway kill switch** — `handle-inbound.ts` enforces the `no_one` floor before forwarding. Zero contact-table lookups, zero daemon I/O, true kill.
+- **Runtime floor** — every other policy flows through the gateway unchanged; the runtime evaluates rank-vs-floor inside `admission-policy.ts`. This keeps the canonical `actor-trust-resolver.ts:280` classifier as the single source of `TrustClass` truth (no fork).
+- **Gateway vs runtime reciprocity** — the gateway section in `gateway/CLAUDE.md` records *which channels the gateway enforces*; the assistant section records *how the runtime classifies*. Either side getting out of sync is a bug, not an over-defended boundary.
+
+**Adding a new policy**: extend the `AdmissionPolicy` union in `packages/gateway-client/src/admission-policy-contract.ts`, add its floor in `ADMISSION_FLOOR`, update the openapi schema, and update `gateway/src/__tests__/channel-admission-policy-routes.test.ts` + `assistant/src/runtime/routes/inbound-stages/admission-policy.test.ts`. Do not add a 6th floor without also bumping the `TRUST_CLASS_RANK` ceiling to match.
+
+**Adding a new exempt channel**: update `ADMISSION_POLICY_EXEMPT_CHANNELS` in `packages/gateway-client/src/admission-policy-contract.ts` AND `EXEMPT_CHANNEL_TYPES` in `gateway/src/db/admission-policy-store.ts`. The gateway route (403), GET-list omission, runtime short-circuit, and seed-skip all read from these — symmetric enforcement is required so a stray runtime call (test harness, internal IPC) can't bypass the floor.
+
+**Hiding a channel from the UI (still enforced)**: add it to `ADMISSION_POLICY_HIDDEN_CHANNELS` in `packages/gateway-client/src/admission-policy-contract.ts` (and the web mirror `HIDDEN_CHANNELS` in `clients/web/src/lib/channel-admission-policy/types.ts`). The GET-list omission, `PUT`/`DELETE` 403, and seed re-pin all read from this set. Use this — **not** the exempt set — for a channel that must keep enforcing a floor but should not be user-configurable, so its admission check is never short-circuited.
+
+### Trust Classes → Capabilities (what an actor may do)
+
+Two orthogonal axes, do not conflate them:
+
+- **Admission** (above) — *who gets in the door*. `TRUST_CLASS_RANK` vs `ADMISSION_FLOOR`, enforced across gateway + runtime.
+- **Capabilities** — *what an actor may do once admitted*. Resolved in the runtime, never on the gateway.
+
+**Trust classes** (`TrustClass` in `assistant/src/runtime/actor-trust-resolver.ts`) are the *role*, ranked by `TRUST_CLASS_RANK`:
+
+| Class | Rank | Meaning |
+|---|---|---|
+| `guardian` | 4 | Matches the active guardian binding for this (assistant, channel). |
+| `trusted_contact` | 3 | Active contact channel, not the guardian. |
+| `unverified_contact` | 2 | Contact channel that is `pending`/`unverified` — known but not verified. |
+| `unknown` | 1 | No contact record, no identity, or blocked/revoked. Fail-closed. |
+
+The gateway classifies the actor at ingress (keyed on `actorExternalId`) and forwards the resolved `trustClass`; it is persisted in retry payloads, the journal store, and conversation CRUD. The gateway does **not** compute capabilities.
+
+**Capability resolution** lives in `assistant/src/runtime/capabilities.ts`. `resolveCapabilities(trustClass) → CapabilitySet` is the **single fail-closed trust boundary** for the "what may they do" axis, separating permissions from the raw class the way RBAC separates permissions from roles:
+
+- **Total & fail-closed.** Accepts any string or `undefined`; anything not a recognized class (incl. legacy strings like `"non_guardian"`) resolves to the `unknown` set. The lookup uses an own-property check so inherited keys (`"__proto__"`, `"constructor"`, `"toString"`) also fail closed.
+- **`trusted_contact` ≡ `unverified_contact`.** They share the same `CapabilitySet` object — the distinction is admission-only. Pinned by `capabilities.test.ts`.
+- **`CapabilitySet` fields**: `canSelfApproveTools`, `sensitiveToolApproval` (`self | escalate-and-wait | deny`), `canManageSchedules`, `canUseVerificationControlPlane`, `canSelfAuthorizeArchiveBySender`, `canAccessMemory`, `canAccessPrivilegedDocuments`, `canRunUnsandboxedShell`, `mayBeInteractive`, `canActUnderDiskPressureCleanup`, `promptTrustGuidance` (`none | social-engineering-defense | stranger-warning`). All the booleans except `mayBeInteractive` are guardian-only; `mayBeInteractive` is also true for contacts.
+
+**How call sites use it.** Read a named capability instead of re-deriving from the raw class — e.g. `if (!resolveCapabilities(trustClass).canAccessMemory) skip`. Context-dependent decisions **compose** a capability primitive with runtime context rather than encoding it in the table: `resolveRoutingState` uses `mayBeInteractive && guardianRouteResolvable`; `document-tool` uses `canAccessPrivilegedDocuments || executionChannel === "vellum"`; the self-approval race guard uses `!canSelfApproveTools && <pending-row state>`. The legacy `isUntrustedTrustClass` helper has been removed — use `!resolveCapabilities(x).<cap>`.
+
+**Stateless.** Capabilities are derived on read from the already-persisted/forwarded `trustClass`; nothing capability-shaped is stored or sent on the wire.
+
+**Adding a capability**: add the field to `CapabilitySet` + the three class records (`GUARDIAN_CAPABILITIES`, `CONTACT_CAPABILITIES`, `UNKNOWN_CAPABILITIES`) + the `MATRIX` in `capabilities.test.ts`. **Adding a trust class**: add a member to `TrustClass` (the `Record<TrustClass, …>` tables then fail to compile until every column is filled) and a matrix row.
+
+**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.

package/ARCHITECTURE.md

@@ -34,9 +34,9 @@ Internet
 
 ### STT Route Proxying (Assistant-Scoped Rewrite)
 
-Native clients (macOS, iOS) send speech-to-text transcription requests through the gateway to the daemon's STT service. Clients POST to the assistant-scoped path `/v1/assistants/:assistantId/stt/transcribe`, which the gateway's runtime proxy rewrites to the flat daemon path `/v1/stt/transcribe`. This follows the same assistant-scoped rewrite pattern used by other client-facing endpoints (feature flags, privacy config, etc.).
+Clients send speech-to-text transcription requests through the gateway to the daemon's STT service. Clients POST to the assistant-scoped path `/v1/assistants/:assistantId/stt/transcribe`, which the gateway's runtime proxy rewrites to the flat daemon path `/v1/stt/transcribe`. This follows the same assistant-scoped rewrite pattern used by other client-facing endpoints (feature flags, privacy config, etc.).
 
-The request carries base64-encoded WAV audio and a MIME type. The daemon resolves the configured STT provider via `resolveBatchTranscriber()` and returns the transcribed text. Clients use the response to implement a service-first strategy: the service transcription takes precedence when available, with Apple-native `SFSpeechRecognizer` as fallback when the service returns 503 (not configured) or fails.
+The request carries base64-encoded WAV audio and a MIME type. The daemon resolves the configured STT provider via `resolveBatchTranscriber()` and returns the transcribed text. Clients use the response to implement a service-first strategy: the service transcription takes precedence when available, with a client-local fallback when the service returns 503 (not configured) or fails.
 
 | Client path (gateway)               | Daemon path (after rewrite) | Method |
 | ----------------------------------- | --------------------------- | ------ |
@@ -48,12 +48,11 @@ The request carries base64-encoded WAV audio and a MIME type. The daemon resolve
 | ------------------------------------------------ | ------------------------------------------------------------------------- |
 | `gateway/src/http/routes/runtime-proxy.ts`       | Assistant-scoped path rewriting (`/v1/assistants/:id/...` → `/v1/...`)    |
 | `assistant/src/runtime/routes/stt-routes.ts`     | Daemon HTTP endpoint: validates audio, resolves transcriber, returns text |
-| `clients/shared/Network/STTClient.swift`         | Shared client: POSTs audio to the gateway, returns typed `STTResult`      |
-| `clients/shared/Utilities/AudioWavEncoder.swift` | WAV encoding utility for PCM audio buffers                                |
+| `clients/web/src/domains/chat/voice/stt-api.ts`     | Web client: POSTs audio to the gateway, returns a typed result            |
 
 ### STT Streaming WebSocket Proxy
 
-Native clients (macOS, iOS) 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.
+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.
 
@@ -80,7 +79,7 @@ Native clients (macOS, iOS) open WebSocket connections through the gateway to th
 | `gateway/src/index.ts`                            | Route registration: wires upgrade handler to the gateway's Bun HTTP server                                         |
 | `assistant/src/runtime/http-server.ts`            | Daemon-side WebSocket upgrade at `/v1/stt/stream`, session creation and registry                                   |
 | `assistant/src/stt/stt-stream-session.ts`         | Runtime session orchestrator: drives the `StreamingTranscriber` from the WebSocket                                 |
-| `clients/shared/Network/STTStreamingClient.swift` | Swift client: builds the gateway WS URL via `GatewayHTTPClient.buildWebSocketRequest`                              |
+| `clients/web/src/domains/chat/voice/dictation-stream.ts` | Web client: opens the gateway WebSocket, parses transcript events, reports failures                            |
 
 ### Assistant Feature Flags API
 

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

@@ -74,7 +74,11 @@ function createMockTransport(): CesTransport & {
   messages: string[];
   messageHandler: ((msg: string) => void) | null;
   alive: boolean;
+  /** Simulate the transport dying (e.g. a spurious stdout EOF): mark it dead
+   *  and fire the registered close handlers, as the real transports do. */
+  die: () => void;
 } {
+  const closeHandlers: Array<() => void> = [];
   const transport = {
     messages: [] as string[],
     messageHandler: null as ((msg: string) => void) | null,
@@ -88,9 +92,16 @@ function createMockTransport(): CesTransport & {
     isAlive() {
       return transport.alive;
     },
+    onClose(handler: () => void) {
+      closeHandlers.push(handler);
+    },
     close() {
       transport.alive = false;
     },
+    die() {
+      transport.alive = false;
+      for (const handler of closeHandlers) handler();
+    },
   };
   return transport;
 }
@@ -605,6 +616,42 @@ describe("CesRpcClient", () => {
     expect(client.isReady()).toBe(false);
   });
 
+  test("a pending request fails fast when the transport dies (no timeout wait)", async () => {
+    const transport = createMockTransport();
+    const client = createCesRpcClient(transport, {
+      handshakeTimeoutMs: 5000,
+      // Long timeout on purpose: the call must reject from the transport
+      // DEATH, not this timer. Without the fail-fast it would hang 60s.
+      requestTimeoutMs: 60_000,
+    });
+
+    // Handshake
+    const hPromise = client.handshake();
+    const hSent = JSON.parse(transport.messages[0]!);
+    transport.messageHandler!(
+      JSON.stringify({
+        type: "handshake_ack",
+        protocolVersion: CES_PROTOCOL_VERSION,
+        sessionId: hSent.sessionId,
+        accepted: true,
+      }),
+    );
+    await hPromise;
+
+    const callPromise = client.call("list_credentials", {});
+
+    // The transport's read side dies (e.g. a spurious stdout EOF on a CES
+    // bounce) while the request is in flight — the response can never arrive.
+    transport.die();
+
+    try {
+      await callPromise;
+      throw new Error("should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(CesTransportError);
+    }
+  });
+
   test("subsequent handshake call returns immediately if already ready", async () => {
     const transport = createMockTransport();
     const client = createCesRpcClient(transport, { handshakeTimeoutMs: 5000 });

package/node_modules/@vellumai/ces-client/src/rpc-client.ts

@@ -45,6 +45,14 @@ export interface CesTransport {
   isAlive(): boolean;
   /** Tear down the transport connection. */
   close(): void;
+  /**
+   * Register a callback that fires once when the transport dies (its read side
+   * ends, the process exits, or the socket closes). Lets the client fail-fast
+   * any in-flight requests instead of letting each wait out its timeout.
+   * Optional: a transport that doesn't implement it falls back to
+   * timeout-based failure.
+   */
+  onClose?(handler: () => void): void;
 }
 
 // ---------------------------------------------------------------------------
@@ -155,6 +163,16 @@ export function createCesRpcClient(
 
   const pending = new Map<string, PendingRequest>();
 
+  /** Reject and clear every in-flight request. Shared by `close()` and the
+   *  transport-death handler. */
+  function rejectAllPending(error: Error): void {
+    for (const [id, entry] of pending) {
+      clearTimeout(entry.timer);
+      pending.delete(id);
+      entry.reject(error);
+    }
+  }
+
   // -------------------------------------------------------------------------
   // Incoming message dispatch
   // -------------------------------------------------------------------------
@@ -209,6 +227,15 @@ export function createCesRpcClient(
     }
   });
 
+  // Fail-fast on transport death: when the transport's read side ends (e.g. a
+  // spurious stdout EOF on a CES bounce) or the connection closes, reject every
+  // in-flight request immediately. The response can never arrive on a dead
+  // transport, so without this a pending call hangs until `requestTimeoutMs`
+  // (observed: 30s stalls on credential reads that raced a CES restart).
+  transport.onClose?.(() => {
+    rejectAllPending(new CesTransportError("CES transport closed"));
+  });
+
   // -------------------------------------------------------------------------
   // Send helpers
   // -------------------------------------------------------------------------
@@ -384,11 +411,7 @@ export function createCesRpcClient(
     },
 
     close(): void {
-      for (const [id, entry] of pending) {
-        clearTimeout(entry.timer);
-        entry.reject(new CesTransportError("CES client closed"));
-        pending.delete(id);
-      }
+      rejectAllPending(new CesTransportError("CES client closed"));
       ready = false;
       transport.close();
     },

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

@@ -0,0 +1,97 @@
+/**
+ * Shared admission policy vocabulary used on the gateway→runtime wire.
+ *
+ * Both the gateway (channel admission policy storage + kill switch) and the
+ * runtime (admission-policy stage) consume these values. Keeping the type
+ * here avoids the runtime importing from `gateway/src` and avoids the
+ * vocabulary drift the plan §2.1 flags for the verification-purpose
+ * `trustClass` enum.
+ */
+
+import { z } from "zod";
+
+/**
+ * Per-channel inbound admission policy — ordered from most-restrictive
+ * (`no_one`, hard kill switch) to most-permissive (`strangers`, admits any
+ * sender). See `unverified-contact-role-plan.md` §2.3.
+ */
+export const ADMISSION_POLICY_VALUES = [
+  "no_one",
+  "guardian_only",
+  "trusted_contacts",
+  "any_contact",
+  "strangers",
+] as const;
+
+export type AdmissionPolicy = (typeof ADMISSION_POLICY_VALUES)[number];
+
+export const AdmissionPolicySchema = z.enum(ADMISSION_POLICY_VALUES);
+
+/**
+ * Read-side default applied when a channel has no row in the DB. Matches
+ * today's effective semantics: guardian + active contacts admitted,
+ * strangers denied. See plan §2.2.
+ */
+export const ADMISSION_POLICY_DEFAULT: AdmissionPolicy = "trusted_contacts";
+
+/**
+ * Minimum trust rank required for each policy. Higher rank = more trusted.
+ * `no_one` is 5 — above the maximum guardian rank (4) — so no class is ever
+ * admitted. See plan §2.4 for the rank table.
+ */
+export const ADMISSION_FLOOR: Record<AdmissionPolicy, number> = {
+  no_one: 5,
+  guardian_only: 4,
+  trusted_contacts: 3,
+  any_contact: 2,
+  strangers: 1,
+};
+
+/**
+ * Hard-exempt internal channels — never subject to PUT policy, omitted from
+ * GET list, runtime admission stage short-circuits without floor check.
+ *
+ * `platform` / `a2a` are peer/internal channels with no human-trust model.
+ *
+ * `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
+ * {@link ADMISSION_POLICY_HIDDEN_CHANNELS}.
+ */
+export const ADMISSION_POLICY_EXEMPT_CHANNELS: ReadonlySet<string> = new Set([
+  "platform",
+  "a2a",
+]);
+
+export function isAdmissionPolicyExemptChannel(channelType: string): boolean {
+  return ADMISSION_POLICY_EXEMPT_CHANNELS.has(channelType);
+}
+
+/**
+ * Channels omitted from the Channel Trust Floors list (GET) and rejected on
+ * PUT/DELETE — managed automatically at their seed default, not user
+ * configurable. Unlike {@link ADMISSION_POLICY_EXEMPT_CHANNELS} they are still
+ * enforced at runtime, so hiding a real inbound channel like `whatsapp` never
+ * silently disables its admission floor check. The startup seed re-pins any
+ * drifted row so a stale floor (e.g. a legacy `no_one`) can't strand a channel
+ * the user can no longer see.
+ *
+ * `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.
+ */
+export const ADMISSION_POLICY_HIDDEN_CHANNELS: ReadonlySet<string> = new Set([
+  "vellum",
+  "whatsapp",
+]);
+
+export function isAdmissionPolicyHiddenChannel(channelType: string): boolean {
+  return ADMISSION_POLICY_HIDDEN_CHANNELS.has(channelType);
+}
+
+export function isAdmissionPolicy(value: unknown): value is AdmissionPolicy {
+  return (
+    typeof value === "string" &&
+    (ADMISSION_POLICY_VALUES as readonly string[]).includes(value)
+  );
+}

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

@@ -12,6 +12,8 @@
 
 import { z } from "zod";
 
+import { AdmissionPolicySchema } from "./admission-policy-contract.js";
+
 // ---------------------------------------------------------------------------
 // Command intent (channel-initiated commands, e.g. Telegram /start)
 // ---------------------------------------------------------------------------
@@ -67,6 +69,14 @@ export const SourceMetadataSchema = z
     /** Slack workspace/team ID. */
     account: z.string().optional(),
 
+    /**
+     * Per-channel inbound admission policy attached by the gateway. The
+     * runtime admission-policy stage enforces the floor against the
+     * resolved trust class; when absent, the runtime falls back to
+     * `ADMISSION_POLICY_DEFAULT` (`trusted_contacts`).
+     */
+    admissionPolicy: AdmissionPolicySchema.optional(),
+
     // Email-specific fields
     /** Email subject line. */
     emailSubject: z.string().optional(),

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

@@ -19,20 +19,26 @@ export * from "./gateway-ipc-contracts.js";
 
 export { ipcCall, IpcCallError, PersistentIpcClient } from "./ipc-client.js";
 
+// Outbound delivery contract (daemon → gateway) — Zod schemas + derived types
+export {
+  ApprovalActionOptionSchema,
+  ApprovalUIMetadataSchema,
+  AttachmentMetadataSchema,
+  ChannelDeliveryResultSchema,
+  ChannelReplyPayloadSchema,
+  PermissionRequestDetailsSchema,
+} from "./outbound-contract.js";
+
 export type {
   ApprovalActionOption,
   ApprovalUIMetadata,
   AttachmentMetadata,
   ChannelDeliveryResult,
   ChannelReplyPayload,
-  IpcRequest,
-  IpcResponse,
-  Logger,
   PermissionRequestDetails,
-} from "./types.js";
-
-export { noopLogger } from "./types.js";
+} from "./outbound-contract.js";
 
+// Inbound contract (gateway → daemon) — Zod schemas + derived types
 export {
   CommandIntentSchema,
   RuntimeInboundPayloadSchema,
@@ -44,3 +50,23 @@ export type {
   RuntimeInboundPayload,
   SourceMetadata,
 } from "./inbound-contract.js";
+
+// IPC, logger, and utility types
+export type { IpcRequest, IpcResponse, Logger } from "./types.js";
+
+export { noopLogger } from "./types.js";
+
+// Admission policy contract (gateway → daemon) — Zod schemas + derived types + channel sets
+export {
+  ADMISSION_FLOOR,
+  ADMISSION_POLICY_DEFAULT,
+  ADMISSION_POLICY_EXEMPT_CHANNELS,
+  ADMISSION_POLICY_HIDDEN_CHANNELS,
+  ADMISSION_POLICY_VALUES,
+  AdmissionPolicySchema,
+  isAdmissionPolicy,
+  isAdmissionPolicyExemptChannel,
+  isAdmissionPolicyHiddenChannel,
+} from "./admission-policy-contract.js";
+
+export type { AdmissionPolicy } from "./admission-policy-contract.js";

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

@@ -0,0 +1,119 @@
+/**
+ * Daemon → gateway outbound delivery contract.
+ *
+ * Zod schemas defining the wire format for channel replies delivered from
+ * the daemon to the gateway via `POST /deliver/{channel}`. Both services
+ * import from here so the contract is enforced at compile time.
+ *
+ * The daemon constructs these payloads in `deliverChannelReply()` and
+ * `deliverApprovalPrompt()`; the gateway validates and dispatches them
+ * to the target channel provider.
+ */
+
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Attachment metadata
+// ---------------------------------------------------------------------------
+
+export const AttachmentMetadataSchema = z.object({
+  id: z.string(),
+  filename: z.string(),
+  mimeType: z.string(),
+  sizeBytes: z.number(),
+  kind: z.string(),
+  data: z.string().optional(),
+  thumbnailData: z.string().optional(),
+  fileBacked: z.boolean().optional(),
+});
+
+export type AttachmentMetadata = z.infer<typeof AttachmentMetadataSchema>;
+
+// ---------------------------------------------------------------------------
+// Approval UI types
+// ---------------------------------------------------------------------------
+
+export const ApprovalActionOptionSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+});
+
+export type ApprovalActionOption = z.infer<typeof ApprovalActionOptionSchema>;
+
+export const PermissionRequestDetailsSchema = z.object({
+  toolName: z.string(),
+  riskLevel: z.string(),
+  toolInput: z.record(z.string(), z.unknown()),
+  requesterIdentifier: z.string().optional(),
+});
+
+export type PermissionRequestDetails = z.infer<
+  typeof PermissionRequestDetailsSchema
+>;
+
+export const ApprovalUIMetadataSchema = z.object({
+  requestId: z.string(),
+  actions: z.array(ApprovalActionOptionSchema),
+  plainTextFallback: z.string(),
+  permissionDetails: PermissionRequestDetailsSchema.optional(),
+});
+
+export type ApprovalUIMetadata = z.infer<typeof ApprovalUIMetadataSchema>;
+
+// ---------------------------------------------------------------------------
+// Channel reply payload — the full outbound wire format
+// ---------------------------------------------------------------------------
+
+export const ChannelReplyPayloadSchema = z.object({
+  chatId: z.string(),
+  text: z.string().optional(),
+  /** Pre-formatted Block Kit blocks for Slack delivery. */
+  blocks: z.array(z.unknown()).optional(),
+  assistantId: z.string().optional(),
+  attachments: z.array(AttachmentMetadataSchema).optional(),
+  approval: ApprovalUIMetadataSchema.optional(),
+  chatAction: z.literal("typing").optional(),
+  /**
+   * When true, deliver via `chat.postEphemeral` so only the target `user`
+   * sees the message.
+   */
+  ephemeral: z.boolean().optional(),
+  /** Slack user ID — required when `ephemeral` is true. */
+  user: z.string().optional(),
+  /** When provided, update an existing message instead of posting a new one. */
+  messageTs: z.string().optional(),
+  /** When true, auto-generate Block Kit blocks from text via textToBlocks(). */
+  useBlocks: z.boolean().optional(),
+  /** When provided, add or remove an emoji reaction on a message. */
+  reaction: z
+    .object({
+      action: z.enum(["add", "remove"]),
+      name: z.string(),
+      messageTs: z.string(),
+    })
+    .optional(),
+  /** When provided, set or clear the Slack Assistants API thread status. */
+  assistantThreadStatus: z
+    .object({
+      channel: z.string(),
+      threadTs: z.string(),
+      status: z.string(),
+      /** Serialized to Slack as `loading_messages`. */
+      loadingMessages: z.array(z.string()).optional(),
+    })
+    .optional(),
+});
+
+export type ChannelReplyPayload = z.infer<typeof ChannelReplyPayloadSchema>;
+
+// ---------------------------------------------------------------------------
+// Channel delivery result — gateway response
+// ---------------------------------------------------------------------------
+
+export const ChannelDeliveryResultSchema = z.object({
+  ok: z.boolean(),
+  /** The message timestamp returned by the delivery endpoint. */
+  ts: z.string().optional(),
+});
+
+export type ChannelDeliveryResult = z.infer<typeof ChannelDeliveryResultSchema>;