types.ts

/**
 * Cursor Hook Payload Types
 * Based on Cursor 1.7+ hooks system
 */

// Base payload fields present in all hook events
export interface CursorBasePayload {
  conversation_id: string;
  generation_id: string;
  hook_event_name: string;
  workspace_roots: string[];
}

// beforeSubmitPrompt - fires when user submits a prompt
export interface BeforeSubmitPromptPayload extends CursorBasePayload {
  hook_event_name: "beforeSubmitPrompt";
  prompt: string;
}

// beforeShellExecution - fires before shell command runs
export interface BeforeShellExecutionPayload extends CursorBasePayload {
  hook_event_name: "beforeShellExecution";
  command: string;
  cwd: string;
}

// beforeMCPExecution - fires before MCP tool runs
export interface BeforeMCPExecutionPayload extends CursorBasePayload {
  hook_event_name: "beforeMCPExecution";
  tool_name: string;
  tool_input: Record<string, unknown>;
  url?: string;
  command?: string;
}

// beforeReadFile - fires before file is read
export interface BeforeReadFilePayload extends CursorBasePayload {
  hook_event_name: "beforeReadFile";
  file_path: string;
  content?: string;
  attachments?: Array<{
    type: string;
    file_path: string;
  }>;
}

// afterFileEdit - fires after a file is modified
export interface AfterFileEditPayload extends CursorBasePayload {
  hook_event_name: "afterFileEdit";
  file_path: string;
  edits: Array<{
    old_string: string;
    new_string: string;
  }>;
}

// stop - fires when agent session completes
export interface StopPayload extends CursorBasePayload {
  hook_event_name: "stop";
  status?: "completed" | "aborted" | "error";
  loop_count?: number;
}

// afterAgentResponse - fires after agent completes an assistant message
export interface AfterAgentResponsePayload extends CursorBasePayload {
  hook_event_name: "afterAgentResponse";
  text: string;
}

// Union type for all payloads
export type CursorHookPayload =
  | BeforeSubmitPromptPayload
  | BeforeShellExecutionPayload
  | BeforeMCPExecutionPayload
  | BeforeReadFilePayload
  | AfterFileEditPayload
  | AfterAgentResponsePayload
  | StopPayload;

// Hook response types
export interface HookResponseAllow {
  continue: true;
  permission: "allow";
}

export interface HookResponseDeny {
  continue: false;
  permission: "deny";
  userMessage?: string;
  agentMessage?: string;
}

export interface HookResponseAsk {
  continue: boolean;
  permission: "ask";
  userMessage?: string;
}

export type HookResponse = HookResponseAllow | HookResponseDeny | HookResponseAsk;

/**
 * OpenSync API Types
 */

export interface OpenSyncConfig {
  convexUrl: string;
  apiKey: string;
  autoSync?: boolean;
  syncToolCalls?: boolean;
  syncThinking?: boolean;
  debug?: boolean;
}

// Source identifier for this plugin
export const OPENSYNC_SOURCE = "cursor-sync" as const;
export type OpenSyncSource = typeof OPENSYNC_SOURCE;

export interface OpenSyncSession {
  id?: string;
  externalId: string;
  title: string;
  model?: string;
  source: OpenSyncSource;
  project?: string;
  directory?: string;
  gitBranch?: string;
  startedAt: number;
  endedAt?: number;
  totalTokens?: number;
  promptTokens?: number;
  completionTokens?: number;
  cost?: number;
  messageCount?: number;
  toolCallCount?: number;
}

// Message part types for structured content
// Backend requires: { type: string, content: any }
export interface MessagePart {
  type: string;
  content: string;
}

export interface OpenSyncMessage {
  id?: string;
  sessionExternalId: string;
  externalId: string;
  source: OpenSyncSource;
  role: "user" | "assistant" | "system" | "tool";
  textContent?: string;
  parts?: MessagePart[];
  timestamp: number;
  promptTokens?: number;
  completionTokens?: number;
  model?: string;
}

// Request types for OpenSync API
export type SyncSessionPayload = Omit<OpenSyncSession, "id">;
export type SyncMessagePayload = Omit<OpenSyncMessage, "id">;

export interface SyncSessionRequest {
  session: SyncSessionPayload;
}

export interface SyncMessageRequest {
  message: SyncMessagePayload;
}

export interface SyncBatchRequest {
  sessions?: SyncSessionPayload[];
  messages?: SyncMessagePayload[];
}

// Response types from OpenSync API (backend uses 'ok', we normalize to 'success')
export interface SyncSessionResponse {
  success?: boolean;
  ok?: boolean;
  sessionId?: string;
  error?: string;
}

export interface SyncMessageResponse {
  success?: boolean;
  ok?: boolean;
  messageId?: string;
  error?: string;
}

export interface SyncBatchResponse {
  success?: boolean;
  ok?: boolean;
  sessionIds?: string[];
  messageIds?: string[];
  error?: string;
}

/**
 * In-memory session state for accumulating data across hook events
 */
export interface SessionState {
  conversationId: string;
  generationId: string;
  prompt?: string;
  workspaceRoots: string[];
  startedAt: number;
  messages: Array<{
    role: "user" | "assistant" | "tool";
    content: string;
    timestamp: number;
    toolName?: string;
  }>;
  fileEdits: Array<{
    filePath: string;
    timestamp: number;
  }>;
  shellCommands: Array<{
    command: string;
    cwd: string;
    timestamp: number;
  }>;
  mcpCalls: Array<{
    toolName: string;
    toolInput: Record<string, unknown>;
    timestamp: number;
  }>;
}