messages.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 { InitializeParams, InitializeResult, ReconnectParams, ReconnectResult, SubscribeParams, SubscribeResult, CreateSessionParams, DisposeSessionParams, CreateTerminalParams, DisposeTerminalParams, ListSessionsParams, ListSessionsResult, ResourceReadParams, ResourceReadResult, ResourceWriteParams, ResourceWriteResult, ResourceListParams, ResourceListResult, ResourceCopyParams, ResourceCopyResult, ResourceDeleteParams, ResourceDeleteResult, ResourceMoveParams, ResourceMoveResult, FetchTurnsParams, FetchTurnsResult, UnsubscribeParams, DispatchActionParams, AuthenticateParams, AuthenticateResult, ResolveSessionConfigParams, ResolveSessionConfigResult, SessionConfigCompletionsParams, SessionConfigCompletionsResult } from './commands.js';

import type { ActionEnvelope } from './actions.js';
import type { ProtocolNotification } from './notifications.js';

// ─── JSON-RPC Base Types ─────────────────────────────────────────────────────

/** A JSON-RPC request: has both `method` and `id`. */
export interface JsonRpcRequest {
	readonly jsonrpc: '2.0';
	readonly id: number;
	readonly method: string;
	readonly params?: unknown;
}

/** A JSON-RPC success response. */
export interface JsonRpcSuccessResponse {
	readonly jsonrpc: '2.0';
	readonly id: number;
	readonly result: unknown;
}

/** A JSON-RPC error response. */
export interface JsonRpcErrorResponse {
	readonly jsonrpc: '2.0';
	readonly id: number;
	readonly error: {
		readonly code: number;
		readonly message: string;
		readonly data?: unknown;
	};
}

/** A JSON-RPC response (success or error). */
export type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;

/** A JSON-RPC notification: has `method` but no `id`. */
export interface JsonRpcNotification {
	readonly jsonrpc: '2.0';
	readonly method: string;
	readonly params?: unknown;
}

// ─── Command Map ─────────────────────────────────────────────────────────────

/**
 * Registry mapping each command method name to its params and result types.
 *
 * @category Commands
 */
export interface CommandMap {
	'initialize': { params: InitializeParams; result: InitializeResult };
	'reconnect': { params: ReconnectParams; result: ReconnectResult };
	'subscribe': { params: SubscribeParams; result: SubscribeResult };
	'createSession': { params: CreateSessionParams; result: null };
	'disposeSession': { params: DisposeSessionParams; result: null };
	'createTerminal': { params: CreateTerminalParams; result: null };
	'disposeTerminal': { params: DisposeTerminalParams; result: null };
	'listSessions': { params: ListSessionsParams; result: ListSessionsResult };
	'resourceRead': { params: ResourceReadParams; result: ResourceReadResult };
	'resourceWrite': { params: ResourceWriteParams; result: ResourceWriteResult };
	'resourceList': { params: ResourceListParams; result: ResourceListResult };
	'resourceCopy': { params: ResourceCopyParams; result: ResourceCopyResult };
	'resourceDelete': { params: ResourceDeleteParams; result: ResourceDeleteResult };
	'resourceMove': { params: ResourceMoveParams; result: ResourceMoveResult };
	'fetchTurns': { params: FetchTurnsParams; result: FetchTurnsResult };
	'authenticate': { params: AuthenticateParams; result: AuthenticateResult };
	'resolveSessionConfig': { params: ResolveSessionConfigParams; result: ResolveSessionConfigResult };
	'sessionConfigCompletions': { params: SessionConfigCompletionsParams; result: SessionConfigCompletionsResult };
}

// ─── Notification Maps ───────────────────────────────────────────────────────

/** Params for the server → client `notification` method. */
export interface NotificationMethodParams {
	notification: ProtocolNotification;
}

/**
 * Registry mapping each client → server notification method to its params type.
 *
 * @category Notifications
 */
export interface ClientNotificationMap {
	'unsubscribe': { params: UnsubscribeParams };
	'dispatchAction': { params: DispatchActionParams };
}

