IPC Message type reference

For each message type that is sent in the record we record

  • purpose
  • expected payload (or "varies")
  • expected response (if any)
  • sent by (extension, MCP server, symposium app, etc)
  • any other relevant details

response

Sent by: All components (VSCode extension, MCP server, Symposium app)

Purpose: Acknowledge and respond to incoming requests

Payload: Varies based on the original message type

Notes: Response messages are special. They are sent in response to other messages and their fields are determined in response to that message type:

  • the id is equal to the id of the message being responding to
  • the payload type depends on the message being responded to

marco

Sent by: VSCode extension

Purpose: Discovery broadcast to find active MCP servers ("who's out there?")

Payload: {} (empty object)

Expected response: polo messages from active MCP servers

Notes: Uses simplified sender format (no full MessageSender object)

polo

Sent by: MCP server

Purpose: Response to marco discovery messages

Payload: 

#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct PoloPayload {
    // Shell PID is now at top level in IPCMessage
}

Expected response: None (broadcast response)

Notes: Server identification comes from the sender field in the IPCMessage

store_reference

Sent by: VSCode extension

Purpose: Store code references for later expansion by agents

Payload: 

/// Payload for store_reference messages - generic key-value storage
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct StoreReferencePayload {
    /// UUID key for the reference
    pub key: String,
    /// Arbitrary JSON value - self-documenting structure determined by extension
    pub value: serde_json::Value,
}

Expected response: response with success confirmation

Target: MCP server

get_taskspace_state

Sent by: VSCode extension

Purpose: Query the current state of a taskspace

Payload:

interface TaskspaceRollCallPayload {
    taskspace_uuid: string;
}

Expected response: response with TaskspaceStateResponse

Target: Symposium app

register_taskspace_window

Sent by: VSCode extension

Purpose: Register a VSCode window with a specific taskspace

Payload:

interface RegisterTaskspaceWindowPayload {
    window_title: string;
    taskspace_uuid: string;
}

Expected response: response with success confirmation

Target: Symposium app

present_walkthrough

Sent by: MCP server

Purpose: Display interactive code walkthrough in VSCode

Payload:

#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema)]
pub struct PresentWalkthroughParams {
    /// Markdown content with embedded XML elements (comment, gitdiff, action, mermaid)
    /// See dialectic guidance for XML element syntax and usage
    pub content: String,

    /// Base directory path for resolving relative file references
    #[serde(rename = "baseUri")]
    pub base_uri: String,
}

Expected response: None (display command)

Target: VSCode extension

log

Sent by: MCP server

Purpose: Send log messages to VSCode output channel

Payload:

#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct LogParams {
    /// Log level
    pub level: LogLevel,

    /// Log message content
    pub message: String,
}

Expected response: None (logging command)

Target: VSCode extension

get_selection

Sent by: MCP server

Purpose: Request currently selected text from VSCode editor

Payload: {} (empty object)

Expected response: response with selected text or null

Target: VSCode extension

reload_window

Sent by: Daemon (on shutdown)

Purpose: Instruct all VSCode extensions to reload their windows

Payload: {} (empty object)

Expected response: None (command)

Target: All connected VSCode extensions

Notes: Broadcast message with generic sender (/tmp working directory)

goodbye

Sent by: MCP server

Purpose: Notify that the MCP server is shutting down

Payload: {} (empty object)

Expected response: None (notification)

Target: VSCode extension

resolve_symbol_by_name

Sent by: MCP server

Purpose: Find symbol definitions by name using LSP

Payload:

{
    symbol_name: string;
}

Expected response: response with Vec<ResolvedSymbol>

Target: VSCode extension

find_all_references

Sent by: MCP server

Purpose: Find all references to a symbol using LSP

Payload:

{
    symbol_name: string;
}

Expected response: response with Vec<FileLocation>

Target: VSCode extension

create_synthetic_pr

Sent by: MCP server

Purpose: Create a new synthetic pull request in VSCode

Payload: Synthetic PR creation data

Expected response: response with PR ID

Target: VSCode extension

update_synthetic_pr

Sent by: MCP server

Purpose: Update an existing synthetic pull request

Payload: Synthetic PR update data

Expected response: response with success confirmation

Target: VSCode extension

user_feedback

Sent by: VSCode extension

Purpose: Send user feedback (comments, review completion) to MCP server

Payload:

