@vellumai/assistant 0.12.3-staging.1 → 0.12.3-staging.2

package/docs/mode-sessions.md

@@ -0,0 +1,183 @@
+# Transcript mode sessions
+
+Mode sessions are compact, conversation-owned lifecycle records for grouping
+computer-use, browser, Live vision, and reserved Ambient transcript activity.
+They connect runtime producers to immutable message membership while keeping
+model input and stored message content unchanged.
+
+## API contract
+
+`src/api/mode-session.ts` owns both shared shapes:
+
+- `ModeSession` is immutable transcript membership: an opaque `id` and one of
+  `computer_use`, `browser`, `live_vision`, or `ambient`.
+- `ModeSessionSummary` is the durable lifecycle record. It carries the owning
+  conversation, mode, timing bounds, boundary message IDs, terminal reason,
+  and a positive monotonic revision.
+
+Only three statuses are stored: `active`, `completed`, and `interrupted`.
+Waiting and draining are runtime presentation facts and do not add database
+states. Duration is derived from recorded time bounds instead of stored as a
+separate value. Active records have no terminal fields, completed records have
+a confirmed end, and interrupted records may leave the end unknown. A known end
+never precedes the last confirmed activity.
+
+## Persistence
+
+Migration 381 creates `conversation_mode_sessions`. Each row belongs to one
+conversation through an `ON DELETE CASCADE` foreign key. The
+`(conversation_id, status)` index supports conversation-scoped active reads,
+while the primary key supports bounded ID batches for transcript pages.
+
+`conversation-mode-sessions.ts` is the only lifecycle writer. Begin creates
+revision 1. Activity, boundary, revision-only, and terminal updates require the
+caller's expected revision and run in an immediate transaction. Each accepted
+write increments the revision. A stale revision, missing record, or terminal
+record is returned as an expected write outcome. Terminal rows cannot return
+to active or change to a different terminal result. Repeating the same terminal
+outcome is an accepted no-op and does not advance the revision.
+
+The first included boundary can precede source activation when a later action
+claims assistant content already persisted in the same logical turn. Last
+activity never moves backward. An interruption may have an unknown end, so
+`endedAt` remains nullable and `lastActivityAt` remains the last confirmed
+time.
+
+## Startup recovery
+
+After database migrations succeed, the assistant marks every leftover active
+record interrupted before database readiness is published. Recovery increments
+the revision, preserves activity and message boundaries, records
+`assistant_restarted`, and leaves `endedAt` null. It runs on every boot rather
+than as a checkpointed migration.
+
+If this auxiliary recovery fails, ordinary database readiness succeeds and
+tracking stays unavailable for that boot. History omits unrecovered active
+descriptors while preserving terminal records and message stamps. A subsequent
+boot retries through the same startup path. Required migration failures still
+block database readiness.
+
+Runtime source generations and structural question associations are owned by
+the producer and message-membership integration. Those process-local facts are
+not reconstructed after restart. Resumed mode work uses a fresh session ID and
+callbacks from retired source generations are rejected.
+
+New producer admissions are controlled by the default-off `session-groups`
+assistant feature flag. Browser and computer-use actions still execute when the
+flag is off, but they do not activate or claim a mode session. Existing owners
+and terminal cleanup continue to drain so disabling the flag cannot strand
+accepted work. Live voice snapshots the flag when its socket session is
+created: disabled sessions retain the existing camera transport without
+advertising or preparing tracked sight-session epochs.
+
+The same flag controls activity-label wording at the shared rendering
+boundary. Disabled views retain their existing labels and phase grouping.
+
+The migration, startup recovery, persisted message stamps, and history reads
+remain available while the flag is off. This keeps records made by an enabled
+cohort compatible with rollback and later re-enablement.
+
+## Runtime ownership
+
+Each live `Conversation` owns one `ConversationModeSessionCoordinator`.
+Computer-use, browser, and camera producers activate a source with a stable
+source identity and guarded generation. The first accepted mode action claims
+the logical turn. The coordinator backfills rows already persisted for that
+turn, then stamps later user, assistant, and tool-result rows as they are
+inserted. A turn keeps its first owner when another mode acts inside it.
+
+Source eligibility and captured turn ownership end separately. Ending or
+resetting a source prevents future claims immediately, but a captured turn
+keeps its owner until its final output is persisted. Ordinary computer-use and
+browser sources finish when the turn settles. Camera sources use a source
+lifetime plus a synthetic run turn, so accepted frame writes and captured
+voice turns form a settlement barrier before terminal persistence. A camera
+epoch snapshots ownership before asynchronous frame persistence; stale epochs
+cannot join a later run.
+
+Tracking failures are logged and isolated from authorized actions and accepted
+content persistence. They never repeat the underlying action. A refused camera
+start clears client negotiation and falls back to untracked frames without
+revoking consent or ending voice. Individual stale-frame rejection does not
+use this fallback.
+
+Server admission is the camera boundary: an admitted frame can finish saving
+after stop, but a device-side capture delivered after its run ends is rejected
+and reclaimed. Reconnect pauses capture delivery and announces a fresh run
+after replacement readiness. In-flight uploads and native samples retain their
+captured ownership and cannot join the replacement run.
+
+The coordinator stores only `active`, `completed`, or `interrupted`. Waiting
+and finishing are revisioned runtime hints. Terminal dispositions remain
+pending in memory until all captured turns release, then one idempotent
+compare-and-swap update records the terminal outcome. A successful turn with
+no explicit producer end also finalizes, allowing later work from the same
+resource generation to mint a new session.
+
+Regular reload, TTL, LRU, and memory-pressure eviction retain a conversation
+while it has an eligible mode source, captured owner, structural association,
+or unsettled terminal disposition. This preserves accepted camera output and
+exact structural continuation in the coordinator that admitted them. A long
+structural wait therefore remains resident until it is consumed, invalidated,
+or its source retires. Explicit conversation deletion and process shutdown
+keep their existing teardown semantics; startup recovery interrupts any
+durable active record left by process exit.
+
+Invalidating the final structural association retires a turn-lifetime source
+and lets accepted output settle. Successful abandoned waits end at their last
+confirmed activity with reason `structural_wait_abandoned`; cleanup does not
+extend their duration. Source-lifetime camera runs remain eligible. A retired
+disposition that cannot persist its terminal update releases residency and
+invalidates history without claiming completion. An active record without live
+ownership has no descriptor and renders as unavailable.
+
+## Structural continuation
+
+Structural waits associate an exact response identifier with the owned turn.
+Ordinary `ask_question` awaits its resolver inside that turn, so its answer
+resumes the existing owner. A blocking UI surface can accept a new turn: its
+matching response consumes the association before surface cleanup and retains
+the session ID. Rejected, stale, unrelated, or cross-conversation responses
+cannot inherit ownership. Dismissal invalidates the association. Ordinary prose
+and an idle reusable resource do not continue a session; later mode work starts
+a fresh ID and duration.
+
+Structural associations intentionally do not survive restart. Startup recovery
+terminalizes the old record, and a late response remains part of the existing
+interaction flow without reopening that record.
+
+## Transcript and synchronization
+
+`modeSession` is optional message metadata and is stripped from caller-supplied
+metadata. Membership is added only after a row insert succeeds. Text and
+thinking deltas carry no repeated ownership field; row-boundary events carry
+the current owner, and the normal conversation-messages invalidation refetches
+retrospective stamps.
+
+History returns one batched `modeSessions` descriptor list beside messages.
+The query resolves records for page members and accepts bounded explicit IDs
+for groups already loaded outside the newest page. Consolidation never crosses
+a stamped/unstamped or different-owner boundary. Same-owner folds retain row
+aliases and `modeSessionActivity.firstAt`/`lastAt`, so donor timestamps survive
+history compaction.
+
+Message deletion and retry paths recompute replaceable first/last display
+boundaries for every affected conversation session. They preserve status,
+terminal time, reason, and confirmed activity, and increment the revision.
+Deleting every owned row leaves the lifecycle record available for audit but
+produces no transcript container.
+
+All membership, lifecycle, boundary, and runtime-hint changes reuse the
+conversation-messages `sync_changed` tag. Clients merge descriptors by
+revision in the history query cache and refetch through the existing history
+reconciliation path. Explicit stale revisions cannot replace newer cached
+descriptors; an omitted descriptor remains unavailable. There is no separate
+descriptor store, session event stream, or polling endpoint.
+
+The transcript keeps lightweight segment identities for stable disclosure keys,
+not duplicate message bodies. Closed children unmount, and eligible mounted
+headers share one coarse clock that pauses while the app is hidden. No header
+visibility observer is required. The clock reads initial desktop visibility
+from the existing attention state on its coarse tick, without publishing a
+shared lifecycle edge. With grouping disabled, the load-older guard uses the
+ordinary flat-transcript behavior and skips grouped DOM scans.

