@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022248.91fa053

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

@@ -0,0 +1,216 @@
+/**
+ * Shared invite contracts for the gateway-native invite lifecycle.
+ *
+ * Hash + generation helpers live here so gateway-computed hashes match
+ * assistant-minted (and backfilled) hashes byte-for-byte — hash compatibility
+ * with rows already stored in both DBs is load-bearing, so do not change the
+ * scheme. The channel-gating allowlist and the redemption-outcome / invite
+ * IPC schemas are shared so gateway and daemon converge on one source of
+ * truth instead of drifting copies.
+ */
+
+import { createHash, randomBytes, randomInt } from "node:crypto";
+
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Hash + generation helpers
+// ---------------------------------------------------------------------------
+
+function sha256Hex(input: string): string {
+  return createHash("sha256").update(input).digest("hex");
+}
+
+/**
+ * SHA-256 hash an invite token for storage comparison. Must remain stable:
+ * stored invite rows hold hashes produced by this function.
+ */
+export function hashInviteToken(rawToken: string): string {
+  return sha256Hex(rawToken);
+}
+
+/**
+ * SHA-256 hash a numeric invite/voice code for storage comparison. Must
+ * remain stable: stored invite rows hold hashes produced by this function.
+ */
+export function hashInviteCode(code: string): string {
+  return sha256Hex(code);
+}
+
+/**
+ * Generate a raw invite token: 32 bytes = 256 bits of entropy,
+ * base64url-encoded to a 43-character URL-safe string.
+ */
+export function generateInviteToken(): string {
+  return randomBytes(32).toString("base64url");
+}
+
+/**
+ * Basic E.164 phone number validation: starts with +, followed by 10-15
+ * digits. Gates `expectedExternalUserId` on voice invites so the identity
+ * binding is a real dialable number.
+ */
+export function isValidE164(phone: string): boolean {
+  return /^\+\d{10,15}$/.test(phone);
+}
+
+/**
+ * Generate a cryptographically random numeric code of the given length.
+ * Uses node:crypto randomInt for uniform distribution.
+ */
+export function generateInviteCode(digits: number = 6): string {
+  if (digits < 4 || digits > 10) {
+    throw new Error(
+      `Voice code digit count must be between 4 and 10, got ${digits}`,
+    );
+  }
+  const min = Math.pow(10, digits - 1); // e.g. 100000 for 6 digits
+  const max = Math.pow(10, digits); // e.g. 1000000 for 6 digits
+  return String(randomInt(min, max));
+}
+
+// ---------------------------------------------------------------------------
+// Channel gating
+// ---------------------------------------------------------------------------
+
+/**
+ * Channels where inbound invite-code redemption is supported. Mirrors the
+ * `invite.codeRedemptionEnabled` flags in the assistant's channel policy
+ * registry (`assistant/src/channels/config.ts`), which delegates here so
+ * gateway and daemon share one allowlist.
+ */
+export const INVITE_CODE_REDEMPTION_CHANNELS: ReadonlySet<string> = new Set([
+  "telegram",
+  "whatsapp",
+  "slack",
+  "email",
+]);
+
+/** Whether invite code redemption is enabled for the given channel. */
+export function isInviteCodeRedemptionEnabled(channelType: string): boolean {
+  return INVITE_CODE_REDEMPTION_CHANNELS.has(channelType);
+}
+
+// ---------------------------------------------------------------------------
+// Redemption outcome
+// ---------------------------------------------------------------------------
+
+const INVITE_REDEMPTION_RESULT_VALUES = ["redeemed", "already_member"] as const;
+
+export type InviteRedemptionResult =
+  (typeof INVITE_REDEMPTION_RESULT_VALUES)[number];
+
+/**
+ * Result of a successful invite redemption resolved by the gateway. Carries
+ * the identity fields the daemon needs to mirror the activation locally
+ * (`already_member` = the sender was already an active member, so no invite
+ * use was consumed). Also the payload of the best-effort daemon IPC
+ * `invite_redeemed` info-mirror event, verbatim.
+ */
+export const InviteRedemptionOutcomeSchema = z.object({
+  inviteId: z.string(),
+  contactId: z.string(),
+  sourceChannel: z.string(),
+  memberExternalUserId: z.string(),
+  memberExternalChatId: z.string().optional(),
+  displayName: z.string().optional(),
+  username: z.string().optional(),
+  // Opaque passthrough — the gateway stores but never interprets it.
+  sourceConversationId: z.string().optional(),
+  result: z.enum(INVITE_REDEMPTION_RESULT_VALUES),
+});
+
+export type InviteRedemptionOutcome = z.infer<
+  typeof InviteRedemptionOutcomeSchema
+>;
+
+// ---------------------------------------------------------------------------
+// IPC schemas
+// ---------------------------------------------------------------------------
+//
+// The schemas below define the gateway-native invite redemption IPC surface.
+// Schema-to-method mapping:
+//
+// - `RedeemInviteByCodeRequestSchema` / `RedeemInviteByTokenRequestSchema` —
+//   request shapes for the gateway redemption engine (code and link-token
+//   redemption).
+// - `RedeemVoiceInviteRequestSchema` — gateway IPC `redeem_voice_invite`.
+// - `GetActiveVoiceInviteRequestSchema` — gateway IPC
+//   `get_active_voice_invite`.
+//
+// Wire dispatch for `invites_redeem` (gateway IPC + HTTP redeem): the presence
+// of `code` selects voice redemption (validated by
+// `RedeemVoiceInviteRequestSchema`); otherwise the body is a link-token
+// redemption (validated by `RedeemInviteByTokenRequestSchema`).
+
+/**
+ * Gateway redemption-engine request for code redemption (6-digit code).
+ * Not an `invites_redeem` wire shape: bare-code redemption only happens via
+ * the gateway inbound intercept, which supplies the sender identity itself.
+ */
+export const RedeemInviteByCodeRequestSchema = z.object({
+  code: z.string().min(1),
+  sourceChannel: z.string().trim().min(1),
+  externalUserId: z.string().optional(),
+  externalChatId: z.string().optional(),
+  displayName: z.string().optional(),
+  username: z.string().optional(),
+});
+
+export type RedeemInviteByCodeRequest = z.infer<
+  typeof RedeemInviteByCodeRequestSchema
+>;
+
+/**
+ * Gateway redemption-engine request for token redemption. `token` is the raw
+ * link token as sent on the `invites_redeem` wire by the CLI and the daemon
+ * relay.
+ */
+export const RedeemInviteByTokenRequestSchema = z.object({
+  token: z.string().min(1),
+  sourceChannel: z.string().trim().min(1),
+  externalUserId: z.string().optional(),
+  externalChatId: z.string().optional(),
+  displayName: z.string().optional(),
+  username: z.string().optional(),
+});
+
+export type RedeemInviteByTokenRequest = z.infer<
+  typeof RedeemInviteByTokenRequestSchema
+>;
+
+/**
+ * Request for gateway IPC `redeem_voice_invite` (voice-channel spoken code).
+ * Also the `invites_redeem` voice wire shape, selected by the presence of
+ * `code`.
+ */
+export const RedeemVoiceInviteRequestSchema = z.object({
+  callerExternalUserId: z.string().min(1),
+  code: z.string().min(1),
+});
+
+export type RedeemVoiceInviteRequest = z.infer<
+  typeof RedeemVoiceInviteRequestSchema
+>;
+
+/** Request for gateway IPC `get_active_voice_invite`. */
+export const GetActiveVoiceInviteRequestSchema = z.object({
+  callerExternalUserId: z.string().min(1),
+});
+
+export type GetActiveVoiceInviteRequest = z.infer<
+  typeof GetActiveVoiceInviteRequestSchema
+>;
+
+/**
+ * Active voice invite awaiting the expected caller — display metadata for
+ * the personalized voice prompt; never carries the code or its hash.
+ */
+export const ActiveVoiceInviteSchema = z.object({
+  inviteId: z.string(),
+  inviteeName: z.string().nullable(),
+  guardianName: z.string().nullable(),
+  codeDigits: z.number().int(),
+});
+
+export type ActiveVoiceInvite = z.infer<typeof ActiveVoiceInviteSchema>;

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

