Accept included remote history events

Author: SqlRush

docs/cc-100-roadmap.md

@@ -112,6 +112,8 @@ M6 补充：remote history event-list 现在接受 `value`/`values`/`resources`/
 
 M6 补充：remote history response parser 现在会解包 `payload`/`response`/`result`/`body` 等通用响应外壳，外壳内的 event list、pagination、links 会继续递归解析。
 
+M6 补充：remote history response parser 现在接受 JSON:API `included` collection，会过滤非事件资源，并递归解包 `resource`/`attributes`/`properties` 后用外层 resource id 作为事件 ID fallback。
+
 M6 补充：remote history `data`/`payload`/`response`/`result`/`body` 等 event-list 字段现在也接受单个 SDK event 对象，避免非数组单事件页被当作普通 wrapper 后丢失。
 
 M6 补充：remote history `SDKEvent` 本体现在接受 `eventType`/`event_type`/`role` 类型别名、`createdAt`/`created_at` 时间戳别名，以及 `payload`/`data`/`body`/`serializedMessage` message payload 别名；payload 只有 `role`/`content` 时也能 materialize 成 transcript message。

docs/claude-code-go-rewrite-plan.md

@@ -208,6 +208,7 @@ test/parity/                 # golden tests against TS/official behavior
 - 本轮补充：remote history response parser 会递归解包 `data.session.events`、`data.projectSession.eventConnection`、`data.viewer.session.events`、`data.node.eventConnection`、`conversation`、`remoteHistory`、`_embedded` 等 GraphQL/session/HAL wrapper，继续复用 `nodes`/`edges[].node` 和 `pageInfo` pagination 解析。
 - 本轮补充：remote history event-list 接受 `value`/`values`/`resources`/`collection` 别名，connection edge 也接受 `resource`/`value` 作为 node payload，覆盖 OData/HAL/resource collection 风格响应。
 - 本轮补充：remote history response parser 现在也递归解包页级 JSON:API/resource `attributes`/`properties` wrapper，event-list 接受 `list`/`object`/`objects` aliases，并能把单个 `data.attributes` resource event 作为一条 SDK event 恢复。
+- 本轮补充：remote history response parser 现在也接受 JSON:API `included` collection，会过滤非事件资源，并递归解包 `resource`/`attributes`/`properties` 后保留外层 resource id 作为事件 ID fallback。
 - 本轮补充：remote history response parser 会解包 `payload`/`response`/`result`/`body` 等通用响应外壳，外壳内的 event list、pagination、links 会继续递归解析。
 - 本轮补充：remote history `SDKEvent` 本体接受 `eventType`/`event_type`/`role` 类型别名、`createdAt`/`created_at` 时间戳别名，以及 `payload`/`data`/`body`/`serializedMessage` message payload 别名；payload 只有 `role`/`content` 时也能 materialize 成 transcript message。
 - 本轮补充：transcript resume 的嵌套 content block 接受 `toolUseId`/`toolUseID`、`isError`、`cacheControl`、`cacheReference` 字段别名，并保留 cache edit 的 `cacheReference`。

docs/first-second-parity-audit.md

@@ -361,6 +361,7 @@ M7 progress now includes:
 - `internal/session`: remote-history event arrays now unwrap element-level wrappers such as `event`/`record`/`entry`/`item`/`resource`/`value` and wrapper-only `data`/`payload`/`body`, using element cursors as event ID fallback outside GraphQL edges.
 - `internal/session`: remote-history event arrays now accept JSON:API/resource-style elements with event payloads inside `attributes` or `properties`, preserving the outer resource `id` as the SDK event ID fallback.
 - `internal/session`: remote-history response parsing now recurses through page-level JSON:API/resource `attributes`/`properties` wrappers, accepts `list`/`object`/`objects` as event-list aliases, and treats a single `data.attributes` resource payload as one SDK event.
+- `internal/session`: remote-history response parsing now accepts JSON:API `included` collections, filters out non-event resources, and recursively unwraps resource/attributes/properties event payloads while preserving resource ID fallbacks.
 - `internal/contracts`/`internal/session`: content block `type` decoding now normalizes camel/kebab/compact aliases such as `toolUse`, `tool-result`, `cacheEdits`, `inputImage`, and `chain-of-thought`.
 - `internal/session`: image history dimensions now default display size to original size when only `width`/`height` or original dimensions are present, preserving source metadata for single-size image fixtures.
 - `internal/session`: pasted-content history type decoding now normalizes aliases such as `inputImage`/`pasted-image`/`input_text`/`pasted-text` to canonical `image`/`text` for runtime and stored history.

