From ef730ac84aedb3bea093723b1318f563a162a70d Mon Sep 17 00:00:00 2001
From: viettranx <viettranx@gmail.com>
Date: Sat, 11 Apr 2026 11:33:36 +0700
Subject: [PATCH] refactor(ws/channels): accept agent_key or UUID (adds
 agentStore to struct)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

NFR-2 exception (Phase 3 C2): ChannelInstancesMethods struct gains an
agentStore field, required to support agent_key input via the cache-aware
resolver. Constructor signature expanded and single caller at
cmd/gateway_channels_setup.go:146 updated.

Router is passed nil — channel_instances methods are not wired to the
router today, so falls back to pure DB lookup. Acceptable given create
is a rare operation. Preserves the existing i18n key MsgInvalidID.

Phase 3 of agent identity hardening.
---
 cmd/gateway_channels_setup.go                 |  2 +-
 internal/gateway/methods/channel_instances.go | 20 +++++++++++++------
 2 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/cmd/gateway_channels_setup.go b/cmd/gateway_channels_setup.go
index 36c4f9c3..2e0d0548 100644
--- a/cmd/gateway_channels_setup.go
+++ b/cmd/gateway_channels_setup.go
@@ -143,7 +143,7 @@ func wireChannelRPCMethods(server *gateway.Server, pgStores *store.Stores, chann
 
 	// Register channel instances WS RPC methods
 	if pgStores.ChannelInstances != nil {
-		methods.NewChannelInstancesMethods(pgStores.ChannelInstances, msgBus, msgBus).Register(server.Router())
+		methods.NewChannelInstancesMethods(pgStores.ChannelInstances, pgStores.Agents, msgBus, msgBus).Register(server.Router())
 		zalomethods.NewQRMethods(pgStores.ChannelInstances, msgBus).Register(server.Router())
 		zalomethods.NewContactsMethods(pgStores.ChannelInstances).Register(server.Router())
 		whatsapp.NewQRMethods(pgStores.ChannelInstances, channelMgr).Register(server.Router())
diff --git a/internal/gateway/methods/channel_instances.go b/internal/gateway/methods/channel_instances.go
index 7872a1ba..71d9e9f8 100644
--- a/internal/gateway/methods/channel_instances.go
+++ b/internal/gateway/methods/channel_instances.go
@@ -23,15 +23,20 @@ var channelInstanceAllowed = map[string]bool{
 }
 
 // ChannelInstancesMethods handles channel instance CRUD via WebSocket RPC.
+//
+// NFR-2 exception (Phase 3 C2): agentStore is a new struct field required to
+// support agent_key input via resolveAgentUUIDCached. Constructor signature
+// expanded — single caller at cmd/gateway_channels_setup.go.
 type ChannelInstancesMethods struct {
-	store    store.ChannelInstanceStore
-	msgBus   *bus.MessageBus
-	eventBus bus.EventPublisher
+	store      store.ChannelInstanceStore
+	agentStore store.AgentStore
+	msgBus     *bus.MessageBus
+	eventBus   bus.EventPublisher
 }
 
 // NewChannelInstancesMethods creates a new handler for channel instance management.
-func NewChannelInstancesMethods(s store.ChannelInstanceStore, msgBus *bus.MessageBus, eventBus bus.EventPublisher) *ChannelInstancesMethods {
-	return &ChannelInstancesMethods{store: s, msgBus: msgBus, eventBus: eventBus}
+func NewChannelInstancesMethods(s store.ChannelInstanceStore, as store.AgentStore, msgBus *bus.MessageBus, eventBus bus.EventPublisher) *ChannelInstancesMethods {
+	return &ChannelInstancesMethods{store: s, agentStore: as, msgBus: msgBus, eventBus: eventBus}
 }
 
 // Register registers all channel instance RPC methods.
@@ -122,7 +127,10 @@ func (m *ChannelInstancesMethods) handleCreate(ctx context.Context, client *gate
 		return
 	}
 
-	agentID, err := uuid.Parse(params.AgentID)
+	// Accept both agent_key and UUID via resolveAgentUUIDCached (Phase 3 FR-1).
+	// nil router: channel_instances methods are not wired to the router — falls
+	// back to a pure DB lookup which is acceptable given create is a rare op.
+	agentID, err := resolveAgentUUIDCached(ctx, nil, m.agentStore, params.AgentID)
 	if err != nil {
 		client.SendResponse(protocol.NewErrorResponse(req.ID, protocol.ErrInvalidRequest, i18n.T(locale, i18n.MsgInvalidID, "agent_id")))
 		return