@vellumai/assistant 0.3.14 → 0.3.16

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

@@ -11,6 +11,7 @@
 import { answerCall, cancelCall, getCallStatus, relayInstruction,startCall } from '../../calls/call-domain.js';
 import { getConfig } from '../../config/loader.js';
 import { VALID_CALLER_IDENTITY_MODES } from '../../config/schema.js';
+import { httpError, httpErrorCodeFromStatus } from '../http-errors.js';
 
 // ── Idempotency cache ─────────────────────────────────────────────────────────
 // Stores serialized 201 responses keyed by idempotencyKey for 5 minutes so
@@ -42,10 +43,7 @@ function pruneIdempotencyCache(): void {
  */
 export async function handleStartCall(req: Request, assistantId: string = 'self'): Promise<Response> {
   if (!getConfig().calls.enabled) {
-    return Response.json(
-      { error: 'Calls feature is disabled via configuration. Set calls.enabled to true to use this feature.' },
-      { status: 403 },
-    );
+    return httpError('FORBIDDEN', 'Calls feature is disabled via configuration. Set calls.enabled to true to use this feature.', 403);
   }
 
   let body: {
@@ -59,23 +57,20 @@ export async function handleStartCall(req: Request, assistantId: string = 'self'
   try {
     body = await req.json() as typeof body;
   } catch {
-    return Response.json({ error: 'Invalid JSON in request body' }, { status: 400 });
+    return httpError('BAD_REQUEST', 'Invalid JSON in request body', 400);
   }
 
   if (typeof body !== 'object' || body == null || Array.isArray(body)) {
-    return Response.json({ error: 'Request body must be a JSON object' }, { status: 400 });
+    return httpError('BAD_REQUEST', 'Request body must be a JSON object', 400);
   }
 
   if (!body.conversationId) {
-    return Response.json({ error: 'conversationId is required' }, { status: 400 });
+    return httpError('BAD_REQUEST', 'conversationId is required', 400);
   }
 
   if (body.callerIdentityMode != null &&
       !(VALID_CALLER_IDENTITY_MODES as readonly string[]).includes(body.callerIdentityMode as string)) {
-    return Response.json(
-      { error: `Invalid callerIdentityMode: "${body.callerIdentityMode}". Must be one of: ${VALID_CALLER_IDENTITY_MODES.join(', ')}` },
-      { status: 400 },
-    );
+    return httpError('BAD_REQUEST', `Invalid callerIdentityMode: "${body.callerIdentityMode}". Must be one of: ${VALID_CALLER_IDENTITY_MODES.join(', ')}`, 400);
   }
 
   // Idempotency check: return cached response for duplicate requests
@@ -101,7 +96,8 @@ export async function handleStartCall(req: Request, assistantId: string = 'self'
   });
 
   if (!result.ok) {
-    return Response.json({ error: result.error }, { status: result.status ?? 500 });
+    const status = result.status ?? 500;
+    return httpError(httpErrorCodeFromStatus(status), result.error, status);
   }
 
   const responseBody = {
@@ -127,7 +123,8 @@ export function handleGetCallStatus(callSessionId: string): Response {
   const result = getCallStatus(callSessionId);
 
   if (!result.ok) {
-    return Response.json({ error: result.error }, { status: result.status ?? 500 });
+    const status = result.status ?? 500;
+    return httpError(httpErrorCodeFromStatus(status), result.error, status);
   }
 
   const { session } = result;
@@ -166,7 +163,8 @@ export async function handleCancelCall(req: Request, callSessionId: string): Pro
   const result = await cancelCall({ callSessionId, reason });
 
   if (!result.ok) {
-    return Response.json({ error: result.error }, { status: result.status ?? 500 });
+    const status = result.status ?? 500;
+    return httpError(httpErrorCodeFromStatus(status), result.error, status);
   }
 
   return Response.json({
@@ -185,11 +183,11 @@ export async function handleAnswerCall(req: Request, callSessionId: string): Pro
   try {
     body = await req.json() as typeof body;
   } catch {
-    return Response.json({ error: 'Invalid JSON in request body' }, { status: 400 });
+    return httpError('BAD_REQUEST', 'Invalid JSON in request body', 400);
   }
 
   if (typeof body !== 'object' || body == null || Array.isArray(body)) {
-    return Response.json({ error: 'Request body must be a JSON object' }, { status: 400 });
+    return httpError('BAD_REQUEST', 'Request body must be a JSON object', 400);
   }
 
   const result = await answerCall({
@@ -198,7 +196,8 @@ export async function handleAnswerCall(req: Request, callSessionId: string): Pro
   });
 
   if (!result.ok) {
-    return Response.json({ error: result.error }, { status: result.status ?? 500 });
+    const status = result.status ?? 500;
+    return httpError(httpErrorCodeFromStatus(status), result.error, status);
   }
 
   return Response.json({ ok: true, questionId: result.questionId });
@@ -214,11 +213,11 @@ export async function handleInstructionCall(req: Request, callSessionId: string)
   try {
     body = await req.json() as typeof body;
   } catch {
-    return Response.json({ error: 'Invalid JSON in request body' }, { status: 400 });
+    return httpError('BAD_REQUEST', 'Invalid JSON in request body', 400);
   }
 
   if (typeof body !== 'object' || body == null || Array.isArray(body)) {
-    return Response.json({ error: 'Request body must be a JSON object' }, { status: 400 });
+    return httpError('BAD_REQUEST', 'Request body must be a JSON object', 400);
   }
 
   const result = await relayInstruction({
@@ -227,7 +226,8 @@ export async function handleInstructionCall(req: Request, callSessionId: string)
   });
 
   if (!result.ok) {
-    return Response.json({ error: result.error }, { status: result.status ?? 500 });
+    const status = result.status ?? 500;
+    return httpError(httpErrorCodeFromStatus(status), result.error, status);
   }
 
   return Response.json({ ok: true });

package/src/runtime/routes/channel-delivery-routes.ts

@@ -3,6 +3,7 @@
  * and post-decision delivery scheduling.
  */
 import * as channelDeliveryStore from '../../memory/channel-delivery-store.js';
+import { httpError } from '../http-errors.js';
 export { type DeliverReplyOptions,deliverReplyViaCallback } from '../channel-reply-delivery.js';
 
 // ---------------------------------------------------------------------------
@@ -19,7 +20,7 @@ export async function handleReplayDeadLetters(req: Request): Promise<Response> {
   const eventIds = body.eventIds;
 
   if (!Array.isArray(eventIds) || eventIds.length === 0) {
-    return Response.json({ error: 'eventIds array is required' }, { status: 400 });
+    return httpError('BAD_REQUEST', 'eventIds array is required', 400);
   }
 
   const replayed = channelDeliveryStore.replayDeadLetters(eventIds);
@@ -40,13 +41,13 @@ export async function handleChannelDeliveryAck(req: Request): Promise<Response>
   const { sourceChannel, externalChatId, externalMessageId } = body;
 
   if (!sourceChannel || typeof sourceChannel !== 'string') {
-    return Response.json({ error: 'sourceChannel is required' }, { status: 400 });
+    return httpError('BAD_REQUEST', 'sourceChannel is required', 400);
   }
   if (!externalChatId || typeof externalChatId !== 'string') {
-    return Response.json({ error: 'externalChatId is required' }, { status: 400 });
+    return httpError('BAD_REQUEST', 'externalChatId is required', 400);
   }
   if (!externalMessageId || typeof externalMessageId !== 'string') {
-    return Response.json({ error: 'externalMessageId is required' }, { status: 400 });
+    return httpError('BAD_REQUEST', 'externalMessageId is required', 400);
   }
 
   const acked = channelDeliveryStore.acknowledgeDelivery(
@@ -56,7 +57,7 @@ export async function handleChannelDeliveryAck(req: Request): Promise<Response>
   );
 
   if (!acked) {
-    return Response.json({ error: 'Inbound event not found' }, { status: 404 });
+    return httpError('NOT_FOUND', 'Inbound event not found', 404);
   }
 
   return new Response(null, { status: 204 });

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

@@ -7,6 +7,7 @@
  */
 
 import { getContact, listContacts, mergeContacts } from '../../contacts/contact-store.js';
+import { httpError } from '../http-errors.js';
 
 /**
  * GET /v1/contacts?limit=50
@@ -23,10 +24,7 @@ export function handleListContacts(url: URL): Response {
 export function handleGetContact(contactId: string): Response {
   const contact = getContact(contactId);
   if (!contact) {
-    return Response.json(
-      { ok: false, error: `Contact "${contactId}" not found` },
-      { status: 404 },
-    );
+    return httpError('NOT_FOUND', `Contact "${contactId}" not found`, 404);
   }
   return Response.json({ ok: true, contact });
 }
@@ -38,10 +36,7 @@ export async function handleMergeContacts(req: Request): Promise<Response> {
   const body = (await req.json()) as { keepId?: string; mergeId?: string };
 
   if (!body.keepId || !body.mergeId) {
-    return Response.json(
-      { ok: false, error: 'keepId and mergeId are required' },
-      { status: 400 },
-    );
+    return httpError('BAD_REQUEST', 'keepId and mergeId are required', 400);
   }
 
   try {
@@ -49,6 +44,6 @@ export async function handleMergeContacts(req: Request): Promise<Response> {
     return Response.json({ ok: true, contact });
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    return Response.json({ ok: false, error: message }, { status: 400 });
+    return httpError('BAD_REQUEST', message, 400);
   }
 }

package/src/runtime/routes/conversation-attention-routes.ts

@@ -10,6 +10,7 @@ import {
 } from '../../memory/conversation-attention-store.js';
 import * as conversationStore from '../../memory/conversation-store.js';
 import { truncate } from '../../util/truncate.js';
+import { httpError } from '../http-errors.js';
 
 export function handleListConversationAttention(url: URL): Response {
   const stateParam = url.searchParams.get('state') ?? 'all';
@@ -22,7 +23,7 @@ export function handleListConversationAttention(url: URL): Response {
   const before = rawBefore !== undefined && Number.isFinite(rawBefore) ? rawBefore : undefined;
 
   if (!['seen', 'unseen', 'all'].includes(stateParam)) {
-    return Response.json({ error: 'Invalid state parameter. Must be seen, unseen, or all.' }, { status: 400 });
+    return httpError('BAD_REQUEST', 'Invalid state parameter. Must be seen, unseen, or all.', 400);
   }
 
   const attentionStates = listConversationAttention({
@@ -61,9 +62,9 @@ export function handleListConversationAttention(url: URL): Response {
   const results = pageStates.map((attn) => {
     const conv = conversationMap.get(attn.conversationId);
     const convSource = conv?.source ?? 'user';
-    const hasUnseen = attn.latestAssistantMessageAt !== null &&
-      (attn.lastSeenAssistantMessageAt === null || attn.lastSeenAssistantMessageAt < attn.latestAssistantMessageAt);
-    const state: 'seen' | 'unseen' | 'no_assistant_message' = attn.latestAssistantMessageAt === null
+    const hasUnseen = attn.latestAssistantMessageAt != null &&
+      (attn.lastSeenAssistantMessageAt == null || attn.lastSeenAssistantMessageAt < attn.latestAssistantMessageAt);
+    const state: 'seen' | 'unseen' | 'no_assistant_message' = attn.latestAssistantMessageAt == null
       ? 'no_assistant_message'
       : hasUnseen ? 'unseen' : 'seen';
 

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

@@ -17,6 +17,7 @@ import { getConfiguredProvider } from '../../providers/provider-send-message.js'
 import type { Provider } from '../../providers/types.js';
 import { getLogger } from '../../util/logger.js';
 import { buildAssistantEvent } from '../assistant-event.js';
+import { httpError } from '../http-errors.js';
 import type {
   MessageProcessor,
   NonBlockingMessageProcessor,
@@ -64,10 +65,7 @@ export function handleListMessages(
     const mapping = getConversationByKey(conversationKey);
     resolvedConversationId = mapping?.conversationId;
   } else {
-    return Response.json(
-      { error: 'conversationKey or conversationId query parameter is required' },
-      { status: 400 },
-    );
+    return httpError('BAD_REQUEST', 'conversationKey or conversationId query parameter is required', 400);
   }
 
   if (!resolvedConversationId) {
@@ -181,10 +179,10 @@ function makeHubPublisher(
       });
     }
 
-    const msgRecord = msg as unknown as Record<string, unknown>;
+    // ServerMessage is a large union; sessionId exists on most but not all variants.
     const msgSessionId =
-      'sessionId' in msg && typeof msgRecord.sessionId === 'string'
-        ? (msgRecord.sessionId as string)
+      'sessionId' in msg && typeof (msg as { sessionId?: unknown }).sessionId === 'string'
+        ? (msg as { sessionId: string }).sessionId
         : undefined;
     const resolvedSessionId = msgSessionId ?? conversationId;
     const event = buildAssistantEvent('self', msg, resolvedSessionId);
@@ -217,57 +215,36 @@ export async function handleSendMessage(
 
   const { conversationKey, content, attachmentIds } = body;
   if (!body.sourceChannel || typeof body.sourceChannel !== 'string') {
-    return Response.json(
-      { error: 'sourceChannel is required' },
-      { status: 400 },
-    );
+    return httpError('BAD_REQUEST', 'sourceChannel is required', 400);
   }
   const sourceChannel = parseChannelId(body.sourceChannel);
 
   if (!sourceChannel) {
-    return Response.json(
-      { error: `Invalid sourceChannel: ${body.sourceChannel}. Valid values: ${CHANNEL_IDS.join(', ')}` },
-      { status: 400 },
-    );
+    return httpError('BAD_REQUEST', `Invalid sourceChannel: ${body.sourceChannel}. Valid values: ${CHANNEL_IDS.join(', ')}`, 400);
   }
 
   if (!body.interface || typeof body.interface !== 'string') {
-    return Response.json(
-      { error: 'interface is required' },
-      { status: 400 },
-    );
+    return httpError('BAD_REQUEST', 'interface is required', 400);
   }
   const sourceInterface = parseInterfaceId(body.interface);
   if (!sourceInterface) {
-    return Response.json(
-      { error: `Invalid interface: ${body.interface}. Valid values: ${INTERFACE_IDS.join(', ')}` },
-      { status: 400 },
-    );
+    return httpError('BAD_REQUEST', `Invalid interface: ${body.interface}. Valid values: ${INTERFACE_IDS.join(', ')}`, 400);
   }
 
   if (!conversationKey) {
-    return Response.json(
-      { error: 'conversationKey is required' },
-      { status: 400 },
-    );
+    return httpError('BAD_REQUEST', 'conversationKey is required', 400);
   }
 
   // Reject non-string content values (numbers, objects, etc.)
   if (content != null && typeof content !== 'string') {
-    return Response.json(
-      { error: 'content must be a string' },
-      { status: 400 },
-    );
+    return httpError('BAD_REQUEST', 'content must be a string', 400);
   }
 
   const trimmedContent = typeof content === 'string' ? content.trim() : '';
   const hasAttachments = Array.isArray(attachmentIds) && attachmentIds.length > 0;
 
   if (trimmedContent.length === 0 && !hasAttachments) {
-    return Response.json(
-      { error: 'content or attachmentIds is required' },
-      { status: 400 },
-    );
+    return httpError('BAD_REQUEST', 'content or attachmentIds is required', 400);
   }
 
   // Validate that all attachment IDs resolve
@@ -276,10 +253,7 @@ export async function handleSendMessage(
     if (resolved.length !== attachmentIds.length) {
       const resolvedIds = new Set(resolved.map((a) => a.id));
       const missing = attachmentIds.filter((id) => !resolvedIds.has(id));
-      return Response.json(
-        { error: `Attachment IDs not found: ${missing.join(', ')}` },
-        { status: 400 },
-      );
+      return httpError('BAD_REQUEST', `Attachment IDs not found: ${missing.join(', ')}`, 400);
     }
   }
 
@@ -299,6 +273,13 @@ export async function handleSendMessage(
       : [];
 
     if (session.isProcessing()) {
+      // If a tool confirmation is pending, auto-deny it so the agent
+      // can finish the current turn and process this queued message.
+      if (session.hasAnyPendingConfirmation()) {
+        session.denyAllPendingConfirmations();
+        pendingInteractions.removeBySession(session);
+      }
+
       // Queue the message so it's processed when the current turn completes
       const requestId = crypto.randomUUID();
       const result = session.enqueueMessage(
@@ -317,10 +298,7 @@ export async function handleSendMessage(
         { isInteractive: false },
       );
       if (result.rejected) {
-        return Response.json(
-          { error: 'Message queue is full. Please retry later.' },
-          { status: 429 },
-        );
+        return httpError('RATE_LIMITED', 'Message queue is full. Please retry later.', 429);
       }
       return Response.json({ accepted: true, queued: true }, { status: 202 });
     }
@@ -335,7 +313,7 @@ export async function handleSendMessage(
       assistantMessageInterface: sourceInterface,
     });
     const requestId = crypto.randomUUID();
-    const messageId = session.persistUserMessage(content ?? '', attachments, requestId);
+    const messageId = await session.persistUserMessage(content ?? '', attachments, requestId);
 
     // Fire-and-forget the agent loop; events flow to the hub via onEvent.
     // Mark non-interactive so conflict clarification doesn't block the turn.
@@ -349,7 +327,7 @@ export async function handleSendMessage(
   // ── Legacy path (fallback when sendMessageDeps not wired) ───────────
   const processor = deps.persistAndProcessMessage ?? deps.processMessage;
   if (!processor) {
-    return Response.json({ error: 'Message processing not configured' }, { status: 503 });
+    return httpError('SERVICE_UNAVAILABLE', 'Message processing not configured', 503);
   }
 
   try {
@@ -364,10 +342,7 @@ export async function handleSendMessage(
     return Response.json({ accepted: true, messageId: result.messageId }, { status: 202 });
   } catch (err) {
     if (err instanceof Error && err.message === 'Session is already processing a message') {
-      return Response.json(
-        { error: 'Session is busy processing another message. Please retry.' },
-        { status: 409 },
-      );
+      return httpError('CONFLICT', 'Session is busy processing another message. Please retry.', 409);
     }
     throw err;
   }
@@ -406,10 +381,7 @@ export async function handleGetSuggestion(
 ): Promise<Response> {
   const conversationKey = url.searchParams.get('conversationKey');
   if (!conversationKey) {
-    return Response.json(
-      { error: 'conversationKey query parameter is required' },
-      { status: 400 },
-    );
+    return httpError('BAD_REQUEST', 'conversationKey query parameter is required', 400);
   }
 
   const mapping = getConversationByKey(conversationKey);
@@ -517,10 +489,7 @@ export async function handleGetSuggestion(
 export function handleSearchConversations(url: URL): Response {
   const query = url.searchParams.get('q') ?? '';
   if (!query.trim()) {
-    return Response.json(
-      { error: 'q query parameter is required' },
-      { status: 400 },
-    );
+    return httpError('BAD_REQUEST', 'q query parameter is required', 400);
   }
 
   const limit = url.searchParams.has('limit')

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

@@ -0,0 +1,71 @@
+/**
+ * Debug introspection endpoint for monitoring and troubleshooting.
+ */
+
+import { statSync } from 'node:fs';
+
+import { getDbPath } from '../../util/platform.js';
+import { countConversations } from '../../memory/conversation-store.js';
+import { getMemoryJobCounts } from '../../memory/jobs-store.js';
+import { countSchedules } from '../../schedule/schedule-store.js';
+import { rawAll } from '../../memory/db.js';
+import { getConfig } from '../../config/loader.js';
+import { getProviderDebugStatus } from '../../providers/registry.js';
+
+/** Process start time — used to calculate uptime. */
+const startedAt = Date.now();
+
+function getDatabaseSizeBytes(): number | null {
+  try {
+    return statSync(getDbPath()).size;
+  } catch {
+    return null;
+  }
+}
+
+function getMemoryItemCount(): number {
+  try {
+    const rows = rawAll<{ c: number }>('SELECT COUNT(*) AS c FROM memory_items');
+    return rows[0]?.c ?? 0;
+  } catch {
+    return 0;
+  }
+}
+
+export function handleDebug(): Response {
+  const now = Date.now();
+  const uptimeSeconds = Math.floor((now - startedAt) / 1000);
+
+  const conversationCount = countConversations();
+  const memoryItemCount = getMemoryItemCount();
+  const dbSizeBytes = getDatabaseSizeBytes();
+
+  const memoryJobCounts = getMemoryJobCounts();
+
+  const scheduleCounts = countSchedules();
+
+  const config = getConfig();
+  const providerOrder = Array.isArray(config.providerOrder) ? config.providerOrder : [];
+  const providerStatus = getProviderDebugStatus(config.provider, providerOrder);
+
+  return Response.json({
+    session: {
+      uptimeSeconds,
+      startedAt: new Date(startedAt).toISOString(),
+    },
+    provider: providerStatus,
+    memory: {
+      conversationCount,
+      memoryItemCount,
+      ...(dbSizeBytes != null ? { databaseSizeBytes: dbSizeBytes } : {}),
+    },
+    jobs: {
+      memory: memoryJobCounts,
+    },
+    schedules: {
+      total: scheduleCounts.total,
+      enabled: scheduleCounts.enabled,
+    },
+    timestamp: new Date(now).toISOString(),
+  });
+}

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

@@ -11,6 +11,7 @@ import { getOrCreateConversation } from '../../memory/conversation-key-store.js'
 import { formatSseFrame, formatSseHeartbeat } from '../assistant-event.js';
 import type { AssistantEventSubscription } from '../assistant-event-hub.js';
 import { AssistantEventHub,assistantEventHub } from '../assistant-event-hub.js';
+import { httpError } from '../http-errors.js';
 
 /** Keep-alive comment sent to idle clients every 30 s by default. */
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
@@ -35,7 +36,7 @@ export function handleSubscribeAssistantEvents(
 ): Response {
   const conversationKey = url.searchParams.get('conversationKey');
   if (!conversationKey) {
-    return Response.json({ error: 'conversationKey is required' }, { status: 400 });
+    return httpError('BAD_REQUEST', 'conversationKey is required', 400);
   }
 
   const hub = options?.hub ?? assistantEventHub;
@@ -88,7 +89,7 @@ export function handleSubscribeAssistantEvents(
     );
   } catch (err) {
     if (err instanceof RangeError) {
-      return Response.json({ error: 'Too many concurrent connections' }, { status: 503 });
+      return httpError('SERVICE_UNAVAILABLE', 'Too many concurrent connections', 503);
     }
     throw err;
   }