feat: extend plugin SDK Message with channel, encryption, and DM context

Author: Cod-e-Codes

PLUGIN_ECOSYSTEM.md

@@ -37,10 +37,11 @@ The plugin ecosystem consists of several interconnected components:
 
 **Features**:
 - Plugin interface with lifecycle methods
-- Message processing and response system
+- Message processing and response system with extended context (channel, encryption status, message ID, recipient, edited flag)
 - Command registration and execution
 - Configuration management
 - Manifest validation
+- Backwards-compatible JSON wire format (new `omitempty` fields are silently ignored by older plugins)
 
 ### 2. Plugin Host (`plugin/host/`)
 
@@ -145,7 +146,27 @@ The plugin ecosystem consists of several interconnected components:
 }
 ```
 
-### Message Types
+### Message Data (type "message")
+
+When the hub sends a `"message"` request, the `data` payload is an `sdk.Message` object:
+
+```json
+{
+  "sender": "alice",
+  "content": "hello world",
+  "created_at": "2025-07-24T15:04:00Z",
+  "type": "text",
+  "channel": "general",
+  "encrypted": false,
+  "message_id": 42,
+  "recipient": "",
+  "edited": false
+}
+```
+
+Zero-value fields (`channel` empty, `encrypted` false, `message_id` 0, etc.) are omitted from JSON via `omitempty`. Plugins compiled against older SDK versions silently ignore new keys.
+
+### Request Types
 
 1. **init**: Plugin initialization with configuration
 2. **message**: Incoming chat message processing
@@ -169,11 +190,15 @@ type MyPlugin struct {
 }
 
 func (p *MyPlugin) OnMessage(msg sdk.Message) ([]sdk.Message, error) {
+    if msg.Encrypted {
+        return nil, nil // content is opaque ciphertext
+    }
     if strings.HasPrefix(msg.Content, "hello") {
         return []sdk.Message{{
             Sender:    "MyBot",
             Content:   "Hello back!",
             CreatedAt: time.Now(),
+            Channel:   msg.Channel, // reply in the same channel
         }}, nil
     }
     return nil, nil

PROTOCOL.md

@@ -241,7 +241,7 @@ Sensitive values (like `admin_key`) are passed only during handshake and are not
 
 ## Notes on Extensibility
 
-The protocol is intentionally JSON-based. **Plugins** extend the server through a managed plugin host (separate processes, JSON IPC); chat messages with `type` `"text"` can be forwarded to plugins for automation, while `:`-prefixed lines and `admin_command` messages participate in the command pipeline (including built-in admin commands where authorized). Clients and tools should use the `type` field and optional structured fields (`message_id`, `channel`, `reaction`, etc.) to interpret each payload.
+The protocol is intentionally JSON-based. **Plugins** extend the server through a managed plugin host (separate processes, JSON IPC); chat messages with `type` `"text"` can be forwarded to plugins for automation, while `:`-prefixed lines and `admin_command` messages participate in the command pipeline (including built-in admin commands where authorized). The plugin SDK's `Message` struct mirrors the core wire fields (`sender`, `content`, `created_at`, `type`, `channel`, `encrypted`, `message_id`, `recipient`, `edited`) so plugins receive full message context. All extended fields use `omitempty`, making the wire format backwards-compatible with older compiled plugins. Clients and tools should use the `type` field and optional structured fields (`message_id`, `channel`, `reaction`, etc.) to interpret each payload.
 
 ---
 

README.md

@@ -766,12 +766,12 @@ Percentages are **statement coverage** from a merged profile (`go test -coverpro
 | `plugin/license` | 87.1% | 203 LOC | High |
 | `client/crypto` | 80.3% | 320 LOC | High |
 | `config` | 73.2% | 285 LOC | High |
-| `plugin/host` | 63.0% | 533 LOC | Medium |
+| `plugin/host` | 62.5% | 536 LOC | Medium |
 | `client/config` | 57.3% | 1683 LOC | Medium |
 | `internal/doctor` | 49.8% | 661 LOC | Medium |
 | `plugin/store` | 47.0% | 490 LOC | Medium |
 | `cmd/license` | 42.2% | 140 LOC | Medium |
