@parall/sdk 1.12.0

package/src/types.ts

@@ -0,0 +1,1399 @@
+// ============================================================
+// Entity Types — mirror server data model
+// ============================================================
+
+export type UserType = 'human' | 'agent';
+export type UserStatus = 'active' | 'disabled';
+
+export interface User {
+  id: string;
+  type: UserType;
+  display_name: string;
+  avatar_url: string | null;
+  email: string | null;
+  phone: string | null;
+  status: UserStatus;
+  email_verified: boolean;
+  last_seen_at: string | null;
+  created_at: string;
+}
+
+export type ChatType = 'direct' | 'group';
+export type AgentRoutingMode = 'passive' | 'active' | 'smart';
+
+export interface Chat {
+  id: string;
+  type: ChatType;
+  org_id: string;
+  name: string | null;
+  avatar_url: string | null;
+  description: string | null;
+  agent_routing_mode: AgentRoutingMode;
+  last_message_at: string | null;
+  last_message_preview: string | null;
+  last_message_sender: string | null;
+  creator_id: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export type ChatMemberRole = 'owner' | 'admin' | 'member';
+
+export type NotificationLevel = 'all' | 'mentions_only' | 'none';
+
+// Push notification subscription
+export interface PushSubscribeRequest {
+  platform: 'web' | 'ios' | 'android';
+  token: string;
+  device_id?: string;
+}
+
+// Notification preferences
+export interface NotifPrefs {
+  dm?: boolean;
+  mention?: boolean;
+  task_assign?: boolean;
+}
+
+export interface NotificationPreferences {
+  scope: string;
+  prefs: NotifPrefs;
+  updated_at: string;
+}
+
+export interface ChatMember {
+  chat_id: string;
+  user_id: string;
+  role: ChatMemberRole;
+  notification_level: NotificationLevel;
+  pinned: boolean;
+  joined_at: string;
+  user?: User;
+}
+
+export type MessageType =
+  | 'text'
+  | 'file'
+  | 'tool_call'       // deprecated: use AgentStep
+  | 'tool_result'     // deprecated: use AgentStep
+  | 'approval_card'   // deprecated: use 'card' with card_type='approval'
+  | 'state_delta'     // deprecated: use AgentStep
+  | 'card'
+  | 'system';
+
+export const MENTION_ALL_USER_ID = 'all';
+
+export interface Mention {
+  user_id: string;
+  offset: number;
+  length: number;
+}
+
+export interface LinkPreview {
+  url: string;
+  title?: string;
+  image?: string;
+  description?: string;
+}
+
+export interface TextContent {
+  text: string;
+  format?: string;
+  mentions?: Mention[];
+  link_previews?: LinkPreview[];
+}
+
+export interface MediaContent {
+  attachment_id: string;
+  file_name: string;
+  file_size: number;
+  mime_type: string;
+  width?: number;
+  height?: number;
+  duration?: number;
+  caption?: string;
+}
+
+export interface ToolCallContent {
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+  status: string;
+  started_at: string;
+}
+
+export interface ToolResultContent {
+  tool_call_id: string;
+  tool_name: string;
+  status: string;
+  output: string;
+  duration_ms: number;
+  collapsible: boolean;
+}
+
+export interface ApprovalOption {
+  key: string;
+  label: string;
+  style: 'primary' | 'danger' | 'secondary';
+}
+
+export interface ApprovalCardContent {
+  approval_id: string;
+  title: string;
+  description: string;
+  action_type: string;
+  action_payload: Record<string, unknown>;
+  risk_level: string;
+  status: string;
+  options: ApprovalOption[];
+  expires_at: string;
+}
+
+// CardContent is the polymorphic content for 'card' message type.
+// card_type discriminates the data payload.
+export type CardContent =
+  | { card_type: 'approval'; data: ApprovalCardContent; approval_id?: string }
+  | { card_type: string; data: Record<string, unknown>; approval_id?: string };
+
+export type AgentState = 'thinking' | 'tool_calling' | 'streaming' | 'waiting_approval' | 'completed' | 'error';
+
+export interface StateDeltaContent {
+  state: AgentState;
+  text: string;
+  progress: number;
+  collapsible: boolean;
+}
+
+export type SystemEvent =
+  | 'chat_created'
+  | 'member_added'
+  | 'member_removed'
+  | 'member_role_changed'
+  | 'chat_renamed'
+  | 'chat_avatar_changed';
+
+export interface SystemContent {
+  event: SystemEvent;
+  actor_id: string;
+  actor_name: string;
+  target_id?: string;
+  target_name?: string;
+}
+
+export type MessageContent =
+  | TextContent
+  | MediaContent
+  | ToolCallContent
+  | ToolResultContent
+  | ApprovalCardContent
+  | StateDeltaContent
+  | SystemContent
+  | IssueProjectionContent
+  | CardContent;
+
+export interface Message {
+  id: string;
+  chat_id: string;
+  sender_id: string;
+  sender?: User;
+  thread_root_id: string | null;
+  message_type: MessageType;
+  content: MessageContent;
+  version: number;
+  reply_count: number;
+  edited_at: string | null;
+  deleted_at: string | null;
+  created_at: string;
+  idempotency_key: string | null;
+  agent_step_id?: string | null;
+  hints?: MessageHints | null;
+}
+
+export interface Attachment {
+  id: string;
+  org_id: string;
+  uploader_id: string;
+  file_name: string;
+  file_size: number;
+  mime_type: string;
+  storage_key: string;
+  status: 'pending' | 'uploaded';
+  width: number | null;
+  height: number | null;
+  thumbnail_key: string | null;
+  created_at: string;
+}
+
+export type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
+
+export interface Approval {
+  id: string;
+  message_id: string;
+  chat_id: string;
+  requester_id: string;
+  status: ApprovalStatus;
+  action_type: string;
+  action_payload: Record<string, unknown>;
+  decided_by: string | null;
+  decided_at: string | null;
+  expires_at: string | null;
+  created_at: string;
+}
+
+export type OrgMemberRole = 'owner' | 'admin' | 'member';
+
+export interface Organization {
+  id: string;
+  name: string;
+  avatar_url: string | null;
+  is_personal: boolean;
+  created_at: string;
+}
+
+export interface OrgMember {
+  org_id: string;
+  user_id: string;
+  role: OrgMemberRole;
+  joined_at: string;
+  user?: User;
+}
+
+// Invitation
+
+export type InvitationStatus = 'pending' | 'accepted' | 'declined';
+
+export interface OrgInvitation {
+  id: string;
+  org_id: string;
+  email: string;
+  role: OrgMemberRole;
+  status: InvitationStatus;
+  inviter_id: string;
+  expires_at: string;
+  accepted_at: string | null;
+  created_at: string;
+  inviter?: User;
+  org?: Organization;
+}
+
+export interface InvitationPublicInfo {
+  id: string;
+  org_name: string;
+  org_avatar_url: string | null;
+  inviter_name: string;
+  email: string;
+  role: OrgMemberRole;
+  expires_at: string;
+}
+
+export interface CreateInvitationRequest {
+  email: string;
+  role?: OrgMemberRole;
+}
+
+export interface ApiKey {
+  id: string;
+  key: string;
+  agent_id: string;
+  created_at: string;
+}
+
+export interface CreateAgentResponse {
+  user: User;
+  api_key: string;
+  machine?: Machine;
+}
+
+export interface UnreadCount {
+  chat_id: string;
+  unread_count: number;
+  last_read_message_id: string;
+  last_read_at: string;
+}
+
+// ============================================================
+// API Response Types
+// ============================================================
+
+export interface PaginatedResponse<T> {
+  data: T[];
+  has_more: boolean;
+  next_cursor?: string;
+}
+
+export interface ErrorResponse {
+  error: string;
+  code: string;
+  details?: Record<string, unknown>;
+}
+
+export interface AuthTokens {
+  access_token: string;
+  refresh_token: string;
+  user: User;
+}
+
+export interface RegisterResponse {
+  email: string;
+}
+
+export interface CheckEmailResponse {
+  exists: boolean;
+}
+
+export interface PresignResponse {
+  upload_url: string;
+  attachment_id: string;
+  expires_in: number;
+}
+
+export interface WsTicketResponse {
+  ticket: string;
+  expires_at: string;
+  ws_url: string;
+}
+
+// ============================================================
+// API Request Types
+// ============================================================
+
+export interface RegisterRequest {
+  email: string;
+  password: string;
+  display_name: string;
+}
+
+export interface LoginRequest {
+  email: string;
+  password: string;
+}
+
+export interface CreateChatRequest {
+  type: ChatType;
+  org_id: string;
+  name?: string;
+  description?: string;
+  member_ids: string[];
+  agent_routing_mode?: AgentRoutingMode;
+}
+
+export interface MessageHints {
+  no_reply?: boolean;
+}
+
+export interface SendMessageRequest {
+  message_type: MessageType;
+  content: MessageContent;
+  thread_root_id?: string;
+  idempotency_key?: string;
+  agent_step_id?: string;
+  hints?: MessageHints;
+}
+
+export interface SendDirectMessageRequest {
+  user_id: string;
+  message_type: MessageType;
+  content: MessageContent;
+  thread_root_id?: string;
+  idempotency_key?: string;
+  agent_step_id?: string;
+  hints?: MessageHints;
+}
+
+export interface DirectMessageResponse {
+  chat: Chat;
+  message: Message;
+}
+
+export interface PatchMessageRequest {
+  version: number;
+  ops: JsonPatchOp[];
+}
+
+export interface JsonPatchOp {
+  op: 'replace' | 'add';
+  path: string;
+  value: unknown;
+}
+
+export interface WorkspaceFiles {
+  soul_md?: string;
+  agents_md?: string;
+  tools_md?: string;
+}
+
+export interface CreateAgentRequest {
+  display_name: string;
+  agent_provider?: string;
+  agent_endpoint?: string;
+  agent_model?: string;
+  agent_permissions?: string[];
+  runtime_type?: string; // "openclaw" | "claude-code" | "codex"; default "openclaw"
+  machine_type?: string;
+  machine_label?: string;
+  workspace?: WorkspaceFiles;
+}
+
+// ---- Machine types ----
+
+export type MachineStatus = 'provisioning' | 'starting' | 'running' | 'stopped' | 'error' | 'terminated';
+
+export interface Machine {
+  id: string;
+  org_id: string;
+  label: string;
+  status: MachineStatus;
+  compute_provider: string;
+  runtime_type: string;
+  region: string | null;
+  created_by: string;
+  created_at: string;
+  updated_at: string;
+}
+
+// ---- Agent enriched types ----
+
+export interface RunConfig {
+  intermediate_text?: 'step_only' | 'chat';
+}
+
+export interface AgentProfile {
+  user_id: string;
+  provider: string | null;
+  endpoint: string | null;
+  model: string | null;
+  permissions: string[];
+  machine_id: string | null;
+  runtime_type: string;
+  run_config?: RunConfig;
+  created_by: string;
+  created_at: string;
+}
+
+export interface AgentPresence {
+  online: boolean;
+  status: string; // "online" | "busy" | "error" | "offline"
+  session_id?: string;
+  telemetry?: Record<string, unknown>;
+}
+
+export interface AgentWithRuntime extends User {
+  agent_profile?: AgentProfile | null;
+  machine?: Machine | null;
+  presence?: AgentPresence | null;
+}
+
+export interface PresignUploadRequest {
+  file_name: string;
+  file_size: number;
+  mime_type: string;
+}
+
+export interface FileUrlResponse {
+  url: string;
+  expires_in: number;
+  width?: number;
+  height?: number;
+}
+
+// ============================================================
+// Task Types
+// ============================================================
+
+export type TaskStatus = 'todo' | 'in_progress' | 'in_review' | 'done' | 'canceled';
+export type TaskPriority = 'high' | 'normal' | 'low';
+export type TaskRelationTargetType = 'task' | 'message' | 'chat' | 'agent_session';
+export type TaskRelationType = 'blocks' | 'related' | 'duplicate' | 'source' | 'reference' | 'discussion' | 'execution';
+
+export interface Task {
+  id: string;
+  org_id: string;
+  title: string;
+  description: string | null;
+  status: TaskStatus;
+  priority: TaskPriority;
+  assignee_id: string | null;
+  creator_id: string;
+  parent_id: string | null;
+  project_id: string | null;
+  seq_number: number | null;
+  identifier: string | null;
+  sort_order: number;
+  assignee?: User;
+  creator?: User;
+  created_at: string;
+  updated_at: string;
+  started_at: string | null;
+  completed_at: string | null;
+  canceled_at: string | null;
+}
+
+/** Content shape for system messages that project issue operations into chat. */
+export interface IssueProjectionContent {
+  event: 'issue_created' | 'issue_status_changed' | 'issue_assigned';
+  actor_id: string;
+  actor_name: string;
+  issue_id: string;
+  identifier: string;
+  title: string;
+  old_status?: string;
+  new_status?: string;
+  assignee_id?: string;
+  assignee_name?: string;
+}
+
+export interface TaskRelation {
+  id: string;
+  task_id: string;
+  target_type: TaskRelationTargetType;
+  target_id: string;
+  relation_type: TaskRelationType;
+  created_by: string;
+  created_at: string;
+}
+
+export interface CreateTaskRequest {
+  title: string;
+  description?: string;
+  status?: TaskStatus;
+  priority?: TaskPriority;
+  assignee_id?: string;
+  parent_id?: string;
+  project_id?: string;
+  source_chat_id?: string;
+  sort_order?: number;
+}
+
+export interface UpdateTaskRequest {
+  title?: string;
+  description?: string;
+  status?: TaskStatus;
+  priority?: TaskPriority;
+  assignee_id?: string | null;
+  parent_id?: string | null;
+  project_id?: string | null;
+  sort_order?: number;
+}
+
+export interface CreateTaskRelationRequest {
+  target_type: TaskRelationTargetType;
+  target_id: string;
+  relation_type: TaskRelationType;
+}
+
+// ============================================================
+// Project Types
+// ============================================================
+
+export type ProjectStatus = 'active' | 'paused' | 'completed' | 'archived';
+
+export interface Project {
+  id: string;
+  org_id: string;
+  name: string;
+  key: string;
+  description: string | null;
+  lead_id: string | null;
+  status: ProjectStatus;
+  color: string | null;
+  sort_order: number;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface CreateProjectRequest {
+  name: string;
+  key?: string;
+  description?: string;
+  lead_id?: string;
+  color?: string;
+}
+
+export interface UpdateProjectRequest {
+  name?: string;
+  key?: string;
+  description?: string | null;
+  lead_id?: string | null;
+  status?: ProjectStatus;
+  color?: string | null;
+  sort_order?: number;
+}
+
+// ============================================================
+// Wiki Types
+// ============================================================
+
+export type WikiChangesetStatus =
+  | 'draft'
+  | 'proposed'
+  | 'approval_pending'
+  | 'approved'
+  | 'rejected'
+  | 'merged'
+  | 'closed'
+  | 'superseded';
+
+export interface Wiki {
+  id: string;
+  org_id: string;
+  slug: string;
+  name: string;
+  repo_owner: string;
+  repo_name: string;
+  default_branch: string;
+  created_by: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface WikiFileChange {
+  path: string;
+  action: 'create' | 'update' | 'delete';
+}
+
+export interface WikiChangeset {
+  id: string;
+  wiki_id: string;
+  title: string;
+  message: string | null;
+  status: WikiChangesetStatus;
+  merge_commit: string | null;
+  file_changes: WikiFileChange[];
+  changed_paths: string[];
+  approval_id: string | null;
+  source_chat_id: string | null;
+  source_message_id: string | null;
+  source_run_id: string | null;
+  last_error: string | null;
+  created_by: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface WikiTreeEntry {
+  name: string;
+  path: string;
+  type: 'tree' | 'blob';
+  size?: number;
+}
+
+export interface WikiTreeResponse {
+  data: WikiTreeEntry[];
+  path: string;
+}
+
+export interface WikiFileManifestEntry {
+  path: string;
+  sha256: string;
+  size: number;
+  version: number;
+  updated_at: string;
+}
+
+export interface WikiNodeSection {
+  wiki_id: string;
+  wiki_slug: string;
+  wiki_name: string;
+  node_id: string;
+  path: string;
+  title: string;
+  heading_path?: string[];
+  section_path: string;
+  level: number;
+  start_line: number;
+  end_line: number;
+  content: string;
+}
+
+export interface WikiNodeSectionArtifact {
+  version: number;
+  generated_at: string;
+  wiki_id: string;
+  wiki_slug: string;
+  wiki_name: string;
+  ref: string;
+  manifest_digest: string;
+  file_count: number;
+  nodes: WikiNodeSection[];
+}
+
+export interface WikiSearchResult {
+  wiki_id: string;
+  wiki_slug: string;
+  wiki_name: string;
+  node_id: string;
+  path: string;
+  title: string;
+  heading_path?: string[];
+  section_path: string;
+  level: number;
+  start_line: number;
+  end_line: number;
+  score: number;
+  snippet: string;
+}
+
+export interface WikiSearchResponse {
+  wiki_id: string;
+  wiki_slug: string;
+  wiki_name: string;
+  query: string;
+  ref: string;
+  results: WikiSearchResult[];
+}
+
+export interface WikiPageIndexEntry {
+  path: string;
+  title: string;
+  top_headings: string[];
+  size_bytes: number;
+  section_count: number;
+}
+
+export interface WikiPageIndex {
+  wiki_id: string;
+  wiki_slug: string;
+  wiki_name: string;
+  ref: string;
+  generated_at: string;
+  page_count: number;
+  pages: WikiPageIndexEntry[];
+}
+
+export interface WikiFileRef {
+  source_path: string;
+  uri: string;
+  context?: string;
+  prefix: string;
+  entity_id: string;
+  target_path?: string;
+  fragment?: string;
+  line: number;
+}
+
+export interface WikiRefsResponse {
+  wiki_id: string;
+  wiki_slug: string;
+  wiki_name: string;
+  ref: string;
+  total: number;
+  refs: WikiFileRef[];
+}
+
+export interface WikiBrokenRef extends WikiFileRef {
+  reason: string;
+}
+
+export interface WikiRefsCheckResponse {
+  wiki_id: string;
+  wiki_slug: string;
+  wiki_name: string;
+  ref: string;
+  total: number;
+  broken: WikiBrokenRef[];
+}
+
+export interface WikiDiffFile {
+  path: string;
+  action?: string; // "create" | "update" | "delete"
+  additions: number;
+  deletions: number;
+}
+
+export interface WikiDiff {
+  patch: string;
+  files: WikiDiffFile[];
+}
+
+export interface CreateWikiRequest {
+  slug: string;
+  name: string;
+  default_branch?: string;
+}
+
+export interface CreateWikiChangesetRequest {
+  title: string;
+  message?: string;
+  file_changes: Array<{
+    path: string;
+    action: 'create' | 'update' | 'delete';
+    content_base64?: string;
+    base_version?: number;
+  }>;
+  source_chat_id?: string;
+  source_message_id?: string;
+  source_run_id?: string;
+}
+
+export interface UpdateWikiChangesetRequest {
+  title?: string;
+  message?: string;
+  file_changes?: Array<{
+    path: string;
+    action: 'create' | 'update' | 'delete';
+    content_base64?: string;
+    base_version?: number;
+  }>;
+}
+
+export interface WikiCommit {
+  sha: string;
+  title: string;
+  message: string;
+  author_name: string;
+  author_email: string;
+  date: string;
+  changeset_id?: string;
+}
+
+export interface WikiBlameEntry {
+  sha: string;
+  lines: string[];
+  message: string;
+  author: string;
+  date: string;
+  changeset_id?: string;
+}
+
+// ============================================================
+// Wiki Path Scopes (AFCS ACL)
+// ============================================================
+
+export interface WikiPathScope {
+  id: string;
+  wiki_id: string;
+  path: string;
+  readers: unknown;
+  maintainers: unknown;
+  admins: unknown;
+  created_by: string;
+  created_at: string;
+}
+
+export interface CreateWikiPathScopeRequest {
+  path: string;
+  readers?: unknown;
+  maintainers?: unknown;
+  admins?: unknown;
+}
+
+export interface WikiAccessStatus {
+  path: string;
+  read: boolean;
+  maintain: boolean;
+  admin: boolean;
+}
+
+export interface CreateWikiAccessRequest {
+  path: string;
+  reason: string;
+}
+
+// ============================================================
+// Wiki Operations (Audit Log)
+// ============================================================
+
+export interface WikiOperation {
+  id: string;
+  wiki_id: string;
+  actor_id: string;
+  op_type: string;
+  changeset_id?: string | null;
+  payload: Record<string, unknown>;
+  parent_op_id?: string | null;
+  created_at: string;
+}
+
+export interface WikiOperationsResponse {
+  data: WikiOperation[];
+  has_more: boolean;
+}
+
+// ============================================================
+// Wiki Blob
+// ============================================================
+
+export interface WikiBlob {
+  path: string;
+  content: string;
+  size: number;
+  encoding: string;
+  sha256?: string;
+}
+
+// ============================================================
+// WebSocket Event Types
+// ============================================================
+
+export interface WsFrame<T = unknown> {
+  type: string;
+  seq?: number;
+  data: T;
+}
+
+export interface HelloData {
+  conn_id: string;
+  user_id: string;
+  session_id?: string; // agent-only: server-assigned session ID
+  server_time: string;
+  heartbeat_interval: number;
+}
+
+export interface MessageNewData {
+  id: string;
+  chat_id: string;
+  sender_id: string;
+  sender?: User;
+  thread_root_id: string | null;
+  message_type: MessageType;
+  content: MessageContent;
+  version: number;
+  created_at: string;
+  reply_count?: number;
+  edited_at?: string | null;
+  deleted_at?: string | null;
+  idempotency_key?: string | null;
+  agent_step_id?: string | null;
+  hints?: MessageHints | null;
+}
+
+export interface MessagePatchData {
+  message_id: string;
+  chat_id: string;
+  version: number;
+  ops: JsonPatchOp[];
+}
+
+export interface MessageEditData {
+  message_id: string;
+  chat_id: string;
+  content: MessageContent;
+  edited_at: string;
+}
+
+export interface MessageDeleteData {
+  message_id: string;
+  chat_id: string;
+  thread_root_id?: string;
+}
+
+export interface TypingUpdateData {
+  chat_id: string;
+  thread_root_id: string | null;
+  user_id: string;
+  action: 'start' | 'stop';
+}
+
+export interface ChatCreatedData extends Chat {}
+
+export interface ChatUpdateData {
+  chat_id: string;
+  changes: Partial<Pick<Chat, 'name' | 'avatar_url' | 'description' | 'agent_routing_mode' | 'last_message_at' | 'last_message_preview' | 'last_message_sender'>>;
+}
+
+export interface ChatDeletedData {
+  chat_id: string;
+}
+
+/** @deprecated Use CardUpdateData */
+export type ApprovalUpdateData = CardUpdateData;
+
+export interface CardUpdateData {
+  card_type: string;
+  approval_id?: string;
+  message_id: string;
+  chat_id: string;
+  status: string;
+  decided_by?: string;
+  decided_at?: string;
+}
+
+export interface RecoveryOverflowData {
+  message: string;
+}
+
+export interface WatchingData {
+  chat_ids: string[];
+}
+
+export interface MembershipChangedData {
+  chat_id: string;
+  user_id: string;
+  action: 'added' | 'removed';
+}
+
+// ---- Task Comment & Activity Types ----
+
+export type TaskActivityAction = 'created' | 'field_changed' | 'commented';
+
+export interface TaskComment {
+  id: string;
+  task_id: string;
+  author_id: string;
+  body: string;
+  mentions?: Mention[];
+  agent_step_id?: string | null;
+  created_at: string;
+  updated_at: string;
+  author?: User;
+}
+
+export interface TaskActivity {
+  id: string;
+  task_id: string;
+  actor_id: string;
+  action: TaskActivityAction;
+  field?: string;
+  old_value?: string;
+  new_value?: string;
+  created_at: string;
+  actor?: User;
+}
+
+export interface CreateTaskCommentRequest {
+  body: string;
+}
+
+export interface UpdateTaskCommentRequest {
+  body: string;
+}
+
+// ---- Task WS Event Data ----
+
+export type TaskCreatedData = Task;
+export type TaskUpdatedData = Task;
+/** Sent to user:{agentID} channel when a task is assigned to an agent. Data is the full Task. */
+export type TaskAssignedData = Task;
+export interface TaskDeletedData {
+  task_id: string;
+  org_id: string;
+}
+
+export type TaskCommentCreatedData = TaskComment;
+export type TaskCommentUpdatedData = TaskComment;
+export interface TaskCommentDeletedData {
+  comment_id: string;
+  task_id: string;
+  org_id: string;
+}
+
+export type ProjectCreatedData = Project;
+export type ProjectUpdatedData = Project;
+export interface ProjectDeletedData {
+  project_id: string;
+  org_id: string;
+}
+
+// ---- Agent Session / Step ----
+
+export interface AgentSessionDB {
+  id: string;
+  agent_id: string;
+  org_id: string;
+  status: string;          // idle | active | completed | failed | cancelled
+  runtime_type: string;
+  runtime_key: string | null;
+  runtime_ref: Record<string, unknown> | null;
+  started_at: string;
+  finished_at: string | null;
+  created_at: string;
+}
+
+export interface AgentStep {
+  id: string;
+  session_id: string;
+  step_type: string;
+  target_type: string;
+  target_id: string | null;
+  content: Record<string, unknown>;
+  group_key: string | null;
+  runtime_key: string | null;
+  idempotency_key?: string;
+  created_at: string;
+}
+
+export interface CreateAgentSessionRequest {
+  runtime_type?: string;
+  runtime_key?: string;
+  runtime_ref?: Record<string, unknown>;
+}
+
+export interface CreateAgentStepRequest {
+  step_type: string;
+  content: Record<string, unknown>;
+  target_type?: string;
+  target_id?: string;
+  group_key?: string;
+  runtime_key?: string;
+  idempotency_key?: string;
+  projection?: boolean; // project text steps to chat message or task comment (controlled by agent's run_config)
+}
+
+export interface UpdateAgentSessionRequest {
+  status: string;
+}
+
+// Agent session WS event data
+export type AgentSessionNewData = AgentSessionDB;
+
+export interface AgentSessionUpdateData {
+  session_id: string;
+  status: string;
+  finished_at?: string;
+}
+
+export interface AgentStepNewData extends AgentStep {}
+
+export type WikiChangesetCreatedData = WikiChangeset & { org_id: string };
+export type WikiChangesetUpdatedData = WikiChangeset & { org_id: string };
+
+// ============================================================
+// Inbox Types
+// ============================================================
+
+export type InboxItemType =
+  | 'mention' | 'task_assign' | 'task_update'
+  | 'task_comment' | 'approval_request'
+  | 'agent_alert' | 'invitation';
+
+export interface InboxItem {
+  id: string;
+  org_id: string;
+  recipient_id: string;
+  actor_id: string | null;
+  type: InboxItemType;
+  entity_type: string;
+  entity_id: string;
+  group_key: string;
+  source_type: string;
+  source_id: string;
+  chat_id: string | null;
+  task_id: string | null;
+  title: string;
+  body: string;
+  read_at: string | null;
+  archived_at: string | null;
+  snoozed_until: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+// ============================================================
+// Dispatch Types (agent event delivery)
+// ============================================================
+
+export type DispatchEventType = 'message' | 'task_assign';
+export type DispatchStatus = 'pending' | 'acked';
+
+export interface DispatchEvent {
+  id: string;
+  org_id: string;
+  agent_id: string;
+  event_type: DispatchEventType;
+  source_type: string;
+  source_id: string;
+  chat_id: string | null;
+  task_id: string | null;
+  actor_id: string | null;
+  status: DispatchStatus;
+  acked_at: string | null;
+  created_at: string;
+}
+
+export type DispatchNewData = DispatchEvent;
+
+export type InboxNewData = InboxItem;
+
+export interface InboxUpdateData {
+  id: string;
+  read_at?: string | null;
+  archived_at?: string | null;
+  snoozed_until?: string | null;
+}
+
+export interface InboxBulkUpdateData {
+  action: 'mark_all_read' | 'archive_all';
+}
+
+export interface InboxUnreadCountResponse {
+  count: number;
+}
+
+export interface ReadPositionUpdateData {
+  chat_id: string;
+  last_read_message_id: string;
+}
+
+export interface NotificationAlertData {
+  title: string;
+  body: string;
+  category: string; // "mention" | "dm" | "task_assign"
+  data: Record<string, string> | null; // {org_id, chat_id, url, ...}
+}
+
+export type WsEventMap = {
+  'hello': HelloData;
+  'message.new': MessageNewData;
+  'message.patch': MessagePatchData;
+  'message.edit': MessageEditData;
+  'message.delete': MessageDeleteData;
+  'typing.update': TypingUpdateData;
+  'chat.created': ChatCreatedData;
+  'chat.update': ChatUpdateData;
+  'chat.deleted': ChatDeletedData;
+  'approval.update': ApprovalUpdateData; // deprecated, kept for backward compat
+  'card.update': CardUpdateData;
+  'recovery.overflow': RecoveryOverflowData;
+  'watching': WatchingData;
+  'pong': { ts: number };
+  'membership.changed': MembershipChangedData;
+  'task.created': TaskCreatedData;
+  'task.updated': TaskUpdatedData;
+  'task.deleted': TaskDeletedData;
+  'task.assigned': TaskAssignedData;
+  'task.comment.created': TaskCommentCreatedData;
+  'task.comment.updated': TaskCommentUpdatedData;
+  'task.comment.deleted': TaskCommentDeletedData;
+  'project.created': ProjectCreatedData;
+  'project.updated': ProjectUpdatedData;
+  'project.deleted': ProjectDeletedData;
+  'agent_session.new': AgentSessionNewData;
+  'agent_session.update': AgentSessionUpdateData;
+  'agent_step.new': AgentStepNewData;
+  'invitation.new': InvitationNewEventData;
+  'invitation.accepted': InvitationAcceptedEventData;
+  'invitation.declined': InvitationDeclinedEventData;
+  'agent_config.update': AgentConfigUpdateData;
+  'presence.update': PresenceUpdateData;
+  'wiki.changeset.created': WikiChangesetCreatedData;
+  'wiki.changeset.updated': WikiChangesetUpdatedData;
+  'notification.alert': NotificationAlertData;
+  'inbox.new': InboxNewData;
+  'inbox.update': InboxUpdateData;
+  'inbox.bulk_update': InboxBulkUpdateData;
+  'read_position.updated': ReadPositionUpdateData;
+  'dispatch.new': DispatchNewData;
+};
+
+// Invitation WS event data
+export interface InvitationNewEventData {
+  id: string;
+  org_id: string;
+  org_name: string;
+  inviter_name: string;
+  role: OrgMemberRole;
+  expires_at: string;
+}
+
+export interface InvitationAcceptedEventData {
+  invitation_id: string;
+  org_id: string;
+  user_id: string;
+  display_name: string;
+  role: OrgMemberRole;
+}
+
+export interface InvitationDeclinedEventData {
+  invitation_id: string;
+  org_id: string;
+  email: string;
+}
+
+// ============================================================
+// Platform Config Types
+// ============================================================
+
+export interface PlatformConfigResponse {
+  version: string;
+  schema_version: number;
+  min_plugin_version?: string;
+  config: Record<string, unknown>;
+}
+
+export interface AgentConfigUpdateData {
+  version: string;
+}
+
+export interface PresenceUpdateData {
+  org_id: string;
+  user_id: string;
+  status: string; // "online" | "offline" (future: "busy", "error", "away")
+}
+
+// ============================================================
+// Reference Resolution Types
+// ============================================================
+
+export interface ResolveRefsRequest {
+  refs: string[];
+}
+
+export interface ResolvedRef {
+  type: string;
+  exists: boolean;
+  restricted?: boolean;
+
+  // User fields
+  display_name?: string;
+  avatar_url?: string | null;
+  user_type?: string;
+
+  // Task fields
+  title?: string;
+  status?: string;
+  identifier?: string;
+
+  // Chat fields
+  chat_name?: string | null;
+  chat_type?: string;
+
+  // Message fields
+  sender_name?: string;
+  preview?: string;
+  chat_id?: string;
+
+  // Wiki fields
+  file_name?: string;
+  wiki_name?: string;
+  fragment_exists?: boolean;
+
+  // Task comment fields
+  comment_author?: string;
+  comment_body?: string;
+  task_id?: string;
+}
+
+export interface ResolveRefsResponse {
+  results: Record<string, ResolvedRef>;
+}
+
+export interface BacklinkItem {
+  source_type: string;
+  source_id: string;
+  context?: string;
+  snippet?: string;
+  created_at: string;
+  chat_id?: string;
+  sender_name?: string;
+  task_title?: string;
+  task_id?: string;
+  author_name?: string;
+}
+
+export interface BacklinksResponse {
+  backlinks: BacklinkItem[];
+  next_cursor?: string;
+}
+
+export interface BrokenRefItem {
+  ref_link_id: string;
+  source_type: string;
+  source_id: string;
+  uri: string;
+  target_type: string;
+  target_id: string;
+}
+
+export interface BrokenRefsResponse {
+  broken_refs: BrokenRefItem[];
+  total: number;
+}