@geteigen/cli 0.0.0-stage → 3.1.0

package/dist/shared/events.d.ts

@@ -0,0 +1,932 @@
+import type { ActionDraftInfo } from "./actionDrafts.js";
+import type { DocCardInfo } from "./docs.js";
+import type { MachineAgentTool, MachineClient, MachineDirListing } from "./machines.js";
+import type { AgentBackendKind, RunUsage } from "./backends/types.js";
+import type { WorkspaceGitSnapshot, WorkspacePathMatch, WorkspaceRepoEntry, WorkspaceRepoFile } from "./workspace.js";
+import type { SpaceMessageMeta } from "./space.js";
+import type { ApprovalMode, AgentMode, ApprovalRequestInfo } from "./approvals.js";
+import type { ControlMode, RoomRole, RoomVisibility } from "./roomPermissions.js";
+import type { AgentContextReceiptInfo, AutoMemoryMode, MemoryEntryInfo, RepoMapInfo, RoomContextSnapshot } from "./roomContext.js";
+import type { WorkerPromptAttachment } from "./uploads.js";
+import type { BrainEpochEvent, BrainMemoryEvent, BrainReceiptInfo } from "./brain.js";
+import type { IntegrationConnectionInfo, IntegrationLeaseInfo } from "./integrations.js";
+import type { ToolIntegrationRef } from "./toolIntegration.js";
+import type { CliCommandCatalog } from "./slashCommands.js";
+export type { ControlMode, RoomInviteRole, RoomRole } from "./roomPermissions.js";
+export type { ApprovalMode, AgentMode, ApprovalStatus, ApprovalRequestInfo, } from "./approvals.js";
+export interface Participant {
+    socketId: string;
+    name: string;
+    color: string;
+    isDriver: boolean;
+    /** Agent ids this participant currently drives. */
+    drivingAgentIds?: string[];
+    userId?: string;
+    isOwner?: boolean;
+    /** Effective collaboration role in this room. */
+    role?: RoomRole;
+    /** Profile picture URL, when the user has one. */
+    avatarUrl?: string;
+}
+/** Durable room membership (online or offline). */
+export interface RoomMemberInfo {
+    userId: string;
+    email: string;
+    name: string;
+    role: RoomRole;
+    online: boolean;
+    /** Agent ids currently driven by an online socket for this user. */
+    drivingAgentIds?: string[];
+    /** Profile picture URL, when the user has one. */
+    avatarUrl?: string;
+}
+export interface SteerLogEntry {
+    sender: string;
+    color: string;
+    text: string;
+    ts: number;
+}
+export type ChatRole = "user" | "assistant" | "tool" | "system";
+export type ChatStatus = "streaming" | "done" | "error";
+export type AgentRuntime = "local" | "cloud";
+/** cli = the local CLI's own sign-in (Cursor, Claude Code, Codex, or OpenCode). server/byok use API keys. */
+export type AuthMode = "cli" | "server" | "byok";
+export type AgentStatus = "idle" | "running" | "waiting_input" | "stopped" | "error";
+/** feature = normal room agent; integrator = hidden merge agent for Integrate. */
+export type AgentKind = "feature" | "integrator";
+/** Billed token usage for an agent, refreshed after each run. */
+export interface AgentUsageInfo {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    totalTokens: number;
+    reasoningTokens?: number;
+    rawCostCents?: number;
+    chargedCents?: number;
+    /** Tokens sent in the most recent run (input + cache reads/writes). */
+    contextTokens?: number;
+    /** Model context window, when known. */
+    contextWindowTokens?: number;
+    updatedAt: number;
+}
+export interface AgentInfo {
+    id: string;
+    roomId: string;
+    backend: AgentBackendKind;
+    label: string;
+    /** Local runtime: the machine this agent runs on, and its name. */
+    machineId?: string | null;
+    machineName?: string | null;
+    scopePath?: string;
+    sessionId?: string;
+    modelId: string;
+    status: AgentStatus;
+    createdBy?: string;
+    createdAt: number;
+    sortOrder?: number;
+    sdkAgentId?: string;
+    branch?: string;
+    prUrl?: string;
+    /** Plan mode = read-only explore/propose (Cursor --mode plan / Claude permission-mode plan / OpenCode plan agent). */
+    planMode?: boolean;
+    kind?: AgentKind;
+    /** Latest `agent.getUsage()` snapshot, when the runtime reports it. */
+    usage?: AgentUsageInfo;
+    /** Slash commands the agent's CLI last reported (Claude Code). */
+    cliCommands?: CliCommandCatalog;
+    /** False for Cursor Cloud agents that skip cloning the repo. */
+    hasRepo?: boolean;
+    /** Per-agent execution settings. Legacy agents inherit the room values. */
+    runtime: AgentRuntime;
+    authMode: AuthMode;
+    repoPath?: string;
+    repoUrl?: string;
+    startingRef?: string;
+    autoCreatePR?: boolean;
+    keyHint?: string;
+}
+/**
+ * Reserved `agentId` for people-to-people chat in the Space. No agent ever
+ * has this id, so these messages never reach an agent's prompt or tab.
+ */
+export declare const SPACE_CHANNEL_ID = "space";
+export interface SpaceTypist {
+    socketId: string;
+    name: string;
+    userId?: string;
+    /** Set when typing inside a thread. */
+    threadId?: string;
+}
+export declare function isSpaceMessage(msg: {
+    agentId?: string;
+}): boolean;
+export declare function isIntegratorAgent(agent: {
+    kind?: string | null;
+}): boolean;
+export declare function isFeatureAgent(agent: {
+    kind?: string | null;
+}): boolean;
+export interface AgentConflict {
+    paths: string[];
+    agentIds: string[];
+}
+export interface FileLease {
+    roomId: string;
+    path: string;
+    agentId: string;
+    callId?: string;
+    acquiredAt: number;
+    expiresAt: number;
+}
+export interface AgentConflictBlocked {
+    agentId: string;
+    path: string;
+    holderAgentId: string;
+    action: "aborted" | "queued";
+}
+/** Structured todo item from TodoWrite / todo tools. */
+export interface AgentTodoItem {
+    id: string;
+    content: string;
+    status: "pending" | "in_progress" | "completed" | "cancelled";
+}
+export type PlanStatus = "pending" | "approved" | "dismissed";
+/** Temporary file/image attached to a user message. */
+export interface ChatAttachment {
+    id: string;
+    name: string;
+    mime: string;
+    size: number;
+    url: string;
+}
+export interface ClarifyingQuestionOption {
+    label: string;
+    description?: string;
+}
+export interface ClarifyingQuestion {
+    id?: string;
+    question: string;
+    header?: string;
+    options?: ClarifyingQuestionOption[];
+    multiSelect?: boolean;
+    selectedAnswers?: string[];
+    answered?: boolean;
+}
+export interface ChatMessage {
+    id: string;
+    roomId: string;
+    role: ChatRole;
+    content: string;
+    senderName?: string;
+    senderColor?: string;
+    /** Durable Clerk/user id of the human who sent this message (for git attribution). */
+    senderUserId?: string;
+    toolName?: string;
+    /** Unified diff when this message is a file edit. */
+    diffPatch?: string;
+    /** Full todo list when this message is a TodoWrite / todo tool call. */
+    todos?: AgentTodoItem[];
+    status: ChatStatus;
+    ts: number;
+    /** Room-level agent that produced or received this message. */
+    agentId?: string;
+    /** Pending/decided approval gate attached to this tool row (if any). */
+    approval?: ApprovalRequestInfo;
+    /** Plan-mode document attached to an assistant reply. */
+    planStatus?: PlanStatus;
+    /** Images / files the user attached to this message. */
+    attachments?: ChatAttachment[];
+    /** Structured clarifying questions when the LLM asks for user clarification. */
+    questions?: ClarifyingQuestion[];
+    /** Flag when an edit / tool message has been reverted. */
+    reverted?: boolean;
+    /** Model the agent was running when it wrote this reply (assistant messages). */
+    modelId?: string;
+    /** MCP tool rows: the integration that ran (drives the card's logo + label). */
+    integration?: ToolIntegrationRef;
+    /** Space features: thread, hand-off, people mentions. */
+    space?: SpaceMessageMeta;
+    /** Model thinking / reasoning shown above the assistant reply. */
+    thinking?: string;
+    /** Integration writes the agent drafted for people to review and send. */
+    actionDrafts?: ActionDraftInfo[];
+    /** Docs the agent created or updated, shown as cards. */
+    docs?: DocCardInfo[];
+}
+/** Keep thinking (and other defined fields) when a later write omits them. */
+export declare function mergeChatMessage(prev: ChatMessage | undefined, incoming: ChatMessage): ChatMessage;
+export interface IntegrationQueueItem {
+    id: string;
+    sourceAgentId: string;
+    sourceLabel?: string;
+    createdAt: number;
+}
+/** One room-wide integration merge at a time; extra clicks queue. */
+export interface IntegrationJobInfo {
+    status: "idle" | "running";
+    sourceAgentId?: string;
+    sourceLabel?: string;
+    heldBy?: string;
+    expiresAt?: number;
+    queue: IntegrationQueueItem[];
+}
+export interface CloudMeta {
+    repoUrl?: string;
+    startingRef?: string;
+    branch?: string;
+    prUrl?: string;
+    autoCreatePR?: boolean;
+}
+export interface RoomMemberPreview {
+    userId: string;
+    name: string;
+    avatarUrl?: string;
+    /** Connected to this session right now. Membership alone does not set this. */
+    online?: boolean;
+}
+/**
+ * One feature agent on a session, paired with the person they're with.
+ * The sessions list uses this to show who is working with which harness.
+ */
+export interface SessionSeat {
+    agentId: string;
+    backend: AgentBackendKind;
+    agentLabel: string;
+    /** True while this agent is mid-run. */
+    working: boolean;
+    /** Person driving or steering this agent, when known. */
+    userId?: string;
+    name: string;
+    avatarUrl?: string;
+    /** One-line live focus the agent set with `update_focus`. */
+    focus?: string;
+}
+export interface RoomInfo {
+    id: string;
+    name: string;
+    repoPath: string;
+    /** Local runtime: the machine new agents in this session run on. */
+    defaultMachineId?: string | null;
+    agentCommand: string;
+    participantCount: number;
+    /** active | stopped | archived */
+    status: string;
+    createdAt: number;
+    /** Dashboard row summary: a few members, the harnesses, and what needs attention. */
+    memberPreview?: RoomMemberPreview[];
+    memberCount?: number;
+    agentBackends?: AgentBackendKind[];
+    /**
+     * Feature agents paired with the person they're with.
+     * Present on session lists so a live room can show who is working with what.
+     */
+    seats?: SessionSeat[];
+    /** Runtimes in use across this session's agents (empty for an empty session). */
+    agentRuntimes?: AgentRuntime[];
+    /** Auth modes in use across this session's agents. */
+    agentAuthModes?: AuthMode[];
+    workingAgents?: number;
+    pendingApprovals?: number;
+    runtime: AgentRuntime;
+    authMode: AuthMode;
+    modelId: string;
+    /** Who may steer agents in this room. */
+    controlMode: ControlMode;
+    /** Team-workspace sessions: "private" = owner + invited people only. */
+    visibility?: RoomVisibility;
+    /**
+     * Human approval gates for irreversible / high-blast-radius tools.
+     * Separate from file locks and driver control.
+     */
+    approvalMode: ApprovalMode;
+    /** Silent auto-memory after each successful run. Default extract (on). */
+    autoMemory?: AutoMemoryMode;
+    repoUrl?: string;
+    startingRef?: string;
+    prUrl?: string;
+    autoCreatePR?: boolean;
+    /** Shared integration branch (steer/integration-…) used by Integrate. */
+    integrationBranch?: string;
+    /** Single PR from the integration branch into startingRef. */
+    integrationPrUrl?: string;
+    integrationAgentId?: string;
+    /** Current integration lock + queue (one merge at a time per room). */
+    integrationJob?: IntegrationJobInfo;
+    keyHint?: string;
+    ownerId?: string;
+    /** Organization that owns this session (null/undefined = personal). */
+    orgId?: string;
+    orgName?: string;
+    inviteCode?: string;
+    /** Active Cursor CLI chat id for the room's default agent (--resume). */
+    cursorSessionId?: string;
+    /** Agents in this room (populated when available). */
+    agents?: AgentInfo[];
+    /** Caller's effective role when requested with auth. */
+    myRole?: RoomRole;
+    /** Host or org admin — can manage invites, members, agents, settings. */
+    myCanManage?: boolean;
+    /** Room has a Slack incoming webhook configured (or env fallback available). */
+    slackNotifyConfigured?: boolean;
+    /** Masked hint for the room webhook — only for managers. */
+    slackWebhookHint?: string;
+}
+/** One person's acknowledgement of a review ping. */
+export interface PingAckInfo {
+    userId: string;
+    name: string;
+    ts: number;
+}
+/** In-room + Slack "flag for review" interrupt. */
+export interface PingInfo {
+    id: string;
+    roomId: string;
+    actorUserId: string;
+    actorName: string;
+    note?: string;
+    /** Everyone in the room, or a subset of member user ids. */
+    targets: "everyone" | string[];
+    status: "open" | "dismissed";
+    createdAt: number;
+    acks: PingAckInfo[];
+}
+export interface UserInfo {
+    id: string;
+    email: string;
+    name: string;
+}
+export interface WorkerInfo {
+    id: string;
+    name: string;
+    status: "online" | "offline" | "busy";
+    lastSeenAt: number;
+}
+export interface ModelInfo {
+    id: string;
+    displayName: string;
+    description?: string;
+    /** Zero-cost per-token (badge: "Free") — the OpenCode gateway tier also needs no API key. */
+    free?: boolean;
+    /** Picker section, e.g. "xAI" / "MiniMax" for OpenCode free models. */
+    group?: string;
+}
+/** Cursor CLI chat session stored under ~/.cursor/chats for a workspace. */
+export interface CursorChatSession {
+    id: string;
+    createdAt: number;
+    updatedAt: number;
+    hasConversation: boolean;
+}
+export interface RepoInfo {
+    url: string;
+}
+export type AgentRunStatus = "idle" | "running" | "error";
+/** Someone drafting a message to a specific agent in the room. */
+export interface TypingUser {
+    socketId: string;
+    name: string;
+    agentId: string;
+}
+export interface ChatHistoryPage {
+    messages: ChatMessage[];
+    hasMore: boolean;
+    agentId?: string;
+}
+export interface RoomJoinSnapshot {
+    messages: ChatMessage[];
+    hasMoreHistory: boolean;
+    hasMoreByAgent?: Record<string, boolean>;
+    agents: AgentInfo[];
+    pendingApprovals: ApprovalRequestInfo[];
+    openPings: PingInfo[];
+    cloudMeta: CloudMeta | null;
+    members: RoomMemberInfo[];
+}
+/** Lifecycle of a browser terminal attached to a cloud agent's sandbox. */
+export type SandboxTerminalState = "connecting" | "open" | "closed" | "error";
+export interface SandboxTerminalRef {
+    agentId: string;
+    /** Client-chosen id; also the PTY session id inside the sandbox. */
+    terminalId: string;
+}
+/**
+ * Per-user alert pushed to `user:{id}` (desktop notifications, Dock badge).
+ * Sent to the people who need to act or asked for the run — not the room.
+ */
+export interface UserNotification {
+    id: string;
+    kind: "approval" | "review" | "run_finished" | "run_failed" | "automation_created" | "automation_finished";
+    /** Room it is about; absent for notifications from outside a room (automation runs). */
+    roomId?: string;
+    /** Where it came from, shown as context: the room name, or the automation name. */
+    roomName: string;
+    title: string;
+    body: string;
+    /** Page to open when clicked; defaults to the room. */
+    href?: string;
+    createdAt: number;
+    /** Set once the recipient has seen it in the notification list. */
+    readAt?: number | null;
+}
+/**
+ * Kinds that belong in the in-app list and toasts. A room agent finishing a
+ * turn ("run_finished") is routine and only reaches the desktop app; an
+ * automation run finishing ("automation_finished") is shown, since nobody
+ * was watching it.
+ */
+export declare function isInboxNotification(kind: UserNotification["kind"]): boolean;
+/** Where a notification opens: its link, else its room. */
+export declare function notificationHref(n: Pick<UserNotification, "href" | "roomId">): string | null;
+export interface ServerToClientEvents {
+    "chat-history": (messages: ChatMessage[]) => void;
+    "chat-history-page": (page: ChatHistoryPage) => void;
+    "room-snapshot": (snapshot: RoomJoinSnapshot) => void;
+    "chat-message": (message: ChatMessage) => void;
+    /** Who is composing in the Space right now. */
+    "space-typing": (typists: SpaceTypist[]) => void;
+    "chat-delta": (id: string, content: string, status?: ChatStatus, meta?: {
+        append?: boolean;
+        thinking?: string;
+    }) => void;
+    /** @deprecated Prefer agents snapshot + agent-status(agentId, …). Kept for single-agent rooms. */
+    "agent-status": (statusOrAgentId: AgentRunStatus | string, detailOrStatus?: string | AgentRunStatus, detail?: string) => void;
+    "cloud-meta": (meta: CloudMeta) => void;
+    "model-updated": (modelId: string, agentId?: string) => void;
+    "cursor-session-updated": (sessionIdOrAgentId: string | null, sessionId?: string | null) => void;
+    presence: (participants: Participant[]) => void;
+    /** Full-repo or per-agent concatenated patch. Second arg is agentId when multi-agent. */
+    "diff-update": (patch: string, agentId?: string) => void;
+    "steer-log": (entry: SteerLogEntry) => void;
+    "steer-history": (entries: SteerLogEntry[]) => void;
+    "drive-requested": (payload: {
+        socketId: string;
+        name: string;
+        agentId?: string;
+    }) => void;
+    /** Sent to the requester while waiting for host/driver approval. */
+    "drive-request-pending": (payload: {
+        agentId?: string;
+    }) => void;
+    "drive-granted": (agentId?: string) => void;
+    "drive-released": (agentId?: string) => void;
+    agents: (agents: AgentInfo[]) => void;
+    /** Peer started / refreshed typing toward an agent. */
+    typing: (payload: TypingUser) => void;
+    /** Peer stopped typing (omit agentId to clear all agents for that socket). */
+    "typing-stop": (payload: {
+        socketId: string;
+        agentId?: string;
+    }) => void;
+    kicked: (reason: string) => void;
+    /** Host changed room collaboration settings. */
+    "control-mode-updated": (mode: ControlMode) => void;
+    /** Room membership roster changed (roles / joins / removals). */
+    "members-updated": (members: RoomMemberInfo[]) => void;
+    /** Agent proposed a high-blast-radius action that needs human sign-off. */
+    "tool-approval-requested": (request: ApprovalRequestInfo) => void;
+    "user-notification": (notification: UserNotification) => void;
+    /** Pending approval was approved/denied/expired. */
+    "tool-approval-resolved": (request: ApprovalRequestInfo) => void;
+    /** Full snapshot of open approvals for the room (on join / reconnect). */
+    "tool-approvals": (requests: ApprovalRequestInfo[]) => void;
+    /** Full snapshot of open review pings (on join / reconnect). */
+    "room-pings": (pings: PingInfo[]) => void;
+    /** Someone flagged the session for human review. */
+    "review-flagged": (ping: PingInfo) => void;
+    /** Someone acknowledged a review ping. */
+    "review-acked": (ping: PingInfo) => void;
+    /** A review ping was dismissed. */
+    "review-dismissed": (ping: PingInfo) => void;
+    "room-context": (snapshot: RoomContextSnapshot) => void;
+    /** Supermemory-backed memory created/edited/accepted/archived. */
+    "memory-updated": (payload: BrainMemoryEvent) => void;
+    /** New proposal awaiting human accept (agent, auto-run, dream, or member). */
+    "memory-proposal": (payload: BrainMemoryEvent) => void;
+    /** Tag epochs advanced (accept, archive, ingest completion, webhook). */
+    "memory-epoch-bumped": (payload: BrainEpochEvent) => void;
+    /** Receipt for the memory context an agent run consumed. */
+    "memory-receipt": (receipt: BrainReceiptInfo) => void;
+    /** Memories in a tag the agent's last run used changed after that run. */
+    "memory-context-stale": (payload: {
+        agentId: string;
+        receiptId: string;
+        tags: string[];
+    }) => void;
+    "integration-status": (payload: {
+        orgId: string;
+        connection: IntegrationConnectionInfo;
+    }) => void;
+    "lease-requested": (lease: IntegrationLeaseInfo) => void;
+    "lease-updated": (lease: IntegrationLeaseInfo) => void;
+    "repo-map-updated": (map: RepoMapInfo) => void;
+    "context-receipt": (receipt: AgentContextReceiptInfo) => void;
+    "context-stale": (payload: {
+        agentId: string;
+        usedVersion: number;
+        currentVersion: number;
+    }) => void;
+    "auto-memory-saved": (payload: {
+        agentId: string;
+        count: number;
+        entries: MemoryEntryInfo[];
+    }) => void;
+    /** Integration branch / PR / lock queue changed after an Integrate click. */
+    "integration-updated": (payload: {
+        roomId: string;
+        branch: string;
+        prUrl?: string;
+        sourceAgentId: string;
+        integratorAgentId: string;
+        job?: IntegrationJobInfo;
+    }) => void;
+    /** File changes were reverted. */
+    "changes-reverted": (payload: {
+        agentId?: string;
+        filePaths: string[];
+        messageId?: string;
+    }) => void;
+    /** Authoritative copies of an agent's recent messages (after a resync request). */
+    "chat-resync": (payload: {
+        agentId: string;
+        messages: ChatMessage[];
+    }) => void;
+    /** PTY output from a cloud agent's sandbox terminal. */
+    "sandbox-terminal-output": (payload: SandboxTerminalRef & {
+        data: string;
+    }) => void;
+    "sandbox-terminal-status": (payload: SandboxTerminalRef & {
+        state: SandboxTerminalState;
+        message?: string;
+    }) => void;
+    error: (message: string) => void;
+}
+export interface ClientToServerEvents {
+    /** Team chat in the Space — seen by people only, never sent to an agent. */
+    "space-message": (text: string, extras?: {
+        attachmentIds?: string[];
+        space?: SpaceMessageMeta;
+    }) => void;
+    /** Composing in the Space (or one of its threads). */
+    "space-typing": (typing: boolean, threadId?: string) => void;
+    "steer-message": (textOrAgentId: string, text?: string, extras?: {
+        attachmentIds?: string[];
+        /** Per-turn memory composer overrides (exclude entries, scope toggles). */
+        memory?: {
+            excludeIds?: string[];
+            onlyRoom?: boolean;
+            includeWorkspace?: boolean;
+            includePersonal?: boolean;
+        };
+        /** Sent from the Space: thread, hand-off, mentions. */
+        space?: SpaceMessageMeta;
+        /** Also show this user message in another agent's chat, without running that agent. */
+        echo?: {
+            agentId: string;
+            content: string;
+        };
+    }) => void;
+    /** Revert uncommitted file changes made by the LLM (specific files, tool message, or all). */
+    "revert-changes": (payload: {
+        roomId?: string;
+        agentId?: string;
+        filePaths?: string[];
+        messageId?: string;
+    }) => void;
+    /** Approve a finished plan and switch the agent to implement it. */
+    "approve-plan": (payload: {
+        messageId: string;
+        agentId?: string;
+    }) => void;
+    /** Hide the approve card without implementing. */
+    "dismiss-plan": (payload: {
+        messageId: string;
+    }) => void;
+    /** Announce that this user is typing to an agent (clients should throttle). */
+    typing: (agentId: string) => void;
+    /** Stop typing indicator for one agent, or all agents when omitted. */
+    "typing-stop": (agentId?: string) => void;
+    "request-drive": (agentId?: string) => void;
+    "release-drive": (agentId?: string) => void;
+    "grant-drive": (toSocketIdOrAgentId: string, toSocketId?: string) => void;
+    /**
+     * Approve or deny a pending tool-approval request.
+     * Any non-driver human in the room may decide (editors+).
+     */
+    "tool-approval-decision": (requestId: string, approved: boolean, opts?: {
+        alwaysAllow?: boolean;
+    }) => void;
+    /**
+     * Flag the session for review — pings the room + optional Slack webhook.
+     * Editors and the host may flag. Empty/omitted targetUserIds = everyone.
+     */
+    "flag-review": (payload: {
+        note?: string;
+        targetUserIds?: string[];
+    }) => void;
+    /** Acknowledge a review ping (in-room; deep-link uses REST). */
+    "ack-review": (pingId: string) => void;
+    /** Dismiss an open review ping (actor or host). */
+    "dismiss-review": (pingId: string) => void;
+    "leave-room": () => void;
+    "remove-member": (userId: string) => void;
+    /** Older chat messages before the given cursor (join only sent a page). */
+    "load-chat-history": (cursor: {
+        beforeTs?: number;
+        beforeId?: string;
+        agentId?: string;
+    }) => void;
+    /** Ask the server for the latest stored diff (skipped on join). */
+    "request-diff": (agentId?: string) => void;
+    /**
+     * Re-fetch an agent's messages since `sinceTs` — sent when a run ends while
+     * a bubble still looks mid-stream (a final delta was missed).
+     */
+    "resync-agent-messages": (payload: {
+        agentId: string;
+        sinceTs: number;
+    }) => void;
+    /** Attach to (or create) a PTY in a cloud agent's sandbox. */
+    "sandbox-terminal-open": (payload: SandboxTerminalRef & {
+        cols: number;
+        rows: number;
+    }) => void;
+    "sandbox-terminal-input": (payload: SandboxTerminalRef & {
+        data: string;
+    }) => void;
+    "sandbox-terminal-resize": (payload: SandboxTerminalRef & {
+        cols: number;
+        rows: number;
+    }) => void;
+    /** Detach; the shell keeps running in the sandbox. */
+    "sandbox-terminal-close": (payload: SandboxTerminalRef) => void;
+}
+/** Worker ↔ Server events (Socket.IO /worker namespace) */
+export interface WorkerToServerEvents {
+    "worker:ready": (info: {
+        workerId: string;
+        machineName: string;
+        /** Protocol 8+: what the machine is and which agent CLIs it has. */
+        os?: string;
+        arch?: string;
+        client?: MachineClient;
+        agents?: MachineAgentTool[];
+        maxConcurrent?: number;
+        activeRoomId?: string | null;
+        busy?: boolean;
+        /** Protocol 2+: concurrent multi-agent support. */
+        protocol?: number;
+        activeRuns?: Array<{
+            roomId: string;
+            agentId: string;
+        }>;
+    }) => void;
+    /** Protocol 8+: machine details that changed after connect (detected agent CLIs). */
+    "worker:info": (info: {
+        agents?: MachineAgentTool[];
+    }) => void;
+    "worker:agent-event": (data: {
+        roomId: string;
+        agentId?: string;
+        event: AgentStreamEventPayload;
+    }) => void;
+    "worker:file-diff": (data: {
+        roomId: string;
+        agentId?: string;
+        /** Tool call id — server maps to the chat tool message via toolMsgIds */
+        callId: string;
+        toolName: string;
+        path: string;
+        patch: string;
+    }) => void;
+    "worker:folder-picked": (data: {
+        requestId: string;
+        path: string | null;
+        error?: string;
+    }) => void;
+    "worker:models-listed": (data: {
+        requestId: string;
+        models?: Array<{
+            id: string;
+            displayName: string;
+        }>;
+        error?: string;
+    }) => void;
+    "worker:sessions-listed": (data: {
+        requestId: string;
+        sessions?: CursorChatSession[];
+        error?: string;
+    }) => void;
+    "worker:files-reverted": (data: {
+        roomId: string;
+        agentId?: string;
+        filePaths: string[];
+        messageId?: string;
+        error?: string;
+    }) => void;
+    /** Protocol 9+: answer to worker:list-dirs. */
+    "worker:dirs-listed": (data: {
+        requestId: string;
+        listing?: MachineDirListing;
+        error?: string;
+    }) => void;
+    /** Protocol 9+: answer to worker:prepare-repo — the checkout's absolute path. */
+    "worker:repo-prepared": (data: {
+        requestId: string;
+        path?: string;
+        error?: string;
+    }) => void;
+    /** Protocol 9+: answer to worker:finalize-git. */
+    "worker:git-finalized": (data: {
+        requestId: string;
+        /** Something was committed/pushed. */
+        pushed?: boolean;
+        branch?: string;
+        error?: string;
+    }) => void;
+    /** Protocol 11+: working-tree snapshot for a local agent. */
+    "worker:workspace-git-result": (data: {
+        requestId: string;
+        snapshot?: WorkspaceGitSnapshot;
+        error?: string;
+    }) => void;
+    /** Protocol 12+: commit, push, checkout, create, or discard finished. */
+    "worker:workspace-git-action-result": (data: {
+        requestId: string;
+        ok?: boolean;
+        error?: string;
+    }) => void;
+    /** Protocol 11+: repo folder listing. */
+    "worker:workspace-dir-result": (data: {
+        requestId: string;
+        entries?: WorkspaceRepoEntry[];
+        error?: string;
+    }) => void;
+    /** Protocol 11+: repo file read. */
+    "worker:workspace-file-result": (data: {
+        requestId: string;
+        file?: WorkspaceRepoFile;
+        error?: string;
+    }) => void;
+    /** Protocol 11+: repo path search. */
+    "worker:workspace-search-result": (data: {
+        requestId: string;
+        matches?: WorkspacePathMatch[];
+        error?: string;
+    }) => void;
+}
+export interface ServerToWorkerEvents {
+    "worker:run-prompt": (data: {
+        roomId: string;
+        agentId?: string;
+        prompt: string;
+        repoPath: string;
+        /** Scope-resolved working directory (defaults to repoPath). */
+        cwd?: string;
+        modelId: string;
+        sessionId?: string | null;
+        /** Agent CLI backend — defaults to cursor when omitted. */
+        backend?: AgentBackendKind;
+        /** Plan vs agent mode for this run. */
+        mode?: AgentMode;
+        /** Protocol 4+: user images/files to write into the worker cwd. */
+        attachments?: WorkerPromptAttachment[];
+        /**
+         * Protocol 7+: streamable-HTTP MCP servers to attach (room tools +
+         * Integrations Hub), same bundle hosted CLI sandboxes get.
+         */
+        mcpServers?: Record<string, {
+            type: "http";
+            url: string;
+            headers: Record<string, string>;
+        }>;
+        /**
+         * Protocol 9+: extra environment for this run only (team machines get the
+         * workspace's provider keys this way; never persisted on the machine).
+         */
+        env?: Record<string, string>;
+    }) => void;
+    "worker:abort": (data: {
+        roomId: string;
+        agentId?: string;
+    }) => void;
+    /** Protocol 9+: list folders (remote folder browser). Omitted path = the roots / home. */
+    "worker:list-dirs": (data: {
+        requestId: string;
+        path?: string;
+    }) => void;
+    /**
+     * Protocol 9+: clone (or update) a repo into `<work root>/<dir>` and check out
+     * `branch` (created from `ref` when missing). `token` authenticates private
+     * GitHub clones and is kept only in the clone's remote URL.
+     */
+    "worker:prepare-repo": (data: {
+        requestId: string;
+        repoUrl: string;
+        ref: string;
+        dir: string;
+        branch?: string;
+        token?: string;
+    }) => void;
+    /** Protocol 9+: commit everything in `repoPath` and push `branch`. */
+    "worker:finalize-git": (data: {
+        requestId: string;
+        repoPath: string;
+        branch: string;
+        message: string;
+        token?: string;
+    }) => void;
+    /** Protocol 11+: working-tree snapshot for a local agent. */
+    "worker:workspace-git": (data: {
+        requestId: string;
+        repoPath: string;
+        cwd?: string;
+    }) => void;
+    /** Protocol 12+: commit, push, switch, create, or discard in a local repo. */
+    "worker:workspace-git-action": (data: {
+        requestId: string;
+        repoPath: string;
+        action: "commit" | "push" | "checkout" | "create" | "discard";
+        message?: string;
+        branch?: string;
+        path?: string;
+        /** GitHub token for push/fetch; worker stores it in the machine credential helper. */
+        token?: string;
+    }) => void;
+    /** Protocol 11+: list a folder inside a local repo. */
+    "worker:workspace-dir": (data: {
+        requestId: string;
+        repoPath: string;
+        path: string;
+    }) => void;
+    /** Protocol 11+: read a file inside a local repo. */
+    "worker:workspace-file": (data: {
+        requestId: string;
+        repoPath: string;
+        path: string;
+    }) => void;
+    /** Protocol 11+: search paths inside a local repo. */
+    "worker:workspace-search": (data: {
+        requestId: string;
+        repoPath: string;
+        query: string;
+    }) => void;
+    /** Protocol 9+: settings managed in the app. The worker refuses work outside `allowedRoots` (when non-empty). */
+    "worker:settings": (data: {
+        allowedRoots: string[];
+        maxConcurrent: number;
+    }) => void;
+    /** Protocol 9+: this machine was revoked — forget the credential and stop. */
+    "worker:revoked": (data: {
+        message: string;
+    }) => void;
+    "worker:pick-folder": (data: {
+        requestId: string;
+    }) => void;
+    "worker:list-models": (data: {
+        requestId: string;
+        /** Protocol 6+: list models for this CLI backend. Omitted = cursor. */
+        backend?: AgentBackendKind;
+    }) => void;
+    "worker:list-sessions": (data: {
+        requestId: string;
+        repoPath: string;
+    }) => void;
+    "worker:error": (message: string) => void;
+    "worker:revert-files": (data: {
+        roomId: string;
+        agentId?: string;
+        filePaths: string[];
+        messageId?: string;
+        repoPath?: string;
+    }) => void;
+}
+export interface AgentStreamEventPayload {
+    kind: string;
+    sessionId?: string;
+    text?: string;
+    callId?: string;
+    name?: string;
+    detail?: string;
+    path?: string;
+    /** Unified diff for edit tools (local git or synthetic from tool args). */
+    diffPatch?: string;
+    /** Structured todos for TodoWrite / todo tools. */
+    todos?: AgentTodoItem[];
+    /** Structured clarifying questions when the LLM asks for user clarification. */
+    questions?: ClarifyingQuestion[];
+    message?: string;
+    result?: string;
+    parentCallId?: string;
+    status?: string;
+    /** MCP tool events: the integration that ran. */
+    integration?: ToolIntegrationRef;
+    /** tool_done: the tool failed or was rejected. */
+    isError?: boolean;
+    /** cli_commands: what the CLI reported at startup. */
+    catalog?: CliCommandCatalog;
+    /** done: token usage for this turn (CLI backends). */
+    usage?: RunUsage;
+}
+export declare const AVATAR_COLORS: string[];
+export type { AgentBackendKind };