-| `server` | 36.1% | 6298 LOC | Low |
+| `server` | 36.1% | 6310 LOC | Low |
 | `plugin/manager` | 32.1% | 626 LOC | Low |
 | `client` | 23.0% | 4966 LOC | Low |
 | `cmd/server` | 13.7% | 424 LOC | Low |

TESTING.md

@@ -52,7 +52,7 @@ The Marchat test suite provides foundational coverage of the application's core
 | `server/config_test.go` | Server configuration | Server configuration logic and validation |
 | `server/client_test.go` | Server client management | WebSocket client initialization, message handling, admin operations |
 | `server/health_test.go` | Server health monitoring | Health checks, system metrics, HTTP endpoints, concurrent access |
-| `plugin/sdk/plugin_test.go` | Plugin SDK | Message types, JSON serialization, validation |
+| `plugin/sdk/plugin_test.go` | Plugin SDK | Message types, extended fields (channel, encrypted, message_id, recipient, edited), JSON serialization, omitempty validation, backwards-compat unknown-field handling |
 | `plugin/host/host_test.go` | Plugin Host | Plugin lifecycle, communication, enable/disable |
 | `plugin/host/plugin_lifecycle_test.go` | Plugin Host subprocess IPC | Minimal JSON plugin built with `go build`, `StartPlugin` / `StopPlugin`, `ExecuteCommand`, double-start guard |
 | `plugin/store/store_test.go` | Plugin Store | Registry management, platform resolution, filtering |
@@ -174,12 +174,12 @@ go test -cover ./...
 | `plugin/license` | 87.1% | High | 203 | Small |
 | `client/crypto` | 80.3% | High | 320 | Small |
 | `config` | 73.2% | High | 285 | Small |
-| `plugin/host` | 63.0% | Medium | 533 | Medium |
+| `plugin/host` | 62.5% | Medium | 536 | Medium |
 | `client/config` | 57.3% | Medium | 1683 | Medium |
 | `internal/doctor` | 49.8% | Medium | 661 | Medium |
 | `plugin/store` | 47.0% | Medium | 490 | Medium |
 | `cmd/license` | 42.2% | Medium | 140 | Small |
-| `server` | 36.1% | Low | 6298 | Large |
+| `server` | 36.1% | Low | 6310 | Large |
 | `plugin/manager` | 32.1% | Low | 626 | Medium |
 | `client` | 23.0% | Low | 4966 | Large |
 | `cmd/server` | 13.7% | Low | 424 | Medium |
@@ -195,7 +195,7 @@ go test -cover ./...
 - **Config Package**: Configuration loading, validation, environment variables (73.2%)
 
 ### Medium Coverage (40-70%)
-- **Plugin Host Package**: Load/start/stop lifecycle, JSON IPC with a minimal test plugin, `ExecuteCommand` (63.0%)
+- **Plugin Host Package**: Load/start/stop lifecycle, JSON IPC with a minimal test plugin, `ExecuteCommand` (62.5%)
 - **Client Config Package**: Configuration management, path utilities, keystore migration, interactive UI (57.3%)
 - **Doctor Package**: Server/client diagnostics, env checks, update metadata, DB probes (49.8%)
 - **Plugin Store**: Registry management, platform resolution, filtering, caching (47.0%)
