Add a cross-client telemetry-names contract (+ Rust reference adoption)

clients/go/CHANGELOG.md

@@ -16,6 +16,12 @@ tag whose matching `## [X.Y.Z]` heading is missing from this file.
 
 ### Added
 
+- Generated telemetry-name constants (`telemetry.generated.go`) — the shared
+  cross-client self-instrumentation span / metric / attribute names, generated
+  from the `types/telemetry/registry.ts` contract so they stay identical across
+  clients. Includes the `host-event` / `host-subscription` / `host-resource` /
+  `host-snapshot` / `host-summaries` `ahp.stream` values for multi-host
+  dropped-event accounting.
 - `ChangesetOperationStatusDisabled` — new `ChangesetOperationStatus` value for
   operations that are currently unavailable and cannot be invoked.
 - `ChangesetOperation.Group` — optional identifier for grouping related

clients/go/ahptypes/telemetry.generated.go

@@ -0,0 +1,100 @@
+// Generated from types/*.ts — do not edit.
+//
+// Regenerate with: npm run generate:go
+
+package ahptypes
+
+// Cross-client telemetry NAMES — the self-instrumentation contract shared by every
+// AHP client, generated from types/telemetry/registry.ts. Only the names are shared;
+// the tracer / meter wiring is hand-written per language.
+
+const (
+	// Instrumentation-scope name used for every AHP self-instrumentation span and metric.
+	TelemetrySource = "Microsoft.AgentHostProtocol"
+
+	// Span names.
+	// Span covering a single JSON-RPC request, from send until it settles.
+	RequestSpan = "ahp.request"
+
+	// Metric names.
+	// Messages sent to the host, tagged by ahp.message.kind (request|notification).
+	MessagesSentMetric = "ahp.client.messages.sent"
+	// Messages received from the host.
+	MessagesReceivedMetric = "ahp.client.messages.received"
+	// Round-trip duration of a JSON-RPC request, tagged by rpc.method and ahp.outcome (ok|error|cancelled|timeout).
+	RequestDurationMetric = "ahp.client.request.duration"
+	// Requests awaiting a response.
+	RequestsInFlightMetric = "ahp.client.requests.in_flight"
+	// Subscriptions registered with the client (decremented on unsubscribe or shutdown).
+	SubscriptionsActiveMetric = "ahp.client.subscriptions.active"
+	// Reconnect operations, tagged by outcome.
+	ReconnectsMetric = "ahp.client.reconnects"
+	// Buffered events evicted under back-pressure (drop-oldest), tagged by stream.
+	EventsDroppedMetric = "ahp.client.events.dropped"
+	// Inbound frames that failed to decode and were skipped (protocol resync is the host’s responsibility).
+	FramesMalformedMetric = "ahp.client.frames.malformed"
+
+	// Metric units.
+	// Unit for the ahp.client.messages.sent metric.
+	MessagesSentUnit = "{message}"
+	// Unit for the ahp.client.messages.received metric.
+	MessagesReceivedUnit = "{message}"
+	// Unit for the ahp.client.request.duration metric.
+	RequestDurationUnit = "ms"
+	// Unit for the ahp.client.requests.in_flight metric.
+	RequestsInFlightUnit = "{request}"
+	// Unit for the ahp.client.subscriptions.active metric.
+	SubscriptionsActiveUnit = "{subscription}"
+	// Unit for the ahp.client.reconnects metric.
+	ReconnectsUnit = "{reconnect}"
+	// Unit for the ahp.client.events.dropped metric.
+	EventsDroppedUnit = "{event}"
+	// Unit for the ahp.client.frames.malformed metric.
+	FramesMalformedUnit = "{frame}"
+
+	// Attribute keys.
+	// RPC system identifier (OTel rpc.system); always "jsonrpc" for AHP.
+	AttrRpcSystem = "rpc.system"
+	// JSON-RPC method name the span/metric is scoped to (OTel rpc.method).
+	AttrRpcMethod = "rpc.method"
+	// Client-assigned JSON-RPC request id.
+	AttrRequestId = "ahp.request.id"
+	// Terminal outcome of a request or reconnect (ok|error|cancelled|timeout).
+	AttrOutcome = "ahp.outcome"
+	// Whether a sent message was a request or a notification.
+	AttrMessageKind = "ahp.message.kind"
+	// Which event stream a dropped or observed event belongs to.
+	AttrStream = "ahp.stream"
+
+	// Attribute values.
+	// JSON-RPC — the only RPC system AHP uses.
+	RpcSystemJsonrpc = "jsonrpc"
+	// The request or reconnect completed successfully.
+	OutcomeOk = "ok"
+	// The request or reconnect failed with an error response.
+	OutcomeError = "error"
+	// The request was cancelled before it settled.
+	OutcomeCancelled = "cancelled"
+	// The request exceeded its configured timeout.
+	OutcomeTimeout = "timeout"
+	// A JSON-RPC request (expects a response).
+	MessageKindRequest = "request"
+	// A JSON-RPC notification (fire-and-forget).
+	MessageKindNotification = "notification"
+	// A per-resource subscription stream.
+	StreamSubscription = "subscription"
+	// The client-wide event stream.
+	StreamEvent = "event"
+	// A state-snapshot stream.
+	StreamState = "state"
+	// A multi-host client's host-event delivery stream.
+	StreamHostEvent = "host-event"
+	// A multi-host client's host-subscription delivery stream.
+	StreamHostSubscription = "host-subscription"
+	// A multi-host client's host-resource delivery stream.
+	StreamHostResource = "host-resource"
+	// A multi-host client's host-snapshot delivery stream.
+	StreamHostSnapshot = "host-snapshot"
+	// A multi-host client's host-summaries delivery stream.
+	StreamHostSummaries = "host-summaries"
+)

