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, ChangesetSummary, FileEdit, ModelSelection, ProjectInfo, SessionStatus,
17 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, or rapidly changing
83/// `changesets`) at their discretion.
84/// - Clients that have no cached entry for `session` MAY ignore the
85/// notification; it is not a substitute for `root/sessionAdded`.
86#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
87#[serde(rename_all = "camelCase")]
88pub struct SessionSummaryChangedParams {
89 /// Channel URI this notification belongs to (the root channel)
90 pub channel: Uri,
91 /// URI of the session whose summary changed
92 pub session: Uri,
93 /// Mutable summary fields that changed; omitted fields are unchanged.
94 ///
95 /// Identity fields (`resource`, `provider`, `createdAt`) never change and
96 /// MUST be omitted by senders; receivers SHOULD ignore them if present.
97 pub changes: PartialSessionSummary,
98}
99
100/// Sent by the server when a protected resource requires (re-)authentication.
101///
102/// This notification MAY be associated with any channel — for example, an
103/// agent advertised on the root channel, or a per-session resource. The
104/// `channel` field identifies the subscription the auth requirement belongs
105/// to; the `resource` field carries the OAuth-protected resource identifier
106/// (per RFC 9728).
107///
108/// Clients should obtain a fresh token and push it via the `authenticate`
109/// command.
110#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
111#[serde(rename_all = "camelCase")]
112pub struct AuthRequiredParams {
113 /// Channel URI this notification belongs to
114 pub channel: Uri,
115 /// The protected resource identifier that requires authentication
116 pub resource: String,
117 /// Why authentication is required
118 #[serde(default, skip_serializing_if = "Option::is_none")]
119 pub reason: Option<AuthRequiredReason>,
120}
121
122/// Delivers a batch of OTLP log records to a client subscribed to the host's
123/// logs channel (advertised on `TelemetryCapabilities.logs`).
124///
125/// The `payload` field is an OTLP/JSON `ExportLogsServiceRequest` value
126/// verbatim — i.e. an object of shape `{ resourceLogs: ResourceLogs[] }` as
127/// defined by [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/logs/v1/logs_service.proto).
128/// AHP does not redeclare the OTLP type system; clients SHOULD use an
129/// OpenTelemetry SDK or schema to parse it.
130///
131/// Like all stateless-channel notifications, this is ephemeral: it is not
132/// replayed on reconnect. Subscribers receive only batches emitted after
133/// their `subscribe` succeeds.
134#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
135#[serde(rename_all = "camelCase")]
136pub struct OtlpExportLogsParams {
137 /// Channel URI this notification belongs to (an `ahp-otlp:` URI advertised on `TelemetryCapabilities.logs`).
138 pub channel: Uri,
139 /// OTLP/JSON `ExportLogsServiceRequest` value. The top-level field is
140 /// `resourceLogs: ResourceLogs[]`; nested shapes are defined by
141 /// opentelemetry-proto and are not redeclared here.
142 pub payload: JsonObject,
143}
144
145/// Delivers a batch of OTLP spans to a client subscribed to the host's
146/// traces channel (advertised on `TelemetryCapabilities.traces`).
147///
148/// The `payload` field is an OTLP/JSON `ExportTraceServiceRequest` value
149/// verbatim — i.e. an object of shape `{ resourceSpans: ResourceSpans[] }`
150/// as defined by [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/trace/v1/trace_service.proto).
151#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
152#[serde(rename_all = "camelCase")]
153pub struct OtlpExportTracesParams {
154 /// Channel URI this notification belongs to (an `ahp-otlp:` URI advertised on `TelemetryCapabilities.traces`).
155 pub channel: Uri,
156 /// OTLP/JSON `ExportTraceServiceRequest` value. The top-level field is
157 /// `resourceSpans: ResourceSpans[]`; nested shapes are defined by
158 /// opentelemetry-proto and are not redeclared here.
159 pub payload: JsonObject,
160}
161
162/// Delivers a batch of OTLP metric data points to a client subscribed to
163/// the host's metrics channel (advertised on `TelemetryCapabilities.metrics`).
164///
165/// The `payload` field is an OTLP/JSON `ExportMetricsServiceRequest` value
166/// verbatim — i.e. an object of shape `{ resourceMetrics: ResourceMetrics[] }`
167/// as defined by [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/collector/metrics/v1/metrics_service.proto).
168#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
169#[serde(rename_all = "camelCase")]
170pub struct OtlpExportMetricsParams {
171 /// Channel URI this notification belongs to (an `ahp-otlp:` URI advertised on `TelemetryCapabilities.metrics`).
172 pub channel: Uri,
173 /// OTLP/JSON `ExportMetricsServiceRequest` value. The top-level field is
174 /// `resourceMetrics: ResourceMetrics[]`; nested shapes are defined by
175 /// opentelemetry-proto and are not redeclared here.
176 pub payload: JsonObject,
177}
178
179// ─── Partial Summaries ────────────────────────────────────────────────
180
181/// Partial equivalent of SessionSummary — every field is optional for delta updates.
182#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
183#[serde(rename_all = "camelCase")]
184pub struct PartialSessionSummary {
185 /// Session URI
186 #[serde(default, skip_serializing_if = "Option::is_none")]
187 pub resource: Option<Uri>,
188 /// Agent provider ID
189 #[serde(default, skip_serializing_if = "Option::is_none")]
190 pub provider: Option<String>,
191 /// Session title
192 #[serde(default, skip_serializing_if = "Option::is_none")]
193 pub title: Option<String>,
194 /// Current session status
195 #[serde(default, skip_serializing_if = "Option::is_none")]
196 pub status: Option<u32>,
197 /// Human-readable description of what the session is currently doing
198 #[serde(default, skip_serializing_if = "Option::is_none")]
199 pub activity: Option<String>,
200 /// Creation timestamp
201 #[serde(default, skip_serializing_if = "Option::is_none")]
202 pub created_at: Option<i64>,
203 /// Last modification timestamp
204 #[serde(default, skip_serializing_if = "Option::is_none")]
205 pub modified_at: Option<i64>,
206 /// Server-owned project for this session
207 #[serde(default, skip_serializing_if = "Option::is_none")]
208 pub project: Option<ProjectInfo>,
209 /// Currently selected model
210 #[serde(default, skip_serializing_if = "Option::is_none")]
211 pub model: Option<ModelSelection>,
212 /// Currently selected custom agent.
213 ///
214 /// Absent (`undefined`) means no custom agent is selected for this session
215 /// — the session uses the provider's default behavior.
216 #[serde(default, skip_serializing_if = "Option::is_none")]
217 pub agent: Option<AgentSelection>,
218 /// The working directory URI for this session
219 #[serde(default, skip_serializing_if = "Option::is_none")]
220 pub working_directory: Option<Uri>,
221 /// Catalogue of changesets the server can produce for this session. Each
222 /// entry advertises a subscribable view of file changes (uncommitted,
223 /// session-wide, per-turn, etc.) and the URI template the client expands
224 /// before subscribing. See {@link ChangesetSummary} for the full shape and
225 /// {@link /guide/changesets | Changesets} for an overview of the model.
226 #[serde(default, skip_serializing_if = "Option::is_none")]
227 pub changesets: Option<Vec<ChangesetSummary>>,
228}