#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct UserFeedbackPayload {
    pub review_id: String,
    pub feedback_type: String, // "comment" or "complete_review"
    pub file_path: Option<String>,
    pub line_number: Option<u32>,
    pub comment_text: Option<String>,
    pub completion_action: Option<String>, // "request_changes", "checkpoint", "return"
    pub additional_notes: Option<String>,
    pub context_lines: Option<Vec<String>>,
}

Expected response: response with acknowledgment

Target: MCP server

spawn_taskspace

Sent by: MCP server

Purpose: Request creation of a new taskspace

Payload: 

#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct SpawnTaskspacePayload {
    pub project_path: String,
    pub taskspace_uuid: String,
    pub name: String,
    pub task_description: String,
    pub initial_prompt: String,
}

Expected response: response with taskspace info

Target: Symposium app

log_progress

Sent by: MCP server

Purpose: Report progress with visual indicators

Payload:

#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct LogProgressPayload {
    pub project_path: String,
    pub taskspace_uuid: String,
    pub message: String,
    pub category: ProgressCategory,
}

Expected response: None (display command)

Target: Symposium app

signal_user

Sent by: MCP server

Purpose: Request user attention for assistance

Payload:

#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct SignalUserPayload {
    pub project_path: String,
    pub taskspace_uuid: String,
    pub message: String,
}

Expected response: None (notification)

Target: Symposium app

update_taskspace

Sent by: MCP server

Purpose: Update taskspace name and description

Payload: 

#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct UpdateTaskspacePayload {
    pub project_path: String,
    pub taskspace_uuid: String,
    pub name: String,
    pub description: String,
}

Expected response: response with success confirmation

Target: Symposium app

delete_taskspace

Preview: taskspace-deletion-dialog-confirmation

Sent by: MCP server

Purpose: Request deletion of the current taskspace with user confirmation

Payload: 

#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct DeleteTaskspacePayload {
    pub project_path: String,
    pub taskspace_uuid: String,
}

Expected response: response with success confirmation (sent after user confirms) or error (if user cancels)

Target: Symposium app

Notes: This message triggers a confirmation dialog. The response is deferred until the user either confirms or cancels the deletion. If confirmed, the taskspace is deleted and a success response is sent. If cancelled, an error response is sent with the message "Taskspace deletion was cancelled by user".

taskspace_roll_call

Sent by: Symposium app

Purpose: Broadcast to discover active taskspaces for window registration

Payload: {} (empty object)

Expected response: Taskspace registration responses

Target: All components (broadcast)

Message Routing

Messages are routed based on sender information:

  • Directory matching: Messages are delivered to extensions whose workspace contains the sender's working directory
  • PID matching: When shellPid is provided, messages are delivered to extensions that have a terminal with that PID
  • Taskspace routing: Messages with taskspaceUuid can be routed to specific taskspace-aware components

Core IPC Types

The IPC message format is consistent across all components:

IPCMessage Structure

Rust (MCP Server):

#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct IPCMessage {
    /// Message type identifier
    #[serde(rename = "type")]
    pub message_type: IPCMessageType,

    /// Unique message ID for response tracking
    pub id: String,

    /// Sender information for routing
    pub sender: MessageSender,

    /// Message payload - for store_reference: { key: string, value: arbitrary_json }
    pub payload: serde_json::Value,
}

TypeScript (VSCode Extension):

interface IPCMessage {
    type: string;
    id: string;
    sender: MessageSender;
    payload: any;
}

Swift (Symposium App): Note: Swift implementation exists but not currently documented with anchors.

MessageSender Structure

Rust (MCP Server):

#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct MessageSender {
    /// Working directory - always present for reliable matching
    #[serde(rename = "workingDirectory")]
    pub working_directory: String,

    /// Optional taskspace UUID for taskspace-specific routing
    #[serde(rename = "taskspaceUuid")]
    pub taskspace_uuid: Option<String>,

    /// Optional shell PID - only when VSCode parent found
    #[serde(rename = "shellPid")]
    pub shell_pid: Option<u32>,
}

TypeScript (VSCode Extension):

interface MessageSender {
    workingDirectory: string;      // Always present - reliable matching
    taskspaceUuid?: string;        // Optional - for taskspace-specific routing
    shellPid?: number;             // Optional - only when VSCode parent found
}

Swift (Symposium App): Note: Swift implementation exists but not currently documented with anchors.