internal/session/remote_history.go

@@ -65,6 +65,7 @@ type sessionEventsResponse struct {
 	History              []contracts.SDKEvent `json:"history"`
 	Nodes                []contracts.SDKEvent `json:"nodes"`
 	Edges                []contracts.SDKEvent `json:"edges"`
+	Included             []contracts.SDKEvent `json:"included"`
 	HasMore              bool                 `json:"has_more"`
 	HasMoreCamel         bool                 `json:"hasMore"`
 	HasNext              bool                 `json:"has_next"`
@@ -204,6 +205,15 @@ func (r *sessionEventsResponse) mergeJSON(data []byte) error {
 			return err
 		}
 	}
+	if value, ok := raw["included"]; ok {
+		events, ok, err := decodeRemoteHistoryFilteredEventArray("included", value)
+		if err != nil {
+			return err
+		}
+		if ok && r.Included == nil {
+			r.Included = events
+		}
+	}
 	return nil
 }
 
@@ -494,6 +504,9 @@ func (r *sessionEventsResponse) mergeFrom(other sessionEventsResponse) {
 	if r.Edges == nil {
 		r.Edges = other.Edges
 	}
+	if r.Included == nil {
+		r.Included = other.Included
+	}
 	r.mergePageFields(other)
 }
 
@@ -678,6 +691,35 @@ func decodeRemoteHistoryEventArray(name string, data json.RawMessage) ([]contrac
 	return events, nil
 }
 
