// Generated from types/*.ts — do not edit.
// Regenerate with: npm run generate:typescript

/**
 * Root Channel Notifications — Session catalogue events delivered on the
 * `ahp-root://` channel.
 *
 * @module channels-root/notifications
 */

import type { URI } from '../common/state.js';
import type { SessionSummary } from '../channels-session/state.js';

// ─── root/sessionAdded ───────────────────────────────────────────────────────

/**
 * Broadcast to all clients subscribed to the root channel when a new session
 * is created.
 *
 * @category Protocol Notifications
 * @method root/sessionAdded
 * @direction Server → Client
 * @messageType Notification
 * @version 1
 * @example
 * ```json
 * {
 *   "jsonrpc": "2.0",
 *   "method": "root/sessionAdded",
 *   "params": {
 *     "channel": "ahp-root://",
 *     "summary": {
 *       "resource": "ahp-session:/<uuid>",
 *       "provider": "copilot",
 *       "title": "New Session",
 *       "status": 1,
 *       "createdAt": "2024-03-09T16:00:00.000Z",
 *       "modifiedAt": "2024-03-09T16:00:00.000Z"
 *     }
 *   }
 * }
 * ```
 */
export interface SessionAddedParams {
  /** Channel URI this notification belongs to (the root channel) */
  channel: URI;
  /** Summary of the new session */
  summary: SessionSummary;
}

// ─── root/sessionRemoved ─────────────────────────────────────────────────────

/**
 * Broadcast to all clients subscribed to the root channel when a session is
 * disposed.
 *
 * @category Protocol Notifications
 * @method root/sessionRemoved
 * @direction Server → Client
 * @messageType Notification
 * @version 1
 * @example
 * ```json
 * {
 *   "jsonrpc": "2.0",
 *   "method": "root/sessionRemoved",
 *   "params": {
 *     "channel": "ahp-root://",
 *     "session": "ahp-session:/<uuid>"
 *   }
 * }
 * ```
 */
export interface SessionRemovedParams {
  /** Channel URI this notification belongs to (the root channel) */
  channel: URI;
  /** URI of the removed session */
  session: URI;
}

// ─── root/sessionSummaryChanged ──────────────────────────────────────────────

/**
 * Broadcast to all clients subscribed to the root channel when an existing
 * session's summary changes (title, status, `modifiedAt`, model, working
 * directory, read/done state, or diff statistics).
 *
 * This notification lets clients that maintain a cached session list — for
 * example, the result of a previous `listSessions()` call — stay in sync with
 * in-flight sessions without having to subscribe to every session URI
 * individually. It is complementary to, not a replacement for,
 * `root/sessionAdded` and `root/sessionRemoved`: those signal lifecycle
 * (creation/disposal), while this signals summary-level mutations on an
 * already-known session.
 *
 * Semantics:
 *
 * - Only fields present in `changes` have new values; omitted fields are
 *   unchanged on the client's cached summary.
 * - Identity fields (`resource`, `provider`, `createdAt`) never change and
 *   are not carried.
 * - Like all protocol notifications, this is ephemeral: it is **not**
 *   replayed on reconnect. On reconnect, clients should re-fetch the full
 *   catalog via `listSessions()` as usual.
 * - The server SHOULD emit this notification whenever any mutable field on
 *   {@link SessionSummary | `SessionSummary`} changes for a session the
 *   server has surfaced via `listSessions()` or `root/sessionAdded`.
 *   Servers MAY coalesce or debounce updates for noisy fields (for example,
 *   `modifiedAt` bumps while a turn is streaming) at their discretion.
 * - Clients that have no cached entry for `session` MAY ignore the
 *   notification; it is not a substitute for `root/sessionAdded`.
 *
 * @category Protocol Notifications
 * @method root/sessionSummaryChanged
 * @direction Server → Client
 * @messageType Notification
 * @version 1
 * @example
 * ```json
 * {
 *   "jsonrpc": "2.0",
 *   "method": "root/sessionSummaryChanged",
 *   "params": {
 *     "channel": "ahp-root://",
 *     "session": "ahp-session:/<uuid>",
 *     "changes": {
 *       "title": "Refactor auth middleware",
 *       "status": 8,
 *       "modifiedAt": "2024-03-09T16:02:03.456Z"
 *     }
 *   }
 * }
 * ```
 */
export interface SessionSummaryChangedParams {
  /** Channel URI this notification belongs to (the root channel) */
  channel: URI;
  /** URI of the session whose summary changed */
  session: URI;
  /**
   * Mutable summary fields that changed; omitted fields are unchanged.
   *
   * Identity fields (`resource`, `provider`, `createdAt`) never change and
   * MUST be omitted by senders; receivers SHOULD ignore them if present.
   */
  changes: Partial<SessionSummary>;
}

// ─── progress ────────────────────────────────────────────────────────────────

/**
 * Generic progress notification for a long-running operation.
 *
 * A client opts in to progress for a request by including a `progressToken` in
 * that request (today: the `progressToken` field on `createSession`). If the
 * server does long-running work to service the request — e.g. lazily
 * downloading an agent's native SDK the first time a session of that provider
 * is materialized — it emits `progress` notifications carrying the same token.
 *
 * The notification is operation-agnostic: it says nothing about *what* is
 * progressing. The client correlates `progressToken` back to the request it
 * originated from (and thus the UI surface awaiting it) and renders its own
 * localized indicator. The same channel serves any future long-running
 * operation without a new method.
 *
 * Semantics:
 *
 * - `progress` is monotonically non-decreasing for a given `progressToken`.
 * - `total` is present only when the server knows the magnitude up front
 *   (e.g. a `Content-Length`); when absent the client SHOULD show an
 *   indeterminate indicator.
 * - The operation is complete when `progress === total`. The server MUST emit a
 *   final frame satisfying `progress === total`; when the total was never
 *   known, it sets `total` to the final `progress` on that frame. No further
 *   frames reference the token afterwards.
 * - The server MAY emit no progress at all (e.g. the work was already done);
 *   the client then never shows an indicator.
 * - Like all notifications this is ephemeral and is **not** replayed on
 *   reconnect. A client that never receives the terminal frame SHOULD expire
 *   the indicator after an idle timeout.
 *
 * @category Protocol Notifications
 * @method root/progress
 * @direction Server → Client
 * @messageType Notification
 * @version 1
 * @example
 * ```json
 * {
 *   "jsonrpc": "2.0",
 *   "method": "root/progress",
 *   "params": {
 *     "channel": "ahp-root://",
 *     "progressToken": "9b2c1f7e-4a0d-4e2b-8b1a-2f7e4a0d4e2b",
 *     "progress": 18874368,
 *     "total": 41957498
 *   }
 * }
 * ```
 */
export interface ProgressParams {
  /** Channel URI this notification belongs to (the root channel). */
  channel: URI;
  /**
   * Echoes the `progressToken` the client supplied on the originating request
   * (e.g. the `progressToken` field of `createSession`), correlating this frame
   * to that call. Unique across the client's active requests.
   */
  progressToken: string;
  /**
   * Progress so far, in operation-defined units (e.g. bytes received).
   * Monotonically non-decreasing for a given `progressToken`.
   */
  progress: number;
  /**
   * Total when known up front (e.g. from a `Content-Length`); omitted ⇒
   * indeterminate. The operation is complete once `progress === total`.
   */
  total?: number;
  /**
   * Optional human-readable progress message. The client owns its own
   * (localized) presentation derived from the originating request; generic
   * clients that don't track the token MAY display this instead.
   */
  message?: string;
}