VaultysClaw: Skill for Claude Code

Add WebSocket Message Type

When to Use

• Adding a new command the control plane sends to agents
• Adding a new report/event agents send back to the control plane
• Extending the protocol for a new feature (sync, config, notifications, etc.)

Protocol Overview

WSMessage is a flat interface (not a discriminated union) — all messages share the same envelope:

{
  messageId: string;      // e.g. "memory-sync-1748700000000"
  type: WSMessageType;    // string literal from the union
  agentId?: string;       // sender's DID (set by the agent or control plane)
  payload: any;           // typed by convention via payload interface
  timestamp: string;      // ISO 8601
  signature?: string;     // ECDSA hex — only for critical messages
}

Procedure

1. Add the Type String to the Union

File: packages/shared/src/types.ts

Add your new type literal to the WSMessageType union:

export type WSMessageType =
  | ... existing types ...
  | "my_new_type";   // ← add here

2. Add the Payload Interface

In the same file (packages/shared/src/types.ts), add a typed payload interface:

export interface WSMyNewTypePayload {
  // required fields
  sourceId: string;
  // optional fields
  metadata?: Record<string, unknown>;
}

Naming convention: WS + PascalCase(type) + Payload (e.g. WSMemorySyncPayload).

3. Handle in the Control Plane (lib/ws-server.ts)

Direction: agent → control plane (agent sends, server receives):

Add a case to the switch (message.type) in handleMessage():

case "my_new_type":
  this.handleMyNewType(message);
  break;

Then implement the handler as a private method:

private handleMyNewType(message: WSMessage): void {
  const payload = message.payload as WSMyNewTypePayload;
  const agentId = message.agentId;
  // ... business logic ...
}

Direction: control plane → agent (server sends):

Add a public method to send the message: