shelley: record fork provenance to de-duplicate usage data

Prompt: When we fork messages, do we write down where they came from?
I'd like to be able to compute usage data based on usage data and these
new llm columns.

Forking copies a conversation's messages into a new conversation with
fresh message_ids and identical usage_data/llm_api_url/model_name. Until
now nothing recorded that a message was a copy, so summing usage across
all messages (e.g. grouped by the new llm_api_url/model_name columns)
double-counts LLM work already incurred in the source conversation.

Add a nullable forked_from_message_id column on messages, populated by
CopyMessagesForFork with the source message's id (NULL for
originally-incurred messages). To compute usage that counts each LLM
call exactly once, filter WHERE forked_from_message_id IS NULL; join on
it to attribute a fork's copies back to their origin. No FK constraint:
the source may be deleted later and the fork should survive independently.

Also surface llm_api_url, model_name, and forked_from_message_id through
the API message struct and generated TS types so the front-end can do
the same attribution/de-duplication.

Co-authored-by: Shelley <shelley@exe.dev>

Author: philz

cmd/go2ts.go

@@ -90,6 +90,10 @@ type apiMessageForTS struct {
 	DisplayData    *string   `json:"display_data,omitempty"`
 	Generation     int64     `json:"generation"`
 	EndOfTurn      *bool     `json:"end_of_turn,omitempty"`
+
+	LLMAPIURL           *string `json:"llm_api_url,omitempty"`
+	ModelName           *string `json:"model_name,omitempty"`
+	ForkedFromMessageID *string `json:"forked_from_message_id,omitempty"`
 }
 
 type conversationStateForTS struct {

db/generated/messages.sql.go

@@ -42,8 +42,8 @@ LIMIT ? OFFSET ?;
 -- are renumbered to generation 1 (the destination starts a fresh generation
 -- history), get new message_ids, and preserve content, ordering, and original
 -- timestamps. Used to fork a conversation.
-INSERT INTO messages (message_id, conversation_id, sequence_id, generation, type, llm_data, user_data, usage_data, display_data, excluded_from_context, llm_api_url, model_name, created_at)
-SELECT lower(hex(randomblob(16))), sqlc.arg('dest_conversation_id'), m.sequence_id, 1, m.type, m.llm_data, m.user_data, m.usage_data, m.display_data, m.excluded_from_context, m.llm_api_url, m.model_name, m.created_at
+INSERT INTO messages (message_id, conversation_id, sequence_id, generation, type, llm_data, user_data, usage_data, display_data, excluded_from_context, llm_api_url, model_name, forked_from_message_id, created_at)
+SELECT lower(hex(randomblob(16))), sqlc.arg('dest_conversation_id'), m.sequence_id, 1, m.type, m.llm_data, m.user_data, m.usage_data, m.display_data, m.excluded_from_context, m.llm_api_url, m.model_name, m.message_id, m.created_at
 FROM messages m
 WHERE m.conversation_id = sqlc.arg('source_conversation_id')
   AND m.sequence_id <= sqlc.arg('cutoff_sequence_id')
@@ -120,7 +120,7 @@ UPDATE messages SET excluded_from_context = ? WHERE message_id = ?;
 SELECT m.message_id, m.conversation_id, m.sequence_id, m.type,
        m.llm_data, m.user_data, m.usage_data, m.created_at,
        m.display_data, m.excluded_from_context, m.generation,
-       m.llm_api_url, m.model_name
+       m.llm_api_url, m.model_name, m.forked_from_message_id
 FROM messages m
 WHERE m.conversation_id = ? AND m.type = 'agent'
   AND m.sequence_id > COALESCE(

db/generated/models.go

@@ -0,0 +1,19 @@
+-- Record fork provenance on copied messages.
+--
+-- When a conversation is forked, its messages are copied into the new
+-- conversation with fresh message_ids (see CopyMessagesForFork). Without a
+-- back-reference, summing usage_data / llm_api_url / model_name across all
+-- messages double-counts the LLM work that was already incurred in the source
+-- conversation, because the forked copies carry identical usage values.
+--
+-- forked_from_message_id points at the source message a copy was made from.
+-- It is NULL for originally-incurred messages. To compute usage that counts
+-- each LLM call exactly once, filter WHERE forked_from_message_id IS NULL.
+-- It deliberately has no FK constraint: the source message (or its whole
+-- conversation) may be deleted later, and the fork should survive as an
+-- independent conversation rather than cascade-delete or block.
+ALTER TABLE messages ADD COLUMN forked_from_message_id TEXT;
+
+-- Index so attributing a fork's copies back to their origins (or finding all
+-- forks of a message) is cheap.
+CREATE INDEX idx_messages_forked_from ON messages(forked_from_message_id) WHERE forked_from_message_id IS NOT NULL;

db/query/messages.sql

@@ -86,6 +86,22 @@ func TestForkConversationCopiesUpToCutoff(t *testing.T) {
 	if copied[0].MessageID == msgs[0].MessageID {
 		t.Fatal("copied message should have a new message_id")
 	}
+	// Each copy records the source message it came from so usage data can be
+	// de-duplicated (forked copies carry identical usage values and would
+	// otherwise double-count). Source messages have no provenance.
+	for i, c := range copied {
+		if c.ForkedFromMessageID == nil {
+			t.Fatalf("copied message %d should record forked_from_message_id", i)
+		}
+		if *c.ForkedFromMessageID != msgs[i].MessageID {
+			t.Fatalf("copied message %d forked_from = %q, want %q", i, *c.ForkedFromMessageID, msgs[i].MessageID)
+		}
+	}
+	for i, m := range srcMsgs {
+		if m.ForkedFromMessageID != nil {
+			t.Fatalf("source message %d should have nil forked_from_message_id, got %q", i, *m.ForkedFromMessageID)
+		}
+	}
 }
 
 // TestHandleForkConversationByMessageID drives the HTTP handler and confirms it

db/schema/032-add-message-forked-from.sql

@@ -46,6 +46,13 @@ type APIMessage struct {
 	DisplayData    *string   `json:"display_data,omitempty"`
 	Generation     int64     `json:"generation"`
 	EndOfTurn      *bool     `json:"end_of_turn,omitempty"`
+	// LLMAPIURL and ModelName identify which LLM produced this message's
+	// usage data; ForkedFromMessageID points at the source message a fork
+	// copy came from (nil for originally-incurred messages). Together they
+	// let clients attribute and de-duplicate usage across forks.
+	LLMAPIURL           *string `json:"llm_api_url,omitempty"`
+	ModelName           *string `json:"model_name,omitempty"`
+	ForkedFromMessageID *string `json:"forked_from_message_id,omitempty"`
 }
 
 // ConversationState represents the current state of a conversation.
@@ -155,17 +162,20 @@ func toAPIMessages(messages []generated.Message) []APIMessage {
 		llmData, endOfTurnPtr := llmDataForAPI(msg.LlmData, msg.Type, msg.MessageID)
 
 		apiMsg := APIMessage{
-			MessageID:      msg.MessageID,
-			ConversationID: msg.ConversationID,
-			SequenceID:     msg.SequenceID,
-			Type:           msg.Type,
-			LlmData:        llmData,
-			UserData:       msg.UserData,
-			UsageData:      msg.UsageData,
-			CreatedAt:      msg.CreatedAt,
-			DisplayData:    msg.DisplayData,
-			Generation:     msg.Generation,
-			EndOfTurn:      endOfTurnPtr,
+			MessageID:           msg.MessageID,
+			ConversationID:      msg.ConversationID,
+			SequenceID:          msg.SequenceID,
+			Type:                msg.Type,
+			LlmData:             llmData,
+			UserData:            msg.UserData,
+			UsageData:           msg.UsageData,
+			CreatedAt:           msg.CreatedAt,
+			DisplayData:         msg.DisplayData,
+			Generation:          msg.Generation,
+			EndOfTurn:           endOfTurnPtr,
+			LLMAPIURL:           msg.LlmApiUrl,
+			ModelName:           msg.ModelName,
+			ForkedFromMessageID: msg.ForkedFromMessageID,
 		}
 		apiMessages[i] = apiMsg
 	}

server/fork_test.go

@@ -28,6 +28,7 @@ export interface Usage {
   output_tokens: number;
   cost_usd: number;
   model?: string;
+  url?: string;
   start_time?: string | null;
   end_time?: string | null;
 }
@@ -44,6 +45,9 @@ export interface ApiMessageForTS {
   display_data?: string | null;
   generation: number;
   end_of_turn?: boolean | null;
+  llm_api_url?: string | null;
+  model_name?: string | null;
+  forked_from_message_id?: string | null;
 }
 
 export interface ConversationStateForTS {