/** Nuva Agent API (Preview). */
export type JsonValue = null | boolean | number | string | readonly JsonValue[] | { readonly [key: string]: JsonValue };
export type JsonObject = { readonly [key: string]: JsonValue };
export type Timestamp = string; // ISO 8601, UTC.
export type Cursor = string; // Opaque; never construct or parse it.
export type Unsubscribe = () => void;

export interface Page<T> {
	readonly items: readonly T[];
	readonly nextCursor: Cursor | null;
}

export interface PaginationQuery {
	readonly cursor?: Cursor;
	readonly limit?: number;
}

export interface RecordRef<K extends string = string> {
	readonly kind: K;
	readonly id: string;
	readonly revision: string;
}

export interface RecordLink<K extends string = string> {
	readonly ref: RecordRef<K>;
	readonly label: string;
}

export interface MessageRef {
	readonly sessionId: string;
	readonly messageId: string;
}

export interface UiSkillRef {
	readonly id: string;
	readonly revision: string;
}

export interface UserIdentity {
	readonly userId: string;
	readonly displayName: string;
}

export interface Session {
	readonly id: string;
	readonly kind: 'main' | 'work';
	readonly title: string;
	readonly owner: UserIdentity;
	readonly createdAt: Timestamp;
}

interface PartBase {
	readonly id: string;
}

export type QuoteTarget =
	| { readonly type: 'record'; readonly record: RecordLink }
	| { readonly type: 'message'; readonly message: MessageRef };

export type MessagePart =
	| (PartBase & {
			readonly type: 'text';
			readonly format: 'plain' | 'markdown';
			readonly text: string;
	  })
	| (PartBase & { readonly type: 'mention'; readonly record: RecordLink })
	| (PartBase & { readonly type: 'resource'; readonly record: RecordLink })
	| (PartBase & {
			readonly type: 'quote';
			readonly target: QuoteTarget;
			readonly text: string;
	  })
	| DynamicToolUIPart
	| NotificationHostCall;

interface MessageBase {
	readonly ref: MessageRef;
	readonly createdAt: Timestamp;
	readonly content: readonly MessagePart[];
	readonly attachments: readonly RecordLink[];
	readonly replyTo?: MessageRef;
}

export type MessageView = MessageBase &
	(
		| {
				readonly role: 'user';
				readonly metadata: { readonly user: UserIdentity };
		  }
		| {
				readonly role: 'assistant';
		  }
	) &
	({ readonly state: 'streaming' | 'complete' | 'interrupted' } | { readonly state: 'failed'; readonly error: NuvaErrorInfo });

export declare class MessageDraft {
	private constructor();
	private readonly messageDraftBrand;
	text(text: string): MessageDraft;
	mention(record: RecordLink): MessageDraft;
	attach(record: RecordLink): MessageDraft;
	quote(target: RecordLink | MessageView, selectedText: string): MessageDraft;
	replyTo(message: MessageView): MessageDraft;
}

export declare const Message: {
	create(): MessageDraft;
	text(text: string): MessageDraft;
};

export type DynamicToolUIPart = {
	readonly type: 'dynamic-tool';
	readonly toolName: string;
	readonly toolCallId: string;
	readonly input: JsonObject;
} & (
	| { readonly state: 'input-available' }
	| { readonly state: 'output-available'; readonly output: JsonValue }
	| { readonly state: 'output-error'; readonly errorText: string }
);

export interface NotificationHostCall {
	readonly type: 'data-host-call';
	readonly id: string;
	readonly data: {
		readonly toolName: string;
		readonly input: JsonObject;
	};
}

export interface HostFailure {
	readonly code: string;
	readonly message: string;
}

export type ReviewDecisionValue = {
	decision: 'approve' | 'reject';
	text: string;
};

export declare const ReviewDecision: {
	approve(text?: string): ReviewDecisionValue;
	reject(text?: string): ReviewDecisionValue;
};

