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) 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 { 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 LastActive time.Time
} }
@@ -140,7 +145,13 @@ type SessionSummary struct {
type ConversationMessage struct { type ConversationMessage struct {
Role string // "user" or "assistant" Role string // "user" or "assistant"
Content string 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 // 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, session_id TEXT NOT NULL,
source_id TEXT NOT NULL DEFAULT '', source_id TEXT NOT NULL DEFAULT '',
sender TEXT NOT NULL DEFAULT '', sender TEXT NOT NULL DEFAULT '',
sender_id TEXT NOT NULL DEFAULT '',
role TEXT NOT NULL DEFAULT '', role TEXT NOT NULL DEFAULT '',
text TEXT NOT NULL DEFAULT '', text TEXT NOT NULL DEFAULT '',
ts INTEGER NOT NULL, ts INTEGER NOT NULL,
@@ -173,6 +174,12 @@ func openSQLiteSessionStore(dsn string) (SessionStore, error) {
!strings.Contains(err.Error(), "duplicate column name") { !strings.Contains(err.Error(), "duplicate column name") {
return nil, errors.Join(fmt.Errorf("sessionstore: migrate messages table: %w", err), db.Close()) 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 // Backfill the role for rows written before it was persisted, using
// the same sender-equality the store boundary applies to new writes: // the same sender-equality the store boundary applies to new writes:
// a message sent by its session's bot identity is the assistant's. // 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) at := stamp(msg)
if clamp { if clamp {
_, err := ex.ExecContext(ctx, ` _, err := ex.ExecContext(ctx, `
INSERT INTO messages (message_id, session_id, source_id, sender, role, text, ts) INSERT INTO messages (message_id, session_id, source_id, sender, sender_id, role, text, ts)
VALUES (?, ?, ?, ?, ?, ?, ( VALUES (?, ?, ?, ?, ?, ?, ?, (
SELECT CASE SELECT CASE
WHEN MAX(ts) IS NOT NULL AND MAX(ts) >= ? THEN MAX(ts) + 1 WHEN MAX(ts) IS NOT NULL AND MAX(ts) >= ? THEN MAX(ts) + 1
ELSE ? ELSE ?
@@ -796,7 +803,7 @@ func saveMessageAt(ctx context.Context, ex execer, sessionID string, msg messagi
FROM messages WHERE session_id = ? FROM messages WHERE session_id = ?
)) ))
ON CONFLICT(session_id, message_id) DO NOTHING`, 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) at.UnixMilli(), at.UnixMilli(), sessionID)
if err != nil { if err != nil {
return "", fmt.Errorf("sessionstore: save message: %w", err) 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, ` _, err = ex.ExecContext(ctx, `
INSERT INTO messages (message_id, session_id, source_id, sender, role, text, ts) INSERT INTO messages (message_id, session_id, source_id, sender, sender_id, role, text, ts)
VALUES (?, ?, ?, ?, ?, ?, ?)`, VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
id, sessionID, msg.SourceID, msg.Sender, role, msg.Text, at.UnixMilli()) id, sessionID, msg.SourceID, msg.Sender, msg.SenderID, role, msg.Text, at.UnixMilli())
if err != nil { if err != nil {
return "", fmt.Errorf("sessionstore: save message: %w", err) 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 // stored per message: a LEFT JOIN keeps orphaned rows readable exactly
// as before, with an empty address. // as before, with an empty address.
rows, err := s.db.QueryContext(ctx, ` 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, '') COALESCE(s.channel_id, ''), COALESCE(s.thread_id, '')
FROM ( 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 ? WHERE session_id = ? ORDER BY ts DESC LIMIT ?
) m LEFT JOIN sessions s ON s.session_id = m.session_id ) m LEFT JOIN sessions s ON s.session_id = m.session_id
ORDER BY m.ts ASC`, sessionID, n) ORDER BY m.ts ASC`, sessionID, n)
@@ -994,9 +1001,9 @@ func (s *sqliteSessionStore) MessageCount(ctx context.Context, sessionID string)
return n, nil return n, nil
} }
// scanMessages scans rows shaped (message_id, source_id, sender, role, text, // scanMessages scans rows shaped (message_id, source_id, sender, sender_id,
// ts, channel_id, thread_id). Both the history reads and SearchMessages select // role, text, ts, channel_id, thread_id). Both the history reads and
// that column order, so they share one scanner. // SearchMessages select that column order, so they share one scanner.
func scanMessages(rows *sql.Rows) ([]messaging.Message, error) { func scanMessages(rows *sql.Rows) ([]messaging.Message, error) {
defer func() { _ = rows.Close() }() defer func() { _ = rows.Close() }()
var out []messaging.Message var out []messaging.Message
@@ -1007,7 +1014,7 @@ func scanMessages(rows *sql.Rows) ([]messaging.Message, error) {
role string role string
ts int64 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 { &msg.ConversationID.ChannelID, &msg.ConversationID.ThreadID); err != nil {
return nil, fmt.Errorf("sessionstore: scan message: %w", err) 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, ` 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, '') COALESCE(s.channel_id, ''), COALESCE(s.thread_id, '')
FROM messages_fts FROM messages_fts
JOIN messages m ON m.id = messages_fts.rowid 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) { func TestSQLiteMessageTimestampsIncreaseAcrossStoreHandles(t *testing.T) {
path := filepath.Join(t.TempDir(), "messages.db") path := filepath.Join(t.TempDir(), "messages.db")
stores := make([]SessionStore, 2) stores := make([]SessionStore, 2)
@@ -643,7 +685,7 @@ func TestSQLiteSessionStore_MigratesPreRoleDatabase(t *testing.T) {
t.Fatalf("open raw db: %v", err) t.Fatalf("open raw db: %v", err)
} }
oldMessages := strings.Replace(sqliteSessionSchema, 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) "\tsender TEXT NOT NULL DEFAULT '',\n", 1)
if _, err := db.ExecContext(t.Context(), oldMessages); err != nil { if _, err := db.ExecContext(t.Context(), oldMessages); err != nil {
t.Fatalf("create old schema: %v", err) 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 { func sqliteStoreDB(t *testing.T, st SessionStore) *sql.DB {
t.Helper() t.Helper()
s, ok := st.(*sqliteSessionStore) s, ok := st.(*sqliteSessionStore)
@@ -28,6 +28,9 @@ func NewAdapter(store gateway.SessionStore) *Adapter {
return &Adapter{store: store} 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) { func (a *Adapter) RecentSessions(ctx context.Context, since time.Time) ([]curator.SessionSummary, error) {
sessions, err := a.store.List(ctx) sessions, err := a.store.List(ctx)
if err != nil { if err != nil {
@@ -38,11 +41,15 @@ func (a *Adapter) RecentSessions(ctx context.Context, since time.Time) ([]curato
if s.LastActiveAt.Before(since) { if s.LastActiveAt.Before(since) {
continue 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 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) { func (a *Adapter) Messages(ctx context.Context, sessionID string, n int) ([]curator.ConversationMessage, error) {
msgs, err := a.store.RecentMessages(ctx, sessionID, n) msgs, err := a.store.RecentMessages(ctx, sessionID, n)
if err != nil { if err != nil {
@@ -54,7 +61,7 @@ func (a *Adapter) Messages(ctx context.Context, sessionID string, n int) ([]cura
if m.Role == messaging.RoleAssistant { if m.Role == messaging.RoleAssistant {
role = "assistant" 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 return out, nil
} }
@@ -82,3 +82,64 @@ func TestAdapterMessagesReadsRoleFromRecords(t *testing.T) {
t.Errorf("Messages()[2] = %+v, want user/bare", got[2]) 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)
}
}