feat(gateway): persist the channel-native sender id on messages

Slice 1 of docs/prds/memory-engine-unification.md: persist the
participant, so a later curator can address agent-user memory scope.

- messages gains sender_id: schema, ALTER migration (idempotent via
  duplicate-column detection), both inserts, and both history selects.
  Pre-existing rows default to empty.
- curator.SessionSummary gains AgentID and ConversationMessage gains
  SenderID; the sessioncurator adapter fills them from the session's bot
  identity and the stored record.

The memory contract is untouched and nothing consumes the new fields
yet. Deriving a session's participant from its user-role messages, and
failing closed on ambiguity, stays with the curator rewrite.
This commit is contained in:
sam committed 2026-09-17 22:06:54 +10:00
1 parent b215636f99
commit 2cd796a3a3
5 files changed
+203 -19

No files matched your search

+14 -3
View File
@@ -130,9 +130,14 @@ type ConversationSource interface {
Messages(ctx context.Context, sessionID string, n int) ([]ConversationMessage, error)
}
// SessionSummary identifies one session and when it was last active.
// SessionSummary identifies one session, the agent that served it, and when
// it was last active.
type SessionSummary struct {
ID string
ID string
// AgentID is the agent that owns the session, as recorded on the
// session's own source. Agent-user memory is addressed by it, so a
// curator never has to recover the agent from the session id.
AgentID string
LastActive time.Time
}
@@ -140,7 +145,13 @@ type SessionSummary struct {
type ConversationMessage struct {
Role string // "user" or "assistant"
Content string
At time.Time
// SenderID is the channel-native stable identifier of the party that
// sent the message (see messaging.Message.SenderID). Empty for an
// assistant message, and for a channel that carries no per-sender
// identity. A curator derives a session's participant from the
// user-role messages that carry one.
SenderID string
At time.Time
}
// EventSink publishes curator activity (what ran, what changed, why). It is
+20 -13
View File
@@ -70,6 +70,7 @@ CREATE TABLE IF NOT EXISTS messages (
session_id TEXT NOT NULL,
source_id TEXT NOT NULL DEFAULT '',
sender TEXT NOT NULL DEFAULT '',
sender_id TEXT NOT NULL DEFAULT '',
role TEXT NOT NULL DEFAULT '',
text TEXT NOT NULL DEFAULT '',
ts INTEGER NOT NULL,
@@ -173,6 +174,12 @@ func openSQLiteSessionStore(dsn string) (SessionStore, error) {
!strings.Contains(err.Error(), "duplicate column name") {
return nil, errors.Join(fmt.Errorf("sessionstore: migrate messages table: %w", err), db.Close())
}
// A database created before sender ids were persisted has a messages
// table without the sender_id column; same duplicate-column detection.
if _, err := db.ExecContext(ctx, `ALTER TABLE messages ADD COLUMN sender_id TEXT NOT NULL DEFAULT ''`); err != nil &&
!strings.Contains(err.Error(), "duplicate column name") {
return nil, errors.Join(fmt.Errorf("sessionstore: migrate messages sender_id: %w", err), db.Close())
}
// Backfill the role for rows written before it was persisted, using
// the same sender-equality the store boundary applies to new writes:
// a message sent by its session's bot identity is the assistant's.
@@ -787,8 +794,8 @@ func saveMessageAt(ctx context.Context, ex execer, sessionID string, msg messagi
at := stamp(msg)
if clamp {
_, err := ex.ExecContext(ctx, `
INSERT INTO messages (message_id, session_id, source_id, sender, role, text, ts)
VALUES (?, ?, ?, ?, ?, ?, (
INSERT INTO messages (message_id, session_id, source_id, sender, sender_id, role, text, ts)
VALUES (?, ?, ?, ?, ?, ?, ?, (
SELECT CASE
WHEN MAX(ts) IS NOT NULL AND MAX(ts) >= ? THEN MAX(ts) + 1
ELSE ?
@@ -796,7 +803,7 @@ func saveMessageAt(ctx context.Context, ex execer, sessionID string, msg messagi
FROM messages WHERE session_id = ?
))
ON CONFLICT(session_id, message_id) DO NOTHING`,
id, sessionID, msg.SourceID, msg.Sender, role, msg.Text,
id, sessionID, msg.SourceID, msg.Sender, msg.SenderID, role, msg.Text,
at.UnixMilli(), at.UnixMilli(), sessionID)
if err != nil {
return "", fmt.Errorf("sessionstore: save message: %w", err)
@@ -815,9 +822,9 @@ func saveMessageAt(ctx context.Context, ex execer, sessionID string, msg messagi
}
_, err = ex.ExecContext(ctx, `
INSERT INTO messages (message_id, session_id, source_id, sender, role, text, ts)
VALUES (?, ?, ?, ?, ?, ?, ?)`,
id, sessionID, msg.SourceID, msg.Sender, role, msg.Text, at.UnixMilli())
INSERT INTO messages (message_id, session_id, source_id, sender, sender_id, role, text, ts)
VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
id, sessionID, msg.SourceID, msg.Sender, msg.SenderID, role, msg.Text, at.UnixMilli())
if err != nil {
return "", fmt.Errorf("sessionstore: save message: %w", err)
}
@@ -950,10 +957,10 @@ func (s *sqliteSessionStore) RecentMessages(ctx context.Context, sessionID strin
// stored per message: a LEFT JOIN keeps orphaned rows readable exactly
// as before, with an empty address.
rows, err := s.db.QueryContext(ctx, `
SELECT m.message_id, m.source_id, m.sender, m.role, m.text, m.ts,
SELECT m.message_id, m.source_id, m.sender, m.sender_id, m.role, m.text, m.ts,
COALESCE(s.channel_id, ''), COALESCE(s.thread_id, '')
FROM (
SELECT message_id, source_id, sender, role, text, ts, session_id FROM messages
SELECT message_id, source_id, sender, sender_id, role, text, ts, session_id FROM messages
WHERE session_id = ? ORDER BY ts DESC LIMIT ?
) m LEFT JOIN sessions s ON s.session_id = m.session_id
ORDER BY m.ts ASC`, sessionID, n)
@@ -994,9 +1001,9 @@ func (s *sqliteSessionStore) MessageCount(ctx context.Context, sessionID string)
return n, nil
}
// scanMessages scans rows shaped (message_id, source_id, sender, role, text,
// ts, channel_id, thread_id). Both the history reads and SearchMessages select
// that column order, so they share one scanner.
// scanMessages scans rows shaped (message_id, source_id, sender, sender_id,
// role, text, ts, channel_id, thread_id). Both the history reads and
// SearchMessages select that column order, so they share one scanner.
func scanMessages(rows *sql.Rows) ([]messaging.Message, error) {
defer func() { _ = rows.Close() }()
var out []messaging.Message
@@ -1007,7 +1014,7 @@ func scanMessages(rows *sql.Rows) ([]messaging.Message, error) {
role string
ts int64
)
if err := rows.Scan(&id, &msg.SourceID, &msg.Sender, &role, &msg.Text, &ts,
if err := rows.Scan(&id, &msg.SourceID, &msg.Sender, &msg.SenderID, &role, &msg.Text, &ts,
&msg.ConversationID.ChannelID, &msg.ConversationID.ThreadID); err != nil {
return nil, fmt.Errorf("sessionstore: scan message: %w", err)
}
@@ -1063,7 +1070,7 @@ func (s *sqliteSessionStore) SearchMessages(ctx context.Context, sessionID strin
}
rows, err := s.db.QueryContext(ctx, `
SELECT m.message_id, m.source_id, m.sender, m.role, m.text, m.ts,
SELECT m.message_id, m.source_id, m.sender, m.sender_id, m.role, m.text, m.ts,
COALESCE(s.channel_id, ''), COALESCE(s.thread_id, '')
FROM messages_fts
JOIN messages m ON m.id = messages_fts.rowid
+99 -1
View File
@@ -420,6 +420,48 @@ func TestSQLiteMessageTimestampRoundTrips(t *testing.T) {
}
}
// TestSQLiteSessionStore_SenderIDRoundTrips proves the channel-native
// participant identifier survives both history reads -- the ordered
// RecentMessages and the ranked SearchMessages -- and that a record with no
// sender id round-trips as empty rather than erroring.
func TestSQLiteSessionStore_SenderIDRoundTrips(t *testing.T) {
st := newTestSQLiteStore(t)
ctx := context.Background()
if err := st.SaveMessage(ctx, "sess", messaging.Message{
SourceID: "tg-1", Sender: "alice", SenderID: "u-42",
Role: messaging.RoleUser, Text: "hello there", At: sqliteBase(),
}); err != nil {
t.Fatalf("SaveMessage: %v", err)
}
if err := st.SaveMessage(ctx, "sess", messaging.Message{
Sender: "archie", Role: messaging.RoleAssistant, Text: "hi", At: sqliteBase().Add(time.Second),
}); err != nil {
t.Fatalf("SaveMessage(no sender id): %v", err)
}
hist, err := st.RecentMessages(ctx, "sess", 10)
if err != nil {
t.Fatalf("RecentMessages: %v", err)
}
if len(hist) != 2 {
t.Fatalf("RecentMessages = %d messages, want 2", len(hist))
}
if hist[0].SenderID != "u-42" {
t.Errorf("RecentMessages()[0].SenderID = %q, want %q", hist[0].SenderID, "u-42")
}
if hist[1].SenderID != "" {
t.Errorf("RecentMessages()[1].SenderID = %q, want empty", hist[1].SenderID)
}
page, err := st.SearchMessages(ctx, "sess", MessageQuery{Query: "hello", Limit: 10})
if err != nil {
t.Fatalf("SearchMessages: %v", err)
}
if len(page.Messages) != 1 || page.Messages[0].SenderID != "u-42" {
t.Errorf("SearchMessages() = %+v, want one match with SenderID u-42", page.Messages)
}
}
func TestSQLiteMessageTimestampsIncreaseAcrossStoreHandles(t *testing.T) {
path := filepath.Join(t.TempDir(), "messages.db")
stores := make([]SessionStore, 2)
@@ -643,7 +685,7 @@ func TestSQLiteSessionStore_MigratesPreRoleDatabase(t *testing.T) {
t.Fatalf("open raw db: %v", err)
}
oldMessages := strings.Replace(sqliteSessionSchema,
"\tsender TEXT NOT NULL DEFAULT '',\n\trole TEXT NOT NULL DEFAULT '',\n",
"\tsender TEXT NOT NULL DEFAULT '',\n\tsender_id TEXT NOT NULL DEFAULT '',\n\trole TEXT NOT NULL DEFAULT '',\n",
"\tsender TEXT NOT NULL DEFAULT '',\n", 1)
if _, err := db.ExecContext(t.Context(), oldMessages); err != nil {
t.Fatalf("create old schema: %v", err)
@@ -690,6 +732,62 @@ func TestSQLiteSessionStore_MigratesPreRoleDatabase(t *testing.T) {
}
}
// TestSQLiteSessionStore_MigratesPreSenderIDDatabase simulates a database
// created before sender_id existed: a role-era schema with no sender_id
// column. Opening it must add the column with an empty default, leave the
// existing rows readable, and stay clean across a second open.
func TestSQLiteSessionStore_MigratesPreSenderIDDatabase(t *testing.T) {
path := filepath.Join(t.TempDir(), "old-sender.db")
db, err := sql.Open("sqlite", sqliteSessionDSN(path))
if err != nil {
t.Fatalf("open raw db: %v", err)
}
oldMessages := strings.Replace(sqliteSessionSchema,
"\tsender_id TEXT NOT NULL DEFAULT '',\n", "", 1)
if _, err := db.ExecContext(t.Context(), oldMessages); err != nil {
t.Fatalf("create old schema: %v", err)
}
millis := sqliteBase().UnixMilli()
if _, err := db.ExecContext(t.Context(), `INSERT INTO sessions (session_id, platform, bot_user, channel_id, created_at, last_active_at)
VALUES ('sess-old', 'telegram', 'archie', 'chat-1', ?, ?)`, millis, millis); err != nil {
t.Fatalf("seed old session: %v", err)
}
if _, err := db.ExecContext(t.Context(), `INSERT INTO messages (message_id, session_id, source_id, sender, role, text, ts) VALUES
('m-user', 'sess-old', 'tg-1', 'alice', 'user', 'hello', ?)`, millis); err != nil {
t.Fatalf("seed old message: %v", err)
}
if err := db.Close(); err != nil {
t.Fatalf("close raw db: %v", err)
}
st, err := OpenSQLiteSessionStore(path)
if err != nil {
t.Fatalf("reopen old database: %v", err)
}
t.Cleanup(func() { _ = st.Close() })
hist, err := st.RecentMessages(context.Background(), "sess-old", 10)
if err != nil {
t.Fatalf("RecentMessages: %v", err)
}
if len(hist) != 1 {
t.Fatalf("history = %d messages, want 1", len(hist))
}
if hist[0].Sender != "alice" || hist[0].SenderID != "" {
t.Errorf("migrated message = %+v, want sender alice with empty SenderID", hist[0])
}
// The second open takes the duplicate-column path; it must not fail.
again, err := OpenSQLiteSessionStore(path)
if err != nil {
t.Fatalf("second reopen: %v", err)
}
t.Cleanup(func() { _ = again.Close() })
if _, err := again.RecentMessages(context.Background(), "sess-old", 10); err != nil {
t.Fatalf("RecentMessages after second reopen: %v", err)
}
}
func sqliteStoreDB(t *testing.T, st SessionStore) *sql.DB {
t.Helper()
s, ok := st.(*sqliteSessionStore)
@@ -28,6 +28,9 @@ func NewAdapter(store gateway.SessionStore) *Adapter {
return &Adapter{store: store}
}
// RecentSessions returns sessions active at or after since, newest first.
// AgentID is the session's bot identity, the closest thing to an Agent the
// tree records today (see docs/architecture/identity.md).
func (a *Adapter) RecentSessions(ctx context.Context, since time.Time) ([]curator.SessionSummary, error) {
sessions, err := a.store.List(ctx)
if err != nil {
@@ -38,11 +41,15 @@ func (a *Adapter) RecentSessions(ctx context.Context, since time.Time) ([]curato
if s.LastActiveAt.Before(since) {
continue
}
out = append(out, curator.SessionSummary{ID: s.SessionID, LastActive: s.LastActiveAt})
out = append(out, curator.SessionSummary{ID: s.SessionID, AgentID: s.Source.BotUser, LastActive: s.LastActiveAt})
}
return out, nil
}
// Messages returns the most recent n messages of one session, chronological.
// SenderID rides through unchanged from the stored record; deciding whose
// participant that is -- failing closed on zero or several distinct senders
// -- belongs to the curator, not this adapter.
func (a *Adapter) Messages(ctx context.Context, sessionID string, n int) ([]curator.ConversationMessage, error) {
msgs, err := a.store.RecentMessages(ctx, sessionID, n)
if err != nil {
@@ -54,7 +61,7 @@ func (a *Adapter) Messages(ctx context.Context, sessionID string, n int) ([]cura
if m.Role == messaging.RoleAssistant {
role = "assistant"
}
out = append(out, curator.ConversationMessage{Role: role, Content: m.Text, At: m.At})
out = append(out, curator.ConversationMessage{Role: role, Content: m.Text, SenderID: m.SenderID, At: m.At})
}
return out, nil
}
@@ -82,3 +82,64 @@ func TestAdapterMessagesReadsRoleFromRecords(t *testing.T) {
t.Errorf("Messages()[2] = %+v, want user/bare", got[2])
}
}
// TestAdapterRecentSessionsCarriesAgentID pins that a session's agent reaches
// the curator contract, so an agent-user scope can be addressed without
// recovering the agent from the session id.
func TestAdapterRecentSessionsCarriesAgentID(t *testing.T) {
t.Parallel()
store := newTestStore(t)
ctx := context.Background()
sess := gateway.SessionContext{
SessionID: "s1",
Source: messaging.SessionSource{Platform: "telegram", BotUser: "winter", ChannelID: "chat-1"},
LastActiveAt: time.Unix(2000, 0),
}
if err := store.Save(ctx, sess); err != nil {
t.Fatalf("Save() = %v", err)
}
got, err := NewAdapter(store).RecentSessions(ctx, time.Unix(1000, 0))
if err != nil {
t.Fatalf("RecentSessions() = %v, want nil", err)
}
if len(got) != 1 || got[0].AgentID != "winter" {
t.Fatalf("RecentSessions() = %+v, want one session with AgentID winter", got)
}
}
// TestAdapterMessagesCarriesSenderID pins that the channel-native participant
// identifier survives the store-to-curator hop, and stays empty for a message
// whose channel offers none.
func TestAdapterMessagesCarriesSenderID(t *testing.T) {
t.Parallel()
store := newTestStore(t)
ctx := context.Background()
if err := store.Save(ctx, gateway.SessionContext{SessionID: "s1", LastActiveAt: time.Unix(1000, 0)}); err != nil {
t.Fatalf("Save() = %v", err)
}
for _, m := range []messaging.Message{
{Sender: "alice", SenderID: "u-42", Role: messaging.RoleUser, Text: "hello", At: time.Unix(1, 0)},
{Sender: "archie", Role: messaging.RoleAssistant, Text: "hi", At: time.Unix(2, 0)},
} {
if err := store.SaveMessage(ctx, "s1", m); err != nil {
t.Fatalf("SaveMessage(%v) = %v", m, err)
}
}
got, err := NewAdapter(store).Messages(ctx, "s1", 10)
if err != nil {
t.Fatalf("Messages() = %v, want nil", err)
}
if len(got) != 2 {
t.Fatalf("Messages() = %+v, want 2", got)
}
if got[0].SenderID != "u-42" {
t.Errorf("Messages()[0].SenderID = %q, want %q", got[0].SenderID, "u-42")
}
if got[1].SenderID != "" {
t.Errorf("Messages()[1].SenderID = %q, want empty", got[1].SenderID)
}
}