A webhook set SenderID to its configured route path. The turn path reads that field through a per-channel resolver which refuses webhook, but the session curator derives its participant from the raw field with no channel filter, so a webhook session with exactly one distinct sender and one extracted fact wrote agent-user memory addressed to User: "/hooks/...". Nothing reads it, and every pass added more, because the facts are identical strings with no dedup. docs/prds/memory-engine-unification.md criterion 7 requires that a route path never become a user identity. Clear it at the producer rather than teaching every consumer which channels are lying: a route path is a source, not a person, so it no longer enters SenderID. It still keys the inbound rate limit, where it is the documented per-source budget for webhooks (config.RateLimitConfig), so it travels in the new transport-only Inbound.BudgetKey -- carried on the wire beside Page, never persisted, and never read as an identity. pb.Message gains budget_key (field 9) for the same reason page (field 7) exists: transport context that rides with an inbound message and is deliberately absent from storedProto's rendering of a canonical record. The curator needs no change. An empty SenderID already fails closed as an unidentified user message, which is the path a dashboard session takes, and sessionParticipant's existing skip covers it; the test name now says so.
130 lines
4.7 KiB
Go
130 lines
4.7 KiB
Go
// Package messaging owns canonical Messages, Conversations, branches,
|
|
// channel and source correlation, and typed tool-call/tool-result message
|
|
// variants.
|
|
//
|
|
// This package intentionally contains only the vocabulary already settled
|
|
// in docs/architecture/migration-decisions.md section 2: the composite
|
|
// Conversation identity, immutable MessageIDs, typed tool-call and
|
|
// tool-result messages, and branch lineage through ParentConversationID and
|
|
// ForkMessageID. Migrating internal/gateway/'s session, compression,
|
|
// approval, and branch logic onto these types is deliberately out of scope
|
|
// here — see that section for why, and bd for the tracked follow-up work.
|
|
package messaging
|
|
|
|
import "time"
|
|
|
|
// ConversationID is the composite identity of a Conversation: a channel and
|
|
// the channel-native thread within it. Two conversations with the same
|
|
// ChannelID but different ThreadID are distinct.
|
|
type ConversationID struct {
|
|
ChannelID string
|
|
ThreadID string
|
|
}
|
|
|
|
func (c ConversationID) String() string {
|
|
if c.ThreadID == "" {
|
|
return c.ChannelID
|
|
}
|
|
return c.ChannelID + "/" + c.ThreadID
|
|
}
|
|
|
|
// MessageID is the canonical, immutable identifier for a Message. Once
|
|
// assigned it never changes, including across branch and fork operations —
|
|
// a forked transcript references the original MessageID it branched from
|
|
// rather than minting a new one for shared history.
|
|
type MessageID string
|
|
|
|
// Role identifies who or what produced a Message.
|
|
type Role string
|
|
|
|
const (
|
|
RoleUser Role = "user"
|
|
RoleAssistant Role = "assistant"
|
|
RoleTool Role = "tool"
|
|
RoleSystem Role = "system"
|
|
)
|
|
|
|
// Conversation is a single thread of Messages within a channel, optionally
|
|
// forked from another Conversation.
|
|
//
|
|
// Parent and child transcript isolation is exact: a fork sees the parent's
|
|
// history up to ForkMessageID, and appends to its own independent
|
|
// continuation. Nothing appended to the child is visible to the parent, and
|
|
// nothing appended to the parent after the fork point is visible to the
|
|
// child.
|
|
type Conversation struct {
|
|
ID ConversationID
|
|
|
|
// ParentConversationID is the Conversation this one branched from, and
|
|
// the zero value when this Conversation is not a branch.
|
|
ParentConversationID ConversationID
|
|
// ForkMessageID is the last MessageID visible to this Conversation from
|
|
// its parent's history. Empty when ParentConversationID is empty.
|
|
ForkMessageID MessageID
|
|
|
|
CreatedAt time.Time
|
|
}
|
|
|
|
// IsBranch reports whether this Conversation was forked from another.
|
|
func (c Conversation) IsBranch() bool {
|
|
return c.ParentConversationID != ConversationID{}
|
|
}
|
|
|
|
// Message is one immutable, persisted turn in a Conversation.
|
|
type Message struct {
|
|
ID MessageID
|
|
ConversationID ConversationID
|
|
|
|
// SourceID is the channel-native identifier (e.g. a Telegram
|
|
// message_id) this Message correlates to. Empty for messages with no
|
|
// upstream identity.
|
|
SourceID string
|
|
|
|
// Sender is the channel-native display attribution (e.g. a Telegram
|
|
// username) recorded when the message was written. Like SourceID it
|
|
// is external correlation metadata, never the canonical identity: the
|
|
// canonical Role field is authoritative in-process. At the gateway wire
|
|
// boundary (internal/infrastructure/gatewayrpc) Role is deliberately
|
|
// dropped and rebuilt from Sender via RoleForSender, so Sender is also
|
|
// preserved for that reconstruction and for history search and
|
|
// transcript rendering.
|
|
Sender string
|
|
|
|
// SenderID is the channel-native stable identifier for the party that
|
|
// sent this message (e.g. a Telegram numeric user ID or an SMTP from
|
|
// address), distinct from Sender's human-readable display form. Empty
|
|
// when the channel has no stable per-person identity to offer -- which
|
|
// includes a webhook, whose configured route path is a source rather
|
|
// than a person and travels in the transport-only Inbound.BudgetKey
|
|
// instead (see docs/prds/memory-engine-unification.md §3). Used to key
|
|
// per-identity inbound controls and to derive a memory participant, so
|
|
// a non-person value here becomes a user identity to every consumer
|
|
// that reads it.
|
|
SenderID string
|
|
|
|
Role Role
|
|
Text string
|
|
|
|
// ToolCall and ToolResult are populated instead of Text for their
|
|
// respective Roles; a Message carries exactly one of Text, ToolCall, or
|
|
// ToolResult content.
|
|
ToolCall *ToolCall
|
|
ToolResult *ToolResult
|
|
|
|
At time.Time
|
|
}
|
|
|
|
// ToolCall is a typed request from the assistant to invoke a tool.
|
|
type ToolCall struct {
|
|
CallID string
|
|
ToolName string
|
|
Arguments string // JSON-encoded arguments, opaque to this package
|
|
}
|
|
|
|
// ToolResult is a typed response to a prior ToolCall, correlated by CallID.
|
|
type ToolResult struct {
|
|
CallID string
|
|
Output string
|
|
Err string // non-empty when the tool call failed
|
|
}
|