export interface AgentData {
	readonly session: Session;
	readonly messages: Page<MessageView>;
}

export type AgentReadState =
	| { readonly status: 'loading' }
	| { readonly status: 'error'; readonly error: NuvaErrorInfo }
	| (AgentData & {
			readonly error?: NuvaErrorInfo;
	  } & ({ readonly status: 'idle' | 'running' } | { readonly status: 'waiting_for_response'; readonly callIds: readonly string[] }));

export type AgentStatus = AgentReadState['status'];

export type NuvaErrorCode =
	| 'UNAUTHENTICATED'
	| 'FORBIDDEN'
	| 'NOT_FOUND'
	| 'INVALID_INPUT'
	| 'REVISION_CONFLICT'
	| 'CALL_ALREADY_RESOLVED'
	| 'CALL_OBSOLETE'
	| 'REQUEST_ID_CONFLICT'
	| 'RATE_LIMITED'
	| 'UNSUPPORTED_CONTENT'
	| 'CONNECTION_ERROR'
	| 'SERVICE_ERROR';

export interface NuvaErrorInfo {
	readonly code: NuvaErrorCode;
	readonly message: string;
	readonly retryable: boolean;
	readonly requestId?: string;
	readonly acceptance?: 'not_accepted' | 'unknown';
}

export declare class NuvaError extends Error implements NuvaErrorInfo {
	constructor(info: NuvaErrorInfo);
	readonly code: NuvaErrorCode;
	readonly retryable: boolean;
	readonly requestId?: string;
	readonly acceptance?: 'not_accepted' | 'unknown';
}

export interface CommandOptions {
	readonly requestId?: string;
}

export interface SendReceipt {
	readonly requestId: string;
	readonly message: MessageRef;
}

export interface ResponseReceipt {
	readonly requestId: string;
	readonly call: Extract<DynamicToolUIPart, { state: 'output-available' }>;
}

export interface HostFailureReceipt {
	readonly requestId: string;
	readonly call: Extract<DynamicToolUIPart, { state: 'output-error' }>;
}

export interface AgentOptions {
	readonly sessionId: string;
}

export interface AgentHandle {
	readonly sessionId: string;
	send(message: MessageDraft, options?: CommandOptions): Promise<SendReceipt>;
	respond(
		call: Extract<DynamicToolUIPart, { state: 'input-available' }>,
		output: JsonValue,
		options?: CommandOptions,
	): Promise<ResponseReceipt>;
	fail(
		call: Extract<DynamicToolUIPart, { state: 'input-available' }>,
		failure: HostFailure,
		options?: CommandOptions,
	): Promise<HostFailureReceipt>;
	subscribe(listener: (state: AgentReadState) => void): Unsubscribe;
	onHostCall(listener: (part: DynamicToolUIPart | NotificationHostCall) => void): Unsubscribe;
	refresh(): Promise<void>;
	loadEarlierMessages(): Promise<void>;
	listPendingCalls(query?: PaginationQuery): Promise<Page<Extract<DynamicToolUIPart, { state: 'input-available' }>>>;
	getHostCall(toolCallId: string): Promise<DynamicToolUIPart | NotificationHostCall>;
}

export type AgentResult = AgentHandle & AgentReadState;

export interface SessionsClient {
	getMain(): Promise<Session>;
	get(sessionId: string): Promise<Session>;
	list(query?: PaginationQuery): Promise<Page<Session>>;
	getMessage(ref: MessageRef): Promise<MessageView>;
	history(sessionId: string, query?: PaginationQuery): Promise<Page<MessageView>>;
}

export interface NuvaClientOptions {
	getAccessToken(): Promise<string>;
}

export interface NuvaClient {
	readonly sessions: SessionsClient;
	agent(options: AgentOptions): AgentHandle;
	close(): void;
}

export declare function createNuva(options: NuvaClientOptions): NuvaClient;