package/docs/voice-input-diagnostics.md

@@ -0,0 +1,58 @@
+# Voice input diagnostics
+
+Hands-free voice records signal measurements in the ordinary support log export. This includes calls started from the macOS companion. These diagnostics do not change capture constraints, speech thresholds, interruption timing, or task cancellation. They add no PCM recordings, transcript text, microphone labels, or device identifiers.
+
+## Collect a reproduction
+
+Use the same microphone, output device, volume, and companion surface as the failing call. Note whether output is through headphones or speakers.
+
+1. Start a companion voice call. Stay quiet for about 20 seconds to capture the room baseline.
+2. Ask for an explanation long enough to produce sustained speech. Stay quiet while it answers; note the time of any unexpected cutoff.
+3. Ask it to start a background investigation. Stay quiet during startup; note missing acknowledgements or cancelled starts.
+4. Deliberately interrupt an answer with a short spoken question. This provides a real interruption to compare against the unexplained cutoffs.
+5. End the call and export logs through the existing feedback log export.
+
+Keep the initial reproduction on the original audio setup. A second call using headphones, or using the built-in microphone instead of a headset, can isolate a route-dependent problem after the first capture.
+
+## Client records
+
+`[live-voice-input]` entries are serialized JSON in `electron-main-logs.txt`. Electron collects them from every renderer, so export does not depend on which window hosts the companion call. The same events appear as `voice_input` in the web diagnostics lifecycle ring.
+
+- `capture_started` and `input_switched` report applied echo cancellation, noise suppression, gain control, channel count, and track/context/output sample rates. `null` means the browser did not report a setting. An explicit device selection reports whether it matched, without logging either device identifier.
+- `capture_mute`, `capture_unmute`, `capture_ended`, and `capture_statechange` expose track and audio-context transitions. Listeners retire with the old stream on a device switch or stop.
+- `session_ready` links the client `captureId` to the server `sessionId`. Capture can open before the server is ready, so earlier entries have a null session ID. `entry` identifies the launch surface when supplied.
+- `speech_started`, `turn_cancelled`, and `utterance_discarded` report whether playback was active, held, or actually resumed after an unusable utterance.
+
+## Server records
+
+Search the assistant log for `Live voice input diagnostics` or `voice_input_`. All records include session, input-turn, assistant-turn, and speech-generation identifiers where available, plus the effective threshold, room floor, echo configuration, playback estimate, and foreground-task state.
+
+- `voice_input_window` summarizes each approximately five-second arrival window: received audio duration, zero-signal duration, duration-weighted mean amplitude, minimum/maximum chunk mean amplitude, classified speech/silence/echo duration, and maximum arrival gap. Window emission requires incoming audio; `voice_input_closed` flushes a partial window.
+- The same window includes `sttSubmittedChunks`, `sttSubmittedAudioMs`, and `sttMaxSubmissionGapMs`. These measure handoff to the transcription adapter, not provider receipt. A probe can buffer audio before submission, and the final chunk of an arrival window can be submitted in the next window. Compare sustained windows to identify input that arrives normally but stops reaching transcription.
+- `voice_input_provider_turn_start` and `voice_input_provider_turn_end` record provider boundaries alongside local VAD state. End records include confidence, the provider's `trigger` (`model`, `timeout`, or `manual`), decoded audio position in seconds from stream start, and elapsed time since locally detected speech. Missing provider fields are null. These records describe received decisions, including ones ignored as stale or after fallback; correlate with the turn metrics to identify the boundary that committed the request.
+- `voice_input_microphone_gate_changed` records when the transcription audio gate closes or reopens. `microphoneGateClosed` is included with the other input diagnostics. Closing replaces room audio with silence; it does not commit a transcript or stop local energy detection.
+- `voice_input_barge_in_armed`, `voice_input_barge_in_fired`, and `voice_input_barge_in_expired` distinguish a candidate from an accepted or expired local interruption on providers without native turn detection. Fired events include accumulated speech duration, guard resets, and a bounded trace of the preceding two seconds (at most 40 input chunks).
+- `voice_input_speech_started` includes `source: "provider"` when a Flux `StartOfTurn` triggers the client speech signal and any active-turn cancellation. `source: "local"` identifies local onset or a confirmed pre-dial guard replay; guards completed during ordinary streaming use `voice_input_barge_in_fired`.
+- Each trace entry captures the amplitude and gate/echo state before classification, and classified durations, remaining probe buffer, and correlation result after classification. The classifier can hold a probe and release multiple older chunks together, so a row's classified duration can differ from its received duration. A null correlation means no comparison ran, not a measured zero correlation.
+- `voice_input_speech_routed` binds the speech generation to the input turn that actually receives its audio. At onset, the prior spent cycle may still be installed, so use this routing record for correlation rather than assuming the onset's `inputTurnId` is the new utterance.
+- `voice_input_transcript` reports committed character count and provider, never words. `voice_input_utterance_discarded` reports the discard reason and remaining transcript/partial state.
+
+Amplitude uses the classifier's PCM16 mean-absolute scale, not the client's normalized UI meter. Playback timing is the server's estimate, not proof that sound was heard. An empty transcript is evidence of no usable transcription; it does not establish that the person was silent or that the detector was wrong.
+
+These are local diagnostic logs, not new analytics events or voice protocol fields. Existing log retention and export apply.
+
+## Flux pause handling
+
+When Flux owns turn detection, microphone audio passes through for one second of received audio after the last locally detected speech. After that, the input gate replaces room audio with digital silence while the microphone and local energy detector keep listening. The cutoff is measured in PCM samples, so network batching does not change it. Flux continues receiving elapsed silence and owns the turn boundary; closing this gate does not release the question.
+
+While closed, the gate holds the most recent 200 ms before deciding whether to send those samples as silence or as the lead-in to resumed speech. On speech onset, it forwards that lead-in and the new speech exactly once. The provider feed can lag input by up to 200 ms while idle, then catches up on speech onset. Confirmed playback echo is replaced with silence before entering this buffer. Idle audio is not accumulated into request recordings. Manual capture and locally endpointed providers retain their existing routing.
+
+Flux `StartOfTurn` owns hands-free interruption, independently of the provider end-of-turn setting. Above-threshold microphone audio alone cannot pause playback, cancel a reply, or trigger a speech-start screenshot. A provider turn start emits `speech_started` immediately, without the local sustained-speech delay, and cancels an active reply through the shared interruption path. Duplicate or older provider turn indices are ignored within a stream. Other providers retain the local guard. This waits for provider recognition and does not guarantee rejection of playback echo or background speech that Flux transcribes.
+
+Managed Flux maps provider turn indices into one continuous sequence across transparent relay reconnects. A new relay connection restarting at zero therefore cannot make fresh speech look like a duplicate. If connection setup falls back to a provider without native turn detection, the suppressed local onset is replayed through the local interruption path, preserving its sustained-speech guard result even if the utterance ended during the dial.
+
+The gate shares the existing adaptive energy classifier. Quiet speech within the one-second tail passes through; quiet onset in the 200 ms buffer is preserved if followed by detected speech. Sustained speech entirely below the local threshold can be suppressed, and noise classified as speech can reopen the gate. This limits background exposure rather than guaranteeing that every false transcript is eliminated.
+
+For a focused reproduction, say an unfinished question such as "Did they help invent", pause briefly, then complete it with "ChatGPT". Repeat with a shorter and a longer pause, plus a complete short question. Note when the assistant starts answering and export the logs. Check that STT submissions continue during the pause, then use the provider end event's time, confidence, and trigger to distinguish model endpointing from a timeout. Tests verify audio delivery and event handling; they do not establish how Flux will segment real speech.
+
+For the idle gate, stay silent and type for 20 seconds, then ask a question with a pause longer than one second. Repeat with a quiet voice and with a deliberate interruption during an answer. Check for phantom requests, a clipped first syllable, split questions, and missed interruptions. Correlate those observations with gate transitions and provider turn events.

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/package.json

