From 95294268d8ee50b587c5348ff79b615b559b4af7 Mon Sep 17 00:00:00 2001
From: weichen <weichen@local>
Date: Tue, 29 Sep 2026 18:26:32 +0000
Subject: [PATCH] Add the context assembly observation to the run-completed
 payload

Details (original message):
Add the context assembly observation to the run-completed payload (items, truncations, estimated size).
---
 conformance_test.go                      |  8 ++++++++
 events.go                                |  9 +++++++++
 testdata/golden/context_observation.json | 13 +++++++++++++
 ts/types.ts                              | 11 ++++++++++-
 4 files changed, 40 insertions(+), 1 deletion(-)
 create mode 100644 testdata/golden/context_observation.json

diff --git a/conformance_test.go b/conformance_test.go
index e3ef06c..72ec07d 100644
--- a/conformance_test.go
+++ b/conformance_test.go
@@ -177,3 +177,11 @@ func contains(s, sub string) bool {
 		return false
 	})()
 }
+
+func TestGoldenContextObservation(t *testing.T) {
+	golden(t, "context_observation", ContextObservation{
+		Items:       []string{"system(画像)", "history(12)", "attachments(1)", "knowledge(3)"},
+		Truncations: []string{"历史 47 条超窗口 40，仅保留最近部分", "工具结果超长，转工件引用"},
+		EstChars:    18234,
+	})
+}
diff --git a/events.go b/events.go
index 257893a..a8278f0 100644
--- a/events.go
+++ b/events.go
@@ -110,6 +110,15 @@ type ArtifactPayload struct {
 
 type RunCompletedPayload struct {
 	Usage Usage `json:"usage"`
+	// Context 为该次运行的上下文组装观测（4.10/4.17：构成 + 裁剪记录；可解释性）。
+	Context *ContextObservation `json:"context,omitempty"`
+}
+
+// ContextObservation 记录一次模型输入的实际构成与预算裁剪（ctxasm 产出）。
+type ContextObservation struct {
+	Items       []string `json:"items"`                 // 如 system(画像) / history(12) / attachments(1) / knowledge(3)
+	Truncations []string `json:"truncations,omitempty"` // 裁剪记录（历史超窗/工具结果超限/附件截断）
+	EstChars    int      `json:"estChars"`              // 估算输入字符量
 }
 
 type RunFailedPayload struct {
diff --git a/testdata/golden/context_observation.json b/testdata/golden/context_observation.json
new file mode 100644
index 0000000..8bf37aa
--- /dev/null
+++ b/testdata/golden/context_observation.json
@@ -0,0 +1,13 @@
+{
+  "items": [
+    "system(画像)",
+    "history(12)",
+    "attachments(1)",
+    "knowledge(3)"
+  ],
+  "truncations": [
+    "历史 47 条超窗口 40，仅保留最近部分",
+    "工具结果超长，转工件引用"
+  ],
+  "estChars": 18234
+}
diff --git a/ts/types.ts b/ts/types.ts
index 570bec7..2cf85b7 100644
--- a/ts/types.ts
+++ b/ts/types.ts
@@ -93,7 +93,16 @@ export interface AgentSpawnPayload { agentRun: ID; name: string; task: string }
 export interface AgentProgressPayload { agentRun: ID; note?: string; phase?: RunPhase }
 export interface AgentResultPayload { agentRun: ID; status: RunStatus; summary?: string }
 export interface HITLResolvedPayload { cardId: ID; answer?: string; kind: 'choice' | 'free' | 'timeout' | 'cancelled' }
-export interface RunCompletedPayload { usage: Usage }
+export interface RunCompletedPayload {
+  usage: Usage
+  context?: ContextObservation
+}
+
+export interface ContextObservation {
+  items: string[]
+  truncations?: string[]
+  estChars: number
+}
 export interface RunFailedPayload { code: string; message: string }
 
 // ---- HITL ----