Add optional _meta slot to SystemNotificationResponsePart

[colbylwilliams]

Summary

Closes #307.

SystemNotificationResponsePart conveys a harness event as human-readable content only. There is no machine-readable indication of what triggered it, so a client cannot categorize, icon, group, filter, or localize these parts without string-matching natural-language prose. This adds the standard _meta escape hatch to close that gap.

export interface SystemNotificationResponsePart {
  kind: ResponsePartKind.SystemNotification;
  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<string, unknown>;
}

Why

• _meta?: Record<string, unknown> is the established escape hatch across AHP state carriers (Message, ChatState, UsageInfo, ErrorInfo, RootState, ToolDefinition, session types, …), mirroring the MCP _meta convention. No response-part type carried one before — and the system notification, whose whole purpose is to surface an out-of-band harness event, is the part that most needs it.
• It fits the doctrine's "escape hatches are explicit" principle: provider-specific metadata is allowed but never required for the baseline experience. A minimal client ignores _meta and still renders coherently from content; a typed trigger discriminator can graduate out of _meta later if a portable subset proves worthwhile.

Compatibility

Purely additive and optional. Existing clients ignore _meta; hosts that omit it stay compliant. No reducer change is required — SystemNotificationResponsePart is delivered via the existing ChatResponsePartAction, whose reducer appends the part wholesale, so _meta rides through unchanged.

Changes

• types/channels-chat/state.ts — add the _meta slot with a convention-matching doc comment.
• Generated mirrors — regenerated the JSON Schema and all five client mirrors (Rust, Kotlin, Swift, TypeScript, Go).
• docs/guide/state-model.md — document SystemNotificationResponsePart in the Response Parts section (it was previously missing) and describe the _meta slot.
• CHANGELOGs — added an ### Added entry under ## [0.5.2] — Unreleased in the spec changelog and every per-client changelog.

[Copilot]

Pull request overview

Adds a convention-aligned, optional _meta metadata bag to SystemNotificationResponsePart so hosts can attach machine-readable trigger descriptors while preserving coherent rendering from content alone. This extends the existing _meta escape-hatch pattern to response parts and propagates the additive change through schemas, docs, generated clients, and release notes.

Changes:

• Add optional _meta?: Record<string, unknown> to SystemNotificationResponsePart in the protocol types.
• Regenerate JSON Schemas and all client mirrors to include the new optional field on the wire (_meta) with language-idiomatic property names.
• Document the response part in the state model guide and record the additive change in the spec + per-client changelogs.

Show a summary per file

File	Description
types/channels-chat/state.ts	Adds optional _meta on SystemNotificationResponsePart with usage guidance.
schema/state.schema.json	Updates schema for SystemNotificationResponsePart to include optional _meta.
schema/notifications.schema.json	Propagates optional _meta into the notifications schema mirror.
schema/errors.schema.json	Propagates optional _meta into the errors schema mirror.
schema/commands.schema.json	Propagates optional _meta into the commands schema mirror.
schema/actions.schema.json	Propagates optional _meta into the actions schema mirror.
docs/guide/state-model.md	Documents SystemNotificationResponsePart (including _meta) in the Response Parts section.
CHANGELOG.md	Adds spec changelog bullet for the new optional _meta slot.
clients/typescript/CHANGELOG.md	Notes the additive TypeScript surface change (_meta?: Record<string, unknown>).
clients/swift/CHANGELOG.md	Notes the additive Swift surface change (meta serialized as _meta).
clients/swift/AgentHostProtocol/Sources/AgentHostProtocol/Generated/State.generated.swift	Regenerated Swift types to include meta ↔ _meta coding key and initializer default.
clients/rust/crates/ahp-types/src/state.rs	Regenerated Rust types to include optional meta field serialized as _meta.
clients/rust/CHANGELOG.md	Notes the additive Rust surface change (meta / _meta).
clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/State.generated.kt	Regenerated Kotlin types to include optional meta with @SerialName("_meta").
clients/kotlin/CHANGELOG.md	Notes the additive Kotlin surface change (meta serialized as _meta).
clients/go/ahptypes/state.generated.go	Regenerated Go types to include optional Meta (json:"_meta,omitempty").
clients/go/CHANGELOG.md	Notes the additive Go surface change (Meta / _meta).

Review details

• Files reviewed: 15/17 changed files
• Comments generated: 0
• Review effort level: Low

[roblourens]

This is fine, but is there some origin that would make sense as a real property?

[connor4312]

There is no machine-readable indication of what triggered it, so a client cannot categorize, icon, group, filter, or localize these parts without string-matching natural-language prose

Yea, there is still not, at least not in a standard way. Do we want to actually be more descriptive here?

[colbylwilliams]

@roblourens @connor4312

Agreed. I started with _meta here, but the linked issue calls out kind or something similar (like origin) as a proposed follow up. Happy to do both here, or separately. Just say the word.

[connor4312]

Let's start here but plan to formalize more data in the future