ahp_types/notifications.rs
1// Generated from types/*.ts — do not edit.
2//
3// Regenerate with: npm run generate:rust
4
5#![allow(missing_docs)]
6
7#[allow(unused_imports)]
8use crate::common::{AnyValue, JsonObject, StringOrMarkdown, Uri};
9#[allow(unused_imports)]
10use serde::{Deserialize, Serialize};
11#[allow(unused_imports)]
12use serde_repr::{Deserialize_repr, Serialize_repr};
13
14#[allow(unused_imports)]
15use crate::state::{
16 AgentSelection, ChangesSummary, Changeset, FileEdit, ModelSelection, ProjectInfo,
17 SessionStatus, SessionSummary,
18};
19
20// ─── Enums ────────────────────────────────────────────────────────────
21
22/// Reason why authentication is required.
23#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
24pub enum AuthRequiredReason {
25 /// The client has not yet authenticated for the resource
26 #[serde(rename = "required")]
27 Required,
28 /// A previously valid token has expired or been revoked
29 #[serde(rename = "expired")]
30 Expired,
31}
32
33// ─── Notification Payloads ────────────────────────────────────────────
34
35/// Broadcast to all clients subscribed to the root channel when a new session
36/// is created.
37#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
38#[serde(rename_all = "camelCase")]
39pub struct SessionAddedParams {
40 /// Channel URI this notification belongs to (the root channel)
41 pub channel: Uri,
42 /// Summary of the new session
43 pub summary: SessionSummary,
44}
45
46/// Broadcast to all clients subscribed to the root channel when a session is
47/// disposed.
48#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
49#[serde(rename_all = "camelCase")]
50pub struct SessionRemovedParams {
51 /// Channel URI this notification belongs to (the root channel)
52 pub channel: Uri,
53 /// URI of the removed session
54 pub session: Uri,
55}
56
57/// Broadcast to all clients subscribed to the root channel when an existing
58/// session's summary changes (title, status, `modifiedAt`, model, working
59/// directory, read/done state, or diff statistics).
60///
61/// This notification lets clients that maintain a cached session list — for
62/// example, the result of a previous `listSessions()` call — stay in sync with
63/// in-flight sessions without having to subscribe to every session URI
64/// individually. It is complementary to, not a replacement for,
65/// `root/sessionAdded` and `root/sessionRemoved`: those signal lifecycle
66/// (creation/disposal), while this signals summary-level mutations on an
67/// already-known session.
68///
69/// Semantics:
70///
71/// - Only fields present in `changes` have new values; omitted fields are
72/// unchanged on the client's cached summary.
73/// - Identity fields (`resource`, `provider`, `createdAt`) never change and
74/// are not carried.
75/// - Like all protocol notifications, this is ephemeral: it is **not**
76/// replayed on reconnect. On reconnect, clients should re-fetch the full
77/// catalog via `listSessions()` as usual.
78/// - The server SHOULD emit this notification whenever any mutable field on
79/// {@link SessionSummary | `SessionSummary`} changes for a session the
80/// server has surfaced via `listSessions()` or `root/sessionAdded`.
81/// Servers MAY coalesce or debounce updates for noisy fields (for example,
82/// `modifiedAt` bumps while a turn is streaming) at their discretion.
83/// - Clients that have no cached entry for `session` MAY ignore the
84/// notification; it is not a substitute for `root/sessionAdded`.
85#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
86#[serde(rename_all = "camelCase")]
87pub struct SessionSummaryChangedParams {
88 /// Channel URI this notification belongs to (the root channel)
89 pub channel: Uri,
90 /// URI of the session whose summary changed
91 pub session: Uri,
92 /// Mutable summary fields that changed; omitted fields are unchanged.
93 ///
94 /// Identity fields (`resource`, `provider`, `createdAt`) never change and
95 /// MUST be omitted by senders; receivers SHOULD ignore them if present.
96 pub changes: PartialSessionSummary,
97}
98
99/// Sent by the server when a protected resource requires (re-)authentication.
100///
101/// This notification MAY be associated with any channel — for example, an
102/// agent advertised on the root channel, or a per-session resource. The
103/// `channel` field identifies the subscription the auth requirement belongs
104/// to; the `resource` field carries the OAuth-protected resource identifier
105/// (per RFC 9728).
106///
107/// Clients should obtain a fresh token and push it via the `authenticate`
108/// command.
109#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
110#[serde(rename_all = "camelCase")]
111pub struct AuthRequiredParams {
112 /// Channel URI this notification belongs to
113 pub channel: Uri,
114 /// The protected resource identifier that requires authentication
115 pub resource: String,
116 /// Why authentication is required
117 #[serde(default, skip_serializing_if = "Option::is_none")]
118 pub reason: Option<AuthRequiredReason>,
119}
120
121/// Delivers a batch of OTLP log records to a client subscribed to the host's
122/// logs channel (advertised on `TelemetryCapabilities.logs`).
123///
124/// The `payload` field is an OTLP/JSON `ExportLogsServiceRequest` value
125/// verbatim — i.e. an object of shape `{ resourceLogs: ResourceLogs[] }` as
126/// defined by [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/logs/v1/logs_service.proto).
127/// AHP does not redeclare the OTLP type system; clients SHOULD use an
128/// OpenTelemetry SDK or schema to parse it.
129///
130/// Like all stateless-channel notifications, this is ephemeral: it is not
131/// replayed on reconnect. Subscribers receive only batches emitted after
132/// their `subscribe` succeeds.
133#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
134#[serde(rename_all = "camelCase")]
135pub struct OtlpExportLogsParams {
136 /// Channel URI this notification belongs to (an `ahp-otlp:` URI advertised on `TelemetryCapabilities.logs`).
137 pub channel: Uri,
138 /// OTLP/JSON `ExportLogsServiceRequest` value. The top-level field is
139 /// `resourceLogs: ResourceLogs[]`; nested shapes are defined by
140 /// opentelemetry-proto and are not redeclared here.
141 pub payload: JsonObject,
142}
143
144/// Delivers a batch of OTLP spans to a client subscribed to the host's
145/// traces channel (advertised on `TelemetryCapabilities.traces`).
146///
147/// The `payload` field is an OTLP/JSON `ExportTraceServiceRequest` value
148/// verbatim — i.e. an object of shape `{ resourceSpans: ResourceSpans[] }`
149/// as defined by [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/trace/v1/trace_service.proto).
150#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
151#[serde(rename_all = "camelCase")]
152pub struct OtlpExportTracesParams {
153 /// Channel URI this notification belongs to (an `ahp-otlp:` URI advertised on `TelemetryCapabilities.traces`).
154 pub channel: Uri,
155 /// OTLP/JSON `ExportTraceServiceRequest` value. The top-level field is
156 /// `resourceSpans: ResourceSpans[]`; nested shapes are defined by
157 /// opentelemetry-proto and are not redeclared here.
158 pub payload: JsonObject,
159}
160
161/// Delivers a batch of OTLP metric data points to a client subscribed to
162/// the host's metrics channel (advertised on `TelemetryCapabilities.metrics`).
163///
164/// The `payload` field is an OTLP/JSON `ExportMetricsServiceRequest` value
165/// verbatim — i.e. an object of shape `{ resourceMetrics: ResourceMetrics[] }`
166/// as defined by [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/metrics/v1/metrics_service.proto).
167#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
168#[serde(rename_all = "camelCase")]
169pub struct OtlpExportMetricsParams {
170 /// Channel URI this notification belongs to (an `ahp-otlp:` URI advertised on `TelemetryCapabilities.metrics`).
171 pub channel: Uri,
172 /// OTLP/JSON `ExportMetricsServiceRequest` value. The top-level field is
173 /// `resourceMetrics: ResourceMetrics[]`; nested shapes are defined by
174 /// opentelemetry-proto and are not redeclared here.
175 pub payload: JsonObject,
176}
177
178// ─── Partial Summaries ────────────────────────────────────────────────
179
180/// Partial equivalent of SessionSummary — every field is optional for delta updates.
181#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
182#[serde(rename_all = "camelCase")]
183pub struct PartialSessionSummary {
184 /// Session URI
185 #[serde(default, skip_serializing_if = "Option::is_none")]
186 pub resource: Option<Uri>,
187 /// Agent provider ID
188 #[serde(default, skip_serializing_if = "Option::is_none")]
189 pub provider: Option<String>,
190 /// Session title
191 #[serde(default, skip_serializing_if = "Option::is_none")]
192 pub title: Option<String>,
193 /// Current session status
194 #[serde(default, skip_serializing_if = "Option::is_none")]
195 pub status: Option<u32>,
196 /// Human-readable description of what the session is currently doing
197 #[serde(default, skip_serializing_if = "Option::is_none")]
198 pub activity: Option<String>,
199 /// Creation timestamp
200 #[serde(default, skip_serializing_if = "Option::is_none")]
201 pub created_at: Option<i64>,
202 /// Last modification timestamp
203 #[serde(default, skip_serializing_if = "Option::is_none")]
204 pub modified_at: Option<i64>,
205 /// Server-owned project for this session
206 #[serde(default, skip_serializing_if = "Option::is_none")]
207 pub project: Option<ProjectInfo>,
208 /// Currently selected model
209 #[serde(default, skip_serializing_if = "Option::is_none")]
210 pub model: Option<ModelSelection>,
211 /// Currently selected custom agent.
212 ///
213 /// Absent (`undefined`) means no custom agent is selected for this session
214 /// — the session uses the provider's default behavior.
215 #[serde(default, skip_serializing_if = "Option::is_none")]
216 pub agent: Option<AgentSelection>,
217 /// The working directory URI for this session
218 #[serde(default, skip_serializing_if = "Option::is_none")]
219 pub working_directory: Option<Uri>,
220 /// Aggregate summary of file changes associated with this session. Servers
221 /// may populate this to give clients a quick at-a-glance view of the
222 /// session's footprint (e.g., for list rendering) without requiring the
223 /// client to subscribe to a changeset.
224 #[serde(default, skip_serializing_if = "Option::is_none")]
225 pub changes: Option<ChangesSummary>,
226}