@vellumai/assistant 0.3.4 → 0.3.6

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;
+}

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

@@ -0,0 +1,211 @@
+// User/assistant messages, tool results, confirmations, secrets, errors, and generation lifecycle.
+
+import type { ChannelId } from '../../channels/types.js';
+import type { UserMessageAttachment } from './shared.js';
+
+// === Client → Server ===
+
+export interface UserMessage {
+  type: 'user_message';
+  sessionId: string;
+  content?: string;
+  attachments?: UserMessageAttachment[];
+  activeSurfaceId?: string;
+  /** The page currently displayed in the WebView (e.g. "settings.html"). */
+  currentPage?: string;
+  /** When true, skip the secret-ingress check. Set by the client when the user clicks "Send Anyway". */
+  bypassSecretCheck?: boolean;
+  /** Originating channel identifier (e.g. 'macos', 'ios'). Defaults to 'macos' when absent. */
+  channel?: ChannelId;
+}
+
+export interface ConfirmationResponse {
+  type: 'confirmation_response';
+  requestId: string;
+  decision: 'allow' | 'always_allow' | 'always_allow_high_risk' | 'deny' | 'always_deny';
+  selectedPattern?: string;
+  selectedScope?: string;
+}
+
+export interface SecretResponse {
+  type: 'secret_response';
+  requestId: string;
+  value?: string;    // undefined = user cancelled
+  /** How the secret should be delivered: 'store' persists to keychain (default), 'transient_send' for one-time use without persisting. */
+  delivery?: 'store' | 'transient_send';
+}
+
+export interface SuggestionRequest {
+  type: 'suggestion_request';
+  sessionId: string;
+  requestId: string;
+}
+
+// === Server → Client ===
+
+export interface UserMessageEcho {
+  type: 'user_message_echo';
+  text: string;
+  sessionId?: string;
+}
+
+export interface AssistantTextDelta {
+  type: 'assistant_text_delta';
+  text: string;
+  sessionId?: string;
+}
+
+export interface AssistantThinkingDelta {
+  type: 'assistant_thinking_delta';
+  thinking: string;
+}
+
+export interface ToolUseStart {
+  type: 'tool_use_start';
+  toolName: string;
+  input: Record<string, unknown>;
+  sessionId?: string;
+}
+
+export interface ToolOutputChunk {
+  type: 'tool_output_chunk';
+  chunk: string;
+  sessionId?: string;
+  subType?: 'tool_start' | 'tool_complete' | 'status';
+  subToolName?: string;
+  subToolInput?: string;
+  subToolIsError?: boolean;
+  subToolId?: string;
+}
+
+export interface ToolInputDelta {
+  type: 'tool_input_delta';
+  toolName: string;
+  content: string;
+  sessionId?: string;
+}
+
+export interface ToolResult {
+  type: 'tool_result';
+  toolName: string;
+  result: string;
+  isError?: boolean;
+  diff?: { filePath: string; oldContent: string; newContent: string; isNewFile: boolean };
+  status?: string;
+  sessionId?: string;
+  /** Base64-encoded image data extracted from contentBlocks (e.g. browser_screenshot). */
+  imageData?: string;
+}
+
+export interface ConfirmationRequest {
+  type: 'confirmation_request';
+  requestId: string;
+  toolName: string;
+  input: Record<string, unknown>;
+  riskLevel: string;
+  executionTarget?: 'sandbox' | 'host';
+  allowlistOptions: Array<{ label: string; description: string; pattern: string }>;
+  scopeOptions: Array<{ label: string; scope: string }>;
+  diff?: { filePath: string; oldContent: string; newContent: string; isNewFile: boolean };
+  sandboxed?: boolean;
+  sessionId?: string;
+  /** When false, the client should hide "always allow" / trust-rule persistence affordances. */
+  persistentDecisionsAllowed?: boolean;
+}
+
+export interface SecretRequest {
+  type: 'secret_request';
+  requestId: string;
+  service: string;
+  field: string;
+  label: string;
+  description?: string;
+  placeholder?: string;
+  sessionId?: string;
+  /** Intended purpose of the credential (displayed to user). */
+  purpose?: string;
+  /** Tools allowed to use this credential. */
+  allowedTools?: string[];
+  /** Domains where this credential may be used. */
+  allowedDomains?: string[];
+  /** Whether one-time send override is available. */
+  allowOneTimeSend?: boolean;
+}
+
+export interface MessageComplete {
+  type: 'message_complete';
+  sessionId?: string;
+  attachments?: UserMessageAttachment[];
+}
+
+export interface ErrorMessage {
+  type: 'error';
+  message: string;
+  /** Categorizes the error so the client can offer contextual actions (e.g. "Send Anyway" for secret_blocked). */
+  category?: string;
+}
+
+export interface SecretDetected {
+  type: 'secret_detected';
+  toolName: string;
+  matches: Array<{ type: string; redactedValue: string }>;
+  action: 'redact' | 'warn' | 'block' | 'prompt';
+}
+
+export interface MessageQueued {
+  type: 'message_queued';
+  sessionId: string;
+  requestId: string;
+  position: number;
+}
+
+export interface MessageDequeued {
+  type: 'message_dequeued';
+  sessionId: string;
+  requestId: string;
+}
+
+export interface MessageQueuedDeleted {
+  type: 'message_queued_deleted';
+  sessionId: string;
+  requestId: string;
+}
+
+export interface SuggestionResponse {
+  type: 'suggestion_response';
+  requestId: string;
+  suggestion: string | null;
+  source: 'llm' | 'none';
+}
+
+export type TraceEventKind =
+  | 'request_received'
+  | 'request_queued'
+  | 'request_dequeued'
+  | 'llm_call_started'
+  | 'llm_call_finished'
+  | 'assistant_message'
+  | 'tool_started'
+  | 'tool_permission_requested'
+  | 'tool_permission_decided'
+  | 'tool_finished'
+  | 'tool_failed'
+  | 'secret_detected'
+  | 'generation_handoff'
+  | 'message_complete'
+  | 'generation_cancelled'
+  | 'request_error'
+  | 'tool_profiling_summary';
+
+export interface TraceEvent {
+  type: 'trace_event';
+  eventId: string;
+  sessionId: string;
+  requestId?: string;
+  timestampMs: number;
+  sequence: number;
+  kind: TraceEventKind;
+  status?: 'info' | 'success' | 'warning' | 'error';
+  summary: string;
+  attributes?: Record<string, string | number | boolean | null>;
+}

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