clients/kotlin/CHANGELOG.md

@@ -17,6 +17,12 @@ versions (`*-SNAPSHOT`) are explicitly rejected by the publish pipeline; bump
 
 ### Added
 
+- Generated `AhpTelemetryNames` object — the shared cross-client
+  self-instrumentation span / metric / attribute name constants, generated from
+  the `types/telemetry/registry.ts` contract so they stay identical across
+  clients. Includes the `host-event` / `host-subscription` / `host-resource` /
+  `host-snapshot` / `host-summaries` `ahp.stream` values for multi-host
+  dropped-event accounting.
 - `ChangesetOperationStatus.Disabled` — new enum value for changeset
   operations that are currently unavailable and cannot be invoked.
 - `ChangesetOperation.group` — optional identifier for grouping related

clients/kotlin/src/main/kotlin/com/microsoft/agenthostprotocol/generated/Telemetry.generated.kt

@@ -0,0 +1,101 @@
+// Generated from types/telemetry/registry.ts — do not edit
+
+package com.microsoft.agenthostprotocol.generated
+
+/**
+ * Cross-client telemetry NAMES — the self-instrumentation contract shared by every
+ * AHP client, generated from `types/telemetry/registry.ts`. Only the names are shared;
+ * the OpenTelemetry tracer / meter wiring is hand-written per language.
+ */
+object AhpTelemetryNames {
+
+    // ── Instrumentation scope ──
+    /** Instrumentation-scope name used for every AHP self-instrumentation span and metric. */
+    const val SOURCE: String = "Microsoft.AgentHostProtocol"
+
+    // ── Span names ──
+    /** Span covering a single JSON-RPC request, from send until it settles. */
+    const val REQUEST_SPAN: String = "ahp.request"
+
+    // ── Metric names ──
+    /** Messages sent to the host, tagged by ahp.message.kind (request|notification). */
+    const val MESSAGES_SENT: String = "ahp.client.messages.sent"
+    /** Messages received from the host. */
+    const val MESSAGES_RECEIVED: String = "ahp.client.messages.received"
+    /** Round-trip duration of a JSON-RPC request, tagged by rpc.method and ahp.outcome (ok|error|cancelled|timeout). */
+    const val REQUEST_DURATION: String = "ahp.client.request.duration"
+    /** Requests awaiting a response. */
+    const val REQUESTS_IN_FLIGHT: String = "ahp.client.requests.in_flight"
+    /** Subscriptions registered with the client (decremented on unsubscribe or shutdown). */
+    const val SUBSCRIPTIONS_ACTIVE: String = "ahp.client.subscriptions.active"
+    /** Reconnect operations, tagged by outcome. */
+    const val RECONNECTS: String = "ahp.client.reconnects"
+    /** Buffered events evicted under back-pressure (drop-oldest), tagged by stream. */
+    const val EVENTS_DROPPED: String = "ahp.client.events.dropped"
+    /** Inbound frames that failed to decode and were skipped (protocol resync is the host’s responsibility). */
+    const val FRAMES_MALFORMED: String = "ahp.client.frames.malformed"
+
+    // ── Metric units ──
+    /** Unit for the `ahp.client.messages.sent` metric. */
+    const val MESSAGES_SENT_UNIT: String = "{message}"
+    /** Unit for the `ahp.client.messages.received` metric. */
+    const val MESSAGES_RECEIVED_UNIT: String = "{message}"
+    /** Unit for the `ahp.client.request.duration` metric. */
+    const val REQUEST_DURATION_UNIT: String = "ms"
+    /** Unit for the `ahp.client.requests.in_flight` metric. */
+    const val REQUESTS_IN_FLIGHT_UNIT: String = "{request}"
+    /** Unit for the `ahp.client.subscriptions.active` metric. */
+    const val SUBSCRIPTIONS_ACTIVE_UNIT: String = "{subscription}"
+    /** Unit for the `ahp.client.reconnects` metric. */
+    const val RECONNECTS_UNIT: String = "{reconnect}"
+    /** Unit for the `ahp.client.events.dropped` metric. */
+    const val EVENTS_DROPPED_UNIT: String = "{event}"
+    /** Unit for the `ahp.client.frames.malformed` metric. */
+    const val FRAMES_MALFORMED_UNIT: String = "{frame}"
+
+    // ── Attribute keys ──
+    /** RPC system identifier (OTel rpc.system); always "jsonrpc" for AHP. */
+    const val ATTR_RPC_SYSTEM: String = "rpc.system"
+    /** JSON-RPC method name the span/metric is scoped to (OTel rpc.method). */
+    const val ATTR_RPC_METHOD: String = "rpc.method"
+    /** Client-assigned JSON-RPC request id. */
+    const val ATTR_REQUEST_ID: String = "ahp.request.id"
+    /** Terminal outcome of a request or reconnect (ok|error|cancelled|timeout). */
+    const val ATTR_OUTCOME: String = "ahp.outcome"
+    /** Whether a sent message was a request or a notification. */
+    const val ATTR_MESSAGE_KIND: String = "ahp.message.kind"
+    /** Which event stream a dropped or observed event belongs to. */
+    const val ATTR_STREAM: String = "ahp.stream"
+
+    // ── Attribute values ──
+    /** JSON-RPC — the only RPC system AHP uses. */
+    const val RPC_SYSTEM_JSONRPC: String = "jsonrpc"
+    /** The request or reconnect completed successfully. */
+    const val OUTCOME_OK: String = "ok"
+    /** The request or reconnect failed with an error response. */
+    const val OUTCOME_ERROR: String = "error"
+    /** The request was cancelled before it settled. */
+    const val OUTCOME_CANCELLED: String = "cancelled"
+    /** The request exceeded its configured timeout. */
+    const val OUTCOME_TIMEOUT: String = "timeout"
+    /** A JSON-RPC request (expects a response). */
+    const val MESSAGE_KIND_REQUEST: String = "request"
+    /** A JSON-RPC notification (fire-and-forget). */
+    const val MESSAGE_KIND_NOTIFICATION: String = "notification"
+    /** A per-resource subscription stream. */
+    const val STREAM_SUBSCRIPTION: String = "subscription"
+    /** The client-wide event stream. */
+    const val STREAM_EVENT: String = "event"
+    /** A state-snapshot stream. */
+    const val STREAM_STATE: String = "state"
+    /** A multi-host client's host-event delivery stream. */
+    const val STREAM_HOST_EVENT: String = "host-event"
+    /** A multi-host client's host-subscription delivery stream. */
+    const val STREAM_HOST_SUBSCRIPTION: String = "host-subscription"
+    /** A multi-host client's host-resource delivery stream. */
+    const val STREAM_HOST_RESOURCE: String = "host-resource"
+    /** A multi-host client's host-snapshot delivery stream. */
+    const val STREAM_HOST_SNAPSHOT: String = "host-snapshot"
+    /** A multi-host client's host-summaries delivery stream. */
+    const val STREAM_HOST_SUMMARIES: String = "host-summaries"
+}

