@vellumai/assistant 0.3.5 → 0.3.7

package/src/daemon/ipc-contract/inbox.ts

@@ -0,0 +1,209 @@
+// Assistant inbox: invite management, member management, inbox threads, escalations, and replies.
+
+// === Client → Server ===
+
+export interface IngressInviteRequest {
+  type: 'ingress_invite';
+  action: 'create' | 'list' | 'revoke' | 'redeem';
+  /** Source channel for the invite (required for create and redeem). */
+  sourceChannel?: string;
+  /** Optional note describing the invite (create only). */
+  note?: string;
+  /** Maximum number of times the invite can be redeemed (create only). */
+  maxUses?: number;
+  /** Expiration time in milliseconds from now (create only). */
+  expiresInMs?: number;
+  /** Invite ID to revoke (revoke only). */
+  inviteId?: string;
+  /** Invite token to redeem (redeem only). */
+  token?: string;
+  /** External user ID of the redeemer (redeem only). */
+  externalUserId?: string;
+  /** External chat ID of the redeemer (redeem only). */
+  externalChatId?: string;
+  /** Filter by status (list only). */
+  status?: string;
+}
+
+export interface IngressMemberRequest {
+  type: 'ingress_member';
+  action: 'list' | 'upsert' | 'revoke' | 'block';
+  /** Source channel (required for upsert, optional filter for list). */
+  sourceChannel?: string;
+  /** External user ID (upsert only). */
+  externalUserId?: string;
+  /** External chat ID (upsert only). */
+  externalChatId?: string;
+  /** Display name (upsert only). */
+  displayName?: string;
+  /** Username (upsert only). */
+  username?: string;
+  /** Access policy (upsert only). */
+  policy?: 'allow' | 'deny' | 'escalate';
+  /** Member status (upsert only for setting, list only for filtering). */
+  status?: 'pending' | 'active';
+  /** Member ID (revoke and block only). */
+  memberId?: string;
+  /** Reason for revoke or block (revoke and block only). */
+  reason?: string;
+}
+
+export interface AssistantInboxRequest {
+  type: 'assistant_inbox';
+  action: 'list_threads' | 'get_thread_messages';
+  /** Filter by assistant ID (list_threads only). */
+  assistantId?: string;
+  /** Maximum number of results to return (list_threads and get_thread_messages). */
+  limit?: number;
+  /** Offset for pagination (list_threads only). */
+  offset?: number;
+  /** Conversation ID (required for get_thread_messages). */
+  conversationId?: string;
+  /** Cursor for message pagination — return messages before this ID (get_thread_messages only). */
+  beforeMessageId?: string;
+}
+
+export interface AssistantInboxEscalationRequest {
+  type: 'assistant_inbox_escalation';
+  action: 'list' | 'decide';
+  /** Filter by assistant ID (list only). */
+  assistantId?: string;
+  /** Filter by status (list only). */
+  status?: string;
+  /** Approval request ID (required for decide). */
+  approvalRequestId?: string;
+  /** Decision (required for decide). */
+  decision?: 'approve' | 'deny';
+  /** Reason for the decision (decide only). */
+  reason?: string;
+}
+
+export interface AssistantInboxReplyRequest {
+  type: 'assistant_inbox_reply';
+  conversationId: string;
+  content: string;
+}
+
+// === Server → Client ===
+
+export interface IngressInviteResponse {
+  type: 'ingress_invite_response';
+  success: boolean;
+  error?: string;
+  /** Single invite (returned on create/revoke). Token field is only present on create. */
+  invite?: {
+    id: string;
+    sourceChannel: string;
+    token?: string;
+    tokenHash: string;
+    maxUses: number;
+    useCount: number;
+    expiresAt: number | null;
+    status: string;
+    note?: string;
+    createdAt: number;
+  };
+  /** List of invites (returned on list). */
+  invites?: Array<{
+    id: string;
+    sourceChannel: string;
+    tokenHash: string;
+    maxUses: number;
+    useCount: number;
+    expiresAt: number | null;
+    status: string;
+    note?: string;
+    createdAt: number;
+  }>;
+}
+
+export interface IngressMemberResponse {
+  type: 'ingress_member_response';
+  success: boolean;
+  error?: string;
+  /** Single member (returned on upsert/revoke/block). */
+  member?: {
+    id: string;
+    sourceChannel: string;
+    externalUserId?: string;
+    externalChatId?: string;
+    displayName?: string;
+    username?: string;
+    status: string;
+    policy: string;
+    lastSeenAt?: number;
+    createdAt: number;
+  };
+  /** List of members (returned on list). */
+  members?: Array<{
+    id: string;
+    sourceChannel: string;
+    externalUserId?: string;
+    externalChatId?: string;
+    displayName?: string;
+    username?: string;
+    status: string;
+    policy: string;
+    lastSeenAt?: number;
+    createdAt: number;
+  }>;
+}
+
+export interface AssistantInboxResponse {
+  type: 'assistant_inbox_response';
+  success: boolean;
+  error?: string;
+  /** List of inbox threads (returned on list_threads). */
+  threads?: Array<{
+    conversationId: string;
+    sourceChannel: string;
+    externalChatId: string;
+    externalUserId?: string;
+    displayName?: string;
+    username?: string;
+    lastMessageAt?: number;
+    unreadCount: number;
+    hasPendingEscalation: boolean;
+    lastInboundAt?: number;
+    lastOutboundAt?: number;
+  }>;
+  /** List of messages (returned on get_thread_messages). */
+  messages?: Array<{
+    id: string;
+    role: string;
+    content: string;
+    createdAt: number;
+    metadata?: Record<string, unknown>;
+  }>;
+}
+
+export interface AssistantInboxEscalationResponse {
+  type: 'assistant_inbox_escalation_response';
+  success: boolean;
+  error?: string;
+  /** List of escalations (returned on list). */
+  escalations?: Array<{
+    id: string;
+    runId: string;
+    conversationId: string;
+    channel: string;
+    requesterExternalUserId: string;
+    requesterChatId: string;
+    status: string;
+    requestSummary?: string;
+    createdAt: number;
+  }>;
+  /** Decision result (returned on decide). */
+  decision?: {
+    id: string;
+    status: string;
+    decidedAt: number;
+  };
+}
+
+export interface AssistantInboxReplyResponse {
+  type: 'assistant_inbox_reply_response';
+  success: boolean;
+  error?: string;
+  messageId?: string;
+}

