Derive session event envelopes across SDKs

Share schema-level session event envelope discovery across code generators and use it for Go and Python session-event wrappers so top-level envelope fields like agentId round-trip consistently.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: stephentoub

go/generated_session_events.go

@@ -0,0 +1,78 @@
+package copilot
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestSessionEventAgentIDRoundTripsKnownEvent(t *testing.T) {
+	event, err := UnmarshalSessionEvent([]byte(`{
+		"id": "00000000-0000-0000-0000-000000000001",
+		"timestamp": "2026-01-01T00:00:00Z",
+		"parentId": null,
+		"agentId": "agent-1",
+		"type": "user.message",
+		"data": {
+			"content": "Hello"
+		}
+	}`))
+	if err != nil {
+		t.Fatalf("failed to unmarshal session event: %v", err)
+	}
+
+	if event.AgentID == nil || *event.AgentID != "agent-1" {
+		t.Fatalf("expected agent ID to round-trip, got %v", event.AgentID)
+	}
+	if _, ok := event.Data.(*UserMessageData); !ok {
+		t.Fatalf("expected user message data, got %T", event.Data)
+	}
+
+	data, err := event.Marshal()
+	if err != nil {
+		t.Fatalf("failed to marshal session event: %v", err)
+	}
+
+	var serialized map[string]any
+	if err := json.Unmarshal(data, &serialized); err != nil {
+		t.Fatalf("failed to unmarshal serialized session event: %v", err)
+	}
+	if serialized["agentId"] != "agent-1" {
+		t.Fatalf("expected serialized agentId to round-trip, got %v", serialized["agentId"])
+	}
+}
+
+func TestSessionEventAgentIDRoundTripsUnknownEvent(t *testing.T) {
+	event, err := UnmarshalSessionEvent([]byte(`{
+		"id": "00000000-0000-0000-0000-000000000002",
+		"timestamp": "2026-01-01T00:00:00Z",
+		"parentId": null,
+		"agentId": "future-agent",
+		"type": "future.feature_from_server",
+		"data": {
+			"key": "value"
+		}
+	}`))
+	if err != nil {
+		t.Fatalf("failed to unmarshal session event: %v", err)
+	}
+
+	if event.AgentID == nil || *event.AgentID != "future-agent" {
+		t.Fatalf("expected agent ID to round-trip, got %v", event.AgentID)
+	}
+	if _, ok := event.Data.(*RawSessionEventData); !ok {
+		t.Fatalf("expected raw session event data, got %T", event.Data)
+	}
+
+	data, err := event.Marshal()
+	if err != nil {
+		t.Fatalf("failed to marshal session event: %v", err)
+	}
+
+	var serialized map[string]any
+	if err := json.Unmarshal(data, &serialized); err != nil {
+		t.Fatalf("failed to unmarshal serialized session event: %v", err)
+	}
+	if serialized["agentId"] != "future-agent" {
+		t.Fatalf("expected serialized agentId to round-trip, got %v", serialized["agentId"])
+	}
+}

go/session_event_serialization_test.go

@@ -24,6 +24,7 @@
     UserMessageAgentMode,
     UserMessageAttachmentGithubReferenceType,
     session_event_from_dict,
+    session_event_to_dict,
 )
 
 
@@ -47,6 +48,39 @@ def test_unknown_event_type_maps_to_unknown(self):
         event = session_event_from_dict(unknown_event)
         assert event.type == SessionEventType.UNKNOWN, f"Expected UNKNOWN, got {event.type}"
 
+    def test_known_event_preserves_top_level_agent_id(self):
+        """Known events should preserve the top-level sub-agent envelope ID."""
+        known_event = {
+            "id": str(uuid4()),
+            "timestamp": datetime.now().isoformat(),
+            "parentId": None,
+            "agentId": "agent-1",
+            "type": "user.message",
+            "data": {"content": "Hello"},
+        }
+
+        event = session_event_from_dict(known_event)
+        assert event.agent_id == "agent-1"
+        assert session_event_to_dict(event)["agentId"] == "agent-1"
+
+    def test_unknown_event_preserves_top_level_agent_id(self):
+        """Unknown events should preserve the top-level sub-agent envelope ID."""
+        unknown_event = {
+            "id": str(uuid4()),
+            "timestamp": datetime.now().isoformat(),
+            "parentId": None,
+            "agentId": "future-agent",
+            "type": "session.future_feature_from_server",
+            "data": {"key": "value"},
+        }
+
+        event = session_event_from_dict(unknown_event)
+        assert event.type == SessionEventType.UNKNOWN
+        assert event.agent_id == "future-agent"
+        serialized = session_event_to_dict(event)
+        assert serialized["agentId"] == "future-agent"
+        assert serialized["type"] == "session.future_feature_from_server"
+
     def test_malformed_uuid_raises_error(self):
         """Malformed UUIDs should raise ValueError for visibility, not be suppressed."""
         malformed_event = {

python/copilot/generated/session_events.py

@@ -31,10 +31,13 @@ import {
     isObjectSchema,
     isVoidSchema,
     getNullableInner,
+    getSessionEventVariantSchemas,
+    getSharedSessionEventEnvelopeProperties,
     REPO_ROOT,
     type ApiSchema,
     type DefinitionCollections,
     type RpcMethod,
+    type SessionEventEnvelopeProperty,
 } from "./utils.js";
 
 const execFileAsync = promisify(execFile);
@@ -317,12 +320,6 @@ interface EventVariant {
     dataDescription?: string;
 }
 
-interface EventEnvelopeProperty {
-    name: string;
-    schema: JSONSchema7;
-    required: boolean;
-}
-
 let generatedEnums = new Map<string, { enumName: string; values: string[] }>();
 
 /** Schema definitions available during session event generation (for $ref resolution). */
@@ -369,63 +366,6 @@ function extractEventVariants(schema: JSONSchema7): EventVariant[] {
         });
 }
 
