@vellumai/assistant 0.5.10 → 0.5.12

package/src/runtime/routes/inbound-message-handler.ts

@@ -13,6 +13,7 @@ import {
 } from "../../channels/types.js";
 import { touchContactInteraction } from "../../contacts/contacts-write.js";
 import type { TrustContext } from "../../daemon/conversation-runtime-assembly.js";
+import type { HeartbeatService } from "../../heartbeat/heartbeat-service.js";
 import * as attachmentsStore from "../../memory/attachments-store.js";
 import {
   recordConversationSeenSignal,
@@ -20,6 +21,7 @@ import {
 } from "../../memory/conversation-attention-store.js";
 import * as deliveryChannels from "../../memory/delivery-channels.js";
 import * as deliveryCrud from "../../memory/delivery-crud.js";
+import * as deliveryStatus from "../../memory/delivery-status.js";
 import * as externalConversationStore from "../../memory/external-conversation-store.js";
 import { canonicalizeInboundIdentity } from "../../util/canonicalize-identity.js";
 import { getLogger } from "../../util/logger.js";
@@ -57,6 +59,7 @@ export async function handleChannelInbound(
   approvalConversationGenerator?: ApprovalConversationGenerator,
   _guardianActionCopyGenerator?: GuardianActionCopyGenerator,
   _guardianFollowUpConversationGenerator?: GuardianFollowUpConversationGenerator,
+  heartbeatService?: HeartbeatService,
 ): Promise<Response> {
   // Gateway-origin proof is enforced by route-policy middleware (svc_gateway
   // principal type required) before this handler runs. The exchange JWT
@@ -641,7 +644,7 @@ export async function handleChannelInbound(
   // For new (non-duplicate) messages, run the secret ingress check
   // synchronously, then fire off the agent loop in the background.
   if (!result.duplicate && processMessage) {
-    runSecretIngressCheck({
+    const ingressResult = runSecretIngressCheck({
       eventId: result.eventId,
       sourceChannel,
       conversationExternalId,
@@ -659,30 +662,48 @@ export async function handleChannelInbound(
       canonicalAssistantId,
     });
 
-    // Fire-and-forget: process the message and deliver the reply in the background.
-    // The HTTP response returns immediately so the gateway webhook is not blocked.
-    // The onEvent callback in processMessage registers pending interactions, and
-    // approval interception (above) handles decisions via the pending-interactions tracker.
-    processChannelMessageInBackground({
-      processMessage,
-      conversationId: result.conversationId,
-      eventId: result.eventId,
-      content: trimmedContent,
-      attachmentIds: hasAttachments ? attachmentIds : undefined,
-      sourceChannel,
-      sourceInterface,
-      externalChatId: conversationExternalId,
-      trustCtx,
-      metadataHints,
-      metadataUxBrief,
-      commandIntent,
-      sourceLanguageCode,
-      replyCallbackUrl,
-      mintBearerToken,
-      assistantId: canonicalAssistantId,
-      approvalCopyGenerator,
-      chatType: sourceChatType,
-    });
+    if (ingressResult.blocked) {
+      // Intentional block — mark the event as processed (not failed/dead-lettered).
+      deliveryStatus.markProcessed(result.eventId);
+      log.info(
+        {
+          eventId: result.eventId,
+          detectedTypes: ingressResult.detectedTypes,
+        },
+        "Channel message blocked at ingress: contains secrets",
+      );
+    } else {
+      // Guardian messages reset the heartbeat timer so the next heartbeat
+      // fires a full interval after this interaction.
+      if (trustCtx.trustClass === "guardian") {
+        heartbeatService?.resetTimer();
+      }
+
+      // Fire-and-forget: process the message and deliver the reply in the background.
+      // The HTTP response returns immediately so the gateway webhook is not blocked.
+      // The onEvent callback in processMessage registers pending interactions, and
+      // approval interception (above) handles decisions via the pending-interactions tracker.
+      processChannelMessageInBackground({
+        processMessage,
+        conversationId: result.conversationId,
+        eventId: result.eventId,
+        content: trimmedContent,
+        attachmentIds: hasAttachments ? attachmentIds : undefined,
+        sourceChannel,
+        sourceInterface,
+        externalChatId: conversationExternalId,
+        trustCtx,
+        metadataHints,
+        metadataUxBrief,
+        commandIntent,
+        sourceLanguageCode,
+        replyCallbackUrl,
+        mintBearerToken,
+        assistantId: canonicalAssistantId,
+        approvalCopyGenerator,
+        chatType: sourceChatType,
+      });
+    }
   }
 
   return Response.json({

package/src/runtime/routes/inbound-stages/acl-enforcement.ts

@@ -447,10 +447,11 @@ export async function enforceIngressAcl(
           );
         }
 
+        const replyText = guardianNotified
+          ? `Hmm looks like you don't have access to talk to me. I'll let ${resolveGuardianLabel(sourceChannel, canonicalAssistantId)} know you tried talking to me and get back to you.`
+          : "Sorry, you haven't been approved to message this assistant.";
+        let replyDelivered = false;
         if (replyCallbackUrl) {
-          const replyText = guardianNotified
-            ? `Hmm looks like you don't have access to talk to me. I'll let ${resolveGuardianLabel(sourceChannel, canonicalAssistantId)} know you tried talking to me and get back to you.`
-            : "Sorry, you haven't been approved to message this assistant.";
           const replyPayload: Parameters<typeof deliverChannelReply>[1] = {
             chatId: conversationExternalId,
             text: replyText,
@@ -467,6 +468,7 @@ export async function enforceIngressAcl(
               replyPayload,
               mintBearerToken(),
             );
+            replyDelivered = true;
           } catch (err) {
             log.error(
               { err, conversationExternalId },
@@ -481,6 +483,9 @@ export async function enforceIngressAcl(
             accepted: true,
             denied: true,
             reason: "not_a_member",
+            // Include reply text so the gateway can deliver directly when
+            // callback delivery failed (e.g. signing-key mismatch → 401).
+            ...(!replyDelivered && { replyText }),
           }),
           guardianVerifyCode,
         };
@@ -714,15 +719,16 @@ export async function enforceIngressAcl(
             }
           }
 
+          const inactiveReplyText = guardianNotified
+            ? `Hmm looks like you don't have access to talk to me. I'll let ${resolveGuardianLabel(sourceChannel, canonicalAssistantId)} know you tried talking to me and get back to you.`
+            : "Sorry, you haven't been approved to message this assistant.";
+          let inactiveReplyDelivered = false;
           if (replyCallbackUrl) {
-            const replyText = guardianNotified
-              ? `Hmm looks like you don't have access to talk to me. I'll let ${resolveGuardianLabel(sourceChannel, canonicalAssistantId)} know you tried talking to me and get back to you.`
-              : "Sorry, you haven't been approved to message this assistant.";
             const inactiveReplyPayload: Parameters<
               typeof deliverChannelReply
             >[1] = {
               chatId: conversationExternalId,
-              text: replyText,
+              text: inactiveReplyText,
               assistantId,
             };
             // On Slack, send as ephemeral so only the requester sees the rejection
@@ -739,6 +745,7 @@ export async function enforceIngressAcl(
                 inactiveReplyPayload,
                 mintBearerToken(),
               );
+              inactiveReplyDelivered = true;
             } catch (err) {
               log.error(
                 { err, conversationExternalId },
@@ -752,6 +759,7 @@ export async function enforceIngressAcl(
               accepted: true,
               denied: true,
               reason: `member_${channelStatusToMemberStatus(resolvedMember.channel.status)}`,
+              ...(!inactiveReplyDelivered && { replyText: inactiveReplyText }),
             }),
             guardianVerifyCode,
           };
@@ -763,10 +771,13 @@ export async function enforceIngressAcl(
           { sourceChannel, channelId: resolvedMember.channel.id },
           "Ingress ACL: member policy deny",
         );
+        const denyReplyText =
+          "Sorry, you haven't been approved to message this assistant.";
+        let denyReplyDelivered = false;
         if (replyCallbackUrl) {
           const denyPayload: Parameters<typeof deliverChannelReply>[1] = {
             chatId: conversationExternalId,
-            text: "Sorry, you haven't been approved to message this assistant.",
+            text: denyReplyText,
             assistantId,
           };
           if (sourceChannel === "slack" && (canonicalSenderId ?? rawSenderId)) {
@@ -779,6 +790,7 @@ export async function enforceIngressAcl(
               denyPayload,
               mintBearerToken(),
             );
+            denyReplyDelivered = true;
           } catch (err) {
             log.error(
               { err, conversationExternalId },
@@ -792,6 +804,7 @@ export async function enforceIngressAcl(
             accepted: true,
             denied: true,
             reason: "policy_deny",
+            ...(!denyReplyDelivered && { replyText: denyReplyText }),
           }),
           guardianVerifyCode,
         };

package/src/runtime/routes/inbound-stages/secret-ingress-check.ts

@@ -9,6 +9,7 @@ import type { ChannelId } from "../../../channels/types.js";
 import type { TrustContext } from "../../../daemon/conversation-runtime-assembly.js";
 import { recordConversationSeenSignal } from "../../../memory/conversation-attention-store.js";
 import * as deliveryCrud from "../../../memory/delivery-crud.js";
+import { checkIngressForSecrets } from "../../../security/secret-ingress.js";
 import { getLogger } from "../../../util/logger.js";
 
 const log = getLogger("runtime-http");
@@ -35,10 +36,21 @@ export interface SecretIngressCheckParams {
   canonicalAssistantId: string;
 }
 
+export interface SecretIngressCheckResult {
+  blocked: boolean;
+  detectedTypes?: string[];
+}
+
 /**
- * Persist the raw payload and record a Telegram seen signal.
+ * Persist the raw payload, scan for secrets, and record a Telegram seen signal.
+ *
+ * Returns `{ blocked: true, detectedTypes }` when the message contains
+ * known-format secrets — the caller should skip background dispatch and mark
+ * the event as processed (not failed/dead-lettered).
  */
-export function runSecretIngressCheck(params: SecretIngressCheckParams): void {
+export function runSecretIngressCheck(
+  params: SecretIngressCheckParams,
+): SecretIngressCheckResult {
   const {
     eventId,
     sourceChannel,
@@ -73,6 +85,20 @@ export function runSecretIngressCheck(params: SecretIngressCheckParams): void {
     assistantId: canonicalAssistantId,
   });
 
+  // ── Secret ingress scan ──
+  // Scan trimmedContent (post-transcription) so secrets introduced via
+  // transcribed audio are also caught.
+  const ingressResult = checkIngressForSecrets(trimmedContent);
+  if (ingressResult.blocked) {
+    // Clear stored payload to prevent secret-bearing content on disk.
+    deliveryCrud.clearPayload(eventId);
+    log.warn(
+      { eventId, detectedTypes: ingressResult.detectedTypes },
+      "Channel message blocked at ingress: secret detected",
+    );
+    return { blocked: true, detectedTypes: ingressResult.detectedTypes };
+  }
+
   // Record inferred seen signal for non-duplicate Telegram inbound messages
   if (sourceChannel === "telegram") {
     try {
@@ -99,4 +125,6 @@ export function runSecretIngressCheck(params: SecretIngressCheckParams): void {
       );
     }
   }
+
+  return { blocked: false };
 }

package/src/runtime/routes/inbound-stages/transcribe-audio.ts

@@ -15,8 +15,7 @@ import { getLogger } from "../../../util/logger.js";
 
 const log = getLogger("transcribe-audio");
 
-const VOICE_TRANSCRIPTION_FLAG_KEY =
-  "feature_flags.channel-voice-transcription.enabled" as const;
+const VOICE_TRANSCRIPTION_FLAG_KEY = "channel-voice-transcription" as const;
 
 /** Timeout for the entire transcription pipeline (all attachments). */
 const TRANSCRIPTION_TIMEOUT_MS = 30_000;

package/src/runtime/routes/integrations/slack/share.ts

@@ -28,7 +28,7 @@ const log = getLogger("slack-share");
  * Resolve the Slack bot token from the OAuth connection store.
  */
 async function resolveSlackToken(): Promise<string | undefined> {
-  const conn = getConnectionByProvider("integration:slack");
+  const conn = getConnectionByProvider("slack");
   return conn
     ? await getSecureKeyAsync(`oauth_connection/${conn.id}/access_token`)
     : undefined;

package/src/runtime/routes/integrations/twilio.ts

@@ -271,17 +271,22 @@ export async function handleProvisionTwilioNumber(
   }
 
   let body: { country?: string; areaCode?: string };
-  try {
-    body = (await req.json()) as typeof body;
-  } catch {
-    return Response.json(
-      {
-        success: false,
-        hasCredentials: await hasTwilioCredentials(),
-        error: "Invalid JSON in request body",
-      },
-      { status: 400 },
-    );
+  const provisionText = await req.text();
+  if (!provisionText.trim()) {
+    body = {};
+  } else {
+    try {
+      body = JSON.parse(provisionText) as typeof body;
+    } catch {
+      return Response.json(
+        {
+          success: false,
+          hasCredentials: await hasTwilioCredentials(),
+          error: "Invalid JSON in request body",
+        },
+        { status: 400 },
+      );
+    }
   }
   const { accountSid, authToken } = await getTwilioCredentials();
   const country = body.country ?? "US";
@@ -406,17 +411,22 @@ export async function handleReleaseTwilioNumber(
   }
 
   let body: { phoneNumber?: string };
-  try {
-    body = (await req.json()) as typeof body;
-  } catch {
-    return Response.json(
-      {
-        success: false,
-        hasCredentials: await hasTwilioCredentials(),
-        error: "Invalid JSON in request body",
-      },
-      { status: 400 },
-    );
+  const releaseText = await req.text();
+  if (!releaseText.trim()) {
+    body = {};
+  } else {
+    try {
+      body = JSON.parse(releaseText) as typeof body;
+    } catch {
+      return Response.json(
+        {
+          success: false,
+          hasCredentials: await hasTwilioCredentials(),
+          error: "Invalid JSON in request body",
+        },
+        { status: 400 },
+      );
+    }
   }
   const raw = loadRawConfig();
   const twilio = (raw?.twilio ?? {}) as Record<string, unknown>;

package/src/runtime/routes/invite-routes.ts

@@ -9,6 +9,8 @@
  *   POST   /v1/contacts/invites/:id/call  — trigger an outbound call for a phone invite
  */
 
+import { z } from "zod";
+
 import type { RouteDefinition } from "../http-router.js";
 import {
   createIngressInvite,
@@ -169,28 +171,109 @@ export function inviteRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "contacts/invites",
       method: "GET",
+      summary: "List invites",
+      description:
+        "Return all invites, optionally filtered by sourceChannel or status.",
+      tags: ["contacts"],
+      queryParams: [
+        {
+          name: "sourceChannel",
+          schema: { type: "string" },
+          description: "Filter by source channel",
+        },
+        {
+          name: "status",
+          schema: { type: "string" },
+          description: "Filter by invite status",
+        },
+      ],
+      responseBody: z.object({
+        ok: z.boolean(),
+        invites: z.array(z.unknown()).describe("Invite objects"),
+      }),
       handler: ({ url }) => handleListInvites(url),
     },
     {
       endpoint: "contacts/invites",
       method: "POST",
+      summary: "Create an invite",
+      description:
+        'Create a new invite. Supports voice invites when sourceChannel is "phone".',
+      tags: ["contacts"],
+      requestBody: z.object({
+        contactId: z.string().describe("Contact to invite"),
+        sourceChannel: z
+          .string()
+          .describe("Source channel (e.g. phone)")
+          .optional(),
+        note: z.string().describe("Optional note").optional(),
+        maxUses: z.number().describe("Max redemptions").optional(),
+        expiresInMs: z.number().describe("Expiry duration in ms").optional(),
+        contactName: z.string().describe("Contact display name").optional(),
+        expectedExternalUserId: z
+          .string()
+          .describe("Expected user ID (E.164 for phone)")
+          .optional(),
+        friendName: z
+          .string()
+          .describe("Friend name for the invite")
+          .optional(),
+        guardianName: z.string().describe("Guardian name").optional(),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+        invite: z.object({}).passthrough().describe("Created invite"),
+      }),
       handler: async ({ req }) => handleCreateInvite(req),
     },
     {
       endpoint: "contacts/invites/redeem",
       method: "POST",
+      summary: "Redeem an invite",
+      description: "Redeem an invite by token or voice code.",
+      tags: ["contacts"],
+      requestBody: z.object({
+        token: z.string().describe("Invite token (token-based redemption)"),
+        code: z.string().describe("Voice code (voice-code redemption)"),
+        callerExternalUserId: z
+          .string()
+          .describe("Caller E.164 phone (voice-code)"),
+        externalUserId: z.string().describe("External user ID (token-based)"),
+        externalChatId: z.string().describe("External chat ID (token-based)"),
+        sourceChannel: z.string().describe("Source channel (token-based)"),
+        assistantId: z.string().describe("Assistant ID (voice-code)"),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+        invite: z
+          .object({})
+          .passthrough()
+          .describe("Redeemed invite (token path)"),
+        type: z.string().describe("Redemption type (voice path)"),
+        memberId: z.string().describe("Member ID (voice path)"),
+      }),
       handler: async ({ req }) => handleRedeemInvite(req),
     },
     {
       endpoint: "contacts/invites/:id",
       method: "DELETE",
       policyKey: "contacts/invites",
+      summary: "Revoke an invite",
+      description: "Revoke an invite by ID.",
+      tags: ["contacts"],
       handler: ({ params }) => handleRevokeInvite(params.id),
     },
     {
       endpoint: "contacts/invites/:id/call",
       method: "POST",
       policyKey: "contacts/invites",
+      summary: "Trigger invite call",
+      description: "Trigger an outbound call for a phone invite.",
+      tags: ["contacts"],
+      responseBody: z.object({
+        ok: z.boolean(),
+        callSid: z.string().describe("Call SID from the provider"),
+      }),
       handler: async ({ params }) => handleTriggerInviteCall(params.id),
     },
   ];

package/src/runtime/routes/log-export-routes.ts

@@ -22,6 +22,7 @@ import { tmpdir } from "node:os";
 import { join, relative } from "node:path";
 
 import { and, desc, eq, gte, lte } from "drizzle-orm";
+import { z } from "zod";
 
 import { getDb } from "../../memory/db.js";
 import {
@@ -670,6 +671,19 @@ export function logExportRouteDefinitions(): RouteDefinition[] {
       endpoint: "export",
       method: "POST",
       policyKey: "export",
+      summary: "Export logs and audit data",
+      description:
+        "Export audit records, daemon logs, workspace contents, and config as a tar.gz archive.",
+      tags: ["export"],
+      requestBody: z.object({
+        auditLimit: z
+          .number()
+          .int()
+          .describe("Max audit records (default 1000)"),
+        conversationId: z.string().describe("Scope to a single conversation"),
+        startTime: z.number().describe("Lower bound epoch ms"),
+        endTime: z.number().describe("Upper bound epoch ms"),
+      }),
       handler: async ({ req }) => {
         const body = (await req.json()) as ExportRequestBody;
         return handleExport(body);

package/src/runtime/routes/memory-item-routes.ts

@@ -10,6 +10,7 @@
 
 import { and, asc, count, desc, eq, inArray, like, ne, or } from "drizzle-orm";
 import { v4 as uuid } from "uuid";
+import { z } from "zod";
 
 import { getConfig } from "../../config/loader.js";
 import { getDb } from "../../memory/db.js";
@@ -597,7 +598,11 @@ export async function handleUpdateMemoryItem(
   // If sourceType was set (either directly or via mapping), also write verificationState
   if (body.sourceType !== undefined && body.verificationState === undefined) {
     set.verificationState =
-      body.sourceType === "tool" ? "user_confirmed" : "assistant_inferred";
+      body.sourceType === "tool"
+        ? "user_confirmed"
+        : existing.verificationState === "user_reported"
+          ? "user_reported"
+          : "assistant_inferred";
   }
 
   // If subject, statement, or kind changed, recompute fingerprint
@@ -717,29 +722,122 @@ export function memoryItemRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "memory-items",
       method: "GET",
+      summary: "List memory items",
+      description:
+        "Return memory items with filtering, search, sorting, and pagination.",
+      tags: ["memory"],
+      queryParams: [
+        {
+          name: "kind",
+          schema: { type: "string" },
+          description: "Filter by kind",
+        },
+        {
+          name: "status",
+          schema: { type: "string" },
+          description: "Filter by status (default active)",
+        },
+        {
+          name: "search",
+          schema: { type: "string" },
+          description: "Full-text search query",
+        },
+        {
+          name: "sort",
+          schema: { type: "string" },
+          description: "Sort field (default lastSeenAt)",
+        },
+        {
+          name: "order",
+          schema: { type: "string" },
+          description: "asc or desc (default desc)",
+        },
+        {
+          name: "limit",
+          schema: { type: "integer" },
+          description: "Max results (default 100)",
+        },
+        {
+          name: "offset",
+          schema: { type: "integer" },
+          description: "Pagination offset",
+        },
+      ],
+      responseBody: z.object({
+        items: z.array(z.unknown()).describe("Memory item objects"),
+        total: z.number(),
+      }),
       handler: (ctx) => handleListMemoryItems(ctx.url),
     },
     {
       endpoint: "memory-items/:id",
       method: "GET",
       policyKey: "memory-items",
+      summary: "Get a memory item",
+      description:
+        "Return a single memory item by ID with supersession metadata.",
+      tags: ["memory"],
+      responseBody: z.object({
+        item: z
+          .object({})
+          .passthrough()
+          .describe("Memory item with scopeLabel and supersession info"),
+      }),
       handler: (ctx) => handleGetMemoryItem(ctx),
     },
     {
       endpoint: "memory-items",
       method: "POST",
+      summary: "Create a memory item",
+      description: "Create a new memory item and enqueue embedding.",
+      tags: ["memory"],
+      requestBody: z.object({
+        kind: z
+          .string()
+          .describe("Memory kind (identity, preference, project, etc.)"),
+        subject: z.string().describe("Subject line"),
+        statement: z.string().describe("Statement content"),
+        importance: z
+          .number()
+          .describe("Importance score (default 0.8)")
+          .optional(),
+      }),
+      responseBody: z.object({
+        item: z.object({}).passthrough().describe("Created memory item"),
+      }),
       handler: (ctx) => handleCreateMemoryItem(ctx),
     },
     {
       endpoint: "memory-items/:id",
       method: "PATCH",
       policyKey: "memory-items",
+      summary: "Update a memory item",
+      description: "Partially update fields on an existing memory item.",
+      tags: ["memory"],
+      requestBody: z.object({
+        subject: z.string(),
+        statement: z.string(),
+        kind: z.string(),
+        status: z.string(),
+        importance: z.number(),
+        sourceType: z.string(),
+        verificationState: z.string(),
+      }),
+      responseBody: z.object({
+        item: z.object({}).passthrough().describe("Updated memory item"),
+      }),
       handler: (ctx) => handleUpdateMemoryItem(ctx),
     },
     {
       endpoint: "memory-items/:id",
       method: "DELETE",
       policyKey: "memory-items",
+      summary: "Delete a memory item",
+      description: "Delete a memory item and its embeddings.",
+      tags: ["memory"],
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
       handler: (ctx) => handleDeleteMemoryItem(ctx),
     },
   ];