+func decodeRemoteHistoryFilteredEventArray(name string, data json.RawMessage) ([]contracts.SDKEvent, bool, error) {
+	data = bytes.TrimSpace(data)
+	if len(data) == 0 || bytes.Equal(data, []byte("null")) {
+		return nil, false, nil
+	}
+	if data[0] != '[' {
+		return nil, false, fmt.Errorf("%s must be an event array", name)
+	}
+	var rawEvents []json.RawMessage
+	if err := json.Unmarshal(data, &rawEvents); err != nil {
+		return nil, false, fmt.Errorf("%s: %w", name, err)
+	}
+	events := make([]contracts.SDKEvent, 0, len(rawEvents))
+	for index, rawEvent := range rawEvents {
+		if !remoteHistoryRawLooksLikeEvent(rawEvent) {
+			continue
+		}
+		event, err := decodeRemoteHistoryEventElement(name, index, rawEvent)
+		if err != nil {
+			return nil, false, err
+		}
+		events = append(events, event)
+	}
+	if len(events) == 0 {
+		return nil, false, nil
+	}
+	return events, true, nil
+}
+
 func decodeRemoteHistoryEventMap(name string, data json.RawMessage) ([]contracts.SDKEvent, bool, error) {
 	var rawEvents map[string]json.RawMessage
 	if err := json.Unmarshal(data, &rawEvents); err != nil {
@@ -722,7 +764,7 @@ func decodeRemoteHistoryEventMap(name string, data json.RawMessage) ([]contracts
 func remoteHistoryEventMapReservedKey(key string) bool {
 	switch key {
 	case "page", "pagination", "page_info", "pageInfo", "paging", "links", "_links", "meta", "metadata",
-		"attributes", "properties",
+		"attributes", "properties", "included",
 		"has_more", "hasMore", "has_next", "hasNext", "has_next_page", "hasNextPage",
 		"has_previous", "hasPrevious", "has_previous_page", "hasPreviousPage", "has_older", "hasOlder", "more",
 		"first_id", "firstId", "next_before_id", "nextBeforeId", "next_cursor", "nextCursor",
@@ -741,6 +783,24 @@ func remoteHistoryEventMapReservedKey(key string) bool {
 	}
 }
 
+func remoteHistoryRawLooksLikeEvent(data json.RawMessage) bool {
+	data = bytes.TrimSpace(data)
+	if len(data) == 0 || bytes.Equal(data, []byte("null")) || data[0] != '{' {
+		return false
+	}
+	var fields map[string]json.RawMessage
+	if err := json.Unmarshal(data, &fields); err != nil {
+		return false
+	}
+	if remoteHistoryLooksLikeSingleEvent(fields) {
+		return true
+	}
+	if nested := remoteHistoryWrappedEventRaw(fields); nested != nil {
+		return remoteHistoryRawLooksLikeEvent(nested)
+	}
+	return false
+}
+
 func decodeRemoteHistoryEventElement(name string, index int, data json.RawMessage) (contracts.SDKEvent, error) {
 	data = bytes.TrimSpace(data)
 	if len(data) == 0 || bytes.Equal(data, []byte("null")) {
@@ -749,15 +809,22 @@ func decodeRemoteHistoryEventElement(name string, index int, data json.RawMessag
 	cursor := ""
 	resourceID := ""
 	rawEvent := data
-	if data[0] == '{' {
+	for len(rawEvent) > 0 && rawEvent[0] == '{' {
 		var fields map[string]json.RawMessage
-		if err := json.Unmarshal(data, &fields); err == nil {
-			cursor = remoteHistoryStringField(fields, "cursor")
-			resourceID = remoteHistoryStringField(fields, "id", "event_id", "eventId", "uuid")
-			if nested := remoteHistoryWrappedEventRaw(fields); nested != nil {
-				rawEvent = nested
-			}
+		if err := json.Unmarshal(rawEvent, &fields); err != nil {
+			break
+		}
+		cursor = firstNonEmpty(cursor, remoteHistoryStringField(fields, "cursor"))
+		resourceID = firstNonEmpty(resourceID, remoteHistoryStringField(fields, "id", "event_id", "eventId", "uuid"))
+		nested := remoteHistoryWrappedEventRaw(fields)
+		if nested == nil {
+			break
+		}
+		nested = bytes.TrimSpace(nested)
+		if len(nested) == 0 || bytes.Equal(nested, rawEvent) {
+			break
 		}
+		rawEvent = nested
 	}
 	var event contracts.SDKEvent
 	if err := json.Unmarshal(rawEvent, &event); err != nil {
@@ -1391,7 +1458,7 @@ func firstEventList(values ...[]contracts.SDKEvent) []contracts.SDKEvent {
 }
 
 func responseEventList(response sessionEventsResponse) []contracts.SDKEvent {
-	return firstEventList(response.Data, response.Events, response.Items, response.Results, response.Value, response.Values, response.Resources, response.Collection, response.Records, response.Rows, response.Entries, response.Messages, response.History, response.Nodes, response.Edges)
+	return firstEventList(response.Data, response.Events, response.Items, response.Results, response.Value, response.Values, response.Resources, response.Collection, response.Records, response.Rows, response.Entries, response.Messages, response.History, response.Nodes, response.Edges, response.Included)
 }
 
 func cloneHeader(header http.Header) http.Header {

internal/session/remote_history_test.go

@@ -988,6 +988,41 @@ func TestFetchRemoteHistoryAcceptsResourcePageAttributes(t *testing.T) {
 	}
 }
 
+func TestFetchRemoteHistoryAcceptsIncludedResourceEvents(t *testing.T) {
+	var seen []url.Values
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		seen = append(seen, r.URL.Query())
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{
+			"included": [
+				{"id":"tool_1","type":"tool","attributes":{"name":"Bash"}},
+				{"id":"evt_included_status","type":"session-events","attributes":{"eventType":"status","sessionID":"s","status":"included"}},
+				{"resource":{"id":"evt_included_assistant","type":"session-events","properties":{"role":"assistant","sessionId":"s","createdAt":"2026-01-01T00:00:02Z","message":{"type":"assistant","content":[{"type":"text","text":"hello included"}]}}}}
+			],
+			"pageInfo": {"hasPreviousPage": false}
+		}`))
+	}))
+	defer server.Close()
+
+	authCtx := NewRemoteHistoryAuthContext("s", "token", "", auth.OAuthConfig{BaseAPIURL: server.URL})
+	events, err := FetchRemoteHistory(context.Background(), server.Client(), authCtx, RemoteHistoryFetchOptions{Limit: 3})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !events.Complete || events.Pages != 1 || len(events.Events) != 2 || events.NextBeforeID != "" {
+		t.Fatalf("events = %#v", events)
+	}
+	if events.Events[0].ID != "evt_included_status" || events.Events[0].Status != "included" || events.Events[0].SessionID != "s" {
+		t.Fatalf("status included event = %#v", events.Events[0])
+	}
+	if events.Events[1].ID != "evt_included_assistant" || events.Events[1].Type != contracts.SDKEventAssistant || events.Events[1].Message == nil || len(events.Events[1].Message.Content) != 1 || events.Events[1].Message.Content[0].Text != "hello included" {
+		t.Fatalf("assistant included event = %#v", events.Events[1])
+	}
+	if len(seen) != 1 {
+		t.Fatalf("queries = %#v", seen)
+	}
+}
+
 func TestFetchRemoteHistoryAcceptsKeyedEventMaps(t *testing.T) {
 	var seen []url.Values
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {