@vellumai/assistant 0.3.5 → 0.3.6

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

@@ -0,0 +1,315 @@
+// Session lifecycle, auth, model config, and history types.
+
+import type { ChannelId } from '../../channels/types.js';
+import type { ThreadType } 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. */
+  offset?: number;
+  /** Maximum number of sessions to return. Defaults to 50. */
+  limit?: number;
+}
+
+/** Lightweight session transport metadata for channel identity and natural-language guidance. */
+export interface SessionTransportMetadata {
+  /** Logical channel identifier (e.g. "desktop", "telegram", "mobile"). */
+  channelId: ChannelId;
+  /** Optional natural-language hints for channel-specific UX behavior. */
+  hints?: string[];
+  /** Optional concise UX brief for this channel. */
+  uxBrief?: string;
+}
+
+export interface SessionCreateRequest {
+  type: 'session_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). */
+  preactivatedSkillIds?: string[];
+  /** If provided, automatically sent as the first user message after session creation. */
+  initialMessage?: string;
+}
+
+export interface SessionSwitchRequest {
+  type: 'session_switch';
+  sessionId: string;
+}
+
+export interface AuthMessage {
+  type: 'auth';
+  token: string;
+}
+
+export interface PingMessage {
+  type: 'ping';
+}
+
+export interface CancelRequest {
+  type: 'cancel';
+  sessionId?: string;
+}
+
+export interface DeleteQueuedMessage {
+  type: 'delete_queued_message';
+  sessionId: string;
+  requestId: string;
+}
+
+export interface ModelGetRequest {
+  type: 'model_get';
+}
+
+export interface ModelSetRequest {
+  type: 'model_set';
+  model: string;
+}
+
+export interface ImageGenModelSetRequest {
+  type: 'image_gen_model_set';
+  model: string;
+}
+
+export interface HistoryRequest {
+  type: 'history_request';
+  sessionId: string;
+}
+
+export interface UndoRequest {
+  type: 'undo';
+  sessionId: string;
+}
+
+export interface RegenerateRequest {
+  type: 'regenerate';
+  sessionId: string;
+}
+
+export interface UsageRequest {
+  type: 'usage_request';
+  sessionId: string;
+}
+
+export interface SandboxSetRequest {
+  type: 'sandbox_set';
+  enabled: boolean;
+}
+
+export interface SessionsClearRequest {
+  type: 'sessions_clear';
+}
+
+export interface ConversationSearchRequest {
+  type: 'conversation_search';
+  /** The search query string. */
+  query: string;
+  /** Maximum number of conversations to return. Defaults to 20. */
+  limit?: number;
+  /** Maximum number of matching messages to return per conversation. Defaults to 3. */
+  maxMessagesPerConversation?: number;
+}
+
+// === Server → Client ===
+
+export interface ConversationSearchMatchingMessage {
+  messageId: string;
+  role: string;
+  /** Plain-text excerpt around the match, truncated to ~200 chars. */
+  excerpt: string;
+  createdAt: number;
+}
+
+export interface ConversationSearchResultItem {
+  conversationId: string;
+  conversationTitle: string | null;
+  conversationUpdatedAt: number;
+  matchingMessages: ConversationSearchMatchingMessage[];
+}
+
+export interface ConversationSearchResponse {
+  type: 'conversation_search_response';
+  query: string;
+  results: ConversationSearchResultItem[];
+}
+
+export interface SessionInfo {
+  type: 'session_info';
+  sessionId: string;
+  title: string;
+  correlationId?: string;
+  threadType?: ThreadType;
+}
+
+export interface SessionTitleUpdated {
+  type: 'session_title_updated';
+  sessionId: string;
+  title: string;
+}
+
+/** Channel binding metadata exposed in session/conversation list APIs. */
+export interface ChannelBinding {
+  sourceChannel: ChannelId;
+  externalChatId: string;
+  externalUserId?: string | null;
+  displayName?: string | null;
+  username?: string | null;
+}
+
+export interface SessionListResponse {
+  type: 'session_list_response';
+  sessions: Array<{ id: string; title: string; updatedAt: number; threadType?: ThreadType; source?: string; channelBinding?: ChannelBinding; conversationOriginChannel?: ChannelId }>;
+  /** Whether more sessions exist beyond the returned page. */
+  hasMore?: boolean;
+}
+
+export interface SessionsClearResponse {
+  type: 'sessions_clear_response';
+  cleared: number;
+}
+
+export interface AuthResult {
+  type: 'auth_result';
+  success: boolean;
+  message?: string;
+}
+
+export interface PongMessage {
+  type: 'pong';
+}
+
+export interface DaemonStatusMessage {
+  type: 'daemon_status';
+  httpPort?: number;
+  version?: string;
+}
+
+export interface GenerationCancelled {
+  type: 'generation_cancelled';
+  sessionId?: string;
+}
+
+export interface GenerationHandoff {
+  type: 'generation_handoff';
+  sessionId: string;
+  requestId?: string;
+  queuedCount: number;
+  attachments?: UserMessageAttachment[];
+}
+
+export interface ModelInfo {
+  type: 'model_info';
+  model: string;
+  provider: string;
+  configuredProviders?: string[];
+}
+
+export interface HistoryResponseToolCall {
+  name: string;
+  input: Record<string, unknown>;
+  result?: string;
+  isError?: boolean;
+  /** Base64-encoded image data from tool contentBlocks (e.g. browser_screenshot). */
+  imageData?: string;
+}
+
+export interface HistoryResponseSurface {
+  surfaceId: string;
+  surfaceType: string;
+  title?: string;
+  data: Record<string, unknown>;
+  actions?: Array<{ id: string; label: string; style?: string }>;
+  display?: string;
+}
+
+export interface HistoryResponse {
+  type: 'history_response';
+  sessionId: string;
+  messages: Array<{
+    id?: string;  // Database message ID (for matching surfaces)
+    role: string;
+    text: string;
+    timestamp: number;
+    toolCalls?: HistoryResponseToolCall[];
+    /** True when tool_use blocks appeared before any text block in the original content. */
+    toolCallsBeforeText?: boolean;
+    attachments?: UserMessageAttachment[];
+    /** Text segments split by tool-call boundaries. Preserves interleaving order. */
+    textSegments?: string[];
+    /** Content block ordering using "text:N", "tool:N", "surface:N" encoding. */
+    contentOrder?: string[];
+    /** UI surfaces (widgets) embedded in the message. */
+    surfaces?: HistoryResponseSurface[];
+    /** Present when this message is a subagent lifecycle notification (completed/failed/aborted). */
+    subagentNotification?: {
+      subagentId: string;
+      label: string;
+      status: 'completed' | 'failed' | 'aborted';
+      error?: string;
+      conversationId?: string;
+    };
+  }>;
+}
+
+export interface UndoComplete {
+  type: 'undo_complete';
+  removedCount: number;
+  sessionId?: string;
+}
+
+export interface UsageUpdate {
+  type: 'usage_update';
+  inputTokens: number;
+  outputTokens: number;
+  totalInputTokens: number;
+  totalOutputTokens: number;
+  estimatedCost: number;
+  model: string;
+}
+
+export interface UsageResponse {
+  type: 'usage_response';
+  totalInputTokens: number;
+  totalOutputTokens: number;
+  estimatedCost: number;
+  model: string;
+}
+
+export interface ContextCompacted {
+  type: 'context_compacted';
+  previousEstimatedInputTokens: number;
+  estimatedInputTokens: number;
+  maxInputTokens: number;
+  thresholdTokens: number;
+  compactedMessages: number;
+  summaryCalls: number;
+  summaryInputTokens: number;
+  summaryOutputTokens: number;
+  summaryModel: string;
+}
+
+export type SessionErrorCode =
+  | 'PROVIDER_NETWORK'
+  | 'PROVIDER_RATE_LIMIT'
+  | 'PROVIDER_API'
+  | 'CONTEXT_TOO_LARGE'
+  | 'QUEUE_FULL'
+  | 'SESSION_ABORTED'
+  | 'SESSION_PROCESSING_FAILED'
+  | 'REGENERATE_FAILED'
+  | 'UNKNOWN';
+
+export interface SessionErrorMessage {
+  type: 'session_error';
+  sessionId: string;
+  code: SessionErrorCode;
+  userMessage: string;
+  retryable: boolean;
+  debugDetails?: string;
+}

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

@@ -0,0 +1,42 @@
+// Shared types used across multiple IPC domains.
+
+export type ThreadType = 'standard' | 'private';
+
+/** Runtime normalizer — collapses unknown/legacy DB values to 'standard'. */
+export function normalizeThreadType(raw: string | null | undefined): ThreadType {
+  return raw === 'private' ? 'private' : 'standard';
+}
+
+export interface IpcBlobRef {
+  id: string;
+  kind: 'ax_tree' | 'screenshot_jpeg';
+  encoding: 'utf8' | 'binary';
+  byteLength: number;
+  sha256?: string;
+}
+
+export interface UsageStats {
+  inputTokens: number;
+  outputTokens: number;
+  estimatedCost: number;
+}
+
+export interface DictationContext {
+  bundleIdentifier: string;
+  appName: string;
+  windowTitle: string;
+  selectedText?: string;
+  cursorInTextField: boolean;
+}
+
+export interface UserMessageAttachment {
+  id?: string;
+  filename: string;
+  mimeType: string;
+  data: string;
+  extractedText?: string;
+  /** Original file size in bytes. Present when data was omitted from history_response to reduce payload size. */
+  sizeBytes?: number;
+  /** Base64-encoded JPEG thumbnail. Generated server-side for video attachments. */
+  thumbnailData?: string;
+}

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