clients/rust/CHANGELOG.md

@@ -19,6 +19,24 @@ matching `## [X.Y.Z]` heading is missing from this file.
 
 - `ahp_error_codes::CONFLICT` constant (`-32011`) added to `ahp-types`; covers ETag-conflict failures from `ResourceWriteParams.if_match` checks.
 - `apply_action_to_changeset`, `apply_action_to_annotations`, and `apply_action_to_resource_watch` reducers in `ahp`; all previously-skipped conformance fixtures for the `changeset`, `annotations`, and `resourceWatch` reducer families now pass.
+- Generated `telemetry` module (`ahp_types::telemetry`) — the shared
+  cross-client self-instrumentation span / metric / attribute name constants,
+  generated from the `types/telemetry/registry.ts` contract so they stay
+  identical across clients. Includes the `host-event` / `host-subscription` /
+  `host-resource` / `host-snapshot` / `host-summaries` `ahp.stream` values for
+  multi-host dropped-event accounting.
+- The `ahp` client now emits self-instrumentation **metrics** named by
+  `ahp_types::telemetry` through the [`metrics`](https://docs.rs/metrics)
+  facade: messages sent/received, request duration + in-flight, reconnects,
+  dropped events (per stream), and malformed frames, with `rpc.*` / `ahp.*`
+  attributes. The facade is a no-op until the host installs a recorder, so it
+  is zero-cost when unobserved. Only the names are shared; the instrumentation
+  is hand-written and idiomatic to Rust. Covered by a
+  `tests/telemetry_emission.rs` integration test that installs a `metrics-util`
+  recorder and asserts the metrics actually emit (names, the in-flight gauge
+  going `+1` → `0`, and the `rpc.method` / `ahp.outcome` / `ahp.message.kind`
+  attributes), plus an `examples/otel_export.rs` showing a consumer installing
+  a recorder to observe the client's self-instrumentation.
 - `ChangesetOperationStatus::Disabled` — new variant for changeset operations
   that are currently unavailable and cannot be invoked.
 - `ChangesetOperation.group` — optional identifier for grouping related
@@ -44,6 +62,14 @@ matching `## [X.Y.Z]` heading is missing from this file.
   as `null`.
 - Session reducers now apply `_meta` (`meta`) updates from every
   tool-call-scoped action, not only `session/toolCallStart`.
+- Client telemetry: a cancelled request is now tagged
+  `ahp.outcome=cancelled` instead of `ahp.outcome=timeout` on the
+  `ahp.client.request.duration` metric. Cancellation (the caller dropping the
+  request future) and the in-client `default_request_timeout` deadline are now
+  distinct outcomes. Cancellation is recorded via an RAII span guard, so a
+  cancelled request still emits a `request.duration` sample and the
+  `ahp.client.requests.in_flight` gauge is decremented (previously a dropped
+  request future emitted nothing and leaked the in-flight gauge at `+1`).
 
 ### Added