@@ -27,7 +27,8 @@
     "./reactions": "./src/reactions.ts",
     "./guardian-requests": "./src/guardian-requests.ts",
     "./platform-credential": "./src/platform-credential.ts",
-    "./plan-credit": "./src/plan-credit.ts"
+    "./plan-credit": "./src/plan-credit.ts",
+    "./integration-categories": "./src/integration-categories.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

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

@@ -29,6 +29,7 @@ export * from "./trust-rules.js";
 export * from "./ingress.js";
 export * from "./no-response.js";
 export * from "./plan-credit.js";
+export * from "./integration-categories.js";
 export * from "./platform-credential.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";

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

@@ -0,0 +1,36 @@
+/**
+ * Category vocabulary for the integrations catalog, shared by the assistant
+ * daemon (which stamps it on OAuth providers and marketplace MCP entries) and
+ * the clients (which draw the category filter from it).
+ *
+ * The order here is the order clients show the categories in. The slug is the
+ * wire value; the user-facing label is the client's, so it can be translated.
+ */
+export const INTEGRATION_CATEGORIES = [
+  "productivity",
+  "communication",
+  "meetings",
+  "sales",
+  "marketing",
+  "finance",
+  "commerce",
+  "engineering",
+  "knowledge",
+  "recruiting",
+] as const;
+
+export type IntegrationCategory = (typeof INTEGRATION_CATEGORIES)[number];
+
+const INTEGRATION_CATEGORY_SET: ReadonlySet<string> = new Set(
+  INTEGRATION_CATEGORIES,
+);
+
+/**
+ * Whether `value` names a category this build knows. A client reading a newer
+ * catalog treats an unknown slug as uncategorized rather than failing.
+ */
+export function isIntegrationCategory(
+  value: unknown,
+): value is IntegrationCategory {
+  return typeof value === "string" && INTEGRATION_CATEGORY_SET.has(value);
+}

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/package.json