@@ -0,0 +1,120 @@
+// Skill management types.
+
+// === Client → Server ===
+
+export interface SkillsListRequest {
+  type: 'skills_list';
+}
+
+export interface SkillDetailRequest {
+  type: 'skill_detail';
+  skillId: string;
+}
+
+export interface SkillsEnableRequest {
+  type: 'skills_enable';
+  name: string;
+}
+
+export interface SkillsDisableRequest {
+  type: 'skills_disable';
+  name: string;
+}
+
+export interface SkillsConfigureRequest {
+  type: 'skills_configure';
+  name: string;
+  env?: Record<string, string>;
+  apiKey?: string;
+  config?: Record<string, unknown>;
+}
+
+export interface SkillsInstallRequest {
+  type: 'skills_install';
+  slug: string;
+  version?: string;
+}
+
+export interface SkillsUninstallRequest {
+  type: 'skills_uninstall';
+  name: string;
+}
+
+export interface SkillsUpdateRequest {
+  type: 'skills_update';
+  name: string;
+}
+
+export interface SkillsCheckUpdatesRequest {
+  type: 'skills_check_updates';
+}
+
+export interface SkillsSearchRequest {
+  type: 'skills_search';
+  query: string;
+}
+
+export interface SkillsInspectRequest {
+  type: 'skills_inspect';
+  slug: string;
+}
+
+// === Server → Client ===
+
+export interface SkillsListResponse {
+  type: 'skills_list_response';
+  skills: Array<{
+    id: string;
+    name: string;
+    description: string;
+    emoji?: string;
+    homepage?: string;
+    source: 'bundled' | 'managed' | 'workspace' | 'clawhub' | 'extra';
+    state: 'enabled' | 'disabled' | 'available';
+    degraded: boolean;
+    missingRequirements?: { bins?: string[]; env?: string[]; permissions?: string[] };
+    installedVersion?: string;
+    latestVersion?: string;
+    updateAvailable: boolean;
+    userInvocable: boolean;
+    clawhub?: { author: string; stars: number; installs: number; reports: number; publishedAt: string };
+  }>;
+}
+
+export interface SkillStateChanged {
+  type: 'skills_state_changed';
+  name: string;
+  state: 'enabled' | 'disabled' | 'installed' | 'uninstalled';
+}
+
+export interface SkillsOperationResponse {
+  type: 'skills_operation_response';
+  operation: string;
+  success: boolean;
+  error?: string;
+  data?: unknown;
+}
+
+export interface SkillDetailResponse {
+  type: 'skill_detail_response';
+  skillId: string;
+  body: string;
+  icon?: string;
+  error?: string;
+}
+
+export interface SkillsInspectResponse {
+  type: 'skills_inspect_response';
+  slug: string;
+  data?: {
+    skill: { slug: string; displayName: string; summary: string };
+    owner?: { handle: string; displayName: string; image?: string } | null;
+    stats?: { stars: number; installs: number; downloads: number; versions: number } | null;
+    createdAt?: number | null;
+    updatedAt?: number | null;
+    latestVersion?: { version: string; changelog?: string } | null;
+    files?: Array<{ path: string; size: number; contentType?: string }> | null;
+    skillMdContent?: string | null;
+  };
+  error?: string;
+}

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

@@ -0,0 +1,58 @@
+// Subagent lifecycle and communication types.
+
+import type { UsageStats } from './shared.js';
+
+// === Server → Client ===
+
+export interface SubagentSpawned {
+  type: 'subagent_spawned';
+  subagentId: string;
+  parentSessionId: string;
+  label: string;
+  objective: string;
+}
+
+export interface SubagentStatusChanged {
+  type: 'subagent_status_changed';
+  subagentId: string;
+  status: import('../../subagent/types.js').SubagentStatus;
+  error?: string;
+  usage?: UsageStats;
+}
+
+export interface SubagentDetailResponse {
+  type: 'subagent_detail_response';
+  subagentId: string;
+  objective?: string;
+  events: Array<{
+    type: string;
+    content: string;
+    toolName?: string;
+    isError?: boolean;
+  }>;
+}
+
+// === Client → Server ===
+
+export interface SubagentAbortRequest {
+  type: 'subagent_abort';
+  subagentId: string;
+}
+
+export interface SubagentStatusRequest {
+  type: 'subagent_status';
+  /** If omitted, returns all subagents for the session. */
+  subagentId?: string;
+}
+
+export interface SubagentMessageRequest {
+  type: 'subagent_message';
+  subagentId: string;
+  content: string;
+}
+
+export interface SubagentDetailRequest {
+  type: 'subagent_detail_request';
+  subagentId: string;
+  conversationId: string;
+}