notifications.ts

/*---------------------------------------------------------------------------------------------
 *  Copyright (c) Microsoft Corporation. All rights reserved.
 *  Licensed under the MIT License. See License.txt in the project root for license information.
 *--------------------------------------------------------------------------------------------*/

// allow-any-unicode-comment-file
// DO NOT EDIT -- auto-generated by scripts/sync-agent-host-protocol.ts

import type { URI, SessionSummary } from './state.js';

/**
 * Reason why authentication is required.
 *
 * @category Protocol Notifications
 */
export const enum AuthRequiredReason {
	/** The client has not yet authenticated for the resource */
	Required = 'required',
	/** A previously valid token has expired or been revoked */
	Expired = 'expired',
}

// ─── Protocol Notifications ──────────────────────────────────────────────────

/**
 * Discriminant values for all protocol notifications.
 *
 * @category Protocol Notifications
 */
export const enum NotificationType {
	SessionAdded = 'notify/sessionAdded',
	SessionRemoved = 'notify/sessionRemoved',
	SessionSummaryChanged = 'notify/sessionSummaryChanged',
	AuthRequired = 'notify/authRequired',
}

/**
 * Broadcast to all connected clients when a new session is created.
 *
 * @category Protocol Notifications
 * @version 1
 * @example
 * ```json
 * {
 *   "jsonrpc": "2.0",
 *   "method": "notification",
 *   "params": {
 *     "notification": {
 *       "type": "notify/sessionAdded",
 *       "summary": {
 *         "resource": "copilot:/<uuid>",
 *         "provider": "copilot",
 *         "title": "New Session",
 *         "status": 1,
 *         "createdAt": 1710000000000,
 *         "modifiedAt": 1710000000000
 *       }
 *     }
 *   }
 * }
 * ```
 */
export interface SessionAddedNotification {
	type: NotificationType.SessionAdded;
	/** Summary of the new session */
	summary: SessionSummary;
}

/**
 * Broadcast to all connected clients when a session is disposed.
 *
 * @category Protocol Notifications
 * @version 1
 * @example
 * ```json
 * {
 *   "jsonrpc": "2.0",
 *   "method": "notification",
 *   "params": {
 *     "notification": {
 *       "type": "notify/sessionRemoved",
 *       "session": "copilot:/<uuid>"
 *     }
 *   }
 * }
 * ```
 */
export interface SessionRemovedNotification {
	type: NotificationType.SessionRemoved;
	/** URI of the removed session */
	session: URI;
}

/**
 * Broadcast to all connected clients 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,
 * `notify/sessionAdded` and `notify/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 `notify/sessionAdded`.
 *   Servers MAY coalesce or debounce updates for noisy fields (for example,
 *   `modifiedAt` bumps while a turn is streaming, or rapidly changing
 *   `diffs`) at their discretion.
 * - Clients that have no cached entry for `session` MAY ignore the
 *   notification; it is not a substitute for `notify/sessionAdded`.
 *
 * @category Protocol Notifications
 * @version 1
 * @example
 * ```json
 * {
 *   "jsonrpc": "2.0",
 *   "method": "notification",
 *   "params": {
 *     "notification": {
 *       "type": "notify/sessionSummaryChanged",
 *       "session": "copilot:/<uuid>",
 *       "changes": {
 *         "title": "Refactor auth middleware",
 *         "status": 8,
 *         "modifiedAt": 1710000123456
 *       }
 *     }
 *   }
 * }
 * ```
 */
export interface SessionSummaryChangedNotification {
	type: NotificationType.SessionSummaryChanged;
	/** 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>;
}

/**
 * Sent by the server when a protected resource requires (re-)authentication.
 *
 * This notification is sent when a previously valid token expires or is
 * revoked, or when the server discovers a new authentication requirement.
 * Clients should obtain a fresh token and push it via the `authenticate`
 * command.
 *
 * @category Protocol Notifications
 * @version 1
 * @see {@link /specification/authentication | Authentication}
 * @example
 * ```json
 * {
 *   "jsonrpc": "2.0",
 *   "method": "notification",
 *   "params": {
 *     "notification": {
 *       "type": "notify/authRequired",
 *       "resource": "https://api.github.com",
 *       "reason": "expired"
 *     }
 *   }
 * }
 * ```
 */
export interface AuthRequiredNotification {
	type: NotificationType.AuthRequired;
	/** The protected resource identifier that requires authentication */
	resource: string;
	/** Why authentication is required */
	reason?: AuthRequiredReason;
}

/**
 * Discriminated union of all protocol notifications.
 */
export type ProtocolNotification =
	| SessionAddedNotification
	| SessionRemovedNotification
	| SessionSummaryChangedNotification
	| AuthRequiredNotification;