@@ -27,7 +27,8 @@
     "./reactions": "./src/reactions.ts",
     "./guardian-requests": "./src/guardian-requests.ts",
     "./platform-credential": "./src/platform-credential.ts",
-    "./plan-credit": "./src/plan-credit.ts"
+    "./plan-credit": "./src/plan-credit.ts",
+    "./integration-categories": "./src/integration-categories.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

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

@@ -29,6 +29,7 @@ export * from "./trust-rules.js";
 export * from "./ingress.js";
 export * from "./no-response.js";
 export * from "./plan-credit.js";
+export * from "./integration-categories.js";
 export * from "./platform-credential.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";

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

@@ -0,0 +1,36 @@
+/**
+ * Category vocabulary for the integrations catalog, shared by the assistant
+ * daemon (which stamps it on OAuth providers and marketplace MCP entries) and
+ * the clients (which draw the category filter from it).
+ *
+ * The order here is the order clients show the categories in. The slug is the
+ * wire value; the user-facing label is the client's, so it can be translated.
+ */
+export const INTEGRATION_CATEGORIES = [
+  "productivity",
+  "communication",
+  "meetings",
+  "sales",
+  "marketing",
+  "finance",
+  "commerce",
+  "engineering",
+  "knowledge",
+  "recruiting",
+] as const;
+
+export type IntegrationCategory = (typeof INTEGRATION_CATEGORIES)[number];
+
+const INTEGRATION_CATEGORY_SET: ReadonlySet<string> = new Set(
+  INTEGRATION_CATEGORIES,
+);
+
+/**
+ * Whether `value` names a category this build knows. A client reading a newer
+ * catalog treats an unknown slug as uncategorized rather than failing.
+ */
+export function isIntegrationCategory(
+  value: unknown,
+): value is IntegrationCategory {
+  return typeof value === "string" && INTEGRATION_CATEGORY_SET.has(value);
+}

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