package/src/daemon/ipc-contract/integrations.ts

@@ -0,0 +1,284 @@
+// External service integrations: Slack, Telegram, Twilio, Twitter, Vercel, ingress, channel readiness, guardian.
+
+import type { ChannelId } from '../../channels/types.js';
+
+// === Client → Server ===
+
+export interface SlackWebhookConfigRequest {
+  type: 'slack_webhook_config';
+  action: 'get' | 'set';
+  webhookUrl?: string;
+}
+
+export interface IngressConfigRequest {
+  type: 'ingress_config';
+  action: 'get' | 'set';
+  publicBaseUrl?: string;
+  enabled?: boolean;
+}
+
+export interface VercelApiConfigRequest {
+  type: 'vercel_api_config';
+  action: 'get' | 'set' | 'delete';
+  apiToken?: string;
+}
+
+export interface TwitterIntegrationConfigRequest {
+  type: 'twitter_integration_config';
+  action: 'get' | 'set_mode' | 'set_local_client' | 'clear_local_client' | 'disconnect' | 'get_strategy' | 'set_strategy';
+  mode?: 'local_byo' | 'managed';
+  clientId?: string;
+  clientSecret?: string;
+  strategy?: string;
+}
+
+export interface TelegramConfigRequest {
+  type: 'telegram_config';
+  action: 'get' | 'set' | 'clear' | 'set_commands';
+  botToken?: string;  // Only for action: 'set'
+  commands?: Array<{ command: string; description: string }>;  // Only for action: 'set_commands'
+}
+
+export interface TwilioConfigRequest {
+  type: 'twilio_config';
+  action: 'get' | 'set_credentials' | 'clear_credentials' | 'provision_number' | 'assign_number' | 'list_numbers'
+    | 'sms_compliance_status' | 'sms_submit_tollfree_verification' | 'sms_update_tollfree_verification'
+    | 'sms_delete_tollfree_verification' | 'release_number' | 'sms_send_test' | 'sms_doctor';
+  accountSid?: string;        // Only for action: 'set_credentials'
+  authToken?: string;         // Only for action: 'set_credentials'
+  phoneNumber?: string;       // Only for action: 'assign_number' or 'sms_send_test'
+  areaCode?: string;          // Only for action: 'provision_number'
+  country?: string;           // Only for action: 'provision_number' (ISO 3166-1 alpha-2, default 'US')
+  assistantId?: string;       // Scope number assignment/lookup to a specific assistant
+  verificationSid?: string;   // Only for update/delete verification actions
+  verificationParams?: {
+    tollfreePhoneNumberSid?: string;
+    businessName?: string;
+    businessWebsite?: string;
+    notificationEmail?: string;
+    useCaseCategories?: string[];
+    useCaseSummary?: string;
+    productionMessageSample?: string;
+    optInImageUrls?: string[];
+    optInType?: string;
+    messageVolume?: string;
+    businessType?: string;
+    customerProfileSid?: string;
+  };
+  text?: string;              // Only for action: 'sms_send_test' (default: "Test SMS from your Vellum assistant")
+}
+
+export interface ChannelReadinessRequest {
+  type: 'channel_readiness';
+  action: 'get' | 'refresh';
+  channel?: ChannelId;
+  assistantId?: string;
+  includeRemote?: boolean;
+}
+
+export interface GuardianVerificationRequest {
+  type: 'guardian_verification';
+  action: 'create_challenge' | 'status' | 'revoke';
+  channel?: ChannelId;  // Defaults to 'telegram'
+  sessionId?: string;
+  assistantId?: string;  // Defaults to 'self'
+}
+
+export interface TwitterAuthStartRequest {
+  type: 'twitter_auth_start';
+}
+
+export interface TwitterAuthStatusRequest {
+  type: 'twitter_auth_status';
+}
+
+export interface IntegrationListRequest {
+  type: 'integration_list';
+}
+
+export interface IntegrationConnectRequest {
+  type: 'integration_connect';
+  integrationId: string;
+}
+
+export interface IntegrationDisconnectRequest {
+  type: 'integration_disconnect';
+  integrationId: string;
+}
+
+export interface LinkOpenRequest {
+  type: 'link_open_request';
+  url: string;
+  metadata?: Record<string, unknown>;
+}
+
+// === Server → Client ===
+
+export interface SlackWebhookConfigResponse {
+  type: 'slack_webhook_config_response';
+  webhookUrl?: string;
+  success: boolean;
+  error?: string;
+}
+
+export interface IngressConfigResponse {
+  type: 'ingress_config_response';
+  enabled: boolean;
+  publicBaseUrl: string;
+  /** Read-only gateway target computed from GATEWAY_PORT env var (default 7830) + loopback host. */
+  localGatewayTarget: string;
+  success: boolean;
+  error?: string;
+}
+
+export interface VercelApiConfigResponse {
+  type: 'vercel_api_config_response';
+  hasToken: boolean;
+  success: boolean;
+  error?: string;
+}
+
+export interface TwitterIntegrationConfigResponse {
+  type: 'twitter_integration_config_response';
+  success: boolean;
+  mode?: 'local_byo' | 'managed';
+  managedAvailable: boolean;
+  localClientConfigured: boolean;
+  connected: boolean;
+  accountInfo?: string;
+  strategy?: 'oauth' | 'browser' | 'auto';
+  /** Whether the user has explicitly set a strategy (vs. relying on the default 'auto'). */
+  strategyConfigured?: boolean;
+  error?: string;
+}
+
+export interface TelegramConfigResponse {
+  type: 'telegram_config_response';
+  success: boolean;
+  hasBotToken: boolean;
+  botUsername?: string;
+  connected: boolean;
+  hasWebhookSecret: boolean;
+  lastError?: string;
+  error?: string;
+}
+
+export interface TwilioConfigResponse {
+  type: 'twilio_config_response';
+  success: boolean;
+  hasCredentials: boolean;
+  phoneNumber?: string;
+  numbers?: Array<{ phoneNumber: string; friendlyName: string; capabilities: { voice: boolean; sms: boolean } }>;
+  error?: string;
+  /** Non-fatal warning message (e.g. webhook sync failure that did not prevent the primary operation). */
+  warning?: string;
+  compliance?: {
+    numberType?: string;
+    verificationSid?: string;
+    verificationStatus?: string;
+    rejectionReason?: string;
+    rejectionReasons?: string[];
+    errorCode?: string;
+    editAllowed?: boolean;
+    editExpiration?: string;
+  };
+  /** Present when action is 'sms_send_test'. */
+  testResult?: {
+    messageSid: string;
+    to: string;
+    initialStatus: string;
+    finalStatus: string;
+    errorCode?: string;
+    errorMessage?: string;
+  };
+  /** Present when action is 'sms_doctor'. */
+  diagnostics?: {
+    readiness: { ready: boolean; issues: string[] };
+    compliance: { status: string; detail?: string; remediation?: string };
+    lastSend?: { status: string; errorCode?: string; remediation?: string };
+    overallStatus: 'healthy' | 'degraded' | 'broken';
+    actionItems: string[];
+  };
+}
+
+export interface ChannelReadinessResponse {
+  type: 'channel_readiness_response';
+  success: boolean;
+  snapshots?: Array<{
+    channel: ChannelId;
+    ready: boolean;
+    checkedAt: number;
+    stale: boolean;
+    reasons: Array<{ code: string; text: string }>;
+    localChecks: Array<{ name: string; passed: boolean; message: string }>;
+    remoteChecks?: Array<{ name: string; passed: boolean; message: string }>;
+  }>;
+  error?: string;
+}
+
+export interface GuardianVerificationResponse {
+  type: 'guardian_verification_response';
+  success: boolean;
+  secret?: string;
+  instruction?: string;
+  /** Present when action is 'status'. */
+  bound?: boolean;
+  guardianExternalUserId?: string;
+  /** The channel this status pertains to (e.g. "telegram", "sms"). Present when action is 'status'. */
+  channel?: ChannelId;
+  /** The assistant ID scoped to this status. Present when action is 'status'. */
+  assistantId?: string;
+  /** The delivery chat ID for the guardian (e.g. Telegram chat ID). Present when action is 'status' and bound is true. */
+  guardianDeliveryChatId?: string;
+  /** Optional channel username/handle for the bound guardian (for UI display). */
+  guardianUsername?: string;
+  /** Optional display name for the bound guardian (for UI display). */
+  guardianDisplayName?: string;
+  /** Whether a pending verification challenge exists for this (assistantId, channel). Used by relay setup to detect active voice verification sessions. */
+  hasPendingChallenge?: boolean;
+  error?: string;
+}
+
+export interface TwitterAuthResult {
+  type: 'twitter_auth_result';
+  success: boolean;
+  accountInfo?: string;
+  error?: string;
+}
+
+export interface TwitterAuthStatusResponse {
+  type: 'twitter_auth_status_response';
+  connected: boolean;
+  accountInfo?: string;
+  mode?: 'local_byo' | 'managed';
+  error?: string;
+}
+
+export interface IntegrationListResponse {
+  type: 'integration_list_response';
+  integrations: Array<{
+    id: string;
+    connected: boolean;
+    accountInfo?: string | null;
+    connectedAt?: number | null;
+    lastUsed?: number | null;
+    error?: string | null;
+  }>;
+}
+
+export interface IntegrationConnectResult {
+  type: 'integration_connect_result';
+  integrationId: string;
+  success: boolean;
+  accountInfo?: string | null;
+  error?: string | null;
+  setupRequired?: boolean;
+  setupSkillId?: string;
+  setupHint?: string;
+}
+
+export interface OpenUrl {
+  type: 'open_url';
+  url: string;
+  title?: string;
+}

