From d4d215fd5b8102a31fcca096a1b932f48bfbee70 Mon Sep 17 00:00:00 2001
From: "wangziming.ec3o" <wangziming.ec3o@bytedance.com>
Date: Sat, 30 May 2026 01:53:16 +0800
Subject: [PATCH] feat(session): attach turn metadata

---
 packages/session/src/create-session.ts | 20 ++++++++++++++++----
 packages/session/src/types/llm.ts      |  2 ++
 2 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/packages/session/src/create-session.ts b/packages/session/src/create-session.ts
index bbb75e7..0fd5a55 100644
--- a/packages/session/src/create-session.ts
+++ b/packages/session/src/create-session.ts
@@ -37,6 +37,18 @@ function parseToolResultEnvelope(content: string): ToolResultEnvelope | null {
   }
 }
 
+function attachTurnMetadata(records: Message[], turnId: string): Message[] {
+  let seq = 0
+  return records.map((record) => ({
+    ...record,
+    metadata: {
+      ...(record.metadata ?? {}),
+      turnId,
+      turnSeq: seq++,
+    },
+  }))
+}
+
 /** 把 tool 执行结果序列化为 tool message content，对齐 OpenAI/Anthropic 标准（只含结果数据）。 */
 function serializeToolResultContent(result: ToolResultEnvelope['toolResults'][number]): string {
   if (!result.success) {
@@ -254,10 +266,10 @@ function buildSession(
         ...(result.toolCalls && result.toolCalls.length > 0 ? { toolCalls: result.toolCalls } : {}),
         timestamp: new Date().toISOString(),
       }
-      for (const record of recordsToPersist) {
+      const turnId = randomUUID()
+      for (const record of attachTurnMetadata([...recordsToPersist, assistantRecord], turnId)) {
         await storage.appendRecord(currentMeta.id, record)
       }
-      await storage.appendRecord(currentMeta.id, assistantRecord)
 
       return {
         content: result.content,
@@ -363,10 +375,10 @@ function buildSession(
           ...(result.toolCalls && result.toolCalls.length > 0 ? { toolCalls: result.toolCalls } : {}),
           timestamp: new Date().toISOString(),
         }
-        for (const record of recordsToPersist) {
+        const turnId = randomUUID()
+        for (const record of attachTurnMetadata([...recordsToPersist, assistantRecord], turnId)) {
           await storage.appendRecord(currentMeta.id, record)
         }
-        await storage.appendRecord(currentMeta.id, assistantRecord)
 
         // 更新 promptTokens 基线
         if (result.usage?.promptTokens) {
diff --git a/packages/session/src/types/llm.ts b/packages/session/src/types/llm.ts
index 0449182..8871fea 100644
--- a/packages/session/src/types/llm.ts
+++ b/packages/session/src/types/llm.ts
@@ -10,6 +10,8 @@ export interface Message {
   toolCallId?: string
   /** 消息写入时间（ISO 字符串） */
   timestamp?: string
+  /** 持久化层附加元数据（例如 KitKit 的 turnId/turnSeq）。LLM adapter 应忽略该字段。 */
+  metadata?: Record<string, unknown>
 }
 
 /** LLM 返回的工具调用请求 */