Veskslop-t/docs/core-bridge.md

Core bridge

The core bridge is the only surface between the Vesktop core and the external daemon. This document describes the protocol, the validation rules, and the hooks into upstream files.

Files

File	Role	Status
src/shared/puppetProtocol.ts	Action names, error codes, limits, and shared types	Implemented
src/renderer/puppet/actions.ts	Validated action handlers and the core rate limit	Implemented
src/renderer/puppet/events.ts	Event normalization and push to main	Implemented
src/renderer/puppet/index.ts	Renderer initialization	Implemented
src/main/puppetBridge.ts	Unix socket server, request forwarding, event fan-out	Implemented

Event subscription timing. The event module must wait for the flux dispatcher with waitFor(filters.byProps("dispatch", "subscribe"), ...). A direct subscribe at module load can run before Vencord registers the dispatcher. That mistake crashes the whole renderer bundle.

Transport

The core bridge uses a Unix socket. On Linux the path is $XDG_RUNTIME_DIR/vesktop-puppet.sock. On Linux without XDG_RUNTIME_DIR, the path is /tmp/vesktop-puppet.sock. On Windows the path is the named pipe \\.\pipe\vesktop-puppet.sock.

The protocol is newline-delimited JSON. Each request gets one response line. An event subscriber gets event lines until the connection closes.

Request:

{ "id": 1, "action": "message.send", "params": { "channelId": "123", "content": "hello" } }

Success response:

{ "id": 1, "ok": true, "result": { "channelId": "123", "sent": true } }

Error response:

{ "id": 1, "ok": false, "error": { "code": "CONTENT_EMPTY", "message": "content is empty" } }

Event line:

{ "type": "event", "event": { "type": "MESSAGE_CREATE", "channelId": "123" } }

Actions

Action	Parameters	Result
ping	none	"pong"
events.subscribe	none	{ "subscribed": true }. The socket becomes an event subscriber.
state.get	none	The current user, the guilds, and the channels. Cache-only. Includes user avatars and guild icons.
voice.get	optional userId, optional guildId	The voice channel and its members, or channelId: null. Without guildId it searches all guilds.
voice.overview	guildId	The occupied voice channels in the guild and their members
user.search	query, optional guildId, optional limit	Users from the client cache. Guild members when guildId is set.
dm.list	optional limit	Cached DM and group DM channels with recipients, icons, and avatars. Cache-only.
message.send	channelId, content	{ channelId, messageId, sent: true }
message.read	channelId, limit	{ cached, messages }. Cache-only. Messages include the author avatar and attachment CDN links.
message.fetch	channelId, limit, optional before or after	{ fetched, messages }. Fetches from Discord. Same message shape.
reaction.add	channelId, messageId, emoji	{ added: true }
dm.send	userId, content	{ userId, channelId, sent: true }

Events

The renderer normalizes client events and pushes them to subscribers.

Event	Payload
MESSAGE_CREATE	Message ID, channel, guild, channel type, author, content, mentions, timestamp
MESSAGE_REACTION_ADD	Message ID, channel, guild, user, emoji
MESSAGE_REACTION_REMOVE	Same fields as add
VOICE_STATE_UPDATE	User, channel, guild, session, mute, deaf, self-mute, self-deaf

Validation rules

The core validates all input. The daemon cannot bypass these rules.

• A channel ID and a user ID must match the snowflake format. The format is 17 to 20 digits.
• content must be a string. The content must not be empty after a trim.
• content must not contain control characters.
• content must not be longer than 2000 characters.
• The target channel must exist. The channel type must accept text. The allowed types are GUILD_TEXT, DM, GROUP_DM, GUILD_ANNOUNCEMENT, ANNOUNCEMENT_THREAD, PUBLIC_THREAD, and PRIVATE_THREAD.
• limit must be an integer from 1 to 100.
• before and after must be snowflakes. They are mutually exclusive. message.fetch uses them to walk history.
• voice.get accepts snowflakes only. It reads the client cache. It never joins a call.
• voice.overview requires a guild snowflake. It reads the client cache.
• user.search takes a query of 1 to 100 characters and a limit of 1 to 25. It reads the client cache only. An exact snowflake query returns that user when cached.
• dm.list takes a limit of 1 to 50. It reads ChannelStore.getSortedPrivateChannels() only.
• reaction.add accepts a short emoji string without line breaks. It counts as an outbound action for the rate limit.
• A request line must not be larger than 64 KiB.

Core rate limit

The core rate limit is a safety net. It does not replace the daemon pacing.

• The minimum interval between two outbound actions is 500 ms.
• The maximum is 30 outbound actions per minute.
• The limit applies to message.send and dm.send.

Error codes

Code	Meaning
INVALID_REQUEST	The line is not valid JSON.
PAYLOAD_TOO_LARGE	The request line is larger than 64 KiB.
UNKNOWN_ACTION	The action name is not in the action list.
CORE_UNAVAILABLE	The bridge cannot reach the renderer.
NOT_LOGGED_IN	No user is logged in.
INVALID_SNOWFLAKE	The ID is not a snowflake.
INVALID_PARAM	A parameter has the wrong type or value.
CONTENT_EMPTY	The content is empty.
CONTENT_TOO_LONG	The content is longer than 2000 characters.
CHANNEL_NOT_FOUND	The channel is not in the client cache.
NOT_SENDABLE	The channel type cannot receive messages.
SEND_FAILED	Discord rejected the message.
REACTION_FAILED	Discord rejected the reaction.
DM_UNAVAILABLE	The client cannot create a DM channel.
NOT_SUPPORTED	The client does not offer the internal action.
RATE_LIMITED	The core rate limit rejected the action.
INTERNAL	An unexpected error occurred. The details go to the local log only.

Hooks into upstream files

The bridge uses a small number of hooks. Keep these changes minimal.

File	Change
src/main/main.ts	Import the bridge. Call initPuppetBridge() after app.whenReady().
src/shared/IpcEvents.ts	Add PUPPET_EVENT and IpcCommands.PUPPET_COMMAND.
src/renderer/index.ts	Import ./puppet.
src/renderer/ipcCommands.ts	Register PUPPET_COMMAND and call handlePuppetAction.
src/preload/VesktopNative.ts	Add puppet.emit(event) for event push.

How to add an action

1. Add the action name to PuppetAction in src/shared/puppetProtocol.ts.
2. Add a validation case in src/renderer/puppet/actions.ts.
3. Add the action to the known-action set in src/main/puppetBridge.ts.
4. Add a tool in the daemon (poc/src/control-bridge.ts).
5. Add a unit test for the validation path.
6. Run pnpm testTypes, pnpm lint, and pnpm build.

Why this shape

The shape gives three properties:

• The daemon cannot run arbitrary code in the client.
• A daemon bug cannot crash the client or send malformed data to Discord.
• The core patch stays small, so an upstream rebase is easy.