/**
 * Registry mapping each server → client notification method to its params type.
 *
 * @category Notifications
 */
export interface ServerNotificationMap {
	'action': { params: ActionEnvelope };
	'notification': { params: NotificationMethodParams };
}

/** Combined notification map for all directions. */
export type NotificationMap = ClientNotificationMap & ServerNotificationMap;

// ─── Typed Requests ──────────────────────────────────────────────────────────

/**
 * A fully typed JSON-RPC request for a specific AHP command.
 *
 * When used as a union (default generic), narrowing on `method` gives typed `params`:
 *
 * ```ts
 * function handle(req: AhpRequest) {
 *   if (req.method === 'fetchTurns') {
 *     req.params.session; // typed as URI
 *   }
 * }
 * ```
 */
export type AhpRequest<M extends keyof CommandMap = keyof CommandMap> =
	M extends unknown ? {
		readonly jsonrpc: '2.0';
		readonly id: number;
		readonly method: M;
		readonly params: CommandMap[M]['params'];
	} : never;

// ─── Typed Responses ─────────────────────────────────────────────────────────

/**
 * A fully typed JSON-RPC success response for a specific AHP command.
 *
 * Since JSON-RPC responses do not carry `method`, use this with an explicit
 * generic parameter when you know the method from the associated request:
 *
 * ```ts
 * const result: AhpSuccessResponse<'fetchTurns'> = ...;
 * result.result.turns; // typed as Turn[]
 * ```
 */
export type AhpSuccessResponse<M extends keyof CommandMap = keyof CommandMap> =
	M extends unknown ? {
		readonly jsonrpc: '2.0';
		readonly id: number;
		readonly result: CommandMap[M]['result'];
	} : never;

/** Typed JSON-RPC response (success with known result type, or error). */
export type AhpResponse<M extends keyof CommandMap = keyof CommandMap> =
	| AhpSuccessResponse<M>
	| JsonRpcErrorResponse;

// ─── Typed Notifications ─────────────────────────────────────────────────────

/**
 * A fully typed JSON-RPC notification for a specific AHP notification method.
 *
 * When used as a union (default generic), narrowing on `method` gives typed `params`:
 *
 * ```ts
 * function handle(notif: AhpNotification) {
 *   if (notif.method === 'action') {
 *     notif.params.serverSeq; // typed as number
 *   }
 * }
 * ```
 */
export type AhpNotification<M extends keyof NotificationMap = keyof NotificationMap> =
	M extends unknown ? {
		readonly jsonrpc: '2.0';
		readonly method: M;
		readonly params: NotificationMap[M]['params'];
	} : never;

/** A client → server notification. */
export type AhpClientNotification<M extends keyof ClientNotificationMap = keyof ClientNotificationMap> =
	M extends unknown ? {
		readonly jsonrpc: '2.0';
		readonly method: M;
		readonly params: ClientNotificationMap[M]['params'];
	} : never;

/** A server → client notification. */
export type AhpServerNotification<M extends keyof ServerNotificationMap = keyof ServerNotificationMap> =
	M extends unknown ? {
		readonly jsonrpc: '2.0';
		readonly method: M;
		readonly params: ServerNotificationMap[M]['params'];
	} : never;

// ─── Protocol Message Union ──────────────────────────────────────────────────

/**
 * Discriminated union of all AHP protocol messages.
 *
 * Narrow using standard JSON-RPC structure:
 * - Has `method` + `id` → request ({@link AhpRequest})
 * - Has `method`, no `id` → notification ({@link AhpNotification})
 * - Has `result` or `error` + `id` → response ({@link AhpResponse})
 *
 * Then narrow on `method` for fully typed params:
 *
 * ```ts
 * function dispatch(msg: ProtocolMessage) {
 *   if ('method' in msg && 'id' in msg) {
 *     // msg is AhpRequest
 *     if (msg.method === 'fetchTurns') {
 *       msg.params.session; // URI
 *     }
 *   }
 * }
 * ```
 */
export type ProtocolMessage =
	| AhpRequest
	| AhpSuccessResponse
	| JsonRpcErrorResponse
	| AhpNotification;