@@ -37,6 +37,10 @@ export type AttachmentMetadata = z.infer<typeof AttachmentMetadataSchema>;
 export const ApprovalActionOptionSchema = z.object({
   id: z.string(),
   label: z.string(),
+  // Surface-agnostic button weight. Renderers translate it to their platform
+  // token (Slack primary/danger, Surface primary/destructive); absent means
+  // the renderer applies its own default styling.
+  emphasis: z.enum(["primary", "secondary", "destructive"]).optional(),
 });
 
 export type ApprovalActionOption = z.infer<typeof ApprovalActionOptionSchema>;
@@ -61,6 +65,91 @@ export const ApprovalUIMetadataSchema = z.object({
 
 export type ApprovalUIMetadata = z.infer<typeof ApprovalUIMetadataSchema>;
 
+// ---------------------------------------------------------------------------
+// Slack streaming operations
+// ---------------------------------------------------------------------------
+
+/**
+ * One task card in a Slack streamed plan. Mirrors the `task_update` chunk of
+ * the Slack streaming API: an ordered, status-bearing step the assistant is
+ * working through. `title` is capped at 256 characters by Slack.
+ *
+ * @see https://docs.slack.dev/reference/methods/chat.appendStream/
+ */
+export const SlackStreamTaskSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  status: z.enum(["pending", "in_progress", "complete", "error"]),
+  details: z.string().optional(),
+  output: z.string().optional(),
+});
+
+export type SlackStreamTask = z.infer<typeof SlackStreamTaskSchema>;
+
+/**
+ * A single Slack streaming operation, mapping directly onto the
+ * `chat.startStream` / `chat.appendStream` / `chat.stopStream` Web API methods.
+ *
+ * `start` opens a streamed reply on a thread and returns the stream `ts`;
+ * `append` adds markdown (and optional task cards) to that stream; `stop`
+ * finalizes it, optionally rendering rich Block Kit blocks below the streamed
+ * body. Blocks are only accepted on `stop` — during the stream, Slack renders
+ * the `markdownText` natively.
+ *
+ * @see https://docs.slack.dev/reference/methods/chat.startStream/
+ * @see https://docs.slack.dev/reference/methods/chat.appendStream/
+ * @see https://docs.slack.dev/reference/methods/chat.stopStream/
+ */
+export const SlackStreamOpSchema = z
+  .discriminatedUnion("action", [
+    z.object({
+      action: z.literal("start"),
+      threadTs: z.string(),
+      markdownText: z.string().optional(),
+      taskDisplayMode: z.literal("plan").optional(),
+      tasks: z.array(SlackStreamTaskSchema).optional(),
+      /**
+       * Slack user ID of the reader the stream targets. Required by
+       * `chat.startStream` when streaming into a channel; omitted for DMs.
+       */
+      recipientUserId: z.string().optional(),
+      /**
+       * Slack team ID the recipient belongs to. Required alongside
+       * `recipientUserId` when streaming into a channel; omitted for DMs.
+       */
+      recipientTeamId: z.string().optional(),
+    }),
+    z.object({
+      action: z.literal("append"),
+      streamTs: z.string(),
+      markdownText: z.string().optional(),
+      tasks: z.array(SlackStreamTaskSchema).optional(),
+    }),
+    z.object({
+      action: z.literal("stop"),
+      streamTs: z.string(),
+      markdownText: z.string().optional(),
+      blocks: z.array(z.custom<KnownBlock>()).optional(),
+      tasks: z.array(SlackStreamTaskSchema).optional(),
+    }),
+  ])
+  .superRefine((op, ctx) => {
+    // Slack requires either `markdown_text` or `chunks` on `start`/`append`; a
+    // task-only operation advances the plan block without new body text.
+    if (
+      (op.action === "start" || op.action === "append") &&
+      op.markdownText === undefined &&
+      op.tasks === undefined
+    ) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `${op.action} requires markdownText or tasks`,
+      });
+    }
+  });
+
+export type SlackStreamOp = z.infer<typeof SlackStreamOpSchema>;
+
 // ---------------------------------------------------------------------------
 // Channel reply payload — the full outbound wire format
 // ---------------------------------------------------------------------------
