@vellumai/assistant 0.4.54 → 0.4.56

package/src/daemon/message-types/{sessions.ts → conversations.ts}

@@ -1,21 +1,21 @@
-// Session lifecycle, auth, model config, and history types.
+// Conversation lifecycle, auth, model config, and history types.
 
 import type { ChannelId, InterfaceId } from "../../channels/types.js";
-import type { ThreadType } from "./shared.js";
+import type { ConversationType } from "./shared.js";
 import type { UserMessageAttachment } from "./shared.js";
 
 // === Client → Server ===
 
-export interface SessionListRequest {
-  type: "session_list";
-  /** Number of sessions to skip (for pagination). Defaults to 0. */
+export interface ConversationListRequest {
+  type: "conversation_list";
+  /** Number of conversations to skip (for pagination). Defaults to 0. */
   offset?: number;
-  /** Maximum number of sessions to return. Defaults to 50. */
+  /** Maximum number of conversations to return. Defaults to 50. */
   limit?: number;
 }
 
-/** Lightweight session transport metadata for channel identity and natural-language guidance. */
-export interface SessionTransportMetadata {
+/** Lightweight conversation transport metadata for channel identity and natural-language guidance. */
+export interface ConversationTransportMetadata {
   /** Logical channel identifier (e.g. "desktop", "telegram", "mobile"). */
   channelId: ChannelId;
   /** Interface identifier for this transport (e.g. "macos", "ios", "cli"). */
@@ -28,28 +28,28 @@ export interface SessionTransportMetadata {
   chatType?: string;
 }
 
-export interface SessionCreateRequest {
-  type: "session_create";
+export interface ConversationCreateRequest {
+  type: "conversation_create";
   title?: string;
   systemPromptOverride?: string;
   maxResponseTokens?: number;
   correlationId?: string;
-  transport?: SessionTransportMetadata;
-  threadType?: ThreadType;
-  /** Skill IDs to pre-activate in the new session (loaded before the first message). */
+  transport?: ConversationTransportMetadata;
+  conversationType?: ConversationType;
+  /** Skill IDs to pre-activate in the new conversation (loaded before the first message). */
   preactivatedSkillIds?: string[];
-  /** If provided, automatically sent as the first user message after session creation. */
+  /** If provided, automatically sent as the first user message after conversation creation. */
   initialMessage?: string;
 }
 
-export interface SessionSwitchRequest {
-  type: "session_switch";
-  sessionId: string;
+export interface ConversationSwitchRequest {
+  type: "conversation_switch";
+  conversationId: string;
 }
 
-export interface SessionRenameRequest {
-  type: "session_rename";
-  sessionId: string;
+export interface ConversationRenameRequest {
+  type: "conversation_rename";
+  conversationId: string;
   title: string;
 }
 
@@ -64,12 +64,12 @@ export interface PingMessage {
 
 export interface CancelRequest {
   type: "cancel";
-  sessionId?: string;
+  conversationId?: string;
 }
 
 export interface DeleteQueuedMessage {
   type: "delete_queued_message";
-  sessionId: string;
+  conversationId: string;
   requestId: string;
 }
 
@@ -89,7 +89,7 @@ export interface ImageGenModelSetRequest {
 
 export interface MessageContentResponse {
   type: "message_content_response";
-  sessionId: string;
+  conversationId: string;
   messageId: string;
   text?: string;
   toolCalls?: Array<{
@@ -101,27 +101,22 @@ export interface MessageContentResponse {
 
 export interface UndoRequest {
   type: "undo";
-  sessionId: string;
-}
-
-export interface RegenerateRequest {
-  type: "regenerate";
-  sessionId: string;
+  conversationId: string;
 }
 
 export interface UsageRequest {
   type: "usage_request";
-  sessionId: string;
+  conversationId: string;
 }
 
-export interface SessionsClearRequest {
-  type: "sessions_clear";
+export interface ConversationsClearRequest {
+  type: "conversations_clear";
 }
 
-export interface ReorderThreadsRequest {
-  type: "reorder_threads";
+export interface ReorderConversationsRequest {
+  type: "reorder_conversations";
   updates: Array<{
-    sessionId: string;
+    conversationId: string;
     displayOrder: number | null;
     isPinned: boolean;
   }>;
@@ -150,21 +145,21 @@ export interface ConversationSearchResponse {
   results: ConversationSearchResultItem[];
 }
 
-export interface SessionInfo {
-  type: "session_info";
-  sessionId: string;
+export interface ConversationInfo {
+  type: "conversation_info";
+  conversationId: string;
   title: string;
   correlationId?: string;
-  threadType?: ThreadType;
+  conversationType?: ConversationType;
 }
 
-export interface SessionTitleUpdated {
-  type: "session_title_updated";
-  sessionId: string;
+export interface ConversationTitleUpdated {
+  type: "conversation_title_updated";
+  conversationId: string;
   title: string;
 }
 
-/** Channel binding metadata exposed in session/conversation list APIs. */
+/** Channel binding metadata exposed in conversation list APIs. */
 export interface ChannelBinding {
   sourceChannel: ChannelId;
   externalChatId: string;
@@ -182,14 +177,14 @@ export interface AssistantAttention {
   lastSeenSignalType?: string;
 }
 
-export interface SessionListResponse {
-  type: "session_list_response";
-  sessions: Array<{
+export interface ConversationListResponse {
+  type: "conversation_list_response";
+  conversations: Array<{
     id: string;
     title: string;
     createdAt?: number;
     updatedAt: number;
-    threadType?: ThreadType;
+    conversationType?: ConversationType;
     source?: string;
     scheduleJobId?: string;
     channelBinding?: ChannelBinding;
@@ -199,12 +194,12 @@ export interface SessionListResponse {
     displayOrder?: number;
     isPinned?: boolean;
   }>;
-  /** Whether more sessions exist beyond the returned page. */
+  /** Whether more conversations exist beyond the returned page. */
   hasMore?: boolean;
 }
 
-export interface SessionsClearResponse {
-  type: "sessions_clear_response";
+export interface ConversationsClearResponse {
+  type: "conversations_clear_response";
   cleared: number;
 }
 
@@ -227,12 +222,12 @@ export interface DaemonStatusMessage {
 
 export interface GenerationCancelled {
   type: "generation_cancelled";
-  sessionId?: string;
+  conversationId?: string;
 }
 
 export interface GenerationHandoff {
   type: "generation_handoff";
-  sessionId: string;
+  conversationId: string;
   requestId?: string;
   queuedCount: number;
   attachments?: UserMessageAttachment[];
@@ -280,7 +275,7 @@ export interface HistoryResponseSurface {
 
 export interface HistoryResponse {
   type: "history_response";
-  sessionId: string;
+  conversationId: string;
   messages: Array<{
     id?: string; // Database message ID (for matching surfaces)
     role: string;
@@ -318,7 +313,7 @@ export interface HistoryResponse {
 export interface UndoComplete {
   type: "undo_complete";
   removedCount: number;
-  sessionId?: string;
+  conversationId?: string;
 }
 
 export interface UsageUpdate {
@@ -352,7 +347,7 @@ export interface ContextCompacted {
   summaryModel: string;
 }
 
-export type SessionErrorCode =
+export type ConversationErrorCode =
   | "PROVIDER_NETWORK"
   | "PROVIDER_RATE_LIMIT"
   | "PROVIDER_API"
@@ -360,15 +355,15 @@ export type SessionErrorCode =
   | "PROVIDER_ORDERING"
   | "PROVIDER_WEB_SEARCH"
   | "CONTEXT_TOO_LARGE"
-  | "SESSION_ABORTED"
-  | "SESSION_PROCESSING_FAILED"
+  | "CONVERSATION_ABORTED"
+  | "CONVERSATION_PROCESSING_FAILED"
   | "REGENERATE_FAILED"
   | "UNKNOWN";
 
-export interface SessionErrorMessage {
-  type: "session_error";
-  sessionId: string;
-  code: SessionErrorCode;
+export interface ConversationErrorMessage {
+  type: "conversation_error";
+  conversationId: string;
+  code: ConversationErrorCode;
   userMessage: string;
   retryable: boolean;
   debugDetails?: string;
@@ -376,9 +371,9 @@ export interface SessionErrorMessage {
   errorCategory?: string;
 }
 
-/** Server push — broadcast when a schedule creates a conversation, so the client can show it as a chat thread. */
-export interface ScheduleThreadCreated {
-  type: "schedule_thread_created";
+/** Server push — broadcast when a schedule creates a conversation. */
+export interface ScheduleConversationCreated {
+  type: "schedule_conversation_created";
   conversationId: string;
   scheduleJobId: string;
   title: string;
@@ -386,7 +381,7 @@ export interface ScheduleThreadCreated {
 
 // --- Domain-level union aliases (consumed by the barrel file) ---
 
-export type _SessionsClientMessages =
+export type _ConversationsClientMessages =
   | AuthMessage
   | PingMessage
   | CancelRequest
@@ -395,16 +390,15 @@ export type _SessionsClientMessages =
   | ModelSetRequest
   | ImageGenModelSetRequest
   | UndoRequest
-  | RegenerateRequest
   | UsageRequest
-  | SessionListRequest
-  | SessionCreateRequest
-  | SessionSwitchRequest
-  | SessionRenameRequest
-  | SessionsClearRequest
-  | ReorderThreadsRequest;
-
-export type _SessionsServerMessages =
+  | ConversationListRequest
+  | ConversationCreateRequest
+  | ConversationSwitchRequest
+  | ConversationRenameRequest
+  | ConversationsClearRequest
+  | ReorderConversationsRequest;
+
+export type _ConversationsServerMessages =
   | AuthResult
   | PongMessage
   | DaemonStatusMessage
@@ -416,11 +410,11 @@ export type _SessionsServerMessages =
   | UsageUpdate
   | UsageResponse
   | ContextCompacted
-  | SessionErrorMessage
-  | SessionInfo
-  | SessionTitleUpdated
-  | SessionListResponse
-  | SessionsClearResponse
+  | ConversationErrorMessage
+  | ConversationInfo
+  | ConversationTitleUpdated
+  | ConversationListResponse
+  | ConversationsClearResponse
   | ConversationSearchResponse
   | MessageContentResponse
-  | ScheduleThreadCreated;
+  | ScheduleConversationCreated;

package/src/daemon/message-types/documents.ts

@@ -4,7 +4,7 @@
 
 export interface DocumentEditorShow {
   type: "document_editor_show";
-  sessionId: string;
+  conversationId: string;
   surfaceId: string;
   title: string;
   initialContent: string;
@@ -12,7 +12,7 @@ export interface DocumentEditorShow {
 
 export interface DocumentEditorUpdate {
   type: "document_editor_update";
-  sessionId: string;
+  conversationId: string;
   surfaceId: string;
   markdown: string;
   mode: string;

package/src/daemon/message-types/host-bash.ts

@@ -7,10 +7,12 @@
 export interface HostBashRequest {
   type: "host_bash_request";
   requestId: string;
-  sessionId: string;
+  conversationId: string;
   command: string;
   working_dir?: string;
   timeout_seconds?: number;
+  /** Extra environment variables to inject into the subprocess (e.g. VELLUM_UNTRUSTED_SHELL). */
+  env?: Record<string, string>;
 }
 
 // --- Domain-level union aliases (consumed by the barrel file) ---

package/src/daemon/message-types/host-cu.ts

@@ -7,7 +7,7 @@
 export interface HostCuRequest {
   type: "host_cu_request";
   requestId: string;
-  sessionId: string;
+  conversationId: string;
   toolName: string; // "computer_use_click", "computer_use_type_text", etc.
   input: Record<string, unknown>;
   stepNumber: number;

package/src/daemon/message-types/host-file.ts

@@ -7,7 +7,7 @@
 export interface HostFileReadRequest {
   type: "host_file_request";
   requestId: string;
-  sessionId: string;
+  conversationId: string;
   operation: "read";
   path: string;
   offset?: number;
@@ -17,7 +17,7 @@ export interface HostFileReadRequest {
 export interface HostFileWriteRequest {
   type: "host_file_request";
   requestId: string;
-  sessionId: string;
+  conversationId: string;
   operation: "write";
   path: string;
   content: string;
@@ -26,7 +26,7 @@ export interface HostFileWriteRequest {
 export interface HostFileEditRequest {
   type: "host_file_request";
   requestId: string;
-  sessionId: string;
+  conversationId: string;
   operation: "edit";
   path: string;
   old_string: string;

package/src/daemon/message-types/integrations.ts

@@ -45,7 +45,7 @@ export interface ChannelVerificationSessionRequest {
     | "revoke"
     | "resend_session";
   channel?: ChannelId; // Defaults to 'telegram'
-  sessionId?: string;
+  conversationId?: string;
   rebind?: boolean; // When true, allows creating a challenge even if a binding already exists
   /** E.164 phone number for phone, Telegram handle/chat-id. Used by outbound actions. */
   destination?: string;
@@ -155,7 +155,7 @@ export interface ChannelVerificationSessionResponse {
   error?: string;
   /** Human-readable error detail (e.g. for already_bound failures). */
   message?: string;
-  /** Session ID for outbound verification flows. */
+  /** Conversation ID for outbound verification flows. */
   verificationSessionId?: string;
   /** Epoch ms when the verification session expires. */
   expiresAt?: number;

package/src/daemon/message-types/messages.ts

@@ -7,7 +7,7 @@ import type { CommandIntent, UserMessageAttachment } from "./shared.js";
 
 export interface UserMessage {
   type: "user_message";
-  sessionId: string;
+  conversationId: string;
   content?: string;
   attachments?: UserMessageAttachment[];
   activeSurfaceId?: string;
@@ -33,7 +33,7 @@ export interface ConfirmationResponse {
   decision:
     | "allow"
     | "allow_10m"
-    | "allow_thread"
+    | "allow_conversation"
     | "always_allow"
     | "always_allow_high_risk"
     | "deny"
@@ -52,7 +52,7 @@ export interface SecretResponse {
 
 export interface SuggestionRequest {
   type: "suggestion_request";
-  sessionId: string;
+  conversationId: string;
   requestId: string;
 }
 
@@ -61,13 +61,13 @@ export interface SuggestionRequest {
 export interface UserMessageEcho {
   type: "user_message_echo";
   text: string;
-  sessionId?: string;
+  conversationId?: string;
 }
 
 export interface AssistantTextDelta {
   type: "assistant_text_delta";
   text: string;
-  sessionId?: string;
+  conversationId?: string;
 }
 
 export interface AssistantThinkingDelta {
@@ -79,7 +79,7 @@ export interface ToolUseStart {
   type: "tool_use_start";
   toolName: string;
   input: Record<string, unknown>;
-  sessionId?: string;
+  conversationId?: string;
   /** The tool_use block ID for client-side correlation. */
   toolUseId?: string;
 }
@@ -87,7 +87,7 @@ export interface ToolUseStart {
 export interface ToolOutputChunk {
   type: "tool_output_chunk";
   chunk: string;
-  sessionId?: string;
+  conversationId?: string;
   toolUseId?: string;
   subType?: "tool_start" | "tool_complete" | "status";
   subToolName?: string;
@@ -100,14 +100,14 @@ export interface ToolUsePreviewStart {
   type: "tool_use_preview_start";
   toolUseId: string;
   toolName: string;
-  sessionId?: string;
+  conversationId?: string;
 }
 
 export interface ToolInputDelta {
   type: "tool_input_delta";
   toolName: string;
   content: string;
-  sessionId?: string;
+  conversationId?: string;
   /** The tool_use block ID for client-side correlation. */
   toolUseId?: string;
 }
@@ -124,7 +124,7 @@ export interface ToolResult {
     isNewFile: boolean;
   };
   status?: string;
-  sessionId?: string;
+  conversationId?: string;
   /** Base64-encoded image data extracted from contentBlocks (e.g. browser_screenshot). */
   imageData?: string;
   /** The tool_use block ID for client-side correlation. */
@@ -151,11 +151,11 @@ export interface ConfirmationRequest {
     isNewFile: boolean;
   };
   sandboxed?: boolean;
-  sessionId?: string;
+  conversationId?: string;
   /** When false, the client should hide "always allow" / trust-rule persistence affordances. */
   persistentDecisionsAllowed?: boolean;
-  /** Which temporary approval options the client should render (e.g. "Allow for 10 minutes", "Allow for this thread"). */
-  temporaryOptionsAvailable?: Array<"allow_10m" | "allow_thread">;
+  /** Which temporary approval options the client should render (e.g. "Allow for 10 minutes", "Allow for this conversation"). */
+  temporaryOptionsAvailable?: Array<"allow_10m" | "allow_conversation">;
   /** The tool_use block ID for client-side correlation with specific tool calls. */
   toolUseId?: string;
 }
@@ -168,7 +168,7 @@ export interface SecretRequest {
   label: string;
   description?: string;
   placeholder?: string;
-  sessionId?: string;
+  conversationId?: string;
   /** Intended purpose of the credential (displayed to user). */
   purpose?: string;
   /** Tools allowed to use this credential. */
@@ -181,7 +181,7 @@ export interface SecretRequest {
 
 export interface MessageComplete {
   type: "message_complete";
-  sessionId?: string;
+  conversationId?: string;
   attachments?: UserMessageAttachment[];
   /** Database ID of the persisted assistant message, if any. */
   messageId?: string;
@@ -203,14 +203,14 @@ export interface SecretDetected {
 
 export interface MessageQueued {
   type: "message_queued";
-  sessionId: string;
+  conversationId: string;
   requestId: string;
   position: number;
 }
 
 export interface MessageDequeued {
   type: "message_dequeued";
-  sessionId: string;
+  conversationId: string;
   requestId: string;
 }
 
@@ -223,7 +223,7 @@ export interface MessageDequeued {
  */
 export interface MessageRequestComplete {
   type: "message_request_complete";
-  sessionId: string;
+  conversationId: string;
   requestId: string;
   /** True when an existing turn is still running after this request is finalized. */
   runStillActive?: boolean;
@@ -231,7 +231,7 @@ export interface MessageRequestComplete {
 
 export interface MessageQueuedDeleted {
   type: "message_queued_deleted";
-  sessionId: string;
+  conversationId: string;
   requestId: string;
 }
 
@@ -250,7 +250,7 @@ export interface SuggestionResponse {
  */
 export interface ConfirmationStateChanged {
   type: "confirmation_state_changed";
-  sessionId: string;
+  conversationId: string;
   requestId: string;
   state: "pending" | "approved" | "denied" | "timed_out" | "resolved_stale";
   source: "button" | "inline_nl" | "auto_deny" | "timeout" | "system";
@@ -265,12 +265,12 @@ export interface ConfirmationStateChanged {
 /**
  * Server-side assistant activity lifecycle for thinking indicator placement.
  *
- * `activityVersion` is monotonically increasing per session. Clients must
+ * `activityVersion` is monotonically increasing per conversation. Clients must
  * ignore events with a version older than their current known version.
  */
 export interface AssistantActivityState {
   type: "assistant_activity_state";
-  sessionId: string;
+  conversationId: string;
   activityVersion: number;
   phase:
     | "idle"
@@ -320,7 +320,7 @@ export type TraceEventKind =
 export interface TraceEvent {
   type: "trace_event";
   eventId: string;
-  sessionId: string;
+  conversationId: string;
   requestId?: string;
   timestampMs: number;
   sequence: number;

package/src/daemon/message-types/notifications.ts

@@ -16,14 +16,14 @@ export interface NotificationIntent {
   targetGuardianPrincipalId?: string;
 }
 
-/** Server push — broadcast when a notification creates a new vellum conversation thread. */
-export interface NotificationThreadCreated {
-  type: "notification_thread_created";
+/** Server push — broadcast when a notification creates a new vellum conversation. */
+export interface NotificationConversationCreated {
+  type: "notification_conversation_created";
   conversationId: string;
   title: string;
   sourceEventName: string;
   /**
-   * When set, this thread was created for a guardian-sensitive notification
+   * When set, this conversation was created for a guardian-sensitive notification
    * and should only be surfaced by clients bound to this guardian identity.
    */
   targetGuardianPrincipalId?: string;
@@ -73,4 +73,4 @@ export type _NotificationsClientMessages =
 
 export type _NotificationsServerMessages =
   | NotificationIntent
-  | NotificationThreadCreated;
+  | NotificationConversationCreated;

package/src/daemon/message-types/settings.ts

@@ -2,7 +2,7 @@
 
 // === Client → Server ===
 
-/** Request from a session or client to change the voice activation key. */
+/** Request from a conversation or client to change the voice activation key. */
 export interface VoiceConfigUpdateRequest {
   type: "voice_config_update";
   /** The desired activation key (enum value or natural-language name). */

package/src/daemon/message-types/shared.ts

@@ -1,11 +1,11 @@
 // Shared types used across multiple message domains.
 
-export type ThreadType = "standard" | "private";
+export type ConversationType = "standard" | "private";
 
 /** Runtime normalizer — collapses unknown/legacy DB values to 'standard'. */
-export function normalizeThreadType(
+export function normalizeConversationType(
   raw: string | null | undefined,
-): ThreadType {
+): ConversationType {
   return raw === "private" ? "private" : "standard";
 }
 
@@ -41,4 +41,6 @@ export interface UserMessageAttachment {
   thumbnailData?: string;
   /** Absolute path to the local file on disk. Present for file-backed attachments (e.g. recordings). */
   filePath?: string;
+  /** True when the attachment is file-backed and clients should hydrate via the /content endpoint. */
+  fileBacked?: boolean;
 }

package/src/daemon/message-types/skills.ts

@@ -71,8 +71,6 @@ export interface SkillsCreateRequest {
   description: string;
   emoji?: string;
   bodyMarkdown: string;
-  userInvocable?: boolean;
-  disableModelInvocation?: boolean;
   overwrite?: boolean;
 }
 
@@ -87,17 +85,10 @@ export interface SkillsListResponse {
     emoji?: string;
     homepage?: string;
     source: "bundled" | "managed" | "workspace" | "clawhub" | "extra";
-    state: "enabled" | "disabled" | "available";
-    degraded: boolean;
-    missingRequirements?: {
-      bins?: string[];
-      env?: string[];
-      permissions?: string[];
-    };
+    state: "enabled" | "disabled";
     installedVersion?: string;
     latestVersion?: string;
     updateAvailable: boolean;
-    userInvocable: boolean;
     clawhub?: {
       author: string;
       stars: number;