-function getSessionEventVariantSchemas(
-    schema: JSONSchema7,
-    definitionCollections: DefinitionCollections = collectDefinitionCollections(schema as Record<string, unknown>)
-): JSONSchema7[] {
-    const sessionEvent =
-        resolveSchema({ $ref: "#/definitions/SessionEvent" }, definitionCollections) ??
-        resolveSchema({ $ref: "#/$defs/SessionEvent" }, definitionCollections);
-    if (!sessionEvent?.anyOf) throw new Error("Schema must have SessionEvent definition with anyOf");
-
-    return sessionEvent.anyOf.map((variant) => {
-        const resolvedVariant =
-            resolveObjectSchema(variant as JSONSchema7, definitionCollections) ??
-            resolveSchema(variant as JSONSchema7, definitionCollections) ??
-            (variant as JSONSchema7);
-        if (typeof resolvedVariant !== "object" || !resolvedVariant.properties) throw new Error("Invalid variant");
-        return resolvedVariant;
-    });
-}
-
-function getSharedEventEnvelopeProperties(schema: JSONSchema7): EventEnvelopeProperty[] {
-    const variants = getSessionEventVariantSchemas(schema, sessionDefinitions);
-    const firstVariant = variants[0];
-    const firstProperties = firstVariant.properties ?? {};
-
-    return Object.entries(firstProperties)
-        .filter(([name]) => name !== "type" && name !== "data")
-        .map(([name]) => {
-            const propertySchemas = variants
-                .map((variant) => variant.properties?.[name])
-                .filter((propSchema): propSchema is JSONSchema7 => typeof propSchema === "object" && propSchema !== null);
-
-            if (propertySchemas.length !== variants.length) return undefined;
-
-            return {
-                name,
-                schema: selectEnvelopePropertySchema(propertySchemas),
-                required: variants.every((variant) => (variant.required ?? []).includes(name)),
-            };
-        })
-        .filter((property): property is EventEnvelopeProperty => property !== undefined);
-}
-
-function selectEnvelopePropertySchema(propertySchemas: JSONSchema7[]): JSONSchema7 {
-    // Some variants further constrain a shared envelope property, e.g. ephemeral const true.
-    // Generate the base property from the least restrictive schema that has useful metadata.
-    return (
-        propertySchemas.find((schema) => !isConstOrEnumSchema(schema) && schema.description) ??
-        propertySchemas.find((schema) => !isConstOrEnumSchema(schema)) ??
-        propertySchemas.find((schema) => schema.description) ??
-        propertySchemas[0]
-    );
-}
-
-function isConstOrEnumSchema(schema: JSONSchema7): boolean {
-    return "const" in schema || (Array.isArray(schema.enum) && schema.enum.length > 0);
-}
-
 /**
  * Find a discriminator property shared by all variants in an anyOf.
  */
@@ -732,7 +672,7 @@ function generateDataClass(variant: EventVariant, knownTypes: Map<string, string
 }
 
 function emitSessionEventEnvelopeProperty(
-    property: EventEnvelopeProperty,
+    property: SessionEventEnvelopeProperty,
     knownTypes: Map<string, string>,
     nestedClasses: Map<string, string>,
     enumOutput: string[]
@@ -767,7 +707,7 @@ function generateSessionEventsCode(schema: JSONSchema7): string {
     const knownTypes = new Map<string, string>();
     const nestedClasses = new Map<string, string>();
     const enumOutput: string[] = [];
-    const envelopeProperties = getSharedEventEnvelopeProperties(schema);
+    const envelopeProperties = getSharedSessionEventEnvelopeProperties(schema, sessionDefinitions);
 
     const lines: string[] = [];
     lines.push(`${COPYRIGHT}