@@ -43,6 +43,26 @@ export type GatewayLogsTailRouteParams = z.infer<
   typeof GatewayLogsTailRouteParamsSchema
 >;
 
+/**
+ * `gateway_debug_export`: a consistent copy of the gateway database plus its
+ * recent log files, as one gzipped tar, for a debug bundle. No params.
+ */
+export const GatewayDebugExportIpcParamsSchema = z
+  .object({})
+  .strict()
+  .default({});
+
+export const GatewayDebugExportIpcResponseSchema = z.object({
+  ok: z.literal(true),
+  /** `tar.gz` bytes, base64. Contains gateway.sqlite and gateway-logs/. */
+  archive_base64: z.string(),
+  size_bytes: z.number().int().nonnegative(),
+});
+
+export type GatewayDebugExportIpcResponse = z.infer<
+  typeof GatewayDebugExportIpcResponseSchema
+>;
+
 export const GatewayLogsTailIpcResponseSchema = z.object({
   lines: z.array(z.record(z.string(), z.unknown())),
   truncated: z.boolean(),

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

@@ -24,13 +24,15 @@ export {
   PersistentIpcClient,
 } from "./ipc-client.js";
 
-// Outbound delivery contract (daemon → gateway) — Zod schemas + derived types
+// Outbound delivery contract: Zod schemas + derived types
 export {
   ApprovalActionOptionSchema,
   ApprovalUIMetadataSchema,
   AttachmentMetadataSchema,
   ChannelDeliveryResultSchema,
   ChannelReplyPayloadSchema,
+  DELIVER_GATEWAY_REPLY_IPC_METHOD,
+  GatewayReplyRequestSchema,
   MessageAudienceSchema,
   PermissionRequestDetailsSchema,
   StreamOpSchema,
@@ -45,6 +47,7 @@ export type {
   AttachmentMetadata,
   ChannelDeliveryResult,
   ChannelReplyPayload,
+  GatewayReplyRequest,
   MessageAudience,
   PermissionRequestDetails,
   StreamOp,

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

@@ -1,13 +1,17 @@
 /**
- * Daemon → gateway outbound delivery contract.
+ * Outbound channel 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.
+ * Zod schemas for a reply to a channel chat. The daemon constructs these
+ * payloads in `deliverChannelReply()` and `deliverApprovalPrompt()` and hands
+ * them to the channel transport its callback URL names
+ * (`messaging/providers`). `/deliver/{channel}` is only that callback URL's
+ * addressing form: no service serves it. A callback URL no
+ * transport owns (a managed callback carrying a `callback_token`) is POSTed
+ * over HTTP by `http-delivery.ts` instead.
  *
- * The daemon constructs these payloads in `deliverChannelReply()` and
- * `deliverApprovalPrompt()`; the gateway validates and dispatches them
- * to the target channel provider.
+ * The gateway sends through the same transports, never to a provider itself:
+ * a reply it composes for a message it answered at ingress goes to the daemon
+ * as a {@link GatewayReplyRequest}.
  */
 
 import type { KnownBlock } from "@slack/types";
@@ -279,6 +283,33 @@ export const ChannelReplyPayloadSchema = z.object({
 
 export type ChannelReplyPayload = z.infer<typeof ChannelReplyPayloadSchema>;
 
+// ---------------------------------------------------------------------------
+// Gateway reply: gateway to daemon
+// ---------------------------------------------------------------------------
+
+/**
+ * Daemon IPC method that delivers a {@link GatewayReplyRequest}. IPC-only:
+ * it has no HTTP route.
+ */
+export const DELIVER_GATEWAY_REPLY_IPC_METHOD = "deliver_gateway_reply";
+
+/**
+ * A text reply the gateway composed for an inbound message it answered
+ * itself (a verification code, an invite redemption), which the daemon
+ * delivers through the channel transport `callbackUrl` names. The callback
+ * URL is the one the inbound message carried, so the reply lands in the chat
+ * and thread the person wrote from.
+ */
+export const GatewayReplyRequestSchema = ChannelReplyPayloadSchema.pick({
+  chatId: true,
+  assistantId: true,
+}).extend({
+  callbackUrl: z.string().min(1),
+  text: z.string().min(1),
+});
+
+export type GatewayReplyRequest = z.infer<typeof GatewayReplyRequestSchema>;
+
 // ---------------------------------------------------------------------------
 // Channel delivery result — gateway response
 // ---------------------------------------------------------------------------

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

@@ -3,9 +3,8 @@
  *
  * The gateway resolves this verdict from its ACL DB and stamps it onto the
  * inbound payload's `sourceMetadata`; the runtime consumes it. Keeping the
- * type here avoids the runtime importing from `gateway/src` and lets the
- * daemon's `trustClass` union (`actor-trust-resolver.ts`) converge on this
- * one source of truth.
+ * type here avoids the runtime importing from `gateway/src`, and the daemon
+ * imports {@link TrustClass} from here rather than declaring its own.
  *
  * This contract carries ACL + identity keys + minimal labels only — never
  * info fields (notes, userFile, contactType). `status` / `policy` / `type`
@@ -19,9 +18,9 @@ import { z } from "zod";
 import { AdmissionPolicySchema } from "./admission-policy-contract.js";
 
 /**
- * Verification-purpose trust classification. Mirrors the daemon's
- * `TrustClass` union (`actor-trust-resolver.ts`), ordered most- to
- * least-trusted.
+ * Trust classification of an inbound actor, ordered most- to least-trusted.
+ * The one declaration of the vocabulary: the gateway classifies with it and
+ * the daemon derives capabilities from it.
  */
 export const TRUST_CLASS_VALUES = [
   "guardian",

package/node_modules/@vellumai/service-contracts/package.json

@@ -27,7 +27,8 @@
     "./reactions": "./src/reactions.ts",
     "./guardian-requests": "./src/guardian-requests.ts",
     "./platform-credential": "./src/platform-credential.ts",
-    "./plan-credit": "./src/plan-credit.ts"
+    "./plan-credit": "./src/plan-credit.ts",
+    "./integration-categories": "./src/integration-categories.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

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

@@ -29,6 +29,7 @@ export * from "./trust-rules.js";
 export * from "./ingress.js";
 export * from "./no-response.js";
 export * from "./plan-credit.js";
+export * from "./integration-categories.js";
 export * from "./platform-credential.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";

package/node_modules/@vellumai/service-contracts/src/integration-categories.ts

@@ -0,0 +1,36 @@
+/**
+ * Category vocabulary for the integrations catalog, shared by the assistant
+ * daemon (which stamps it on OAuth providers and marketplace MCP entries) and
+ * the clients (which draw the category filter from it).
+ *
+ * The order here is the order clients show the categories in. The slug is the
+ * wire value; the user-facing label is the client's, so it can be translated.
+ */
+export const INTEGRATION_CATEGORIES = [
+  "productivity",
+  "communication",
+  "meetings",
+  "sales",
+  "marketing",
+  "finance",
+  "commerce",
+  "engineering",
+  "knowledge",
+  "recruiting",
+] as const;
+
+export type IntegrationCategory = (typeof INTEGRATION_CATEGORIES)[number];
+
+const INTEGRATION_CATEGORY_SET: ReadonlySet<string> = new Set(
+  INTEGRATION_CATEGORIES,
+);
+
+/**
+ * Whether `value` names a category this build knows. A client reading a newer
+ * catalog treats an unknown slug as uncategorized rather than failing.
+ */
+export function isIntegrationCategory(
+  value: unknown,
+): value is IntegrationCategory {
+  return typeof value === "string" && INTEGRATION_CATEGORY_SET.has(value);
+}

package/node_modules/@vellumai/slack-text/src/index.ts

@@ -127,7 +127,7 @@ export async function buildSlackUserLabelMap(
     ids.map(async (id): Promise<[string, string] | undefined> => {
       try {
         const label = await resolveLabel(id);
-        const sanitized = sanitizeOptionalLabel(label ?? undefined);
+        const sanitized = sanitizeSlackLabel(label ?? undefined);
         if (!sanitized || sanitized === id) return undefined;
         return [id, sanitized];
       } catch {
@@ -166,7 +166,7 @@ export async function buildSlackChannelLabelMap(
     ids.map(async (id): Promise<[string, string] | undefined> => {
       try {
         const label = await resolveLabel(id);
-        const sanitized = sanitizeOptionalLabel(label ?? undefined);
+        const sanitized = sanitizeSlackLabel(label ?? undefined);
         if (!sanitized || sanitized === id) return undefined;
         return [id, sanitized];
       } catch {
@@ -222,7 +222,7 @@ function renderChannelReference(
     return `#${embeddedLabel}`;
   }
 
-  const resolvedLabel = sanitizeOptionalLabel(
+  const resolvedLabel = sanitizeSlackLabel(
     options.channelLabels?.[channelId],
   );
   if (resolvedLabel && resolvedLabel !== channelId) {
@@ -320,15 +320,11 @@ export function sanitizeSlackLabel(
 function sanitizeEmbeddedSlackLabel(
   label: string | undefined,
 ): string | undefined {
-  return sanitizeOptionalLabel(
+  return sanitizeSlackLabel(
     label === undefined ? undefined : decodeSlackHtmlEntities(label),
   );
 }
 
-function sanitizeOptionalLabel(label: string | undefined): string | undefined {
-  return sanitizeSlackLabel(label);
-}
-
 function isSlackUserId(value: string): boolean {
   return /^[UW][A-Z0-9]+$/.test(value);
 }