package/src/daemon/ipc-contract/memory.ts

@@ -0,0 +1,48 @@
+// Memory recall and status types.
+
+export interface MemoryRecalledCandidateDebug {
+  key: string;
+  type: string;
+  kind: string;
+  finalScore: number;
+  lexical: number;
+  semantic: number;
+  recency: number;
+}
+
+export interface MemoryRecalled {
+  type: 'memory_recalled';
+  provider: string;
+  model: string;
+  lexicalHits: number;
+  semanticHits: number;
+  recencyHits: number;
+  entityHits: number;
+  relationSeedEntityCount?: number;
+  relationTraversedEdgeCount?: number;
+  relationNeighborEntityCount?: number;
+  relationExpandedItemCount?: number;
+  earlyTerminated?: boolean;
+  mergedCount: number;
+  selectedCount: number;
+  rerankApplied: boolean;
+  injectedTokens: number;
+  latencyMs: number;
+  topCandidates: MemoryRecalledCandidateDebug[];
+}
+
+export interface MemoryStatus {
+  type: 'memory_status';
+  enabled: boolean;
+  degraded: boolean;
+  reason?: string;
+  provider?: string;
+  model?: string;
+  conflictsPending: number;
+  conflictsResolved: number;
+  oldestPendingConflictAgeMs: number | null;
+  cleanupResolvedJobsPending: number;
+  cleanupSupersededJobsPending: number;
+  cleanupResolvedJobsCompleted24h: number;
+  cleanupSupersededJobsCompleted24h: number;
+}