@@ -0,0 +1,45 @@
+// Pairing approval and approved-device management types.
+
+// === Client → Server ===
+
+export interface PairingApprovalResponse {
+  type: 'pairing_approval_response';
+  pairingRequestId: string;
+  decision: 'approve_once' | 'always_allow' | 'deny';
+}
+
+export interface ApprovedDevicesList {
+  type: 'approved_devices_list';
+}
+
+export interface ApprovedDeviceRemove {
+  type: 'approved_device_remove';
+  hashedDeviceId: string;
+}
+
+export interface ApprovedDevicesClear {
+  type: 'approved_devices_clear';
+}
+
+// === Server → Client ===
+
+export interface PairingApprovalRequest {
+  type: 'pairing_approval_request';
+  pairingRequestId: string;
+  deviceId: string;
+  deviceName: string;
+}
+
+export interface ApprovedDevicesListResponse {
+  type: 'approved_devices_list_response';
+  devices: Array<{
+    hashedDeviceId: string;
+    deviceName: string;
+    lastPairedAt: number;
+  }>;
+}
+
+export interface ApprovedDeviceRemoveResponse {
+  type: 'approved_device_remove_response';
+  success: boolean;
+}

package/src/daemon/ipc-contract/parental-control.ts

@@ -0,0 +1,95 @@
+// Parental control IPC types.
+//
+// The parental control system lets a parent or guardian lock the assistant
+// behind a 6-digit PIN and configure per-topic content restrictions and
+// per-category tool blocks. All mutating operations require the PIN when
+// one has been set.
+
+// === Shared data types ===
+
+/**
+ * Topics that can be individually blocked.
+ * All unlisted topics are allowed.
+ */
+export type ParentalContentTopic =
+  | 'violence'
+  | 'adult_content'
+  | 'political'
+  | 'gambling'
+  | 'drugs';
+
+/**
+ * Broad tool categories that can be disabled for age-appropriate use.
+ * When a category is blocked, individual tool invocations within that
+ * category are rejected before the permission pipeline runs.
+ */
+export type ParentalToolCategory =
+  | 'computer_use'
+  | 'network'
+  | 'shell'
+  | 'file_write';
+
+// === Client → Server ===
+
+/** Retrieve the current parental control settings and PIN status. */
+export interface ParentalControlGetRequest {
+  type: 'parental_control_get';
+}
+
+/** Verify a PIN attempt without changing any state. Useful to gate an unlock-settings flow before showing the full panel. */
+export interface ParentalControlVerifyPinRequest {
+  type: 'parental_control_verify_pin';
+  pin: string;
+}
+
+/** Set, change, or clear the parental control PIN. To set for the first time provide only new_pin. To change provide current_pin and new_pin. To clear provide current_pin and set clear:true. */
+export interface ParentalControlSetPinRequest {
+  type: 'parental_control_set_pin';
+  current_pin?: string;
+  new_pin?: string;
+  clear?: boolean;
+}
+
+/** Update parental control settings. Requires the PIN when parental mode is already enabled. */
+export interface ParentalControlUpdateRequest {
+  type: 'parental_control_update';
+  /** Current PIN — required when parental mode is already enabled. */
+  pin?: string;
+  /** Enable or disable parental control mode. */
+  enabled?: boolean;
+  /** Full replacement list of blocked content topics. */
+  content_restrictions?: ParentalContentTopic[];
+  /** Full replacement list of blocked tool categories. */
+  blocked_tool_categories?: ParentalToolCategory[];
+}
+
+// === Server → Client ===
+
+export interface ParentalControlGetResponse {
+  type: 'parental_control_get_response';
+  enabled: boolean;
+  has_pin: boolean;
+  content_restrictions: ParentalContentTopic[];
+  blocked_tool_categories: ParentalToolCategory[];
+}
+
+export interface ParentalControlVerifyPinResponse {
+  type: 'parental_control_verify_pin_response';
+  verified: boolean;
+}
+
+export interface ParentalControlSetPinResponse {
+  type: 'parental_control_set_pin_response';
+  success: boolean;
+  error?: string;
+}
+
+export interface ParentalControlUpdateResponse {
+  type: 'parental_control_update_response';
+  success: boolean;
+  error?: string;
+  enabled: boolean;
+  has_pin: boolean;
+  content_restrictions: ParentalContentTopic[];
+  blocked_tool_categories: ParentalToolCategory[];
+}