diff --git a/clients/go/ahptypes/state.generated.go b/clients/go/ahptypes/state.generated.go index ec45d39a..09d345d4 100644 --- a/clients/go/ahptypes/state.generated.go +++ b/clients/go/ahptypes/state.generated.go @@ -1645,6 +1645,14 @@ type SystemNotificationResponsePart struct { Kind ResponsePartKind `json:"kind"` // The text of the system notification Content StringOrMarkdown `json:"content"` + // Additional provider-specific metadata for this notification. + // + // A host MAY attach a machine-readable descriptor of what triggered the + // notification so clients can categorize, icon, group, filter, or localize + // it without parsing `content`. Clients MAY look for well-known keys here to + // provide enhanced UI, and MUST render coherently from `content` alone when + // `_meta` is absent or unrecognized. + Meta map[string]json.RawMessage `json:"_meta,omitempty"` } // A resolved input request (elicitation) recorded in the turn transcript. diff --git a/clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/State.generated.kt b/clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/State.generated.kt index c44bc9ad..babb1ec2 100644 --- a/clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/State.generated.kt +++ b/clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/State.generated.kt @@ -2289,7 +2289,18 @@ data class SystemNotificationResponsePart( /** * The text of the system notification */ - val content: StringOrMarkdown + val content: StringOrMarkdown, + /** + * Additional provider-specific metadata for this notification. + * + * A host MAY attach a machine-readable descriptor of what triggered the + * notification so clients can categorize, icon, group, filter, or localize + * it without parsing `content`. Clients MAY look for well-known keys here to + * provide enhanced UI, and MUST render coherently from `content` alone when + * `_meta` is absent or unrecognized. + */ + @SerialName("_meta") + val meta: Map? = null ) @Serializable diff --git a/clients/rust/crates/ahp-types/src/state.rs b/clients/rust/crates/ahp-types/src/state.rs index bee02b04..6775f54e 100644 --- a/clients/rust/crates/ahp-types/src/state.rs +++ b/clients/rust/crates/ahp-types/src/state.rs @@ -2062,6 +2062,15 @@ pub struct ReasoningResponsePart { pub struct SystemNotificationResponsePart { /// The text of the system notification pub content: StringOrMarkdown, + /// Additional provider-specific metadata for this notification. + /// + /// A host MAY attach a machine-readable descriptor of what triggered the + /// notification so clients can categorize, icon, group, filter, or localize + /// it without parsing `content`. Clients MAY look for well-known keys here to + /// provide enhanced UI, and MUST render coherently from `content` alone when + /// `_meta` is absent or unrecognized. + #[serde(rename = "_meta", default, skip_serializing_if = "Option::is_none")] + pub meta: Option, } /// A resolved input request (elicitation) recorded in the turn transcript. diff --git a/clients/swift/AgentHostProtocol/Sources/AgentHostProtocol/Generated/State.generated.swift b/clients/swift/AgentHostProtocol/Sources/AgentHostProtocol/Generated/State.generated.swift index 277d8659..9a6990fc 100644 --- a/clients/swift/AgentHostProtocol/Sources/AgentHostProtocol/Generated/State.generated.swift +++ b/clients/swift/AgentHostProtocol/Sources/AgentHostProtocol/Generated/State.generated.swift @@ -2291,13 +2291,29 @@ public struct SystemNotificationResponsePart: Codable, Sendable { public var kind: ResponsePartKind /// The text of the system notification public var content: StringOrMarkdown + /// Additional provider-specific metadata for this notification. + /// + /// A host MAY attach a machine-readable descriptor of what triggered the + /// notification so clients can categorize, icon, group, filter, or localize + /// it without parsing `content`. Clients MAY look for well-known keys here to + /// provide enhanced UI, and MUST render coherently from `content` alone when + /// `_meta` is absent or unrecognized. + public var meta: [String: AnyCodable]? + + enum CodingKeys: String, CodingKey { + case kind + case content + case meta = "_meta" + } public init( kind: ResponsePartKind, - content: StringOrMarkdown + content: StringOrMarkdown, + meta: [String: AnyCodable]? = nil ) { self.kind = kind self.content = content + self.meta = meta } } diff --git a/docs/.changes/20260709-system-notification-meta-slot.json b/docs/.changes/20260709-system-notification-meta-slot.json new file mode 100644 index 00000000..c82dec3e --- /dev/null +++ b/docs/.changes/20260709-system-notification-meta-slot.json @@ -0,0 +1,5 @@ +{ + "type": "added", + "message": "Optional `_meta` slot on `SystemNotificationResponsePart`, following the MCP `_meta` convention. A host MAY attach a machine-readable descriptor of what triggered the notification so clients can categorize, icon, group, filter, or localize it without parsing `content`.", + "issues": [308] +} diff --git a/docs/guide/state-model.md b/docs/guide/state-model.md index 558208b3..7f0d67fa 100644 --- a/docs/guide/state-model.md +++ b/docs/guide/state-model.md @@ -324,6 +324,7 @@ ContentRef { SystemNotificationResponsePart { kind: 'systemNotification' content: StringOrMarkdown + _meta?: Record // machine-readable trigger metadata; see below } // Durable record of a resolved input request (see Input Requests below) @@ -334,6 +335,8 @@ InputRequestResponsePart { } ``` +`SystemNotificationResponsePart._meta` carries provider-specific metadata describing what triggered the notification. A host MAY attach a machine-readable descriptor so clients can categorize, icon, group, filter, or localize the notification without parsing `content`. Clients MAY inspect well-known keys for enhanced UI, and MUST render coherently from `content` alone when `_meta` is absent or unrecognized. + Text content uses a **create-then-append** pattern: the server first emits a `chat/responsePart` action to create a new markdown (or reasoning) part with an `id`, then streams text into it via `chat/delta` (or `chat/reasoning`) actions targeting that `partId`. This pattern is extensible to future streaming content types. Clients fetch `ContentRef` content separately via the `resourceRead(uri)` command. This keeps the state tree small and serializable. diff --git a/schema/actions.schema.json b/schema/actions.schema.json index 65ab0c2d..038c7b4c 100644 --- a/schema/actions.schema.json +++ b/schema/actions.schema.json @@ -5221,6 +5221,11 @@ "content": { "$ref": "#/$defs/StringOrMarkdown", "description": "The text of the system notification" + }, + "_meta": { + "type": "object", + "additionalProperties": {}, + "description": "Additional provider-specific metadata for this notification.\n\nA host MAY attach a machine-readable descriptor of what triggered the\nnotification so clients can categorize, icon, group, filter, or localize\nit without parsing `content`. Clients MAY look for well-known keys here to\nprovide enhanced UI, and MUST render coherently from `content` alone when\n`_meta` is absent or unrecognized." } }, "required": [ diff --git a/schema/commands.schema.json b/schema/commands.schema.json index 4d28f218..c1b658c8 100644 --- a/schema/commands.schema.json +++ b/schema/commands.schema.json @@ -4509,6 +4509,11 @@ "content": { "$ref": "#/$defs/StringOrMarkdown", "description": "The text of the system notification" + }, + "_meta": { + "type": "object", + "additionalProperties": {}, + "description": "Additional provider-specific metadata for this notification.\n\nA host MAY attach a machine-readable descriptor of what triggered the\nnotification so clients can categorize, icon, group, filter, or localize\nit without parsing `content`. Clients MAY look for well-known keys here to\nprovide enhanced UI, and MUST render coherently from `content` alone when\n`_meta` is absent or unrecognized." } }, "required": [ diff --git a/schema/errors.schema.json b/schema/errors.schema.json index a35f6122..f64961ff 100644 --- a/schema/errors.schema.json +++ b/schema/errors.schema.json @@ -3300,6 +3300,11 @@ "content": { "$ref": "#/$defs/StringOrMarkdown", "description": "The text of the system notification" + }, + "_meta": { + "type": "object", + "additionalProperties": {}, + "description": "Additional provider-specific metadata for this notification.\n\nA host MAY attach a machine-readable descriptor of what triggered the\nnotification so clients can categorize, icon, group, filter, or localize\nit without parsing `content`. Clients MAY look for well-known keys here to\nprovide enhanced UI, and MUST render coherently from `content` alone when\n`_meta` is absent or unrecognized." } }, "required": [ diff --git a/schema/notifications.schema.json b/schema/notifications.schema.json index 4bce2189..3c534515 100644 --- a/schema/notifications.schema.json +++ b/schema/notifications.schema.json @@ -3460,6 +3460,11 @@ "content": { "$ref": "#/$defs/StringOrMarkdown", "description": "The text of the system notification" + }, + "_meta": { + "type": "object", + "additionalProperties": {}, + "description": "Additional provider-specific metadata for this notification.\n\nA host MAY attach a machine-readable descriptor of what triggered the\nnotification so clients can categorize, icon, group, filter, or localize\nit without parsing `content`. Clients MAY look for well-known keys here to\nprovide enhanced UI, and MUST render coherently from `content` alone when\n`_meta` is absent or unrecognized." } }, "required": [ diff --git a/schema/state.schema.json b/schema/state.schema.json index 14045ce1..7a107af7 100644 --- a/schema/state.schema.json +++ b/schema/state.schema.json @@ -3211,6 +3211,11 @@ "content": { "$ref": "#/$defs/StringOrMarkdown", "description": "The text of the system notification" + }, + "_meta": { + "type": "object", + "additionalProperties": {}, + "description": "Additional provider-specific metadata for this notification.\n\nA host MAY attach a machine-readable descriptor of what triggered the\nnotification so clients can categorize, icon, group, filter, or localize\nit without parsing `content`. Clients MAY look for well-known keys here to\nprovide enhanced UI, and MUST render coherently from `content` alone when\n`_meta` is absent or unrecognized." } }, "required": [ diff --git a/types/channels-chat/state.ts b/types/channels-chat/state.ts index 38d4f5bd..00e6f689 100644 --- a/types/channels-chat/state.ts +++ b/types/channels-chat/state.ts @@ -884,6 +884,16 @@ export interface SystemNotificationResponsePart { kind: ResponsePartKind.SystemNotification; /** The text of the system notification */ content: StringOrMarkdown; + /** + * Additional provider-specific metadata for this notification. + * + * A host MAY attach a machine-readable descriptor of what triggered the + * notification so clients can categorize, icon, group, filter, or localize + * it without parsing `content`. Clients MAY look for well-known keys here to + * provide enhanced UI, and MUST render coherently from `content` alone when + * `_meta` is absent or unrecognized. + */ + _meta?: Record; }