@@ -224,7 +224,7 @@ Statement percentages below are from the merged profile (`go tool cover -func=co
 | `config/config.go` | 73.2% | config | Configuration management |
 | `client/notification_manager.go` | 67.5% | client | Desktop / notification integration |
 | `client/config/interactive_ui.go` | 66.9% | client/config | Interactive configuration UI |
-| `plugin/host/host.go` | 63.2% | plugin/host | Plugin subprocess lifecycle and IPC |
+| `plugin/host/host.go` | 62.5% | plugin/host | Plugin subprocess lifecycle and IPC |
 | `server/logger.go` | 61.4% | server | Logging functionality |
 | `server/message_state.go` | 59.2% | server | Reactions, read receipts, channel prefs |
 | `server/db_dialect.go` | 58.5% | server | SQL dialect helpers |
@@ -247,7 +247,7 @@ Statement percentages below are from the merged profile (`go tool cover -func=co
 ### Areas for Future Testing
 - **Server Package**: Advanced WebSocket handling, complex message routing scenarios (current: 36.1%)
 - **Client Package**: WebSocket communication, full TUI integration (current: 23.0%)
-- **Plugin Host**: Broader command/response paths and failure modes beyond the minimal IPC test plugin (current: 63.2%)
+- **Plugin Host**: Broader command/response paths and failure modes beyond the minimal IPC test plugin (current: 62.5%)
 - **Plugin Manager**: Store download, checksum, and install edge cases (current: 32.1%)
 - **Server Main**: Full `main` execution, HTTP/TLS serving, admin panel integration (current: 13.7% statement coverage for `cmd/server/main.go`)
 - **File Transfer**: File upload/download functionality
@@ -385,10 +385,10 @@ When adding new functionality to Marchat:
 
 ## Test Metrics
 
-- **Top-level tests**: 334 `Test*` entrypoints from `go test -list . ./...` on the main module; the nested **`plugin/sdk`** module adds 6 more (`cd plugin/sdk && go test -list . ./...`).
+- **Top-level tests**: 334 `Test*` entrypoints from `go test -list . ./...` on the main module; the nested **`plugin/sdk`** module adds 10 more (`cd plugin/sdk && go test -list . ./...`).
 - **Test files**: 38 `_test.go` files in the repo tree (including `plugin/sdk/plugin_test.go`).
 - **Packages (`go list ./...`)**: 14 in the main module; `plugin/sdk` is a nested module with its own `go.mod`.
-- **Coverage by Package** (statement %, merged profile): 88.1% (`shared`), 87.1% (`plugin/license`), 80.3% (`client/crypto`), 73.2% (`config`), 63.0% (`plugin/host`), 57.3% (`client/config`), 49.8% (`internal/doctor`), 47.0% (`plugin/store`), 42.2% (`cmd/license`), 36.1% (`server`), 32.1% (`plugin/manager`), 23.0% (`client`), 13.7% (`cmd/server`)
+- **Coverage by Package** (statement %, merged profile): 88.1% (`shared`), 87.1% (`plugin/license`), 80.3% (`client/crypto`), 73.2% (`config`), 62.5% (`plugin/host`), 57.3% (`client/config`), 49.8% (`internal/doctor`), 47.0% (`plugin/store`), 42.2% (`cmd/license`), 36.1% (`server`), 32.1% (`plugin/manager`), 23.0% (`client`), 13.7% (`cmd/server`)
 - **Overall Coverage**: **37.7%** across main-module packages (regenerate with `go test -coverprofile=mergedcoverage ./...` then `go tool cover -func=mergedcoverage`; on PowerShell avoid `-coverprofile=*.out`--see note above)
 - **Lines of code (approx.)**: non-test `.go` lines per package directory, same totals as the **Current Coverage Status** table (e.g. `server` 6298, `client` 4966); re-count with:  
   `python -c "import os; ..."` walking the tree and skipping `*_test.go`, or equivalent `find` + `wc -l`.

plugin/README.md

@@ -65,18 +65,55 @@ type Plugin interface {
 }
 ```
 
+### Message Type
+
+The `sdk.Message` struct carries chat context from the hub to plugins and back:
+
+```go
+type Message struct {
+    Sender    string    `json:"sender"`
+    Content   string    `json:"content"`
+    CreatedAt time.Time `json:"created_at"`
+    Type      string    `json:"type,omitempty"`
+    Channel   string    `json:"channel,omitempty"`
+    Encrypted bool      `json:"encrypted,omitempty"`
+    MessageID int64     `json:"message_id,omitempty"`
+    Recipient string    `json:"recipient,omitempty"`
+    Edited    bool      `json:"edited,omitempty"`
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `Sender` | Username of the message author |
+| `Content` | Message text (opaque ciphertext when `Encrypted` is true) |
+| `CreatedAt` | Timestamp |
+| `Type` | `"text"`, `"file"`, `"dm"`, etc. (matches `shared.MessageType` values) |
+| `Channel` | Channel the message belongs to (empty = default `general`) |
+| `Encrypted` | `true` when content is E2E encrypted; plugins should skip parsing |
+| `MessageID` | Server-assigned ID (useful for reactions, edits) |
+| `Recipient` | Target user for DMs (empty = broadcast) |
+| `Edited` | `true` if the message was edited after send |
+
+**Backwards compatibility**: All extended fields use `omitempty`. Plugins compiled against older SDK versions silently ignore unknown JSON keys and omit them on output — no recompile required.
+
 ### Message Processing
 
 Plugins receive messages and can respond with additional messages:
 
 ```go
 func (p *MyPlugin) OnMessage(msg sdk.Message) ([]sdk.Message, error) {
+    // Skip encrypted messages the plugin cannot read
+    if msg.Encrypted {
+        return nil, nil
+    }
     // Process incoming message
     if strings.HasPrefix(msg.Content, "hello") {
         response := sdk.Message{
             Sender:    "MyBot",
             Content:   "Hello back!",
             CreatedAt: time.Now(),
+            Channel:   msg.Channel, // reply in the same channel
         }
         return []sdk.Message{response}, nil
     }

plugin/sdk/plugin.go

@@ -29,12 +29,22 @@ type Config struct {
 	Settings  map[string]string `json:"settings"`
 }
 
-// Message represents a chat message
+// Message represents a chat message.
+//
+// Fields added after the initial SDK release (Channel, Encrypted, MessageID,
+// Recipient, Edited) use omitempty and are backwards-compatible: older plugins
+// that were compiled against the 4-field struct silently ignore the extra JSON
+// keys on input and omit them on output.
 type Message struct {
 	Sender    string    `json:"sender"`
 	Content   string    `json:"content"`
 	CreatedAt time.Time `json:"created_at"`
 	Type      string    `json:"type,omitempty"`
+	Channel   string    `json:"channel,omitempty"`
+	Encrypted bool      `json:"encrypted,omitempty"`
+	MessageID int64     `json:"message_id,omitempty"`
+	Recipient string    `json:"recipient,omitempty"`
+	Edited    bool      `json:"edited,omitempty"`
 }
 
 // PluginCommand represents a command that a plugin can register

plugin/sdk/plugin_test.go

@@ -2,6 +2,7 @@ package sdk
 
 import (
 	"encoding/json"
+	"strings"
 	"testing"
 	"time"
 )
@@ -77,6 +78,112 @@ func TestMessageEmptyFields(t *testing.T) {
 	}
 }
 
+func TestMessageExtendedFields(t *testing.T) {
+	msg := Message{
+		Sender:    "alice",
+		Content:   "hello",
+		CreatedAt: time.Now(),
+		Type:      "text",
+		Channel:   "dev",
+		Encrypted: true,
+		MessageID: 42,
+		Recipient: "bob",
+		Edited:    true,
+	}
+
+	if msg.Channel != "dev" {
+		t.Errorf("Expected channel 'dev', got %s", msg.Channel)
+	}
+	if !msg.Encrypted {
+		t.Error("Expected Encrypted to be true")
+	}
+	if msg.MessageID != 42 {
+		t.Errorf("Expected MessageID 42, got %d", msg.MessageID)
+	}
+	if msg.Recipient != "bob" {
+		t.Errorf("Expected recipient 'bob', got %s", msg.Recipient)
+	}
+	if !msg.Edited {
+		t.Error("Expected Edited to be true")
+	}
+}
+
+func TestMessageExtendedFieldsJSONRoundTrip(t *testing.T) {
+	now := time.Now().Truncate(time.Second)
+	msg := Message{
+		Sender:    "alice",
+		Content:   "encrypted payload",
+		CreatedAt: now,
+		Type:      "text",
+		Channel:   "general",
+		Encrypted: true,
+		MessageID: 99,
+		Recipient: "bob",
+		Edited:    true,
+	}
+
+	data, err := json.Marshal(msg)
+	if err != nil {
+		t.Fatalf("Failed to marshal: %v", err)
+	}
+
+	var got Message
+	if err := json.Unmarshal(data, &got); err != nil {
+		t.Fatalf("Failed to unmarshal: %v", err)
+	}
+
+	if got.Channel != msg.Channel {
+		t.Errorf("Channel: want %q, got %q", msg.Channel, got.Channel)
+	}
+	if got.Encrypted != msg.Encrypted {
+		t.Errorf("Encrypted: want %v, got %v", msg.Encrypted, got.Encrypted)
+	}
+	if got.MessageID != msg.MessageID {
+		t.Errorf("MessageID: want %d, got %d", msg.MessageID, got.MessageID)
+	}
+	if got.Recipient != msg.Recipient {
+		t.Errorf("Recipient: want %q, got %q", msg.Recipient, got.Recipient)
+	}
+	if got.Edited != msg.Edited {
+		t.Errorf("Edited: want %v, got %v", msg.Edited, got.Edited)
+	}
+}
+
+func TestMessageExtendedFieldsOmitEmpty(t *testing.T) {
+	msg := Message{
+		Sender:    "bot",
+		Content:   "hi",
+		CreatedAt: time.Now(),
+	}
+
+	data, err := json.Marshal(msg)
+	if err != nil {
+		t.Fatalf("Failed to marshal: %v", err)
+	}
+
+	raw := string(data)
+	for _, key := range []string{`"channel"`, `"encrypted"`, `"message_id"`, `"recipient"`, `"edited"`} {
+		if strings.Contains(raw, key) {
+			t.Errorf("Zero-value field %s should be omitted from JSON, got: %s", key, raw)
+		}
+	}
+}
+
+func TestMessageBackwardsCompatUnknownFieldsIgnored(t *testing.T) {
+	jsonWithExtra := `{"sender":"hub","content":"test","created_at":"2025-01-01T00:00:00Z","channel":"dev","encrypted":true,"message_id":7,"recipient":"bob","edited":true,"some_future_field":"ignored"}`
+
+	var msg Message
+	if err := json.Unmarshal([]byte(jsonWithExtra), &msg); err != nil {
+		t.Fatalf("Unmarshal should ignore unknown fields: %v", err)
+	}
+	if msg.Channel != "dev" {
+		t.Errorf("Channel: want dev, got %s", msg.Channel)
+	}
+	if msg.MessageID != 7 {
+		t.Errorf("MessageID: want 7, got %d", msg.MessageID)
+	}
+}
+
 func TestMessageWithSpecialCharacters(t *testing.T) {
 	specialContent := "Hello 世界! 🚀 Special chars: @#$%^&*()"
 	msg := Message{

server/plugin_commands.go

@@ -293,6 +293,11 @@ func (h *PluginCommandHandler) SendMessageToPlugins(msg shared.Message) {
 		Content:   msg.Content,
 		CreatedAt: msg.CreatedAt,
 		Type:      string(msg.Type),
+		Channel:   msg.Channel,
+		Encrypted: msg.Encrypted,
+		MessageID: msg.MessageID,
+		Recipient: msg.Recipient,
+		Edited:    msg.Edited,
 	}
 
 	h.manager.SendMessage(pluginMsg)
@@ -315,5 +320,10 @@ func ConvertPluginMessage(pluginMsg sdk.Message) shared.Message {
 		Content:   pluginMsg.Content,
 		CreatedAt: pluginMsg.CreatedAt,
 		Type:      shared.MessageType(pluginMsg.Type),
+		Channel:   pluginMsg.Channel,
+		Encrypted: pluginMsg.Encrypted,
+		MessageID: pluginMsg.MessageID,
+		Recipient: pluginMsg.Recipient,
+		Edited:    pluginMsg.Edited,
 	}
 }