@@ -103,6 +192,8 @@ export const ChannelReplyPayloadSchema = z.object({
       loadingMessages: z.array(z.string()).optional(),
     })
     .optional(),
+  /** When provided, perform one Slack streaming operation (start/append/stop). */
+  slackStream: SlackStreamOpSchema.optional(),
 });
 
 export type ChannelReplyPayload = z.infer<typeof ChannelReplyPayloadSchema>;

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

@@ -32,6 +32,18 @@ export const TrustClassSchema = z.enum(TRUST_CLASS_VALUES);
 
 export type TrustClass = (typeof TRUST_CLASS_VALUES)[number];
 
+const TRUST_CLASS_SET: ReadonlySet<string> = new Set(TRUST_CLASS_VALUES);
+
+/**
+ * Type guard for wire-sourced trust classes. Consumers receive verdicts over
+ * IPC/HTTP, so a field statically typed {@link TrustClass} can still carry an
+ * out-of-contract value (version skew, malformed payload); this narrows it
+ * safely without casting.
+ */
+export function isTrustClass(value: string): value is TrustClass {
+  return TRUST_CLASS_SET.has(value);
+}
+
 /**
  * Per-actor trust verdict resolved by the gateway from its ACL DB. ACL +
  * identity keys + minimal labels only. Guardian binding and member
@@ -42,9 +54,10 @@ export const TrustVerdictSchema = z.object({
   trustClass: TrustClassSchema,
   canonicalSenderId: z.string().nullable(),
 
-  // Present+true ⇒ gateway attempted resolution but failed (DB error);
-  // consumer treats it as "could not vouch", distinct from a real `unknown`
-  // stranger.
+  // Present+true ⇒ gateway attempted resolution but could not produce a
+  // usable verdict (DB error, or a sender who maps to the guardian contact
+  // whose principal is unresolved); consumer treats it as "could not vouch",
+  // distinct from a real `unknown` stranger.
   resolutionFailed: z.boolean().optional(),
 
   // Guardian binding — present only when a guardian binding matches.
@@ -64,6 +77,12 @@ export const TrustVerdictSchema = z.object({
   verifiedAt: z.number().nullable().optional(),
   verifiedVia: z.string().nullable().optional(),
   memberDisplayName: z.string().optional(),
+
+  // Gateway-owned interaction telemetry (a trust signal, not an info field per
+  // the 2×2) — carried straight off the member `contact_channels` row.
+  // Present only when a member channel resolves; absent for unknown senders.
+  interactionCount: z.number().optional(),
+  lastInteraction: z.number().nullable().optional(),
 });
 
 export type TrustVerdict = z.infer<typeof TrustVerdictSchema>;
@@ -80,6 +99,23 @@ export function makeResolutionFailedVerdict(
   return { trustClass: "unknown", canonicalSenderId, resolutionFailed: true };
 }
 
+/**
+ * Downgraded verdict for an inbound sender whose channel identity could not be
+ * authenticated — e.g. an email whose `From:` failed SPF/DKIM/DMARC and so
+ * carries a spoofable address. A spoofable sender must never inherit
+ * guardian/trusted_contact trust from a matching address, so it is reduced to
+ * a plain `unknown` stranger: guardian and member/ACL fields are dropped so no
+ * residual trust is reconstructed downstream. Unlike
+ * {@link makeResolutionFailedVerdict} this is NOT `resolutionFailed` — the
+ * sender is a real stranger and should flow through the normal admission floor
+ * + verification lane, not the could-not-vouch soft-deny.
+ */
+export function makeUnauthenticatedSenderVerdict(
+  canonicalSenderId: string | null,
+): TrustVerdict {
+  return { trustClass: "unknown", canonicalSenderId };
+}
+
 /**
  * IPC request for `resolve_inbound_trust`. Per-actor identity keys the
  * gateway resolver needs to classify the inbound sender. The response reuses

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

@@ -5,10 +5,8 @@ import {
   normalizePublicBaseUrl,
 } from "../ingress.js";
 import {
-  buildTwilioConnectActionUrl,
   buildTwilioMediaStreamUrl,
   buildTwilioPhoneNumberWebhookUrls,
-  buildTwilioRelayUrl,
   buildTwilioVoiceWebhookUrl,
   resolveTwilioPublicBaseUrl,
 } from "../twilio-ingress.js";
@@ -90,12 +88,6 @@ describe("Twilio ingress helpers", () => {
     expect(buildTwilioVoiceWebhookUrl("https://example.test", "call-123")).toBe(
       "https://example.test/webhooks/twilio/voice?callSessionId=call-123",
     );
-    expect(buildTwilioConnectActionUrl("https://example.test")).toBe(
-      "https://example.test/webhooks/twilio/connect-action",
-    );
-    expect(buildTwilioRelayUrl("https://example.test")).toBe(
-      "wss://example.test/webhooks/twilio/relay",
-    );
     expect(buildTwilioMediaStreamUrl("http://example.test")).toBe(
       "ws://example.test/webhooks/twilio/media-stream",
     );

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

@@ -5,8 +5,7 @@
  * 1. Does NOT import from assistant, gateway, credential-executor, or other
  *    service runtime modules.
  * 2. Does NOT import from runtime shared packages that sit above it in the
- *    dependency hierarchy (@vellumai/credential-storage, @vellumai/egress-proxy,
- *    @vellumai/skill-host-contracts).
+ *    dependency hierarchy (@vellumai/credential-storage, @vellumai/egress-proxy).
  * 3. Does NOT import from x-client packages (@vellumai/assistant-client,
  *    @vellumai/ces-client, @vellumai/gateway-client).
  * 4. Remains a pure schema/type package — no runtime dependencies beyond zod.
@@ -73,8 +72,6 @@ const FORBIDDEN_IMPORT_PATTERNS = [
   /require\s*\(\s*["']@vellumai\/credential-storage(?:\/|["'])/,
   /from\s+["']@vellumai\/egress-proxy(?:\/|["'])/,
   /require\s*\(\s*["']@vellumai\/egress-proxy(?:\/|["'])/,
-  /from\s+["']@vellumai\/skill-host-contracts(?:\/|["'])/,
-  /require\s*\(\s*["']@vellumai\/skill-host-contracts(?:\/|["'])/,
 
   // x-client packages (higher layer)
   /from\s+["']@vellumai\/assistant-client(?:\/|["'])/,
@@ -143,7 +140,6 @@ describe("package boundary", () => {
         "@vellumai/assistant",
         "@vellumai/credential-storage",
         "@vellumai/egress-proxy",
-        "@vellumai/skill-host-contracts",
         "@vellumai/assistant-client",
         "@vellumai/ces-client",
         "@vellumai/gateway-client",

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

@@ -2,9 +2,6 @@ import { normalizePublicBaseUrl } from "./ingress.js";
 
 export const TWILIO_VOICE_WEBHOOK_PATH = "/webhooks/twilio/voice";
 export const TWILIO_STATUS_WEBHOOK_PATH = "/webhooks/twilio/status";
-export const TWILIO_CONNECT_ACTION_WEBHOOK_PATH =
-  "/webhooks/twilio/connect-action";
-export const TWILIO_RELAY_WEBHOOK_PATH = "/webhooks/twilio/relay";
 export const TWILIO_MEDIA_STREAM_WEBHOOK_PATH = "/webhooks/twilio/media-stream";
 
 /**
@@ -13,9 +10,9 @@ export const TWILIO_MEDIA_STREAM_WEBHOOK_PATH = "/webhooks/twilio/media-stream";
  * with the actual public URL (from Velay registration, config, or the
  * `X-Vellum-Ingress-URL` header) before returning TwiML to Twilio.
  *
- * The placeholder uses `https://` so that `buildTwilioRelayUrl` /
- * `buildTwilioMediaStreamUrl` can apply the standard `http→ws` scheme
- * conversion, producing `wss://__VELLUM_PUBLIC_BASE_URL__/…` in the output.
+ * The placeholder uses `https://` so that `buildTwilioMediaStreamUrl` can
+ * apply the standard `http→ws` scheme conversion, producing
+ * `wss://__VELLUM_PUBLIC_BASE_URL__/…` in the output.
  */
 export const TWILIO_PUBLIC_BASE_URL_PLACEHOLDER =
   "https://__VELLUM_PUBLIC_BASE_URL__";
@@ -58,14 +55,6 @@ export function buildTwilioStatusWebhookUrl(baseUrl: string): string {
   return `${baseUrl}${TWILIO_STATUS_WEBHOOK_PATH}`;
 }
 
-export function buildTwilioConnectActionUrl(baseUrl: string): string {
-  return `${baseUrl}${TWILIO_CONNECT_ACTION_WEBHOOK_PATH}`;
-}
-
-export function buildTwilioRelayUrl(baseUrl: string): string {
-  return `${toTwilioWebSocketBaseUrl(baseUrl)}${TWILIO_RELAY_WEBHOOK_PATH}`;
-}
-
 export function buildTwilioMediaStreamUrl(baseUrl: string): string {
   return `${toTwilioWebSocketBaseUrl(baseUrl)}${TWILIO_MEDIA_STREAM_WEBHOOK_PATH}`;
 }